read:contacts, write:contacts e — se você usar tags — write:tags.
1. Carga inicial: leia tudo
Pagine até o fim usandohas_more como condição de parada.
2. Incremental: só o que mudou
Guarde o horário da última sincronização e useupdated_after:
3. Escrevendo de volta: trate a duplicata
Criar contato com telefone ou email já existente devolve409 — com o ID do contato existente no corpo. É a deixa para atualizar em vez de criar.
4. Cuidados que evitam retrabalho
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: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_afterno incremental, com o timestamp de antes da varredura -
DUPLICATE_CONTACTtratado como “atualizar” -
Idempotency-Keyestável por contato - Tags acrescentadas pelo endpoint dedicado, não pelo
PATCH - Webhooks assinados e assinatura validada
- Varredura de conferência agendada

