Eventos de cobro (charge.*)

Hechos del ciclo de vida de los cobros. En los eventos de entidad, data es el cobro serializado en el formato de la API v1, con person y collectionRule completos embebidos. En los eventos de hecho (paid, overdue), data es un objeto de referencia compacto.

charge.created

Se dispara cuando se crea un cobro (API, importación, sincronización con 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 (mismo shape que person.created)" },
    "collectionRule": { "id": "8f6a4c2e-1b3d-4e5f-a7c9-2d4f6b8a0e1c", "name": "Régua padrão B2B", "...": "regla completa (mismo shape que collection_rule.created, sin steps)" }
  }
}

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

charge.updated

Se dispara cuando el cobro se modifica vía API/dashboard. Mismo shape que charge.created — nota que currentAmount, daysOverdue y status se recalculan en cada actualización (un cobro vencido puede llegar ya con status: "overdue").

charge.deleted

Se dispara en la eliminación (lógica). Bloqueada si el cobro tiene notificaciones, interacciones, negativaciones o protestos — en esos casos el evento no ocurre.

{
  "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

Se dispara cuando se identifica un pago (webhook del PSP/gateway, conciliación). La regla de cobranza se interrumpe y los envíos pendientes se suprimen antes del 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 y paidAt reflejan lo que reportó el proveedor de pago. Para el estado completo del cobro después de la baja, consulta GET /api/v1/charges/{chargeId}.

charge.overdue

Se dispara una vez por transición: el día en que el cobro vence sin pago (job diario), no cada día 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 ya incluye intereses y multa calculados en el corte.