Skip to main content
O API Gateway Blueprint envia um evento de uso para Dodo Payments a cada chamada de API processada pelo seu serviço, e um medidor Count transforma esses eventos em uma cobrança por chamada para cada cliente. Use-o para acompanhar o uso de endpoints da API, orientar limites de taxa e cobrar pelo uso da API. Ele é fornecido no pacote npm @dodopayments/ingestion-blueprints como trackAPICall(), que envia um evento por chamada, e createBatch(), que enfileira eventos para volumes altos de solicitações.

Casos de uso

O API Gateway Blueprint é adequado para estes cenários:

API-as-a-Service

Acompanhe as chamadas por cliente em uma plataforma de API e cobre pelo número de chamadas.

Rate Limiting

Registre o volume de chamadas de cada cliente para orientar limites de taxa baseados no uso. O blueprint registra o uso, mas não aplica limites.

Performance Monitoring

Registre os tempos de resposta e os códigos de status com cada evento, para que as taxas de erro fiquem junto dos dados de cobrança.

Multi-Tenant SaaS

Cobre os clientes pelo consumo da API em diferentes endpoints.
Cada evento precisa do ID do cliente Dodo Payments que será cobrado, iniciado por cus_. Armazene-o com o registro do usuário ao criar o cliente e passe-o como customerId.

Início rápido

Para acompanhar as chamadas de API, instale o pacote, crie um medidor e envie um evento para cada chamada.
1

Install the SDK

Instale o pacote Dodo Payments Ingestion Blueprints:
2

Get Your API Keys

Crie uma chave de API do Dodo Payments em Developer → API Keys no dashboard do Dodo Payments e armazene-a na variável de ambiente DODO_PAYMENTS_API_KEY. Use uma chave do modo de teste durante o desenvolvimento. Uma chave do modo de teste funciona apenas com test_mode.
3

Create a Meter

No dashboard do Dodo Payments, acesse Products → Meters e clique em Create Meter. Defina estes campos:
  • Meter Name: um nome descritivo, como API Calls.
  • Event Name: api_call ou um nome escolhido por você. Ele deve corresponder exatamente a eventName no seu código (diferencia maiúsculas de minúsculas).
  • Aggregation Type: Count, para cobrar pelo número de chamadas.
  • Measurement Unit: a unidade exibida nas faturas, como calls.
Para contar apenas algumas chamadas, ative Enable Event Filtering e adicione condições a chaves de metadata, como endpoint, method ou status_code.
4

Track API Calls

Crie uma instância de Ingestion com sua chave de API e o nome do evento e escolha um padrão: um evento por chamada, um lote para alto volume ou um middleware do Express.js que acompanhe todas as solicitações. No middleware, req.user vem do seu middleware de autenticação, e seu id deve ser um ID de cliente Dodo Payments. As solicitações sem um usuário conectado são enviadas com o ID de cliente anonymous, que não corresponde a nenhum cliente.

Configuração

Configuração de ingestão

Passe estas opções para new Ingestion():
string
obrigatório
Sua chave de API do Dodo Payments obtida no dashboard.
string
Modo do ambiente: test_mode ou live_mode. O padrão é test_mode. Os SDKs do Dodo Payments usam live_mode por padrão; portanto, defina live_mode explicitamente em produção.
string
obrigatório
Nome do evento que corresponde ao Event Name do seu medidor (diferencia maiúsculas de minúsculas). Todo evento enviado por esta instância usa esse nome.

Opções para acompanhar chamadas de API

Passe estas opções para trackAPICall() e batch.add():
string
obrigatório
O ID do cliente Dodo Payments a ser cobrado pela chamada, por exemplo, cus_123.
object
Metadata opcional sobre a chamada de API, como endpoint, método, código de status e tempo de resposta. Cada valor deve ser uma string, um número ou um booleano. A API rejeita objetos aninhados, arrays e valores null.

Configuração de lotes

createBatch(ingestion, options) enfileira eventos na memória e retorna um objeto com três métodos: add() enfileira um evento, flush() envia os eventos enfileirados e cleanup() os envia e interrompe o temporizador. Um flush envia uma solicitação de ingestão por evento, em paralelo.
number
Número de eventos enfileirados que aciona um flush imediato. Padrão: 100.
number
Milissegundos a aguardar após o add() mais recente antes que o lote seja enviado. Cada add() reinicia o temporizador. Padrão: 5000 (5 segundos).

Práticas recomendadas

Use processamento em lote para alto volume: para aplicações com alto tráfego, use createBatch(). batch.add() retorna imediatamente, portanto o rastreamento não adiciona latência ao seu handler de requisição.
Um lote mantém os eventos na memória até ser enviado e não tenta novamente enviar eventos cujo envio falhou. Um flush automático registra o erro com console.error. Uma chamada a flush() ou cleanup() gera o erro.
Limpe os lotes durante o encerramento: chame batch.cleanup() quando sua aplicação for encerrada, para que os eventos pendentes sejam enviados em vez de perdidos.
Última modificação em 26 de setembro de 2026