Emitir NF-e POST

Emite uma Nota Fiscal Eletrônica (modelo 55) de venda/circulação de mercadoria -- o motor fiscal calcula ICMS/IPI/PIS/COFINS, monta o XML, assina com o certificado digital do contribuinte e transmite para a SEFAZ da UF do emitente.

Quando utilizar

Sempre que seu ERP precisar emitir uma NF-e de saída (venda) ou entrada em nome do contribuinte cadastrado. Cada chamada gera exatamente um documento -- para NFC-e (modelo 65, venda a consumidor final) use o endpoint específico de NFC-e.

Pré-requisitos

• Contribuinte (emitente) já cadastrado -- POST /v1/contribuintes.
• Certificado digital A1 vinculado ao contribuinte -- POST /v1/contribuintes/{id}/certificado-digital.
• Inscrição estadual ativa na UF do emitente.
• Você controla a numeração (ide.numero/ide.serie) -- a API não auto-incrementa, diferente do RPS de NFS-e.
• Responsável técnico cadastrado na sua conta -- CNPJ, nome, e-mail e telefone de contato, preenchidos em Área do Cliente → Responsável Técnico. Sem isso, toda emissão de NF-e/CT-e/MDF-e falha com status: "ERROR". Ver Responsável técnico abaixo.

Responsável técnico

O grupo infRespTec do layout oficial identifica quem desenvolve/opera o sistema usado pra emitir o documento -- na sua conta CentralFiscal, não em cada contribuinte individual. Não existe campo responsavel_tecnico no corpo desta requisição -- a API resolve automaticamente a partir do cadastro da sua conta (CNPJ + nome/e-mail/telefone de contato, preenchidos uma vez em Área do Cliente → Responsável Técnico).

Fluxo da operação

Endpoint

Headers

Body

O corpo do NF-e segue de perto os grupos do XML -- clique num campo com ▸ pra expandir.

Exemplo mínimo

Um item, ICMS regime normal -- veja o código ao lado.

Exemplo Simples Nacional

Mesma estrutura do exemplo acima -- só muda o crt do emitente e a tributação do ICMS do item. Em emitente.crt, use "1" (Simples Nacional). No item, troque icms.cst por icms.csosn -- o exemplo ao lado usa 102 (Tributada pelo Simples Nacional sem permissão de crédito), o CSOSN mais comum pra revenda de mercadoria. PIS/COFINS seguem normalmente com cst de regime normal (01/02 etc.) -- a API não muda o tratamento de PIS/COFINS conforme o CRT do emitente, só o ICMS distingue CST de CSOSN.

Resposta de sucesso

200 OK -- já com o resultado final da SEFAZ nesta mesma resposta (status: "AUTHORIZED" em caso de sucesso). Traz chave (chave de acesso de 44 dígitos) e documento (rótulo do tipo). O campo detalhes traz o cstat/xmotivo reais devolvidos pela SEFAZ, além de tipo_emissao_utilizado ("1" na grande maioria dos casos; "6" ou "7" quando o autorizador primário falhou por comunicação e a NF-e saiu em contingência SVC-AN/SVC-RS -- comportamento ligado por padrão, desliga só se você mandar configuracoes.permitir_contingencia: false). Veja o exemplo ao lado.

Resposta de erro

Erro de payload (campo obrigatório ausente, valor inválido) não vira 400 -- ainda vem 200 OK, com o erro embutido no corpo. A chamada só devolve HTTP de erro de verdade pra falha de autenticação (401) ou contrato ausente (403/409). Pra tudo que acontece depois disso -- inclusive campo obrigatório faltando -- olhe status e retorno_amigavel.codigo (NFE_EMISSAO_FALHOU é o caso comum) na resposta 200, nunca o status HTTP. Exemplo real: endereço do emitente incompleto devolve 200 com status: "ERROR" e retorno_amigavel.codigo: "NFE_EMISSAO_FALHOU" trazendo a mensagem exata do campo que faltou. Catálogo completo de erros: Tratamento de Erros.

Notificação assíncrona

