@pairus/product-data

v1.3.1

Published

5 days ago

SDK oficial da PAIRUS para integração com catálogo GTIN/EAN, predição fiscal (IBS/CBS/IS) e emissão de NF-e/NFC-e com Autocura SEFAZ.

0High
0Medium
0Low

pairus_st

pairus gtin ean fiscal reforma-tributaria ibs cbs imposto-seletivo nfe sefaz tributacao

PAIRUS Product Data SDK para Node.js & TypeScript 🟢

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

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

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 / 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)

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)

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)

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)

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):

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

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)

const nota = await client.emissao.emitirNFe({
  serie: 1,
  natureza_operacao: 'Venda de Mercadorias',
  destinatario: {
    documento: '12345678000195',
    razao_social: 'Cliente Exemplo LTDA',
    uf: 'SP',
    email: '[email protected]',
  },
  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)

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)

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: '[email protected]',
  },
  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

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)

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

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

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

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

// 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)

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)

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`)

📌 Emissão de NFS-e (`client.nfse.emitir`)

📌 Manifestação do Destinatário (`client.dfe.manifestar`)

🛡️ Tratamento de Erros e Exceções

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 para obter mais informações.