NFCe: Nota Fiscal de Consumidor Eletrônica

A NFCe (modelo 65) é o documento fiscal para vendas a consumidor final no varejo. Substitui o cupom fiscal e deve ser emitida no momento da venda.

Endpoint base: https://api.engineapi.com.br/v1/nfce

Pré-requisitos

Diferenças NFe vs NFCe

Emitir NFCe

O item da NFCe reusa o mesmo grupo ibsCbs da NFe (Reforma Tributária); os demais campos são específicos.

curl -X POST https://api.engineapi.com.br/v1/nfce \
  -H "x-api-key: SUA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "destCPF": "12345678909",
    "destNome": "Consumidor Final",
    "items": [{
      "codigo": "PROD001",
      "descricao": "Camiseta Azul M",
      "ncm": "61091000",
      "cfop": "5102",
      "unidade": "UN",
      "quantidade": 1,
      "valorUnitario": 89.90,
      "icms": { "origem": 0, "csosn": "400" }
    }],
    "pagamentos": [
      { "forma": "03", "valor": 89.90 }
    ]
  }'

Campos de referência

pis/cofins e cest seguem exatamente as regras da NF-e (valores informados vão para o documento; combinação sem efeito é recusada com 422, ver PIS, COFINS e IPI). IPI não existe no modelo 65 e ICMS-ST não é escrito: os campos ipi e icms.baseCalculoST/aliquotaST/valorST são aceitos no contrato apenas para poder recusar: com valor diferente de zero devolvem 422 IPI_NAO_SUPORTADO e 422 ICMS_ST_NAO_SUPORTADO, em vez de emitir a NFC-e sem o dado.

Formas de Pagamento

Response de Sucesso

Envelopado em { data, meta }, sem aninhamento nfce:

{
  "data": {
    "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "status": "AUTHORIZED",
    "accessKey": "35260211222333000181650010000000011000000019",
    "protocol": "135260000001234",
    "number": 1,
    "series": 1,
    "model": "65",
    "amount": "89.9",
    "destCNPJ": "12345678909",
    "destName": "Consumidor Final",
    "qrCode": "https://www.fazenda.sp.gov.br/nfce/qrcode?p=35260...",
    "createdAt": "2026-07-06T12:00:00.000Z",
    "updatedAt": "2026-07-06T12:00:01.000Z",
    "downloads": {
      "xml": "/v1/nfce/xml/35260211222333000181650010000000011000000019",
      "pdf": "/v1/nfce/pdf/35260211222333000181650010000000011000000019"
    }
  },
  "meta": {
    "requestId": "req_abc123",
    "timestamp": "2026-07-06T12:00:00.000Z"
  }
}

Sem issuer/customer embutidos e sem xml/xmlPath/pdfPath/invoiceId/message (caminho de arquivo interno / shape antigo, removido). status é "AUTHORIZED" (inglês, mesmo enum de sempre). amount é string decimal ("89.9", sem zero à direita). qrCode é exclusivo da NFCe, não é coluna do banco, só existe na resposta da emissão (guarde-o no seu lado se precisar reimprimir o cupom depois). Não há campos cupomUrl/xmlUrl, use downloads.xml/downloads.pdf (mesmas rotas de download descritas abaixo).

Download do Cupom Fiscal

O DANFCE é retornado como PDF (Content-Type: application/pdf), não passa pelo envelope {data,meta}, o corpo é o arquivo:

curl https://api.engineapi.com.br/v1/nfce/pdf/{accessKey} \
  -H "x-api-key: SUA_API_KEY" \
  -o cupom.pdf

O documento é gerado a partir do XML autorizado da própria nota, no layout de cupom fiscal: ambiente (tpAmb), tributação (CST/CSOSN) e informações complementares saem do documento, nunca de uma remontagem.

Quando o XML autorizado não está armazenado neste ambiente (por exemplo, emissão em sandbox), a resposta é 409 com code: DANFE_INDISPONIVEL, nunca um documento aproximado.

Download do XML

