NFC-e modelo 65 API

USO

Quando usar NFC-e

A NFC-e é para venda de mercadoria ao consumidor final, no balcão ou com entrega em domicílio: loja, mercado, farmácia, restaurante, e-commerce que entrega na mesma UF. Se a venda é para outra empresa revender ou industrializar, ou se atravessa a fronteira do estado, o documento certo é a NF-e modelo 55. Se o que você vende é serviço, é a NFS-e.

SITUAÇÃO	DOCUMENTO
Venda de produto no balcão, consumidor final	NFC-e (65)
Entrega em domicílio ao consumidor, dentro do estado	NFC-e (65), com presenca 4
Venda para outra empresa, ou para outro estado	NF-e (55)
Prestação de serviço	NFS-e

ESC

Escopo e limitações

Leia antes de planejar o PDV

Liberada por estado. A NFC-e já emite em produção no Rio Grande do Sul; os demais estados vêm em seguida. Enquanto a UF do seu emitente não estiver liberada, a emissão em produção devolve 422 com a lista de UFs habilitadas — mas a homologação está aberta em qualquer UF, sem custo, para você integrar o PDV antes.

Contingência offline (tpEmis 9) ainda não está implementada. Hoje só existe emissão online: se a internet do caixa cair, a venda não vira nota até a conexão voltar. Em NFC-e isso importa mais do que nos outros modelos, porque o cliente está esperando o cupom no balcão — planeje um procedimento manual para essa janela.

DANFE-NFCe em PDF ainda não é gerado por nós. Ao consultar a nota autorizada você recebe chave, protocolo, qr_code e url_chave — tudo que o cupom exige além dos itens, que o PDV já tem. Montar e imprimir o cupom fica por conta dele. O endpoint de DANFE em PDF existe só para NF-e.

AUTH

Autenticação

Todas as rotas usam o token da sua conta APIFacil no header Authorization: {seu_token} — sem prefixo "Bearer". O mesmo token que você já usa para WhatsApp e Telegram. Gere ou copie no painel do usuário.

A base da API fiscal é https://nts.apifacil.dev/api/v1, e não apifacil.dev. A nota fiscal roda em domínio próprio: chamar o domínio do WhatsApp devolve 404.

Integrando com ajuda de IA? Aponte o agente para apifacil.dev/fiscal/llms.txt (o mesmo arquivo responde em nts.apifacil.dev/llms.txt): é esta documentação em texto puro, no formato llms.txt, com todos os endpoints, campos e códigos de rejeição.

BASH

# Header correto: Authorization + token direto (SEM "Bearer")
curl https://nts.apifacil.dev/api/v1/emitentes \
  -H "Authorization: SEU_TOKEN_AQUI"

Assinatura: emitir em produção exige a assinatura do serviço Nota Fiscal ativa na conta. Emissão em homologação (ambiente=2) é liberada mesmo sem assinatura, para você testar antes de contratar.

PAIN

Cadastrar emitente

Passo humano, uma vez

1

Acessa o painel
nts.apifacil.dev

→

2

Cadastra o emitente
CNPJ, IE, endereço, regime tributário, município

→

3

Envia o certificado A1
.pfx/.p12 + senha

→

4

Pronto para emitir
via API, pelo seu sistema

Mesma conta e mesma sessão do restante da APIFacil — o painel fiscal só mora num subdomínio próprio. O cadastro dos dados do emitente também pode ser feito por API (veja Cadastrar emitente) — útil pra quem revende a APIFacil e cadastra os CNPJs dos próprios clientes de forma automática. O certificado A1, por ser um arquivo sensível, continua exclusivo do formulário do painel, nunca por API.

CERT

Enviar certificado A1

Na página de detalhe do emitente (depois de cadastrado), envie o arquivo .pfx ou .p12 e a senha. O CNPJ do certificado precisa ser o mesmo do emitente.

CSC

Cadastrar o CSC da NFC-e

Só quem vai emitir NFC-e precisa disso. O CSC (Código de Segurança do Contribuinte) é um segredo compartilhado entre você e a SEFAZ do seu estado, usado para assinar o QR Code impresso no cupom. Ele não é o certificado digital e não sai do certificado: você gera o CSC no portal da SEFAZ e cola no painel, junto com o ID (o número sequencial que aparece ao lado dele).

