Guia para ERP e sistemas de gestão

Integração por REST (não MCP). Contatos estão em todos os planos com API; negócios e tarefas (CRM) exigem o plano Business.

1. A chave

Crie uma chave de serviço com o modelo "ERP / sistema de gestão", restrinja ao IP do seu servidor e defina a validade (por exemplo 365 dias). Guarde a chave no cofre de segredos do ERP e gire-a uma vez por ano.

2. Mapeie os campos

No ERP	No Atendlly
Código do cliente	`identifier` do contato
Número do pedido / oportunidade	`external_id` do negócio
Nome, e-mail, telefone	`name`, `email`, `phone` (E.164 ou número brasileiro)
Outros dados (CPF, data de nascimento…)	`custom_attributes` (até 30 campos)

3. Carga inicial e sincronização

# carga inicial: todos os contatos, 100 por página, seguindo next_cursor até has_more = false
curl "https://atende.suporteja.com.br/v1/contacts?updated_since=1970-01-01T00:00:00Z&limit=100" -H "Authorization: Bearer $KEY"

Depois, sincronize com updated_since (o maior updated_at que você já viu) e assine os webhooks contact_created, contact_updated e conversation_status_changed (veja webhooks).

4. Gravações sem duplicar

# cliente pelo código do ERP: cria ou atualiza (200 ou 201)
curl -X PUT "https://atende.suporteja.com.br/v1/contacts/by_identifier/CLI-000123" -H "Authorization: Bearer $KEY" \
  -H "Content-Type: application/json" -d '{"name": "Clínica Sorriso", "email": "contato@sorriso.com.br"}'

# negócio pelo número do pedido (Business): cria ou atualiza; repetir não duplica
curl -X PUT "https://atende.suporteja.com.br/v1/crm/deals/by_external_id/PED-98765" -H "Authorization: Bearer $KEY" \
  -H "Content-Type: application/json" -d '{"title": "Pedido 98765", "value_cents": 54000, "contact_id": 812}'

Para os outros POST, envie Idempotency-Key (veja idempotência).

5. Limites e erros

Trate 429 respeitando Retry-After, com espera exponencial. Veja limites e erros.

ERPs comuns

Bling, Omie, Tiny, TOTVS e Sankhya não têm integração nativa: use o código do cliente como identifier e o número do pedido como external_id, como acima. No negócio, a linha do tempo mostra "Integração «nome da chave»" e a origem api.