Ambiente de Testes (Sandbox)
O TapSign tem um ambiente de sandbox, separado da produção, para você desenvolver e testar sua integração sem mexer em dados reais.
URLs do Sandbox
| Recurso | URL |
|---|---|
| API Sandbox | https://sandbox-api.tapsign.com.br |
| Painel Sandbox | sandbox.tapsign.com.br |
| Swagger UI | sandbox-api.tapsign.com.br/swagger-ui/index.html |
| Scalar | sandbox-api.tapsign.com.br/scalar |
O sandbox existe para desenvolvimento e testes. Não envie documentos reais para assinatura nesse ambiente.
Diferenciando ambientes
As chaves de API começam com tsk_ nos dois ambientes. O que muda é a base URL e a conta: o sandbox tem banco de dados próprio, então contas, chaves e webhooks criados em um ambiente não existem no outro.
# Requisição no Sandbox
curl -X GET https://sandbox-api.tapsign.com.br/v1/envelopes \
-H "Authorization: Bearer {chave_do_sandbox}"
# Requisição em Produção
curl -X GET https://api.tapsign.com.br/v1/envelopes \
-H "Authorization: Bearer {chave_de_producao}"
Uma chave de produção usada no sandbox (ou o contrário) recebe 401. Guarde as chaves de cada ambiente separadamente.
Criando uma conta no Sandbox
- Acesse sandbox.tapsign.com.br e crie sua conta
- No painel, abra Integrações
- Na aba API Keys, clique em Nova API Key e copie a chave
A regra de plano é a mesma da produção: criar chave de API exige plano Equipe ou Enterprise na conta. Sem esse acesso a criação responde 402. Se precisar de acesso no sandbox para testar, escreva para [email protected].
O que muda em relação à produção
O sandbox roda o mesmo código da produção. As diferenças de configuração são:
| Item | Produção | Sandbox |
|---|---|---|
| Rate limit por chave de API | 60 requisições/min | 120 requisições/min |
POST /v1/auth/api/token | 5 requisições/min por IP | 10 requisições/min por IP |
POST /v1/auth/api/token-refresh | 10 requisições/min por IP | 20 requisições/min por IP |
| URL de webhook | Só https:// e host público | Também aceita http:// e endereços de rede privada |
Campo devMsg nas respostas de erro | Não aparece | Aparece, com o nome técnico do erro |
| Swagger UI e Scalar | Fechados | Abertos |
A validação aceita http:// e hosts privados, mas o endereço ainda precisa ser alcançável a partir do sandbox. Um localhost da sua máquina, por exemplo, não é.
Boas práticas
1. Teste no sandbox primeiro
Desenvolva e teste a integração no sandbox antes de ir para produção. Assim você evita erros com documentos reais.
2. Use variáveis de ambiente
Alterne entre sandbox e produção por variável de ambiente:
# .env.development
TAPSIGN_API_URL=https://sandbox-api.tapsign.com.br
TAPSIGN_API_KEY=tsk_...
# .env.production
TAPSIGN_API_URL=https://api.tapsign.com.br
TAPSIGN_API_KEY=tsk_...
3. Teste webhooks no sandbox
Registre seus webhooks no sandbox para validar que sua aplicação recebe, verifica a assinatura e processa todos os eventos antes de ativar em produção.
curl -X POST https://sandbox-api.tapsign.com.br/v1/webhooks \
-H "Authorization: Bearer {chave_do_sandbox}" \
-H "Content-Type: application/json" \
-d '{
"name": "Teste local",
"url": "https://seu-servidor.com/webhooks/tapsign",
"secret": "um-segredo-de-teste",
"events": ["doc_viewed", "doc_refused", "doc_completed", "doc_canceled"]
}'
4. Valide o fluxo completo
Antes de ir para produção, valide o ciclo completo:
- Enviar o arquivo e criar o envelope, ou criar a partir de um modelo
- Adicionar signatários
- Enviar para assinatura
- Receber o webhook
doc_completed - Baixar o PDF assinado pelo link
signed_file
Antes de migrar para produção, confirme que:
- Todos os endpoints que você usa estão funcionando no sandbox
- Os webhooks são recebidos, têm a assinatura validada e são processados de forma idempotente
- O tratamento de erros cobre 400, 401, 402, 404, 429 e 500
- Há retry com espera para 429 (respeitando
Retry-After) e para 5xx - As variáveis de ambiente estão separadas por ambiente
- A chave de produção foi criada na conta de produção e está guardada com segurança
Próxima seção: Autenticação: configure a autenticação da sua integração.