Atendimento

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

CampoObservação
serieOpcional; padrão = série NFE padrão
naturezaOperacaoObrigatório, até 60 caracteres
tipoOperacaoSAIDA (padrão) ou ENTRADA
finalidadeNORMAL (padrão), COMPLEMENTAR, AJUSTE, DEVOLUCAO; as três últimas exigem referencias (chaves de NF-e)
consumidorFinalPadrão false
presencaObrigatório: NAO_SE_APLICA, PRESENCIAL, INTERNET, TELEATENDIMENTO, ENTREGA_DOMICILIO, PRESENCIAL_FORA_ESTABELECIMENTO, OUTROS
destinatarioObrigató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: origem e cst (regime normal: 00, 10, 20, 30, 40, 41, 50, 51, 60, 70, 90) ou csosn (Simples/MEI: 101, 102, 103, 201, 202, 203, 300, 400, 500, 900), com aliquota, reducaoBase, aliquotaFcp, mvaSt, reducaoBaseSt, aliquotaSt, aliquotaFcpSt, aliquotaCreditoSn, percentualDiferimento conforme o caso. difal (aliquotaInterna, aliquotaInterestadual de 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.
  • pis e cofins (opcionais; padrão CST 49 sem valor): cst (01/02 com aliquota).
  • 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, OUTROS com descricao), valor, aPrazo, cartao. O total pago precisa cobrir o valor da nota (o excedente vira troco).
  • transporte (padrão SEM_FRETE): modalidade, transportadora, veiculo, volumes.
  • cobranca (opcional): fatura e duplicatas[] (numero 001, 002..., vencimento, valor).
  • informacoesAdicionais: complementares e fisco.

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.

RotaResposta
GET /nfe/{id}a NF-e
GET /nfe/{id}/xmlnfeProc íntegro (NF-e + protocolo); 409 nfe-nao-autorizada sem protocolo
GET /nfe/{id}/danfePDF retrato (homologação: "SEM VALOR FISCAL"; cancelada: "CANCELADA")
GET /nfepá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

RotaCorpoResposta
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.

Nesta página