Migrar dos endpoints antigos
De/para entre `/api/integrations/*` e a API v1 — e por que não há pressa.
Se você já tem automações rodando com /api/integrations/*, elas continuam funcionando. Não há prazo de validade, e não vamos desligá-las: sabemos que o segredo está colado dentro de fluxos em produção.
O v1 existe porque a superfície antiga cresceu por demanda e ficou sem regra — três formas de identificar um contato, nenhum jeito de corrigir um cadastro, e idempotência em um endpoint só. Migre quando for mexer no fluxo de qualquer jeito.
De/para
| antigo | novo | o que muda |
|---|---|---|
GET /integrations/contacts?phone= | GET /v1/contacts/:id ou GET /v1/contacts?phone= | aceita contact_id; lista com filtros |
POST /integrations/contacts | POST /v1/contacts | não cria mais card — use POST /v1/cards |
GET /integrations/pipelines | GET /v1/pipelines | igual, mais meta_capi_event por etapa |
GET /integrations/products | GET /v1/products | paginado de verdade (o antigo cortava em 500 sem avisar) |
POST /integrations/sales | POST /v1/sales | aceita contact_id; erro estruturado |
POST /integrations/send | POST /v1/conversations/:id/messages | vira sub-recurso; ganha Idempotency-Key |
POST /integrations/conversations/ai | PATCH /v1/conversations/:id | junta IA, status e responsável no mesmo verbo |
| — | POST /v1/cards | novo: cria o lead na etapa que você escolher |
| — | PATCH /v1/contacts/:id | novo: corrigir cadastro |
| — | /v1/tasks, /v1/notes, /v1/tags, /v1/companies | novos |
As três diferenças que exigem atenção
1. O formato do erro mudou. Antes:
{ "ok": false, "error": "Contato não encontrado." }
Agora:
{ "ok": false, "error": { "code": "not_found", "message": "Contato não encontrado nesta conta." } }
Se o seu fluxo lê error como texto, ele passa a receber um objeto. Programe contra error.code.
2. POST /v1/contacts não cria card. O antigo criava por padrão (create_funnel_card: true), sempre na etapa de entrada. Se o seu fluxo dependia disso, acrescente uma chamada a POST /v1/cards — e aproveite para escolher a etapa certa em vez da entrada.
3. A chave. O v1 aceita o segredo antigo, mas o recomendado é criar uma chave por integração em Configurações → Integrações. Com chaves separadas, revogar uma não derruba as outras.
Dá para usar os dois ao mesmo tempo?
Dá. O mesmo segredo antigo autentica nas duas superfícies, e a chave nova também. Migre endpoint por endpoint, sem janela de parada.