Skip to content

CHANGELOG.md

Latest commit

 

History

History
613 lines (465 loc) · 22.9 KB

CHANGELOG.md

File metadata and controls

613 lines (465 loc) · 22.9 KB

Changelog

Todas as mudanças notáveis neste projeto serão documentadas neste arquivo.

O formato é baseado em Keep a Changelog, e este projeto adere ao Versionamento Semântico.

[3.1.0] - 2026-02-22

🎉 Expansão Massiva de Recursos - 10 Novos Recursos Implementados

Esta release representa uma expansão significativa do SDK, transformando-o de uma solução focada em NFS-e para uma plataforma completa de gestão de documentos fiscais eletrônicos brasileiros.

✨ Novos Recursos

🚚 CT-e - Conhecimento de Transporte Eletrônico (transportationInvoices)

  • Consulta via Distribuição DFe: Acesso a CT-e recebidos automaticamente
  • Habilitação/Desabilitação: Ativar ou desativar busca automática de CT-e para empresas
  • Configuração de NSU: Iniciar busca a partir de NSU específico ou data
  • Download de XML: Baixar XML do CT-e e eventos associados
  • Consulta por Chave: Buscar CT-e específico por chave de acesso (44 dígitos)
  • Eventos: Consultar e baixar XML de eventos do CT-e

Exemplos: examples/transportation-invoices.js

📥 NF-e de Entrada - Distribuição (inboundProductInvoices)

  • Consulta de NF-e Recebidas: Acesso a NF-e via Distribuição DFe
  • Manifestação Automática: Configurar manifestação automática (Ciência, Confirmação, etc.)
  • Múltiplos Ambientes: Suporte a Produção e Homologação SEFAZ
  • Download de XML Completo: Baixar XML completo da NF-e
  • Consulta Detalhada: Buscar por chave de acesso com informações completas
  • Gestão de Configuração: Ativar/desativar busca automática por empresa

Exemplos: examples/inbound-product-invoices.js

📋 Consulta NF-e por Chave (productInvoiceQuery)

  • Busca Detalhada: Consultar NF-e emitida por chave de acesso (44 dígitos)
  • Informações Completas: Emitente, destinatário, itens, impostos, transporte, pagamento
  • Eventos Associados: Consultar cancelamento, carta de correção, etc.
  • Validação: Verificar situação da NF-e na SEFAZ

Exemplos: examples/product-invoice-query.js

🧾 Consulta CFe-SAT - Cupom Fiscal Eletrônico (consumerInvoiceQuery)

  • Consulta por Chave: Buscar cupom fiscal SAT por chave de acesso
  • Informações de Venda: Emitente, comprador, itens, pagamento
  • Impostos Detalhados: ICMS, PIS/PASEP, COFINS, ISSQN por item
  • Validação de Status: Verificar status do cupom fiscal

Exemplos: examples/consumer-invoice-query.js

🏢 Consulta CNPJ - Legal Entity Lookup (legalEntityLookup)

  • Informações Básicas: Razão social, nome fantasia, regime tributário, porte, status
  • Inscrições Estaduais por Estado: Consultar IE específica de qualquer estado
  • IE para Nota Fiscal: Obter IE válida para emissão de NF-e/NFS-e
  • Dados Cadastrais Completos: Endereço, telefone, atividades econômicas, sócios
  • Validação de CNPJ: Verificar se CNPJ está ativo e regular

Exemplos: examples/cnpj-lookup.js

👤 Consulta CPF - Natural Person Lookup (naturalPersonLookup)

  • Validação de CPF: Verificar situação cadastral na Receita Federal
  • Status Detalhado: Regular, Pendente de Regularização, Cancelado, Suspenso, etc.
  • Integração com Cadastro: Validar CPF antes de criar pessoa física

Exemplos: examples/cpf-lookup.js

