Esquema
| Campo | Tipo | Descrição |
|---|
voucherId | UUIDv7 | Identificador único |
organizationId | UUIDv7 | FK para Organization |
externalRef | string? | Credit grant no Stripe |
name | string | Nome do voucher, máx 255 |
amount | integer | Crédito em centavos |
currency | enum | USD, BRL, EUR |
effectiveAt | datetime? | Data de ativação |
expiresAt | datetime? | Data de expiração |
amountRedeemed | integer | Valor utilizado em centavos |
status | enum | PENDING, ACTIVE, DEPLETED, EXPIRED |
createdBy | UUIDv7 | Criador |
createdAt | datetime | Criação |
updatedBy | UUIDv7 | Último atualizador |
updatedAt | datetime | Última atualização |
deletedBy | UUIDv7? | Quem deletou |
deletedAt | datetime? | Soft delete |
Vouchers são criados via padrão Saga com o Stripe billing credit grant. A criação local e no Stripe acontecem de forma coordenada — se qualquer etapa falhar, a saga compensa automaticamente para garantir consistência entre os sistemas.
Transições de Estado
Um voucher com effectiveAt nulo fica ACTIVE imediatamente. Use effectiveAt para agendar promoções futuras — o voucher aparece como PENDING até a data de ativação.
Relacionamentos
- Belongs to Organization
- Has many VoucherFees
- Has many VoucherUsages
Regras de Negócio
- Criado via padrão Saga com Stripe billing credit grant
- Restrições opcionais por fee via VoucherFees
- Status gerenciado pelas datas effectiveAt/expiresAt
Se um voucher tem VoucherFees configurados, ele só pode ser aplicado em invoices que contenham line items referentes àquelas fees específicas. Sem VoucherFees, o voucher se aplica a qualquer invoice da organização.
Exemplo
{
"voucherId": "019528d5-7a80-7d9b-f8c6-2e4a0c6d8f1b",
"organizationId": "019526a0-1a20-7d3b-a1c9-5f7e9b0d3f5b",
"externalRef": "cg_1AbCdEfGhIjKlMnOpQ",
"name": "Crédito de onboarding",
"amount": 50000,
"currency": "BRL",
"effectiveAt": "2026-02-01T00:00:00Z",
"expiresAt": "2026-08-01T23:59:59Z",
"amountRedeemed": 18750,
"status": "ACTIVE",
"feeRestrictions": [
{
"feeId": "019527a2-4e50-7b6f-d5a3-0b1d7e3a5c8e",
"name": "Uso de IA — Agentes"
}
],
"usages": [
{
"invoiceId": "019527b3-5e60-7b7f-d6a4-0c2e8a4b6d9f",
"amount": 8750,
"appliedAt": "2026-02-15T00:00:00Z"
},
{
"invoiceId": "019528c6-8b90-7e0c-a9d7-3f5b1d7e9a2c",
"amount": 10000,
"appliedAt": "2026-03-15T00:00:00Z"
}
],
"createdBy": "019525fc-1234-7a1b-8c2d-3e4f5a6b7c8d",
"createdAt": "2026-01-28T14:00:00Z",
"updatedBy": "019525fc-1234-7a1b-8c2d-3e4f5a6b7c8d",
"updatedAt": "2026-03-15T00:00:00Z"
}
