Testar e validar chamadas
Como testar a sua chave e cada rota com curl, Postman ou a referência interativa, conferir a resposta e tratar os erros antes de ir para produção.
A API aberta não tem ambiente de testes separado: toda chamada feita com a sua chave age nos dados reais da sua empresa. Por isso, teste com registros criados só para isso (por exemplo, um lead chamado “Teste da integração”) e apague-os no fim.
Antes de começar
- Crie uma chave só para testes em Configurações → API aberta, com os escopos que a integração vai usar e uma validade curta (30 dias). Veja Autenticação e chaves de API.
- Guarde a chave numa variável de ambiente, nunca no código:
export ASTRIFY_API_KEY="SUA_CHAVE_DE_API"1. Confira a chave
GET /v1/me aceita qualquer chave válida e responde com a empresa, os escopos e a validade. É a primeira chamada de qualquer integração.
curl -i https://api2.astrify.com.br/v1/me \ -H "Authorization: Bearer $ASTRIFY_API_KEY"O -i mostra o status e os cabeçalhos da resposta. O esperado é 200 com:
{ "data": { "empresa_id": "00000000-0000-0000-0000-000000000000", "chave": { "id": "11111111-1111-1111-1111-111111111111", "nome": "Integração com o ERP", "escopos": ["contatos:write", "leads:write"], "expira_em": "2027-11-15T12:00:00+00:00", "limite_rpm": 120 } }}Confira em escopos se a chave tem o que cada rota pede. O escopo de cada rota está na página da área, em Rotas da API no menu (por exemplo, Leads). Se vier 401, a chave está errada, expirou ou foi revogada.
2. Teste as rotas
Escolha a ferramenta que preferir. Os exemplos de cada rota, em curl, Node.js e Python, estão nas páginas de Rotas da API.
Copie o exemplo da rota, troque os marcadores em maiúsculas (como LEAD_ID) por ids reais da sua empresa e rode no terminal. Para ver o status e os cabeçalhos, acrescente -i.
curl -i "https://api2.astrify.com.br/v1/funis" \ -H "Authorization: Bearer $ASTRIFY_API_KEY"-
Baixe a coleção do Postman e importe em Import.
-
Nas variáveis da coleção, troque
api_keypela sua chave. Abase_urljá vem comohttps://api2.astrify.com.br. -
Abra a rota, ajuste os ids e o corpo e clique em Send. A autenticação Bearer já usa a variável
api_key.
A referência interativa monta a requisição a partir da especificação: escolha a rota, informe a chave no campo de autenticação Bearer, preencha os parâmetros e envie.
A chamada sai do seu navegador direto para a API. Se o navegador bloquear o envio (erro de CORS no console), copie o exemplo em curl que a própria referência mostra e rode no terminal, ou use o Postman.
3. Valide a resposta
Trate a resposta pelo status HTTP primeiro e só depois pelo corpo.
| Status | O que significa | Como validar |
|---|---|---|
200 |
Deu certo | Confira os campos que você vai usar. Muitas rotas de escrita respondem {"success": true, …} com o registro criado ou uma mensagem. |
400 |
Dado inválido ou id de outra empresa | Liste os ids antes (ex.: GET /v1/funis) e use só os da sua empresa. |
401 |
Chave ausente, inválida, expirada ou revogada | Confira o cabeçalho Authorization: Bearer …. |
403 |
Sem o escopo, cargo sem permissão, IP fora da lista ou plano sem a API | Leia o detail: ele diz o motivo. |
404 |
Registro não existe nesta empresa | Confira o id. |
422 |
Corpo ou parâmetro com formato inválido | O detail lista cada campo com problema. |
429 |
Passou de 120 requisições por minuto | Espere o tempo do cabeçalho Retry-After. |
Os erros vêm com a mensagem em detail:
{ "detail": "Escopo necessário: leads:write" }E os de validação (422) dizem onde está o problema:
{ "detail": [ { "loc": ["body", "funil_id"], "msg": "Field required", "type": "missing" } ]}A lista completa de status, retentativas e como evitar duplicidade está em Limites de uso e erros.
4. Teste o caminho completo
Um roteiro que cobre o caso mais comum, criar um lead e acompanhar o que acontece com ele:
-
GET /v1/funiseGET /v1/funis/{funil_id}/etapas: guarde ofunil_ide oetapa_idonde o lead vai entrar. -
POST /v1/leadscomnome,funil_ideetapa_id(e um nome que deixe claro que é teste). Guarde oidda resposta. -
GET /v1/leads/detalhes/{lead_id}: confira se os campos chegaram como você mandou. -
PATCH /v1/leads/{lead_id}com outroetapa_id: confira na plataforma se o card mudou de etapa e se os Workflows de mudança de etapa rodaram. -
DELETE /v1/leads/{lead_id}: apague o lead de teste.
Os detalhes de cada chamada estão em Leads e Funis.
5. Valide os webhooks
Se a integração recebe eventos da Astrify Flows, teste também a ponta que recebe:
- Aponte o webhook para uma URL pública de teste do seu servidor (a URL precisa ser pública, não vale
localhost). - Confira a assinatura
X-Astrify-Signatureem toda entrega e rejeite as que não baterem. O passo a passo, com exemplos em Node.js e Python, está em Webhooks de saída. - Para disparar Workflows a partir do seu sistema, veja Webhooks de entrada e a rota
POST /v1/workflows/eventosem Workflows.