Cada evento registra uma ação de consumo feita por um cliente — e é a partir deles que toda a cadeia de cobrança é calculada.
O que são eventos
Um evento é um registro que documenta uma ação de uso realizada por um cliente no seu produto. Pense nele como um recibo digital: ele registra quem usou, o que usou, quando usou e quanto usou.
Exemplos do mundo real:
| Produto | Evento | O que mede |
|---|
| Plataforma de API | api_request | Cada chamada à API |
| Cloud storage | storage_used | GB armazenados por dia |
| Fintech | transaction_processed | Cada transação financeira processada |
| Plataforma de IA | inference_call | Cada chamada de inferência ao modelo |
| Help desk | ticket_resolved | Cada ticket resolvido |
Estrutura de um evento
Cada evento possui os seguintes campos:
| Campo | Obrigatório | Descrição |
|---|
idempotencyKey | Sim | Chave única que previne processamento duplicado |
customerExternalId | Sim | ID externo do cliente que gerou o uso |
eventName | Sim | Nome do tipo de uso (ex: api_request, storage_used) |
occurredAt | Sim | Quando o uso aconteceu (ISO 8601, UTC) |
properties.value | Sim | Quantidade consumida (inteiro, mínimo 0) |
properties.* | Não | Propriedades adicionais para filtragem e segmentação |
{
"idempotencyKey": "20240115-acme-api-req-001",
"customerExternalId": "acme_001",
"eventName": "api_request",
"occurredAt": "2024-01-15T14:30:00Z",
"properties": {
"value": 250,
"endpoint": "/v1/payments",
"method": "POST",
"status_code": 200
}
}
Para recursos monetários (valores em dinheiro), envie o valor em centavos — por exemplo, R$ 1.200,50 deve ser enviado como 120050.
Origem do evento
Cada evento registra automaticamente como foi criado:
| Origem | Quando |
|---|
| API | Evento enviado via endpoint /v1/events/ingest |
| Import | Evento importado via planilha CSV/Excel |
| User | Evento criado manualmente pelo Dashboard |
Recálculo de faturas
As faturas são recalculadas diariamente durante a madrugada com os eventos recebidos ao longo do dia. Depois que uma fatura é fechada, ela não é recalculada automaticamente — apenas por ação manual no Dashboard.
Se você precisa corrigir eventos após o fechamento de uma fatura, é possível reabrir a fatura e recalcular os valores manualmente.
Próximos passos
