Esquema
| Campo | Tipo | Descrição |
|---|
feeId | UUIDv7 | Identificador único |
externalProductRef | string | Produto no Stripe (único) |
externalPriceRef | string | Price no Stripe (único) |
externalBillingMeterRef | string | Billing meter no Stripe (único) |
name | string | Nome da fee, máx 255 |
description | text | Descrição |
eventName | string | Nome do evento único, máx 255 |
currency | enum | USD, BRL, EUR |
status | enum | ACTIVE, INACTIVE |
createdBy | UUIDv7 | Criador |
createdAt | datetime | Criação |
updatedBy | UUIDv7 | Último atualizador |
updatedAt | datetime | Última atualização |
deletedBy | UUIDv7? | Quem deletou |
deletedAt | datetime? | Soft delete |
Cada fee cria três recursos no Stripe: um product, um price (metered) e um billing meter. O eventName é usado para enviar eventos de consumo ao billing meter do Stripe, que então calcula o uso para faturamento.
FeeToken (M2M)
| Campo | Tipo | Descrição |
|---|
feeId | UUIDv7 | FK para Fee |
tokenId | UUIDv7 | FK para Token |
A tabela FeeToken define quais tokens compõem cada fee. Uma fee de “Uso de IA” pode agrupar tokens de RESPONSE, PLANNING e MEMORY, por exemplo. Isso permite calcular o custo total de uma operação que consome múltiplos tipos de token.
Relacionamentos
- Has many Tokens via FeeToken (M2M)
- Has many Costs
- Has many VoucherFees
Regras de Negócio
eventName globalmente único- Máximo 10 fees ACTIVE por moeda
- Sincronizada com Stripe (product, price, billing meter)
- Fees vinculadas não podem ter moedas duplicadas
O limite de 10 fees ativas por moeda é uma regra de negócio para manter a previsibilidade do faturamento. Fees inativas não contam para o limite mas continuam existindo para histórico de custos.
Exemplo
{
"feeId": "019527a2-4e50-7b6f-d5a3-0b1d7e3a5c8e",
"externalProductRef": "prod_S9lMnO3qR5xY",
"externalPriceRef": "price_3RsT4uV6wX8yZ0aB",
"externalBillingMeterRef": "bm_1AbCdEfGhIjKlMn",
"name": "Uso de IA — Agentes",
"description": "Consumo de tokens de IA para execução de agentes autônomos",
"eventName": "ai_agent_usage",
"currency": "USD",
"status": "ACTIVE",
"tokens": [
{
"tokenId": "019527b1-5d60-7a7e-c6b4-1c2e8a4b6d9f",
"name": "GPT-4o Response",
"type": "RESPONSE",
"value": 0.00001,
"currency": "USD"
},
{
"tokenId": "019527b1-6e70-7b8f-d7c5-2d3f9a5b7c0e",
"name": "GPT-4o Planning",
"type": "PLANNING",
"value": 0.000015,
"currency": "USD"
}
],
"createdBy": "019525fc-1234-7a1b-8c2d-3e4f5a6b7c8d",
"createdAt": "2026-01-10T08:00:00Z",
"updatedBy": "019525fc-1234-7a1b-8c2d-3e4f5a6b7c8d",
"updatedAt": "2026-01-10T08:00:00Z"
}
