# Sincronizar contatos com o seu sistema

Se seu sistema (ERP, planilha, outro CRM) é a fonte da verdade dos seus contatos, você quer mantê-los sincronizados com o AtendeBot nos dois sentidos: seu sistema envia atualizações para cá, e o AtendeBot avisa quando um contato muda por aqui (ex.: um atendente editou o e-mail no atendimento).

<p class="callout info">Esta receita usa a API v3, a versão atual. Se você vem da v2, comece por <a href="/books/api-e-integracoes/page/o-que-a-api-v3-faz-e-como-comecar">O que a API v3 faz e como começar</a>.</p>

## Objetivo
Criar ou atualizar contatos pelo telefone a partir do seu sistema, em um contato por vez ou em lote, e receber de volta as mudanças feitas no AtendeBot.

## Pré-requisitos
- Token de API com escopos **`contacts:write`** e **`contacts:read`**: veja [Gerar tokens de API para integrações](/books/canais-e-integracoes/page/gerar-tokens-de-api-para-integracoes).
- Um endpoint seu para receber o webhook de volta (opcional, só para o passo 3 abaixo; o que é um webhook: [Configurar webhooks para sistemas externos](/books/canais-e-integracoes/page/configurar-webhooks-para-sistemas-externos)).

## Tempo estimado
15 minutos.

## Caminho de acesso
Chamada direta à API: não há tela equivalente no AtendeBot para sincronização em lote vinda de fora.

## Passo a passo
1. **Criar ou atualizar um contato pelo telefone**, num único contato: use `if_exists: "update"` para que a mesma chamada funcione tanto na primeira sincronização (cria) quanto nas seguintes (atualiza). O telefone precisa vir com DDI, em E.164:

   ```bash
   curl -X POST https://api.atende.bot/public/v3/contacts \
     -H "Authorization: Bearer SEU_TOKEN" \
     -H "Content-Type: application/json" \
     -d '{
       "name": "Maria Souza",
       "phone": "5511999998888",
       "email": "maria@exemplo.com",
       "if_exists": "update"
     }'
   ```

   Sem `if_exists`, telefone já cadastrado responde `409 CONFLICT`, proteção contra duplicata quando você quer só criar.

2. **Em lote**, até 500 contatos por chamada, em `POST /contacts/batch` (só criação, não aceita `if_exists`):

   ```bash
   curl -X POST https://api.atende.bot/public/v3/contacts/batch \
     -H "Authorization: Bearer SEU_TOKEN" \
     -H "Content-Type: application/json" \
     -d '[
       { "name": "Maria Souza", "phone": "5511999998888" },
       { "name": "João Lima", "phone": "5521988887777" }
     ]'
   ```

   A resposta traz `meta.partial: true` quando algum item falha depois de gravar (ex.: tag inexistente); cada falha aparece em `failed`, com o **índice do item** no campo `field`.

3. **De volta**: crie a assinatura do evento `contact.updated` no **formato 3** (o que esta receita espera). Pela tela de Ajustes (API e webhooks → Webhooks) ela já nasce nesse formato: no diálogo, "Formato do payload" fica em v3, e o botão `{ }` ao lado de cada evento abre o envelope de exemplo. Ou pela API:

   ```bash
   curl -X POST https://api.atende.bot/public/v3/webhooks \
     -H "Authorization: Bearer SEU_TOKEN" \
     -H "Content-Type: application/json" \
     -d '{
       "name": "Sincronizar contatos: de volta",
       "url": "https://SEU-ENDPOINT/webhooks/contact-updated",
       "events": [{ "name": "contact.updated" }],
       "secret": "UM_SEGREDO_SEU"
     }'
   ```

   A entrega traz `data.contact` (o contato já carregado: `id`, `name`, `phone`, `email`, `tags`...) e `data.changed`, a lista dos campos que mudaram. Na maioria dos casos você nem precisa buscar de novo; se precisar do contato completo, use `GET /public/v3/contacts/{{ $json.data.contact.id }}` ou `GET /public/v3/contacts/phone:5511999998888` (o prefixo `phone:` funciona como referência direta).

## Resultado esperado
Contato criado ou atualizado a partir do seu sistema; mudanças feitas por aqui chegam de volta pelo webhook `contact.updated`.

## Erros comuns
- **Sintoma:** `400 PHONE_REQUIRES_COUNTRY_CODE`. **Solução:** 10-11 dígitos é faixa ambígua, sempre envie com código do país, ex.: `5511999998888`.
- **Sintoma:** `409 CONFLICT` ao criar. **Solução:** telefone já existe, use `if_exists: "update"`.

## Artigos relacionados
- [O que a API v3 faz e como começar](/books/api-e-integracoes/page/o-que-a-api-v3-faz-e-como-comecar)
- [Configurar webhooks para sistemas externos](/books/canais-e-integracoes/page/configurar-webhooks-para-sistemas-externos)
- [Abrir um card no CRM quando chega uma mensagem](/books/api-e-integracoes/page/abrir-um-card-no-crm-quando-chega-uma-mensagem)