Eventos de cobrança (charge.*)

Fatos do ciclo de vida das cobranças. Nos eventos de entidade, data é a cobrança serializada no formato da API v1, com person e collectionRule completos embutidos. Nos eventos de fato (paid, overdue), data é um objeto de referência enxuto.

charge.created

Dispara quando uma cobrança é criada (API, importação, sincronização com ERP/gateway).

{
  "event": "charge.created",
  "timestamp": "2026-07-23T12:00:00.000Z",
  "organizationId": "0f7a3c1e-2b4d-4e6f-8a9b-1c2d3e4f5a6b",
  "data": {
    "id": "4a2b6c8d-1e3f-4a5b-9c7d-2e4f6a8b0c1d",
    "publicId": "b2c3d4e5-f6a7-4b8c-9d0e-1f2a3b4c5d6e",
    "organizationId": "0f7a3c1e-2b4d-4e6f-8a9b-1c2d3e4f5a6b",
    "workspaceId": null,
    "companyId": null,
    "businessUnitId": null,
    "personId": "7c1e9f2a-3b4d-4c5e-8f6a-1b2c3d4e5f60",
    "collectionRuleId": "8f6a4c2e-1b3d-4e5f-a7c9-2d4f6b8a0e1c",
    "documentNumber": "NF-2026-0451",
    "description": "Mensalidade julho/2026",
    "originalAmount": "1500.00",
    "interestAmount": "0.00",
    "fineAmount": "0.00",
    "discountAmount": "0.00",
    "paidAmount": null,
    "currentAmount": "1500.00",
    "issueDate": "2026-07-01T00:00:00.000Z",
    "dueDate": "2026-07-31T00:00:00.000Z",
    "paidAt": null,
    "daysOverdue": 0,
    "status": "pending",
    "paymentMethod": null,
    "barcode": null,
    "pixEmv": null,
    "paymentUrl": "https://pay.example.com/b2c3d4e5",
    "externalId": "ERP-TIT-2026-0451",
    "customData": null,
    "tags": ["mensalidade"],
    "currentStep": null,
    "lastNotificationAt": null,
    "negativedAt": null,
    "protestedAt": null,
    "source": "api",
    "lastVerifiedAt": null,
    "paymentClaimed": false,
    "legalHold": false,
    "legalHoldReason": null,
    "deletedAt": null,
    "metadata": {},
    "createdAt": "2026-07-23T12:00:00.000Z",
    "updatedAt": "2026-07-23T12:00:00.000Z",
    "person": { "id": "7c1e9f2a-3b4d-4c5e-8f6a-1b2c3d4e5f60", "name": "Padaria Pão Quente Ltda", "documentNumber": "12345678000190", "...": "cliente completo (mesmo shape do person.created)" },
    "collectionRule": { "id": "8f6a4c2e-1b3d-4e5f-a7c9-2d4f6b8a0e1c", "name": "Régua padrão B2B", "...": "régua completa (mesmo shape do collection_rule.created, sem steps)" }
  }
}

Valores de status: pending · paid · overdue · cancelled · negotiated · protested · negatived · written_off. Valores de source: kobana · erp · api · spreadsheet · manual.

charge.updated

Dispara quando a cobrança é alterada via API/dashboard. Mesmo shape do charge.created — repare que currentAmount, daysOverdue e status são recalculados a cada atualização (uma cobrança vencida pode chegar já com status: "overdue").

charge.deleted

Dispara na exclusão (lógica). Bloqueada se a cobrança tem notificações, interações, negativações ou protestos — nesses casos o evento não ocorre.

{
  "event": "charge.deleted",
  "timestamp": "2026-07-23T12:00:00.000Z",
  "organizationId": "0f7a3c1e-2b4d-4e6f-8a9b-1c2d3e4f5a6b",
  "data": { "id": "4a2b6c8d-1e3f-4a5b-9c7d-2e4f6a8b0c1d" }
}

charge.paid

Dispara quando um pagamento é identificado (webhook do PSP/gateway, conciliação). A régua é interrompida e os envios pendentes são suprimidos antes do evento.

{
  "event": "charge.paid",
  "timestamp": "2026-07-23T14:32:08.000Z",
  "organizationId": "0f7a3c1e-2b4d-4e6f-8a9b-1c2d3e4f5a6b",
  "data": {
    "chargeId": "4a2b6c8d-1e3f-4a5b-9c7d-2e4f6a8b0c1d",
    "personId": "7c1e9f2a-3b4d-4c5e-8f6a-1b2c3d4e5f60",
    "amount": 1500.0,
    "paidAt": "2026-07-23T14:31:55.000Z"
  }
}

amount e paidAt refletem o que o provedor de pagamento reportou. Para o estado completo da cobrança após a baixa, consulte GET /api/v1/charges/{chargeId}.

charge.overdue

Dispara uma vez por transição: no dia em que a cobrança vence sem pagamento (job diário), não a cada dia de atraso.

{
  "event": "charge.overdue",
  "timestamp": "2026-07-23T06:00:00.000Z",
  "organizationId": "0f7a3c1e-2b4d-4e6f-8a9b-1c2d3e4f5a6b",
  "data": {
    "chargeId": "4a2b6c8d-1e3f-4a5b-9c7d-2e4f6a8b0c1d",
    "personId": "7c1e9f2a-3b4d-4c5e-8f6a-1b2c3d4e5f60",
    "daysOverdue": 1,
    "currentAmount": 1512.5
  }
}

currentAmount já inclui juros e multa calculados na virada.