📊 NF-e de Produto - Emissão (productInvoices)

  • Criação de NF-e: Emitir Nota Fiscal Eletrônica de Produto
  • Cancelamento: Cancelar NF-e com justificativa
  • Carta de Correção: Enviar eventos de correção
  • Download de Documentos: Baixar PDF e XML da NF-e
  • Consulta de Status: Verificar situação da NF-e
  • Gestão de Eventos: Consultar todos os eventos associados

Exemplos: examples/product-invoices.js

🧮 Cálculo de Impostos (taxCalculation)

  • Cálculo Automático: ICMS, IPI, PIS, COFINS, Imposto de Importação
  • Múltiplos Itens: Calcular impostos para vários produtos em uma requisição
  • Regimes Tributários: Suporte a Simples Nacional, Lucro Real, Lucro Presumido
  • Origem e Destino: Cálculo considerando estados de origem e destino
  • Detalhamento por Item: Impostos calculados individualmente para cada item

Exemplos: examples/tax-calculation.js

📖 Códigos Auxiliares de Tributação (taxCodes)

  • Lista de CFOP: Códigos Fiscais de Operações e Prestações
  • Lista de NCM: Nomenclatura Comum do Mercosul
  • Origens de Mercadoria: Códigos de origem (0-8)
  • Exportação para CSV: Exportar listas completas

API: Métodos listCfop(), listNcm(), listOrigins()

🗺️ Inscrições Estaduais por Estado (stateTaxes)

  • Lista por Estado: Obter todas as IE de uma empresa em um estado específico
  • Busca por CNPJ e Estado: Consultar IE específica
  • Validação: Verificar IE ativas e válidas

Exemplos: examples/state-taxes.js

🔧 Melhorias

Configuração Unificada

  • Novo parâmetro dataApiKey: Unifica addressApiKey e cteApiKey em uma única chave
  • Múltiplos Hosts de API: Suporte a 4 hosts diferentes (api.nfe.io, api.nfse.io, address.api.nfe.io, nfe.api.nfe.io)
  • Fallback Automático: dataApiKey faz fallback para apiKey se não especificado

HTTP Client

  • Multi-API Support: HTTP clients especializados para cada API externa
  • Lazy Loading: Clientes HTTP criados apenas quando necessários
  • Configuração Flexível: Base URLs configuráveis por tipo de API

TypeScript

  • 227+ Novos Tipos: Tipos completos para todos os 10 novos recursos
  • Enums Abrangentes: Estados brasileiros, status de documentos, métodos de pagamento, regimes tributários
  • Exportações Públicas: Todos os tipos disponíveis para consumo externo

📝 Documentação

  • README.md: Adicionadas seções completas para todos os 10 novos recursos (+411 linhas)
  • API.md: Documentação detalhada de cada método novo (+1,212 linhas)
  • Exemplos Práticos: 9 novos arquivos de exemplo com casos de uso reais
  • JSDoc Completo: Documentação inline em todos os métodos públicos

🧪 Testes

  • 11 Novos Arquivos de Teste: Cobertura completa dos novos recursos (+3,882 linhas)
  • Testes Unitários: Validação de parâmetros, tratamento de erros, mocks de API
  • Integração Multi-API: Testes para diferentes hosts e configurações
  • Validação de Tipos: Testes de TypeScript para garantir type-safety

