Ambiente de testes

O sandbox é uma cópia da API com os mesmos endpoints, os mesmos códigos de erro e as mesmas validações, e sem nenhuma consequência: nada é cobrado, nada tem valor jurídico e nenhum e-mail chega a quem não deveria. É onde a sua integração deve nascer, e é onde ela deve continuar sendo testada depois de estar em produção.

Começar

Duas mudanças em relação a produção, e nenhuma outra:

# Sandbox
ADM_BASE=https://api.adigitalmax.com.br/v1/sandbox
ADM_CHAVE=adx_test_3a5e1c92f704...

# Producao
# ADM_BASE=https://api.adigitalmax.com.br/v1
# ADM_CHAVE=adx_live_9f2c7d41b8e6...

A chave de sandbox sai do mesmo lugar da de produção, em Configurações → API → Chaves, escolhendo ambiente SANDBOX. O prefixo adx_test_ deixa isso visível em qualquer log, o que é útil quando alguém pergunta se aquele documento estranho de ontem era teste.

O que muda em relação à produção

Gatilhos de simulação

O problema de testar assinatura eletrônica é que o caminho feliz depende de uma pessoa clicar em um link, e os caminhos infelizes dependem de esperar dias. Os gatilhos resolvem isso: o endereço de e-mail do signatário determina o que ele vai fazer, e a plataforma age sozinha em segundos.

Além dos e-mails, dois campos aceleram o relógio:

#!/usr/bin/env bash
# Envia, espera concluir e baixa. O ciclo inteiro em menos de um minuto,
# sem ninguem precisar clicar em nada.

set -euo pipefail

ADM_CHAVE="${ADM_CHAVE:?use uma chave adx_test_}"
ADM_BASE="https://api.adigitalmax.com.br/v1/sandbox"
AUTH=(--header "Authorization: Bearer $ADM_CHAVE")

DADOS='{
  "titulo": "Contrato de teste - ciclo completo",
  "nivelAssinatura": "SEGURA",
  "fatoresExigidos": ["EMAIL", "SMS_OTP"],
  "signatarios": [
    {
      "nome": "Robo Que Assina",
      "email": "assina@teste.adigitalmax.com.br",
      "telefone": "+5511900000000",
      "funcao": "ASSINAR",
      "metodoEntrega": "EMAIL",
      "ordem": 1
    }
  ],
  "campos": [
    { "tipo": "ASSINATURA", "pagina": 1, "x": 0.10, "y": 0.75, "largura": 0.34, "altura": 0.07 }
  ]
}'

# 1. Criar. Nasce em RASCUNHO; nada e disparado.
DOC=$(curl --fail-with-body --silent --show-error "${AUTH[@]}" \
  --request POST "$ADM_BASE/documentos" \
  --form "dados=$DADOS;type=application/json" \
  --form "arquivo=@./contrato.pdf;type=application/pdf")

DOC_ID=$(echo "$DOC" | jq -r '.id')

# 2. Enviar, que e sempre uma chamada separada.
curl --fail-with-body --silent --show-error "${AUTH[@]}" \
  --request POST "$ADM_BASE/documentos/$DOC_ID/enviar" > /dev/null

echo "Documento $DOC_ID enviado. Aguardando o robo assinar..."

# O robo assina em ~5s. Consultamos a cada 3s, no maximo 10 vezes,
# que e sondagem aceitavel em teste e inaceitavel em producao.
for _ in $(seq 1 10); do
  sleep 3
  STATUS=$(curl --silent "${AUTH[@]}" "$ADM_BASE/documentos/$DOC_ID" | jq -r '.status')
  echo "  status: $STATUS"
  [ "$STATUS" = "ASSINADO" ] && break
done

[ "$STATUS" = "ASSINADO" ] || { echo "Nao concluiu a tempo."; exit 1; }

curl --silent "${AUTH[@]}" "$ADM_BASE/documentos/$DOC_ID/certificado" \
  | jq '{codigo, versao, hashDocumento}'

curl --location --fail-with-body --silent "${AUTH[@]}" \
  --output "teste-assinado.pdf" \
  "$ADM_BASE/documentos/$DOC_ID/arquivo?tipo=ASSINADO"

echo "Gravado teste-assinado.pdf (com marca d'agua de ambiente de testes)."

Dados de exemplo

Toda organização nasce, no sandbox, com um acervo pronto para você não precisar construir nada antes de ler. Os identificadores abaixo são estáveis por organização e aparecem no painel, em ambiente de sandbox.

Um PDF de teste com sete páginas, marcadores de variável e espaço reservado para assinatura no rodapé da última página está em contrato-exemplo.pdf, disponível no painel do sandbox. As coordenadas usadas nos guias foram calculadas para ele. >>> PENDENTE DE BACKEND <<<

Roteiro de aceitação

Antes de considerar a integração pronta, exerça os doze casos abaixo no sandbox. Os quatro primeiros são o caminho feliz e todo mundo faz; os oito seguintes são os que produzem chamado de suporte às sextas-feiras.

Antes de ir para produção

1. Troque a chave e a URL base por variável de ambiente, se ainda não estiverem. Nenhuma das duas deve aparecer escrita no código.
2. Cadastre o webhook de produção, com segredo próprio. Ele é separado do de sandbox e não herda nada.
3. Confirme que você valida a assinatura HMAC com o segredo do ambiente certo. Segredo de sandbox contra evento de produção falha em toda entrega, e o sintoma é um webhook silenciosamente desativado depois de 72 horas.
4. Use um endpoint de webhook por ambiente, com segredos diferentes. É a última defesa contra um evento de teste virar pedido real: o receptor de produção simplesmente não valida a assinatura de um evento de sandbox.
5. Verifique os endereços de e-mail dos remetentes no painel, em Configurações. Em produção o e-mail sai de verdade e a entregabilidade depende disso.
6. Revise os escopos da chave de produção. É comum a de sandbox ter sido criada com tudo marcado, para não travar o desenvolvimento; a de produção deve ter o mínimo.
7. Guarde o primeiro documento de produção e confira o PDF, o certificado e a validação pública com olho humano, antes de abrir o volume. Marca d'água esquecida, campo fora de lugar e nome de remetente errado só aparecem olhando.