Sandbox e números mágicos

O sandbox é a forma mais rápida de integrar. Ele executa as mesmas validações e o mesmo fluxo assíncrono da produção, mas troca a Sefin Nacional por um simulador que responde sempre do mesmo jeito para a mesma entrada.

Como entrar no sandbox#

Use uma chave que começa com emt_test_. Não existe URL separada: a mesma URL base serve aos dois ambientes.

curl https://emitra.com.br/api/v1/integracao/me \
  -H "Authorization: Bearer emt_test_xxxxxxxx_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

O que muda no sandbox#

Tomadores e itens criados com chave de teste só existem no sandbox. Para produção, cadastre de novo com a chave emt_live_ ou pelo painel.

Números mágicos#

O resultado da emissão no sandbox depende dos centavos de servico.valor:

Exemplo de rejeição#

curl https://emitra.com.br/api/v1/integracao/nfse \
  -H "Authorization: Bearer $EMITRA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: teste-rejeicao-0001" \
  -d '{
    "tomador_id": "5f0c2a8e-1b7d-4c3e-9a51-2d6e8f4b7c10",
    "competencia": "2026-11-10",
    "servico": { "codigo_tributacao_nacional": "010601", "descricao": "Teste de rejeição", "valor": "1500.13" }
  }'

Depois de alguns segundos, GET /nfse/{id} devolve status: "rejected" e o objeto rejeicao preenchido, igual ao que acontece em produção. Use isso para testar a sua tela de erro e o tratamento do webhook nfse.rejected.

O que o sandbox não simula#

• Regras específicas de cada município (alíquota parametrizada, retenção obrigatória, inscrição municipal). Para isso, use a produção restrita com o certificado real. Veja Ambientes.
• Prazos reais de cancelamento e substituição.
• O conteúdo fiscal real do XML: o XML do sandbox é ilustrativo e não deve ser importado em sistema contábil.

Boas práticas#

• Rode a suíte de testes do seu sistema contra o sandbox no CI, com uma chave de teste exclusiva para isso.
• Gere Idempotency-Key únicas por teste para não receber respostas guardadas de execuções anteriores.
• Valide o seu receptor de webhook com o botão Testar do painel ou com POST /webhooks/{id}/testar.

Próximos passos#

• Idempotência
• Erros e rejeições da Sefin
• Rate limits