Eventos de acuerdo (agreement.*)

Hechos del ciclo de vida de los acuerdos de negociación. En los eventos de entidad, data es el acuerdo con el cliente resumido (person) y, cuando ya se generaron, las cuotas (installments).

Valores de status: proposed · accepted · active · completed · cancelled · defaulted. Valores de status de cuota: pending · paid · overdue · cancelled.

agreement.created

Se dispara cuando se crea una propuesta de acuerdo (status: "proposed"). Las cuotas todavía no existen — se generan en la aceptación.

{
  "event": "agreement.created",
  "timestamp": "2026-07-23T12:00:00.000Z",
  "organizationId": "0f7a3c1e-2b4d-4e6f-8a9b-1c2d3e4f5a6b",
  "data": {
    "id": "6e4f2a8c-3b5d-4c7e-9f1a-4b6d8e0f2a4c",
    "publicId": "c3d4e5f6-a7b8-4c9d-0e1f-2a3b4c5d6e7f",
    "organizationId": "0f7a3c1e-2b4d-4e6f-8a9b-1c2d3e4f5a6b",
    "workspaceId": null,
    "companyId": null,
    "businessUnitId": null,
    "personId": "7c1e9f2a-3b4d-4c5e-8f6a-1b2c3d4e5f60",
    "negotiationOfferId": null,
    "originalTotal": "4820.00",
    "discountAmount": "820.00",
    "finalTotal": "4000.00",
    "numberOfInstallments": 4,
    "installmentValue": "1000.00",
    "firstDueDate": "2026-08-05T00:00:00.000Z",
    "status": "proposed",
    "acceptedAt": null,
    "acceptedIp": null,
    "termsAccepted": null,
    "cancelledAt": null,
    "cancellationReason": null,
    "completedAt": null,
    "externalId": null,
    "customData": null,
    "tags": [],
    "metadata": {},
    "createdAt": "2026-07-23T12:00:00.000Z",
    "updatedAt": "2026-07-23T12:00:00.000Z",
    "deletedAt": null,
    "person": {
      "id": "7c1e9f2a-3b4d-4c5e-8f6a-1b2c3d4e5f60",
      "name": "Padaria Pão Quente Ltda",
      "documentNumber": "12345678000190",
      "documentType": "cnpj"
    }
  }
}

agreement.updated

Se dispara cuando el acuerdo se modifica. Mismo shape que agreement.created, más el array installments:

{
  "installments": [
    {
      "id": "1a3c5e7f-9b2d-4e6f-8a0c-3d5f7b9e1a2c",
      "publicId": "d4e5f6a7-b8c9-4d0e-1f2a-3b4c5d6e7f80",
      "agreementId": "6e4f2a8c-3b5d-4c7e-9f1a-4b6d8e0f2a4c",
      "installmentNumber": 1,
      "dueDate": "2026-08-05T00:00:00.000Z",
      "amount": "1000.00",
      "paidAmount": null,
      "paidAt": null,
      "status": "pending",
      "deletedAt": null,
      "customMetadata": null,
      "metadata": {},
      "externalId": null,
      "createdAt": "2026-07-23T15:20:00.000Z",
      "updatedAt": "2026-07-23T15:20:00.000Z"
    }
  ]
}

agreement.accepted

Se dispara en la aceptación del acuerdo — las cuotas se generan y la regla de cobranza de los cobros cubiertos se interrumpe antes del evento. El shape del data depende de quién aceptó:

Aceptación por el operador (API/dashboard) — acuerdo completo (mismo shape que agreement.updated, con installments), ahora con status: "accepted", acceptedAt, acceptedIp y termsAccepted llenos.

Aceptación por el deudor (portal) — resumen compacto, con valores numéricos:

{
  "event": "agreement.accepted",
  "timestamp": "2026-07-23T18:45:12.000Z",
  "organizationId": "0f7a3c1e-2b4d-4e6f-8a9b-1c2d3e4f5a6b",
  "data": {
    "id": "6e4f2a8c-3b5d-4c7e-9f1a-4b6d8e0f2a4c",
    "originalTotal": 4820.0,
    "discountAmount": 820.0,
    "finalTotal": 4000.0,
    "numberOfInstallments": 4,
    "installmentValue": 1000.0,
    "firstDueDate": "2026-08-05T00:00:00.000Z",
    "status": "accepted",
    "acceptedAt": "2026-07-23T18:45:11.000Z",
    "personId": "7c1e9f2a-3b4d-4c5e-8f6a-1b2c3d4e5f60"
  }
}

Maneja los dos shapes: identifícalos por el conjunto de campos o consulta GET /api/v1/agreements/{id} para el estado canónico.

agreement.cancelled

Se dispara en la cancelación. data es el acuerdo completo (con installments), con status: "cancelled", cancelledAt y cancellationReason llenos; las cuotas pendientes/vencidas pasan a cancelled.

agreement.broken

:::caution Planeado — todavía no se emite Este evento está reservado en el catálogo, pero todavía no se emite: como el incumplimiento del acuerdo se marca manualmente (no hay detección automática), ningún punto del sistema dispara agreement.broken hoy. Para seguir los acuerdos morosos, consulta el status defaulted vía GET /api/v1/agreements o monitorea los eventos de acuerdo ya emitidos (agreement.accepted, agreement.cancelled). :::

Cuando pase a emitirse, se disparará al incumplirse el acuerdo (una cuota no pagada lleva el acuerdo a defaulted), con data en el shape de entidad de la familia (acuerdo completo con installments).

agreement.completed

Se dispara cuando todas las cuotas quedan saldadas (status: "completed", completedAt lleno). data sigue el shape de entidad de la familia.

agreement.deleted

Se dispara en la eliminación (lógica); los acuerdos completed no pueden eliminarse.

{
  "event": "agreement.deleted",
  "timestamp": "2026-07-23T12:00:00.000Z",
  "organizationId": "0f7a3c1e-2b4d-4e6f-8a9b-1c2d3e4f5a6b",
  "data": { "id": "6e4f2a8c-3b5d-4c7e-9f1a-4b6d8e0f2a4c" }
}