Sandbox

Introdução

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

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:

Ambiente	URL
Produção	https://api.asaas.com/
Sandbox	https://api-sandbox.asaas.com/

🚧
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.

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.

Updated 7 days ago