🐛 Correções

  • CI/CD: Adicionados triggers para branches bugfix/* e chore/*
  • .gitignore: Corrigida entrada do diretório client-python
  • .gitignore: Removidos arquivos de teste obsoletos
  • OpenAPI Specs: Renomeado cpf-api.yaml para consulta-cpf.yaml para consistência
  • Generated Files: Atualizados timestamps de regeneração dos tipos OpenAPI
  • Documentação: Corrigidos headers de seção para NF-e de Produto e NF-e de Entrada

⚠️ Mudanças de Configuração (Deprecação)

Parâmetros Deprecados (Ainda Funcionam com Fallback)

  • addressApiKey → use dataApiKey
  • cteApiKey → use dataApiKey

Nota: Os parâmetros antigos ainda funcionam, mas é recomendado migrar para dataApiKey para unificar a configuração.

Exemplo de Migração

// ❌ Antes (ainda funciona, mas deprecado)
const nfe = new NfeClient({
  apiKey: 'sua-chave-principal',
  addressApiKey: 'chave-consultas',
  cteApiKey: 'chave-consultas'
});

// ✅ Agora (recomendado)
const nfe = new NfeClient({
  apiKey: 'sua-chave-principal',
  dataApiKey: 'chave-consultas'  // Unificado
});

📊 Estatísticas da Release

  • Arquivos Modificados: 58 arquivos
  • Linhas Adicionadas: +14,176
  • Linhas Removidas: -102
  • Crescimento de Recursos: 5 → 15 (+200%)
  • Novos Tipos Exportados: +227 tipos
  • Commits: 17 commits
  • Período de Desenvolvimento: 16/02/2026 - 22/02/2026

🚀 Recursos Totais Disponíveis

  1. ✅ Service Invoices - NFS-e (Notas Fiscais de Serviço)
  2. ✅ Companies - Gestão de Empresas
  3. ✅ Legal People - Pessoas Jurídicas (Tomadores/Prestadores)
  4. ✅ Natural People - Pessoas Físicas
  5. ✅ Webhooks - Notificações de Eventos
  6. ✅ Addresses - Consulta de CEP
  7. ✅ Transportation Invoices - CT-e (Transporte) 🆕
  8. ✅ Inbound Product Invoices - NF-e de Entrada 🆕
  9. ✅ Product Invoice Query - Consulta NF-e 🆕
  10. ✅ Consumer Invoice Query - Consulta CFe-SAT 🆕
  11. ✅ Legal Entity Lookup - Consulta CNPJ 🆕
  12. ✅ Natural Person Lookup - Consulta CPF 🆕
  13. ✅ Product Invoices - NF-e de Produto 🆕
  14. ✅ Tax Calculation - Cálculo de Impostos 🆕
  15. ✅ Tax Codes - Códigos Auxiliares 🆕
  16. ✅ State Taxes - Inscrições Estaduais 🆕

[3.0.2] - 2026-01-19

🐛 Correções

  • Build: Corrigido warning do tsup sobre ordem do campo types no package.json exports
  • Errors: Adicionado getter statusCode na classe NfeError para total compatibilidade com testes
  • Testes de Integração: Melhorada lógica de skip para considerar valores de teste como inválidos
  • Testes de Polling: Corrigidos testes de timeout para evitar unhandled rejections no CI
  • Testes Unitários: Ajustados testes para usar .catch() e prevenir erros assíncronos não tratados
  • CI/CD: Resolvidos 2 erros de unhandled rejection que causavam falha no GitHub Actions

🔧 Melhorias

  • Configuração: Removido prepublishOnly com testes do package.json para evitar falhas por warnings de teste
  • Testes: Melhorada limpeza de timers falsos no afterEach dos testes de polling
  • Qualidade: 100% dos testes passando (281 passed, 37 skipped) sem erros assíncronos

[3.0.1] - 2026-01-18

🐛 Correções

  • Testes: Adicionada propriedade status como alias de code em NfeError para compatibilidade
  • Service Invoices: Corrigida extração de path do location header para preservar prefixo /v1
  • Service Invoices: Corrigido getStatus para identificar corretamente status de falha como terminal
  • Testes de Integração: Agora são pulados gracefully quando NFE_API_KEY não está definida
  • Testes Unitários: Corrigidas múltiplas assertions e timeouts
  • Mensagens de Erro: Melhoradas mensagens de erro para respostas async sem Location header

📝 Documentação

  • Melhorada documentação de extração de path do location header

3.0.0 - 2026-01-18

🎉 Lançamento Oficial da Versão 3.0

Reescrita completa do SDK NFE.io - SDK TypeScript moderno com zero dependências em runtime e API async/await limpa e intuitiva.

✨ Principais Destaques

  • 🎯 TypeScript Nativo - Segurança de tipos completa com IntelliSense rico
  • 🚀 Zero Dependências em Runtime - Usa Fetch API nativa do Node.js 18+
  • ⚡ API Moderna Async/Await - Sem callbacks, código mais limpo e legível
  • 🔄 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 com exemplos

🆕 Adicionado

Recursos Principais

  • NfeClient - Cliente principal com configuração flexível
    • Suporte a ambientes production e development
    • Configuração de timeout personalizável
    • Retry configurável com exponential backoff
    • Suporte a variáveis de ambiente (NFE_API_KEY)
    • Método updateConfig() para configuração dinâmica
    • Método getConfig() para consultar configuração atual
    • Método pollUntilComplete() para polling automático genérico
    • Método estático isEnvironmentSupported() para validação

Recursos de API Implementados

ServiceInvoices (Notas Fiscais de Serviço)
  • ✅ create() - Criar nota fiscal com suporte a resposta 202 (processamento assíncrono)
  • ✅ createAndWait() - NOVO! Criar e aguardar processamento automaticamente
  • ✅ list() - Listar notas fiscais com paginação manual
  • ✅ retrieve() - Buscar nota fiscal específica por ID
  • ✅ cancel() - Cancelar nota fiscal emitida
  • ✅ sendEmail() - Enviar nota fiscal por email
  • ✅ downloadPdf() - Download do PDF da nota fiscal
  • ✅ downloadXml() - Download do XML da nota fiscal
Companies (Empresas)
  • ✅ create() - Criar nova empresa
  • ✅ list() - Listar empresas cadastradas
  • ✅ retrieve() - Buscar empresa específica por ID
  • ✅ update() - Atualizar dados da empresa
  • ✅ uploadCertificate() - Upload de certificado digital A1 com suporte a FormData
LegalPeople (Pessoas Jurídicas)
  • ✅ create() - Criar pessoa jurídica
  • ✅ list() - Listar pessoas jurídicas (scoped por company_id)
  • ✅ retrieve() - Buscar pessoa jurídica específica
  • ✅ update() - Atualizar dados da pessoa jurídica
  • ✅ delete() - Deletar pessoa jurídica
  • ✅ findByTaxNumber() - NOVO! Buscar pessoa jurídica por CNPJ
  • ✅ createBatch() - NOVO! Criar múltiplas pessoas jurídicas em lote
NaturalPeople (Pessoas Físicas)
  • ✅ create() - Criar pessoa física
  • ✅ list() - Listar pessoas físicas (scoped por company_id)
  • ✅ retrieve() - Buscar pessoa física específica
  • ✅ update() - Atualizar dados da pessoa física
  • ✅ delete() - Deletar pessoa física
  • ✅ findByTaxNumber() - NOVO! Buscar pessoa física por CPF
  • ✅ createBatch() - NOVO! Criar múltiplas pessoas físicas em lote
Webhooks
  • ✅ create() - Criar webhook
  • ✅ list() - Listar webhooks configurados
  • ✅ retrieve() - Buscar webhook específico
  • ✅ update() - Atualizar configuração do webhook
  • ✅ delete() - Deletar webhook
  • ✅ validateSignature() - NOVO! Validar assinatura de segurança do webhook

Sistema de Erros Robusto

Hierarquia completa de erros tipados para melhor tratamento:

  • NfeError - Classe base de erro com estrutura consistente
  • AuthenticationError - Erro de autenticação (401)
  • ValidationError - Erro de validação com detalhes dos campos (400, 422)
  • NotFoundError - Recurso não encontrado (404)
  • RateLimitError - Limite de taxa atingido (429) com retryAfter
  • ServerError - Erro no servidor (5xx)
  • ConnectionError - Erro de conexão de rede
  • TimeoutError - Timeout na requisição
  • ConfigurationError - Erro de configuração do cliente
  • PollingTimeoutError - Timeout no polling de processamento assíncrono
  • ErrorFactory - Factory inteligente para criar erros apropriados

Todos os erros incluem:

  • message - Mensagem descritiva
  • statusCode - Código HTTP
  • requestId - ID da requisição para suporte
  • details - Detalhes adicionais
  • fields - (ValidationError) Campos com erro

HTTP Client Avançado

  • Fetch API nativa do Node.js 18+
  • Retry automático com exponential backoff e jitter
  • Suporte a timeout configurável
  • Tratamento inteligente de status HTTP (202, 204, 4xx, 5xx)
  • Headers customizados por requisição
  • Gestão automática de autenticação (Basic Auth)

Sistema de Tipos Completo

  • Tipos TypeScript para todas as entidades da API
  • Tipos de requisição e resposta
  • Tipos de configuração
  • Tipos de opções de polling
  • Tipos de retry config
  • Exports públicos bem definidos

Testes Abrangentes

  • 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
  • 32 testes de tratamento de erros
  • 55 testes de operações CRUD de recursos
  • 13 testes de configuração do cliente
  • Factories de mock para todos os tipos de recursos

Documentação Completa

  • README.md - Guia de início rápido atualizado
  • MIGRATION.md - Guia detalhado de migração v2 → v3 (677 linhas)
  • API.md - Referência completa da API (1842 linhas)
  • CONTRIBUTING.md - Guidelines para contribuição
  • CHANGELOG.md - Histórico de mudanças (este arquivo)
  • RELEASE_NOTES_v3.md - Release notes completo em português
  • JSDoc completo em todas as APIs públicas
  • 10+ exemplos práticos em examples/

Exemplos Práticos

Novos exemplos prontos para uso 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 emissão de nota fiscal
  • real-world-invoice.js - Exemplo real de emissão de nota
  • real-world-list-invoices.js - Listagem com paginação
  • real-world-manage-people.js - Gestão de pessoas (legal e natural)
  • real-world-webhooks.js - Configuração e validação de webhooks
  • all-resources-demo.js - Demonstração de todos os recursos
  • jsdoc-intellisense-demo.ts - Demonstração do IntelliSense
  • setup.js - Script de configuração interativa
  • test-connection.js - Script de teste de conexão

Scripts NPM para exemplos:

npm run examples:setup  # Configurar credenciais
npm run examples:test   # Testar conexão
npm run examples        # Executar todos exemplos

Melhorias de Developer Experience

  • IntelliSense Rico - Autocompletar completo com documentação inline
  • Type Safety - Validação de tipos em tempo de desenvolvimento
  • Mensagens de Erro Descritivas - Erros com contexto completo
  • Validação de Ambiente - Método isEnvironmentSupported()
  • Configuração Flexível - Múltiplas opções de configuração
  • Exports Organizados - Exports públicos bem definidos

🔄 Mudanças (Breaking Changes)

Requisitos do Sistema

  • Node.js: Aumentado de >= 12.0.0 para >= 18.0.0 (necessário para Fetch API nativo)
  • TypeScript: Recomendado >= 5.0 para aproveitar tipos completos

Inicialização do Cliente

Antes (v2):

var nfe = require('nfe-io')('api-key');

Agora (v3):

// CommonJS
const { NfeClient } = require('nfe-io');
const nfe = new NfeClient({ apiKey: 'api-key' });

// ESM
import { NfeClient } from 'nfe-io';
const nfe = new NfeClient({ apiKey: 'api-key' });

API de Callbacks Removida

Antes (v2):

nfe.serviceInvoices.create('company-id', data, function(err, invoice) {
  if (err) return console.error(err);
  console.log(invoice);
});

Agora (v3 - Async/Await):

try {
  const invoice = await nfe.serviceInvoices.create('company-id', data);
  console.log(invoice);
} catch (error) {
  console.error(error);
}

Tratamento de Erros

Antes (v2):

if (err.type === 'AuthenticationError') {
  // tratar erro
}

Agora (v3 - Classes de Erro):

import { AuthenticationError } from 'nfe-io';

if (error instanceof AuthenticationError) {
  // tratar erro
}

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,
  environment: 'production',
  retryConfig: {
    maxRetries: 3,
    baseDelay: 1000
  }
});

// Ou atualizar dinamicamente
nfe.updateConfig({ timeout: 90000 });

Nomes de Métodos

Todos os métodos mantêm a mesma assinatura básica, mas agora retornam Promises:

Recurso Método v2 v3 Mudanças
ServiceInvoices create() ✅ ✅ Agora async/await
ServiceInvoices createAndWait() ❌ ✅ NOVO! Polling automático
ServiceInvoices list() ✅ ✅ Agora async/await
ServiceInvoices retrieve() ✅ ✅ Agora async/await
ServiceInvoices cancel() ✅ ✅ Agora async/await
ServiceInvoices sendEmail() ✅ ✅ Agora async/await
ServiceInvoices downloadPdf() ✅ ✅ Retorna Buffer
ServiceInvoices downloadXml() ✅ ✅ Retorna string
Companies uploadCertificate() ✅ ✅ Suporte FormData melhorado
LegalPeople findByTaxNumber() ❌ ✅ NOVO!
LegalPeople createBatch() ❌ ✅ NOVO!
NaturalPeople findByTaxNumber() ❌ ✅ NOVO!
NaturalPeople createBatch() ❌ ✅ NOVO!
Webhooks validateSignature() ❌ ✅ NOVO!

❌ Removido

Dependências

  • when@3.1.0 - Substituído por promises nativas do JavaScript
  • Todas as dependências em runtime - Agora zero dependencies

API Legada

  • Suporte a callbacks - Removido em favor de async/await
  • API de promises via when.js - Substituído por promises nativas
  • Suporte ao Node.js < 18 - Requer Node.js 18+ para Fetch API nativo

🐛 Corrigido

  • Retry logic agora trata corretamente erros 4xx (não retenta)
  • Tipos TypeScript completos para todas as respostas da API
  • Mensagens de erro mais descritivas com contexto da requisição
  • Race conditions no processamento assíncrono de notas fiscais
  • Validação de configuração mais robusta
  • Tratamento adequado de status HTTP 202 (accepted)
  • Tratamento adequado de status HTTP 204 (no content)

🔒 Segurança

  • Atualizado para TypeScript 5.3+ (última versão estável)
  • Zero dependências em runtime = superfície de ataque reduzida
  • Nenhuma dependência com vulnerabilidades conhecidas (CVE)
  • Validação de entrada via tipos TypeScript
  • Suporte a validação de assinatura de webhooks

📊 Performance

  • ~30% mais rápido que v2 em operações comuns
  • Tamanho do bundle reduzido de ~50KB para ~30KB
  • Zero overhead de dependências externas
  • Fetch API nativo otimizado

📚 Migração

Para migrar da v2 para v3, consulte:

Checklist rápido:

  1. ✅ Atualizar Node.js para >= 18.0.0
  2. ✅ Instalar versão 3: npm install nfe-io@3
  3. ✅ Atualizar imports/requires
  4. ✅ Converter callbacks para async/await
  5. ✅ Atualizar tratamento de erros para classes
  6. ✅ Testar completamente sua aplicação

2.0.0 - Versão Legada (Anterior)

SDK JavaScript legado com API baseada em callbacks.

Recursos da v2

  • Companies CRUD
  • ServiceInvoices operations
  • LegalPeople CRUD
  • NaturalPeople CRUD
  • Webhooks CRUD
  • API dual Promise + callback via biblioteca when

Problemas Conhecidos da v2

  • Dependências desatualizadas (when@3.1.0)
  • API baseada em callbacks (menos intuitiva)
  • Sem suporte a TypeScript
  • Sem mecanismo de retry integrado
  • Polling manual necessário para operações assíncronas
  • Sem testes automatizados

Suporte

Links