No Rio Grande do Sul: e-CAC da SEFAZ-RS → Meus Serviços → NFC-e → Manutenção de CSC. Anote o código na hora — a SEFAZ não mostra de novo depois. Guardamos criptografado e nunca exibimos de volta na tela.

CSC errado ou de outro ambiente é a causa da rejeição 464 — Código de Hash no QR-Code difere do calculado. Homologação e produção têm CSC diferentes, então cada emitente (que já é um cadastro por ambiente) leva o seu.

202

Como acompanhar a emissão

Por que a resposta é 202, e não 201

Quando você chama POST /nfce, a API valida na hora tudo o que dá para validar sem falar com o fisco (certificado, CSC, UF habilitada, formas de pagamento, referência repetida) e devolve 202 Accepted com a nota em status: "processando". A numeração, a assinatura, o QR Code e a autorização na SEFAZ acontecem em seguida, em segundo plano — em geral em poucos segundos.

O motivo é que o webservice da SEFAZ é lento e cai. Emitindo de forma síncrona, cada indisponibilidade do fisco vira um timeout no seu PDV — e, pior, uma nova tentativa depois de um timeout pode gerar duas notas autorizadas para a mesma venda. Aqui isso não acontece: a nota é conferida na SEFAZ antes de qualquer reenvio, então uma tentativa repetida nunca vira nota duplicada.

Como o PDV acompanha: guarde o id devolvido no 202 e consulte GET /api/v1/documentos/{id} até o status sair de processando. Na prática a autorização leva poucos segundos quando a SEFAZ está saudável. Se quiser localizar a nota pelo identificador da venda no seu sistema em vez do id, mande referencia_externa na emissão e filtre por ela.

O laço de consulta, na prática: espere cerca de 1 segundo depois do 202 e consulte GET /documentos/{id} a cada 2 segundos. Esse endpoint lê o registro da nota e não entra no limite de 120 emissões por minuto, então o caixa pode consultar à vontade — mas não use POST /documentos/{id}/consultar dentro do laço: ele pergunta à SEFAZ a cada chamada, existe para exceção e tem teto próprio de 30 por minuto.

Se passar de 30 segundos ainda em processando, a SEFAZ provavelmente está lenta: chame POST /documentos/{id}/consultar uma vez e siga consultando o GET a cada 10 segundos. Não reemita a venda — a nota pode já estar autorizada, e reemitir com a mesma referencia_externa é recusado justamente para o caixa não gerar cupom em duplicidade.

STATUS	O QUE SIGNIFICA	O QUE FAZER
processando	Autorização em andamento	Consultar de novo em alguns segundos
autorizado	Autorizada; traz chave, protocolo, qr_code e url_chave	Montar e imprimir o cupom
rejeitado	A SEFAZ recusou; o motivo está em mensagem_retorno	Corrigir e emitir de novo (a numeração recusada não é reaproveitada)
erro	A SEFAZ não respondeu depois de todas as tentativas	Consultar a nota antes de reemitir — ela pode ter sido autorizada

O que imprimir no cupom: quando a nota fica autorizado, a consulta devolve, além do status, os quatro campos que o DANFE-NFCe exige e que o PDV ainda não tem: chave (impressa em grupos de 4 dígitos), protocolo com a data-hora, qr_code — a string que a impressora transforma em imagem — e url_chave, que vai na linha "Consulte pela Chave de Acesso em". Os itens e totais são os que o próprio PDV enviou.

Esses dois últimos também ficam dentro do XML, no grupo infNFeSupl, mas virem na resposta poupa o caixa de abrir um parser de XML no meio da venda.

Ritmo de envio: rajadas acima do rate limit não são perdidas — são aceitas e autorizadas em sequência, e a numeração de cada CNPJ emitente sai sempre em ordem.

POST /api/v1/emitentes/{id}/nfce Emitir NFC-e ▶

Emite uma NFC-e (modelo 65) — a nota do varejo, que substituiu o cupom fiscal, para venda presencial ou entrega em domicílio ao consumidor final. Exige que o emitente tenha certificado A1 e CSC cadastrados.

