Ambientes

Operações fiscais têm comportamentos diferentes conforme o ambiente do autorizador. Antes de emitir, confirme se a empresa e o documento estão configurados para o ambiente correto.

Duas coisas têm ambiente, não uma

Esta é a origem mais comum de confusão na primeira integração:

1. A sua API Key é de produção ou de homologação — ela não alterna. É por isso que você recebe duas na criação da conta.
2. A configuração de cada empresa também tem ambiente (PUT /v1/empresas/{cpf_cnpj}/nfe, /nfce, /nfse).

E o que acontece quando as duas discordam depende do documento:

Documento	Onde fica a configuração	Se a chave e a configuração discordam
NF-e	uma configuração por empresa	403, com a mensagem dizendo qual é qual
NFC-e	uma configuração por empresa	403, igual à NF-e
NFS-e	uma configuração por ambiente	não há conflito: a chave escolhe qual configuração vale

A mensagem do 403 é literal:

Ambiente incompatível: sua API Key é de produção, mas o emitente está configurado para homologação. Use uma API Key de homologação ou altere a configuração do emitente.

O campo ambiente muda de tipo entre as rotas

Rota	Valor
PUT /v1/empresas/{cpf_cnpj}/nfe e /nfce	número: 1 produção, 2 homologação
PUT /v1/empresas/{cpf_cnpj}/nfse	texto: "producao" ou "homologacao"

É a divergência que mais causa erro na configuração inicial. Mandar 2 na rota de NFS-e não configura homologação — é valor inválido.

NFS-e: configurar produção não mexe em homologação

Como a configuração de NFS-e é por ambiente, cada um tem a sua própria numeração de RPS e as suas próprias credenciais de prefeitura. Configurar um não altera o outro — e emitir com a chave de produção usa a configuração de produção, sempre.

Homologação

Use homologação durante todo o desenvolvimento.

Documentos emitidos em homologação não têm valor fiscal e não devem ser tratados como documentos válidos da operação real da empresa.

Produção

Produção é o ambiente de documentos com efeito fiscal real. Uma nota autorizada aqui produz consequências tributárias.

Antes de migrar:

• valide autenticação;
• valide o cadastro do emitente;
• confira o certificado e a validade;
• teste o fluxo de consulta após a emissão;
• implemente tratamento de rejeições;
• implemente proteção contra emissões duplicadas (ver referência externa);
• confirme numeração e série.

Numeração não se mistura entre ambientes

Cada ambiente tem a própria sequência. O último número autorizado em homologação não diz nada sobre produção. GET /v1/empresas/numeracao devolve as duas separadas justamente por isso.

Atenção à NFS-e

A disponibilidade de homologação depende do município ou provedor. Nem todo ambiente municipal reproduz o comportamento da produção, e alguns simplesmente não oferecem ambiente de teste.

Consulte NFS-e antes de assumir que um município possui ambiente de homologação.