Eventos de acordo (agreement.*)

Fatos do ciclo de vida dos acordos de negociação. Nos eventos de entidade, data é o acordo com o cliente resumido (person) e, quando já geradas, as parcelas (installments).

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

agreement.created

Dispara quando uma proposta de acordo é criada (status: "proposed"). As parcelas ainda não existem — são geradas no aceite.

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

Dispara quando o acordo é alterado. Mesmo shape do agreement.created, mais o 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

Dispara no aceite do acordo — as parcelas são geradas e a régua das cobranças cobertas é interrompida antes do evento. O shape do data depende de quem aceitou:

Aceite pelo operador (API/dashboard) — acordo completo (mesmo shape do agreement.updated, com installments), agora com status: "accepted", acceptedAt, acceptedIp e termsAccepted preenchidos.

Aceite pelo devedor (portal) — resumo enxuto, com 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"
  }
}

Trate os dois shapes: identifique pelo conjunto de campos ou consulte GET /api/v1/agreements/{id} para o estado canônico.

agreement.cancelled

Dispara no cancelamento. data é o acordo completo (com installments), com status: "cancelled", cancelledAt e cancellationReason preenchidos; parcelas pendentes/vencidas vão a cancelled.

agreement.broken

:::caution Planejado — ainda não emitido Este evento está reservado no catálogo, mas ainda não é emitido: como a quebra de acordo é marcada manualmente (não há detecção automática), nenhum ponto do sistema dispara agreement.broken hoje. Para acompanhar acordos inadimplentes, consulte o status defaulted via GET /api/v1/agreements ou monitore os eventos de acordo já emitidos (agreement.accepted, agreement.cancelled). :::

Quando passar a ser emitido, disparará na quebra do acordo (parcela não paga leva o acordo a defaulted), com data no shape de entidade da família (acordo completo com installments).

agreement.completed

Dispara quando todas as parcelas são quitadas (status: "completed", completedAt preenchido). data segue o shape de entidade da família.

agreement.deleted

Dispara na exclusão (lógica); acordos completed não podem ser excluídos.

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