A resposta é 202 Accepted com a nota em processando: a autorização acontece logo em seguida, em segundo plano. Veja Como acompanhar a emissão para o motivo e para o jeito certo de o PDV acompanhar até virar autorizado.

O consumidor pode não se identificar: basta omitir o objeto destinatario inteiro. Se identificar, o CPF ou CNPJ é obrigatório e o endereço só é enviado ao fisco quando você mandar logradouro (caso de entrega em domicílio, com presenca: 4).

PARÂMETRO	TIPO	OBRIG	DESCRIÇÃO
itens	array	SIM	Ao menos 1 item vendido
itens[].codigo	string	SIM	Seu código interno do produto, até 60 chars
itens[].descricao	string	SIM	Descrição do produto, até 120 chars — é o que sai impresso no cupom
itens[].ncm	string	SIM	8 dígitos, código NCM do produto
itens[].cfop	string	SIM	4 dígitos. Na NFC-e a operação é sempre dentro do estado — normalmente 5102
itens[].quantidade	decimal	SIM	Maior que zero
itens[].valor_unitario	decimal	SIM	Valor unitário em reais
itens[].gtin	string	NÃO	Código de barras do produto (EAN/GTIN), até 14 dígitos
itens[].unidade	string	NÃO	Unidade comercial (UN, KG, CX…), até 6 chars
itens[].origem	integer	NÃO	0 a 8, origem da mercadoria (0 nacional, padrão)
itens[].csosn	string	Se Simples Nacional	3 dígitos. Use no lugar de cst_icms quando o emitente é optante do Simples
itens[].cst_icms	string	Se regime normal	2 dígitos, CST do ICMS
itens[].aliquota_icms	decimal	NÃO	0 a 100, percentual de ICMS
itens[].cst_pis / cst_cofins	string	NÃO	2 dígitos cada
itens[].aliquota_pis / aliquota_cofins	decimal	NÃO	0 a 100 cada
pagamentos	array	SIM	Obrigatório na NFC-e (na NF-e não é). Ao menos uma forma de pagamento
pagamentos[].forma	string	SIM	2 dígitos do meio de pagamento: 01 dinheiro, 03 cartão de crédito, 04 cartão de débito, 17 Pix
pagamentos[].valor	decimal	SIM	Valor pago nessa forma, maior que zero
presenca	integer	NÃO	1 venda presencial no balcão (padrão), 4 entrega em domicílio. Os demais códigos da NF-e (internet, teleatendimento) não valem para NFC-e
destinatario	object	NÃO	Omita quando o consumidor não se identificar. Presente, exige documento
destinatario.documento	string	Se houver destinatário	Só dígitos: CPF (11) ou CNPJ (14)
destinatario.nome	string	NÃO	Até 60 chars
destinatario.logradouro, numero, bairro, codigo_municipio, municipio, uf, cep	string	NÃO	Endereço do consumidor. Só é enviado ao fisco se logradouro vier preenchido — use na entrega em domicílio
serie	integer	NÃO	1 a 889, série do documento (padrão 1). O número é controlado por nós
referencia_externa	string	NÃO	Seu identificador único por emitente (ex: ID da venda no PDV), até 80 chars — evita emitir a mesma nota duas vezes
natureza_operacao	string	NÃO	Até 60 chars, padrão "Venda ao consumidor"
observacao	string	NÃO	Informações complementares, até 5000 chars
ibs_cbs	boolean	NÃO	Envia os grupos de IBS/CBS da reforma tributária (NT 2025.002-RTC). Padrão false: quem define se já é obrigatório para você é o seu regime, confirme com o contador antes de ligar

BASH

curl -X POST https://nts.apifacil.dev/api/v1/emitentes/42/nfce \
  -H "Authorization: SEU_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "referencia_externa": "venda-9912",
    "itens": [
      {
        "codigo": "7891",
        "descricao": "Cafe torrado 500g",
        "ncm": "09012100",
        "cfop": "5102",
        "unidade": "UN",
        "quantidade": 2,
        "valor_unitario": 19.90,
        "csosn": "102"
      }
    ],
    "pagamentos": [
      { "forma": "17", "valor": 39.80 }
    ]
  }'

