Sandbox

Como testar minha integração?

O Sandbox do Asaas é o ambiente de testes da API, criado para que você possa desenvolver, validar e homologar sua integração com segurança antes de utilizar credenciais de produção.

Nesse ambiente, é possível simular fluxos como criação de clientes, emissão de cobranças, recebimento de webhooks, pagamentos, transferências e outras operações da plataforma, sem movimentar valores reais.

O objetivo do Sandbox é permitir que sua aplicação seja testada de ponta a ponta antes do go-live, reduzindo riscos durante a transição para produção.

Neste guia você vai encontrar

• Quando usar o Sandbox
• Como criar sua conta Sandbox
• Ambientes e URLs da API
• Como o Sandbox se comporta
• Como configurar sua conta no Sandbox
• Como adicionar saldo para testes
• Como testar funcionalidades no Sandbox
• O que pode ou não pode ser testado
• Aprovação de contas e subcontas
• Erros comuns e boas práticas
• Antes de ir para produção

Quando usar o Sandbox

O Sandbox deve ser utilizado sempre que você precisar:

• iniciar o desenvolvimento de uma nova integração
• validar requisições à API sem impacto em ambiente real
• testar respostas, tratamentos de erro e webhooks
• homologar fluxos de cobrança, pagamento e movimentação
• verificar se sua aplicação está pronta para produção

Recomendamos que todos os testes iniciais da integração sejam realizados nesse ambiente antes da troca para a API de produção.

Como criar sua conta Sandbox

👍

Você pode criar uma conta Sandbox em: https://sandbox.asaas.com/

Basta seguir o fluxo normal de criação de conta e, após finalizar o cadastro, gerar uma API Key exclusiva para esse ambiente.

A conta Sandbox é independente da conta de produção. Por isso, mesmo que você já utilize o Asaas em ambiente real, ainda será necessário criar uma conta própria para testes.

Ambientes e URLs da API

O ambiente Sandbox é separado do ambiente de produção. Isso significa que:

• os dados criados no Sandbox não existem em produção
• os dados criados em produção não existem no Sandbox
• as credenciais de acesso são diferentes
• as configurações realizadas em Sandbox não são replicadas para produção

Para que os testes funcionem corretamente, você deve utilizar a API Key e a URL do ambiente correspondente:

🚧

Use sempre a API Key de Sandbox com a URL de Sandbox.

Use sempre a API Key de produção com a URL de produção.

Como o Sandbox se comporta

O Sandbox reproduz a maior parte dos fluxos da plataforma, mas possui comportamentos específicos para facilitar a homologação da integração.

Entre eles, estão:

• aprovação automática de contas, desde que os dados obrigatórios sejam preenchidos corretamente
• confirmação manual de pagamentos de cobranças
• uso de cartões fictícios para simular pagamentos com cartão de crédito
• dados simulados em algumas validações internas
• recursos e controles disponíveis apenas no ambiente de testes

Essas diferenças existem para permitir que você valide sua integração de forma completa, sem depender de operações reais.

🚧

Embora o comportamento seja semelhante ao ambiente de produção, nem todas as funcionalidades possuem o mesmo fluxo ou a mesma cobertura no Sandbox.

Sempre consulte a seção O que pode ou não pode ser testado antes de concluir a homologação de um fluxo.

Exemplo de jornada de homologação

Uma jornada típica de testes em Sandbox costuma seguir o seguinte fluxo:

Criar conta Sandbox
        ↓
Gerar API Key
        ↓
Criar cliente
        ↓
Criar cobrança
        ↓
Simular pagamento
        ↓
Receber webhook
        ↓
Validar processamento da aplicação

Por exemplo, para validar o fluxo de recebimento de uma cobrança via API, normalmente você irá:

1. Criar um cliente utilizando o endpoint de clientes.
2. Criar uma cobrança vinculada a esse cliente.
3. Simular o pagamento da cobrança no ambiente Sandbox.
4. Receber o webhook correspondente ao evento de pagamento.
5. Validar se sua aplicação processa corretamente a atualização do status da cobrança.

Esse processo permite validar toda a comunicação entre sua aplicação e o Asaas antes da utilização em produção.

Os detalhes de cada cenário de teste estão disponíveis nas páginas específicas deste guia, como testes de cobranças, transferências, pagamentos, assinaturas e webhooks.

Notificações em Sandbox

O envio e o recebimento de notificações por e-mail e SMS funcionam normalmente em Sandbox.

🚧

Não utilize dados reais de terceiros nos testes.

Para validar notificações, utilize apenas seus próprios e-mails e números de telefone.

Também evite cadastrar números aleatórios ou inválidos apenas para teste, pois isso pode comprometer a validação correta do fluxo de notificações.