Release v3.1.0 - Expansão Massiva de Recursos NFE.io SDK

[andrekutianski]

📊 Resumo Executivo

Branch de origem: develop
Branch de destino: master
Versão: v3.0.2 → v3.1.0
Commits: 17 commits
Arquivos modificados: 58 arquivos
Linhas adicionadas: +14,176
Linhas removidas: -102
Autor principal: Andre Kutianski
Período: 16 de fevereiro - 22 de fevereiro de 2026

---

🎯 Objetivo

Esta release representa uma expansão massiva do NFE.io SDK, adicionando suporte completo para 10 novos recursos da API NFE.io, transformando o SDK de uma solução focada em NFS-e para uma plataforma completa de gestão de documentos fiscais eletrônicos brasileiros.

---

✨ Principais Destaques

🚀 Novos Recursos Implementados (10)

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

   • Consulta via Distribuição DFe
   • Habilitação/desabilitação de busca automática
   • Download de XML do CT-e e eventos
   • Configuração de NSU inicial

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

   • Consulta de NF-e recebidas via Distribuição
   • Manifestação automática (Ciência, Confirmação, Desconhecimento, Operação Não Realizada)
   • Download de XML completo
   • Configuração por ambiente SEFAZ

3. 📋 Consulta NF-e por Chave de Acesso

   • Busca detalhada de NF-e emitida
   • Informações completas (emitente, destinatário, itens, impostos, pagamento)
   • Consulta de eventos associados

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

   • Consulta de cupons fiscais SAT
   • Informações de emitente, comprador, itens e pagamento

5. 🏢 Consulta CNPJ (Legal Entity Lookup)

   • Informações básicas de pessoa jurídica
   • Inscrições estaduais por estado
   • Inscrições estaduais por estado para nota fiscal
   • Validação de CNPJ ativo

6. 👤 Consulta CPF (Natural Person Lookup)

   • Validação de status de CPF (Regular, Pendente, Cancelado, Suspenso, etc.)

7. 📊 NF-e de Produto (Emissão)

   • Criação de NF-e de produto
   • Cancelamento, carta de correção
   • Download de PDF e XML
   • Consulta de status

8. 🧮 Cálculo de Impostos

   • Cálculo automático de ICMS, IPI, PIS, COFINS, II
   • Múltiplos itens por requisição
   • Suporte a diferentes regimes tributários

9. 📖 Códigos Auxiliares de Tributação

   • Lista de códigos CFOP
   • Lista de NCM
   • Lista de origens de mercadoria

10. 🗺️ Inscrições Estaduais

    • Lista de inscrições estaduais por estado brasileiro

---

📦 Detalhamento Técnico das Mudanças

Arquivos Criados (30 novos arquivos)

Recursos (10 arquivos)

src/core/resources/consumer-invoice-query.ts        (141 linhas)
src/core/resources/inbound-product-invoices.ts      (654 linhas)
src/core/resources/legal-entity-lookup.ts           (334 linhas)
src/core/resources/natural-person-lookup.ts         (214 linhas)
src/core/resources/product-invoice-query.ts         (204 linhas)
src/core/resources/product-invoices.ts              (526 linhas)
src/core/resources/state-taxes.ts                   (268 linhas)
src/core/resources/tax-calculation.ts               (194 linhas)
src/core/resources/tax-codes.ts                     (214 linhas)
src/core/resources/transportation-invoices.ts       (397 linhas)

Testes Unitários (11 arquivos)

tests/unit/consumer-invoice-query.test.ts           (275 linhas)
tests/unit/legal-entity-lookup.test.ts              (587 linhas)
tests/unit/natural-person-lookup.test.ts            (300 linhas)
tests/unit/resources/inbound-product-invoices.test.ts  (510 linhas)
tests/unit/resources/product-invoice-query.test.ts  (335 linhas)
tests/unit/resources/product-invoices.test.ts       (560 linhas)
tests/unit/resources/state-taxes.test.ts            (225 linhas)
tests/unit/resources/tax-calculation.test.ts        (176 linhas)
tests/unit/resources/tax-codes.test.ts              (196 linhas)
tests/unit/resources/tax-types.test.ts              (231 linhas)
tests/unit/resources/transportation-invoices.test.ts (487 linhas)