202 Accepted Aceita, autorização em andamento. Número, chave e protocolo só existem depois da autorização — consulte pelo id

JSON
{
  "documento": {
    "id": 1204,
    "modelo": "65",
    "status": "processando",
    "serie": null,
    "numero": null,
    "chave": null,
    "referencia_externa": "venda-9912",
    "valor_total": "39.80"
  }
}

422 Recusada na própria chamada, antes de ir ao fisco: payload inválido, emitente sem certificado ou sem CSC, UF ainda não habilitada, ou referencia_externa repetida

JSON

{
  "erro": "Emitente sem CSC configurado. A NFC-e exige o Codigo de Seguranca do Contribuinte (codigo + id) alem do certificado digital, para gerar o QR Code do DANFE."
}

Uma recusa aqui não consome número da série: a numeração só é reservada quando a nota segue para o fisco. Rejeição da SEFAZ (por exemplo a 464) não aparece neste 422 — ela chega depois, no status e no mensagem_retorno do documento.

GET /api/v1/documentos Listar documentos ▶

Lista os documentos da conta, paginado, do mais recente para o mais antigo.

PARÂMETRO	TIPO	OBRIG	DESCRIÇÃO
emitente_id	integer	NÃO	Filtra por emitente
modelo	string	NÃO	nfse, 55 (NF-e) ou 65 (NFC-e)
status	string	NÃO	processando, autorizado, rejeitado, cancelado ou erro
por_pagina	integer	NÃO	1 a 100, padrão 25

BASH

curl "https://nts.apifacil.dev/api/v1/documentos?status=autorizado&por_pagina=50" \
  -H "Authorization: SEU_TOKEN"

A resposta é paginada: data traz as notas da página, com current_page, last_page, per_page e total.

200 OK

JSON
{
  "data": [
    {
      "id": 881,
      "emitente_id": 42,
      "modelo": "nfse",
      "status": "autorizado",
      "numero": 42,
      "serie": 1,
      "chave": "43149022266858961000140000000000000126080476084123",
      "valor_total": "1500.00",
      "referencia_externa": null,
      "created_at": "2026-08-26T14:02:11.000000Z"
    }
  ],
  "current_page": 1,
  "last_page": 1,
  "total": 1
}

GET /api/v1/documentos/{id} Detalhe do documento ▶

Retorna o documento com o histórico de eventos (cancelamento, por exemplo). O documento só é retornado se pertencer à conta do token usado — qualquer outro id devolve 404, nunca dado de outra conta.

BASH

curl https://nts.apifacil.dev/api/v1/documentos/881 \
  -H "Authorization: SEU_TOKEN"

200 OK

JSON
{
  "documento": {
    "id": 881,
    "emitente_id": 42,
    "modelo": "nfse",
    "status": "autorizado",
    "numero": 42,
    "chave": "43149022266858961000140000000000000126080476084123",
    "valor_total": "1500.00",
    "codigo_retorno": null,
    "mensagem_retorno": null,
    "eventos": []
  }
}

404 Documento não existe ou não pertence à conta do token

GET /api/v1/documentos/{id}/xml Baixar XML autorizado ▶

Baixa o XML autorizado pelo fisco, guardado pelo prazo legal de 5 anos. Retorna 404 se o documento ainda não tem XML (por exemplo, rejeitado antes de gerar um), ou se o documento não pertence à conta do token.

BASH

curl https://nts.apifacil.dev/api/v1/documentos/881/xml \
  -H "Authorization: SEU_TOKEN" \
  -o nfse-881.xml

200 OK Content-Type: application/xml, corpo é o XML bruto assinado

404 Sem XML ainda (documento não autorizado), ou não pertence à conta

A validade fiscal do documento está neste XML e na chave de acesso — não em nenhum PDF gerado por terceiros.

POST /api/v1/documentos/{id}/consultar Reconsultar no fisco ▶

Reconsulta a situação do documento diretamente no fisco (Sefin Nacional na NFS-e, SEFAZ estadual na NF-e e na NFC-e) e atualiza o registro local. Útil se o status ficou processando por mais tempo que o esperado. Não recebe corpo.

BASH

