Portal do Desenvolvedor FOX NF-e

Integração fiscal por API REST, com SDKs oficiais e webhooks assinados. Esta documentação descreve o que já está em operação e sinaliza, com honestidade, o que ainda está em revisão.

URL base e verificação de saúde #

A URL base canônica é https://www.foxnfe.com.br/api/v1. Os endpoints protegidos respondem 401 sem credenciais válidas — isso verifica a conectividade do endpoint e a exigência de autenticação, sem comprovar os fluxos autenticados. Use uma chamada de leitura para validar conectividade e TLS antes de escrever qualquer fluxo de emissão.

# Sem token: deve responder 401 (autenticação exigida)
curl -i https://www.foxnfe.com.br/api/v1/auth/me

# Com token de servidor (nunca embutido no front-end)
curl -s https://www.foxnfe.com.br/api/v1/auth/me \
  -H "Authorization: Bearer $FOXNFE_TOKEN" \
  -H "X-Tenant-ID: $FOXNFE_TENANT"

Primeiros passos, na ordem certa #

Uma primeira integração segura lê antes de escrever. Comece confirmando identidade e configuração; só depois avance para emissão em ambiente de homologação.

1. Confirme o token com GET /auth/me — retorna o usuário e o tenant vinculados ao token.
2. Inspecione o webhook com GET /webhooks/config — mostra se há URL configurada, sem revelar o segredo.
3. Escolha o ambiente pelo campo ambiente do payload (2 = homologação) — veja Autenticação e ambientes.
4. Trate o 202 como "enfileirado", não como "autorizado pela SEFAZ" — veja Emissão assíncrona.

Autenticação e ambientes #

Cabeçalhos obrigatórios

Obter e reutilizar o token

Um token pode ser obtido por POST /auth/login (e-mail e senha) ou injetado a partir de um segredo já persistido. Em serviços de longa duração, prefira injetar um token guardado no cofre a autenticar a cada chamada.

#!/usr/bin/env python3
# Somente biblioteca padrão. Credenciais vêm do ambiente; o token é gravado
# num arquivo 0600 (ou entregue ao cofre) e NUNCA impresso no stdout.
import json, os, urllib.request

body = json.dumps({                       # json.dumps escapa o conteúdo corretamente
    "email":    os.environ["FOXNFE_EMAIL"],
    "password": os.environ["FOXNFE_PASSWORD"],
}).encode("utf-8")

req = urllib.request.Request(
    "https://www.foxnfe.com.br/api/v1/auth/login",
    data=body, method="POST",
    headers={
        "Content-Type": "application/json",
        "Accept":       "application/json",
        "X-Tenant-ID":  os.environ["FOXNFE_TENANT"],
    },
)
with urllib.request.urlopen(req, timeout=30) as resp:
    token = json.load(resp)["token"]      # não faça print(token)

# Use um caminho novo em um diretório privado, pertencente ao usuário do serviço.
# O_EXCL recusa arquivos existentes e links simbólicos; nunca sobrescreve um token.
# No Windows, use um cofre ou controle de acesso equivalente em vez deste exemplo POSIX.
fd = os.open(os.environ["FOXNFE_TOKEN_FILE"], os.O_WRONLY | os.O_CREAT | os.O_EXCL, 0o600)
with os.fdopen(fd, "w") as f:
    f.write(token)
print("token obtido e gravado com permissão 600")   # confirma sem revelar o segredo

Produção × homologação (NF-e/NFC-e)

Na NF-e/NFC-e, o ambiente fiscal é decidido pelo campo ambiente dentro do payload de emissão: 1 para produção e 2 para homologação. Esse valor viaja no corpo da requisição, não na URL. Um mesmo token e uma mesma URL base atendem os dois ambientes — a diferença está no que você declara no documento. Para a NFSe (Padrão Nacional), o contrato de ambiente é próprio e está em revisão; confira o estado em Estado dos domínios fiscais antes de assumir a mesma convenção.

Emissão assíncrona: o que o 202 significa

A emissão é assíncrona. Ao aceitar uma emissão, a API responde imediatamente com o recurso em estado pending (nas respostas HTTP diretas isso corresponde a 202 Accepted). Isso quer dizer enfileirado para processamento — e não autorizado pela SEFAZ.

