Developers
Criar chave de APIEntrar na plataforma

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:
Terminal window
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.

Terminal window
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.

Terminal window
curl -i "https://api2.astrify.com.br/v1/funis" \
-H "Authorization: Bearer $ASTRIFY_API_KEY"
  1. Baixe a coleção do Postman e importe em Import.

  2. Nas variáveis da coleção, troque api_key pela sua chave. A base_url já vem como https://api2.astrify.com.br.

  3. 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:

  1. GET /v1/funis e GET /v1/funis/{funil_id}/etapas: guarde o funil_id e o etapa_id onde o lead vai entrar.

  2. POST /v1/leads com nome, funil_id e etapa_id (e um nome que deixe claro que é teste). Guarde o id da resposta.

  3. GET /v1/leads/detalhes/{lead_id}: confira se os campos chegaram como você mandou.

  4. PATCH /v1/leads/{lead_id} com outro etapa_id: confira na plataforma se o card mudou de etapa e se os Workflows de mudança de etapa rodaram.

  5. 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-Signature em 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/eventos em Workflows.

Digite para pesquisar em toda a documentação.