NFS-e Padrão Nacional API

CNPJ

O que é um emitente

Um emitente é o CNPJ que assina a NFS-e — a sua empresa, ou a de um cliente seu, se você emite em nome de terceiros. Cada emitente tem cadastro, certificado A1 e numeração de documento próprios. Uma mesma conta APIFacil pode ter vários emitentes: por exemplo, um escritório de contabilidade cadastra um emitente para cada cliente que ele emite nota, e uma empresa com CNPJ em duas cidades cadastra um emitente por CNPJ.

Divisão de responsabilidade: o painel serve só para cadastro (emitente + certificado), feito uma vez, por humano. A emissão de cada nota é sempre uma chamada de API, feita pelo seu sistema. Não existe emissão pela tela do painel.

ESC

Escopo: só Padrão Nacional

O que este módulo atende

O módulo integra com o Padrão Nacional da NFS-e (Sefin Nacional) e cobre 100% dos municípios que já aderiram, em qualquer estado do país — sem escolha de UF, sem integração extra por cidade. Município que mantém emissor próprio da prefeitura exigiria outra integração, com outro leiaute, e não é atendido. Antes de emitir para um cliente novo, confira se o município dele já aderiu — a tabela é sincronizada todo dia às 5h e o gate de emissão recusa antes de gastar uma chamada com o fisco se o município ainda não aderiu. A partir de 1º de novembro de 2026 a adesão ao Padrão Nacional se torna obrigatória para prestadores do Simples Nacional (ME/EPP), então essa cobertura cresce sozinha até lá.

NF-e (produto, modelo 55) está fora do escopo atual desta API. O foco é NFS-e (serviço) pelo Padrão Nacional.

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.

BASH

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

Assinatura: emitir NFS-e 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.

O município é buscado por nome (campo com busca) e só lista município que já emite pelo Padrão Nacional. Se o emitente já estiver cadastrado num município que ainda não aderiu, ele continua aparecendo, sinalizado, para não perder o dado ao editar.

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}/nfse Emitir NFS-e ▶

Emite uma NFS-e para o emitente informado. A emissão é assíncrona no fisco: a resposta já volta com o documento criado em status=processando, e o status vira autorizado ou rejeitado conforme a Sefin Nacional responde.

PARÂMETRO	TIPO	OBRIG	DESCRIÇÃO
codigo_tributacao_nacional	string	SIM	6 dígitos, código nacional do serviço (item + subitem da Lista Anexa à LC 116/2003). Consulte a tabela em gov.br/nfse ou com seu contador — exemplo real: 010201 (análise de sistemas)
descricao	string	SIM	Discriminação do serviço, texto livre (máx 2000 chars)
valor_servico	decimal	SIM	Valor total do serviço em reais, maior que zero. Ex: 1500.00
tributacao_issqn	integer	NÃO	1 Operação tributável (padrão), 2 Imune, 3 Exportação de serviço, 4 Não incidência
retencao_issqn	integer	NÃO	1 Não retido (padrão), 2 Retido pelo tomador
percentual_aproximado_tributos_sn	decimal	Recomendado se o emitente é Simples Nacional	0 a 99.99, percentual aproximado dos tributos (Lei da Transparência, Lei 12.741/2012). Só é usado quando o emitente é optante do Simples Nacional (op_simp_nac 2 ou 3); ignorado nos demais casos. Sem valor, assume 0
referencia_externa	string	NÃO	Seu identificador único por emitente (ex: ID do pedido no seu sistema), até 80 chars — evita emitir a mesma nota duas vezes
serie	integer	NÃO	1 a 99999, série do documento (padrão 1)
competencia	date	NÃO	Formato YYYY-MM-DD, padrão a data de emissão
codigo_municipio_prestacao	integer	NÃO	Código IBGE (7 dígitos) do município onde o serviço foi de fato prestado, só se for diferente do município do emitente
tomador.documento	string	SIM	Só dígitos: CPF (11) ou CNPJ (14) do tomador
tomador.nome	string	SIM	Nome / razão social do tomador, até 300 chars
tomador.email	string	NÃO	E-mail do tomador, até 120 chars
tomador.inscricao_municipal	string	NÃO	IM do tomador, se pessoa jurídica
tomador.logradouro	string	SIM	Endereço do tomador, até 255 chars
tomador.numero	string	SIM	Número do endereço, até 60 chars
tomador.bairro	string	SIM	Bairro do tomador, até 60 chars
tomador.codigo_municipio	integer	SIM	Código IBGE do município do tomador (7 dígitos) — mesma tabela usada no cadastro do emitente
tomador.cep	string	SIM	CEP do tomador, com ou sem traço
tomador.telefone	string	NÃO	Telefone do tomador com DDD, até 14 chars