Exemplos (9 arquivos)

examples/cnpj-lookup.js                             (255 linhas)
examples/consumer-invoice-query.js                  (91 linhas)
examples/cpf-lookup.js                              (117 linhas)
examples/inbound-product-invoices.js                (258 linhas)
examples/product-invoice-query.js                   (163 linhas)
examples/product-invoices.js                        (128 linhas)
examples/state-taxes.js                             (85 linhas)
examples/tax-calculation.js                         (165 linhas)
examples/transportation-invoices.js                 (289 linhas)

Arquivos Modificados Principais

1. Core Client (client.ts)

• +521 linhas adicionadas
• Adicionados 10 novos getters de recursos lazy-loaded
• Adicionados 4 novos HTTP clients para diferentes APIs:
  • _cteHttp - API de CT-e (api.nfse.io)
  • _nfeQueryHttp - API de consulta NF-e
  • _legalEntityHttp - API de consulta CNPJ
  • _naturalPersonHttp - API de consulta CPF
• Atualizada configuração para suportar dataApiKey (unificação de chaves auxiliares)

2. Tipos TypeScript (types.ts)

• +2,922 linhas adicionadas
• Adicionados 227+ novos tipos exportados
• Tipos completos para todos os 10 novos recursos
• Enums extensivos para códigos fiscais, status, métodos de pagamento, etc.

3. Exportações Públicas (index.ts)

• +248 linhas adicionadas
• Exportados 227+ novos tipos públicos
• Exportadas 3 novas constantes de URL de API base

4. Documentação

README.md

• +411 linhas adicionadas
• Seções completas para todos os 10 novos recursos
• Exemplos de código para cada recurso
• Notas sobre pré-requisitos e configurações especiais

API.md

• +1,212 linhas adicionadas
• Documentação detalhada de cada novo método
• Parâmetros, retornos e exceções documentados
• Exemplos práticos para cada operação

5. HTTP Client (client.ts)

• Adicionado tratamento para novos endpoints
• Melhorias no handling de requests multi-API

6. OpenAPI Specs

• Renomeado cpf-api.yaml para consulta-cpf.yaml
• Atualizado timestamp em calculo-impostos-v1.yaml

---

🔧 Mudanças de Configuração

Breaking Changes (Configuração)

❌ Removido: addressApiKey
❌ Removido: cteApiKey

✅ Adicionado: dataApiKey (unifica todas as chaves de APIs auxiliares)

// Antes (v3.0.2)
const nfe = new NfeClient({
  apiKey: 'xxx',
  addressApiKey: 'yyy',  // ❌ Descontinuado
  cteApiKey: 'zzz'       // ❌ Descontinuado
});

// Agora (v3.1.0)
const nfe = new NfeClient({
  apiKey: 'xxx',
  dataApiKey: 'yyy'      // ✅ Unificado
});

---

📊 Cobertura de Testes

Novos Testes Adicionados

• 11 novos arquivos de teste
• 3,882+ linhas de código de teste
• Cobertura completa dos 10 novos recursos
• Testes unitários com mocks para todas as operações
• Testes de validação de parâmetros
• Testes de tratamento de erros

Status de Testes

✅ Todos os testes existentes continuam passando
✅ Novos testes implementados para todos os recursos
✅ Cobertura estimada > 85%

---

🔍 Exemplos de Uso dos Novos Recursos

1. Consulta CNPJ

const nfe = new NfeClient({ apiKey: 'xxx', dataApiKey: 'yyy' });

// Informações básicas
const info = await nfe.legalEntityLookup.getBasicInfo('12345678000190');
console.log('Razão Social:', info.name);
console.log('Regime Tributário:', info.taxRegime);

// Inscrições estaduais para nota fiscal
const inscricoes = await nfe.legalEntityLookup.getStateTaxForInvoice(
  '12345678000190',
  'SP'
);
console.log('IE SP:', inscricoes.stateRegistration);

2. CT-e (Transporte)

