Ambiente de Homologação (Sandbox) para Testar a API de Assinatura

Nenhuma integração de assinatura digital deveria estrear direto em produção. O ambiente de homologação (HML) — também chamado de sandbox — é onde você valida autenticação, criação de transações, métodos de assinatura e webhooks sem gerar assinaturas com validade jurídica, sem consumir quota real e sem risco de afetar contratos de clientes. Este guia mostra, na prática, como testar a API de assinatura SignDocs em homologação antes de subir para produção com segurança.

Vamos cobrir o host correto do sandbox (api-hml.signdocs.com.br, na forma com hífen), o que muda entre HML e produção, o TTL de 7 dias que apaga as entidades de teste, a biometria simulada em homologação, o uso de credenciais separadas, como testar webhooks com túneis ou webhook.site (e por que IPs privados são bloqueados), e um checklist completo de promoção HML para PROD.

Se você ainda não emitiu suas chaves, comece por como obter sua API key de assinatura e pelos primeiros passos da API em 5 minutos. Para o panorama completo da plataforma, consulte o guia-pilar sobre a API de assinatura digital.

O que é o ambiente de homologação (sandbox)

O ambiente de homologação é uma réplica funcional da API de produção, isolada e segura, criada especificamente para testes. Ele expõe os mesmos endpoints, o mesmo modelo de dados e o mesmo formato de resposta da produção, mas opera sobre uma infraestrutura separada, com credenciais próprias e regras pensadas para o ciclo de desenvolvimento.

Na prática, o sandbox permite que sua equipe:

• Valide o fluxo de autenticação OAuth2 client-credentials e a renovação de tokens;
• Crie sessões de assinatura e envelopes de teste sem custo e sem validade jurídica real;
• Exercite cada método de autenticação de signatário (clickwrap, OTP, biometria, certificado ICP-Brasil);
• Receba e verifique webhooks de ponta a ponta;
• Rode testes automatizados de integração em CI/CD sem tocar em dados de clientes;
• Reproduza cenários de erro e valide o tratamento de falhas da sua aplicação.

O princípio central é simples: tudo que acontece em homologação fica em homologação. Documentos assinados no sandbox não têm valor probatório, não aparecem em produção e são descartados automaticamente após o período de retenção de teste.

O host correto: api-hml.signdocs.com.br (com hífen)

O primeiro detalhe — e a fonte mais comum de frustração na primeira integração — é a base URL do sandbox. O host de homologação da SignDocs é:

A produção, por sua vez, usa o host raiz api.signdocs.com.br. A regra de ouro é manter as duas URLs em configuração, selecionadas por estágio:

Com esse padrão, promover a integração para produção é apenas trocar o arquivo de ambiente — sem nenhuma alteração de código. Isso é exatamente o que recomendamos no guia de como obter e gerenciar suas credenciais da API.

O que muda (e o que não muda) entre HML e produção

A maior virtude de um bom sandbox é a paridade: quanto mais parecido com a produção, mais confiança o teste gera. Ainda assim, algumas diferenças deliberadas existem. A tabela abaixo resume o que esperar.

Como os endpoints e payloads são idênticos, qualquer código que funcione contra o sandbox funcionará contra a produção. As diferenças concentram-se em retenção, validade jurídica, biometria e cobrança — nenhuma delas exige alteração no seu cliente, apenas consciência ao planejar os testes.

O TTL de 7 dias: planeje seus testes para isso

Esta é a diferença que mais surpreende quem chega ao sandbox vindo de outros provedores. No ambiente de homologação da SignDocs, as principais entidades — envelopes, transações e o pacote de evidência (evidence pack .p7m) — têm um TTL (time to live) de 7 dias. Passado esse prazo, elas expiram e são removidas automaticamente.

Isso é intencional e saudável: mantém o sandbox enxuto, evita acúmulo de lixo de teste e protege a privacidade de qualquer dado que você tenha colocado lá. Mas tem implicações diretas sobre como você organiza seus testes.

