Como emitir NFC-e via API com a FOX NF-e

O que você precisa antes da primeira chamada

Antes de enviar a primeira NFC-e, confirme conta, credenciais, certificado e ambiente. O cadastro no portal inicia uma avaliação de 14 dias em homologação, e criar a conta não equivale a autorização fiscal. Configure a empresa, o certificado digital A1 e os dados fiscais no portal. Guarde o token apenas no servidor da sua integração, em variável de ambiente ou cofre de segredos, nunca no navegador nem em log.

• Conta e tenant: o cabeçalho X-Tenant-ID recebe o slug textual do tenant (por exemplo minha-empresa), não um número nem UUID.
• Token: obtido por POST /api/v1/auth/login (campos email e password) e enviado como Authorization: Bearer <SEU_TOKEN>.
• Certificado A1: cadastrado e válido para a empresa emitente; a listagem fica em GET /api/v1/certificates e a validação em POST /api/v1/certificates/validate.
• Ambiente: use homologação durante a integração. A resposta de emissão informa o ambiente aplicado no campo ambiente (valores documentados: homologacao e producao). Documentos de homologação não têm valor fiscal.

# Confirme token e tenant antes de qualquer emissão (somente leitura)
curl -sS "https://www.foxnfe.com.br/api/v1/auth/me" \
  -H "Authorization: Bearer <SEU_TOKEN>" \
  -H "X-Tenant-ID: <SLUG_DO_TENANT>" \
  -H "Accept: application/json"

Emissão de ponta a ponta

O fluxo é assíncrono: a API aceita o pedido, enfileira o documento e o processamento segue fora da requisição. Por isso a integração precisa guardar o identificador devolvido e consultar o resultado depois. Siga as etapas abaixo na ordem, começando por chamadas de leitura. Diante de timeout ou erro 5xx, consulte o recurso antes de reenviar, para não criar duplicidade.

1. Confirme a identidade. Chame GET /api/v1/auth/me e verifique se o tenant retornado é o esperado.
2. Confirme o certificado. Liste com GET /api/v1/certificates e confira se há certificado A1 válido para a empresa emitente.
3. Monte o corpo. Preencha destinatario (com cpf_cnpj, nome e endereco) e pelo menos um item em itens, conforme a tabela de campos abaixo.
4. Envie a emissão. Faça POST /api/v1/nfce/emit. Resposta 202 significa documento enfileirado.
5. Guarde o identificador e confira o ambiente. Salve invoice_id e verifique se ambiente é homologacao durante os testes.
6. Consulte o resultado. Chame GET /api/v1/nfce/{invoice} até um estado final. Só authorized com protocolo preenchido confirma a autorização.
7. Baixe XML e DANFE. Com o documento autorizado, use GET /api/v1/nfce/{invoice}/xml e GET /api/v1/nfce/{invoice}/pdf.
8. Cancele quando necessário. Envie POST /api/v1/nfce/{invoice}/cancel com justificativa de 15 a 255 caracteres; a resposta 202 indica cancelamento enfileirado, não concluído.

Requisição e resposta conforme o OpenAPI

Os blocos abaixo reproduzem o exemplo estrutural publicado no OpenAPI vigente. Todos os valores são fictícios e devem ser trocados por dados válidos do seu ambiente de homologação; o exemplo não comprova aceitação fiscal. Salve o corpo como nfce.json e envie com curl. Nesta versão, o SDK Python oficial não expõe um método dedicado à NFC-e, por isso o exemplo usa apenas HTTP.

Corpo da requisição (nfce.json):

{
  "destinatario": {
    "cpf_cnpj": "EXEMPLO_FICTICIO",
    "nome": "EXEMPLO_FICTICIO",
    "endereco": {
      "logradouro": "EXEMPLO_FICTICIO",
      "numero": "EXEMPLO_FICTICIO",
      "bairro": "EXEMPLO_FICTICIO",
      "municipio": "EXEMPLO_FICTICIO",
      "uf": "EX",
      "cep": "00000000"
    }
  },
  "itens": [
    {
      "produto": "EXEMPLO_FICTICIO",
      "ncm": "00000000",
      "cfop": "0000",
      "unidade": "EXEMPL",
      "quantidade": 1,
      "valor_unitario": 1
    }
  ]
}

Envio:

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

Resposta 202 (exemplo estrutural do OpenAPI; o campo ambiente pode vir como producao ou homologacao, e o status segue o enum da tabela de estados):

{
  "invoice_id": 1,
  "status": "draft",
  "message": "NF-e enfileirada para emissão",
  "ambiente": "producao"
}

Consulta do resultado:

curl -sS "https://www.foxnfe.com.br/api/v1/nfce/<INVOICE_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 segue o enum publicado no OpenAPI. Trate como autorizada apenas a NFC-e em authorized com protocolo do autorizador; aceitação HTTP ou enfileiramento não é autorização fiscal. Os estados intermediários pedem nova consulta, nunca reemissão às cegas. A tabela resume a ação recomendada para cada valor, 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. Nenhum código de rejeição da SEFAZ é listado aqui, porque ele vem no campo rejection da consulta com o texto do autorizador. Se receber uma resposta não descrita nesta página, registre o corpo sem o token, consulte o status do recurso e procure o suporte antes de repetir a chamada.

Limites, cobertura e homologação simulada

A disponibilidade depende de documento, UF, ambiente e configuração da empresa; não presuma suporte a todas as variantes a partir do catálogo. Homologação não tem valor fiscal. A NFC-e off-line fica estacionada e sinalizada, e a contingência SVC documentada vale para o modelo 55. Franquias e condições de cada plano estão no portal, após login.

• Homologação simulada por modelo: GET /api/v1/nfe/homologacao lista cenários e POST /api/v1/nfe/homologacao/run aceita modelo 55 ou 65. No modo padrão simulated, o protocolo é sintético e nada é transmitido à SEFAZ; serve para testar leitura de XML e DANFE, não para provar autorização.
• Leiaute oficial: o Portal Nacional da NF-e publica o Manual de Orientação ao Contribuinte (MOC) versão 7.0, que abrange NF-e e NFC-e, e o Manual de Padrões Técnicos do DANFE-NFC-e e QR Code, versão 6.0.
• IBS e CBS: no cronograma divulgado pela Receita Federal (Ato Conjunto RFB/CGIBS nº 4/2026), a NFC-e está no marco de 3 de agosto de 2026. Veja o resumo em cronograma do IBS e da CBS na nota fiscal.
• Planos: consulte documentos incluídos e limites em planos e condições no portal FOX NF-e (login necessário).
• Agentes de IA: a integração por MCP está descrita no guia do servidor MCP da FOX NF-e.

Perguntas frequentes

Estas respostas resumem o contrato público da API e a documentação do desenvolvedor em 23/09/2026. Elas descrevem o comportamento da integração, não a situação fiscal da sua empresa. Para enquadramento tributário, CFOP, NCM e regime, consulte o seu contador. Para detalhes que mudam com o tempo, confira o portal do desenvolvedor e 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.