foxnfe

Estado consolidado em 11/09/2026: consulte estado canônico e limites. O pacote GTM está preparado, não implantado; Trial/Starter ainda não incluem NFS-e no catálogo vigente. Relatos datados preservam o histórico, sem comprovar o estado atual.

SDK oficial FOX NF-e para Node.js — emissão NF-e, NFSe, cancelamento, consulta e integração MCP.

Requisitos

• Node.js 18+
• TypeScript 5+ (opcional, para tipagem completa)

Instalação

npm install foxnfe
# ou
yarn add foxnfe
# ou
pnpm add foxnfe

Quick Start

import { Client } from 'foxnfe';

const client = new Client({ tenantSlug: 'minha-empresa' });

// Autenticar
const auth = await client.login('[email protected]', 'senha-segura');
console.log('Token:', auth.token);

// Ou usar token existente
const client2 = new Client({ tenantSlug: 'minha-empresa', token: 'seu-token-aqui' });
// Ou via withToken (retorna nova instância)
const authed = client.withToken('seu-token-aqui');

NF-e

import { Client, NfeEmitRequest } from 'foxnfe';

const client = new Client({ tenantSlug: 'minha-empresa', token: 'seu-token' });
const nfe = new Nfe(client);

// Emitir NF-e
const payload: NfeEmitRequest = {
    ambiente: 2, // 2=homologação
    certificate_id: 1,
    tomador: {
        cnpj: '12345678000190',
        razao_social: 'Empresa Tomadora Ltda',
        endereco: {
            logradouro: 'Rua das Flores',
            numero: '100',
            municipio: 'São Paulo',
            uf: 'SP',
            cep: '01310100',
        },
    },
    itens: [{
        codigo: 'SRV001',
        descricao: 'Serviço de consultoria',
        cfop: '5933',
        quantidade: 1,
        valor_unitario: 1000.00,
        valor_total: 1000.00,
    }],
    pagamentos: [{ forma: '01', valor: 1000.00 }],
    total: 1000.00,
};

const result = await nfe.emit(payload);
console.log('NF-e ID:', result.id);

// Aguardar autorização (polling automático)
const nfeAutorizada = await nfe.waitForAuthorization(result.id);
console.log('Status:', nfeAutorizada.status); // 'authorized'

// Baixar XML
const xml = await nfe.xml(result.id);
await fs.writeFile('nfe.xml', xml);

// Baixar DANFE PDF
const pdf = await nfe.pdf(result.id);
await fs.writeFile('danfe.pdf', pdf);

// Cancelar
await nfe.cancel(result.id, { justificativa: 'Cancelamento solicitado pelo cliente' });

NFSe

import { Client, Nfse, NfseEmitRequest } from 'foxnfe';

const nfse = new Nfse(client);

const payload: NfseEmitRequest = {
    competencia: '2026-09',                        // AAAA-MM
    cnpj_prestador: '12345678000190',
    inscricao_municipal: '123456',
    razao_social_prestador: 'Minha Empresa Ltda',  // opcional
    descricao_servico: 'Desenvolvimento de software sob encomenda',
    codigo_municipio_prestacao: '3550308',         // IBGE 7 dígitos
    valor_servico: 5000.00,
    // informe cnae OU o trio abaixo
    codigo_tributacao_nacional: '01.03.01.00',     // formato dd.dd.dd.dd
    codigo_tributacao_municipal: '0103',
    aliquota_iss: 2.0,
    tomador: { cnpj: '98765432000110', nome: 'Cliente S.A.' },  // cnpj OU cpf
    prestador: {
        endereco: {
            logradouro: 'Av. Paulista', numero: '1000', bairro: 'Bela Vista',
            codigo_municipio: '3550308', uf: 'SP', cep: '01310100',
        },
    },
};

const result = await nfse.emit(payload);           // 202 { nfse_id, status: 'pending', message }
const nfseData = await nfse.get(result.nfse_id);
console.log('Número NFSe:', nfseData.numero_nfse);

// Consultar por RPS ou chave
await nfse.consultByNumero('00000001');
await nfse.consultByChave('SP3550308202605010000000000001');

// Cancelar (justificativa 15..255) / Substituir (motivo 15..255 + campos de emissão)
await nfse.cancel(result.nfse_id, { justificativa: 'Erro nos dados do tomador' });
await nfse.substitute(result.nfse_id, { ...payload, motivo: 'Correção dos dados do tomador' });

MCP (Model Context Protocol)

import { Mcp } from 'foxnfe';

const mcp = new Mcp(client);

// Inicializar sessão MCP
const info = await mcp.initialize();
console.log('MCP Server:', info.serverInfo.name);

// Listar tools
const { tools } = await mcp.listTools();
tools.forEach(t => console.log(`${t.name}: ${t.description}`));

// Chamar uma tool
const result = await mcp.callTool('emitir_nfe', {
    ambiente: 2,
    certificate_id: 1,
    // ...
});

