API de NFC-e (modelo 65) — cupom fiscal com QR Code

NFC-e · Nota Fiscal de Consumidor · modelo 65 chave ace_

POST /nfce/emitir

Cupom fiscal eletrônico ao consumidor final (varejo). Não exige destinatário (cupom anônimo) e usa CSC (Código de Segurança do Contribuinte). Emitente e certificado vêm da configuração. Cobra 1 unidade por cupom autorizado.

Configuração (uma vez): além do certificado, a NFC-e precisa do CSC e CSC id (gerados na SEFAZ do seu estado). Envie em PUT /nfce/configuracao: {"ambiente":2,"serie_nfce":1,"csc":"SEU-CSC","csc_id":"000001"}. O POST /nfce/certificado é o mesmo da NF-e.

Configuração

curl -X PUT .../api/v1/nfce/configuracao \
  -H "Authorization: Bearer ace_SEU_TOKEN" \
  -d '{
    "ambiente": 2, "serie_nfce": 1,
    "csc": "A1B2C3D4-....-CSC",
    "csc_id": "000001",
    "inscricao_estadual": "123456789"
  }'

$cli->nfce()->enviarCertificado($b64, 'senha');
$cli->nfce()->configurar([
  'ambiente'=>2, 'serie_nfce'=>1,
  'csc'=>'A1B2...', 'csc_id'=>'000001',
]);

Api.Put('nfce/configuracao', JSONFromStr(
  '{"ambiente":2,"serie_nfce":1,'+
  '"csc":"A1B2...","csc_id":"000001"}')).Free;

Cabeçalho opcional

A NFC-e já fixa saída, operação interna, finalidade normal e consumidor final — você não envia esses campos. Sobram (na raiz do JSON):

Campo	Padrão	Valores
`natureza_operacao`	VENDA	texto livre
`presenca`	1	1=presencial, 2=internet, 3=teleatendimento, 4=NFC-e entrega a domicílio, 9=outros
`info_complementar`	—	texto livre (infCpl do cupom)

Cabeçalho

{
  "natureza_operacao": "VENDA",
  "presenca": 1,
  "info_complementar": "Obrigado pela preferência"
}

Destinatário opcional (cupom identificado)

A NFC-e pode ser anônima. Para colocar o CPF/CNPJ do consumidor no cupom, envie o objeto destinatario (basta o documento):

Campo		Descrição
`documento`	se enviar dest.	CPF (11) ou CNPJ (14)
`nome`	CONSUMIDOR	Nome do consumidor
`endereco`	opc.	logradouro, numero, complemento, bairro, cod_municipio (IBGE), cidade, uf, cep — usa o do emitente se faltar

Destinatário (opcional)

{
  "destinatario": {
    "documento": "11144477735",
    "nome": "JOAO CONSUMIDOR"
  }
}
// omita "destinatario" para cupom anônimo

Itens / produtos obrigatório

Lista produtos[] (1+). Cada item permite desconto próprio.

Campo		Descrição
`codigo`	obrig.	Código interno do produto
`descricao`	obrig.	Descrição do item
`ncm`	obrig.	NCM (8 díg)
`unidade`	obrig.	UN, KG, CX…
`quantidade`	obrig.	número
`valor_unitario`	obrig.	número (total do item = qtd × unit)
`cfop`	5102	CFOP de venda (padrão 5102)
`desconto`	0	Desconto do item (em R$)
`ean`	SEM GTIN	Código de barras
`origem`	0	0=nacional, 1=import. direta…
`csosn`	102	Simples Nacional (regime Simples)
`cst_icms` · `aliq_icms`	00 · 18	Lucro Real/Presumido
`cst_pis` · `cst_cofins`	07	CST PIS/COFINS

Impostos automáticos: emitente Simples Nacional → ICMSSN com csosn (102). Emitente Lucro Real/Presumido → ICMS com cst_icms + aliq_icms sobre o valor líquido (após desconto). PIS/COFINS com CST 07.

Totais opcional

totais.desconto — desconto do cupom inteiro (sobrepõe a soma dos descontos por item). NFC-e não usa frete.

