Créditos e saldos
Como funcionam os créditos CaptureKit e como recarregar o seu saldo.
Cada chamada faturável desconta créditos do seu espaço de trabalho. O painel Uso do dashboard, em Definições → Assinatura, mostra três saldos. O endpoint de uso da API reporta uma autonomia combinada para poder alertar a partir do código sem analisar cada balde.
Utilização
Período atual38,400
10,000
3,780
Assinatura
Pro · renova no dia 1
Os três saldos
| Saldo | O que é | Repõe |
|---|---|---|
| Quota da assinatura | Chamadas API incluídas no seu plano | Sim — no início de cada período de faturação (a partir do Stripe quando disponível; caso contrário, o mês civil). A quota não usada não transita. |
| Pack API pontual | Quota API adicional de uma compra única | Nunca — consumido até esgotar, entre períodos de faturação |
| Créditos pay-as-you-go | Um livro separado, usado só depois de a quota da assinatura e os packs API estarem vazios | Nunca — os créditos ficam até serem gastos |
No dashboard essas três barras aparecem em Definições → Assinatura → Uso (e no painel Utilização API da barra lateral). No endpoint de uso (/v1/usage), o objeto subscription é a quota API combinada (assinatura + packs restantes). O pay-as-you-go fica em credits. O remaining de topo é a soma dos dois.
Ordem de consumo
Primeiro a quota da assinatura
As chamadas faturáveis preenchem a dotação do plano do período atual.
Depois os packs API pontuais
Quando a dotação do período se esgota, a quota restante dos packs é consumida a seguir. Os packs são imputados por ordem de compra.
Depois os créditos pay-as-you-go
Só se a quota API combinada não puder cobrir o custo do endpoint é que debitamos o livro pay-as-you-go.
Caso contrário a chamada é recusada
A API devolve 402 com Payment required, e o pedido não é executado.
O que é faturado
| Resultado | Créditos |
|---|---|
200 ou 201 (resposta faturável bem-sucedida / aceite) | Sim — o custo em créditos do endpoint |
404 | Normalmente sim — salvo se esse endpoint marcar o 404 como gratuito (indicado na Biblioteca e na página do endpoint) |
401, 402, 400, 5xx e a maioria dos outros erros | Não — e qualquer reserva pay-as-you-go é libertada |
| Endpoints por linha com 0 resultados | Grátis |
| Endpoints por linha com N resultados | N × o custo por linha — tudo ou nada (saldo insuficiente → 402 antes de qualquer linha ser devolvida) |
/v1/usage e URL de estado de jobs | Sempre grátis — sem verificação de quota |
Cada endpoint declara o seu custo na Biblioteca (e na Referência da API): N créditos por chamada ou por linha. O saldo é verificado antes de o trabalho começar, por isso um job nunca é aceite sem os créditos para o pagar. Consultar o estado de um job nunca custa créditos.
Comprar mais capacidade
Abrir as definições de assinatura
Aceda a Definições → Assinatura e clique em Ver todos os planos (ou abra https://app.capturekit.dev/pricing).
Escolher um pack pontual
Consoante o produto, um pack acrescenta à quota API (pack API pontual) ou ao livro pay-as-you-go. Por si só nunca altera o seu nível de assinatura. Os packs maiores costumam custar menos por crédito.
Confirmar o pagamento
A capacidade fica disponível assim que o pagamento é aceite, e uma fatura é enviada por e-mail para o endereço de faturação.
Os packs comprados também aparecem em Definições → Assinatura → Packs pontuais. Para repor automaticamente quando o saldo combinado desce, veja Recarga automática.
Onde ler o histórico
| Ecrã | O que mostra |
|---|---|
| Definições → Assinatura → Uso | Restante / usado em tempo real dos três saldos do período atual |
| Registros API | Cada pedido com estado, duração e créditos cobrados — incluindo uso de assinatura e packs |
| Definições → Créditos | O livro pay-as-you-go apenas: créditos (recompensas, alguns tipos de pack, recarga automática) e gastos ocorridos depois de a quota API estar vazia. Filtre por membro ou por tipo. |
Endpoint de uso (/v1/usage) | Instantâneo legível por máquina: remaining, subscription, credits, renewal_date — gratuito a chamar |
Se Definições → Créditos parecer vazio enquanto o Analytics mostra tráfego, é o esperado: o consumo de assinatura e packs nunca aparece nessa página. Use os Registros API ou as barras de Uso em alternativa.
Quando vê 402
| Mensagem | Significado | O que fazer |
|---|---|---|
Payment required | Sem quota da assinatura, packs ou pay-as-you-go para o custo desta chamada | Compre um pack, faça upgrade do plano ou ative a recarga automática |
You have open invoices: … | Uma fatura por pagar está a bloquear a conta | Regularize em Definições → Faturas — o saldo sozinho não chega |
Insufficient credits: X required, Y available | Um endpoint por linha devolveria mais linhas do que consegue pagar | Recarregue, ou restrinja o pedido para que voltem menos linhas |
FAQ
- A quota do plano não usada transita? Não. O balde da assinatura repõe-se em cada período de faturação.
- Os packs pontuais expiram no fim do mês? Não. Ficam até serem consumidos.
- Todas as chaves partilham os mesmos saldos? Sim — a quota é do espaço de trabalho.
- Verificar o uso custa créditos? Não.
/v1/usagee os caminhos de estado de jobs são grátis. - Porque é que o Uso no dashboard está separado e
/usage.subscriptioncombinado? Para que um único númeroremainingbaste para alertas; abra o dashboard quando precisar da divisão em três.