Idempotência, erros e novas tentativas

A idempotência de emissão está vinculada ao par payload/tenant: reenviar o mesmo documento para o mesmo tenant não deve gerar duplicidade silenciosa. Diante de um status ambíguo (timeout, 5xx, conexão perdida), não reemita às cegas — primeiro consulte o status do recurso e só então decida. Erros de validação chegam como 422 com o mapa errors; erros de autenticação, como 401/403.

SDKs oficiais #

Node.js (≥ 18)

Instale a partir do tarball oficial e crie o cliente com a URL base explícita. As classes de módulo (Nfe, Nfse, Webhook, Reference, Documents, NfeEvents, Distribuicao, Rtc, Support) recebem o cliente no construtor.

# A partir do download oficial (recomendado)
npm install https://docs.foxnfe.com.br/downloads/foxnfe-1.3.0.tgz

# Ou a partir do arquivo local entregue à sua equipe
npm install ./foxnfe-1.3.0.tgz

import { createClient, Webhook } from 'foxnfe';

const client = createClient({
  tenantSlug: process.env.FOXNFE_TENANT,      // slug, não UUID
  token:      process.env.FOXNFE_TOKEN,       // token do cofre/env
  baseUrl:    'https://www.foxnfe.com.br/api/v1',
});

// Chamadas de leitura para validar a integração:
const me = await client.me();
// A resposta é aninhada: { user: { …, tenant_id }, tenant: { id, slug, name, status }, subscription, abilities }
console.log('tenant (slug):', me.tenant?.slug ?? '(sem tenant)');
console.log('tenant_id:', me.user?.tenant_id ?? '(sem tenant)');

const webhook = new Webhook(client);
const cfg = await webhook.getConfig();
console.log('webhook configurado?', cfg.configured);

Python (≥ 3.9)

Instale a wheel oficial e instancie Client com base_url. Os módulos são expostos como propriedades (client.nfe, client.nfse, client.webhook, client.reference, client.documents, client.nfe_events, client.distribuicao, client.rtc, client.support).

pip install https://docs.foxnfe.com.br/downloads/foxnfe-1.3.0-py3-none-any.whl
# Ou local:
pip install ./foxnfe-1.3.0-py3-none-any.whl

import os
from foxnfe import Client

client = Client(
    tenant_slug=os.environ["FOXNFE_TENANT"],   # slug, não UUID
    token=os.environ["FOXNFE_TOKEN"],          # token do cofre/env
    base_url="https://www.foxnfe.com.br/api/v1",
)

me = client.me()
# Resposta aninhada: {"user": {..., "tenant_id"}, "tenant": {"id", "slug", ...}, ...}
print("tenant (slug):", (me.get("tenant") or {}).get("slug", "(sem tenant)"))
print("tenant_id:", (me.get("user") or {}).get("tenant_id", "(sem tenant)"))

cfg = client.webhook.get_config()
print("webhook configurado?", cfg.get("configured"))

PHP (≥ 8.1)

O pacote depende de Guzzle. Aponte um repositório Composer do tipo package para o zip oficial e então instale por composer require.

{
  "repositories": [
    {
      "type": "package",
      "package": {
        "name": "foxdigital/foxnfe-php",
        "version": "1.3.0",
        "dist": {
          "type": "zip",
          "url": "https://docs.foxnfe.com.br/downloads/foxnfe-php-1.3.0.zip"
        },
        "require": { "php": ">=8.1", "guzzlehttp/guzzle": "^7.0" },
        "autoload": { "psr-4": { "FoxNfe\\": "src/" } }
      }
    }
  ]
}

composer require foxdigital/foxnfe-php:1.3.0

<?php
require 'vendor/autoload.php';

use FoxNfe\Client;

$client = (new Client(
    tenantSlug: getenv('FOXNFE_TENANT'),                 // slug, não UUID
    baseUrl:    'https://www.foxnfe.com.br/api/v1',
))->withToken(getenv('FOXNFE_TOKEN'));                   // token do cofre/env

$me = $client->me();
// Resposta aninhada: ['user' => [..., 'tenant_id'], 'tenant' => ['id','slug',...], ...]
echo 'tenant (slug): ' . ($me['tenant']['slug'] ?? '(sem tenant)') . PHP_EOL;
echo 'tenant_id: '     . ($me['user']['tenant_id'] ?? '(sem tenant)') . PHP_EOL;

