NFS-e Nacional via API: como integrar com a FOX NF-e

O que você precisa antes da primeira chamada

A NFS-e depende de mais variáveis do que a NF-e: além de conta, token e certificado, importam o município, o provedor e o plano contratado. No catálogo atual, a NFS-e Nacional não está incluída no Trial nem no Starter. O cadastro inicia avaliação de 14 dias em homologação e não equivale a autorização fiscal. Guarde o token só no servidor da integração.

• Conta, plano e tenant: plano que inclua NFS-e Nacional; o cabeçalho X-Tenant-ID recebe o slug textual do tenant.
• Token: obtido por POST /api/v1/auth/login e enviado como Authorization: Bearer <SEU_TOKEN>; confirme com GET /api/v1/auth/me.
• Certificado A1: cadastrado para o CNPJ prestador; consulte GET /api/v1/certificates.
• Dados do prestador: CNPJ (14 dígitos), inscrição municipal e endereço com código IBGE do município.
• Ambiente: a documentação indica que a NFS-e tem contrato próprio de ambiente; o schema de emissão publicado não traz campo de ambiente no corpo. Confirme no portal do desenvolvedor como o ambiente do seu tenant está configurado e mantenha a integração em homologação.

Emissão de ponta a ponta

O fluxo é assíncrono e começa pela verificação do município, porque a cobertura é declarada por município e provedor, não presumida. Siga as etapas na ordem e comece por chamadas de leitura. Diante de timeout ou erro 5xx, consulte o recurso antes de reenviar; a documentação vincula a idempotência ao par payload e tenant, e reemitir às cegas pode gerar retrabalho.

1. Confirme a identidade. Chame GET /api/v1/auth/me e verifique o tenant retornado.
2. Verifique o município. Consulte GET /api/v1/nfse/cobertura/{ibge} e leia adesao_nacional, driver, ops e homologacao_externa.
3. Confirme o certificado. Liste com GET /api/v1/certificates.
4. Monte o corpo. Preencha os campos obrigatórios da tabela abaixo, incluindo tomador com cnpj ou cpf.
5. Envie a emissão. Faça POST /api/v1/nfse/emit e guarde nfse_id.
6. Consulte o resultado. Chame GET /api/v1/nfse/{nfse} até um estado final; confira numero_nfse, chave_acesso e codigo_verificacao.
7. Consulte pela chave ou número, se preciso. Use GET /api/v1/nfse/consult/{chave} ou GET /api/v1/nfse/consult/numero/{numero}.
8. Cancele ou substitua. Use POST /api/v1/nfse/{nfse}/cancel (campo justificativa, 15 a 255 caracteres) ou POST /api/v1/nfse/{nfse}/substitute (campo motivo e os dados do novo documento). O 202 indica pedido enfileirado.

Requisição e resposta conforme o OpenAPI

O corpo abaixo parte do exemplo estrutural do OpenAPI vigente, completado com os campos que o próprio schema exige: documento do tomador e códigos de tributação com alíquota. Todos os valores são fictícios e devem ser trocados por dados válidos de homologação. Em vez dos três campos de tributação, o schema também aceita informar cnae. O exemplo não comprova aceitação fiscal.

Verificação do município antes da emissão:

curl -sS "https://www.foxnfe.com.br/api/v1/nfse/cobertura/<CODIGO_IBGE>" \
  -H "Authorization: Bearer <SEU_TOKEN>" \
  -H "X-Tenant-ID: <SLUG_DO_TENANT>" \
  -H "Accept: application/json"

A mesma leitura com o SDK Python oficial (foxnfe no PyPI):

import os
from foxnfe import Client  # pip install foxnfe==1.3.1

client = Client(
    tenant_slug=os.environ["FOXNFE_TENANT"],     # slug do tenant, não número
    token=os.environ["FOXNFE_TOKEN"],            # nunca no código nem em log
    base_url="https://www.foxnfe.com.br/api/v1",  # informe sempre a URL canônica
)

# Somente leitura: capacidades declaradas para um município (código IBGE de 7 dígitos)
cobertura = client.nfse.cobertura_municipio(os.environ["IBGE_MUNICIPIO"])
dados = cobertura.get("data", {})
for campo in ("adesao_nacional", "driver", "ops", "homologacao_externa"):
    print(campo, "=", dados.get(campo))

Corpo da emissão (nfse.json):

