Neste tutorial, você construirá o NeuralAPI — uma plataforma de IA em camadas, onde cada plano de assinatura vem com uma cota mensal de créditos de tokens, os clientes podem comprar pacotes de recarga quando ficarem sem créditos, e seu backend desconta automaticamente os créditos à medida que as solicitações são processadas pelo OpenAI.Documentation Index
Fetch the complete documentation index at: https://docs.dodopayments.com/llms.txt
Use this file to discover all available pages before exploring further.
- Criar uma concessão de crédito personalizada (tokens) e uma medição que faz descontos automáticos nela
- Anexar créditos a planos de assinatura (com e sem excedente) e a um produto de recarga única
- Conectar um endpoint real de conclusão do OpenAI que cobra tokens através do Dodo Payments
- Consultar o saldo de créditos ao vivo de um cliente via SDK
- Verificar assinaturas de webhooks e rotear eventos de crédito do Dodo Payments
O Que Estamos Construindo
Aqui está o modelo de precificação para o NeuralAPI:| Produto | Preço | Tokens | Excedente |
|---|---|---|---|
| Plano Inicial | $29/mês | 10.000.000 tokens/ciclo | Bloqueado a zero |
| Plano Pro | $99/mês | 40.000.000 tokens/ciclo | $0,005 por 1K tokens |
| Pacote de Recarga de Tokens | $19 único | +5.000.000 tokens | — |
- Uma conta no Dodo Payments (modo de teste é suficiente)
- Uma chave de API OpenAI
- Node.js 18+
- Conhecimento básico em TypeScript/Node.js
Etapa 1: Crie Sua Concessão de Crédito de Token
Primeiro, crie a concessão de crédito que será compartilhada tanto pelos planos de assinatura quanto pelo pacote de recarga. Pense nisso como definir a unidade “token” que sua plataforma usa.
Navigate to Credits
- Faça login no seu painel do Dodo Payments
- Clique em Produtos na barra lateral esquerda
- Selecione a guia Créditos
- Clique em Criar Crédito
Configure the credit unit
API TokensTipo de Crédito: Selecione Unidade PersonalizadaNome da Unidade: tokenPrecisão: 0 (tokens são sempre números inteiros)Validade do Crédito: 30 days (créditos são reiniciados a cada ciclo de cobrança)Skip overage at the credit level
Etapa 2: Crie uma Medição para Uso de Tokens
Uma medição agrega eventos de uso recebidos e os converte em deduções de crédito. Você precisa disso antes de criar os produtos do plano, já que irá anexá-lo durante a criação do produto na Etapa 3.Configure the meter
Token Usage MeterNome do Evento: api.tokens_used (isso deve corresponder exatamente ao que seu app envia)Tipo de Agregação: Sum — somamos a contagem de tokens de cada eventoPropriedade de Sobreposição: tokens — a chave de metadados em cada evento cujo valor será somadoUnidade de Medição: tokensSalve a medição e copie seu ID — você fará referência a ele ao anexá-la aos produtos.Etapa 3: Crie os Produtos do Plano
Ambos os planos precisam ser produtos de Cobrança Baseada em Uso, não apenas Assinaturas simples — as medições só podem ser anexadas a produtos UBB, e você precisa da medição para descontar automaticamente os créditos à medida que os clientes acessam sua API. Produtos UBB ainda suportam uma taxa base recorrente (o$29 / $99); o uso além disso é cobrado em créditos.

Plano Inicial ($29/mês — 10M tokens, sem excedente)
Create the Starter UBB product
- Vá para Produtos → Criar Produto
- Selecione Cobrança Baseada em Uso como o tipo de precificação
- Preencha:
NeuralAPI StarterDescrição: 10 million API tokens per month. Perfect for individual developers and small projects.Preço Fixo: 29.00 (a taxa base recorrente — cobrada mensalmente mesmo antes de qualquer uso)Ciclo de Cobrança: MonthlyMoeda: USDAttach the meter
Token Usage Meter. Em seguida, na medição:- Ative Cobrar uso em Créditos
- Concessão de Crédito: selecione
API Tokens - Unidades de Medição por Crédito:
1— cada token no evento corresponde a 1 crédito descontado - Limite Gratuito:
0— a alocação de créditos em si é o “nível gratuito” do cliente; não precisamos de uma banda gratuita extra

