Skip to main content
A SEFAZ de homologação recebe as emissões de teste do emissor, sem validade fiscal, e o próprio parceiro promove o emissor para produção. O modo teste (provedor simulado, sem transmissão à SEFAZ) é uma parada que o administrador da plataforma liga no emissor.
Esta é a versão completa (como funciona, como promover um emissor pra produção, self-service). Pra ver só o que muda entre os dois ambientes numa tabela, veja Homologação vs produção.
O endpoint da API é o mesmo para homologação e produção. A diferença está no campo ambienteFiscal do emissor. O parceiro promove o emissor para produção sozinho; o modo teste (provedor simulado) é uma parada que o administrador da plataforma liga e que revoga essa liberação.

Todo emissor nasce em homologação, fora do modo teste

Ao cadastrar uma empresa (POST /v1/companies), o emissor nasce com ambienteFiscal no valor 2 {/* fact:issuer.ambienteFiscalDefault */} (homologação) e com sandbox=false: a emissão de teste acontece direto na SEFAZ de homologação, sem validade fiscal, sem passar pelo provedor simulado. O payload de cadastro não tem um campo environment (nem ambienteFiscal, nem sandbox) que você possa enviar:
ambienteFiscal e sandbox não mudam pelo PATCH /v1/companies/{id} genérico. Enviar um valor diferente do atual recusa com 422 AMBIENTE_IMUTAVEL (nada é escrito). Reenviar o valor atual (o roundtrip do GET) continua 200 e é ignorado.O parceiro pode voltar para ambienteFiscal=2 pelo endpoint dedicado (PATCH /v1/companies/{id}/ambiente). O valor 1 exige a liberação de produção do emissor, presente desde o cadastro novo e revogada quando o administrador liga o modo teste. Para sair do modo teste e usar a SEFAZ de homologação, o OWNER ou ADMIN usa POST /v1/companies/{id}/promover-homologacao, conforme a seção abaixo.
Notas emitidas em homologação não têm validade fiscal e não precisam ser canceladas. Emita à vontade para testar.

Sair do modo teste e usar a SEFAZ de homologação

No modo teste, o emissor emite com o provedor simulado, sem transmitir à SEFAZ; o modo é uma parada que o administrador da plataforma liga. sandbox=false habilita o provedor real; ambienteFiscal=2 continua selecionando a SEFAZ de homologação, sem validade fiscal. O OWNER ou ADMIN do parceiro dono do emissor pode promover o próprio emissor:
O corpo aceita apenas sandbox booleano, obrigatório. Campos extras, inclusive ambienteFiscal, recebem 400. A chave de API sozinha não autoriza a troca: use o JWT de sessão do dono ou admin. A assinatura precisa permitir escrita. Pré-condições para a promoção: e-mail do dono verificado, certificado A1 presente, não vencido e com a mesma raiz de CNPJ do emissor, IE válida, logradouro, bairro, município, UF, CEP e código IBGE preenchidos. Uma recusa não altera o emissor: Resposta 200:
Para voltar ao mock, envie {"sandbox":true} à mesma rota. O retorno ao mock dispensa certificado e cadastro completo. Cada mudança é auditada com usuário e valor anterior/novo. Repetir o estado atual retorna 200 sem nova auditoria. Esta rota não altera ambienteFiscal nem promove à produção. Depois da promoção, a chave ek_test_ continua válida para emitir no ambiente 2.

CNPJ para Testes

Você pode usar seu próprio CNPJ em homologação. O SEFAZ de teste aceita qualquer CNPJ válido (com dígitos verificadores corretos). CNPJs de teste comuns:
Esses CNPJs são fictícios com dígitos verificadores válidos, conferidos contra o algoritmo oficial de cálculo de DV. Podem ser usados livremente em homologação.
CNPJ com dígito verificador inconsistente com os 12 primeiros dígitos é rejeitado pela SEFAZ de homologação com cStat 208 (“CNPJ do emitente inválido”). Use sempre os CNPJs acima ou gere um novo com DV calculado corretamente antes de testar.

Certificado para Homologação

Em homologação, você pode usar:
  • Seu certificado real (funciona normalmente)
  • Certificado de testes (emitido por qualquer AC, mesmo que expirado)
