Créditos e limites de uso

Algumas operações da API dão trabalho ao servidor (gerar um PDF, montar um pacote SCORM) e podem consumir créditos da conta, os mesmos do plano. Ler o acervo, os materiais e as provas continua grátis.

Veja charging antes de supor custo. Cada ação em GET /usage diz se é cobrada de verdade (charging). Com charging: false, a regra está em simulação: o uso é contado, mas nenhum crédito sai. O limite por dia vale nos dois casos.

O que pode ser cobrado#

Ação (action)	Quando conta
export_pdf_section	Pedido de PDF de um capítulo (POST /materials/{id}/exports com section)
export_pdf	Pedido de PDF da apostila inteira
export_scorm	Pedido de pacote scorm12, scorm2004 ou html5
acquisition	Compra de um produto (taxa de uso, além do preço do produto)
publication	Registro de publicação
login_link	Link de entrada já logado

O custo de cada ação, a franquia grátis do mês e o limite por dia dependem do plano da conta e do tipo de acesso (aplicativo ou chave pessoal). O HotLearn pode mudar esses valores; por isso, consulte sempre a tabela da sua chave. O plano Ilimitado não fica isento sozinho: vale o que a tabela diz para ele.

Consultar antes de gastar#

curl https://hotlearn.com.br/api/v1/usage \
  -H "Authorization: Bearer $HOTLEARN_KEY"

{
  "data": {
    "balance": 4200,
    "unlimited": false,
    "actions": [
      { "action": "export_pdf", "credits": 20, "charging": true, "free_monthly": 20, "used_this_month": 20, "daily_limit": 50, "used_today": 3 }
    ]
  }
}

• credits: quanto a ação custa quando a franquia acabou;
• charging: false quando a ação ainda não é cobrada (o uso é só contado);
• free_monthly / used_this_month: franquia grátis do mês e quanto já foi usado;
• daily_limit / used_today: limite por dia e quanto já foi usado hoje.

Um assistente de IA pode ler essa tabela e avisar a pessoa antes de uma operação pesada.

Como a cobrança funciona#

• Só cobra trabalho feito. Arquivo já pronto da mesma versão sai de graça; pedido que falha devolve os créditos; o mesmo pedido repetido com a mesma Idempotency-Key não cobra duas vezes.
• Franquia primeiro. Dentro da franquia do mês, a ação não custa nada.
• A resposta de uma ação medida traz os cabeçalhos X-Credits-Charged (quanto saiu agora) e X-Credits-Balance (o saldo depois). Em simulação, X-Credits-Charged vem 0; o que a ação custaria está em credits, no GET /usage (escopo account:read).
• O limite de gasto é o saldo de créditos do plano da conta.

Erros#

Status	code	O que fazer
402	insufficient_credits	O saldo não cobre a ação. A resposta traz required e available. Peça para a escola aguardar a recarga do plano ou comprar créditos.
429	daily_limit_reached	A conta chegou ao limite de hoje para essa ação. A resposta traz resets_at e o cabeçalho Retry-After.