Pular para o conteúdo principal

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, promise_*), 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",
    "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.

charge.promise_registered​

Dispara quando uma promessa de pagamento é registrada: uma interação com desfecho promise_to_pay e promiseDate futura (dia civil no fuso da organização). A régua da cobrança é pausada e os envios pendentes são cancelados até promiseDate mais a carência (2 dias civis por padrão) — se a interação está vinculada a uma cobrança, só ela; senão, todas as cobranças em régua do cliente (um evento por cobrança pausada).

{
  "event": "charge.promise_registered",
  "timestamp": "2026-08-04T15:20:33.000Z",
  "organizationId": "0f7a3c1e-2b4d-4e6f-8a9b-1c2d3e4f5a6b",
  "data": {
    "id": "4a2b6c8d-1e3f-4a5b-9c7d-2e4f6a8b0c1d",
    "personId": "7c1e9f2a-3b4d-4c5e-8f6a-1b2c3d4e5f60",
    "interactionId": "5d3e7f9a-2b4c-4d6e-8f0a-3c5e7a9b1d2f",
    "promiseDate": "2026-08-10T00:00:00.000Z",
    "promisedAmount": "1512.50"
  }
}

Aqui id é o id da cobrança sob a promessa; interactionId aponta a interação que a registrou. promiseDate é uma data civil (meia-noite UTC) e promisedAmount é string decimal ou null (promessa sem valor informado). Uma promessa nova substitui as anteriores em aberto no mesmo escopo — passa a valer o novo prazo.

charge.promise_broken​

Dispara quando a verificação diária encontra uma promessa vencida além da carência com a cobrança ainda em aberto (não paga, não negociada, não cancelada). A régua é retomada de onde parou, uma vez por cobrança ainda em aberto no escopo da promessa. Promessa cumprida não gera evento próprio — o pagamento já emitiu charge.paid.

{
  "event": "charge.promise_broken",
  "timestamp": "2026-08-13T04:30:00.000Z",
  "organizationId": "0f7a3c1e-2b4d-4e6f-8a9b-1c2d3e4f5a6b",
  "data": {
    "id": "4a2b6c8d-1e3f-4a5b-9c7d-2e4f6a8b0c1d",
    "personId": "7c1e9f2a-3b4d-4c5e-8f6a-1b2c3d4e5f60",
    "interactionId": "5d3e7f9a-2b4c-4d6e-8f0a-3c5e7a9b1d2f",
    "promiseDate": "2026-08-10T00:00:00.000Z",
    "promisedAmount": "1512.50"
  }
}

Mesmo shape do registro. Com a carência default, uma promessa para sexta pode ser paga até domingo — na segunda ela resolve (cumprida ou quebrada).