SDKs & Bibliotecas
SDKAPI de Nota Fiscal para Node.js e TypeScript
Integração completa com Fetch nativo, Express, NestJS e validação de webhooks HMAC.
Guia completo para integrar a API de emissão fiscal do NFER em aplicações Node.js e TypeScript. Compatível com Express, Next.js, Fastify, NestJS e scripts de backend.
Node.js 18+ (Fetch nativo)TypeScript ReadyZero dependências obrigatórias
1. Configuração e Variáveis de Ambiente
Defina a sua chave de autenticação (X-API-Key) no arquivo .env da sua aplicação:
NFER_API_KEY=sua_chave_a0eebc99.super-secret-key
NFER_API_URL=https://api.nfer.me
2. Cliente HTTP Tipado em TypeScript
Exemplo de função utilitária com tipagem estrita para disparar requisições autenticadas:
interface NferApiResponse<T = unknown> {
id?: string;
jobId?: string;
status?: string;
chave_acesso?: string;
danfe_url?: string;
xml_url?: string;
data?: T;
error?: string;
}
export async function nferRequest<T = unknown>(
endpoint: string,
method: 'GET' | 'POST' | 'PUT' | 'DELETE' = 'POST',
body?: unknown
): Promise<NferApiResponse<T>> {
const url = `${process.env.NFER_API_URL || 'https://api.nfer.me'}${endpoint}`;
3. Emitir NF-e (Produto Modelo 55) em Node.js
Criação e transmissão de rascunho de nota fiscal de mercadoria com cálculo automático de impostos:
import { nferRequest } from './nfer-client';
async function criarNota() {
const draft = await nferRequest('/v1/nfe', 'POST', {
naturezaOperacao: 'VENDA DE MERCADORIA',
tipoOperacao: '1',
finalidade: 1,
consumidorFinal: false,
destinatario: {
tipoPessoa: 'J',
cpfCnpj: '00000000000191',
nome: 'EMPRESA CLIENTE LTDA',
endereco: {
logradouro: 'Avenida Paulista',
numero: '1000',
bairro: 'Bela Vista',
cMun: '3550308',
UF: 'SP',
4. Validar Webhook SEFAZ no Express / Next.js
O NFER assina cada payload com HMAC-SHA256 no cabeçalho X-Nfer-Signature. Veja como validar em Node.js com o módulo nativo crypto:
import express from 'express';
import crypto from 'crypto';
const app = express();
app.use(express.json());
const WEBHOOK_SECRET = process.env.NFER_WEBHOOK_SECRET || 'whsec_...';
app.post('/webhooks/nfer', (req, res) => {
const signature = req.headers['x-nfer-signature'] as string;
const payload = JSON.stringify(req.body);
const expectedSignature = crypto
.createHmac('sha256', WEBHOOK_SECRET)
.update(payload)
.digest('hex');
if (signature !== expectedSignature) {