Skip to main content

​
Esquema

CampoTipoDescrição
invoiceIdUUIDv7Identificador único
organizationIdUUIDv7FK para Organization
subscriptionIdUUIDv7?FK para Subscription
externalRefstringID da invoice no Stripe (único)
typeenumPLAN, FEE
paymentMethodenum?CARD, BOLETO
cardJSON?{brand, last4, expMonth, expYear}
boletoJSON?{url}
currencyenumUSD, BRL, EUR
totalAmountintegerTotal em centavos
discountAmountintegerDesconto em centavos
payableAmountintegerValor a pagar em centavos
discountsarrayDescontos aplicados
linesarrayItens InvoiceLine
statusenumVeja abaixo
issuedAtdatetimeData de emissão
dueDatedatetimeData de vencimento
paidAtdatetime?Data do pagamento
createdAtdatetimeCriação
updatedAtdatetimeÚltima atualização
Existem dois tipos de invoice: PLAN para a cobrança fixa da assinatura e FEE para as taxas de uso variável. Cada tipo corresponde a uma subscription separada no Stripe (externalPlanRef e externalFeeRef).

​
Transições de Estado

Uma invoice em DISPUTED requer ação imediata — o valor fica retido pelo gateway até resolução. Se o dispute for perdido (CHARGEBACK), o valor é estornado ao cliente e a subscription pode entrar em PAST_DUE.

​
Relacionamentos

  • Belongs to Organization
  • Belongs to Subscription (opcional)
  • Has many InvoiceLines
  • Has many CouponUsages / VoucherUsages
  • Has one InvoiceBillingThreshold (opcional)

​
Regras de Negócio

  • Sincronizada com o Stripe
  • Pode incluir descontos de cupom + voucher simultaneamente
  • Suporta upsert por externalRef para invoices manuais
O campo payableAmount é sempre calculado como totalAmount - discountAmount. Descontos de cupom e voucher são aplicados em cascata: primeiro o cupom (percentual ou fixo), depois o voucher (crédito).

​
Exemplo

{
  "invoiceId": "019527b3-5e60-7b7f-d6a4-0c2e8a4b6d9f",
  "organizationId": "019526a0-1a20-7d3b-a1c9-5f7e9b0d3f5b",
  "subscriptionId": "019526a1-3c40-7f5d-b4e2-8a0c6e2f4b7d",
  "externalRef": "in_1PqR2sT4uV6wX8yZ0A",
  "type": "PLAN",
  "paymentMethod": "CARD",
  "card": {
    "brand": "visa",
    "last4": "4242",
    "expMonth": 12,
    "expYear": 2028
  },
  "boleto": null,
  "currency": "BRL",
  "totalAmount": 29900,
  "discountAmount": 5980,
  "payableAmount": 23920,
  "discounts": [
    {
      "type": "COUPON",
      "couponId": "019526b2-4d50-7a6e-c5f3-9b1d7f3a5c8e",
      "code": "BEMVINDO2026",
      "discountType": "PERCENTAGE",
      "amount": 20,
      "discountAmount": 5980
    }
  ],
  "lines": [
    {
      "description": "Plano Profissional — Mensal",
      "quantity": 1,
      "unitAmount": 29900,
      "totalAmount": 29900
    }
  ],
  "status": "PAID",
  "issuedAt": "2026-02-01T00:00:00Z",
  "dueDate": "2026-02-10T23:59:59Z",
  "paidAt": "2026-02-03T14:22:31Z",
  "createdAt": "2026-02-01T00:00:00Z",
  "updatedAt": "2026-02-03T14:22:31Z"
}