Ir para produção e boas práticas#

Checklist de entrada em produção#

Antes de ligar uma empresa em produção (as notas passam a ter valor fiscal):

Cadastro

• A empresa está cadastrada com os dados reais: razão social, CNPJ, inscrição estadual habilitada na SEFAZ, endereço completo e o regime tributário verdadeiro (ele decide como o ICMS é calculado).
• O certificado A1 e-CNPJ ICP-Brasil está instalado e dentro da validade (GET /empresas/{cnpj}/certificado).
• O CNPJ da empresa está credenciado para emitir NF-e na SEFAZ da UF.

Testes em homologação (cada um com nota real na SEFAZ de homologação)

• emissão de cada tipo de venda que o seu ERP faz: consumidor final, empresa contribuinte, interestadual, com frete e desconto, cada forma de pagamento (inclusive cartão e marketplace, se usa);
• rejeição e reenvio: provoque uma rejeição (um dado errado) e confirme que o seu sistema reenvia na mesma ref;
• repetição por falha de rede: reenvie o mesmo POST e confirme que nenhuma nota nova nasce;
• cancelamento, carta de correção e inutilização;
• webhooks: recebimento, conferência da assinatura (com o vetor de teste de Webhooks), resposta rápida e idempotência por id;
• download e guarda do XML autorizado e do DANFE no seu sistema.

Fiscal

• O contador da empresa revisou os tributos que saem nas notas de homologação: a SEFAZ de homologação valida o leiaute e as regras de preenchimento, mas não confere se o ICMS é o devido.
• Os produtos têm NCM e origem corretos (importados mudam a alíquota interestadual) e GTIN válido, ou nenhum.

Troca

• PUT /empresas/{cnpj}/ambiente com {"ambiente": "producao"} (devolve o que ainda impede, se algo impedir).
• A primeira nota de produção é acompanhada de perto: emita uma venda real, confira a chave_nfe na consulta pública da SEFAZ e o DANFE.

Pode reaproveitar as mesmas ref que usou em homologação: as notas de produção começam do zero e a numeração é separada.

Tentativas e erros de rede#

A regra de ouro: no POST /nfe, repetir é sempre seguro, porque a ref é idempotente. Falhou? Repita com a mesma ref e o mesmo corpo.

Use espera exponencial com variação aleatória (jitter), com um teto de tentativas. Por exemplo: 1 s, 2 s, 4 s, 8 s, 16 s (cada uma ± 20%), parando depois de 5 a 8 tentativas e alertando uma pessoa. Respeite Retry-After quando houver.

espera = min(60, 2^tentativa) segundos × (0,8 a 1,2 aleatório)

Acompanhar a nota#

Recomendação: use webhooks para reagir e uma reconciliação periódica como rede de segurança.

• Webhook: processe o evento, responda 2xx rápido, e seja idempotente (deduplique por id).
• Polling (se não puder receber webhooks): consulte GET /nfe/{ref} a cada 2 segundos nos primeiros 30 segundos, depois a cada 10, depois a cada minuto, até um estado final. Nunca consulte em laço sem espera: você bate no limite de requisições.
• Reconciliação: um trabalho seu (a cada 5 a 15 minutos) que consulta as notas que o seu sistema ainda considera pendentes e as notas dos últimos dias. Cobre o webhook que não chegou e o seu servidor que estava fora do ar.

Uma nota pode ficar em processando_autorizacao por minutos ou até algumas horas se a SEFAZ da UF estiver instável: a plataforma tenta de novo sozinha por até 6 horas e consulta a chave antes de reenviar, então nunca duplica. Não reenvie a venda com ref nova, e não bloqueie a operação do cliente esperando a SEFAZ: trate a nota como "em processamento" e siga.

Guarde os documentos fiscais#

• XML autorizado: guarde no seu sistema assim que o nfe.autorizada chegar (ou o status virar autorizado). A obrigação de guarda é de 5 anos. Depois do cancelamento, o XML autorizado continua disponível na API, e o XML do evento de cancelamento vem em eventos[].caminho_xml: guarde os dois.
• DANFE: pode ser gerado de novo a qualquer momento enquanto a nota vale; guarde se precisar enviar ao cliente.
• A chave de acesso (chave_nfe) identifica a nota na consulta pública da SEFAZ. Guarde junto do pedido.

