Boas práticas

O que faz a integração durar.

• Use o modo incremental (desde + depoisDe) para sincronizar: traz só o que mudou e não derruba o limite.
• Trate 429 esperando o Retry-After, com recuo exponencial — nunca repita em laço fechado.
• Mande Idempotency-Key em todo POST: rede cai, sua rotina repete, e nada duplica.
• Confira a assinatura do webhook antes de processar; responda 2xx rápido e processe depois.
• Uma chave por sistema integrado, com o menor escopo que serve; revogue a que não se usa.

Formas inadequadas

• Varrer a lista inteira a cada minuto — é o que o modo incremental substitui.
• Compartilhar a chave de API com usuários finais ou embuti-la em app de celular ou página pública.
• Gravar via API sem usuário responsável na chave — a trilha ficaria sem autoria, por isso é 409.