@pairus/product-data 1.4.0 → 1.5.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (8) hide show
  1. package/README.md +431 -407
  2. package/dist/index.d.mts +80 -73
  3. package/dist/index.d.ts +80 -73
  4. package/dist/index.js +14 -7
  5. package/dist/index.js.map +1 -1
  6. package/dist/index.mjs +14 -7
  7. package/dist/index.mjs.map +1 -1
  8. package/package.json +1 -1
package/README.md CHANGED
@@ -1,408 +1,432 @@
1
- # PAIRUS Product Data SDK para Node.js & TypeScript 🟢
2
-
3
- [![npm version](https://img.shields.io/npm/v/@pairus/product-data.svg?style=flat-square)](https://www.npmjs.com/package/@pairus/product-data)
4
- [![npm downloads](https://img.shields.io/npm/dm/@pairus/product-data.svg?style=flat-square)](https://www.npmjs.com/package/@pairus/product-data)
5
- [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg?style=flat-square)](https://opensource.org/licenses/MIT)
6
-
7
- 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`).
8
-
9
- ---
10
-
11
- ## ⚡ Quickstart em 3 Linhas
12
-
13
- ```typescript
14
- import { PairusProductData } from '@pairus/product-data';
15
-
16
- const client = new PairusProductData({ apiKey: 'sua_chave_pairus' });
17
- const produto = await client.products.get('7891000100103');
18
- console.log(`${produto.xProd} | NCM: ${produto.ncm} | CEST: ${produto.cest}`);
19
- ```
20
-
21
- ---
22
-
23
- ## 📦 Instalação
24
-
25
- ```bash
26
- npm install @pairus/product-data
27
- # ou
28
- yarn add @pairus/product-data
29
- # ou
30
- pnpm add @pairus/product-data
31
- ```
32
-
33
- ---
34
-
35
- ## 🛠️ Inicialização e Configuração
36
-
37
- Você pode passar a chave diretamente no construtor ou configurar a variável de ambiente `PAIRUS_API_KEY`:
38
-
39
- ```typescript
40
- // TypeScript / ES Modules (ESM)
41
- import { PairusProductData } from '@pairus/product-data';
42
- const client = new PairusProductData(); // lê PAIRUS_API_KEY do ambiente
43
-
44
- // CommonJS (CJS)
45
- const { PairusProductData } = require('@pairus/product-data');
46
- const client = new PairusProductData({ apiKey: 'pk_live_...' });
47
- ```
48
-
49
- ---
50
-
51
- ## 📚 Módulos e Casos de Uso Práticos
52
-
53
- ### 1. 🔍 Catálogo GTIN & Produtos
54
-
55
- #### A. Consulta Básica (V1)
56
- ```typescript
57
- const produto = await client.products.get('7891000100103');
58
- console.log(produto.xProd, produto.marca, produto.ncm, produto.cest);
59
- ```
60
-
61
- #### B. Consulta Enriquecida por IA com SEO e Ficha Técnica (V2)
62
- ```typescript
63
- const enriched = await client.products.getEnriched('7891000100103');
64
- console.log(enriched.descricao_completa);
65
- console.log(enriched.ficha_tecnica); // Dimensões, volume, peso, etc.
66
- console.log(enriched.palavras_chave); // Otimizadas para e-commerce
67
- ```
68
-
69
- #### C. Busca Semântica por Intenção (Linguagem Natural)
70
- ```typescript
71
- const resultado = await client.products.search('refrigerante zero açucar lata');
72
- for (const item of resultado.produtos) {
73
- console.log(`[Score: ${item.score}] ${item.gtin} - ${item.xProd}`);
74
- }
75
- ```
76
-
77
- #### D. Leitura de Código de Barras por Imagem (OCR V2)
78
- ```typescript
79
- import * as fs from 'fs';
80
-
81
- const imageBuffer = fs.readFileSync('foto_rotulo.jpg');
82
- const produto = await client.products.scan(imageBuffer);
83
- console.log(`Detectado GTIN: ${produto.gtin} - ${produto.xProd}`);
84
- ```
85
-
86
- ---
87
-
88
- ### 2. ⚖️ Predição Fiscal & Reforma Tributária (IBS / CBS / IS)
89
-
90
- Obtenha parâmetros fiscais completos e em total conformidade com a Reforma Tributária (LC 214/2025):
91
-
92
- ```typescript
93
- const predicao = await client.fiscal.predict({
94
- xProd: 'Refrigerante Coca-Cola 350ml',
95
- regimeTributario: 'simples_nacional', // 'simples_nacional', 'lucro_presumido' ou 'lucro_real'
96
- ufOrigem: 'SP',
97
- ufDestino: 'RJ',
98
- finalidade: 'revenda', // 'revenda', 'consumo_final' ou 'industrializacao'
99
- destinatarioContribuinte: true,
100
- });
101
-
102
- const trib = predicao.dados_tributarios!;
103
- console.log(`CFOP: ${trib.cfop} | CST/CSOSN: ${trib.icms_cst_csosn}`);
104
- console.log(`IBS Efetivo: ${trib.ibscbs.ibs_aliquota_efetiva}% | CBS: ${trib.ibscbs.cbs_aliquota_efetiva}%`);
105
- ```
106
-
107
- #### Saneamento Fiscal em Lote
108
- ```typescript
109
- const lote = await client.fiscal.sanitize([
110
- { ncm: '22021000', descricao: 'Refrigerante Cola' },
111
- { ncm: '22030000', descricao: 'Cerveja Pilsen' },
112
- ]);
113
-
114
- for (const item of lote.itens) {
115
- console.log(`NCM: ${item.ncm} | CEST Sugerido: ${item.cest_sugerido}`);
116
- }
117
- ```
118
-
119
- ---
120
-
121
- ### 3. 🧾 Emissão de NF-e e NFC-e com Autocura SEFAZ
122
-
123
- #### Forma 1: Modo Rápido (Objeto Simples / Dinâmico)
124
- ```typescript
125
- const nota = await client.emissao.emitirNFe({
126
- serie: 1,
127
- natureza_operacao: 'Venda de Mercadorias',
128
- destinatario: {
129
- documento: '12345678000195',
130
- razao_social: 'Cliente Exemplo LTDA',
131
- uf: 'SP',
132
- email: 'financeiro@cliente.com.br',
133
- },
134
- itens: [
135
- {
136
- descricao: 'Mouse Sem Fio USB',
137
- ncm: '84716053',
138
- quantidade: 2,
139
- valor_unitario: 49.90,
140
- cfop: '5102',
141
- },
142
- ],
143
- });
144
-
145
- if (nota.sucesso) {
146
- console.log(`✅ NF-e Autorizada! Chave: ${nota.chave_acesso}`);
147
- console.log(`📄 Protocolo SEFAZ: ${nota.protocolo_autorizacao}`);
148
- console.log(`🖨️ DANFE URL: ${nota.danfe_url}`);
149
- } else {
150
- console.log(`❌ Rejeição SEFAZ [${nota.cStat}]: ${nota.xMotivo}`);
151
- }
152
- ```
153
-
154
- #### Forma 2: Simulação Gratuita (Custo ZERO de créditos)
155
- ```typescript
156
- const simulacao = await client.emissao.simular({
157
- destinatario: { documento: '12345678000195', razao_social: 'Teste', uf: 'SP' },
158
- itens: [{ descricao: 'Item Teste', valor_unitario: 100 }],
159
- });
160
- console.log('Simulação realizada:', simulacao.sucesso);
161
- ```
162
-
163
- ---
164
-
165
- ### 4. 🏛️ Emissão de NFS-e (Serviços - Padrão Nacional SND / ABRASF)
166
-
167
- ```typescript
168
- const nfse = await client.nfse.emitir({
169
- prestador: {
170
- cnpj: '12345678000195',
171
- inscricao_municipal: '123456',
172
- razao_social: 'Minha Empresa Tech LTDA',
173
- },
174
- tomador: {
175
- cpf_cnpj: '98765432000198',
176
- razao_social: 'Cliente Tomador S.A.',
177
- email: 'contas@tomador.com.br',
178
- },
179
- servico: {
180
- item_lista_servico: '1.07', // Suporte técnico e TI (LC 116/2003)
181
- discriminacao: 'Desenvolvimento e manutenção de software sob medida',
182
- municipio_prestacao_ibge: '3550308', // São Paulo/SP
183
- valor_servicos: 4500.0,
184
- aliquota_iss: 2.0,
185
- iss_retido: false,
186
- retencoes_federais: {
187
- pis_retido: true, aliquota_pis: 0.65, valor_pis: 29.25,
188
- cofins_retido: true, aliquota_cofins: 3.0, valor_cofins: 135.0,
189
- csll_retida: true, aliquota_csll: 1.0, valor_csll: 45.0,
190
- irrf_retido: true, aliquota_irrf: 1.5, valor_irrf: 67.50,
191
- },
192
- },
193
- });
194
-
195
- if (nfse.sucesso) {
196
- console.log(`✅ NFS-e Emitida! Número: ${nfse.numero_nfse}`);
197
- console.log(`🔑 Chave Nacional: ${nfse.chave_acesso_nacional}`);
198
- console.log(`💰 Valor Líquido: R$ ${nfse.valor_liquido.toFixed(2)}`);
199
- console.log(`🖨️ DANFSE URL: ${nfse.link_visualizacao}`);
200
- }
201
- ```
202
-
203
- ---
204
-
205
- ### 5. 🔄 Ciclo de Vida e Eventos Fiscais
206
-
207
- #### Cancelamento de NF-e
208
- ```typescript
209
- const cancelamento = await client.emissao.cancelar({
210
- chave_acesso: '35260912345678000195550010000000451234567890',
211
- justificativa: 'Cancelamento acordado formalmente entre as partes envolvidas',
212
- });
213
- console.log('Cancelamento registrado:', cancelamento.sucesso);
214
- ```
215
-
216
- #### Carta de Correção (CC-e)
217
- ```typescript
218
- const cce = await client.emissao.cartaCorrecao({
219
- chave_acesso: '35260912345678000195550010000000451234567890',
220
- correcao: 'Correção do endereço de entrega: Rua das Palmeiras, 456 - Bairro Central',
221
- });
222
- console.log('CC-e protocolada:', cce.sucesso);
223
- ```
224
-
225
- #### Inutilização de Faixa de Numeração Quebrada
226
- ```typescript
227
- const inut = await client.emissao.inutilizar({
228
- cnpj_emitente: '12345678000195',
229
- serie: 1,
230
- numero_inicial: 100,
231
- numero_final: 105,
232
- justificativa: 'Quebra involuntária de numeração por oscilação de conectividade',
233
- });
234
- console.log('Inutilização homologada:', inut.sucesso);
235
- ```
236
-
237
- ### 6. 📥 DF-e Inbound & Captura SEFAZ Nacional (Gestão de Compras)
238
-
239
- 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.
240
-
241
- #### A. Sincronizar Documentos com a SEFAZ
242
- ```typescript
243
- const sync = await client.dfe.sincronizar({
244
- cnpj: '12345678000195',
245
- ambiente: 'producao',
246
- });
247
-
248
- console.log(`Status SEFAZ [${sync.cstat}]: ${sync.xmotivo}`);
249
- console.log(`Novos documentos capturados: ${sync.novos_documentos}`);
250
- console.log(`NSU Atualizado: ${sync.ult_nsu} -> ${sync.max_nsu}`);
251
-
252
- for (const doc of sync.documentos) {
253
- console.log(`NF-e ${doc.numero}/${doc.serie} - R$ ${doc.valor_total} (${doc.nome_emitente})`);
254
- }
255
- ```
256
-
257
- #### B. Listar Compras Recebidas
258
- ```typescript
259
- const compras = await client.dfe.listarDocumentos({
260
- cnpj: '12345678000195',
261
- limite: 50,
262
- });
263
-
264
- for (const doc of compras.documentos) {
265
- console.log(`Chave: ${doc.chave_acesso} | Manifestação: ${doc.manifestacao_status}`);
266
- }
267
- ```
268
-
269
- #### C. Manifestação do Destinatário na SEFAZ
270
- ```typescript
271
- // 1. Ciência da Emissão (Libera o XML completo procNFe)
272
- const ciencia = await client.dfe.manifestar({
273
- chave_acesso: '35260912345678000195550010000000451234567890',
274
- cnpj: '12345678000195',
275
- tipo_evento: '210210',
276
- });
277
- console.log('Ciência homologada. Protocolo:', ciencia.protocolo);
278
-
279
- // 2. Confirmação da Operação (Atesta recebimento da mercadoria)
280
- await client.dfe.manifestar({
281
- chave_acesso: '35260912345678000195550010000000451234567890',
282
- cnpj: '12345678000195',
283
- tipo_evento: '210200',
284
- });
285
-
286
- // 3. Operação Não Realizada (Exige justificativa mínima de 15 caracteres)
287
- await client.dfe.manifestar({
288
- chave_acesso: '35260912345678000195550010000000451234567890',
289
- cnpj: '12345678000195',
290
- tipo_evento: '210240',
291
- justificativa: 'Mercadoria não entregue pelo transportador no prazo estipulado',
292
- });
293
- ```
294
-
295
- #### D. Download de XML e DANFE (PDF)
296
- ```typescript
297
- import * as fs from 'fs/promises';
298
-
299
- const chave = '35260912345678000195550010000000451234567890';
300
-
301
- // Baixa o XML completo
302
- const xmlString = await client.dfe.baixarXml(chave);
303
- await fs.writeFile(`${chave}.xml`, xmlString, 'utf-8');
304
-
305
- // Baixa o DANFE em PDF
306
- const danfeBuffer = await client.dfe.baixarDanfe(chave);
307
- await fs.writeFile(`DANFE_${chave}.pdf`, Buffer.from(danfeBuffer));
308
- ```
309
-
310
- ---
311
-
312
- ### 7. 🔐 Webhooks Seguros (HMAC-SHA256)
313
-
314
- ```typescript
315
- import { Webhooks } from '@pairus/product-data';
316
-
317
- // Em um handler Express, Fastify ou Next.js:
318
- const payloadBruto = req.rawBody; // String ou Buffer recebido bruto
319
- const signature = req.headers['x-pairus-signature'] as string;
320
- const webhookSecret = process.env.PAIRUS_WEBHOOK_SECRET!;
321
-
322
- try {
323
- const evento = Webhooks.constructEvent(payloadBruto, signature, webhookSecret);
324
- console.log(`Evento seguro recebido: ${evento.event} na data ${evento.timestamp}`);
325
- } catch (err: any) {
326
- console.error(`Assinatura forjada ou inválida! ${err.message}`);
327
- }
328
- ```
329
-
330
- ---
331
-
332
- ## 📋 Tabela de Parâmetros (Obrigatórios vs. Opcionais)
333
-
334
- ### 📌 Emissão de NF-e / NFC-e (`client.emissao.emitirNFe`)
335
-
336
- | Propriedade | Tipo | Obrigatoriedade | Padrão | Regras & Descrição |
337
- | :--- | :---: | :---: | :---: | :--- |
338
- | `destinatario.documento` | `string` | **Obrigatório** | - | CPF (11 dígitos) ou CNPJ (14 dígitos). |
339
- | `destinatario.razao_social` | `string` | **Obrigatório** | - | Razão Social ou Nome do destinatário. |
340
- | `destinatario.uf` | `string` | **Obrigatório** | - | Sigla da UF do destinatário (2 letras). |
341
- | `itens` | `Array` | **Obrigatório** | - | Pelo menos 1 item na lista. |
342
- | `itens[].descricao` | `string` | **Obrigatório** | - | Descrição clara do item na nota. |
343
- | `itens[].valor_unitario` | `number` | **Obrigatório** | - | Preço unitário maior que 0. |
344
- | `itens[].quantidade` | `number` | Opcional | `1.0` | Quantidade comercializada. |
345
- | `itens[].ncm` | `string` | Opcional | Auto | NCM de 8 dígitos (enquadrado por IA se omitido). |
346
- | `itens[].cfop` | `string` | Opcional | Auto | CFOP da operação. |
347
- | `serie` | `number` | Opcional | `1` | Série da nota fiscal (1 a 999). |
348
-
349
- ### 📌 Emissão de NFS-e (`client.nfse.emitir`)
350
-
351
- | Propriedade | Tipo | Obrigatoriedade | Padrão | Regras & Descrição |
352
- | :--- | :---: | :---: | :---: | :--- |
353
- | `prestador.cnpj` | `string` | **Obrigatório** | - | CNPJ da empresa prestadora (14 dígitos). |
354
- | `prestador.inscricao_municipal` | `string` | **Obrigatório** | - | Inscrição Municipal do prestador. |
355
- | `prestador.razao_social` | `string` | **Obrigatório** | - | Razão Social do prestador emitente. |
356
- | `tomador.cpf_cnpj` | `string` | **Obrigatório** | - | CPF (11) ou CNPJ (14) do cliente tomador. |
357
- | `tomador.razao_social` | `string` | **Obrigatório** | - | Nome completo ou Razão Social do tomador. |
358
- | `servico.item_lista_servico` | `string` | **Obrigatório** | - | Subitem da LC 116/2003 (ex: `"1.07"`). |
359
- | `servico.discriminacao` | `string` | **Obrigatório** | - | Descrição detalhada do serviço. |
360
- | `servico.municipio_prestacao_ibge`| `string`| **Obrigatório** | - | Código IBGE do local do serviço (7 dígitos). |
361
- | `servico.valor_servicos` | `number` | **Obrigatório** | - | Valor bruto cobrado pelo serviço (R$). |
362
- | `servico.aliquota_iss` | `number` | Opcional | `2.0` | Alíquota de ISS de 0.0% a 5.0%. |
363
- | `servico.iss_retido` | `boolean`| Opcional | `false` | Se o ISS deve ser retido pelo tomador. |
364
- | `modo` | `string` | Opcional | `'direto'` | `'direto'` (pass-through) ou `'assistido'` (IA). |
365
- | `ambiente` | `string` | Opcional | `'producao'` | `'producao'` ou `'homologacao'`. |
366
-
367
- ### 📌 Manifestação do Destinatário (`client.dfe.manifestar`)
368
-
369
- | Propriedade | Tipo | Obrigatoriedade | Padrão | Regras & Descrição |
370
- | :--- | :---: | :---: | :---: | :--- |
371
- | `chave_acesso` | `string` | **Obrigatório** | - | Chave de acesso de 44 dígitos da NF-e emitida pelo fornecedor. |
372
- | `cnpj` | `string` | **Obrigatório** | - | CNPJ da sua empresa compradora/destinatária. |
373
- | `tipo_evento` | `string` | **Obrigatório** | - | `'210210'` (Ciência), `'210200'` (Confirmação), `'210220'` (Desconhecimento) ou `'210240'` (Não Realizada). |
374
- | `justificativa`| `string` | Condicional | - | Obrigatória estritamente para `'210240'` (mínimo de 15 caracteres). |
375
- | `ambiente` | `string` | Opcional | `'producao'` | `'producao'` ou `'homologacao'`. |
376
-
377
- ---
378
-
379
- ## 🛡️ Tratamento de Erros e Exceções
380
-
381
- ```typescript
382
- import {
383
- PairusAPIError,
384
- AuthenticationError,
385
- RateLimitError,
386
- NetworkError,
387
- } from '@pairus/product-data';
388
-
389
- try {
390
- await client.emissao.emitirNFe(...);
391
- } catch (err: any) {
392
- if (err instanceof AuthenticationError) {
393
- console.error('Chave de API inválida');
394
- } else if (err instanceof RateLimitError) {
395
- console.error(`Rate limit atingido. Aguarde ${err.retryAfter}s`);
396
- } else if (err instanceof PairusAPIError) {
397
- console.error(`Erro Fiscal [${err.cStat}]: ${err.xMotivo}`);
398
- } else if (err instanceof NetworkError) {
399
- console.error('Falha de rede após retentativas');
400
- }
401
- }
402
- ```
403
-
404
- ---
405
-
406
- ## 📄 Licença
407
-
1
+ # PAIRUS Product Data SDK para Node.js & TypeScript 🟢
2
+
3
+ [![npm version](https://img.shields.io/npm/v/@pairus/product-data.svg?style=flat-square)](https://www.npmjs.com/package/@pairus/product-data)
4
+ [![npm downloads](https://img.shields.io/npm/dm/@pairus/product-data.svg?style=flat-square)](https://www.npmjs.com/package/@pairus/product-data)
5
+ [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg?style=flat-square)](https://opensource.org/licenses/MIT)
6
+
7
+ 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`).
8
+
9
+ ---
10
+
11
+ ## ⚡ Quickstart em 3 Linhas
12
+
13
+ ```typescript
14
+ import { PairusProductData } from '@pairus/product-data';
15
+
16
+ const client = new PairusProductData({ apiKey: 'sua_chave_pairus' });
17
+ const produto = await client.products.get('7891000100103');
18
+ console.log(`${produto.xProd} | NCM: ${produto.ncm} | CEST: ${produto.cest}`);
19
+ ```
20
+
21
+ ---
22
+
23
+ ## 📦 Instalação
24
+
25
+ ```bash
26
+ npm install @pairus/product-data
27
+ # ou
28
+ yarn add @pairus/product-data
29
+ # ou
30
+ pnpm add @pairus/product-data
31
+ ```
32
+
33
+ ---
34
+
35
+ ## 🛠️ Inicialização e Configuração
36
+
37
+ Você pode passar a chave diretamente no construtor ou configurar a variável de ambiente `PAIRUS_API_KEY`:
38
+
39
+ ```typescript
40
+ // TypeScript / ES Modules (ESM)
41
+ import { PairusProductData } from '@pairus/product-data';
42
+ const client = new PairusProductData(); // lê PAIRUS_API_KEY do ambiente
43
+
44
+ // CommonJS (CJS)
45
+ const { PairusProductData } = require('@pairus/product-data');
46
+ const client = new PairusProductData({ apiKey: 'pk_live_...' });
47
+ ```
48
+
49
+ ---
50
+
51
+ ## 📚 Módulos e Casos de Uso Práticos
52
+
53
+ ### 1. 🔍 Catálogo GTIN & Produtos
54
+
55
+ #### A. Consulta Básica (V1)
56
+ ```typescript
57
+ const produto = await client.products.get('7891000100103');
58
+ console.log(produto.xProd, produto.marca, produto.ncm, produto.cest);
59
+ ```
60
+
61
+ #### B. Consulta Enriquecida por IA com SEO e Ficha Técnica (V2)
62
+ ```typescript
63
+ const enriched = await client.products.getEnriched('7891000100103');
64
+ console.log(enriched.descricao_completa);
65
+ console.log(enriched.ficha_tecnica); // Dimensões, volume, peso, etc.
66
+ console.log(enriched.palavras_chave); // Otimizadas para e-commerce
67
+ ```
68
+
69
+ #### C. Busca Semântica por Intenção (Linguagem Natural)
70
+ ```typescript
71
+ const resultado = await client.products.search('refrigerante zero açucar lata');
72
+ for (const item of resultado.produtos) {
73
+ console.log(`[Score: ${item.score}] ${item.gtin} - ${item.xProd}`);
74
+ }
75
+ ```
76
+
77
+ #### D. Leitura de Código de Barras por Imagem (OCR V2)
78
+ ```typescript
79
+ import * as fs from 'fs';
80
+
81
+ const imageBuffer = fs.readFileSync('foto_rotulo.jpg');
82
+ const produto = await client.products.scan(imageBuffer);
83
+ console.log(`Detectado GTIN: ${produto.gtin} - ${produto.xProd}`);
84
+ ```
85
+
86
+ ---
87
+
88
+ ### 2. ⚖️ Predição Fiscal & Reforma Tributária (IBS / CBS / IS)
89
+
90
+ Obtenha parâmetros fiscais completos e em total conformidade com a Reforma Tributária (LC 214/2025):
91
+
92
+ ```typescript
93
+ const predicao = await client.fiscal.predict({
94
+ xProd: 'Refrigerante Coca-Cola 350ml',
95
+ regimeTributario: 'simples_nacional', // 'simples_nacional', 'lucro_presumido' ou 'lucro_real'
96
+ ufOrigem: 'SP',
97
+ ufDestino: 'RJ',
98
+ finalidade: 'revenda', // 'revenda', 'consumo_final' ou 'industrializacao'
99
+ destinatarioContribuinte: true,
100
+ });
101
+
102
+ const trib = predicao.dados_tributarios!;
103
+ console.log(`CFOP: ${trib.cfop} | CST/CSOSN: ${trib.icms_cst_csosn}`);
104
+ console.log(`IBS Efetivo: ${trib.ibscbs.ibs_aliquota_efetiva}% | CBS: ${trib.ibscbs.cbs_aliquota_efetiva}%`);
105
+ ```
106
+
107
+ #### Saneamento Fiscal em Lote
108
+ ```typescript
109
+ const lote = await client.fiscal.sanitize([
110
+ { ncm: '22021000', descricao: 'Refrigerante Cola' },
111
+ { ncm: '22030000', descricao: 'Cerveja Pilsen' },
112
+ ]);
113
+
114
+ for (const item of lote.itens) {
115
+ console.log(`NCM: ${item.ncm} | CEST Sugerido: ${item.cest_sugerido}`);
116
+ }
117
+ ```
118
+
119
+ ---
120
+
121
+ ### 3. 🧾 Emissão de NF-e e NFC-e com Autocura SEFAZ
122
+
123
+ #### Forma 1: NF-e (Objeto Simples)
124
+ ```typescript
125
+ const nota = await client.emissao.emitirNFe({
126
+ cnpj_emitente: '11222333000181',
127
+ serie: 1,
128
+ natureza_operacao: 'Venda de Mercadorias',
129
+ destinatario: {
130
+ cpf_cnpj: '12345678000195',
131
+ razao_social: 'Cliente Exemplo LTDA',
132
+ uf: 'SP',
133
+ email: 'financeiro@cliente.com.br',
134
+ },
135
+ itens: [
136
+ {
137
+ descricao: 'Mouse Sem Fio USB',
138
+ ncm: '84716053',
139
+ quantidade: 2,
140
+ valor_unitario: 49.90,
141
+ cfop: '5102',
142
+ },
143
+ ],
144
+ });
145
+
146
+ if (nota.sucesso) {
147
+ console.log(`✅ NF-e Autorizada! Chave: ${nota.chave_acesso}`);
148
+ console.log(`📄 Protocolo SEFAZ: ${nota.protocolo}`);
149
+ } else {
150
+ console.log(`❌ ${nota.status_sefaz} [${nota.cStat}]: ${nota.xMotivo}`);
151
+ }
152
+ ```
153
+
154
+ #### Forma 2: NFC-e no PDV com troco e idempotência (reenvio seguro)
155
+ ```typescript
156
+ const nfce = await client.emissao.emitirNFCe(
157
+ {
158
+ cnpj_emitente: '11222333000181',
159
+ tipo_documento: 'NFCE',
160
+ itens: [{ descricao: 'Refrigerante 2L', ncm: '22021000', valor_unitario: 9.9, quantidade: 2 }],
161
+ pagamentos: [{ forma_pagamento: '01', valor: 50 }], // troco de R$ 30,20 gerado pela API
162
+ },
163
+ { idempotencyKey: 'pdv03-cupom-000123' }, // identificador único da venda no seu PDV
164
+ );
165
+ ```
166
+
167
+ Toda emissão envia o cabeçalho `Idempotency-Key`. Sem `idempotencyKey`, o SDK gera um UUID e o reutiliza nas
168
+ **retentativas automáticas** (timeout, queda de rede, 5xx): se a primeira tentativa já tiver emitido a nota, a API
169
+ devolve essa mesma nota (`repeticao_idempotente: true`, sem novo faturamento) em vez de emitir outra. Informe o
170
+ identificador da venda quando o PDV puder reenviá-la depois de reiniciar. A chave vale por 24 h e é liberada se a
171
+ nota for rejeitada, para você corrigir e reenviar.
172
+
173
+ #### Forma 3: Simulação Gratuita (Custo ZERO de créditos)
174
+ ```typescript
175
+ const simulacao = await client.emissao.simular({
176
+ cnpj_emitente: '11222333000181',
177
+ destinatario: { cpf_cnpj: '12345678000195', razao_social: 'Teste', uf: 'SP' },
178
+ itens: [{ descricao: 'Item Teste', valor_unitario: 100 }],
179
+ });
180
+ console.log('Simulação realizada:', simulacao.sucesso);
181
+ ```
182
+
183
+ ---
184
+
185
+ ### 4. 🏛️ Emissão de NFS-e (Serviços - Padrão Nacional SND / ABRASF)
186
+
187
+ ```typescript
188
+ const nfse = await client.nfse.emitir({
189
+ prestador: {
190
+ cnpj: '12345678000195',
191
+ inscricao_municipal: '123456',
192
+ razao_social: 'Minha Empresa Tech LTDA',
193
+ },
194
+ tomador: {
195
+ cpf_cnpj: '98765432000198',
196
+ razao_social: 'Cliente Tomador S.A.',
197
+ email: 'contas@tomador.com.br',
198
+ },
199
+ servico: {
200
+ item_lista_servico: '1.07', // Suporte técnico e TI (LC 116/2003)
201
+ discriminacao: 'Desenvolvimento e manutenção de software sob medida',
202
+ municipio_prestacao_ibge: '3550308', // São Paulo/SP
203
+ valor_servicos: 4500.0,
204
+ aliquota_iss: 2.0,
205
+ iss_retido: false,
206
+ retencoes_federais: {
207
+ pis_retido: true, aliquota_pis: 0.65, valor_pis: 29.25,
208
+ cofins_retido: true, aliquota_cofins: 3.0, valor_cofins: 135.0,
209
+ csll_retida: true, aliquota_csll: 1.0, valor_csll: 45.0,
210
+ irrf_retido: true, aliquota_irrf: 1.5, valor_irrf: 67.50,
211
+ },
212
+ },
213
+ });
214
+
215
+ if (nfse.sucesso) {
216
+ console.log(`✅ NFS-e Emitida! Número: ${nfse.numero_nfse}`);
217
+ console.log(`🔑 Chave Nacional: ${nfse.chave_acesso_nacional}`);
218
+ console.log(`💰 Valor Líquido: R$ ${nfse.valor_liquido.toFixed(2)}`);
219
+ console.log(`🖨️ DANFSE URL: ${nfse.link_visualizacao}`);
220
+ }
221
+ ```
222
+
223
+ ---
224
+
225
+ ### 5. 🔄 Ciclo de Vida e Eventos Fiscais
226
+
227
+ #### Cancelamento de NF-e
228
+ ```typescript
229
+ const cancelamento = await client.emissao.cancelar({
230
+ chave_acesso: '35260912345678000195550010000000451234567890',
231
+ justificativa: 'Cancelamento acordado formalmente entre as partes envolvidas',
232
+ });
233
+ console.log('Cancelamento registrado:', cancelamento.sucesso);
234
+ ```
235
+
236
+ #### Carta de Correção (CC-e)
237
+ ```typescript
238
+ const cce = await client.emissao.cartaCorrecao({
239
+ chave_acesso: '35260912345678000195550010000000451234567890',
240
+ correcao: 'Correção do endereço de entrega: Rua das Palmeiras, 456 - Bairro Central',
241
+ });
242
+ console.log('CC-e protocolada:', cce.sucesso);
243
+ ```
244
+
245
+ #### Inutilização de Faixa de Numeração Quebrada
246
+ ```typescript
247
+ const inut = await client.emissao.inutilizar({
248
+ cnpj_emitente: '12345678000195',
249
+ serie: 1,
250
+ numero_inicial: 100,
251
+ numero_final: 105,
252
+ justificativa: 'Quebra involuntária de numeração por oscilação de conectividade',
253
+ });
254
+ console.log('Inutilização homologada:', inut.sucesso);
255
+ ```
256
+
257
+ ### 6. 📥 DF-e Inbound & Captura SEFAZ Nacional (Gestão de Compras)
258
+
259
+ 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.
260
+
261
+ #### A. Sincronizar Documentos com a SEFAZ
262
+ ```typescript
263
+ const sync = await client.dfe.sincronizar({
264
+ cnpj: '12345678000195',
265
+ ambiente: 'producao',
266
+ });
267
+
268
+ console.log(`Status SEFAZ [${sync.cstat}]: ${sync.xmotivo}`);
269
+ console.log(`Novos documentos capturados: ${sync.novos_documentos}`);
270
+ console.log(`NSU Atualizado: ${sync.ult_nsu} -> ${sync.max_nsu}`);
271
+
272
+ for (const doc of sync.documentos) {
273
+ console.log(`NF-e ${doc.numero}/${doc.serie} - R$ ${doc.valor_total} (${doc.nome_emitente})`);
274
+ }
275
+ ```
276
+
277
+ #### B. Listar Compras Recebidas
278
+ ```typescript
279
+ const compras = await client.dfe.listarDocumentos({
280
+ cnpj: '12345678000195',
281
+ limite: 50,
282
+ });
283
+
284
+ for (const doc of compras.documentos) {
285
+ console.log(`Chave: ${doc.chave_acesso} | Manifestação: ${doc.manifestacao_status}`);
286
+ }
287
+ ```
288
+
289
+ #### C. Manifestação do Destinatário na SEFAZ
290
+ ```typescript
291
+ // 1. Ciência da Emissão (Libera o XML completo procNFe)
292
+ const ciencia = await client.dfe.manifestar({
293
+ chave_acesso: '35260912345678000195550010000000451234567890',
294
+ cnpj: '12345678000195',
295
+ tipo_evento: '210210',
296
+ });
297
+ console.log('Ciência homologada. Protocolo:', ciencia.protocolo);
298
+
299
+ // 2. Confirmação da Operação (Atesta recebimento da mercadoria)
300
+ await client.dfe.manifestar({
301
+ chave_acesso: '35260912345678000195550010000000451234567890',
302
+ cnpj: '12345678000195',
303
+ tipo_evento: '210200',
304
+ });
305
+
306
+ // 3. Operação Não Realizada (Exige justificativa mínima de 15 caracteres)
307
+ await client.dfe.manifestar({
308
+ chave_acesso: '35260912345678000195550010000000451234567890',
309
+ cnpj: '12345678000195',
310
+ tipo_evento: '210240',
311
+ justificativa: 'Mercadoria não entregue pelo transportador no prazo estipulado',
312
+ });
313
+ ```
314
+
315
+ #### D. Download de XML e DANFE (PDF)
316
+ ```typescript
317
+ import * as fs from 'fs/promises';
318
+
319
+ const chave = '35260912345678000195550010000000451234567890';
320
+
321
+ // Baixa o XML completo
322
+ const xmlString = await client.dfe.baixarXml(chave);
323
+ await fs.writeFile(`${chave}.xml`, xmlString, 'utf-8');
324
+
325
+ // Baixa o DANFE em PDF
326
+ const danfeBuffer = await client.dfe.baixarDanfe(chave);
327
+ await fs.writeFile(`DANFE_${chave}.pdf`, Buffer.from(danfeBuffer));
328
+ ```
329
+
330
+ ---
331
+
332
+ ### 7. 🔐 Webhooks Seguros (HMAC-SHA256)
333
+
334
+ ```typescript
335
+ import { Webhooks } from '@pairus/product-data';
336
+
337
+ // Em um handler Express, Fastify ou Next.js:
338
+ const payloadBruto = req.rawBody; // String ou Buffer recebido bruto
339
+ const signature = req.headers['x-pairus-signature'] as string;
340
+ const webhookSecret = process.env.PAIRUS_WEBHOOK_SECRET!;
341
+
342
+ try {
343
+ const evento = Webhooks.constructEvent(payloadBruto, signature, webhookSecret);
344
+ console.log(`Evento seguro recebido: ${evento.event} na data ${evento.timestamp}`);
345
+ } catch (err: any) {
346
+ console.error(`Assinatura forjada ou inválida! ${err.message}`);
347
+ }
348
+ ```
349
+
350
+ ---
351
+
352
+ ## 📋 Tabela de Parâmetros (Obrigatórios vs. Opcionais)
353
+
354
+ ### 📌 Emissão de NF-e / NFC-e (`client.emissao.emitirNFe`)
355
+
356
+ | Propriedade | Tipo | Obrigatoriedade | Padrão | Regras & Descrição |
357
+ | :--- | :---: | :---: | :---: | :--- |
358
+ | `cnpj_emitente` | `string` | **Obrigatório** | - | CNPJ da sua empresa emitente (com certificado A1 cadastrado). |
359
+ | `destinatario.cpf_cnpj` | `string` | **Obrigatório na NF-e** | - | CPF (11 dígitos) ou CNPJ (14 dígitos). Opcional na NFC-e. |
360
+ | `destinatario.razao_social` | `string` | Opcional | - | Razão Social ou Nome do destinatário. |
361
+ | `destinatario.uf` | `string` | Opcional | UF do emitente | Sigla da UF do destinatário (2 letras). |
362
+ | `itens` | `Array` | **Obrigatório** | - | Pelo menos 1 item na lista. |
363
+ | `itens[].descricao` | `string` | **Obrigatório** | - | Descrição clara do item na nota. |
364
+ | `itens[].valor_unitario` | `number` | **Obrigatório** | - | Preço unitário maior que 0. |
365
+ | `itens[].quantidade` | `number` | Opcional | `1.0` | Quantidade comercializada. |
366
+ | `itens[].ncm` | `string` | Opcional | Auto | NCM de 8 dígitos (enquadrado por IA se omitido). |
367
+ | `itens[].cfop` | `string` | Opcional | Auto | CFOP da operação. |
368
+ | `serie` | `number` | Opcional | `1` | Série da nota fiscal (1 a 999). |
369
+ | `numero` | `number` | Opcional | Automático | Número da nota; omitido, a API reserva o próximo de forma atômica. |
370
+ | `pagamentos` | `Array` | Opcional | PIX no total | Formas de pagamento; acima do total, a API gera o troco (`vTroco`). |
371
+ | `options.idempotencyKey` | `string` | Opcional | UUID gerado | Identificador da venda (8 a 128 caracteres); reenvio seguro sem duplicar a nota. |
372
+
373
+ ### 📌 Emissão de NFS-e (`client.nfse.emitir`)
374
+
375
+ | Propriedade | Tipo | Obrigatoriedade | Padrão | Regras & Descrição |
376
+ | :--- | :---: | :---: | :---: | :--- |
377
+ | `prestador.cnpj` | `string` | **Obrigatório** | - | CNPJ da empresa prestadora (14 dígitos). |
378
+ | `prestador.inscricao_municipal` | `string` | **Obrigatório** | - | Inscrição Municipal do prestador. |
379
+ | `prestador.razao_social` | `string` | **Obrigatório** | - | Razão Social do prestador emitente. |
380
+ | `tomador.cpf_cnpj` | `string` | **Obrigatório** | - | CPF (11) ou CNPJ (14) do cliente tomador. |
381
+ | `tomador.razao_social` | `string` | **Obrigatório** | - | Nome completo ou Razão Social do tomador. |
382
+ | `servico.item_lista_servico` | `string` | **Obrigatório** | - | Subitem da LC 116/2003 (ex: `"1.07"`). |
383
+ | `servico.discriminacao` | `string` | **Obrigatório** | - | Descrição detalhada do serviço. |
384
+ | `servico.municipio_prestacao_ibge`| `string`| **Obrigatório** | - | Código IBGE do local do serviço (7 dígitos). |
385
+ | `servico.valor_servicos` | `number` | **Obrigatório** | - | Valor bruto cobrado pelo serviço (R$). |
386
+ | `servico.aliquota_iss` | `number` | Opcional | `2.0` | Alíquota de ISS de 0.0% a 5.0%. |
387
+ | `servico.iss_retido` | `boolean`| Opcional | `false` | Se o ISS deve ser retido pelo tomador. |
388
+ | `modo` | `string` | Opcional | `'direto'` | `'direto'` (pass-through) ou `'assistido'` (IA). |
389
+ | `ambiente` | `string` | Opcional | `'producao'` | `'producao'` ou `'homologacao'`. |
390
+
391
+ ### 📌 Manifestação do Destinatário (`client.dfe.manifestar`)
392
+
393
+ | Propriedade | Tipo | Obrigatoriedade | Padrão | Regras & Descrição |
394
+ | :--- | :---: | :---: | :---: | :--- |
395
+ | `chave_acesso` | `string` | **Obrigatório** | - | Chave de acesso de 44 dígitos da NF-e emitida pelo fornecedor. |
396
+ | `cnpj` | `string` | **Obrigatório** | - | CNPJ da sua empresa compradora/destinatária. |
397
+ | `tipo_evento` | `string` | **Obrigatório** | - | `'210210'` (Ciência), `'210200'` (Confirmação), `'210220'` (Desconhecimento) ou `'210240'` (Não Realizada). |
398
+ | `justificativa`| `string` | Condicional | - | Obrigatória estritamente para `'210240'` (mínimo de 15 caracteres). |
399
+ | `ambiente` | `string` | Opcional | `'producao'` | `'producao'` ou `'homologacao'`. |
400
+
401
+ ---
402
+
403
+ ## 🛡️ Tratamento de Erros e Exceções
404
+
405
+ ```typescript
406
+ import {
407
+ PairusAPIError,
408
+ AuthenticationError,
409
+ RateLimitError,
410
+ NetworkError,
411
+ } from '@pairus/product-data';
412
+
413
+ try {
414
+ await client.emissao.emitirNFe(...);
415
+ } catch (err: any) {
416
+ if (err instanceof AuthenticationError) {
417
+ console.error('Chave de API inválida');
418
+ } else if (err instanceof RateLimitError) {
419
+ console.error(`Rate limit atingido. Aguarde ${err.retryAfter}s`);
420
+ } else if (err instanceof PairusAPIError) {
421
+ console.error(`Erro Fiscal [${err.cStat}]: ${err.xMotivo}`);
422
+ } else if (err instanceof NetworkError) {
423
+ console.error('Falha de rede após retentativas');
424
+ }
425
+ }
426
+ ```
427
+
428
+ ---
429
+
430
+ ## 📄 Licença
431
+
408
432
  Distribuído sob a licença **MIT**. Consulte o arquivo [LICENSE](LICENSE) para obter mais informações.