BASH

curl -X POST https://apifacil.dev/api/v1/emitentes/42/nfse \
  -H "Authorization: SEU_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "codigo_tributacao_nacional": "010201",
    "descricao": "Consultoria em TI",
    "valor_servico": 1500.00,
    "tomador": {
      "documento": "12345678900",
      "nome": "Cliente Final",
      "logradouro": "Rua Exemplo",
      "numero": "100",
      "bairro": "Centro",
      "codigo_municipio": 4314902,
      "cep": "90000-000"
    }
  }'

202 Accepted Documento aceito e enfileirado para emissão (chegue como "processando"; consulte depois para saber quando autorizar)

JSON
{
  "documento": {
    "id": 881,
    "status": "processando",
    "numero": 42,
    "serie": 1,
    "valor_total": "1500.00"
  }
}

422 Validação falhou, ou emitente sem certificado, ou município fora do Padrão Nacional

JSON

{
  "erro": "CNPJ do tomador invalido (digito verificador nao confere)."
}

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
status	string	NÃO	processando, autorizado, rejeitado, cancelado ou erro
por_pagina	integer	NÃO	1 a 100, padrão 25

BASH

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

A resposta é a paginação padrão do Laravel: data, current_page, last_page, total. O painel usa a mesma listagem, com filtro e paginação, em nts.apifacil.dev/documentos.

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://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 pela Sefin Nacional, 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://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 na Sefin Nacional 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://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 a Sefin Nacional; 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://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 de NFS-e 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://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://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 (NF-e, NFS-e) que este emitente já usou, pra acompanhar a numeração sem precisar contar pelo histórico de documentos.

BASH

curl https://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.

MAP

Cobertura de municípios

Quem já emite pelo Padrão Nacional

Cobrimos 100% dos municípios que já aderiram ao Padrão Nacional, em qualquer estado — a API funciona do mesmo jeito no país inteiro, sem escolha de UF nem integração extra por cidade. A partir de 1º de novembro de 2026 o Padrão Nacional passa a ser obrigatório para prestadores do Simples Nacional (ME/EPP) em todo o Brasil. A tabela abaixo mostra a adesão de hoje, que só cresce até lá.

RECORTE	EMITEM PELO PADRÃO NACIONAL — TODOS COBERTOS
Brasil	2.706 de 5.570 municípios
Rio Grande do Sul	277 de 497 municípios
São Paulo	382 de 645 municípios

A lista é sincronizada todo dia às 5h a partir da planilha oficial de adesões do governo. Se o município do seu cliente aderir amanhã, a emissão libera sozinha, sem precisar de deploy nem cadastro novo.

Município que ainda mantém emissor próprio da prefeitura, fora do Padrão Nacional, é recusado antes de gastar uma chamada com o fisco, com uma mensagem explicando o motivo.

LIM

Rate limit

120 requisições por minuto por conta, em todos os endpoints deste módulo. Passar do limite devolve 429.

ERR

Erros comuns

STATUS	CAUSA	SOLUÇÃO
401	Token errado ou enviado com "Bearer "	Remover "Bearer ", usar o token puro do painel
404	Emitente ou documento não pertence à conta	Conferir o ID no painel
422	Município fora do Padrão Nacional	Confira a adesão em Cobertura antes de emitir
422	Emitente sem certificado configurado	Enviar o certificado A1 no painel
422	Emissão em produção sem assinatura ativa	Assinar o serviço Nota Fiscal, ou usar ambiente de homologação
429	Mais de 120 requisições por minuto	Respeitar o header Retry-After
502	Falha de comunicação com a Sefin Nacional	Reconsultar depois; o documento fica em "processando"

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