{
  "competencia": "0000-00",
  "cnpj_prestador": "00000000000000",
  "inscricao_municipal": "EXEMPLO_FICTICIO",
  "descricao_servico": "EXEMPLO_FICTICIO",
  "codigo_tributacao_nacional": "00.00.00.00",
  "codigo_tributacao_municipal": "EXEMPLO_FICTICIO",
  "aliquota_iss": 0,
  "codigo_municipio_prestacao": "0000000",
  "valor_servico": 1,
  "tomador": {
    "cnpj": "00000000000000",
    "nome": "EXEMPLO_FICTICIO"
  },
  "prestador": {
    "endereco": {
      "logradouro": "EXEMPLO_FICTICIO",
      "numero": "EXEMPLO_FI",
      "bairro": "EXEMPLO_FICTICIO",
      "codigo_municipio": "EXEMPLO",
      "uf": "EX",
      "cep": "00000000"
    }
  }
}

Envio:

curl -sS -X POST "https://www.foxnfe.com.br/api/v1/nfse/emit" \
  -H "Authorization: Bearer <SEU_TOKEN>" \
  -H "X-Tenant-ID: <SLUG_DO_TENANT>" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  --data @nfse.json

Resposta 202 (exemplo estrutural do OpenAPI):

{
  "nfse_id": 1,
  "status": "draft",
  "message": "NFSe enfileirada para emissão"
}

Consulta do resultado:

curl -sS "https://www.foxnfe.com.br/api/v1/nfse/<NFSE_ID>" \
  -H "Authorization: Bearer <SEU_TOKEN>" \
  -H "X-Tenant-ID: <SLUG_DO_TENANT>" \
  -H "Accept: application/json"

Estados do documento e o que fazer

O campo status da NFS-e segue o enum publicado no OpenAPI, que inclui substituted. Trate como autorizada apenas a nota em authorized com identificação preenchida; aceitação HTTP ou enfileiramento não é autorização fiscal. Os estados intermediários pedem nova consulta. A tabela resume a ação recomendada sem presumir comportamento que o contrato público não descreve.

Erros confirmados no contrato e na documentação

Os erros abaixo aparecem no OpenAPI ou no portal do desenvolvedor, com o código textual devolvido no campo error. Eles cobrem autenticação, validação, cobertura e operações não oferecidas para o provedor do município. Se receber uma resposta não descrita aqui, registre o corpo sem o token, consulte o estado do recurso e procure o suporte antes de repetir a chamada.

Limites, cobertura municipal e fontes oficiais

A cobertura depende de documento, município, provedor e ambiente, e não deve ser inferida como universal. Cadastro territorial, adesão ao padrão nacional, parametrização municipal, integração testada e produção liberada são estados diferentes. Antes de prometer emissão ao seu cliente, consulte a matriz pública e o endpoint de cobertura do município. Franquias e condições estão no portal.

• Matriz pública: cobertura municipal de NFS-e da FOX NF-e, sem login. Segundo o llms.txt de 23/09/2026, a base tem 5.571 registros territoriais, com 30 municípios cadastrados com SpeedGov, 1 com Ginfes e 5.540 sem provedor identificado.
• Homologação externa: a documentação informa que homologacao_externa permanece pendente de autorização até o ciclo real com o município.
• Padrão nacional: segundo o Portal Nacional da NFS-e, a NFS-e de padrão nacional “objetiva unificar e simplificar os processos de emissão e guarda desses documentos em todo o território nacional”, e “a adesão ao padrão nacional deverá ser ratificada pelo município através da assinatura do Termo de Adesão”.
• IBS e CBS: no cronograma da Receita Federal (Ato Conjunto RFB/CGIBS nº 4/2026), a NFS-e de serviços em geral está no marco de 1º de outubro de 2026, e categorias específicas têm outras datas. Veja o cronograma do IBS e da CBS na nota fiscal.
• Planos: a NFS-e Nacional não está incluída no Trial nem no Starter no catálogo atual; consulte planos e condições no portal FOX NF-e (login necessário).
• Agentes de IA: veja o guia do servidor MCP da FOX NF-e.

Perguntas frequentes

Estas respostas resumem o contrato público da API, a documentação do desenvolvedor e as fontes oficiais consultadas em 23/09/2026. Elas descrevem a integração, não o enquadramento fiscal do seu serviço. Para código de tributação, alíquota de ISS e regime, consulte o seu contador e a legislação do município. Confira o OpenAPI vigente antes de publicar a integração.

Autoria e método

Elaborado pela equipe fiscal e de engenharia da Central Fox Tecnologia LTDA com auxílio de IA a partir do contrato público da API e das fontes oficiais listadas; exemplos conferidos contra o OpenAPI vigente. Conteúdo informativo; não substitui orientação contábil ou jurídica. Atualizado em 23/09/2026.