Pular para o conteúdo principal

Sincronizar os contatos de um site

POST 
/contacts/sync

Os clientes de um site conectado, até 500 por chamada. É o que o plugin do WordPress chama para trazer os usuários, clientes e leads do site — e qualquer plataforma própria com a API key de um site conectado pode chamar também. A resposta é 200 mesmo quando linhas falham: o resultado de cada uma vem em results, na ordem do envio.

POST /contacts/batch é uma planilha enviada uma vez. Esta rota é o contrário: um sistema que reporta as mesmas pessoas de novo e de novo, e por isso as regras só somam, nunca destroem:

  • o contato é achado primeiro por quem ele é no site (ref: o usuário 42 do WordPress), depois pelo telefone. Quem trocou de número continua sendo o mesmo contato; se o número novo já é de outro contato, nada é unido e a linha volta com phone_conflict;
  • sem telefone e sem vínculo com o site, ninguém é criado (no_phone, invalid_phone);
  • tags só entram, pelo nome, e as que não existem são criadas. Para tirar uma, use removeTags;
  • nome, e-mail e campos personalizados só preenchem o que está vazio: o que alguém digitou no painel vence o que o site reporta. Os campos que o próprio site calcula (os wc_… do WooCommerce) sobrescrevem — a menos que occurredAt seja mais antigo que o último aplicado para aquele vínculo (stale_snapshot);
  • um opt-out dado no site sempre vale. O consentimento só passa de unknown para opted_in, com evidência, e nunca por cima de um opt-out (kept_opt_out) ou de uma supressão (kept_suppression);
  • um valor para um campo que a conta não tem, ou do tipo errado, é descartado e aparece em warnings — o resto da linha é aplicado;
  • contatos novos contam no teto do plano (contact_limit_reached).

Com options.triggers em false — o padrão, o de uma carga inicial — nada dispara: nenhum fluxo começa e nenhum webhook contact.created sai. Uma carga de dez mil clientes não pode cumprimentar dez mil pessoas. Mande true para o que acabou de acontecer no site.

Idempotência. Com o header Idempotency-Key, um lote repetido depois de uma conexão que caiu devolve o primeiro resultado, com Idempotent-Replayed: true, em vez de ser aplicado duas vezes. A mesma chave com outro corpo é recusada com 422 idempotency_key_reused; enquanto a primeira requisição ainda roda, a repetição recebe 409 idempotency_in_progress.

Só a API key de um site conectado sincroniza — ela vem com a permissão contacts:sync. Uma API key comum recebe 404 site_not_found, e uma API key restrita a alguns números, 403.

Request​

Responses​

Resultado por linha.