@pairus/product-data 1.1.0 → 1.3.0

package/README.md

@@ -1,141 +1,408 @@
-# PAIRUS Product Data SDK para Node.js & TypeScript (`@pairus/product-data`)
-
-SDK oficial da **PAIRUS Soluções Tecnológicas** para Node.js e TypeScript com tipagem completa, auto-complete inteligente, retentativas automáticas e helper para validação de Webhooks HMAC-SHA256.
-
-[![npm version](https://img.shields.io/npm/v/@pairus/product-data.svg)](https://www.npmjs.com/package/@pairus/product-data)
-[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
-
----
-
-## 📦 Instalação
-
-```bash
-npm install @pairus/product-data
-# ou
-yarn add @pairus/product-data
-# ou
-pnpm add @pairus/product-data
-```
-
----
-
-## 🚀 Início Rápido
-
-### 1. Consulta de Produto por GTIN
-
-```typescript
-import { PairusProductData } from '@pairus/product-data';
-
-// Inicializa o cliente (lê automaticamente process.env.PAIRUS_API_KEY se omitido)
-const client = new PairusProductData({ apiKey: 'pk_live_...' });
-
-async function main() {
-  const produto = await client.products.get('7891000744703');
-  console.log(`Produto: ${produto.xProd}`);
-  console.log(`NCM: ${produto.ncm} | CEST: ${produto.cest}`);
-}
-
-main();
-```
-
-### 2. Predição Fiscal com Reforma Tributária (IBS/CBS/IS)
-
-```typescript
-import { PairusProductData } from '@pairus/product-data';
-
-const client = new PairusProductData();
-
-async function prever() {
-  const predicao = await client.fiscal.predict({
-    xProd: 'Refrigerante Coca-Cola Lata 350ml',
-    gtin: '7894900010015',
-    regimeTributario: 'simples_nacional',
-    ufOrigem: 'SP',
-    ufDestino: 'RJ',
-    finalidade: 'revenda',
-  });
-
-  const tributos = predicao.dados_tributarios!;
-  console.log(`NCM Sugerido: ${tributos.ncm_sugerido}`);
-  console.log(`CST IBS/CBS: ${tributos.ibscbs.cst}`);
-  console.log(`Alíquota Efetiva CBS: ${tributos.ibscbs.cbs_aliquota_efetiva}%`);
-  console.log(`Alíquota Efetiva IBS: ${tributos.ibscbs.ibs_aliquota_efetiva}%`);
-  console.log(`Alíquota Unificada: ${tributos.aliquota_efetiva_unificada}%`);
-}
-
-prever();
-```
-
-### 3. Validação de Webhooks (Express / Next.js)
-
-```typescript
-import express from 'express';
-import { Webhooks } from '@pairus/product-data';
-
-const app = express();
-
-app.post('/webhooks/pairus', express.raw({ type: 'application/json' }), (req, res) => {
-  const signature = req.headers['x-pairus-signature'] as string;
-  const secret = process.env.PAIRUS_WEBHOOK_SECRET!;
-
-  try {
-    const evento = Webhooks.constructEvent(req.body, signature, secret);
-    console.log(`Evento recebido: ${evento.event}`, evento.data);
-    res.status(200).json({ received: true });
-  } catch (err) {
-    res.status(400).json({ error: 'Assinatura inválida' });
-  }
-});
-```
-
-### 4. Emissão de NF-e / NFC-e com Autocura SEFAZ
-
-```typescript
-import { PairusProductData } from '@pairus/product-data';
-
-const client = new PairusProductData();
-
-async function emitir() {
-  // Emissão de NF-e (Modelo 55) com correção inteligente pré-transmissão
-  const nfe = await client.emissao.emitirNFe({
-    natureza_operacao: 'VENDA DE MERCADORIAS',
-    autocura: true,
-    itens: [
-      {
-        cProd: 'PROD-001',
-        xProd: 'Refrigerante Coca-Cola 350ml',
-        NCM: '22021000',
-        CFOP: '5102',
-        uCom: 'UN',
-        qCom: 10,
-        vUnCom: 5.0,
-        vProd: 50.0,
-      },
-    ],
-  });
-
-  console.log(`Status SEFAZ: ${nfe.cStat} - ${nfe.xMotivo}`);
-  console.log(`Chave de Acesso: ${nfe.chave_acesso}`);
-  console.log(`DANFE PDF: ${nfe.danfe_url}`);
-
-  // Simulação com custo ZERO de créditos
-  const simulacao = await client.emissao.simular({
-    natureza_operacao: 'TESTE PREVIO',
-    itens: [{ cProd: 'T1', xProd: 'Item', NCM: '22021000', CFOP: '5102', uCom: 'UN', qCom: 1, vUnCom: 10, vProd: 10 }],
-  });
-  console.log(`DANFE Simulado: ${simulacao.danfe_url}`);
-
-  // Cancelamento oficial perante o Fisco
-  await client.emissao.cancelar({
-    chave_acesso: nfe.chave_acesso!,
-    justificativa: 'Desistencia de compra pelo consumidor final',
-  });
-}
-
-emitir();
-```
-
----
-
-## 🛡️ Licença
-Distribuído sob a licença MIT.
+# PAIRUS Product Data SDK para Node.js & TypeScript 🟢
+
+[![npm version](https://img.shields.io/npm/v/@pairus/product-data.svg?style=flat-square)](https://www.npmjs.com/package/@pairus/product-data)
+[![npm downloads](https://img.shields.io/npm/dm/@pairus/product-data.svg?style=flat-square)](https://www.npmjs.com/package/@pairus/product-data)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg?style=flat-square)](https://opensource.org/licenses/MIT)
+
+SDK oficial da **PAIRUS Soluções Tecnológicas** para Node.js (18+) e TypeScript, com suporte nativo a ESM e CommonJS, tipagem estrita com TypeScript Interfaces, retentativas automáticas com *Exponential Backoff* e tratamento amigável de erros da SEFAZ (`cStat` e `xMotivo`).
+
+---
+
+## ⚡ Quickstart em 3 Linhas
+
+```typescript
+import { PairusProductData } from '@pairus/product-data';
+
+const client = new PairusProductData({ apiKey: 'sua_chave_pairus' });
+const produto = await client.products.get('7891000100103');
+console.log(`${produto.xProd} | NCM: ${produto.ncm} | CEST: ${produto.cest}`);
+```
+
+---
+
+## 📦 Instalação
+
+```bash
+npm install @pairus/product-data
+# ou
+yarn add @pairus/product-data
+# ou
+pnpm add @pairus/product-data
+```
+
+---
+
+## 🛠️ Inicialização e Configuração
+
+Você pode passar a chave diretamente no construtor ou configurar a variável de ambiente `PAIRUS_API_KEY`:
+
+```typescript
+// TypeScript / ES Modules (ESM)
+import { PairusProductData } from '@pairus/product-data';
+const client = new PairusProductData(); // lê PAIRUS_API_KEY do ambiente
+
+// CommonJS (CJS)
+const { PairusProductData } = require('@pairus/product-data');
+const client = new PairusProductData({ apiKey: 'pk_live_...' });
+```
+
+---
+
+## 📚 Módulos e Casos de Uso Práticos
+
+### 1. 🔍 Catálogo GTIN & Produtos
+
+#### A. Consulta Básica (V1)
+```typescript
+const produto = await client.products.get('7891000100103');
+console.log(produto.xProd, produto.marca, produto.ncm, produto.cest);
+```
+
+#### B. Consulta Enriquecida por IA com SEO e Ficha Técnica (V2)
+```typescript
+const enriched = await client.products.getEnriched('7891000100103');
+console.log(enriched.descricao_completa);
+console.log(enriched.ficha_tecnica); // Dimensões, volume, peso, etc.
+console.log(enriched.palavras_chave); // Otimizadas para e-commerce
+```
+
+#### C. Busca Semântica por Intenção (Linguagem Natural)
+```typescript
+const resultado = await client.products.search('refrigerante zero açucar lata');
+for (const item of resultado.produtos) {
+  console.log(`[Score: ${item.score}] ${item.gtin} - ${item.xProd}`);
+}
+```
+
+#### D. Leitura de Código de Barras por Imagem (OCR V2)
+```typescript
+import * as fs from 'fs';
+
+const imageBuffer = fs.readFileSync('foto_rotulo.jpg');
+const produto = await client.products.scan(imageBuffer);
+console.log(`Detectado GTIN: ${produto.gtin} - ${produto.xProd}`);
+```
+
+---
+
+### 2. ⚖️ Predição Fiscal & Reforma Tributária (IBS / CBS / IS)
+
+Obtenha parâmetros fiscais completos e em total conformidade com a Reforma Tributária (LC 214/2025):
+
+```typescript
+const predicao = await client.fiscal.predict({
+  xProd: 'Refrigerante Coca-Cola 350ml',
+  regimeTributario: 'simples_nacional', // 'simples_nacional', 'lucro_presumido' ou 'lucro_real'
+  ufOrigem: 'SP',
+  ufDestino: 'RJ',
+  finalidade: 'revenda', // 'revenda', 'consumo_final' ou 'industrializacao'
+  destinatarioContribuinte: true,
+});
+
+const trib = predicao.dados_tributarios!;
+console.log(`CFOP: ${trib.cfop} | CST/CSOSN: ${trib.icms_cst_csosn}`);
+console.log(`IBS Efetivo: ${trib.ibscbs.ibs_aliquota_efetiva}% | CBS: ${trib.ibscbs.cbs_aliquota_efetiva}%`);
+```
+
+#### Saneamento Fiscal em Lote
+```typescript
+const lote = await client.fiscal.sanitize([
+  { ncm: '22021000', descricao: 'Refrigerante Cola' },
+  { ncm: '22030000', descricao: 'Cerveja Pilsen' },
+]);
+
+for (const item of lote.itens) {
+  console.log(`NCM: ${item.ncm} | CEST Sugerido: ${item.cest_sugerido}`);
+}
+```
+
+---
+
+### 3. 🧾 Emissão de NF-e e NFC-e com Autocura SEFAZ
+
+#### Forma 1: Modo Rápido (Objeto Simples / Dinâmico)
+```typescript
+const nota = await client.emissao.emitirNFe({
+  serie: 1,
+  natureza_operacao: 'Venda de Mercadorias',
+  destinatario: {
+    documento: '12345678000195',
+    razao_social: 'Cliente Exemplo LTDA',
+    uf: 'SP',
+    email: 'financeiro@cliente.com.br',
+  },
+  itens: [
+    {
+      descricao: 'Mouse Sem Fio USB',
+      ncm: '84716053',
+      quantidade: 2,
+      valor_unitario: 49.90,
+      cfop: '5102',
+    },
+  ],
+});
+
+if (nota.sucesso) {
+  console.log(`✅ NF-e Autorizada! Chave: ${nota.chave_acesso}`);
+  console.log(`📄 Protocolo SEFAZ: ${nota.protocolo_autorizacao}`);
+  console.log(`🖨️ DANFE URL: ${nota.danfe_url}`);
+} else {
+  console.log(`❌ Rejeição SEFAZ [${nota.cStat}]: ${nota.xMotivo}`);
+}
+```
+
+#### Forma 2: Simulação Gratuita (Custo ZERO de créditos)
+```typescript
+const simulacao = await client.emissao.simular({
+  destinatario: { documento: '12345678000195', razao_social: 'Teste', uf: 'SP' },
+  itens: [{ descricao: 'Item Teste', valor_unitario: 100 }],
+});
+console.log('Simulação realizada:', simulacao.sucesso);
+```
+
+---
+
+### 4. 🏛️ Emissão de NFS-e (Serviços - Padrão Nacional SND / ABRASF)
+
+```typescript
+const nfse = await client.nfse.emitir({
+  prestador: {
+    cnpj: '12345678000195',
+    inscricao_municipal: '123456',
+    razao_social: 'Minha Empresa Tech LTDA',
+  },
+  tomador: {
+    cpf_cnpj: '98765432000198',
+    razao_social: 'Cliente Tomador S.A.',
+    email: 'contas@tomador.com.br',
+  },
+  servico: {
+    item_lista_servico: '1.07', // Suporte técnico e TI (LC 116/2003)
+    discriminacao: 'Desenvolvimento e manutenção de software sob medida',
+    municipio_prestacao_ibge: '3550308', // São Paulo/SP
+    valor_servicos: 4500.0,
+    aliquota_iss: 2.0,
+    iss_retido: false,
+    retencoes_federais: {
+      pis_retido: true, aliquota_pis: 0.65, valor_pis: 29.25,
+      cofins_retido: true, aliquota_cofins: 3.0, valor_cofins: 135.0,
+      csll_retida: true, aliquota_csll: 1.0, valor_csll: 45.0,
+      irrf_retido: true, aliquota_irrf: 1.5, valor_irrf: 67.50,
+    },
+  },
+});
+
+if (nfse.sucesso) {
+  console.log(`✅ NFS-e Emitida! Número: ${nfse.numero_nfse}`);
+  console.log(`🔑 Chave Nacional: ${nfse.chave_acesso_nacional}`);
+  console.log(`💰 Valor Líquido: R$ ${nfse.valor_liquido.toFixed(2)}`);
+  console.log(`🖨️ DANFSE URL: ${nfse.link_visualizacao}`);
+}
+```
+
+---
+
+### 5. 🔄 Ciclo de Vida e Eventos Fiscais
+
+#### Cancelamento de NF-e
+```typescript
+const cancelamento = await client.emissao.cancelar({
+  chave_acesso: '35260912345678000195550010000000451234567890',
+  justificativa: 'Cancelamento acordado formalmente entre as partes envolvidas',
+});
+console.log('Cancelamento registrado:', cancelamento.sucesso);
+```
+
+#### Carta de Correção (CC-e)
+```typescript
+const cce = await client.emissao.cartaCorrecao({
+  chave_acesso: '35260912345678000195550010000000451234567890',
+  correcao: 'Correção do endereço de entrega: Rua das Palmeiras, 456 - Bairro Central',
+});
+console.log('CC-e protocolada:', cce.sucesso);
+```
+
+#### Inutilização de Faixa de Numeração Quebrada
+```typescript
+const inut = await client.emissao.inutilizar({
+  cnpj_emitente: '12345678000195',
+  serie: 1,
+  numero_inicial: 100,
+  numero_final: 105,
+  justificativa: 'Quebra involuntária de numeração por oscilação de conectividade',
+});
+console.log('Inutilização homologada:', inut.sucesso);
+```
+
+### 6. 📥 DF-e Inbound & Captura SEFAZ Nacional (Gestão de Compras)
+
+Capture ativamente as notas fiscais emitidas por fornecedores contra o seu CNPJ via WebService `NFeDistribuicaoDFe` da SEFAZ Nacional, com controle incremental de NSU, descompactação automática de lotes `docZip` e Manifestação do Destinatário.
+
+#### A. Sincronizar Documentos com a SEFAZ
+```typescript
+const sync = await client.dfe.sincronizar({
+  cnpj: '12345678000195',
+  ambiente: 'producao',
+});
+
+console.log(`Status SEFAZ [${sync.cstat}]: ${sync.xmotivo}`);
+console.log(`Novos documentos capturados: ${sync.novos_documentos}`);
+console.log(`NSU Atualizado: ${sync.ult_nsu} -> ${sync.max_nsu}`);
+
+for (const doc of sync.documentos) {
+  console.log(`NF-e ${doc.numero}/${doc.serie} - R$ ${doc.valor_total} (${doc.nome_emitente})`);
+}
+```
+
+#### B. Listar Compras Recebidas
+```typescript
+const compras = await client.dfe.listarDocumentos({
+  cnpj: '12345678000195',
+  limite: 50,
+});
+
+for (const doc of compras.documentos) {
+  console.log(`Chave: ${doc.chave_acesso} | Manifestação: ${doc.manifestacao_status}`);
+}
+```
+
+#### C. Manifestação do Destinatário na SEFAZ
+```typescript
+// 1. Ciência da Emissão (Libera o XML completo procNFe)
+const ciencia = await client.dfe.manifestar({
+  chave_acesso: '35260912345678000195550010000000451234567890',
+  cnpj: '12345678000195',
+  tipo_evento: '210210',
+});
+console.log('Ciência homologada. Protocolo:', ciencia.protocolo);
+
+// 2. Confirmação da Operação (Atesta recebimento da mercadoria)
+await client.dfe.manifestar({
+  chave_acesso: '35260912345678000195550010000000451234567890',
+  cnpj: '12345678000195',
+  tipo_evento: '210200',
+});
+
+// 3. Operação Não Realizada (Exige justificativa mínima de 15 caracteres)
+await client.dfe.manifestar({
+  chave_acesso: '35260912345678000195550010000000451234567890',
+  cnpj: '12345678000195',
+  tipo_evento: '210240',
+  justificativa: 'Mercadoria não entregue pelo transportador no prazo estipulado',
+});
+```
+
+#### D. Download de XML e DANFE (PDF)
+```typescript
+import * as fs from 'fs/promises';
+
+const chave = '35260912345678000195550010000000451234567890';
+
+// Baixa o XML completo
+const xmlString = await client.dfe.baixarXml(chave);
+await fs.writeFile(`${chave}.xml`, xmlString, 'utf-8');
+
+// Baixa o DANFE em PDF
+const danfeBuffer = await client.dfe.baixarDanfe(chave);
+await fs.writeFile(`DANFE_${chave}.pdf`, Buffer.from(danfeBuffer));
+```
+
+---
+
+### 7. 🔐 Webhooks Seguros (HMAC-SHA256)
+
+```typescript
+import { Webhooks } from '@pairus/product-data';
+
+// Em um handler Express, Fastify ou Next.js:
+const payloadBruto = req.rawBody; // String ou Buffer recebido bruto
+const signature = req.headers['x-pairus-signature'] as string;
+const webhookSecret = process.env.PAIRUS_WEBHOOK_SECRET!;
+
+try {
+  const evento = Webhooks.constructEvent(payloadBruto, signature, webhookSecret);
+  console.log(`Evento seguro recebido: ${evento.event} na data ${evento.timestamp}`);
+} catch (err: any) {
+  console.error(`Assinatura forjada ou inválida! ${err.message}`);
+}
+```
+
+---
+
+## 📋 Tabela de Parâmetros (Obrigatórios vs. Opcionais)
+
+### 📌 Emissão de NF-e / NFC-e (`client.emissao.emitirNFe`)
+
+| Propriedade | Tipo | Obrigatoriedade | Padrão | Regras & Descrição |
+| :--- | :---: | :---: | :---: | :--- |
+| `destinatario.documento` | `string` | **Obrigatório** | - | CPF (11 dígitos) ou CNPJ (14 dígitos). |
+| `destinatario.razao_social` | `string` | **Obrigatório** | - | Razão Social ou Nome do destinatário. |
+| `destinatario.uf` | `string` | **Obrigatório** | - | Sigla da UF do destinatário (2 letras). |
+| `itens` | `Array` | **Obrigatório** | - | Pelo menos 1 item na lista. |
+| `itens[].descricao` | `string` | **Obrigatório** | - | Descrição clara do item na nota. |
+| `itens[].valor_unitario` | `number` | **Obrigatório** | - | Preço unitário maior que 0. |
+| `itens[].quantidade` | `number` | Opcional | `1.0` | Quantidade comercializada. |
+| `itens[].ncm` | `string` | Opcional | Auto | NCM de 8 dígitos (enquadrado por IA se omitido). |
+| `itens[].cfop` | `string` | Opcional | Auto | CFOP da operação. |
+| `serie` | `number` | Opcional | `1` | Série da nota fiscal (1 a 999). |
+
+### 📌 Emissão de NFS-e (`client.nfse.emitir`)
+
+| Propriedade | Tipo | Obrigatoriedade | Padrão | Regras & Descrição |
+| :--- | :---: | :---: | :---: | :--- |
+| `prestador.cnpj` | `string` | **Obrigatório** | - | CNPJ da empresa prestadora (14 dígitos). |
+| `prestador.inscricao_municipal` | `string` | **Obrigatório** | - | Inscrição Municipal do prestador. |
+| `prestador.razao_social` | `string` | **Obrigatório** | - | Razão Social do prestador emitente. |
+| `tomador.cpf_cnpj` | `string` | **Obrigatório** | - | CPF (11) ou CNPJ (14) do cliente tomador. |
+| `tomador.razao_social` | `string` | **Obrigatório** | - | Nome completo ou Razão Social do tomador. |
+| `servico.item_lista_servico` | `string` | **Obrigatório** | - | Subitem da LC 116/2003 (ex: `"1.07"`). |
+| `servico.discriminacao` | `string` | **Obrigatório** | - | Descrição detalhada do serviço. |
+| `servico.municipio_prestacao_ibge`| `string`| **Obrigatório** | - | Código IBGE do local do serviço (7 dígitos). |
+| `servico.valor_servicos` | `number` | **Obrigatório** | - | Valor bruto cobrado pelo serviço (R$). |
+| `servico.aliquota_iss` | `number` | Opcional | `2.0` | Alíquota de ISS de 0.0% a 5.0%. |
+| `servico.iss_retido` | `boolean`| Opcional | `false` | Se o ISS deve ser retido pelo tomador. |
+| `modo` | `string` | Opcional | `'direto'` | `'direto'` (pass-through) ou `'assistido'` (IA). |
+| `ambiente` | `string` | Opcional | `'producao'` | `'producao'` ou `'homologacao'`. |
+
+### 📌 Manifestação do Destinatário (`client.dfe.manifestar`)
+
+| Propriedade | Tipo | Obrigatoriedade | Padrão | Regras & Descrição |
+| :--- | :---: | :---: | :---: | :--- |
+| `chave_acesso` | `string` | **Obrigatório** | - | Chave de acesso de 44 dígitos da NF-e emitida pelo fornecedor. |
+| `cnpj` | `string` | **Obrigatório** | - | CNPJ da sua empresa compradora/destinatária. |
+| `tipo_evento` | `string` | **Obrigatório** | - | `'210210'` (Ciência), `'210200'` (Confirmação), `'210220'` (Desconhecimento) ou `'210240'` (Não Realizada). |
+| `justificativa`| `string` | Condicional | - | Obrigatória estritamente para `'210240'` (mínimo de 15 caracteres). |
+| `ambiente` | `string` | Opcional | `'producao'` | `'producao'` ou `'homologacao'`. |
+
+---
+
+## 🛡️ Tratamento de Erros e Exceções
+
+```typescript
+import {
+  PairusAPIError,
+  AuthenticationError,
+  RateLimitError,
+  NetworkError,
+} from '@pairus/product-data';
+
+try {
+  await client.emissao.emitirNFe(...);
+} catch (err: any) {
+  if (err instanceof AuthenticationError) {
+    console.error('Chave de API inválida');
+  } else if (err instanceof RateLimitError) {
+    console.error(`Rate limit atingido. Aguarde ${err.retryAfter}s`);
+  } else if (err instanceof PairusAPIError) {
+    console.error(`Erro Fiscal [${err.cStat}]: ${err.xMotivo}`);
+  } else if (err instanceof NetworkError) {
+    console.error('Falha de rede após retentativas');
+  }
+}
+```
+
+---
+
+## 📄 Licença
+
+Distribuído sob a licença **MIT**. Consulte o arquivo [LICENSE](LICENSE) para obter mais informações.