NF-e modelo 55 API

USO

Quando usar NF-e

A NF-e documenta circulação de mercadoria quando o destinatário está identificado: outra empresa, um consumidor em outro estado, ou você mesmo numa transferência entre filiais. Venda de balcão ao consumidor final dentro do estado é NFC-e modelo 65, que é mais simples e imprime cupom em vez de DANFE. Serviço é NFS-e.

SITUAÇÃO	DOCUMENTO
Venda para outra empresa (B2B)	NF-e (55)
Venda para consumidor em outro estado	NF-e (55)
Remessa, devolução, transferência entre filiais	NF-e (55)
Venda no balcão ao consumidor final, mesma UF	NFC-e (65)
Prestação de serviço	NFS-e

ESC

Escopo e limitações

Leia antes de planejar a integração

Em preparação — ainda não emite em nenhum estado. A NF-e continua desligada enquanto validamos o fluxo de credenciamento; qualquer chamada de emissão devolve 422. Esta página existe para você conhecer o contrato desde já, mas não feche contrato contando com ela. Quem vende ao consumidor final no balcão já tem a NFC-e (modelo 65) emitindo em produção no Rio Grande do Sul.

A emissão de NF-e é síncrona, diferente da NFS-e e da NFC-e, que respondem 202 e terminam a autorização em segundo plano. A resposta já volta 201 com chave e protocolo, ou 422 com a rejeição da SEFAZ. Use sempre referencia_externa: se a sua chamada der timeout, é ela que impede uma nova tentativa de gerar uma segunda nota para o mesmo pedido.

Contingência offline (tpEmis 9) ainda não está implementada. Se a SEFAZ estiver fora, a emissão falha em vez de gerar a nota em contingência para transmitir depois.

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.

POST

Emissão

Endpoints da API

POST /api/v1/emitentes/{id}/nfe Emitir NF-e ▶

Emite uma NF-e (modelo 55). O destinatário é obrigatório e completo, com endereço — é ele que define se a operação é interna ou interestadual e, portanto, a tributação. Exige emitente com certificado A1 cadastrado.

PARÂMETRO	TIPO	OBRIG	DESCRIÇÃO
destinatario.documento	string	SIM	Só dígitos: CPF (11) ou CNPJ (14)
destinatario.nome	string	SIM	Razão social ou nome, até 60 chars
destinatario.logradouro, numero, bairro, municipio, uf, cep	string	SIM	Endereço completo do destinatário
destinatario.codigo_municipio	integer	SIM	7 dígitos, código IBGE do município do destinatário
destinatario.indicador_ie	integer	NÃO	1 contribuinte de ICMS, 2 isento, 9 não contribuinte
destinatario.ie	string	NÃO	Inscrição estadual, até 20 chars. Obrigatória na prática quando indicador_ie é 1
destinatario.email, complemento, telefone	string	NÃO	Complementares
itens	array	SIM	1 a 990 itens
itens[].codigo	string	SIM	Seu código interno do produto, até 60 chars
itens[].descricao	string	SIM	Descrição do produto, até 120 chars
itens[].ncm	string	SIM	8 dígitos, código NCM
itens[].cfop	string	SIM	4 dígitos. Começa em 5 na operação interna, em 6 na interestadual
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 (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
itens[].cst_pis / cst_cofins	string	Se regime normal	2 dígitos cada. O CRT não distingue Lucro Presumido de Lucro Real, então não existe alíquota padrão segura — informe
itens[].aliquota_pis / aliquota_cofins	decimal	Se regime normal	0 a 100 cada
pagamentos	array	NÃO	Opcional na NF-e (na NFC-e é obrigatório). Quando enviado, exige forma e valor
pagamentos[].forma	string	Se houver pagamentos	2 dígitos: 01 dinheiro, 03 crédito, 04 débito, 15 boleto, 17 Pix, 90 sem pagamento
pagamentos[].valor	decimal	Se houver pagamentos	Maior que zero
natureza_operacao	string	NÃO	Até 60 chars, ex: "Venda de mercadoria", "Devolucao de venda"
modalidade_frete	integer	NÃO	0 a 9. 0 por conta do emitente, 1 por conta do destinatário, 9 sem frete
serie	integer	NÃO	1 a 889 (padrão 1). O número é controlado por nós
referencia_externa	string	NÃO	Seu identificador único por emitente (ex: número do pedido), até 80 chars — evita emitir a mesma nota duas vezes
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: confirme com o contador antes de ligar

BASH

curl -X POST https://nts.apifacil.dev/api/v1/emitentes/42/nfe \
  -H "Authorization: SEU_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "referencia_externa": "pedido-4471",
    "natureza_operacao": "Venda de mercadoria",
    "destinatario": {
      "documento": "98765432000110",
      "nome": "CLIENTE ALFA LTDA",
      "indicador_ie": 1,
      "ie": "0961234567",
      "logradouro": "Rua Sinimbu",
      "numero": "1500",
      "bairro": "Centro",
      "codigo_municipio": 4305108,
      "municipio": "Caxias do Sul",
      "uf": "RS",
      "cep": "95020000"
    },
    "itens": [
      {
        "codigo": "SKU-118",
        "descricao": "Camiseta algodao M",
        "ncm": "61091000",
        "cfop": "5102",
        "unidade": "UN",
        "quantidade": 10,
        "valor_unitario": 69.98,
        "origem": 0,
        "csosn": "102"
      }
    ],
    "pagamentos": [
      { "forma": "15", "valor": 699.80 }
    ]
  }'

