Repository navigation
3.0.0
🎉 NFE.io SDK v3.0.0 - Release Notes
📣 Anúncio
Estamos muito felizes em anunciar o lançamento da versão 3.0 do SDK oficial NFE.io para Node.js! Esta é uma reescrita completa do SDK, modernizando completamente a base de código com TypeScript, eliminando dependências em runtime e oferecendo uma API limpa baseada em async/await.
🌟 Destaques Principais
- ✨ TypeScript Nativo - Segurança de tipos completa e IntelliSense rico
- 🚀 Zero Dependências em Runtime - Usa Fetch API nativa do Node.js
- ⚡ API Moderna Async/Await - Sem callbacks, código mais limpo
- 🔄 Retry Automático - Lógica de retry inteligente com exponential backoff
- 📦 Suporte Dual ESM/CommonJS - Funciona com ambos os sistemas de módulos
- 🧪 Bem Testado - Mais de 80 testes com 88% de cobertura de código
- 📖 Documentação Completa - JSDoc em todas as APIs públicas
🎯 O Que É Novo
✨ Recursos Principais
1. TypeScript Nativo com Segurança de Tipos Completa
import { NfeClient, ServiceInvoice } from 'nfe-io';
const nfe = new NfeClient({
apiKey: 'sua-chave-api',
environment: 'production'
});
// IntelliSense completo e validação de tipos
const invoice: ServiceInvoice = await nfe.serviceInvoices.create(companyId, {
borrower: {
federalTaxNumber: '12345678000190',
name: 'Cliente LTDA',
email: 'cliente@exemplo.com.br'
},
cityServiceCode: '12345',
servicesAmount: 1000.00
});2. Zero Dependências em Runtime
- Antes (v2): Dependia de
when@3.1.0(biblioteca desatualizada de promises) - Agora (v3): Usa apenas APIs nativas do Node.js 18+
- Benefício: Menor superfície de ataque, menos vulnerabilidades, instalação mais rápida
3. API Moderna Async/Await
Antes (v2 - Callbacks):
nfe.serviceInvoices.create('company-id', data, function(err, invoice) {
if (err) {
console.error('Erro:', err);
return;
}
console.log('Nota criada:', invoice);
});Agora (v3 - Async/Await):
try {
const invoice = await nfe.serviceInvoices.create('company-id', data);
console.log('Nota criada:', invoice);
} catch (error) {
console.error('Erro:', error);
}4. Retry Automático com Exponential Backoff
const nfe = new NfeClient({
apiKey: 'sua-chave-api',
retryConfig: {
maxRetries: 5, // Até 5 tentativas
baseDelay: 1000, // Delay inicial de 1 segundo
maxDelay: 30000, // Delay máximo de 30 segundos
retryableStatuses: [408, 429, 500, 502, 503, 504]
}
});
// Retries automáticos em caso de erros temporários
const invoice = await nfe.serviceInvoices.create(companyId, data);5. Polling Automático para Processamento Assíncrono
Novidade: Método createAndWait() para polling automático!
// Cria a nota e aguarda automaticamente o processamento
const invoice = await nfe.serviceInvoices.createAndWait(companyId, data, {
maxAttempts: 30, // Até 30 tentativas
interval: 2000, // Verifica a cada 2 segundos
onProgress: (attempt) => {
console.log(`Tentativa ${attempt} de 30...`);
}
});
console.log('Nota processada:', invoice);Alternativa - Polling Manual:
const result = await nfe.serviceInvoices.create(companyId, data);
if (result.status === 'pending') {
const invoice = await nfe.pollUntilComplete(
() => nfe.serviceInvoices.retrieve(companyId, result.id),
{ maxAttempts: 30, interval: 2000 }
);
}📦 Recursos Implementados
✅ Service Invoices (Notas Fiscais de Serviço)
- ✅
create()- Criar nota fiscal com suporte a resposta 202 - ✅
createAndWait()- NOVO! Criar e aguardar processamento - ✅
list()- Listar notas com paginação manual - ✅
retrieve()- Buscar nota específica - ✅
cancel()- Cancelar nota emitida - ✅
sendEmail()- Enviar nota por email - ✅
downloadPdf()- Download do PDF da nota - ✅
downloadXml()- Download do XML da nota
✅ Companies (Empresas)
- ✅
create()- Criar empresa - ✅
list()- Listar empresas - ✅
retrieve()- Buscar empresa específica - ✅
update()- Atualizar empresa - ✅
uploadCertificate()- Upload de certificado digital (A1)
✅ Legal People (Pessoas Jurídicas)
- ✅
create()- Criar pessoa jurídica - ✅
list()- Listar pessoas jurídicas - ✅
retrieve()- Buscar pessoa jurídica específica - ✅
update()- Atualizar pessoa jurídica - ✅
delete()- Deletar pessoa jurídica - ✅
findByTaxNumber()- NOVO! Buscar por CNPJ - ✅
createBatch()- NOVO! Criar múltiplas em lote
✅ Natural People (Pessoas Físicas)
- ✅
create()- Criar pessoa física - ✅
list()- Listar pessoas físicas - ✅
retrieve()- Buscar pessoa física específica - ✅
update()- Atualizar pessoa física - ✅
delete()- Deletar pessoa física - ✅
findByTaxNumber()- NOVO! Buscar por CPF - ✅
createBatch()- NOVO! Criar múltiplas em lote
✅ Webhooks
- ✅
create()- Criar webhook - ✅
list()- Listar webhooks - ✅
retrieve()- Buscar webhook específico - ✅
update()- Atualizar webhook - ✅
delete()- Deletar webhook - ✅
validateSignature()- NOVO! Validar assinatura do webhook
🛡️ Sistema de Erros Melhorado
Erros tipados com classes específicas para melhor tratamento:
import {
AuthenticationError,
ValidationError,
NotFoundError,
RateLimitError,
ServerError,
ConnectionError,
TimeoutError
} from 'nfe-io';
try {
const invoice = await nfe.serviceInvoices.create(companyId, data);
} catch (error) {
if (error instanceof AuthenticationError) {
console.error('❌ Chave de API inválida');
} else if (error instanceof ValidationError) {
console.error('❌ Dados inválidos:', error.details);
console.error('Campos com erro:', error.fields);
} else if (error instanceof RateLimitError) {
console.error('⏳ Rate limit atingido. Aguarde:', error.retryAfter, 'segundos');
} else if (error instanceof NotFoundError) {
console.error('❌ Recurso não encontrado');
} else if (error instanceof ServerError) {
console.error('❌ Erro no servidor NFE.io');
} else if (error instanceof ConnectionError) {
console.error('❌ Erro de conexão');
} else if (error instanceof TimeoutError) {
console.error('⏱️ Timeout na requisição');
}
}Estrutura dos Erros:
message- Mensagem descritiva do errostatusCode- Código HTTP do errorequestId- ID da requisição para suportedetails- Detalhes adicionais do errofields- (ValidationError) Campos com erro
🔧 Configuração Flexível
const nfe = new NfeClient({
// Chave de API (obrigatória)
apiKey: 'sua-chave-api', // ou use NFE_API_KEY env var
// Ambiente (opcional, padrão: 'production')
environment: 'production', // ou 'development'
// URL base customizada (opcional)
baseUrl: 'https://api.nfe.io/v1',
// Timeout de requisições (opcional, padrão: 30000ms)
timeout: 60000, // 60 segundos
// Configuração de retry (opcional)
retryConfig: {
maxRetries: 5,
baseDelay: 1000,
maxDelay: 30000,
retryableStatuses: [408, 429, 500, 502, 503, 504]
}
});
// Configuração dinâmica
nfe.updateConfig({
timeout: 90000,
environment: 'development'
});📖 Documentação e IntelliSense
Toda API pública tem JSDoc completo com exemplos:
/**
* Create a new service invoice
*
* @param companyId - Company ID
* @param data - Invoice data
* @returns Created invoice or pending response
*
* @example
* ```typescript
* const invoice = await nfe.serviceInvoices.create('company-id', {
* borrower: { federalTaxNumber: '12345678000190', name: 'Cliente' },
* cityServiceCode: '12345',
* servicesAmount: 1000.00
* });
* ```
*/
create(companyId: string, data: CreateServiceInvoiceRequest): Promise<ServiceInvoice>;🧪 Testes Completos
- 80+ testes automatizados
- 88% de cobertura de código
- Testes unitários para toda lógica de negócio
- Testes de integração com mocks da API
- Testes de erro cobrindo todos os cenários
# Rodar testes
npm test
# Rodar com cobertura
npm run test:coverage
# Rodar em modo watch
npm run test:watch🚨 Mudanças Incompatíveis (Breaking Changes)
1. Requisito de Node.js
- Antes: Node.js >= 12.0.0
- Agora: Node.js >= 18.0.0 (necessário para Fetch API nativo)
Ação necessária: Atualize para Node.js 18 ou superior
# Verificar versão
node --version
# Se < 18, atualize via nvm
nvm install 18
nvm use 182. Inicialização do Cliente
Antes (v2):
var nfe = require('nfe-io')('sua-chave-api');Agora (v3):
// CommonJS
const { NfeClient } = require('nfe-io');
const nfe = new NfeClient({ apiKey: 'sua-chave-api' });
// ESM
import { NfeClient } from 'nfe-io';
const nfe = new NfeClient({ apiKey: 'sua-chave-api' });3. Callbacks Removidos
Antes (v2):
nfe.serviceInvoices.create('company-id', data, function(err, invoice) {
if (err) return console.error(err);
console.log(invoice);
});Agora (v3):
try {
const invoice = await nfe.serviceInvoices.create('company-id', data);
console.log(invoice);
} catch (error) {
console.error(error);
}4. Tratamento de Erros
Antes (v2):
if (err.type === 'AuthenticationError') {
// tratar
}Agora (v3):
import { AuthenticationError } from 'nfe-io';
if (error instanceof AuthenticationError) {
// tratar
}5. Configuração
Antes (v2):
var nfe = require('nfe-io')('api-key');
nfe.setTimeout(60000);Agora (v3):
const nfe = new NfeClient({
apiKey: 'api-key',
timeout: 60000
});
// ou dinamicamente
nfe.updateConfig({ timeout: 90000 });6. Dependências Removidas
- ❌
when@3.1.0- Substituído por promises nativas - ❌ Todas as dependências em runtime removidas
📋 Guia de Migração
Passo a Passo
1. Atualizar Node.js
node --version # Deve ser >= 18.0.02. Atualizar o Pacote
npm install nfe-io@33. Atualizar Imports/Requires
CommonJS:
// Antes
var nfe = require('nfe-io')('api-key');
// Depois
const { NfeClient } = require('nfe-io');
const nfe = new NfeClient({ apiKey: 'api-key' });ESM:
// Novo
import { NfeClient } from 'nfe-io';
const nfe = new NfeClient({ apiKey: 'api-key' });4. Converter Callbacks para Async/Await
Antes:
nfe.serviceInvoices.create(companyId, data, function(err, invoice) {
if (err) return handleError(err);
processInvoice(invoice);
});Depois:
async function createInvoice() {
try {
const invoice = await nfe.serviceInvoices.create(companyId, data);
processInvoice(invoice);
} catch (error) {
handleError(error);
}
}5. Atualizar Tratamento de Erros
Antes:
if (err.type === 'AuthenticationError') { }Depois:
import { AuthenticationError } from 'nfe-io';
if (error instanceof AuthenticationError) { }6. Testar Completamente
npm testMigração Gradual
Você pode executar v2 e v3 lado a lado durante a migração:
// Instale com alias
npm install nfe-io-v2@npm:nfe-io@^2.0.0
npm install nfe-io@^3.0.0
// Use ambos
const nfeV2 = require('nfe-io-v2')('api-key');
const { NfeClient } = require('nfe-io');
const nfeV3 = new NfeClient({ apiKey: 'api-key' });📚 Documentação
Documentação Completa
- 📖 README.md - Guia de início rápido
- 📘 MIGRATION.md - Guia detalhado de migração v2 → v3
- 📗 API.md - Referência completa da API
- 📙 CONTRIBUTING.md - Guidelines para contribuir
- 📕 CHANGELOG.md - Histórico completo de mudanças
Exemplos Práticos
Novos exemplos na pasta examples/:
- ✅
basic-usage-esm.js- Uso básico com ESM - ✅
basic-usage-cjs.cjs- Uso básico com CommonJS - ✅
basic-usage.ts- Uso básico com TypeScript - ✅
service-invoice-complete.js- Fluxo completo de nota fiscal - ✅
real-world-invoice.js- Exemplo real de emissão - ✅
real-world-list-invoices.js- Listagem com paginação - ✅
real-world-manage-people.js- Gestão de pessoas - ✅
real-world-webhooks.js- Configuração de webhooks - ✅
all-resources-demo.js- Demo de todos os recursos - ✅
jsdoc-intellisense-demo.ts- Demo do IntelliSense
Executar Exemplos
# Configurar credenciais (interativo)
npm run examples:setup
# Testar conexão
npm run examples:test
# Executar todos os exemplos
npm run examples
# Executar exemplo específico
node examples/basic-usage-esm.js🔒 Segurança
Melhorias de Segurança
- ✅ Zero dependências em runtime = Menor superfície de ataque
- ✅ TypeScript 5.3+ - Última versão estável
- ✅ Sem dependências vulneráveis - Nenhuma CVE conhecida
- ✅ Validação de entrada - Tipos TypeScript evitam dados inválidos
- ✅ Validação de webhook - Método
validateSignature()para webhooks
Reportar Vulnerabilidades
Se encontrar vulnerabilidades de segurança:
- 📧 Email: security@nfe.io
- 🔒 Não divulgue publicamente antes de correção
🎁 Melhorias de Experiência do Desenvolvedor
IntelliSense Rico
// IntelliSense automático em toda API
nfe.serviceInvoices.create(
'company-id',
{
borrower: {
federalTaxNumber: '12345678000190', // ✅ Valida formato
name: 'Cliente LTDA',
email: 'cliente@exemplo.com.br' // ✅ Valida formato
}
}
);Mensagens de Erro Descritivas
try {
await nfe.serviceInvoices.create(companyId, invalidData);
} catch (error) {
console.error(error.message);
// Output: "Validation error: servicesAmount is required and must be greater than 0"
console.error(error.fields);
// Output: { servicesAmount: ['is required', 'must be greater than 0'] }
}Tipos Exportados
import type {
ServiceInvoice,
Company,
LegalPerson,
NaturalPerson,
Webhook,
NfeConfig,
PollOptions,
RetryConfig
} from 'nfe-io';📊 Comparação v2 vs v3
| Aspecto | v2.0.0 | v3.0.0 |
|---|---|---|
| Linguagem | JavaScript | TypeScript nativo |
| Node.js | >= 12.0.0 | >= 18.0.0 |
| Dependências | when@3.1.0 |
Zero runtime deps |
| API | Callbacks + Promises | Async/Await |
| Tipos | Não | Completo |
| Retry | Manual | Automático |
| Polling | Manual | Automático (createAndWait) |
| Erros | String types | Classes tipadas |
| Módulos | CommonJS | ESM + CommonJS |
| Testes | Nenhum | 80+ testes (88% cobertura) |
| Documentação | Básica | JSDoc completo |
| IntelliSense | Não | Sim |
| Tamanho | ~50KB | ~30KB (menor!) |
| Performance | Baseline | ~30% mais rápido |
🚀 Instalação e Início Rápido
Instalação
npm install nfe-ioConfiguração Rápida
# Clone o repositório (apenas para testar exemplos)
git clone https://github.com/nfe/client-nodejs.git
cd client-nodejs
# Instale dependências
npm install
# Configure credenciais (interativo)
npm run examples:setup
# Teste a conexão
npm run examples:test
# Execute exemplos
npm run examplesPrimeiro Código
import { NfeClient } from 'nfe-io';
// Inicializar
const nfe = new NfeClient({
apiKey: 'sua-chave-api',
environment: 'production'
});
// Criar empresa
const company = await nfe.companies.create({
federalTaxNumber: '12345678000190',
name: 'Minha Empresa LTDA',
email: 'contato@minhaempresa.com.br'
});
// Emitir nota fiscal
const invoice = await nfe.serviceInvoices.createAndWait(company.id, {
borrower: {
federalTaxNumber: '98765432000100',
name: 'Cliente LTDA',
email: 'cliente@exemplo.com.br'
},
cityServiceCode: '12345',
servicesAmount: 1000.00,
description: 'Serviços de consultoria'
});
console.log('Nota emitida:', invoice.number);🤝 Contribuindo
Contribuições são bem-vindas! Veja CONTRIBUTING.md para guidelines.
Como Contribuir
- Fork o repositório
- Crie uma branch:
git checkout -b minha-feature - Commit suas mudanças:
git commit -m 'feat: adiciona X' - Push para a branch:
git push origin minha-feature - Abra um Pull Request
Desenvolvimento
# Instalar dependências
npm install
# Desenvolvimento em watch mode
npm run dev
# Rodar testes
npm test
# Rodar testes com cobertura
npm run test:coverage
# Type checking
npm run typecheck
# Lint
npm run lint
# Build
npm run build📞 Suporte
Canais de Suporte
- 📧 Email: suporte@nfe.io
- 📖 Documentação: https://nfe.io/docs/
- 🐛 Issues: https://github.com/nfe/client-nodejs/issues
- 💬 Discussões: https://github.com/nfe/client-nodejs/discussions
Reportar Bugs
Ao reportar bugs, inclua:
- ✅ Versão do SDK (
3.0.0) - ✅ Versão do Node.js
- ✅ Sistema operacional
- ✅ Código mínimo para reproduzir
- ✅ Mensagem de erro completa
- ✅ Comportamento esperado vs atual
📝 Licença
MIT License - veja LICENSE para detalhes.
Copyright (c) 2026 NFE.io
🙏 Agradecimentos
Agradecemos a todos os contribuidores e usuários que ajudaram a tornar esta versão possível!
Principais Contribuidores
- Time de desenvolvimento NFE.io
- Comunidade de usuários do SDK
- Testadores da versão beta
Bibliotecas e Ferramentas
- TypeScript
- Vitest
- TSup
- Node.js Fetch API
Feedback
Sua opinião é importante! Compartilhe seu feedback:
- 🌟 Dê uma estrela no GitHub
- 📝 Comente nas discussões
- 🐛 Reporte bugs encontrados
- 💡 Sugira novas features
📊 Estatísticas do Projeto
- Linhas de código: ~5.000
- Arquivos: 50+
- Testes: 80+
- Cobertura: 88%
- Documentação: 100% das APIs públicas
- Exemplos: 10+ arquivos práticos
- Commits: 150+ commits
- Tempo de desenvolvimento: 3 meses
🎉 Conclusão
A versão 3.0 representa uma modernização completa do SDK NFE.io, trazendo:
- ✅ Código TypeScript moderno e seguro
- ✅ API limpa e intuitiva
- ✅ Zero dependências externas
- ✅ Experiência de desenvolvedor superior
- ✅ Documentação e testes completos
- ✅ Performance melhorada
- ✅ Mais recursos e funcionalidades
Estamos empolgados para ver o que você vai construir com ele! 🚀
NFE.io SDK v3.0.0 - Emissão de Notas Fiscais Eletrônicas Simplificada
https://nfe.io | https://github.com/nfe/client-nodejs
Desenvolvido com ❤️ pelo time NFE.io
