Skip to main content
O caso mais comum de integração: manter a base de contatos da SocialSell alinhada com um sistema que já existe. Este guia cobre as duas direções e os pontos onde a maioria das integrações erra. Escopos necessários: read:contacts, write:contacts e — se você usar tags — write:tags.

1. Carga inicial: leia tudo

Pagine até o fim usando has_more como condição de parada.
Use meta.has_more, não meta.next_cursor === null: o campo é omitido na última página. Testar contra null gera um laço infinito ou uma parada precoce, conforme a linguagem.

2. Incremental: só o que mudou

Guarde o horário da última sincronização e use updated_after:
Guarde o timestamp de antes de começar a varredura, não de depois. Um contato alterado durante a leitura seria perdido se você marcasse o fim.

3. Escrevendo de volta: trate a duplicata

Criar contato com telefone ou email já existente devolve 409com o ID do contato existente no corpo. É a deixa para atualizar em vez de criar.

4. Cuidados que evitam retrabalho

tags e custom_fields no PATCH substituem tudo. Enviar tags: ["novo"] apaga as demais. Para acrescentar sem perder, use POST /v1/contacts/:id/tags.
Contato não tem responsável. Não existe assigned_to em contato — a atribuição acontece por conversa. Se o seu sistema tem “dono do cliente”, mapeie para um campo personalizado, ou espelhe via assigned_to das conversas.
Excluir contato dispara contact.deleted — assim como criar, atualizar, e adicionar ou remover tag. Se a sua integração escreve pela API e assina esses eventos, ela recebe o eco da própria ação: deduplique por id do evento.

5. Tempo real: complemente com webhooks

Para não varrer a base a cada minuto, assine os eventos e reserve a varredura para uma conferência diária:
O payload de data.contact tem o mesmo formato que a API devolve — não é preciso um segundo parser.

Checklist

  • Paginação para em has_more: false
  • updated_after no incremental, com o timestamp de antes da varredura
  • DUPLICATE_CONTACT tratado como “atualizar”
  • Idempotency-Key estável por contato
  • Tags acrescentadas pelo endpoint dedicado, não pelo PATCH
  • Webhooks assinados e assinatura validada
  • Varredura de conferência agendada