Developers
Criar chave de APIEntrar na plataforma

Checklist para colocar a sua integração em produção

Chaves, escopos, limites, retentativas, duplicidade e webhooks. O que conferir antes de ligar uma integração com a API aberta da Astrify Flows.

Equipe Astrify FlowsBoas práticas · · 6 min de leitura

A integração funcionou no teste. Antes de deixá-la rodando sozinha, vale passar por esta lista. Cada item tem o link para o guia com a regra completa.

Chave e acesso

Uma chave por integração. Se o ERP e o site usam a mesma chave, revogar uma derruba as duas. Com chaves separadas, o Último uso e as Últimas chamadas de cada uma mostram exatamente quem está chamando o quê.

Só os escopos necessários. GET pede <recurso>:read; os demais métodos pedem <recurso>:write. Uma integração que só lê leads não precisa de leads:write. A tabela completa está em Autenticação e chaves de API.

Lembre de quem criou a chave. A chave age em nome do usuário que a criou: vale o menor entre a permissão do cargo dele e os escopos da chave. Se esse usuário for desativado, a chave para de funcionar. Prefira criar as chaves de produção com um usuário que não vai sair da empresa.

Restrinja por IP quando o servidor tiver IP fixo (até 20 IPs por chave). Chamadas de outro IP recebem 403.

Planeje a validade. A chave expira em 30 dias, 90 dias, 180 dias, 1 ano ou 2 anos. Anote a data e use Rotacionar com a opção de manter a antiga ativa: as duas funcionam ao mesmo tempo e você troca a integração sem ficar fora do ar.

Segredo fora do código. Variável de ambiente ou cofre de segredos. Se a chave vazar, revogue na hora: em poucos segundos ela para em todos os servidores.

Limites e falhas

Respeite 120 requisições por minuto por chave. O limite vale para todos os planos e não é configurável. Para volume, use as rotas em lote (como POST /v1/leads/importar-lote) e espalhe as chamadas no tempo.

Trate 429 com o Retry-After. A resposta diz quantos segundos esperar.

Repita só o que pode dar certo na segunda vez. 429, 5xx, falha de rede e tempo esgotado: sim, com espera crescente (1 s, 2 s, 4 s…) e um máximo de tentativas. 400, 401, 403, 404, 409 e 422: não, a mesma chamada vai falhar de novo.

Tempo limite de 15 a 30 segundos no seu cliente HTTP.

Trate pelo status, não pelo texto. A mensagem em detail ajuda a depurar, mas pode mudar. Detalhes em Limites de uso e erros.

Duplicidade

A API não tem cabeçalho de idempotência. Antes de repetir um POST que estourou o tempo, consulte se o registro foi criado (por exemplo, GET /v1/leads?view=list&search=…) ou guarde o id que veio na primeira resposta. O artigo Do formulário do site ao funil de vendas mostra esse padrão em código.

Listas grandes

Paginar certo evita perder registros. Peça limit=100&offset=0, depois offset=100, e pare quando has_more for false, quando offset passar de total ou quando vier menos itens que o limit. Veja Paginação e filtros.

Webhooks

URL de webhook de entrada é credencial. Quem souber a URL dispara o Workflow. Chame a partir do servidor, nunca do navegador, e lembre que cada evento executado conta no limite mensal de execuções do plano.

Valide a assinatura dos webhooks de saída. O cabeçalho X-Astrify-Signature traz t=<timestamp>,v1=<hex>. Recalcule o HMAC-SHA256 com o corpo exatamente como chegou, compare em tempo constante e rejeite entregas com mais de 5 minutos de diferença. Código pronto em Webhooks de saída.

O bloco Disparar webhook do Workflow não assina. Se a sua URL recebe chamadas desse bloco, envie um token próprio num cabeçalho e confira do seu lado.

Antes de abrir um chamado

Tenha em mãos o prefixo da chave (nunca a chave completa), o método e a rota, o status e o detail da resposta e a data e hora aproximadas. Veja Suporte.

Digite para pesquisar em toda a documentação.