Produtos (exemplo)

{
  "produtos": [
    { "codigo": "001",
      "ean": "7896292301382",
      "descricao": "REFRIGERANTE LATA 350ML",
      "ncm": "22021000", "cfop": "5102",
      "unidade": "UN", "quantidade": 2,
      "valor_unitario": 5.50, "desconto": 0.50,
      "origem": 0, "csosn": "102" }
  ],
  "totais": { "desconto": "0.50" }
}

Pagamento obrigatório

Objeto pagamento com formas[] (uma ou mais) e troco. Cada forma:

Campo		Descrição
`forma`	obrig.	Meio de pagamento (tabela abaixo)
`valor`	obrig.	Valor pago nessa forma
`descricao`	se 99	Descrição livre do meio de pagamento (2 a 60 caracteres) — obrigatória em `forma: "99"`. Sem ela recusamos na hora com `422`, antes de gastar a viagem à SEFAZ (que recusaria com 441). Não preenchemos por você: só quem emite sabe o que foi o pagamento.
`tipo_integracao`	2	1=integrado ao seu sistema (TEF/API), 2=não integrado (POS/maquininha). Vale para todo meio eletrônico, não só cartão.
`cnpj_credenciadora`	opc.	CNPJ da credenciadora/PSP (Cielo, Rede, PagSeguro, Mercado Pago…)
`bandeira`	opc.	01=Visa, 02=Master, 03=Amex, 04=Sorocred, 05=Diners, 06=Elo, 07=Hipercard, 08=Aura, 09=Cabal, 99=outros
`autorizacao`	opc.	Código de autorização da transação (NSU/cAut)
`cnpj_beneficiario`	opc.	CNPJ de quem recebeu o dinheiro, quando não é o emitente (NT 2023.004)
`id_terminal`	opc.	Identificador do terminal/maquininha (NT 2023.004)
`cnpj_transacional` + `uf_transacional`	opc.	CNPJ e UF do estabelecimento onde o pagamento foi processado (NT 2023.004). Enviar os dois — sozinhos são ignorados.
`pagamento.troco`	opc.	Valor do troco (dinheiro)

Meio eletrônico exige o grupo de integração. Para 03 04 10 11 12 13 17 18 19 20 21 a SEFAZ obriga o grupo card com tpIntegra — inclusive no PIX. Sem ele a nota volta com rejeição 391 ("não informados os dados do cartão de crédito/débito"), mesmo não sendo cartão. Nós preenchemos tipo_integracao: 2 sozinhos quando você não manda, então {"forma":"17","valor":10} já funciona; mande 1 se o pagamento for capturado pelo seu sistema.

Formas de pagamento (`forma`)

`01` dinheiro	`02` cheque	`03` cartão crédito
`04` cartão débito	`05` crédito loja	`10` vale alimentação
`11` vale refeição	`12` vale presente	`13` vale combustível
`14` duplicata mercantil	`15` boleto	`16` depósito bancário
`17` PIX dinâmico	`18` transf. bancária / carteira digital	`19` fidelidade / cashback
`20` PIX estático	`21` crédito em loja	`22` pgto. eletrônico não informado
`90` sem pagamento	`99` outros exige descricao

PIX: use 17 quando o QR é gerado por cobrança (dinâmico) e 20 quando é o QR fixo do estabelecimento (estático).

Pagamento · dinheiro + cartão + PIX

{
  "pagamento": {
    "formas": [
      { "forma": "01", "valor": 6.00 },

      // cartão: bandeira e autorização quando você tiver
      { "forma": "03", "valor": 4.50,
        "tipo_integracao": 2,
        "cnpj_credenciadora": "01027058000191",
        "bandeira": "02",
        "autorizacao": "123456" },

      // PIX: só isso já basta (tipo_integracao 2 entra sozinho)
      { "forma": "17", "valor": 3.50 },

      // PIX capturado pelo seu sistema, com o PSP e o terminal
      { "forma": "17", "valor": 2.00,
        "tipo_integracao": 1,
        "cnpj_credenciadora": "01027058000191",
        "autorizacao": "E1234567202607281200",
        "id_terminal": "POS-01" },

      // 99 = outros: a descrição é obrigatória
      { "forma": "99", "valor": 1.00,
        "descricao": "Vale do funcionário" }
    ],
    "troco": 0
  }
}