O SEFAZ de homologação aceita certificados com qualquer validade. O upload segue o mesmo contrato de produção: POST /v1/companies/{id}/certificate, campo multipart file, ver Certificados Digitais.

Promovendo um emissor para produção

A produção vem liberada desde o cadastro. Depois de validar a integração em homologação, o próprio parceiro alterna entre 1 e 2 por PATCH /v1/companies/{id}/ambiente. Emitir em produção exige ek_live_, cuja geração exige assinatura ACTIVE em plano pago. Se o administrador colocou o emissor em modo teste, a liberação foi revogada. Nesse caso, depois de sair do mock pelo próprio parceiro, solicitar o ambiente 1 recebe 422 PRODUCAO_NAO_LIBERADA até nova liberação administrativa. A recusa não altera o ambiente nem grava auditoria. No mock (sandbox=true), a troca de ambiente continua permitida, mas sair do mock no ambiente 1 também exige a liberação. Promover ou voltar ao mock pelo parceiro preserva a liberação; somente o administrador da plataforma pode concedê-la ou revogá-la. O parceiro continua podendo enviar {"ambienteFiscal":2} para voltar à homologação. A rota aceita somente os números 1 ou 2; outro valor recebe 400. Emissor de outro parceiro recebe 404. Mudanças permitidas são auditadas na mesma transação e a resposta inclui prontoPara atualizado, sem segredos. Em produção, a ek_test_ não opera o emissor. Use uma ek_live_ de plano ativo, conforme Autenticação.

Testando Rejeições

Para testar o tratamento de erros no seu código, você pode provocar rejeições específicas (todas voltam como 400 com error.erros[], nunca 422, ver Erros e Rejeições):

Comparação: Homologação vs Produção

O DANFE em homologação

GET /v1/nfe/pdf/{accessKey} e GET /v1/nfce/pdf/{accessKey} funcionam normalmente em homologação: o documento é gerado a partir do XML autorizado pela SEFAZ de homologação, e a própria SEFAZ manda imprimir a tarja NF-E EMITIDA EM AMBIENTE DE HOMOLOGACAO - SEM VALOR FISCAL. Ambiente, CST/CSOSN e informações complementares saem do XML: o PDF é o documento, não uma remontagem. A resposta só é 409 (DANFE_INDISPONIVEL) quando não existe XML autorizado para aquele documento neste ambiente:
Emissor de demonstração (criado pelos seeds de demo da plataforma, não por você): o download de PDF funciona mesmo sem uma emissão real na SEFAZ de homologação. Você recebe um DANFE de teste com os itens/CSOSN/informações complementares do SEU payload, e o que é sintético vem declarado dentro do próprio documento: o protocolo (nProt) usa o prefixo DEMO (nunca um número puro: protocolo real da SEFAZ é só dígitos, então não colide com nenhuma faixa real) e o infCpl/xMotivo dizem literalmente “AMBIENTE DE DEMONSTRAÇÃO, documento sintético, sem validade fiscal”. O 409 não aparece nesse caso.
No modo teste (sandbox=true), ligado pelo administrador da plataforma em PATCH /v1/admin/companies/{id}/sandbox, a emissão usa o provedor simulado (protocolo DEMO…) mesmo com certificado A1 válido, e a liberação de produção é revogada. Para usar a SEFAZ de homologação, o OWNER ou ADMIN do parceiro promove o emissor em POST /v1/companies/{id}/promover-homologacao, depois do upload do certificado.

Checklist: Estou pronto para produção?

1

Emissão testada

Sua integração emite NF-e com sucesso em homologação e recebe status: "AUTHORIZED"?
2

Erros tratados

Seu código trata 400 (rejeição SEFAZ, error.erros[]) e exibe mensagem amigável ao usuário?
3

Webhooks configurados

Você tem um endpoint recebendo invoice.authorized e invoice.rejected (PATCH /v1/webhooks/config)?
4

Idempotência implementada

Seu código usa o header Idempotency-Key na emissão e o id do evento no webhook para evitar duplicidade?
5

Certificado de produção

Você tem um certificado e-CNPJ A1 válido e fez o upload (POST /v1/companies/{id}/certificate)?
6

Ambiente de produção liberado

Você gerou a própria ek_live_? Emissor que passou pelo modo teste do administrador só produz depois de nova liberação.

Veja também