Não existe webhook genérico hoje -- e como a chamada já é síncrona (a resposta já traz o resultado final), normalmente você não precisa de nada além do próprio POST. Se precisar reconsultar mais tarde (ex. reprocessamento manual), use GET /v1/nfe/emissoes/{transmissao_id}.

Cancelamento

POST /v1/nfe/cancelamentos -- exige chave_acesso (44 dígitos), protocolo (da autorização original) e justificativa com pelo menos 15 caracteres. Mesmo padrão síncrono da emissão: a resposta já vem com o resultado final do evento de cancelamento na SEFAZ. Veja o exemplo ao lado.

Carta de Correção (CC-e)

POST /v1/nfe/cartas-correcao -- evento 110110. Não cancela nem corrige valores, impostos ou participantes da NF-e (isso exige cancelamento + nova emissão) -- só serve para os campos que a legislação permite corrigir por evento (dados cadastrais, endereço, informações complementares etc.). A NF-e original continua AUTHORIZED em caso de sucesso -- é isso que aparece no campo status da resposta, não um estado novo. Mesmo padrão síncrono do Cancelamento acima.

Exige chave_acesso (44 dígitos) e x_correcao (texto livre, 15 a 1000 caracteres -- limites do próprio schema oficial da SEFAZ, leiauteCCe_v1.00.xsd). sequencia_evento é opcional (padrão 1) -- só precisa informar se for enviar mais de uma CC-e para a mesma NF-e (a SEFAZ aceita até 19 por chave); quem controla qual sequencial usar em cada reenvio é quem chama a API, a CentralFiscal não guarda esse contador.

curl -X POST https://areacliente.centralfiscal.com.br/v1/nfe/cartas-correcao \
  -H "Authorization: Bearer cf_test_51JqK..." \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: cce-nfe-0001" \
  -d '{
    "chave_acesso": "43260712345678000190550010000010011000010018",
    "x_correcao": "Correcao do endereco do destinatario: numero do imovel e complemento."
  }'

Ator Interessado

POST /v1/nfe/atores-interessados -- evento 110150 ("Ator Interessado na NF-e - Transportador"). Autoriza um terceiro (CNPJ ou CPF -- ex.: contador, outro transportador, ou qualquer parte interessada) a baixar o XML completo da NF-e diretamente na SEFAZ, sem você precisar compartilhar o arquivo manualmente. Não cancela nem altera nenhum dado da NF-e -- ela continua AUTHORIZED em caso de sucesso, só ganha um evento de autorização anexado. Mesmo padrão síncrono do Cancelamento/CC-e acima.

Exige chave_acesso (44 dígitos) e autorizado.documento (CNPJ ou CPF de quem está sendo autorizado a baixar o XML). tipo_autorizacao é opcional: "0" não permite, "1" permite que o autorizado -- quando for um transportador -- repasse a autorização a subcontratados ou redespachados. Quando tipo_autorizacao é "1", a CentralFiscal já preenche xCondUso com o texto fixo exigido pelo schema oficial (leiauteEventoAtorInteressado_v1.00.xsd) -- não é um campo que você envia. sequencia_evento é opcional (padrão 1), mesmo critério da CC-e (a SEFAZ aceita até 20 por chave).

curl -X POST https://areacliente.centralfiscal.com.br/v1/nfe/atores-interessados \
  -H "Authorization: Bearer cf_test_51JqK..." \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: ator-nfe-0001" \
  -d '{
    "chave_acesso": "43260712345678000190550010000010011000010018",
    "autorizado": { "documento": "98765432000121" }
  }'

Eventos RTC (Reforma Tributária)

A Reforma Tributária (IBS/CBS) define 16 eventos novos de NF-e. Esta página documenta os 7 que fazem sentido do lado de quem emite a nota (tpAutor=1, Empresa Emitente). A CentralFiscal também expõe os 6 eventos do lado da empresa destinatária (tpAutor=2) -- ver Eventos RTC · como destinatário na página de Manifestação do Destinatário. Os 3 que sobram são do lado de empresa sucessora em fusão/aquisição ou do próprio Fisco -- fora do escopo do produto. Todos os 7 eventos desta página seguem o mesmo padrão síncrono do Cancelamento/CC-e/Ator Interessado acima: nenhum deles cancela nem altera a NF-e, ela continua AUTHORIZED em caso de sucesso, só ganha o evento correspondente anexado.

