Comece aquiAmbientes e sandbox

Ambientes e sandbox

A API tem dois ambientes isolados. No sandbox você desenvolve e testa sem valor fiscal. Em produção, cada nota autorizada é um documento de verdade. Cada ambiente tem a própria URL base e as próprias chaves.

Os dois ambientes

  • URL base
    Sandbox
    sandbox.api.emissordenota.com/v1
    Produção
    api.emissordenota.com/v1
  • Prefixo da chave
    Sandbox
    edn_test_
    Produção
    edn_live_
  • Valor fiscal
    Sandbox
    Nenhum. A nota não é transmitida.
    Produção
    Total. A nota é transmitida e autorizada.
  • Certificado digital
    Sandbox
    Dispensado
    Produção
    Certificado A1 válido da empresa emissora
  • Webhooks
    Sandbox
    Enviados aos endpoints cadastrados no sandbox
    Produção
    Enviados aos endpoints cadastrados em produção
  • Limites
    Sandbox
    120 requisições por minuto, sem consumir a franquia mensal
    Produção
    120 requisições por minuto e 100.000 por mês

Nada passa de um ambiente para o outro. Empresas, clientes, notas e endpoints de webhook criados no sandbox ficam no sandbox, e uma chave edn_test_ recebe 401 se for usada na URL de produção.

Como o sandbox se comporta

O sandbox responde com os mesmos formatos, códigos de erro e eventos da produção. A diferença é que a transmissão é simulada: nada é enviado à prefeitura nem ao Emissor Nacional.

  • As notas recebem número, chave de acesso, XML e PDF de exemplo, marcados como SEM VALOR FISCAL.
  • A autorização leva alguns segundos, para você exercitar o fluxo assíncrono e os webhooks como em produção.
  • As guias do Simples são fictícias e não podem ser pagas.

Empresa de teste

Toda conta já tem uma empresa pronta no sandbox, com o id emp_teste_01. Ela está no Simples Nacional, tem certificado simulado e pode emitir sem nenhum cadastro prévio.

Emitindo com a empresa de teste
curl -X POST https://sandbox.api.emissordenota.com/v1/nfse \  -H "Authorization: Bearer $EDN_TEST_KEY" \  -H "Content-Type: application/json" \  -d '{    "empresa_id": "emp_teste_01",    "data_competencia": "2026-11-09",    "tomador": { "documento": "98765432000198", "nome": "Clínica Bem Viver Ltda" },    "servico": {      "codigo_tributacao_nacional": "010701",      "descricao": "Suporte técnico em informática",      "valor": 1500.00    }  }'

Simulando cenários

Para testar os caminhos de erro sem depender de uma prefeitura real, use os valores abaixo em servico.valor. Qualquer outro valor resulta em nota autorizada.

ValorResultadoO que acontece

  • 0.01Nota rejeitada
    A nota vai para o status rejeitada e o evento nfse.rejeitada é enviado, com um motivo de exemplo.
  • 0.02Autorização lenta
    A nota fica em processando por 2 minutos antes de ser autorizada. Serve para testar a espera pelo webhook.
  • 0.03Prefeitura fora do ar
    A API responde 503. Serve para testar as suas novas tentativas com Idempotency-Key.
Resposta com servico.valor igual a 0.01
{  "id": "nfse_7Qd1bRm5Ke",  "status": "rejeitada",  "ambiente": "sandbox",  "motivos": [    {      "campo": "servico.codigo_tributacao_nacional",      "mensagem": "Código de tributação não aceito no município do prestador."    }  ]}

Indo para produção

O código não muda entre os ambientes. O que muda é a configuração:

  • Troque a URL base para https://api.emissordenota.com/v1.
  • Gere uma chave edn_live_ em Configurações › API e integrações e guarde no cofre de segredos do seu sistema.
  • Confira se cada empresa emissora tem certificado A1 válido e cadastro completo no painel.
  • Cadastre o endpoint de webhook de produção e salve o novo segredo whsec_, que é diferente do usado no sandbox.

Em produção a nota tem valor fiscal

Uma nota autorizada por engano só é desfeita com cancelamento, dentro do prazo da prefeitura. Faça a primeira emissão de cada empresa com um valor real e conferido.