Endpoint#
HTTP
POST /v1/integrations/eventsO corpo é um envelope com a versão do contrato e uma lista de eventos:
JSON
{
"schemaVersion": 1,
"events": [
{
"id": "evt_8f2c1a",
"type": "deal.upserted",
"occurredAt": "2026-10-07T13:00:00-03:00",
"contact": {
"externalId": "pac_88",
"name": "Maria Souza",
"phone": "+55 47 99999-0000",
"email": "[email protected]"
},
"deal": {
"externalId": "orc_991",
"status": "won",
"stage": "Pago",
"amount": 350.00,
"currency": "BRL",
"openedAt": "2026-10-05T09:12:00-03:00",
"closedAt": "2026-10-07T13:00:00-03:00",
"attendant": "Ana",
"origin": "Instagram"
}
}
]
}- Cada requisição leva de 1 a 50 eventos.
- Os eventos são processados na ordem do array. Dois eventos do mesmo orçamento no mesmo lote são aplicados na sequência em que vieram.
schemaVersionhoje é sempre1. Outro valor é recusado com400 schema_version_unsupported.
Tipos de evento#
type | Quando enviar |
|---|---|
deal.upserted | O orçamento foi criado ou teve qualquer mudança: status, valor, etapa. |
deal.deleted | O orçamento foi excluído no seu sistema. O corpo precisa só de deal.externalId. |
Um tipo fora desta lista volta como ignored, sem erro. Assim, versões futuras do contrato não quebram quem já integra.
Exclusão#
JSON
{
"schemaVersion": 1,
"events": [
{
"id": "evt_8f2c1d",
"type": "deal.deleted",
"occurredAt": "2026-10-08T10:00:00-03:00",
"deal": { "externalId": "orc_991" }
}
]
}Quando enviar#
Envie um deal.upserted a cada mudança do orçamento, com o estado completo dele naquele momento. Não é preciso agrupar por horário: lotes pequenos e frequentes funcionam bem. Veja as regras de consistência antes de implementar.