Sandbox

Introdução

Teste sua integração no Sandbox

O Sandbox é o ambiente de testes do Asaas. Nele, você pode desenvolver e homologar sua integração sem movimentar valores reais.

É possível testar fluxos como criação de clientes, cobranças, pagamentos, transferências e Webhooks antes de utilizar as credenciais de Produção.

📘
Ao concluir este guia, você terá criado sua conta Sandbox, configurado a autenticação e entendido como validar os principais fluxos da integração.

Quando utilizar

Use o Sandbox para:

iniciar uma nova integração;
testar requisições sem impacto em Produção;
validar respostas e tratamentos de erro;
homologar cobranças, pagamentos e movimentações;
testar o recebimento e processamento de Webhooks;
preparar sua aplicação para o go-live.

Realize os testes iniciais no Sandbox e migre para Produção somente após validar os fluxos da integração.

1. Crie sua conta Sandbox

👍
Crie sua conta Sandbox e siga o fluxo normal de cadastro.

A conta Sandbox é independente da conta de Produção. Mesmo que você já tenha uma conta Asaas, será necessário criar outra para os testes.

Após concluir o cadastro, gere uma chave de API exclusiva para esse ambiente.

2. Configure o ambiente

Utilize a URL e a chave correspondentes ao ambiente:

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

🚧
As contas, dados, configurações e chaves de API não são compartilhados entre Sandbox e Produção.
Utilize sempre uma chave de Sandbox na URL de Sandbox e uma chave de Produção na URL de Produção.

3. Conheça o comportamento do Sandbox

O Sandbox reproduz a maior parte dos fluxos da plataforma, mas possui comportamentos próprios para facilitar os testes, como:

aprovação automática de contas quando os dados obrigatórios são válidos;
confirmação manual de cobranças;
uso de cartões fictícios;
dados simulados em algumas validações;
recursos específicos para homologação.

🚧
Nem todas as funcionalidades possuem a mesma cobertura ou o mesmo comportamento de Produção.
Consulte O que pode ou não pode ser testado antes de concluir sua homologação.

4. Valide uma jornada completa

Uma homologação pode seguir este fluxo:

Criar conta Sandbox
        ↓
Gerar chave de API
        ↓
Criar cliente
        ↓
Criar cobrança
        ↓
Simular pagamento
        ↓
Receber Webhook
        ↓
Validar o processamento

Por exemplo, para testar o recebimento de uma cobrança:

Crie um cliente.
Crie uma cobrança vinculada a ele.
Simule o pagamento no Sandbox.
Receba o evento de Webhook correspondente.
Confirme se sua aplicação atualizou o status corretamente.

📘
A homologação não deve considerar apenas o retorno da criação.
Valide também mudanças de status, eventos assíncronos, erros e reprocessamentos.

Notificações no Sandbox

O envio de notificações por e-mail e SMS também pode ocorrer no Sandbox.

🚧
Não utilize dados reais de terceiros.
Para testar notificações, informe somente e-mails e números de telefone que você tenha autorização para utilizar.

Evite cadastrar contatos aleatórios ou inválidos, pois as mensagens podem ser enviadas durante os testes.

Antes de ir para Produção

Confirme se sua integração:

utiliza a URL e a chave corretas;
trata respostas de erro;
processa Webhooks de forma idempotente;
possui logs e monitoramento;
não utiliza dados fictícios;
está preparada para diferenças entre Sandbox e Produção;
teve todos os fluxos críticos homologados.

Próximos passos

Updated 6 days ago

Did this page help you?