Como testar funcionalidades em sandbox

O ambiente Sandbox permite validar a maior parte dos fluxos disponíveis na API antes da utilização em produção.

Embora o comportamento seja semelhante ao ambiente produtivo, algumas funcionalidades possuem mecanismos específicos de homologação para facilitar os testes. Em determinados cenários, é possível simular eventos, confirmar operações manualmente ou utilizar recursos disponíveis apenas no ambiente de Sandbox.

Por esse motivo, alguns fluxos exigem procedimentos diferentes dos utilizados em produção.

Quando utilizar

Esta seção é recomendada para desenvolvedores que desejam:

• validar integrações antes da implantação em produção;
• testar fluxos financeiros sem movimentar valores reais;
• homologar recebimento de webhooks;
• validar regras de negócio da aplicação;
• simular cenários específicos da plataforma;
• compreender comportamentos exclusivos do ambiente Sandbox.

Como funciona o processo de homologação

Em uma integração típica, o processo de testes costuma seguir a seguinte jornada:

Configurar conta Sandbox
        ↓
Criar recursos de teste
(clientes, cobranças, etc.)
        ↓
Executar operações
        ↓
Simular eventos
        ↓
Receber webhooks
        ↓
Validar comportamento da aplicação
        ↓
Homologar integração

Dependendo da funcionalidade testada, podem existir mecanismos específicos de simulação para permitir a reprodução do comportamento esperado sem necessidade de processamento financeiro real.

Diferenças em relação à produção

Embora o Sandbox reproduza grande parte dos comportamentos da plataforma, existem diferenças importantes que devem ser consideradas durante os testes:

• algumas operações podem ser simuladas manualmente;
• determinadas validações internas são simplificadas;
• alguns recursos dependem de configurações específicas do Sandbox;
• nem todas as integrações externas possuem comportamento idêntico ao ambiente produtivo;
• a disponibilidade de um recurso em Sandbox não garante sua habilitação em produção.

Por esse motivo, recomenda-se sempre validar os requisitos necessários antes da entrada em operação.

🚧

Importante

A homologação em Sandbox reduz riscos durante o desenvolvimento, mas não substitui as validações, habilitações comerciais e requisitos operacionais existentes no ambiente de produção.

Funcionalidades com fluxo de teste específico

As páginas abaixo apresentam instruções detalhadas para homologação dos principais recursos disponíveis no Sandbox:

• Como realizar transferências
• Como simular contas a pagar
• Como testar pagamento com cartão de crédito
• Como testar um pagamento via QR Code
• Como testar ações críticas
• Tentar pagar QR Code Pix no Sandbox sem chave cadastrada = erro 404
• Como gerar novas cobranças de uma assinatura

O que pode ser testado

Nem todas as funcionalidades da plataforma possuem cobertura completa no ambiente de Sandbox.

Antes de iniciar a homologação, consulte a página:

• O que pode ou não pode ser testado

Ela apresenta a lista atualizada dos recursos disponíveis para testes e suas respectivas limitações.

Testando chamadas diretamente na documentação

Além dos testes realizados pela sua aplicação, também é possível executar chamadas diretamente pela documentação da API utilizando credenciais de Sandbox.

Esse recurso é útil para:

• validar payloads;
• testar parâmetros;
• analisar respostas da API;
• reproduzir cenários rapidamente durante o desenvolvimento.

Consulte:

Como testar chamadas na documentação

Boas práticas

📘

Recomendado

• Realize os testes em Sandbox antes da utilização em produção.
• Valide tanto as respostas síncronas quanto os webhooks recebidos.
• Teste cenários de sucesso e de erro sempre que possível.
• Utilize dados fictícios durante a homologação.
• Consulte as páginas específicas de cada funcionalidade para entender comportamentos particulares do Sandbox.

Uma homologação completa reduz significativamente a necessidade de ajustes após a entrada em produção.