Mesmo sendo muito semelhante ao ambiente de produção, o ambiente de Sandbox possui comportamentos específicos relacionados à aprovação de contas, onboarding e acesso de subcontas.

Por isso, alguns cuidados são necessários para garantir que os testes ocorram corretamente.

Aprovação de contas avulsas

No Sandbox, contas criadas diretamente no ambiente são aprovadas automaticamente, desde que todos os dados comerciais obrigatórios sejam preenchidos corretamente.

Garanta que os dados informados sejam compatíveis com o tipo do campo, evitando por exemplo:

• números no campo de nome;
• caracteres especiais;
• preenchimentos inconsistentes.

Após o envio das informações obrigatórias, a validação ocorre automaticamente, sem necessidade de envio manual de documentos.

No ambiente de testes, os dados utilizados não precisam ser reais. É obrigatório apenas o preenchimento completo dos campos exigidos para que a validação seja concluída.

👍

Dica

Caso não queira utilizar dados reais, você pode usar geradores de dados fictícios para seus testes, como:

https://geradorbr.com/gerador-de-pessoas/

❗️

Importante

O uso de números ou caracteres especiais (como _, #, !, -, entre outros) no nome da conta pode:

• impedir a validação automática;
• desabilitar funcionalidades como PIX;
• comprometer o funcionamento correto da integração.

Evite:

Conta Teste_01

Prefira:

Conta Teste Um

Se a conta não for aprovada automaticamente ou o PIX aparecer como desabilitado, revise o nome cadastrado, remova números e caracteres especiais e atualize os dados da conta.

Caso o problema persista, entre em contato com o suporte.

Aprovação de subcontas

No Sandbox, a aprovação de subcontas pode ocorrer de diferentes formas, dependendo do modelo utilizado na integração.

Atualmente, existem três possibilidades:

• aprovação automática via configuração do Sandbox;
• aprovação manual utilizando endpoint específico de aprovação;
• fluxo de onboarding via onboardingUrl em operações BaaS.

É fundamental garantir o preenchimento correto de todos os dados comerciais obrigatórios no momento da criação da subconta.

Além disso, o nome da subconta também deve seguir as mesmas regras aplicadas às contas avulsas, utilizando apenas letras e espaços.

Aprovação via endpoint

O Sandbox disponibiliza um endpoint específico para aprovação de contas e subcontas durante os testes.

Esse fluxo pode ser utilizado para simular aprovações sem depender do comportamento automático do ambiente.

Endpoint:

POST /v3/accounts/{id}/approve

Referência: Aprovar contas em sandbox

📘

Quando utilizar

Esse endpoint é especialmente útil em cenários onde:

• a aprovação automática não está habilitada;
• o integrador deseja controlar o momento da aprovação;
• é necessário simular comportamentos mais próximos do ambiente produtivo.

Autoaprovação de subcontas

Também é possível habilitar a funcionalidade de autoaprovação no Sandbox.

Nesse modelo, novas subcontas são aprovadas automaticamente após a criação, desde que os dados obrigatórios estejam preenchidos corretamente.

A configuração pode ser realizada conforme descrito aqui:

Como configurar sua conta no Sandbox

Comportamento por tipo de subconta

Cada modelo de subconta possui comportamentos específicos relacionados ao onboarding e acesso no ambiente de Sandbox.

Subcontas padrão

Ao criar uma subconta padrão no Sandbox, o link de redefinição de senha é enviado para o e-mail da conta pai responsável pela criação da subconta.

Esse comportamento existe apenas para facilitar os testes no ambiente Sandbox.

O acesso da subconta ocorre da seguinte forma:

1. a conta pai recebe o e-mail de redefinição de senha;
2. o link é utilizado para definir a senha da subconta;
3. após a definição da senha, o login pode ser realizado normalmente com os dados da subconta.

❗️

Importante

O envio do e-mail para a conta pai é um comportamento específico do Sandbox e não representa exatamente o fluxo operacional do ambiente de produção.

Subcontas em operações BaaS

Em operações BaaS, o onboarding pode ocorrer por meio do onboardingUrl, onde o usuário final realiza o envio dos documentos obrigatórios.

No Sandbox, esse fluxo possui caráter ilustrativo e simplificado, servindo apenas para homologação da integração.

O comportamento do ambiente de testes não representa integralmente todas as validações regulatórias, cadastrais e operacionais existentes em produção.

📘

Importante

Em operações BaaS, o fluxo de onboarding, envio de documentos, aprovação e apresentação da instituição prestadora pode variar conforme:

• tipo de conta;
• validações regulatórias;
• status cadastral;
• regras de compliance;
• configurações contratuais e operacionais aplicáveis em produção.

Atualização de dados comerciais

Ao atualizar dados comerciais da conta ou subconta no Sandbox, algumas informações podem ser preenchidas automaticamente durante o processo de validação.

Por exemplo, o Asaas pode inserir nomes genéricos como:

João da Silva

para permitir a continuidade do fluxo de homologação.

Da mesma forma, ao acessar a aba Meu usuário, podem aparecer informações como:

• CPF;
• endereço;
• data de nascimento.

Esses dados são simulados e utilizados exclusivamente para funcionamento interno do ambiente Sandbox, não representando dados reais.

Erros comuns e boas práticas

Durante a homologação em Sandbox, alguns problemas são recorrentes. Antes de acionar o suporte, revise os pontos abaixo.

Utilizar API Key ou URL incorreta

Verifique se a API Key utilizada corresponde ao ambiente correto.

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

Misturar credenciais e ambientes é uma das causas mais comuns de erro de autenticação e comportamentos inesperados.

Tentar testar operações sem saldo disponível

Alguns fluxos exigem saldo disponível na conta Sandbox.

Nesses casos:

1. crie cobranças fictícias;
2. confirme os pagamentos;
3. utilize o saldo gerado para continuar os testes.

Esperar comportamento idêntico ao ambiente de produção

Embora o Sandbox replique grande parte da jornada real, algumas etapas possuem comportamento específico de homologação, como:

• aprovações automáticas;
• confirmações manuais;
• uso de dados simulados;
• fluxos simplificados;
• controles de teste exclusivos do Sandbox.

Utilizar dados inválidos no cadastro

Nomes com números, caracteres especiais ou preenchimentos inconsistentes podem:

• impedir a aprovação automática;
• comprometer o funcionamento do PIX;
• gerar falhas em funcionalidades dependentes da validação cadastral.

Testar notificações com dados de terceiros

As notificações por e-mail e SMS funcionam normalmente no Sandbox.

Para evitar disparos indevidos:

• utilize apenas contatos próprios;
• evite utilizar dados reais de terceiros durante homologações.

Ignorar limitações específicas da funcionalidade

Antes de considerar um fluxo como homologado, valide se:

• a funcionalidade possui suporte completo no Sandbox;
• existem limitações específicas documentadas;
• o comportamento esperado depende de recursos disponíveis apenas em produção.

Antes de ir para produção

Antes de migrar sua integração para produção, revise se:

• a URL da API foi alterada corretamente;
• a API Key utilizada é a de produção;
• os recursos necessários estão habilitados na conta real;
• o fluxo completo foi homologado;
• sua aplicação trata corretamente falhas e webhooks;
• as limitações do Sandbox foram consideradas.

❗️

Importante

O fato de um fluxo funcionar no Sandbox não garante automaticamente que todos os requisitos de produção estejam atendidos.

A validação final deve considerar:

• permissões da conta;
• validações regulatórias;
• recursos habilitados;
• comportamento real do ambiente produtivo.

Próximos passos

Depois de configurar sua conta Sandbox, recomendamos seguir esta ordem:

1. gerar sua API Key de Sandbox;
2. apontar sua integração para a URL de Sandbox;
3. criar um cliente fictício;
4. emitir uma cobrança de teste;
5. confirmar o pagamento para simular saldo;
6. testar os fluxos específicos da integração;
7. validar o recebimento de webhooks;
8. revisar limitações específicas do Sandbox;
9. trocar para produção apenas após a homologação completa.

Para suporte técnico relacionado à integração:

[email protected]