Pagamento Integral (112110)

POST /v1/nfe/pagamentos-integrais -- "Informação de efetivo pagamento integral para liberar crédito presumido do adquirente". É uma confirmação simples, no mesmo espírito do Ator Interessado: o único dado que você envia é a chave_acesso (44 dígitos) da NF-e referenciada -- a descrição do evento e o indicador de quitação são fixos, preenchidos pela CentralFiscal.

curl -X POST https://areacliente.centralfiscal.com.br/v1/nfe/pagamentos-integrais \
  -H "Authorization: Bearer cf_test_51JqK..." \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: pagtointegral-nfe-0001" \
  -d '{
    "chave_acesso": "43260712345678000190550010000010011000010018"
  }'

Importação em ALC/ZFM (112120)

POST /v1/nfe/importacoes-alc-zfm -- "Importação em ALC/ZFM não convertida em isenção" (Área de Livre Comércio / Zona Franca de Manaus). Item por item, em itens[]: nItem, vIbs/vCbs (valor do IBS/CBS que não atendeu aos requisitos da isenção) e qtde/unidade (quantidade que não converteu).

curl -X POST https://areacliente.centralfiscal.com.br/v1/nfe/importacoes-alc-zfm \
  -H "Authorization: Bearer cf_test_51JqK..." \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: importalczfm-nfe-0001" \
  -d '{
    "chave_acesso": "43260712345678000190550010000010011000010018",
    "itens": [
      { "nItem": 1, "vIbs": 120.50, "vCbs": 45.10, "qtde": 3.5, "unidade": "UN" }
    ]
  }'

Perecimento no Transporte (112130)

POST /v1/nfe/perecimentos-transporte-fornecedor -- "Perecimento, perda, roubo ou furto durante o transporte contratado pelo fornecedor". Item por item, em itens[], cada item carrega dois pares de valor de imposto com significado diferente -- não troque um pelo outro:

• vIbsNotaFornecimento/vCbsNotaFornecimento -- valor do imposto na nota de fornecimento correspondente à quantidade perdida.
• qPerecimento/uPerecimento -- a quantidade perdida.
• vIbsEstornoCredito/vCbsEstornoCredito -- valor do crédito a estornar referente à aquisição (diferente do par acima).

curl -X POST https://areacliente.centralfiscal.com.br/v1/nfe/perecimentos-transporte-fornecedor \
  -H "Authorization: Bearer cf_test_51JqK..." \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: perecimento-nfe-0001" \
  -d '{
    "chave_acesso": "43260712345678000190550010000010011000010018",
    "itens": [
      {
        "nItem": 1,
        "vIbsNotaFornecimento": 200.00, "vCbsNotaFornecimento": 80.00,
        "qPerecimento": 5, "uPerecimento": "UN",
        "vIbsEstornoCredito": 150.00, "vCbsEstornoCredito": 60.00
      }
    ]
  }'

Fornecimento Não Realizado (112140)

POST /v1/nfe/fornecimentos-nao-realizados -- "Fornecimento não realizado com pagamento antecipado". Item por item, em itens[]: nItem, vIbs/vCbs (valor na nota de débito do pagamento antecipado correspondente à quantidade não fornecida) e qNaoFornecida/uNaoFornecida.

curl -X POST https://areacliente.centralfiscal.com.br/v1/nfe/fornecimentos-nao-realizados \
  -H "Authorization: Bearer cf_test_51JqK..." \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: fornecnaorealizado-nfe-0001" \
  -d '{
    "chave_acesso": "43260712345678000190550010000010011000010018",
    "itens": [
      { "nItem": 1, "vIbs": 30.00, "vCbs": 12.00, "qNaoFornecida": 2, "uNaoFornecida": "UN" }
    ]
  }'