curl -X POST https://nts.apifacil.dev/api/v1/documentos/881/consultar \
  -H "Authorization: SEU_TOKEN"

200 OK Documento com o status atualizado

JSON
{
  "documento": {
    "id": 881,
    "status": "autorizado",
    "chave": "43149022266858961000140000000000000126080476084123"
  }
}

502 Falha de comunicação com o webservice do fisco; tentar de novo depois

POST /api/v1/documentos/{id}/cancelar Cancelar ▶

Cancela um documento autorizado, mediante justificativa. Só funciona para documento em status=autorizado.

PARÂMETRO	TIPO	OBRIG	DESCRIÇÃO
justificativa	string	SIM	15 a 255 caracteres, exigência do fisco

BASH

curl -X POST https://nts.apifacil.dev/api/v1/documentos/881/cancelar \
  -H "Authorization: SEU_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"justificativa":"Nota emitida com valor incorreto, cliente solicitou cancelamento."}'

200 OK

JSON
{
  "evento": {
    "tipo": "cancelamento",
    "status": "autorizado",
    "justificativa": "Nota emitida com valor incorreto, cliente solicitou cancelamento."
  },
  "documento": {
    "id": 881,
    "status": "cancelado"
  }
}

422 Documento não está autorizado, ou o fisco recusou o cancelamento

CNPJ

Emitentes

Endpoints da API

POST /api/v1/emitentes Cadastrar emitente ▶

Cadastra os dados de um emitente (CNPJ) pela API, sem precisar passar pelo formulário do painel. Pensado pra quem revende a APIFacil: seu sistema cadastra o CNPJ do cliente assim que ele compra, e o cliente (ou você) só precisa entrar no painel uma vez pra subir o certificado A1.

O certificado A1 não entra neste endpoint. Depois de cadastrado por aqui, o emitente aparece no painel (nts.apifacil.dev) pronto pra receber o certificado. Sem certificado, a emissão devolve 422.

PARÂMETRO	TIPO	OBRIG	DESCRIÇÃO
cnpj	string	SIM	14 dígitos, sem pontos, barra ou traço
razao_social	string	SIM	Máx 120 caracteres
nome_fantasia	string	NÃO	Máx 120 caracteres
ie	string	SIM	Inscrição estadual, ou "ISENTO"
im	string	NÃO	Inscrição municipal
crt	integer	SIM	1 Simples Nacional, 2 Simples excesso sublimite, 3 Regime normal, 4 MEI
op_simp_nac	integer	SIM	1 Não optante, 2 Optante MEI, 3 Optante ME/EPP
reg_ap_trib_sn	integer	Obrigatório se op_simp_nac=3	1, 2 ou 3 — regime de apuração dos tributos do Simples Nacional
logradouro	string	SIM	Máx 120 caracteres
numero	string	SIM	Máx 20 caracteres
complemento	string	NÃO	Máx 120 caracteres
bairro	string	SIM	Máx 60 caracteres
codigo_municipio	integer	SIM	Código IBGE do município do emitente (7 dígitos)
municipio	string	SIM	Nome do município
uf	string	SIM	2 letras
cep	string	SIM	Com ou sem traço
telefone	string	NÃO	Com DDD
ambiente	integer	NÃO	1 produção, 2 homologação — padrão 2

Um mesmo CNPJ só pode ter um emitente cadastrado por ambiente (produção e homologação contam separado). Cadastrar de novo o mesmo CNPJ no mesmo ambiente devolve 422.

BASH

curl -X POST https://nts.apifacil.dev/api/v1/emitentes \
  -H "Authorization: SEU_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "cnpj": "12345678000195",
    "razao_social": "Comercio Exemplo Ltda",
    "ie": "ISENTO",
    "crt": 3,
    "op_simp_nac": 1,
    "logradouro": "Av. Ipiranga",
    "numero": "6681",
    "bairro": "Partenon",
    "codigo_municipio": 4314902,
    "municipio": "Porto Alegre",
    "uf": "RS",
    "cep": "90619-900"
  }'

201 Created

JSON
{
  "emitente": {
    "id": 42,
    "cnpj": "12345678000195",
    "razao_social": "Comercio Exemplo Ltda",
    "municipio": "Porto Alegre",
    "uf": "RS",
    "ambiente": 2,
    "certificado_configurado": false,
    "certificado_vence_em_dias": null
  }
}

