Como Testar sua Integração de Assinatura Digital: do Sandbox ao CI

Nas camadas certas, sim; em todas, não. A estratégia que funciona tem três andares: testes unitários mockam o SDK/cliente HTTP (rápidos, rodam a cada commit, validam a SUA lógica); testes de integração batem no sandbox real (api-hml.signdocs.com.br) e validam o contrato — payload aceito, resposta parseada, erros tratados; e um smoke test no pipeline valida o caminho crítico de ponta a ponta antes do deploy. Mockar tudo esconde drift de contrato; bater na API real em todo teste unitário deixa a suíte lenta e dependente de rede. O equilíbrio é mock embaixo, sandbox em cima.

Dois instrumentos. O primeiro é o endpoint de teste da API: POST /v1/webhooks/{webhookId}/test dispara um evento de teste ao seu endpoint registrado, assinado com HMAC de verdade — valida o caminho completo (recepção, verificação de assinatura, resposta) sem criar sessão nenhuma. O segundo é a suíte local: guarde payloads reais capturados no sandbox como fixtures e teste o handler como função pura — assinatura válida, assinatura inválida, timestamp velho (replay), evento duplicado (idempotência), evento de tipo desconhecido. O primeiro prova a tubulação; o segundo, a lógica.

Só se os testes dependerem de entidades antigas — e essa dependência é um mau cheiro de teste de qualquer forma. A regra prática: todo teste cria o que precisa (uma sessão nova custa uma chamada) e nenhum teste referencia IDs fixos de execuções passadas. O TTL vira até um aliado: o sandbox se limpa sozinho, sem rotina de teardown. Para os raros cenários que exigem estado antigo (por exemplo, testar seu tratamento de transação expirada), crie a sessão com expiresInMinutes curto e espere a expiração dentro do próprio teste.

Não use. O sandbox é ambiente de teste: use nomes, e-mails e CPFs fictícios (geradores de CPF válido para teste existem aos montes). Além da higiene LGPD óbvia — dado pessoal real não pertence a ambiente de desenvolvimento —, e-mails reais em teste disparam convites reais para caixas de entrada reais. Crie um domínio de e-mail de teste ou use endereços que você controla. A exceção honesta: no teste de aceitação final, com o time de negócio, use os dados do próprio testador — que sabe que está testando.

O caminho que, se quebrar, para o seu negócio — e só ele: (1) obter token OAuth2 (valida credenciais e conectividade); (2) criar uma sessão com um PDF mínimo e perfil CLICK_ONLY (valida o contrato de criação); (3) consultar GET /v1/transactions/{id} (valida leitura e parsing); (4) opcionalmente, disparar o webhook de teste e conferir que seu endpoint respondeu 200. Quatro chamadas, alguns segundos, roda a cada deploy. Use X-Idempotency-Key com o ID do build para que retries do pipeline não criem lixo duplicado. Testes de cenário completos ficam na suíte noturna, não no gate de deploy.

Quatro coisas, e é melhor saber antes: (1) biometria real — no sandbox os fluxos biométricos rodam em modo simulado por padrão; valide o fluxo end-to-end com biometria real na ativação da conta de produção; (2) retenção durável — o TTL de 7 dias significa que o sandbox nunca testa a guarda de longo prazo; (3) efeito jurídico — nenhuma assinatura de homologação vale como documento real, então o teste de aceitação jurídica é sempre um documento piloto em produção; (4) o seu volume real — cotas e comportamento sob carga se dimensionam no contrato de produção. O plano sob medida cobre esses quatro na transição.