NF-e
NF-e modelo 55 com cálculo de tributos, cancelamento, carta de correção, inutilização e DANFE.
A NF-e (modelo 55) é emitida em qualquer UF. Você envia a operação e a regra fiscal de cada item; o servidor calcula
bases, tributos e totais, numera, assina e transmite. Toda rota exige X-Emitente-Id e o produto NFE contratado.
O emitente precisa de CNPJ, inscrição estadual, certificado A1 válido e uma
série NFE.
Emissão
POST /api/v1/nfe
X-Emitente-Id: 8b3c1f0e-5d2a-4a1b-9c3d-2e1f0a9b8c7d
Idempotency-Key: 9a7e2c4d-1b3f-4e5a-8c6d-0f2e4a6b8c1d
{
"naturezaOperacao": "Venda de mercadoria",
"presenca": "PRESENCIAL",
"consumidorFinal": true,
"destinatario": {
"cnpjCpf": "11222333000181", "nome": "Cliente Exemplo Ltda", "indicadorIe": "NAO_CONTRIBUINTE",
"endereco": { "logradouro": "Rua Exemplo", "numero": "100", "bairro": "Centro",
"codigoMunicipio": "5300108", "cep": "70000000" }
},
"itens": [{
"codigo": "P001", "descricao": "Notebook", "ncm": "84713012", "cfop": "5102", "unidade": "UN",
"quantidade": "1", "valorUnitario": "10.00",
"icms": { "origem": 0, "cst": "00", "aliquota": "18" },
"pis": { "cst": "01", "aliquota": "1.65" }, "cofins": { "cst": "01", "aliquota": "7.60" },
"ibsCbs": { "cst": "000", "classificacaoTributaria": "000001", "aliquotaIbsUf": "0.1", "aliquotaCbs": "0.9" }
}],
"pagamentos": [{ "forma": "PIX_DINAMICO", "valor": "10.00" }]
}Use POST /nfe/calculo com o mesmo corpo para ver os tributos e totais sem emitir: nada é gravado nem numerado.
Operação
| Campo | Observação |
|---|---|
serie | Opcional; padrão = série NFE padrão |
naturezaOperacao | Obrigatório, até 60 caracteres |
tipoOperacao | SAIDA (padrão) ou ENTRADA |
finalidade | NORMAL (padrão), COMPLEMENTAR, AJUSTE, DEVOLUCAO; as três últimas exigem referencias (chaves de NF-e) |
consumidorFinal | Padrão false |
presenca | Obrigatório: NAO_SE_APLICA, PRESENCIAL, INTERNET, TELEATENDIMENTO, ENTREGA_DOMICILIO, PRESENCIAL_FORA_ESTABELECIMENTO, OUTROS |
destinatario | Obrigatório: cnpjCpf, nome, indicadorIe, inscricaoEstadual, endereco (o município define a UF e se a operação é interna ou interestadual) |
Itens
De 1 a 990 itens, com codigo, gtin (nulo = "SEM GTIN"), descricao, ncm, cest, cfop (1º dígito coerente
com o tipo e o destino: 5/6 saída, 1/2 entrada), unidade, quantidade (até 4 casas), valorUnitario (até 10
casas), desconto, frete, seguro, outrasDespesas e a tributação:
icms:origemecst(regime normal: 00, 10, 20, 30, 40, 41, 50, 51, 60, 70, 90) oucsosn(Simples/MEI: 101, 102, 103, 201, 202, 203, 300, 400, 500, 900), comaliquota,reducaoBase,aliquotaFcp,mvaSt,reducaoBaseSt,aliquotaSt,aliquotaFcpSt,aliquotaCreditoSn,percentualDiferimentoconforme o caso.difal(aliquotaInterna,aliquotaInterestadualde 4, 7 ou 12,aliquotaFcp) é obrigatório, e só aceito, em venda interestadual a consumidor final não contribuinte.ipi(opcional):cst,codigoEnquadramento(padrão 999),aliquota.pisecofins(opcionais; padrão CST 49 sem valor):cst(01/02 comaliquota).ibsCbs(opcional, NT 2025.002):cst,classificacaoTributaria,aliquotaIbsUf,aliquotaIbsMunicipal,aliquotaCbs. Veja Tabelas.
Pagamento, transporte e cobrança
pagamentos[]:forma(DINHEIRO,PIX_DINAMICO,CARTAO_CREDITO,BOLETO, ...,SEM_PAGAMENTO,OUTROScomdescricao),valor,aPrazo,cartao. O total pago precisa cobrir o valor da nota (o excedente vira troco).transporte(padrãoSEM_FRETE):modalidade,transportadora,veiculo,volumes.cobranca(opcional):faturaeduplicatas[](numero001, 002...,vencimento,valor).informacoesAdicionais:complementaresefisco.
Erros do POST: 400 com o caminho no campos (ex.: itens[0].icms.csosn; os campos de topo obrigatórios
ausentes vêm todos de uma vez); 409 idempotency-conflito; 422 emitente-sem-ie, emitente-sem-cnpj,
certificado-indisponivel, serie-nao-configurada. Rejeição ou denegação da SEFAZ aparece no GET.
A NF-e
A resposta traz id, status, ambiente, serie, numero, chaveAcesso, protocolo, dataEmissao,
dataHoraAutorizacao, valorTotal, totais (bases, ICMS, ST, FCP, DIFAL, IPI, PIS, COFINS, IBS/CBS, troco),
erros e o conteúdo pedido.
| Rota | Resposta |
|---|---|
GET /nfe/{id} | a NF-e |
GET /nfe/{id}/xml | nfeProc íntegro (NF-e + protocolo); 409 nfe-nao-autorizada sem protocolo |
GET /nfe/{id}/danfe | PDF retrato (homologação: "SEM VALOR FISCAL"; cancelada: "CANCELADA") |
GET /nfe | página; filtros status, emissaoDe, emissaoAte, destinatario, q (número, chave, CPF/CNPJ ou nome) |
GET /nfe/resumo/mensal?de=&ate= | por mês: quantidadeAutorizadas, valorTotal, valorIcms, porStatus |
Eventos
| Rota | Corpo | Resposta |
|---|---|---|
POST /nfe/{id}/cancelamento | {justificativa} (15 a 255) | 200 NF-e CANCELADA (evento 110111, síncrono, idempotente) |
POST /nfe/{id}/carta-correcao | {correcao} (15 a 1000) | 200 evento registrado (110110; sequência automática, até 20) |
GET /nfe/{id}/eventos | — | eventos enviados, registrados e rejeitados |
GET /nfe/{id}/eventos/{eventoId}/xml | — | procEventoNFe do evento |
Erros: 409 nfe-nao-autorizada fora de AUTORIZADA; 422 cancelamento-rejeitado ou carta-correcao-rejeitada
com erros da SEFAZ (ex.: prazo); 422 limite-carta-correcao; 502 sefaz-indisponivel (repita).
Inutilização
POST /nfe/inutilizacao com {serie, numeroInicial, numeroFinal, justificativa} inutiliza números já reservados na
série (abaixo do próximo) sem NF-e válida, como os de notas rejeitadas. Síncrono: responde 200 com homologada,
protocolo e dataHoraRegistro. Erros: 422 faixa-nao-reservada, faixa-em-uso, serie-nao-configurada,
inutilizacao-rejeitada. GET /nfe/inutilizacoes lista as do emitente.