if (result.is_error) {
    console.error('Tool error:', result.content[0]?.text);
} else {
    console.log('Tool result:', result.content[0]?.text);
}

1.3.0 — eventos, rejeições, homologação, RTC, cobertura NFS-e e suporte

import { NfeEvents, Nfe, Nfse, Rtc, Support } from 'foxnfe';

const ev = new NfeEvents(client);
await ev.atorInteressado(15, { documento: '11222333000181' });          // 110150
await ev.insucessoEntrega(15, { dh_tentativa: '2026-09-08T10:00:00-03:00', tp_motivo: 1 }); // 110192
await ev.inutilizar({ serie: 1, numero_inicial: 10, numero_final: 12, justificativa: 'Numeração pulada por falha do ERP' });
await ev.contratos();                                                  // catálogo (conciliação financeira, RTC…)
await ev.registrarEvento(15, 'econf', { /* campos do contrato */ });

const nfe = new Nfe(client);
await nfe.rejeicao('539');                                             // categoria/ação/dica
await nfe.homologacaoRun(65);                                          // amostras XML/PDF simuladas por cenário

await new Nfse(client).coberturaMunicipio('2304400');                  // driver, operações e provas
const rtc = new Rtc(client);
await rtc.verifyResolution('550e8400-e29b-41d4-a716-446655440000');   // reproducible | output_drift | version_drift
await new Support(client).createCase({ subject: 'Webhook sem entrega desde ontem', priority: 'high' });

Cada método valida localmente o que pode (ids, dígitos, tamanhos, enums) e deixa a regra fiscal para a API. A consulta de NF-e traz rejection quando houver rejeição SEFAZ.

Tratamento de Erros

import { ApiException, AuthException, FoxNfeException } from 'foxnfe';

try {
    await nfe.emit(payload);
} catch (err) {
    if (err instanceof AuthException) {
        // Token inválido ou expirado (401/403)
        console.error('Auth error:', err.message);
    } else if (err instanceof ApiException) {
        // Erro da API (422, 500, etc.)
        console.error(`API error ${err.statusCode}:`, err.message);
        console.error('Body:', err.responseBody);
    } else if (err instanceof FoxNfeException) {
        // Timeout, erro de rede, etc.
        console.error('SDK error:', err.message);
    }
}

Configuração avançada

const client = new Client({
    tenantSlug: 'minha-empresa',
    token:      'seu-token',
    baseUrl:    'https://foxnfe.centralfox.online/api/v1', // host legado; padrão: https://www.foxnfe.com.br/api/v1
    timeoutMs:  60_000,
});

Estrutura do pacote

src/
├── index.ts      # Exports públicos + createClient()
├── client.ts     # Cliente HTTP principal
├── nfe.ts        # Módulo NF-e
├── nfse.ts       # Módulo NFSe
├── mcp.ts        # Módulo MCP
├── types.ts      # Tipos TypeScript exportados
└── errors.ts     # Classes de erro

Links

• Documentação API
• Portal FOX NF-e
• Suporte

1.3.3 — licença proprietária

• A partir desta versão o SDK é distribuído sob a Licença de Uso dos SDKs FOX NF-e (arquivo LICENSE): uso permitido somente com contrato de licença do FOX NF-e em vigor. Sem mudança de API.
• As versões 1.3.2 e anteriores foram publicadas sob MIT e permanecem sob essa licença.

1.3.2 — correção do contrato NFS-e e URL base canônica

• nfse.emit: corpo alinhado ao EmitNfseRequest da API (competencia, cnpj_prestador, inscricao_municipal, descricao_servico, codigo_municipio_prestacao, valor_servico, tomador, prestador.endereco + opcionais). ambiente, certificate_id e servico saíram do tipo — não existem no contrato NFS-e. Campos nulos não são enviados.
• nfse.cancel: envia justificativa (15..255, validado antes do envio); motivo segue aceito como alias.
• nfse.substitute: envia motivo (15..255) + campos de emissão; motivo_cancelamento segue aceito como alias e não é enviado. Na substituição a API exige codigo_tributacao_nacional, codigo_tributacao_municipal e aliquota_iss (sem rota por cnae).
• Respostas de emit/cancel/substitute são {nfse_id, message} (202); a consulta usa nfse_id.
• URL base padrão: https://www.foxnfe.com.br/api/v1 (canônico). O host legado https://foxnfe.centralfox.online/api/v1 continua respondendo e pode ser passado explicitamente.

Landing e Site IA — SEO 1.1.0 (11/09/2026)

Estado, testes e publicação. FAQ único com cinco perguntas, quatro casos B2B, conteúdo pré-renderizado e equivalente para bots/humanos. Esta atualização não altera contratos fiscais nem billing.

Licença

Software proprietário da Central Fox Tecnologia LTDA. Uso permitido somente com contrato de licença do FOX NF-e em vigor (ou avaliação gratuita vigente). Veja o arquivo LICENSE. Licenciamento: [email protected].