422 Validação falhou, ou CNPJ já cadastrado neste ambiente

JSON

{
  "erro": "Este CNPJ ja possui um emitente cadastrado neste ambiente."
}

GET /api/v1/emitentes Listar emitentes ▶

Lista os emitentes da conta, com o status do certificado. Não retorna o certificado nem a senha, só se está configurado e a quantos dias vence.

BASH

curl https://nts.apifacil.dev/api/v1/emitentes \
  -H "Authorization: SEU_TOKEN"

200 OK

JSON
{
  "emitentes": [
    {
      "id": 42,
      "cnpj": "12345678000195",
      "razao_social": "Comercio Exemplo Ltda",
      "municipio": "Porto Alegre",
      "uf": "RS",
      "ambiente": 2,
      "certificado_configurado": true,
      "certificado_vence_em_dias": 312
    }
  ]
}

GET /api/v1/emitentes/{id}/numeracao Série e próximo número em uso ▶

Mostra a série e o próximo número de sequência de cada modelo (NFS-e, NF-e, NFC-e) que este emitente já usou, pra acompanhar a numeração sem precisar contar pelo histórico de documentos.

BASH

curl https://nts.apifacil.dev/api/v1/emitentes/42/numeracao \
  -H "Authorization: SEU_TOKEN"

200 OK

JSON
{
  "series": [
    { "modelo": "nfse", "serie": 1, "proximo_numero": 4 }
  ],
  "aviso": null
}

Emitente que nunca emitiu nada volta com series: [] e um aviso explicando que a próxima nota abre na série 1, número 1 — a série só existe no banco a partir da primeira emissão.

LIM

Rate limit

120 emissões por minuto por conta. O limite vale para os endpoints que criam documento — /nfse, /nfce, /nfe e /nfe/inutilizar. Passar do limite devolve 429.

Acompanhar a nota não consome esse limite. GET /documentos, GET /documentos/{id} e o download do XML ficam fora de qualquer teto, então o laço de consulta depois do 202 não disputa espaço com a emissão.

30 consultas ao fisco por minuto por conta, nos dois endpoints que batem no webservice a cada chamada: POST /documentos/{id}/consultar e GET /emitentes/{id}/status-sefaz. Eles existem para exceção — não use o /consultar dentro do laço de acompanhamento. O teto é menor de propósito: consulta em laço leva bloqueio do CNPJ no webservice da SEFAZ, e essa punição é do fisco, não temos como desfazer.

ERR

Rejeições comuns

O que a SEFAZ costuma recusar na NFC-e

CÓDIGO	CAUSA	SOLUÇÃO
464	Código de hash no QR Code difere do calculado	CSC errado, com ID errado, ou do outro ambiente. Homologação e produção têm CSC diferentes — confira em Cadastrar o CSC
539	Duplicidade de NF-e com chave diferente	Já existe nota com esse número. Use referencia_externa para o retry do PDV não duplicar a venda
204	Duplicidade de NF-e	A mesma chave já foi autorizada. Consulte a nota antes de emitir de novo
778	NCM inválido ou inexistente	Conferir o NCM do produto no cadastro
225	Falha no schema do XML	Normalmente campo obrigatório faltando no item ou no pagamento — confira a tabela de parâmetros

Rejeição queima o número. A numeração recusada não volta para a série: se sobrarem números não usados, inutilize a faixa (endpoint de inutilização, documentado na NF-e) para não deixar buraco na sequência.

STATUS HTTP	CAUSA	SOLUÇÃO
401	Token errado ou enviado com "Bearer "	Remover "Bearer ", usar o token puro do painel
403	Emissão em produção sem assinatura ativa	Assinar o serviço Nota Fiscal, ou usar ambiente de homologação
404	Emitente ou documento não pertence à conta	Conferir o ID no painel
422	Sem CSC, sem certificado, UF não habilitada ou payload inválido	A mensagem em erro diz qual dos casos é
429	Acima do rate limit	Respeitar o header Retry-After

Suporte: qualquer dúvida, chame no WhatsApp 55 51 9 8033-1519.