$cfg = $client->webhook()->getConfig();
echo 'webhook configurado? ' . var_export($cfg['configured'] ?? false, true) . PHP_EOL;

• Node.js consumer.mjs — importa foxnfe, mock de fetch
• Python consumer.py — importa foxnfe, adapter requests simulado
• PHP consumer.php — usa FoxNfe\Client, handler Guzzle simulado

Os contratos dos módulos novos (referência, documentos, CC-e, recebidos, catálogo de webhooks) têm demos offline distribuídos junto de cada pacote: examples/reference_documents_offline_demo.{mjs,py,php}.

Webhooks #

Configurar o webhook

A configuração é por tenant. O segredo deve ser definido por você: gere um valor aleatório de alta entropia, envie-o em webhook_secret e guarde a mesma cópia na sua integração — é ela que valida a assinatura. Ao omitir webhook_secret numa atualização, o valor atual é preservado; o DELETE apenas desativa o webhook (active: false) e preserva o segredo para reativação por um novo PUT. A API nunca devolve o segredo: tanto GET quanto PUT retornam apenas secret_preview mascarado.

Envelope CloudEvents v1.0

Cada evento é um CloudEvent no formato abaixo. O id é estável e coincide com o delivery_id — use-o para deduplicação idempotente no consumidor. O catálogo vigente, com os campos garantidos em data, está em GET /webhooks/events (também nos SDKs: webhook.events()).

{
  "specversion":     "1.0",
  "id":              "550e8400-e29b-41d4-a716-446655440000",
  "source":          "https://foxnfe.com.br",
  "type":            "br.com.centralfox.foxnfe.nfe.authorized",
  "datacontenttype": "application/json",
  "time":            "2026-09-05T12:00:00-03:00",
  "data":            { "nfe_id": 123, "status": "authorized" }
}

Verificar a assinatura (HMAC-SHA256)

import crypto from 'node:crypto';
import express from 'express';

const app = express();
// IMPORTANTE: capture o corpo CRU; não use express.json() antes de verificar.
app.use('/hooks/foxnfe', express.raw({ type: '*/*' }));

app.post('/hooks/foxnfe', (req, res) => {
  const secret = process.env.FOXNFE_WEBHOOK_SECRET;
  const header = req.get('X-Webhook-Signature') || '';
  const expected = 'sha256=' + crypto
    .createHmac('sha256', secret)
    .update(req.body)               // Buffer cru, exatamente como recebido
    .digest('hex');

  const a = Buffer.from(header);
  const b = Buffer.from(expected);
  if (a.length !== b.length || !crypto.timingSafeEqual(a, b)) {
    return res.status(401).end();   // assinatura inválida
  }

  const event = JSON.parse(req.body.toString('utf8')); // só depois de verificar
  // deduplicar por event.id antes de processar
  res.status(204).end();
});

import hmac, hashlib, os, json
from flask import Flask, request, abort

app = Flask(__name__)

@app.post("/hooks/foxnfe")
def receive():
    secret = os.environ["FOXNFE_WEBHOOK_SECRET"].encode()
    body = request.get_data()                       # bytes crus, sem reparse
    expected = "sha256=" + hmac.new(secret, body, hashlib.sha256).hexdigest()
    header = request.headers.get("X-Webhook-Signature", "")
    if not hmac.compare_digest(expected, header):   # tempo constante
        abort(401)
    event = json.loads(body)                         # só depois de verificar
    # deduplicar por event["id"] antes de processar
    return "", 204

<?php
$secret = getenv('FOXNFE_WEBHOOK_SECRET');
$body   = file_get_contents('php://input');          // corpo cru, sem reparse
$header = $_SERVER['HTTP_X_WEBHOOK_SIGNATURE'] ?? '';

$expected = 'sha256=' . hash_hmac('sha256', $body, $secret);
if (!hash_equals($expected, $header)) {              // tempo constante
    http_response_code(401);
    exit;
}
$event = json_decode($body, true);                    // só depois de verificar
// deduplicar por $event['id'] antes de processar
http_response_code(204);

Entregas, tentativas e reenvio

