# 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](08-webhooks.md#confira-a-assinatura-sempre)), 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**.

| Situação | O que fazer |
|---|---|
| tempo esgotado ou conexão caiu, sem saber se a nota foi aceita | repita o `POST` igual. Ou consulte `GET /nfe/{ref}` primeiro |
| `5xx` | repita com espera crescente |
| `429` | espere o `Retry-After` e repita |
| `422`, `409` | **não** repita sem mudar nada: corrija o que foi apontado |

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.

```text
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](06-eventos.md#inutilizar-numeracao)) 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](03-empresas.md#numeracao-da-nf-e-series-e-proximo-numero); 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](02-autenticacao.md#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.