NF-e (nota fiscal)
O que é a NF-e, como a loja a emite pela FocusNFe e quais operações o painel oferece.
A NF-e (nota fiscal eletrônica) é o documento fiscal que o vendedor brasileiro precisa emitir em uma venda de mercadoria. Ela é enviada à SEFAZ (a Secretaria da Fazenda do estado), que a autoriza e devolve uma chave de acesso de 44 dígitos. A Venddor não fala direto com a SEFAZ: usa a FocusNFe, um provedor que faz a emissão e devolve o resultado. O DANFE é a versão em PDF da nota, entregue ao cliente junto com o XML.
Como funciona
- O módulo
focusnfeprecisa estar ligado e com token, CNPJ e certificado digital A1 configurados na tela de módulos. Consulte o certificado. - Você emite a nota de um pedido. Com
auto_issue_on_completeligado, a plataforma também emite sozinha quando o pedido é concluído. - A nota entra como
processando. Quando a SEFAZ responde, passa aautorizado,errooudenegado. - Com a nota
autorizado, baixe o XML e o DANFE. - Se algo estiver errado, cancele, corrija ou inutilize.
Status (status)
| Valor | Significado |
|---|---|
processando | Enviada, aguardando a SEFAZ. |
autorizado | Aceita. chave_nfe, xml_url e danfe_url existem. |
erro | Rejeitada. Veja error_msg e error_message. |
denegado | A SEFAZ negou o uso. O número não pode ser reaproveitado. |
cancelado | Cancelada dentro do prazo. |
inutilizado | Faixa de números declarada como não usada. |
Conceitos
Inutilização
Quando a numeração pula (por exemplo, uma emissão falhou antes de chegar à SEFAZ), a lei exige avisar a SEFAZ que aqueles números não serão usados. É a inutilização, de uma faixa de números dentro de uma série.
Modo de simulação
Lojas de demonstração podem ligar simulation_mode: nada vai à SEFAZ e os registros servem só como exemplo. O cancelamento nesse modo é gravado só localmente.
Pedido de seller
Em pedidos com vários sellers, cada seller pode ter a própria nota (vendor_id). Sellers com configuração fiscal própria usam o token deles.
Endpoints
| Método | Caminho | Para quê |
|---|---|---|
| POST | /api/v1/admin/nfe/issue | Emite a partir do pedido |
| POST | /api/v1/admin/nfe | Emite com dados manuais |
| GET | /api/v1/admin/nfe | Lista notas |
| GET | /api/v1/admin/nfe/{id} | Consulta uma nota |
| POST | /api/v1/admin/nfe/{id}/check-status | Consulta o status na FocusNFe |
| GET | /api/v1/admin/nfe/certificate-status | Situação do certificado |
| GET | /api/v1/admin/nfe/{id}/xml | Baixa o XML |
| GET | /api/v1/admin/nfe/{id}/danfe | Baixa o DANFE |
| POST | /api/v1/admin/nfe/{id}/cancel | Cancela |
| DELETE | /api/v1/admin/nfe/{id} | Cancela (rota antiga) |
| POST | /api/v1/admin/nfe/{id}/cce | Carta de correção |
| POST | /api/v1/admin/nfe/inutilize | Inutiliza números |
Erros comuns
- Emitir de novo achando que duplica.
POST /nfe/issueé idempotente por pedido: se já existe nota, devolve a existente com 200. - Cliente sem documento. Pedido sem CPF/CNPJ do cliente volta 422
customer_document_missing. - Quantidade fracionada. Linhas em kg ou litros com quantidade decimal são recusadas (422
fractional_quantity_not_supported): a NF-e só aceita quantidade inteira aqui. - Token da FocusNFe recusado. Volta 422; corrija o token em Módulos, FocusNFe.
- Cancelar fora do prazo. Depois de 24 horas a FocusNFe recusa (502 com a mensagem do provedor).
- Baixar XML de nota não autorizada. Volta 500, pois não há arquivo.
- Usar CC-e para corrigir valor. A carta nunca corrige valores, impostos nem dados do destinatário.