Postman

Use a coleção do Postman para testar os endpoints da API do Asaas em Sandbox antes de implementar as chamadas na sua aplicação.

Quando usar a coleção do Postman

Use a coleção quando você precisar:

• Validar autenticação, headers e URLs antes de escrever código.
• Explorar os endpoints documentados sem montar as requisições manualmente.
• Reproduzir erros de integração e comparar o comportamento da API entre Sandbox e Produção.
• Compartilhar um conjunto de requisições com o time durante o desenvolvimento.

Pré-requisitos

Antes de executar as requisições:

1. Instale o Postman ou acesse sua conta pelo navegador.
2. Crie uma conta de testes no Sandbox do Asaas.
3. Gere uma chave de API para o ambiente que você vai usar. Consulte o guia Chaves de API.
4. Leia o guia de Autenticação para confirmar os headers obrigatórios.

⚠️

Não compartilhe sua chave de API em workspaces públicos, prints, repositórios ou conversas. A chave identifica sua conta e autoriza chamadas em seu nome.

Acessar e fazer fork da coleção

1. Acesse a API do Asaas no Postman:

Acessar Asaas API no Postman

2. No menu lateral esquerdo, expanda Asaas API e clique em Collection Asaas.

3. Clique em Fork, no canto superior direito, e selecione o Workspace em que deseja copiar a coleção.

Configurar autenticação e ambiente

Depois de fazer o fork, configure a coleção ou a requisição que deseja testar com os headers abaixo.

Use a URL correta para o ambiente que você quer testar:

⚠️

As chaves de API de Sandbox e Produção são diferentes. Se você usar uma chave de Produção em uma URL de Sandbox, ou o contrário, a API retornará erro de autenticação.

Se a coleção estiver usando variáveis de ambiente no Postman, atualize a variável da URL base e a variável da chave de API antes de enviar a primeira requisição. Se não estiver usando variáveis, confira esses valores diretamente nos headers e na URL da requisição.

Testar uma requisição

1. Selecione um endpoint dentro da Collection Asaas.
2. Confirme se a URL aponta para o ambiente desejado.
3. Confirme se os headers Content-Type, User-Agent e access_token foram enviados.
4. Clique em Send.
5. Verifique o status HTTP e o corpo da resposta.

Uma resposta de sucesso varia conforme o endpoint chamado, mas deve retornar um status 2xx. Se a autenticação falhar, a API retornará 401 Unauthorized com detalhes no corpo da resposta.

Exemplo de erro por chave usada no ambiente incorreto:

{
  "errors": [
    {
      "code": "invalid_environment",
      "description": "A chave de API informada não pertence a este ambiente"
    }
  ]
}

Exemplo de erro por header de autenticação ausente:

{
  "errors": [
    {
      "code": "access_token_not_found",
      "description": "O cabeçalho de autenticação 'access_token' é obrigatório e não foi encontrado na requisição"
    }
  ]
}

Solução de problemas

Conteúdos relacionados

• Autenticação: veja os headers obrigatórios, URLs de ambiente e erros de autenticação.
• Chaves de API: aprenda a criar e gerenciar sua chave de API.
• Sandbox: teste a integração com dados fictícios antes de usar Produção.