Saltar al contenido principal

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

charge.promise_registered​

Se dispara cuando se registra una promesa de pago: una interacción con resultado promise_to_pay y promiseDate futura (día civil en la zona horaria de la organización). La regla de cobranza se pausa y los envíos pendientes se cancelan hasta promiseDate más el período de gracia (2 días civiles por defecto) — si la interacción está vinculada a un cobro, solo ese; si no, todos los cobros del cliente en regla (un evento por cobro pausado).

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

Aquí id es el id del cobro cubierto por la promesa; interactionId apunta a la interacción que la registró. promiseDate es una fecha civil (medianoche UTC) y promisedAmount es un string decimal o null (promesa sin monto informado). Una promesa nueva sustituye a las anteriores abiertas en el mismo alcance — pasa a valer el nuevo plazo.

charge.promise_broken​

Se dispara cuando la verificación diaria encuentra una promesa vencida más allá de la gracia con el cobro aún abierto (no pagado, no negociado, no cancelado). La regla se reanuda desde donde se detuvo, una vez por cada cobro aún abierto en el alcance de la promesa. Una promesa cumplida no genera evento propio — el pago ya emitió 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"
  }
}

Mismo shape que el registro. Con la gracia por defecto, una promesa para el viernes puede pagarse hasta el domingo — el lunes se resuelve (cumplida o rota).