Previsão de Entrega (112150)

POST /v1/nfe/atualizacoes-previsao-entrega -- "Atualização da Data de Previsão de Entrega". O mais simples dos 7: um único campo de negócio, data_previsao_entrega (formato AAAA-MM-DD).

curl -X POST https://areacliente.centralfiscal.com.br/v1/nfe/atualizacoes-previsao-entrega \
  -H "Authorization: Bearer cf_test_51JqK..." \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: prevendtrega-nfe-0001" \
  -d '{
    "chave_acesso": "43260712345678000190550010000010011000010018",
    "data_previsao_entrega": "2026-10-15"
  }'

Crédito Presumido (211110)

POST /v1/nfe/solicitacoes-credito-presumido -- "Solicitação de Apropriação de crédito presumido". Item por item, em itens[]: vBc (base de cálculo) é obrigatório; ibs e/ou cbs trazem codigoCreditoPresumido (tabela SEFAZ, 2 dígitos), percentualCreditoPresumido e valorCreditoPresumido.

curl -X POST https://areacliente.centralfiscal.com.br/v1/nfe/solicitacoes-credito-presumido \
  -H "Authorization: Bearer cf_test_51JqK..." \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: credpresumido-nfe-0001" \
  -d '{
    "chave_acesso": "43260712345678000190550010000010011000010018",
    "itens": [
      {
        "nItem": 1,
        "vBc": 1000.00,
        "ibs": { "codigoCreditoPresumido": "01", "percentualCreditoPresumido": 10, "valorCreditoPresumido": 100.00 },
        "cbs": { "codigoCreditoPresumido": "02", "percentualCreditoPresumido": 5, "valorCreditoPresumido": 50.00 }
      }
    ]
  }'

Consumo Pessoal (211120)

POST /v1/nfe/consumos-pessoais -- "Destinação de item para consumo pessoal". Item por item, em itens[]: vIbs/vCbs (valor na nota de aquisição correspondente à quantidade destinada a consumo pessoal), qConsumo/uConsumo e chaveAcessoReferenciada/ nItemReferenciado -- a chave da nota emitida para o fornecimento e o item correspondente nela.

curl -X POST https://areacliente.centralfiscal.com.br/v1/nfe/consumos-pessoais \
  -H "Authorization: Bearer cf_test_51JqK..." \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: consumopessoal-nfe-0001" \
  -d '{
    "chave_acesso": "43260712345678000190550010000010011000010018",
    "itens": [
      {
        "nItem": 1,
        "vIbs": 40.00, "vCbs": 16.00,
        "qConsumo": 1, "uConsumo": "UN",
        "chaveAcessoReferenciada": "43260712345678000190550010000010021000010028",
        "nItemReferenciado": 3
      }
    ]
  }'

O que ainda não existe

Estes grupos existem no leiaute oficial (nfe_v4.00.xsd) mas o motor não os suporta hoje -- todos são nichos legítimos de baixo volume, sem previsão:

• NF-e avulsa -- emissão por órgão do Fisco em nome de terceiro.
• infIntermed -- identificação de intermediador/marketplace.
• exporta -- comprovante de exportação (DI, drawback).
• compra -- dados de nota de empenho/pedido de compra governamental.
• cana -- agroindústria canavieira (fechamento de safra).
• agropecuario -- produtos agropecuários animais/vegetais/florestais (NT 2024.003).
• infRespTec -- responsável técnico pelo sistema emissor.
• infSolicNFF -- Nota Fiscal Fácil (NT específica).

Próximos passos

• Baixar o XML e o DANFE usando as URLs em detalhes.
• Se precisar cancelar, ver POST /v1/nfe/cancelamentos acima.
• Se precisar corrigir dados sem cancelar, ver POST /v1/nfe/cartas-correcao acima.
• Se precisar autorizar um terceiro a baixar o XML, ver POST /v1/nfe/atores-interessados acima.
• Reconsultar mais tarde, se precisar: GET /v1/nfe/emissoes/{transmissao_id}.