Chaves de API#

• Uma chave por ambiente de implantação (produção, homologação) e por sistema, para revogar uma sem afetar as outras.
• Rotação sem parada: (1) peça uma chave nova; (2) coloque-a no seu sistema e faça o deploy; (3) confirme pelo GET /requisicoes que a chave antiga parou de ser usada (campo chave, o prefixo); (4) peça a revogação da antiga.
• Guarde em cofre de segredos ou variável de ambiente. Nunca em repositório, no front-end ou em logs.
• Suspeita de vazamento? Revogue na hora: o efeito é imediato.

Monitoramento#

• Registre o X-Request-Id de cada resposta nos seus logs, ao lado do ref. É o que o suporte pede.
• Monitore o certificado: consulte GET /empresas/{cnpj}/certificado periodicamente e alerte com 30 dias de antecedência (dias_restantes). Certificado vencido bloqueia toda a emissão da empresa.
• Alerte quando uma nota ficar mais de 1 hora em processando_autorizacao, ou em erro_autorizacao/erro_validacao sem que alguém tenha agido.
• Acompanhe as entregas dos webhooks (GET /webhooks/{id}/entregas?status=falhou): entregas que esgotaram as tentativas precisam de reenvio.
• Use GET /requisicoes?status=5xx e ?status=429 para enxergar problemas da integração (por exemplo, estourar o limite).

Numeração#

A plataforma reserva o número da NF-e em sequência, sem buracos nem duplicidade, mesmo com várias lojas do mesmo CNPJ emitindo ao mesmo tempo. Uma nota rejeitada mantém o número e é reenviada com ele. Os únicos "buracos" que podem surgir são de notas rejeitadas que você nunca corrigiu: inutilize essa faixa (Inutilizar numeração) até o dia 10 do mês seguinte.

Se a empresa migra de outro emissor, informe o próximo número antes da primeira nota em produção: a numeração da série começa em 1 e precisa continuar de onde o emissor anterior parou, senão haverá duplicidade com notas já emitidas. Veja Numeração da NF-e; pular números sem nota obriga a inutilizar a faixa pulada.

Boas práticas de integração#

• Use um identificador estável da venda como ref (o número do pedido). Nunca um valor aleatório gerado a cada tentativa: ele anularia a proteção contra duplicidade.
• Valide no seu lado o que puder (CPF/CNPJ, NCM de 8 dígitos, totais) para evitar viagens de ida e volta com 422.
• Informe sempre codigo_municipio_destinatario (o IBGE do município do destinatário): evita depender de uma consulta externa por CEP.
• Mantenha o catálogo de produtos sincronizado com PUT /empresas/{cnpj}/produtos/{sku} (idempotente) para que os itens possam ir só com o essencial.
• Trate campos novos em respostas e valores novos de status sem quebrar (veja Compatibilidade).
• Não faça emissões em paralelo para a mesma venda: uma ref, uma chamada por vez. Entre vendas diferentes, paralelize à vontade (respeitando o limite de 120 emissões por minuto).
• Em caso de dúvida fiscal sobre uma operação, fale com o contador antes de emitir: a nota fiscal tem consequência tributária.

Limitações atuais#

A plataforma é transparente sobre o que ainda não cobre. Nesses casos ela recusa com 422 em vez de arriscar:

• ICMS-ST como substituto (CSOSN 201, 202, 203, 900; CST 10, 30, 70, 90);
• devolução, nota complementar e de ajuste (finalidade_emissao diferente de 1) e nota de entrada;
• destinatário no exterior, exportação e importação;
• transportadora, volumes e reboque: a nota sai só com a modalidade do frete;
• unidade tributável diferente da comercial;
• contingência (SVC e EPEC): com a SEFAZ fora do ar a plataforma aguarda e tenta de novo por até 6 horas, mas não emite em contingência.

Precisa de algum desses? Fale com o suporte: ajuda a definir a prioridade.