// Ativar busca automática
const settings = await nfe.transportationInvoices.enable('empresa-id', {
  startFromNsu: 12345
});

// Consultar CT-e por chave
const cte = await nfe.transportationInvoices.retrieve(
  'empresa-id',
  '35240112345678000190570010000001231234567890'
);

// Download XML
const xml = await nfe.transportationInvoices.downloadXml(
  'empresa-id',
  '35240112345678000190570010000001231234567890'
);

3. NF-e de Produto

// Criar NF-e de produto
const nfe = await nfe.productInvoices.create('empresa-id', {
  buyer: { /* ... */ },
  items: [{ /* ... */ }],
  payment: { /* ... */ }
});

// Cancelar NF-e
await nfe.productInvoices.cancel('empresa-id', 'nfe-id', {
  reason: 'Erro no pedido'
});

// Download PDF
const pdf = await nfe.productInvoices.downloadPdf('empresa-id', 'nfe-id');

4. Cálculo de Impostos

const calculo = await nfe.taxCalculation.calculate({
  issuer: {
    federalTaxNumber: '12345678000190',
    state: 'SP'
  },
  recipient: {
    federalTaxNumber: '98765432000100',
    state: 'RJ'
  },
  items: [{
    code: 'PROD-001',
    description: 'Produto teste',
    ncm: '12345678',
    cfop: '5102',
    unitValue: 100.00,
    quantity: 2
  }]
});

console.log('ICMS:', calculo.items[0].icms);
console.log('PIS:', calculo.items[0].pis);
console.log('COFINS:', calculo.items[0].cofins);

---

🐛 Correções Incluídas

.gitignore

• ✅ Corrigida entrada do diretório client-python
• ✅ Removidos arquivos de teste obsoletos

CI/CD

• ✅ Adicionados triggers para branches bugfix/* e chore/*

Documentação

• ✅ Corrigidos headers de seção no README.md

Generated Files

• ✅ Atualizados timestamps de regeneração dos tipos OpenAPI

---

📈 Impacto e Métricas

Crescimento do SDK

• Recursos: 5 → 15 (+200%)
• Linhas de código (src/): ~3,500 → ~10,000 (+186%)
• Linhas de teste: ~2,000 → ~6,000 (+200%)
• Exemplos: 8 → 17 (+112%)
• Tipos exportados: ~100 → 327+ (+227%)

APIs Suportadas

• ✅ NFS-e (Service Invoices) - Existente
• ✅ Pessoa Jurídica/Física - Existente
• ✅ Webhooks - Existente
• ✅ Endereços - Existente
• ✅ CT-e - NOVO
• ✅ NF-e Distribuição - NOVO
• ✅ NF-e Consulta - NOVO
• ✅ CFe-SAT - NOVO
• ✅ Consulta CNPJ - NOVO
• ✅ Consulta CPF - NOVO
• ✅ NF-e Produto - NOVO
• ✅ Cálculo Impostos - NOVO
• ✅ Códigos Auxiliares - NOVO
• ✅ Inscrições Estaduais - NOVO

[github-actions]

📋 OpenAPI Spec Validation

✅ All specs validated and types generated successfully

Specs processed:

• calculo-impostos-v1.yaml - 27.90 KB, 853 lines
• consulta-cnpj.yaml - 34.28 KB, 1128 lines
• consulta-cpf.yaml - 3.39 KB, 83 lines
• consulta-cte-v2.yaml - 18.33 KB, 578 lines
• consulta-endereco.yaml - 11.17 KB, 343 lines
• consulta-nf-consumidor.yaml - 43.41 KB, 1279 lines
• consulta-nf.yaml - 137.87 KB, 3119 lines
• consulta-nfe-distribuicao-v1.yaml - 53.07 KB, 1775 lines
• nf-consumidor-v2.yaml - 293.87 KB, 7609 lines
• nf-produto-v2.yaml - 309.41 KB, 8204 lines
• nf-servico-v1.yaml - 257.42 KB, 6252 lines
• nfeio.yaml - 15.86 KB, 630 lines

Generated types available as artifact in src/generated/.