O que o TTL significa na prática

• Não construa testes que dependam de dados antigos. Um ID de transação criado há mais de uma semana muito provavelmente já não existe. Testes idempotentes e auto-suficientes, que criam o que precisam a cada execução, são a abordagem correta.
• Não use HML como repositório. Se precisa guardar um documento assinado ou um pacote de evidência de teste para referência futura, faça o download e armazene fora do sandbox.
• O verificador público não é confiável para HML. Como as entidades expiram, uma consulta de verificação semanas depois pode não encontrar a transação. Em produção isso não acontece: ENVELOPE, TRANSACTION e EVIDENCE são persistidos de forma durável justamente porque a verificação pública depende dessa consulta de longo prazo.
• Suites de regressão devem recriar o estado. Em CI/CD, faça cada job de teste construir seu próprio envelope/transação e limpar ao final, em vez de assumir dados pré-existentes.

Biometria e assinatura simuladas em homologação

Testar fluxos que exigem biometria facial real seria inviável em automação: você não pode pedir a um pipeline de CI que faça uma prova de vida diante da câmera. Por isso, no sandbox, os métodos BIOMETRIC_LIVENESS (prova de vida) e BIOMETRIC_MATCH (correspondência facial) rodam em modo simulado por padrão para contas self-serve de homologação.

Na prática, isso significa que você consegue exercitar toda a jornada — criação da sessão, avanço pelos passos de assinatura, callback de webhook e geração de evidência — sem uma captura facial verdadeira. A aprovação biométrica em HML é tratada como determinística, o que torna os testes reprodutíveis.

Os demais métodos de autenticação multimétodo também são totalmente testáveis no sandbox:

• CLICK_ACCEPT (clickwrap): aceite por clique, o caminho mais simples para um teste de fumaça;
• OTP_CHALLENGE (código por SMS/e-mail): útil para variar resultados de sucesso e falha;
• BIOMETRIC_LIVENESS / BIOMETRIC_MATCH: simulados, como descrito acima;
• DIGITAL_SIGN_A1 (certificado ICP-Brasil): assinatura com certificado, lembrando que DIGITAL_CERTIFICATE é o valor de profile da política, enquanto DIGITAL_SIGN_A1 aparece apenas como step.type na resposta.

Para entender como esses métodos se combinam em perfis (por exemplo, biometria + OTP), veja a seção de métodos de autenticação em o que é uma API de assinatura digital. Quando precisar de validação biométrica com captura real em homologação, isso é provisionado pela equipe da SignDocs — normalmente no momento em que sua conta recebe quota para o método — em vez de estar disponível por padrão nas contas self-serve.

Credenciais separadas: nunca misture HML e PROD

As credenciais OAuth2 de homologação são distintas e isoladas das de produção. Um client_id/client_secret de HML só emite tokens válidos contra o host de HML, e um token de HML não autentica chamadas em produção (e vice-versa). Essa separação é uma barreira de segurança: impede que um teste, por engano, dispare uma assinatura real.

O fluxo de obtenção de token é idêntico em ambos os estágios — apenas a base URL e o segredo mudam:

Boas práticas de gestão de credenciais para sandbox e produção:

1. Secrets distintos por estágio. Guarde HML e PROD em entradas separadas do seu cofre de segredos (AWS Secrets Manager, Vault, GitHub Secrets), nunca no código.
2. Seleção por variável de ambiente. Uma única flag (STAGE=hml ou STAGE=prod) decide quais credenciais e qual base URL carregar.
3. Rotação independente. Rotacione o segredo de produção sem afetar os testes, e vice-versa.
4. Princípio do menor privilégio. As credenciais de teste em CI/CD devem ser somente de HML, jamais de produção.

Detalhes do fluxo de token, expiração (15 minutos) e assinatura JWT (ECDSA ES256) estão no guia de autenticação OAuth2 da API de assinatura.