201 Created Autorizada pela SEFAZ. A chave de acesso e o protocolo já vêm na resposta

JSON
{
  "documento": {
    "id": 903,
    "modelo": "55",
    "status": "autorizado",
    "serie": 1,
    "numero": 1,
    "chave": "43250812345678000195550010000000011000000012",
    "protocolo": "143250000000002",
    "codigo_retorno": "100",
    "mensagem_retorno": "Autorizado o uso da NF-e",
    "valor_total": "699.80"
  }
}

422 Payload inválido, emitente sem certificado, ou rejeição da SEFAZ

JSON

{
  "erro": "Emitente de regime normal (CRT 3): informe itens[].aliquota_pis."
}

POST /api/v1/documentos/{id}/carta-correcao Carta de correção ▶

Registra uma CC-e (carta de correção eletrônica) na nota já autorizada. Serve para corrigir erro que não altera valores, destinatário nem data de emissão — por exemplo, descrição do produto ou dados de transporte. Se o erro for de valor ou de destinatário, o caminho é cancelar e emitir de novo.

PARÂMETRO	TIPO	OBRIG	DESCRIÇÃO
texto	string	SIM	Entre 15 e 1000 caracteres. É o texto que vai para o fisco e fica público na consulta da nota

BASH

curl -X POST https://nts.apifacil.dev/api/v1/documentos/903/carta-correcao \
  -H "Authorization: SEU_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"texto":"Onde se le transportadora XYZ, leia-se transportadora ABC."}'

200 OK Devolve o evento registrado e o documento atualizado

POST /api/v1/emitentes/{id}/nfe/inutilizar Inutilizar numeração ▶

Declara à SEFAZ que uma faixa de números não vai ser usada. Serve para fechar buraco na sequência — números queimados por rejeição ou por falha no seu sistema. A numeração precisa estar mesmo livre: número já autorizado não pode ser inutilizado, só cancelado.

PARÂMETRO	TIPO	OBRIG	DESCRIÇÃO
serie	integer	SIM	1 a 889
numero_inicial	integer	SIM	Primeiro número da faixa
numero_final	integer	SIM	Último número da faixa, maior ou igual ao inicial
justificativa	string	SIM	Entre 15 e 255 caracteres

BASH

curl -X POST https://nts.apifacil.dev/api/v1/emitentes/42/nfe/inutilizar \
  -H "Authorization: SEU_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "serie": 1,
    "numero_inicial": 45,
    "numero_final": 48,
    "justificativa": "Falha no sistema emissor deixou a faixa sem uso"
  }'

201 Created Inutilização homologada pela SEFAZ

422 A SEFAZ recusou — normalmente porque algum número da faixa já foi usado

GET /api/v1/documentos/{id}/danfe DANFE em PDF ▶

Gera o DANFE (a representação impressa da NF-e) em PDF, para acompanhar a mercadoria. Responde application/pdf. O documento com valor legal continua sendo o XML — o DANFE é só a via de papel.

BASH

curl https://nts.apifacil.dev/api/v1/documentos/903/danfe \
  -H "Authorization: SEU_TOKEN" \
  -o danfe-903.pdf

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 NF-e

CÓDIGO	CAUSA	SOLUÇÃO
100	Autorizado o uso da NF-e	—
135	Evento registrado e vinculado à NF-e	Cancelamento ou carta de correção aceitos
204	Duplicidade de NF-e	A mesma chave já foi autorizada. Consulte antes de emitir de novo
539	Duplicidade de NF-e com chave diferente	Já existe nota com esse número. Use referencia_externa para o retry não duplicar
209	IE do destinatário inválida	Conferir a inscrição estadual, ou marcar indicador_ie como 2 (isento) ou 9 (não contribuinte)
778	NCM inválido ou inexistente	Conferir o NCM do produto no cadastro
225	Falha no schema do XML	Normalmente campo obrigatório faltando — confira a tabela de parâmetros
228	Data de emissão muito atrasada	Emitir na data corrente

Rejeição queima o número. A numeração recusada não volta para a série. Se sobrarem números não usados, feche a faixa com inutilização.

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	Payload inválido, sem certificado, ou rejeição da SEFAZ	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.