Cada entrega é tentada até 3 vezes, com espera de 30 s após a primeira falha e 300 s após a segunda. O histórico paginado (15 por página) fica em GET /webhooks/deliveries. Uma rotina de reconciliação recoloca na fila apenas entregas ainda não tentadas, presas entre o commit e o enfileiramento, com idade mínima de 5 minutos — entregas já falhadas ou em backoff nunca são redirigidas por ela.

Para reenviar manualmente uma entrega em falha terminal, use POST /webhooks/deliveries/{delivery_id}/resend. A operação é auditada (ator, tenant, data e tentativas anteriores) antes de zerar o contador. Os códigos abaixo vêm do controlador atual:

O endpoint POST /webhooks/test enfileira um evento sintético nfe.test para validar URL, assinatura e parsing sem emitir documento real (202; 422 se não houver webhook ativo; 429 no limite de taxa).

Consultas auxiliares #

Paginação: page e per_page (máximo 100). Entrada inválida responde 422; catálogo não provisionado responde 503 tipado, nunca uma amostra apresentada como catálogo completo.

Central de Documentos #

SDKs: documents.importPreview(), documents.import(), documents.exportRequest() (Node/PHP) e client.documents.import_preview(), import_xml(), export_request() (Python).

NF-e recebidas, manifestação e Carta de Correção #

Homologação por modelo e rejeições explicadas #

SDKs: nfe.rejeicao(), nfe.homologacaoRun(), nfe.homologacaoXml()/Pdf() (Node/PHP) e client.nfe.rejeicao(), homologacao_run() (Python).

Reforma tributária: IBS/CBS reproduzível #

SDKs: classe Rtc (Node/PHP) e client.rtc (Python).

Cobertura NFS-e por município e provedor #

SDKs: nfse.cobertura(), nfse.coberturaMunicipio(), nfse.coberturaProvedores() (Node/PHP) e client.nfse.cobertura_municipio() (Python).

Status do serviço e casos de suporte #

SDKs: classe Support (Node/PHP) e client.support (Python).

Estado dos domínios fiscais #

Homologação fiscal externa com certificado real é responsabilidade de cada integrador no ambiente de homologação (ambiente=2); esta página não substitui essa validação. Ela é atualizada a cada domínio que passa a disponível.

Expansão em revisão: CT-e, MDF-e, NFCom, DC-e, NFGás, RetailSync #

Todas as seis rotas exigem ability:nfes:emit e seguem o mesmo ciclo pending → processing → validated|rejected das demais emissões — nunca authorized nesta fase. Novidades por capacidade: veja Novidades.

Guias práticos #

Certificado A1

A emissão exige um certificado digital A1 (ICP-Brasil) válido, referenciado por certificate_id no payload. O certificado é carregado e validado no servidor; o evento certificate.validated sinaliza quando um certificado passou pela validação. Nunca envie o arquivo .pfx/.p12 nem a senha do certificado pelo front-end ou por canais de log.

Erros e novas tentativas

Erros de validação retornam 422 com um mapa errors por campo; falhas de autenticação, 401 ou 403. Para chamadas de escrita com resposta ambígua (timeout ou 5xx), não reemita cegamente: consulte o status do recurso e decida a partir do estado real. Respeite os limites de taxa (429) com espera antes de repetir.

Envios confirmados

Uma emissão só está confirmada quando o recurso sai de pending. Confirme por um destes caminhos: o webhook nfe.authorized/nfse.authorized, ou o polling do recurso até que status deixe de ser pending. O 202 inicial nunca é confirmação de autorização.

Reconciliação de entregas

Para garantir que nenhum evento foi perdido, cruze o seu registro local de eventos recebidos (deduplicados por id) com o histórico em GET /webhooks/deliveries. Entregas em falha terminal podem ser reenviadas manualmente pelo endpoint de resend; entregas presas antes da primeira tentativa são recolocadas na fila pela rotina interna de reconciliação. Como o modelo é at-least-once, a deduplicação no consumidor é parte obrigatória da integração.

Suporte #

Dúvidas de integração podem ser encaminhadas pelos canais oficiais da Central Fox:

• WhatsApp: +55 85 99101-0707
• E-mail de desenvolvimento: dev@centralfox.online