Testando webhooks em homologação: túneis e webhook.site

Webhooks são notoriamente difíceis de testar porque exigem que a API alcance um endpoint seu pela internet. Em desenvolvimento local, sua aplicação roda em localhost — invisível para o mundo externo. O sandbox foi feito para esse cenário, mas há uma regra de segurança importante.

IPs privados e localhost são bloqueados pelo WAF

Ao cadastrar uma URL de webhook que aponta para localhost, 127.0.0.1 ou para um IP de rede privada (faixas 10.x, 192.168.x, 172.16-31.x), uma regra de WAF bloqueia o registro e a chamada retorna 403 do CloudFront. Isso evita ataques de SSRF e tentativas de fazer a infraestrutura chamar endereços internos. Logo, você não pode simplesmente apontar o webhook de HML para a sua máquina.

Opção 1: túnel (ngrok, Cloudflare Tunnel)

A solução padrão é expor seu endpoint local por meio de um túnel, que fornece uma URL pública HTTPS encaminhando para o seu localhost:

Opção 2: coletor público (webhook.site)

Se você só quer inspecionar os payloads e headers antes de escrever o receptor, um coletor como webhook.site oferece uma URL pública descartável que captura cada POST recebido. É ideal para descobrir o formato exato do evento e o header de assinatura HMAC antes de implementar a verificação real.

Lembre-se de que a verificação HMAC-SHA256 dos webhooks é idêntica em HML e em produção — apenas o segredo do webhook é diferente por ambiente. Validar a verificação no sandbox garante que ela funcionará sem ajustes em produção.

Um teste de ponta a ponta no sandbox

Para amarrar tudo, eis a sequência mínima de um teste de fumaça completo em homologação, do token à evidência. Cada passo usa o host api-hml.signdocs.com.br e as credenciais de HML.

1. Autenticar: obter um access_token via OAuth2 client-credentials no endpoint de token de HML.
2. Criar a sessão de assinatura: chamar POST /v1/signing-sessions com um documento de teste e um signatário. Esse é o caminho da Assinatura Expressa — uma chamada gera o checkout hospedado ou o widget incorporado.
3. Cadastrar o webhook: registrar a URL pública do túnel para os eventos SIGNING_SESSION.COMPLETED e TRANSACTION.COMPLETED.
4. Concluir a assinatura: abrir o link retornado e completar o método de autenticação (clickwrap para o caminho mais rápido; biometria simulada se quiser exercitar esse fluxo).
5. Receber e verificar o webhook: confirmar que o evento chegou ao seu receptor, validar a assinatura HMAC e aplicar a idempotência.
6. Baixar o resultado: obter o documento assinado e o pacote de evidência .p7m — e armazená-los fora do sandbox, lembrando do TTL de 7 dias.

Esse fluxo exercita exatamente o mesmo caminho do quickstart de primeiros passos em 5 minutos que rodará em produção. Se ele passa em HML, você tem alta confiança de que passará em PROD.

Checklist de promoção: de homologação para produção

Antes de virar a chave para produção, percorra esta lista. Ela separa o que se valida no sandbox do que se confere especificamente ao migrar.

Validado em homologação

• Fluxo OAuth2 emitindo e renovando tokens sem erro;
• Criação de sessão de assinatura e/ou envelope com sucesso;
• Ao menos um signatário concluindo cada método de autenticação que você usa;
• Webhooks entregues, com verificação HMAC-SHA256 e idempotência funcionando;
• Tratamento de erros, timeouts e retries exercitado;
• Download do documento assinado e do pacote de evidência .p7m;
• Testes automatizados de integração verdes em CI/CD.

Conferir ao migrar para produção

O ideal é que a promoção seja, do ponto de vista de código, um no-op: apenas variáveis de ambiente mudam. Quanto mais fiel foi o teste em homologação, menor a chance de surpresas em produção.