nfeio-node-sdk

NFE.io Node.js SDK Integration Guide

This skill enables you to write correct, production-ready code using the NFE.io SDK for Brazilian electronic fiscal documents. The SDK covers NFS-e (service invoices), NF-e (product invoices), CT-e (transportation), CFe-SAT (consumer), CNPJ/CPF lookups, tax calculation, and more.

Package & Import

The npm package name is nfe-io. (Until 2026-09-02 the JSDoc examples imported from @nfe-io/sdk, a package that does not exist; corrected at the source.)

// ESM (recommended)
import { NfeClient } from 'nfe-io';

// CommonJS
const { NfeClient } = require('nfe-io');

// Default export (factory function)
import nfeFactory from 'nfe-io';
const nfe = nfeFactory({ apiKey: 'your-key' });

Requirements: Node.js 22+ (uses native fetch). Zero runtime dependencies.

Quick Start

import { NfeClient } from 'nfe-io';

const nfe = new NfeClient({
  apiKey: 'your-api-key',           // Required for most resources
  environment: 'production',         // 'production' | 'development'
  timeout: 30000,                    // Request timeout in ms (default: 30000)
  retryConfig: {                     // Optional retry configuration
    maxRetries: 3,                   // Default: 3
    baseDelay: 1000,                 // Default: 1000ms
    maxDelay: 30000,                 // Default: 30000ms
    backoffMultiplier: 2,            // Default: 2
  },
});

Two complementary API keys — not alternatives. Measured route by route (2026-10-14): the data key is rejected (403) on fiscal-document routes (NF-e, NFC-e, NFS-e, inbound documents, tax codes and calculation), and the main key is rejected (403) on the lookup hosts. Some account-registry routes also accept the data key; that is not a documented contract and the SDK does not rely on it.

• apiKey (main) → FISCAL hosts: api.nfe.io, api.nfse.io. Covers every emission resource plus certificates, municipalTaxes, stateTaxes, taxCodes and taxCalculation.
• dataApiKey → LOOKUP hosts: nfe.api.nfe.io, legalentity, naturalperson, address. Covers addresses, legalEntityLookup, naturalPersonLookup, productInvoiceQuery and consumerInvoiceQuery.