NF-e

Emissão de NF-e em nome de vendedores - ordem dos endpoints, semântica dos status, pré-requisitos, idempotência, escopo, checklist de integração e solução de problemas.

Visão geral

Os endpoints de NF-e emitem notas fiscais de produto (NF-e) em nome de uma empresa registrada: a emissão é aceita de imediato e autorizada de forma assíncrona na SEFAZ, o resultado chega por webhook ou consulta, e uma nota autorizada pode ser cancelada ou complementada com cartas de correção (CC-e).

Endpoints

Antes de emitir, a empresa precisa estar registrada por Registrar empresa, ter o certificado vinculado por Vincular certificado, e a sua aplicação deve ter uma URL de callback registrada por Registrar webhook. O empresaId devolvido no registro é a variável de caminho de todos os endpoints abaixo.

Passo	Endpoint	Observações
1 Emitir NF-e	`POST /openapi/v2/empresas/{empresaId}/nf-e`	Aceita de imediato; autorizada de forma assíncrona na SEFAZ
2 Consultar NF-e	`GET /openapi/v2/empresas/{empresaId}/nf-e/{nfeId}`	Status, dados da nota, links de download do DANFE / XML
3 Cancelar NF-e	`DELETE /openapi/v2/empresas/{empresaId}/nf-e/{nfeId}`	Dentro de 24 horas da autorização
4 Registrar carta de correção	`POST /openapi/v2/empresas/{empresaId}/nf-e/{nfeId}/carta-correcao`	Dentro de 720 horas da autorização, até 20 por nota, protocolo devolvido de forma síncrona
5 Listar cartas de correção	`GET /openapi/v2/empresas/{empresaId}/nf-e/{nfeId}/carta-correcao`	Cada entrada traz o XML de recibo e o link de download do DACCE

Toda requisição carrega os três cabeçalhos de assinatura descritos em Autenticação; o path assinado inclui o prefixo /openapi e as variáveis de caminho (empresaId / nfeId).

Semântica dos status

`status`	Significado
`AguardandoAutorizacao`	Da aceitação até a resposta da SEFAZ
`Autorizada`	Autorizada pela SEFAZ; `linkDanfe` / `linkDownloadXml` ficam disponíveis
`Negada`	Rejeitada; `motivoStatus` traz o código de status e a descrição da SEFAZ (por exemplo `778 - Rejeicao: NCM inexistente`). Corrija e reenvie
`Cancelada`	Após um cancelamento bem-sucedido

Os resultados autorizado e negado também são entregues na sua URL de callback; os formatos de carga estão em Webhooks.

Status da empresa e pré-requisitos

O endpoint de registro coloca a empresa na fila de aprovação da plataforma; a empresa só pode emitir notas depois que a operação a aprova e o certificado é vinculado. Emitir antes da aprovação retorna o erro 10004004 (empresa não habilitada a emitir). Confirme o andamento da aprovação com a operação da plataforma.

Toda empresa tem um ambiente atual (teste Homologacao / produção Producao); empresas recém-registradas começam em teste, e a mudança para produção é uma ação da operação. O ambienteEmissao da requisição de emissão deve corresponder ao ambiente atual da empresa; a divergência retorna 10004030, uma proteção rígida contra notas de teste emitidas em produção. Veja Ambientes.

Idempotência e reenvio

Requisições de emissão aceitas retornam HTTP 200 sem corpo e entram no fluxo assíncrono de emissão; o resultado chega por webhook ou pelo endpoint de consulta. Reenviar o mesmo id reaproveita a tarefa original; se a tentativa anterior foi negada (Negada), reenviar o mesmo id com os campos corrigidos emite de novo com o novo payload, sem precisar de outro id. Alterar campos-chave como o destinatário enquanto a tentativa anterior ainda está em processamento ou já foi autorizada é rejeitado com 10004032.

Escopo

Item	Suporte
Finalidade da nota	Notas normais e de devolução (`finalidade=Normal` / `Devolucao`); notas complementares / de ajuste ainda não suportadas
Destinatário	Compradores CPF; compradores CNPJ devem trazer `inscricaoEstadual` (contribuinte de ICMS)
Presença do consumidor	Somente `OperacaoPelaInternet`
Formas de pagamento	Uma ou mais entradas cuja soma de `valor` deve ser igual ao total da nota; os dados da credenciadora não são gravados na NF-e
Frete	Fixo sem transporte (`modFrete=9`)
Alíquotas	Códigos tributários mais parâmetros de alíquota opcionais; para empresas CRT=3 as alíquotas ad valorem omitidas são preenchidas pela tabela de alíquotas, e o `pCredSN` de CSOSN 101/201 recorre ao perfil da empresa
Link do DANFE	Disponível na resposta da consulta e, como `nfeLinkDanfe`, no callback de autorização; o PDF é renderizado no primeiro download
Carta de correção (CC-e)	Registro e listagem, protocolo devolvido de forma síncrona, DACCE incluído; ainda sem callback `invoice.cce.registered`
`digestValue` / telefone do cliente / complemento do endereço	Não fornecidos no momento

Checklist de integração

Registre uma empresa → 200 + empresaId; registre o mesmo CNPJ de novo → 400 + 10003002.
Vincule o certificado → 200 sem corpo; senha errada → 400 + CER0005.
Registre o webhook → 200 + webHookId.
Após a aprovação, emita com ambienteEmissao=Homologacao → 200 sem corpo; depois consulte → AguardandoAutorizacao vira Autorizada, e linkDanfe / linkDownloadXml baixam com sucesso.
Receba o callback de autorização: o cabeçalho token é igual ao valor registrado e a carga tem nfeStatus=Autorizada.
Casos negativos: ambienteEmissao=Producao → 400 + 10004030; presencaConsumidor=OperacaoPresencial → 400 + 10004031.
Cancele a nota recém-autorizada → 200; consulte de novo → Cancelada; cancele um id desconhecido → 404 + NFe0001.
Caminhos de falha: sign errado → 401 + 10009003; endpoint não subscrito → 403 + 10009005.

Solução de problemas

Assinatura divergente (401, 10009003)?

Veja a seção de solução de problemas em Autenticação.

Emissão presa em AguardandoAutorizacao?

Enquanto a empresa está no ambiente de teste, isso depende da disponibilidade do ambiente de teste da SEFAZ; se persistir por mais de alguns minutos, contate a plataforma com o empresaId e o nfeId.

Emissão retorna 10004004?

A empresa ainda não foi aprovada, ou o certificado não está vinculado / expirou. Conclua primeiro a aprovação e a vinculação do certificado após o registro.

Callbacks não chegam?

Confirme que uri é um endereço https/http publicamente acessível que retorna 2xx; a plataforma reenvia com backoff e aciona um disjuntor após falhas consecutivas. Chamar Registrar webhook de novo restaura a entrega.