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",
  "organization_id": "0f7a3c1e-2b4d-4e6f-8a9b-1c2d3e4f5a6b",
  "workspace_id": "5e8d1c4b-7a2f-4c9e-b3d6-0a1f2e3d4c5b",
  "data": {
    "id": "6e4f2a8c-3b5d-4c7e-9f1a-4b6d8e0f2a4c",
    "public_id": "c3d4e5f6-a7b8-4c9d-0e1f-2a3b4c5d6e7f",
    "organization_id": "0f7a3c1e-2b4d-4e6f-8a9b-1c2d3e4f5a6b",
    "workspace_id": "5e8d1c4b-7a2f-4c9e-b3d6-0a1f2e3d4c5b",
    "company_id": null,
    "business_unit_id": null,
    "person_id": "7c1e9f2a-3b4d-4c5e-8f6a-1b2c3d4e5f60",
    "negotiation_offer_id": null,
    "original_total": 4820.00,
    "discount_amount": 820.00,
    "final_total": 4000.00,
    "number_of_installments": 4,
    "installment_value": 1000.00,
    "first_due_date": "2026-08-05T00:00:00.000Z",
    "status": "proposed",
    "accepted_at": null,
    "accepted_ip": null,
    "terms_accepted": null,
    "cancelled_at": null,
    "cancellation_reason": null,
    "completed_at": null,
    "external_id": null,
    "custom_data": null,
    "tags": [],
    "metadata": {},
    "custom_metadata": null,
    "created_at": "2026-07-23T12:00:00.000Z",
    "updated_at": "2026-07-23T12:00:00.000Z",
    "deleted_at": null,
    "person": {
      "id": "7c1e9f2a-3b4d-4c5e-8f6a-1b2c3d4e5f60",
      "name": "Padaria Pão Quente Ltda",
      "document_number": "12345678000190",
      "document_type": "cnpj"
    }
  }
}

agreement.updated

Dispara quando o acordo é alterado. Mesmo shape do agreement.created, mais o array installments:

{
  "installments": [
    {
      "id": "1a3c5e7f-9b2d-4e6f-8a0c-3d5f7b9e1a2c",
      "public_id": "d4e5f6a7-b8c9-4d0e-1f2a-3b4c5d6e7f80",
      "agreement_id": "6e4f2a8c-3b5d-4c7e-9f1a-4b6d8e0f2a4c",
      "installment_number": 1,
      "due_date": "2026-08-05T00:00:00.000Z",
      "amount": 1000.00,
      "paid_amount": null,
      "paid_at": null,
      "status": "pending",
      "deleted_at": null,
      "custom_metadata": null,
      "metadata": {},
      "external_id": null,
      "created_at": "2026-07-23T15:20:00.000Z",
      "updated_at": "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",
  "organization_id": "0f7a3c1e-2b4d-4e6f-8a9b-1c2d3e4f5a6b",
  "workspace_id": "5e8d1c4b-7a2f-4c9e-b3d6-0a1f2e3d4c5b",
  "data": {
    "id": "6e4f2a8c-3b5d-4c7e-9f1a-4b6d8e0f2a4c",
    "original_total": 4820.0,
    "discount_amount": 820.0,
    "final_total": 4000.0,
    "number_of_installments": 4,
    "installment_value": 1000.0,
    "first_due_date": "2026-08-05T00:00:00.000Z",
    "status": "accepted",
    "accepted_at": "2026-07-23T18:45:11.000Z",
    "person_id": "7c1e9f2a-3b4d-4c5e-8f6a-1b2c3d4e5f60"
  }
}

Trate os dois shapes: identifique pelo conjunto de campos ou consulte GET /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 /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",
  "organization_id": "0f7a3c1e-2b4d-4e6f-8a9b-1c2d3e4f5a6b",
  "workspace_id": "5e8d1c4b-7a2f-4c9e-b3d6-0a1f2e3d4c5b",
  "data": { "id": "6e4f2a8c-3b5d-4c7e-9f1a-4b6d8e0f2a4c" }
}