curl https://api.engineapi.com.br/v1/nfce/xml/{accessKey} \
  -H "x-api-key: SUA_API_KEY"

Cancelamento

curl -X POST https://api.engineapi.com.br/v1/nfce/{idOuChave}/cancelar \
  -H "x-api-key: SUA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "justificativa": "Erro na forma de pagamento informada na venda" }'

{idOuChave} aceita o UUID (id da resposta de emissão) ou a chave de acesso (44 dígitos numéricos) da NFCe, mesmo contrato do cancelamento de NFe. Sempre escopado ao seu partner (usar id/chave de outro partner devolve o mesmo 404 de "não existe"). O campo do corpo é justificativa (mínimo 15 caracteres), não motivo.

Fora do prazo: cStat 501

Se o cancelamento for solicitado após o prazo da UF, a SEFAZ rejeita e a engineAPI repassa o desfecho verbatim no corpo 400:

{
  "error": {
    "erros": [
      {
        "codigo": "501",
        "descricao": "Rejeicao: Prazo de cancelamento superior ao previsto na Legislacao"
      }
    ]
  }
}

A nota permanece com status AUTHORIZED. Não existe cancelamento extemporâneo de NFCe via API. O remédio legal é emitir uma nota de devolução. Veja também o catálogo de Erros e Rejeições.

Inutilização

Inutilize uma faixa de numeração que nunca será usada. O caso típico é uma nota rejeitada de forma definitiva, que consome o número mas nunca chega a AUTHORIZED: sem inutilizar, esse número fica um gap permanente na sequência fiscal.

curl -X POST https://api.engineapi.com.br/v1/nfce/inutilizar \
  -H "x-api-key: SUA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "serie": 1,
    "numInicial": 45,
    "numFinal": 45,
    "justificativa": "Numero pulado por falha no sistema de PDV local"
  }'

O corpo é validado com mensagens de erro no padrão pt-BR do resto da API (ex.: "Justificativa deve ter no mínimo 15 caracteres (exigência SEFAZ)"). Os campos numéricos aceitam number ou string só-dígitos ("45"), mas rejeitam null, "", array e boolean com uma mensagem pt-BR acionável (nunca o "Invalid input" genérico) e nunca coagem silenciosamente pra 0.

Quando a SEFAZ homologa a inutilização (cStat 102), a resposta vem HTTP 200 com success true:

{
  "data": {
    "success": true,
    "protocol": "135260000009876",
    "message": "Inutilização série 1 nº 45 a 45 homologada",
    "xml": "<inutNFe>...</inutNFe>"
  },
  "meta": {
    "requestId": "req_abc123",
    "timestamp": "2026-07-20T12:00:00.000Z"
  }
}

Quando a SEFAZ rejeita o pedido (qualquer cStat diferente de 102), a engineAPI NÃO traduz isso em 4xx: o desfecho vem no próprio corpo, ainda em HTTP 200, com success false:

{
  "data": {
    "success": false,
    "cStat": 563,
    "xMotivo": "Rejeicao: Ja existe pedido de Inutilizacao com a mesma faixa de numeracao",
    "erros": [
      { "codigo": "563", "descricao": "Rejeicao: Ja existe pedido de Inutilizacao com a mesma faixa de numeracao" }
    ],
    "message": "Rejeicao: Ja existe pedido de Inutilizacao com a mesma faixa de numeracao"
  },
  "meta": {
    "requestId": "req_abc123",
    "timestamp": "2026-07-20T12:00:00.000Z"
  }
}

Outros status possíveis (nenhum é "sempre 200": só o desfecho da SEFAZ é):

Contingência

Se sua operação de varejo depende de continuar vendendo com a SEFAZ fora do ar (o cenário que o modo offline resolve no ACBr/PDV tradicional), fale com o time em suporte@engineapi.com.br, é candidato de roadmap, sem data. Para acompanhar a disponibilidade da SEFAZ antes de uma venda, use GET /v1/nfe/sefaz-status/{uf} (rota compartilhada entre os dois modelos, ver Consultar o status da SEFAZ).

Próximos passos