api.tokens_used recebidos realmente deduzam do saldo do cliente.Configure credit issuance for Starter
10000000Permitir Excedente: Desativado — Clientes do plano Inicial são bloqueados quando os tokens acabamImportar Configurações de Crédito Padrão: Ativado — use a validade de 30 dias da concessão de crédito
Plano Pro ($99/mês — 40M tokens, excedente habilitado)
Create the Pro UBB product
NeuralAPI ProDescrição: 40 million API tokens per month with overage. Built for production applications.Preço Fixo: 99.00Ciclo de Cobrança: MonthlyMoeda: USDAttach the meter
Token Usage Meter, ative Cobrar uso em Créditos ativado, selecione API Tokens, Unidades de Medição por Crédito 1, Limite Gratuito 0.Configure credit issuance with overage
40000000Importar Configurações de Crédito Padrão: Desativado — precisamos personalizar as configurações de excedente por produtoPermitir Excedente: AtivadoPreço Por Unidade: 0.000005 USD por token (ou seja, 5 por 1M tokens — acima da taxa efetiva por token do plano para desencorajar excesso)Comportamento de Excedente: Bill overage at billing — o excedente é cobrado na próxima fatura, depois o saldo é reiniciadoSalve o produto e copie o ID do produto.Etapa 4: Crie o Pacote de Recarga de Tokens
O pacote de recarga é uma compra única que concede 5.000.000 de tokens ao saldo de um cliente existente.
Create a one-time product
- Vá para Produtos → Criar Produto
- Selecione Pagamento Único como o tipo de precificação
- Preencha:
Token Top-Up PackDescrição: Instantly add 5 million tokens to your NeuralAPI balance.Preço: 19.00Moeda: USDAttach the token credit
- Na seção Concessões, clique em Anexar ao lado de Créditos
- Selecione
API Tokens - Defina Créditos emitidos:
5000000 - Desative Importar Configurações de Crédito Padrão — queremos substituir a validade padrão de 30 dias
- Defina Validade do Crédito:
365 days - Salve o produto
Etapa 5: Construa o Backend
Agora vamos construir o servidor Express que lida com o checkout de assinatura, checkout de recarga, conclusões reais do OpenAI com cobrança de tokens, consultas de saldo e eventos de webhook de crédito.Set up environment variables
.env com suas credenciais e IDs das etapas anteriores:DODO_PAYMENTS_WEBHOOK_KEY na Etapa 7 após registrar seu endpoint de webhook.Implement the server
src/server.ts:A note on how deductions actually happen
- Seu manipulador chama o OpenAI e recebe de volta
usage.total_tokens(por exemplo, 1532). - Você ingere um único evento de uso:
event_name: api.tokens_used,metadata: { tokens: 1532 }. - O
Token Usage Meteragrega eventos por cliente. - Como a medição está conectada ao crédito
API Tokenscom Cobrar uso em Créditos, o Dodo Payments deduz 1532 créditos da concessão mais antiga não expirada do cliente (FIFO). - Se o excedente estiver ativado e o cliente ficar abaixo de zero, o déficit é rastreado e cobrado na próxima fatura.
Etapa 6: Adicione um Frontend de Demonstração
Criepublic/index.html para testar todos os fluxos em seu navegador. Persistimos o ID do cliente para localStorage para que assine → gere → recarregue todos compartilhem a mesma identidade, imitando um app autenticado:
Etapa 7: Conecte o Webhook
Webhooks permitem que seu servidor reaja a mudanças de saldo — você os usará para enviar e-mails “quase sem saldo” antes que os clientes cheguem a zero.Expose your local server
https://...ngrok-free.app.Register the webhook in Dodo Payments
- No painel, vá para Desenvolvedores → Webhooks → Adicionar Endpoint
- URL:
https://your-tunnel.ngrok-free.app/webhooks/dodo - Inscreva-se (no mínimo):
credit.addedcredit.deductedcredit.overage_charged
- Salve e copie o Segredo de Assinatura
- Cole-o em
.envcomoDODO_PAYMENTS_WEBHOOK_KEY, então reinicienpm run dev
Etapa 8: Teste o Fluxo Completo
Subscribe a test customer
- Execute
npm run dev - Abra
http://localhost:3000 - Escolha Plano Pro, insira um e-mail de teste + nome, clique em Obter Link de Checkout, complete o checkout com detalhes do cartão de teste
- No painel, vá para Clientes → mais recente e copie o ID
cus_... - Cole-o no campo “ID do cliente logado” na demonstração e clique em Salvar
Generate a real AI response
total_tokens real, ingere um evento de uso e retorna a resposta.Solução de Problemas
Credits not deducting after usage events
Credits not deducting after usage events
- O nome do evento da medição não corresponde ao
event_nameque você está enviando (api.tokens_usedé sensível a maiúsculas e minúsculas) - A medição não está vinculada ao crédito
API Tokensno produto — vá para a configuração de medição do produto e confirme que Cobrar uso em Créditos está ativado - A chave
metadata.tokensnão corresponde ao campo “Propriedade de Sobreposição” da medição - A concessão do cliente expirou (verifique o histórico de créditos do cliente)
- Produtos → Medições: abra a medição e confirme que ela mostra o nome do crédito vinculado no anexo do produto
- A guia Eventos na medição — eventos ingeridos devem aparecer lá mesmo antes da dedução
- Clientes → [Cliente] → Créditos: entradas no livro razão devem aparecer dentro de um ou dois minutos
Balance always shows 0 or 'customer not found'
Balance always shows 0 or 'customer not found'
- O cliente ainda não concluiu o checkout — créditos são emitidos apenas após um pagamento bem-sucedido
- Você está consultando com o
customer_iderrado (use o IDcus_...do painel, não o ID do seu próprio DB) - O
CREDIT_ENTITLEMENT_IDem.envnão corresponde ao crédito anexado ao produto
Overage not working for Pro plan customers
Overage not working for Pro plan customers
- O excedente não foi ativado no anexo de crédito do produto Pro (a configuração de crédito é apenas um padrão)
- O cliente está realmente no plano Inicial, não no Pro
- O limite de excedente foi definido como 0
0.000005 (= $5 por milhão de tokens; verifique os zeros à esquerda — o campo leva o preço por token, não por 1K).`Webhook verification failed` in logs
`Webhook verification failed` in logs
- Ordem de análise do corpo:
express.json()foi aplicado a/webhooks/dodoantes deexpress.raw()— o SDK precisa dos bytes brutos da solicitação, não de JSON analisado - Segredo de assinatura errado em
DODO_PAYMENTS_WEBHOOK_KEY - Proxy reverso está reescrevendo cabeçalhos
app.use('/webhooks/dodo', express.raw(...)) vem antes de app.use(express.json()) em server.ts.Precisa de ajuda?
Parabéns! Você Construiu Cobrança Baseada em Créditos para NeuralAPI
Sua plataforma agora possui um sistema completo de cobrança por créditos, pronto para produção:Token Credit Entitlement
API Tokens reutilizável com validade de 30 dias, compartilhado por todos os planos e o pacote de recargaTiered Plans, One Credit
One-Time Top-Up Pack
Auto-Deduction via Meter
Live Balance API
Verified Webhook Pipeline
credit.added, credit.deducted, credit.overage_charged) roteados por um manipulador de assinatura verificada usando o Standard Webhooks do SDK- Autenticação em
/credits/:customerIde/api/generate— atualmente, qualquer pessoa pode acessar esses pontos com qualquer ID de cliente. Autentique os usuários e procure seu ID de cliente no servidor. - IDs
event_idestáveis — o exemplo usaDate.now() + random. Em produção, use o ID de solicitação para que as tentativas sejam idempotentes (o Dodo Payments deduplica porevent_id). - Persista o mapeamento cliente↔usuário — armazene
customer_idem seu DB após o primeiro checkout para que você não precise de uma etapa manual de colagem. - Decida o que acontece quando uma assinatura termina. Créditos do plano permanecem no livro razão do cliente até sua expiração natural (30 dias a partir da emissão) e créditos de recarga permanecem válidos por 365 dias — mas o
/api/generatedo cookbook só verifica o saldo, não o status da assinatura. Portanto, um cliente cancelado ainda pode consumir seus tokens restantes. Esse é o padrão amigável ao consumidor. Se você deseja um controle de acesso mais rígido, ou (a) escute o webhooksubscription.cancellede controle o acesso/api/generatecom base no status da assinatura, ou (b) chame a API do livro razão do Dodo para debitar créditos de plano não utilizados no cancelamento, deixando intactos os créditos de recarga. - Monitore o painel de Uso de Cobrança para detectar anomalias de medição cedo.