@pairus/product-data 1.0.0 → 1.2.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.
- package/README.md +325 -94
- package/dist/index.d.mts +354 -2
- package/dist/index.d.ts +354 -2
- package/dist/index.js +247 -6
- package/dist/index.js.map +1 -1
- package/dist/index.mjs +243 -6
- package/dist/index.mjs.map +1 -1
- package/package.json +2 -2
package/README.md
CHANGED
|
@@ -1,94 +1,325 @@
|
|
|
1
|
-
# PAIRUS Product Data SDK para Node.js & TypeScript
|
|
2
|
-
|
|
3
|
-
|
|
4
|
-
|
|
5
|
-
[](https://www.npmjs.com/package/@pairus/product-data)
|
|
4
|
+
[](https://www.npmjs.com/package/@pairus/product-data)
|
|
5
|
+
[](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
|
+
---
|
|
238
|
+
|
|
239
|
+
### 6. 🔐 Webhooks Seguros (HMAC-SHA256)
|
|
240
|
+
|
|
241
|
+
```typescript
|
|
242
|
+
import { Webhooks } from '@pairus/product-data';
|
|
243
|
+
|
|
244
|
+
// Em um handler Express, Fastify ou Next.js:
|
|
245
|
+
const payloadBruto = req.rawBody; // String ou Buffer recebido bruto
|
|
246
|
+
const signature = req.headers['x-pairus-signature'] as string;
|
|
247
|
+
const webhookSecret = process.env.PAIRUS_WEBHOOK_SECRET!;
|
|
248
|
+
|
|
249
|
+
try {
|
|
250
|
+
const evento = Webhooks.constructEvent(payloadBruto, signature, webhookSecret);
|
|
251
|
+
console.log(`Evento seguro recebido: ${evento.event} na data ${evento.timestamp}`);
|
|
252
|
+
} catch (err: any) {
|
|
253
|
+
console.error(`Assinatura forjada ou inválida! ${err.message}`);
|
|
254
|
+
}
|
|
255
|
+
```
|
|
256
|
+
|
|
257
|
+
---
|
|
258
|
+
|
|
259
|
+
## 📋 Tabela de Parâmetros (Obrigatórios vs. Opcionais)
|
|
260
|
+
|
|
261
|
+
### 📌 Emissão de NF-e / NFC-e (`client.emissao.emitirNFe`)
|
|
262
|
+
|
|
263
|
+
| Propriedade | Tipo | Obrigatoriedade | Padrão | Regras & Descrição |
|
|
264
|
+
| :--- | :---: | :---: | :---: | :--- |
|
|
265
|
+
| `destinatario.documento` | `string` | **Obrigatório** | - | CPF (11 dígitos) ou CNPJ (14 dígitos). |
|
|
266
|
+
| `destinatario.razao_social` | `string` | **Obrigatório** | - | Razão Social ou Nome do destinatário. |
|
|
267
|
+
| `destinatario.uf` | `string` | **Obrigatório** | - | Sigla da UF do destinatário (2 letras). |
|
|
268
|
+
| `itens` | `Array` | **Obrigatório** | - | Pelo menos 1 item na lista. |
|
|
269
|
+
| `itens[].descricao` | `string` | **Obrigatório** | - | Descrição clara do item na nota. |
|
|
270
|
+
| `itens[].valor_unitario` | `number` | **Obrigatório** | - | Preço unitário maior que 0. |
|
|
271
|
+
| `itens[].quantidade` | `number` | Opcional | `1.0` | Quantidade comercializada. |
|
|
272
|
+
| `itens[].ncm` | `string` | Opcional | Auto | NCM de 8 dígitos (enquadrado por IA se omitido). |
|
|
273
|
+
| `itens[].cfop` | `string` | Opcional | Auto | CFOP da operação. |
|
|
274
|
+
| `serie` | `number` | Opcional | `1` | Série da nota fiscal (1 a 999). |
|
|
275
|
+
|
|
276
|
+
### 📌 Emissão de NFS-e (`client.nfse.emitir`)
|
|
277
|
+
|
|
278
|
+
| Propriedade | Tipo | Obrigatoriedade | Padrão | Regras & Descrição |
|
|
279
|
+
| :--- | :---: | :---: | :---: | :--- |
|
|
280
|
+
| `prestador.cnpj` | `string` | **Obrigatório** | - | CNPJ da empresa prestadora (14 dígitos). |
|
|
281
|
+
| `prestador.inscricao_municipal` | `string` | **Obrigatório** | - | Inscrição Municipal do prestador. |
|
|
282
|
+
| `prestador.razao_social` | `string` | **Obrigatório** | - | Razão Social do prestador emitente. |
|
|
283
|
+
| `tomador.cpf_cnpj` | `string` | **Obrigatório** | - | CPF (11) ou CNPJ (14) do cliente tomador. |
|
|
284
|
+
| `tomador.razao_social` | `string` | **Obrigatório** | - | Nome completo ou Razão Social do tomador. |
|
|
285
|
+
| `servico.item_lista_servico` | `string` | **Obrigatório** | - | Subitem da LC 116/2003 (ex: `"1.07"`). |
|
|
286
|
+
| `servico.discriminacao` | `string` | **Obrigatório** | - | Descrição detalhada do serviço. |
|
|
287
|
+
| `servico.municipio_prestacao_ibge`| `string`| **Obrigatório** | - | Código IBGE do local do serviço (7 dígitos). |
|
|
288
|
+
| `servico.valor_servicos` | `number` | **Obrigatório** | - | Valor bruto cobrado pelo serviço (R$). |
|
|
289
|
+
| `servico.aliquota_iss` | `number` | Opcional | `2.0` | Alíquota de ISS de 0.0% a 5.0%. |
|
|
290
|
+
| `servico.iss_retido` | `boolean`| Opcional | `false` | Se o ISS deve ser retido pelo tomador. |
|
|
291
|
+
| `modo` | `string` | Opcional | `'direto'` | `'direto'` (pass-through) ou `'assistido'` (IA). |
|
|
292
|
+
| `ambiente` | `string` | Opcional | `'producao'` | `'producao'` ou `'homologacao'`. |
|
|
293
|
+
|
|
294
|
+
---
|
|
295
|
+
|
|
296
|
+
## 🛡️ Tratamento de Erros e Exceções
|
|
297
|
+
|
|
298
|
+
```typescript
|
|
299
|
+
import {
|
|
300
|
+
PairusAPIError,
|
|
301
|
+
AuthenticationError,
|
|
302
|
+
RateLimitError,
|
|
303
|
+
NetworkError,
|
|
304
|
+
} from '@pairus/product-data';
|
|
305
|
+
|
|
306
|
+
try {
|
|
307
|
+
await client.emissao.emitirNFe(...);
|
|
308
|
+
} catch (err: any) {
|
|
309
|
+
if (err instanceof AuthenticationError) {
|
|
310
|
+
console.error('Chave de API inválida');
|
|
311
|
+
} else if (err instanceof RateLimitError) {
|
|
312
|
+
console.error(`Rate limit atingido. Aguarde ${err.retryAfter}s`);
|
|
313
|
+
} else if (err instanceof PairusAPIError) {
|
|
314
|
+
console.error(`Erro Fiscal [${err.cStat}]: ${err.xMotivo}`);
|
|
315
|
+
} else if (err instanceof NetworkError) {
|
|
316
|
+
console.error('Falha de rede após retentativas');
|
|
317
|
+
}
|
|
318
|
+
}
|
|
319
|
+
```
|
|
320
|
+
|
|
321
|
+
---
|
|
322
|
+
|
|
323
|
+
## 📄 Licença
|
|
324
|
+
|
|
325
|
+
Distribuído sob a licença **MIT**. Consulte o arquivo [LICENSE](LICENSE) para obter mais informações.
|