Rejeições de pagamento

422 # nosso: forma 99 sem "descricao" (nem chega na SEFAZ)
391 # SEFAZ: meio eletrônico sem o grupo de integração —
    # mande tipo_integracao (1 ou 2)
442 # SEFAZ: soma das formas ≠ total da nota

Emitir — requisição completa

POST /nfce/emitir

Resposta 200: nfce_id, numero, serie, chave, protocolo, qrcode_url (QR do cupom) e status.

Requisição completa

curl -X POST .../api/v1/nfce/emitir \
  -H "Authorization: Bearer ace_SEU_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "produtos": [
      {"codigo":"001","descricao":"REFRIGERANTE 350ML",
       "ncm":"22021000","cfop":"5102","unidade":"UN",
       "quantidade":2,"valor_unitario":5.50}
    ],
    "pagamento": { "formas": [{"forma":"17","valor":11.00}] }
  }'

$c = $cli->nfce()->emitir([
  'produtos' => [['codigo'=>'001','descricao'=>'REFRI 350ML',
     'ncm'=>'22021000','cfop'=>'5102','unidade'=>'UN',
     'quantidade'=>2,'valor_unitario'=>5.50]],
  'pagamento' => ['formas'=>[['forma'=>'17','valor'=>11]]],
]);
$cli->nfce()->danfce($c['nfce_id'], 'cupom.pdf');

R := Api.EmitirNFCe(JSONFromStr(Json));
Api.BaixarPDF('nfce', R.Int('nfce_id'), 'cupom.pdf');

200 · data

{ "nfce_id": 21, "numero": 5, "serie": 1,
  "chave": "33260...(44)",
  "protocolo": "...",
  "qrcode_url": "https://.../consultarNFCe?p=...",
  "status": "autorizada" }

Operações

GET /nfce/{id}/xml · /nfce/{id}/danfce

POST /nfce/{id}/cancelar

POST /nfce/inutilizar

GET /nfce · /nfce/{id}

Cancelar: {"justificativa":"mín. 15 caracteres"}. Inutilizar uma faixa não usada: {"serie":1,"numero_inicial":10,"numero_final":15,"justificativa":"..."}. XML/DANFCE devolvem o arquivo direto.

Erros específicos

422 `emissao_rejeitada`	SEFAZ recusou (CSC inválido, produto sem NCM, etc.)
422 `cancelamento_rejeitado` · `inutilizacao_rejeitada`	Fora de prazo/regra
403 `produto_nao_vinculado`	Empresa sem o produto nfce

Cancelar / inutilizar

curl -X POST .../api/v1/nfce/21/cancelar \
  -H "Authorization: Bearer ace_SEU_TOKEN" \
  -d '{"justificativa":"Cancelamento a pedido do cliente"}'

curl -X POST .../api/v1/nfce/inutilizar \
  -H "Authorization: Bearer ace_SEU_TOKEN" \
  -d '{"serie":1,"numero_inicial":10,
       "numero_final":15,"justificativa":"Pulos de numeracao"}'

$cli->nfce()->cancelar(21, 'Cancelado pelo cliente');
$cli->nfce()->inutilizar(1, 10, 15, 'Pulos');
$cli->nfce()->xml(21, 'cupom.xml');

Api.Cancelar('nfce', 21, 'Cancelado').Free;
Api.BaixarXML('nfce', 21, 'cupom.xml');

Não achou o que procurava? Índice da documentação · tabela de erros · servidor MCP · contexto para IA · suporte · [email protected]

NFC-e · Nota Fiscal de Consumidor · modelo 65 chave ace_

Cabeçalho opcional

Destinatário opcional (cupom identificado)

Itens / produtos obrigatório

Totais opcional

Pagamento obrigatório

Formas de pagamento (forma)

Emitir — requisição completa

Operações

Erros específicos

Formas de pagamento (`forma`)