pairus-product-data 1.0.0__tar.gz

pairus_product_data-1.0.0/.gitignore

@@ -0,0 +1,59 @@
+# Ambiente virtual
+venv/
+.venv/
+env/
+# Credenciais e segredos
+.env
+firebase-key.json
+
+# Prompts de IA (contém lógica de negócio proprietária)
+docs/prompts/
+
+# Certificados
+*.pfx
+*.p12
+*.pem
+*.key
+*.crt
+cert_base64.txt
+
+# Logs
+logs/
+*.log
+
+# Cache Python e Build
+__pycache__/
+*.py[cod]
+*$py.class
+.pytest_cache/
+*.egg-info/
+build/
+dist/
+node_modules/
+
+# Arquivos de IDE
+.idea/
+.vscode/
+*.swp
+*.swo
+
+# Arquivos temporários
+*.tmp
+*.bak
+
+# Firebase
+.firebase/
+*.zip
+
+# Scratch temporário
+scratch/
+
+# Especificação estática OpenAPI pesada (~190KB)
+openapi.json
+
+# Downloads temporários do Sentinel
+data/downloads/
+
+# Relatórios e dumps pesados (> 50KB)
+*.pdf
+git_*.txt

pairus_product_data-1.0.0/PKG-INFO

@@ -0,0 +1,104 @@
+Metadata-Version: 2.5
+Name: pairus-product-data
+Version: 1.0.0
+Summary: SDK oficial da PAIRUS para consulta de dados de produto (GTIN/EAN), catálogo e predição fiscal da Reforma Tributária (IBS/CBS/IS).
+Project-URL: Homepage, https://pairus.com.br
+Project-URL: Documentation, https://pairus.com.br/docs
+Project-URL: Repository, https://github.com/marcos2r/api-consulta-gtin
+Author-email: PAIRUS Soluções Tecnológicas <suporte@pairus.com.br>
+License: MIT
+Keywords: cbs,ean,fiscal,gtin,ibs,imposto-seletivo,nfe,pairus,reforma-tributaria,sefaz,tributacao
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: httpx>=0.25.0
+Requires-Dist: pydantic>=2.0.0
+Provides-Extra: dev
+Requires-Dist: mypy>=1.10.0; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.23.0; extra == 'dev'
+Requires-Dist: pytest>=8.0.0; extra == 'dev'
+Requires-Dist: ruff>=0.4.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# PAIRUS Product Data SDK para Python (`pairus-product-data`)
+
+SDK oficial da **PAIRUS Soluções Tecnológicas** para consulta de dados de catálogo (GTIN/EAN) e predição fiscal completa da **Reforma Tributária (IBS, CBS e Imposto Seletivo)**.
+
+[![PyPI](https://img.shields.io/pypi/v/pairus-product-data.svg)](https://pypi.org/project/pairus-product-data/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+---
+
+## 📦 Instalação
+
+```bash
+pip install pairus-product-data
+```
+
+---
+
+## 🚀 Início Rápido
+
+### 1. Consulta de Produto por Código de Barras (GTIN)
+
+```python
+from pairus_product_data import PairusProductData
+
+# Inicializa o cliente (lê automaticamente a variável de ambiente PAIRUS_API_KEY se omitido)
+client = PairusProductData(api_key="pk_live_sua_chave_aqui")
+
+produto = client.products.get("7891000744703")
+print(f"Produto: {produto.xProd}")
+print(f"NCM: {produto.ncm} | CEST: {produto.cest}")
+```
+
+### 2. Predição Fiscal da Reforma Tributária (IBS/CBS/IS)
+
+```python
+from pairus_product_data import PairusProductData
+
+client = PairusProductData()
+
+predicao = client.fiscal.predict(
+    xProd="Refrigerante Coca-Cola Lata 350ml",
+    gtin="7894900010015",
+    regime_tributario="simples_nacional",
+    uf_origem="SP",
+    uf_destino="RJ",
+    finalidade="revenda"
+)
+
+tributos = predicao.dados_tributarios
+print(f"NCM: {tributos.ncm_sugerido} | CFOP: {tributos.cfop}")
+print(f"CST IBS/CBS: {tributos.ibscbs.cst} | Classificação: {tributos.ibscbs.cClassTrib}")
+print(f"Alíquota Efetiva CBS: {tributos.ibscbs.cbs_aliquota_efetiva}%")
+print(f"Alíquota Efetiva IBS: {tributos.ibscbs.ibs_aliquota_efetiva}%")
+print(f"Alíquota Unificada: {tributos.aliquota_efetiva_unificada}%")
+```
+
+### 3. Validação de Webhooks com Assinatura Criptográfica (HMAC-SHA256)
+
+```python
+from pairus_product_data.webhooks import Webhooks
+
+# Em um endpoint FastAPI / Flask / Django:
+raw_body = request.body
+signature_header = request.headers.get("X-Pairus-Signature")
+webhook_secret = "whsec_seu_secret"
+
+evento = Webhooks.construct_event(raw_body, signature_header, webhook_secret)
+print(f"Evento autêntico recebido: {evento.event} para o GTIN: {evento.data.get('gtin')}")
+```
+
+---
+
+## 🛡️ Licença
+Distribuído sob a licença MIT. Consulte `LICENSE` para mais detalhes.

pairus_product_data-1.0.0/README.md

@@ -0,0 +1,74 @@
+# PAIRUS Product Data SDK para Python (`pairus-product-data`)
+
+SDK oficial da **PAIRUS Soluções Tecnológicas** para consulta de dados de catálogo (GTIN/EAN) e predição fiscal completa da **Reforma Tributária (IBS, CBS e Imposto Seletivo)**.
+
+[![PyPI](https://img.shields.io/pypi/v/pairus-product-data.svg)](https://pypi.org/project/pairus-product-data/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+---
+
+## 📦 Instalação
+
+```bash
+pip install pairus-product-data
+```
+
+---
+
+## 🚀 Início Rápido
+
+### 1. Consulta de Produto por Código de Barras (GTIN)
+
+```python
+from pairus_product_data import PairusProductData
+
+# Inicializa o cliente (lê automaticamente a variável de ambiente PAIRUS_API_KEY se omitido)
+client = PairusProductData(api_key="pk_live_sua_chave_aqui")
+
+produto = client.products.get("7891000744703")
+print(f"Produto: {produto.xProd}")
+print(f"NCM: {produto.ncm} | CEST: {produto.cest}")
+```
+
+### 2. Predição Fiscal da Reforma Tributária (IBS/CBS/IS)
+
+```python
+from pairus_product_data import PairusProductData
+
+client = PairusProductData()
+
+predicao = client.fiscal.predict(
+    xProd="Refrigerante Coca-Cola Lata 350ml",
+    gtin="7894900010015",
+    regime_tributario="simples_nacional",
+    uf_origem="SP",
+    uf_destino="RJ",
+    finalidade="revenda"
+)
+
+tributos = predicao.dados_tributarios
+print(f"NCM: {tributos.ncm_sugerido} | CFOP: {tributos.cfop}")
+print(f"CST IBS/CBS: {tributos.ibscbs.cst} | Classificação: {tributos.ibscbs.cClassTrib}")
+print(f"Alíquota Efetiva CBS: {tributos.ibscbs.cbs_aliquota_efetiva}%")
+print(f"Alíquota Efetiva IBS: {tributos.ibscbs.ibs_aliquota_efetiva}%")
+print(f"Alíquota Unificada: {tributos.aliquota_efetiva_unificada}%")
+```
+
+### 3. Validação de Webhooks com Assinatura Criptográfica (HMAC-SHA256)
+
+```python
+from pairus_product_data.webhooks import Webhooks
+
+# Em um endpoint FastAPI / Flask / Django:
+raw_body = request.body
+signature_header = request.headers.get("X-Pairus-Signature")
+webhook_secret = "whsec_seu_secret"
+
+evento = Webhooks.construct_event(raw_body, signature_header, webhook_secret)
+print(f"Evento autêntico recebido: {evento.event} para o GTIN: {evento.data.get('gtin')}")
+```
+
+---
+
+## 🛡️ Licença
+Distribuído sob a licença MIT. Consulte `LICENSE` para mais detalhes.

pairus_product_data-1.0.0/pairus_product_data/__init__.py

@@ -0,0 +1,27 @@
+"""PAIRUS Product Data - SDK Oficial para Python."""
+
+from pairus_product_data.client import PairusProductData, AsyncPairusProductData
+from pairus_product_data.config import ClientConfig
+from pairus_product_data.exceptions import (
+    AuthenticationError,
+    InvalidSignatureError,
+    NetworkError,
+    PairusAPIError,
+    PairusError,
+    RateLimitError,
+)
+from pairus_product_data.webhooks import Webhooks
+
+__version__ = "1.0.0"
+__all__ = [
+    "PairusProductData",
+    "AsyncPairusProductData",
+    "ClientConfig",
+    "Webhooks",
+    "PairusError",
+    "PairusAPIError",
+    "AuthenticationError",
+    "RateLimitError",
+    "InvalidSignatureError",
+    "NetworkError",
+]

pairus_product_data-1.0.0/pairus_product_data/client.py

@@ -0,0 +1,77 @@
+"""Cliente oficial PAIRUS Product Data."""
+
+from typing import Any
+import httpx
+
+from pairus_product_data.config import ClientConfig
+from pairus_product_data.resources.fiscal import FiscalResource, AsyncFiscalResource
+from pairus_product_data.resources.products import ProductsResource, AsyncProductsResource
+from pairus_product_data.webhooks import Webhooks
+
+
+class PairusProductData:
+    """Cliente oficial síncrono para o ecossistema PAIRUS Product Data."""
+
+    webhooks = Webhooks
+
+    def __init__(
+        self,
+        api_key: str | None = None,
+        base_url: str | None = None,
+        timeout: float | None = None,
+        max_retries: int | None = None,
+        client: httpx.Client | None = None,
+    ) -> None:
+        self.config = ClientConfig.from_env(
+            api_key=api_key,
+            base_url=base_url,
+            timeout=timeout,
+            max_retries=max_retries,
+        )
+        self._http_client = client or httpx.Client()
+        self.products = ProductsResource(self.config, self._http_client)
+        self.fiscal = FiscalResource(self.config, self._http_client)
+
+    def __enter__(self) -> "PairusProductData":
+        return self
+
+    def __exit__(self, exc_type: Any, exc_val: Any, exc_tb: Any) -> None:
+        self._http_client.close()
+
+    def close(self) -> None:
+        """Encerra a sessão HTTP."""
+        self._http_client.close()
+
+
+class AsyncPairusProductData:
+    """Cliente oficial assíncrono para o ecossistema PAIRUS Product Data."""
+
+    webhooks = Webhooks
+
+    def __init__(
+        self,
+        api_key: str | None = None,
+        base_url: str | None = None,
+        timeout: float | None = None,
+        max_retries: int | None = None,
+        client: httpx.AsyncClient | None = None,
+    ) -> None:
+        self.config = ClientConfig.from_env(
+            api_key=api_key,
+            base_url=base_url,
+            timeout=timeout,
+            max_retries=max_retries,
+        )
+        self._http_client = client or httpx.AsyncClient()
+        self.products = AsyncProductsResource(self.config, self._http_client)
+        self.fiscal = AsyncFiscalResource(self.config, self._http_client)
+
+    async def __aenter__(self) -> "AsyncPairusProductData":
+        return self
+
+    async def __aexit__(self, exc_type: Any, exc_val: Any, exc_tb: Any) -> None:
+        await self._http_client.aclose()
+
+    async def close(self) -> None:
+        """Encerra a sessão HTTP assíncrona."""
+        await self._http_client.aclose()

pairus_product_data-1.0.0/pairus_product_data/config.py

@@ -0,0 +1,43 @@
+"""Configurações e opções do cliente PAIRUS."""
+
+import os
+from dataclasses import dataclass
+
+DEFAULT_BASE_URL = "https://api.pairus.com.br"
+DEFAULT_TIMEOUT_SECONDS = 15.0
+DEFAULT_MAX_RETRIES = 3
+
+
+@dataclass
+class ClientConfig:
+    """Configurações de inicialização do cliente PAIRUS Product Data."""
+
+    api_key: str
+    base_url: str = DEFAULT_BASE_URL
+    timeout: float = DEFAULT_TIMEOUT_SECONDS
+    max_retries: int = DEFAULT_MAX_RETRIES
+
+    @classmethod
+    def from_env(
+        cls,
+        api_key: str | None = None,
+        base_url: str | None = None,
+        timeout: float | None = None,
+        max_retries: int | None = None,
+    ) -> "ClientConfig":
+        resolved_key = api_key or os.getenv("PAIRUS_API_KEY")
+        if not resolved_key:
+            raise ValueError(
+                "A chave de API da PAIRUS é obrigatória. Passe 'api_key' ou defina a variável 'PAIRUS_API_KEY'."
+            )
+
+        resolved_url = (base_url or os.getenv("PAIRUS_BASE_URL") or DEFAULT_BASE_URL).rstrip("/")
+        resolved_timeout = timeout if timeout is not None else float(os.getenv("PAIRUS_TIMEOUT", DEFAULT_TIMEOUT_SECONDS))
+        resolved_retries = max_retries if max_retries is not None else int(os.getenv("PAIRUS_MAX_RETRIES", DEFAULT_MAX_RETRIES))
+
+        return cls(
+            api_key=resolved_key,
+            base_url=resolved_url,
+            timeout=resolved_timeout,
+            max_retries=resolved_retries,
+        )

pairus_product_data-1.0.0/pairus_product_data/exceptions.py

@@ -0,0 +1,70 @@
+"""Exceções oficiais do SDK PAIRUS Product Data."""
+
+from typing import Any
+
+
+class PairusError(Exception):
+    """Exceção base para todos os erros do SDK PAIRUS."""
+
+    def __init__(self, message: str) -> None:
+        super().__init__(message)
+        self.message = message
+
+
+class PairusAPIError(PairusError):
+    """Exceção levantada quando a API retorna um erro HTTP (4xx ou 5xx).
+
+    Mapeia os campos padronizados do layout SEFAZ/NF-e (cStat e xMotivo).
+    """
+
+    def __init__(
+        self,
+        status_code: int,
+        cStat: str | None = None,
+        xMotivo: str | None = None,
+        detail: str | None = None,
+        raw_response: dict[str, Any] | None = None,
+    ) -> None:
+        self.status_code = status_code
+        self.cStat = cStat or str(status_code)
+        self.xMotivo = xMotivo or detail or f"Erro HTTP {status_code}"
+        self.detail = detail
+        self.raw_response = raw_response or {}
+
+        mensagem = f"[{self.cStat}] {self.xMotivo}"
+        super().__init__(mensagem)
+
+
+class AuthenticationError(PairusAPIError):
+    """Erro de autenticação (HTTP 401 - Chave de API inválida ou ausente)."""
+    pass
+
+
+class RateLimitError(PairusAPIError):
+    """Erro de limite de taxa excedido (HTTP 429)."""
+
+    def __init__(
+        self,
+        status_code: int = 429,
+        retry_after: float | None = None,
+        cStat: str | None = None,
+        xMotivo: str | None = None,
+        raw_response: dict[str, Any] | None = None,
+    ) -> None:
+        self.retry_after = retry_after
+        super().__init__(
+            status_code=status_code,
+            cStat=cStat or "429",
+            xMotivo=xMotivo or "Limite de requisições excedido. Tente novamente mais tarde.",
+            raw_response=raw_response,
+        )
+
+
+class InvalidSignatureError(PairusError):
+    """Erro levantado quando a assinatura criptográfica HMAC de um webhook é inválida."""
+    pass
+
+
+class NetworkError(PairusError):
+    """Erro de conexão ou timeout após esgotadas as tentativas automáticas."""
+    pass

pairus_product_data-1.0.0/pairus_product_data/models/__init__.py

@@ -0,0 +1,29 @@
+"""Modelos de dados tipados para a API PAIRUS Product Data."""
+
+from pairus_product_data.models.fiscal import (
+    FuelData,
+    IBSCBSData,
+    SelectiveTaxData,
+    TaxPredictionData,
+    TaxPredictionInput,
+    TaxPredictionItemInput,
+    TaxPredictionItemResult,
+    TaxPredictionResponse,
+)
+from pairus_product_data.models.product import ProductDetails, ProductResponse
+from pairus_product_data.models.webhook import WebhookEvent, WebhookPayload
+
+__all__ = [
+    "FuelData",
+    "IBSCBSData",
+    "SelectiveTaxData",
+    "TaxPredictionData",
+    "TaxPredictionInput",
+    "TaxPredictionItemInput",
+    "TaxPredictionItemResult",
+    "TaxPredictionResponse",
+    "ProductDetails",
+    "ProductResponse",
+    "WebhookEvent",
+    "WebhookPayload",
+]

pairus_product_data-1.0.0/pairus_product_data/models/fiscal.py

@@ -0,0 +1,102 @@
+"""Modelos de dados para predição tributária e Reforma Tributária."""
+
+from pydantic import BaseModel, Field
+
+
+class IBSCBSData(BaseModel):
+    """Dados tributários referentes ao IBS e CBS (Reforma Tributária)."""
+    cst: str = Field(..., description="Código de Situação Tributária (CST) com 3 dígitos (ex: '000').")
+    cClassTrib: str = Field(..., description="Código de Classificação Tributária com 6 dígitos (ex: '000001').")
+    cbs_aliquota: float = Field(default=8.8, description="Alíquota nominal da CBS federal (%).")
+    cbs_diferimento: float = Field(default=0.0, description="Percentual de diferimento da CBS (%).")
+    cbs_reducao_aliquota: float = Field(default=0.0, description="Percentual de redução da alíquota da CBS (%).")
+    cbs_aliquota_efetiva: float = Field(default=8.8, description="Alíquota efetiva da CBS (%).")
+    ibs_aliquota_estadual: float = Field(default=10.0, description="Alíquota do IBS estadual da UF de destino (%).")
+    ibs_aliquota_municipal: float = Field(default=7.7, description="Alíquota do IBS municipal de destino (%).")
+    ibs_diferimento: float = Field(default=0.0, description="Percentual de diferimento do IBS (%).")
+    ibs_reducao_aliquota: float = Field(default=0.0, description="Percentual de redução da alíquota do IBS (%).")
+    ibs_aliquota_efetiva: float = Field(default=17.7, description="Alíquota efetiva total do IBS (%).")
+
+
+class SelectiveTaxData(BaseModel):
+    """Dados tributários referentes ao Imposto Seletivo (IS)."""
+    cst: str = Field(default="001", description="CST do Imposto Seletivo com 3 dígitos.")
+    cClassTribIS: str = Field(default="000101", description="Classificação Tributária do IS com 6 dígitos.")
+    aliquota: float = Field(default=0.0, description="Alíquota do Imposto Seletivo (%).")
+
+
+class FuelData(BaseModel):
+    """Dados específicos de combustíveis exigidos pela ANP para o XML da NF-e."""
+    codigo_anp: str = Field(..., description="Código do produto de 9 dígitos gerado pela ANP.")
+    descricao_anp: str = Field(..., description="Descrição oficial do produto na ANP.")
+    perc_glp: float = Field(default=0.0, description="Percentual de GLP (%).")
+    perc_gas_nacional: float = Field(default=0.0, description="Percentual de Gás Natural Nacional (%).")
+    perc_gas_importado: float = Field(default=0.0, description="Percentual de Gás Natural Importado (%).")
+    valor_por_kg: float = Field(default=0.0, description="Valor de partida por KG.")
+
+
+class TaxPredictionData(BaseModel):
+    """Estrutura consolidada de impostos e parâmetros fiscais sugeridos para NF-e."""
+    ncm_sugerido: str = Field(..., description="Código NCM sugerido (8 dígitos numéricos).")
+    cest_sugerido: str | None = Field(default=None, description="Código CEST sugerido (7 dígitos numéricos).")
+    cfop: str = Field(..., description="Código Fiscal de Operações e Prestações (CFOP de 4 dígitos).")
+    cfop_devolucao: str | None = Field(default=None, description="CFOP correspondente de devolução.")
+    icms_cst_csosn: str = Field(..., description="CST ou CSOSN do ICMS.")
+    icms_aliquota: float = Field(default=0.0, description="Alíquota própria de ICMS da operação (%).")
+    icms_aliquota_st: float = Field(default=0.0, description="Alíquota de ICMS ST (%).")
+    icms_mva_st: float = Field(default=0.0, description="Margem de Valor Agregado (MVA ST %).")
+    icms_reducao_bc: float = Field(default=0.0, description="Percentual de redução da base de cálculo do ICMS (%).")
+    icms_reducao_bc_st: float = Field(default=0.0, description="Percentual de redução da base de cálculo do ICMS ST (%).")
+    icms_modalidade_bc: str = Field(default="3", description="Modalidade de determinação da BC do ICMS.")
+    icms_modalidade_bc_st: str = Field(default="4", description="Modalidade de determinação da BC do ICMS ST.")
+    pis_cst: str = Field(..., description="CST do PIS.")
+    pis_aliquota: float = Field(default=0.0, description="Alíquota do PIS (%).")
+    cofins_cst: str = Field(..., description="CST da COFINS.")
+    cofins_aliquota: float = Field(default=0.0, description="Alíquota da COFINS (%).")
+    ipi_cst: str | None = Field(default=None, description="CST do IPI.")
+    ipi_aliquota: float = Field(default=0.0, description="Alíquota do IPI (%).")
+    ibscbs: IBSCBSData = Field(..., description="Detalhamento do IBS e CBS da Reforma Tributária.")
+    imposto_seletivo: SelectiveTaxData | None = Field(default=None, description="Detalhamento do Imposto Seletivo.")
+    dados_combustivel: FuelData | None = Field(default=None, description="Dados ANP para combustíveis.")
+    beneficio_fiscal: str | None = Field(default=None, description="Código de benefício fiscal estadual (cBenef).")
+    aliquota_efetiva_unificada: float = Field(..., description="Soma das alíquotas efetivas de CBS e IBS (%).")
+    motor_ia: str = Field(default="pairus_fiscal_engine", description="Motor de inteligência artificial utilizado.")
+    avisos: list[str] = Field(default_factory=list, description="Avisos e orientações fiscais.")
+
+
+class TaxPredictionItemInput(BaseModel):
+    """Representação de um item para predição em lote."""
+    xProd: str | None = None
+    gtin: str | None = None
+    ncm: str | None = None
+    cest: str | None = None
+
+
+class TaxPredictionInput(BaseModel):
+    """Parâmetros de entrada para o endpoint de predição fiscal."""
+    regime_tributario: str = Field(..., description="Regime tributário ('simples_nacional', 'lucro_presumido', 'lucro_real').")
+    uf_origem: str = Field(..., description="UF de origem da mercadoria (sigla com 2 caracteres).")
+    uf_destino: str | None = Field(default=None, description="UF de destino (sigla com 2 caracteres).")
+    finalidade: str = Field(default="revenda", description="Finalidade da operação ('revenda', 'consumo_final', 'industrializacao').")
+    destinatario_contribuinte: bool = Field(default=True, description="Se o destinatário é contribuinte do ICMS.")
+    xProd: str | None = None
+    gtin: str | None = None
+    ncm: str | None = None
+    cest: str | None = None
+    itens: list[TaxPredictionItemInput] | None = None
+
+
+class TaxPredictionItemResult(BaseModel):
+    """Resultado individual de um item predito no modo lote."""
+    item_index: int
+    xProd: str | None = None
+    dados_tributarios: TaxPredictionData
+
+
+class TaxPredictionResponse(BaseModel):
+    """Resposta oficial da rota de predição fiscal /v2/fiscal/predict."""
+    status: str
+    provider: str
+    xProd: str | None = None
+    dados_tributarios: TaxPredictionData | None = None
+    resultados: list[TaxPredictionItemResult] | None = None

pairus_product_data-1.0.0/pairus_product_data/models/product.py

@@ -0,0 +1,29 @@
+"""Modelos de dados para produtos e catálogo GTIN."""
+
+from typing import Any
+from pydantic import BaseModel, Field
+
+
+class ProductDetails(BaseModel):
+    """Detalhes completos de um produto catalogado na base PAIRUS."""
+    gtin: str = Field(..., description="Código de barras GTIN/EAN numérico.")
+    xProd: str = Field(..., description="Nome comercial / descrição do produto.")
+    ncm: str | None = Field(default=None, description="Código NCM de 8 dígitos.")
+    cest: str | None = Field(default=None, description="Código CEST de 7 dígitos.")
+    marca: str | None = Field(default=None, description="Marca comercial do produto.")
+    fabricante: str | None = Field(default=None, description="Razão social ou nome do fabricante.")
+    categoria: str | None = Field(default=None, description="Categoria do produto.")
+    imagem_url: str | None = Field(default=None, description="URL da imagem oficial do produto.")
+    peso_bruto: float | None = Field(default=None, description="Peso bruto em gramas ou kg.")
+    peso_liquido: float | None = Field(default=None, description="Peso líquido.")
+    quantidade_embalagem: int | None = Field(default=1, description="Quantidade de itens na embalagem.")
+    data_cadastro: str | None = None
+    data_atualizacao: str | None = None
+
+
+class ProductResponse(BaseModel):
+    """Resposta de consulta de produto por GTIN."""
+    status: str
+    provider: str
+    produto: ProductDetails | None = None
+    raw_data: dict[str, Any] | None = None

pairus_product_data-1.0.0/pairus_product_data/models/webhook.py

@@ -0,0 +1,19 @@
+"""Modelos de dados para Webhooks da PAIRUS."""
+
+from typing import Any
+from pydantic import BaseModel, Field
+
+
+class WebhookPayload(BaseModel):
+    """Payload base enviado nos eventos de Webhook da PAIRUS."""
+    event: str = Field(..., description="Nome do evento (ex: 'pairus.fiscal.update').")
+    timestamp: str = Field(..., description="Data/hora do evento no fuso horário do Brasil (ISO 8601).")
+    data: dict[str, Any] = Field(..., description="Dados específicos do evento.")
+
+
+class WebhookEvent(BaseModel):
+    """Representação estruturada de um evento de webhook verificado."""
+    id: str | None = None
+    event: str
+    timestamp: str
+    data: dict[str, Any]

pairus_product_data-1.0.0/pairus_product_data/resources/__init__.py

@@ -0,0 +1,11 @@
+"""Namespaces de recursos da API PAIRUS Product Data."""
+
+from pairus_product_data.resources.fiscal import FiscalResource, AsyncFiscalResource
+from pairus_product_data.resources.products import ProductsResource, AsyncProductsResource
+
+__all__ = [
+    "FiscalResource",
+    "AsyncFiscalResource",
+    "ProductsResource",
+    "AsyncProductsResource",
+]

pairus_product_data-1.0.0/pairus_product_data/resources/base.py

@@ -0,0 +1,194 @@
+"""Classe base para execução de requisições HTTP com retry exponencial."""
+
+import asyncio
+import random
+import time
+from typing import Any
+
+import httpx
+
+from pairus_product_data.config import ClientConfig
+from pairus_product_data.exceptions import (
+    AuthenticationError,
+    NetworkError,
+    PairusAPIError,
+    RateLimitError,
+)
+
+
+class BaseResource:
+    """Classe base síncrona com lógica de retentativas automáticas e tratamento de erros cStat/xMotivo."""
+
+    def __init__(self, config: ClientConfig, client: httpx.Client) -> None:
+        self.config = config
+        self.client = client
+
+    def _request(
+        self,
+        method: str,
+        path: str,
+        params: dict[str, Any] | None = None,
+        json_data: dict[str, Any] | None = None,
+        headers: dict[str, str] | None = None,
+    ) -> dict[str, Any]:
+        url = f"{self.config.base_url}/{path.lstrip('/')}"
+        req_headers = {
+            "Accept": "application/json",
+            "X-API-Key": self.config.api_key,
+            "User-Agent": "Pairus-Python-SDK/1.0.0",
+        }
+        if headers:
+            req_headers.update(headers)
+
+        last_exception: Exception | None = None
+
+        for attempt in range(self.config.max_retries):
+            try:
+                response = self.client.request(
+                    method=method,
+                    url=url,
+                    params=params,
+                    json=json_data,
+                    headers=req_headers,
+                    timeout=self.config.timeout,
+                )
+
+                if response.status_code == 200:
+                    return response.json()
+
+                if response.status_code == 401:
+                    data = response.json() if "application/json" in response.headers.get("content-type", "") else {}
+                    raise AuthenticationError(
+                        status_code=401,
+                        cStat=data.get("cStat", "401"),
+                        xMotivo=data.get("xMotivo", "Chave de API inválida ou não autorizada."),
+                        raw_response=data,
+                    )
+
+                if response.status_code == 429:
+                    retry_after_str = response.headers.get("Retry-After")
+                    retry_after = float(retry_after_str) if retry_after_str else 2.0
+                    if attempt < self.config.max_retries - 1:
+                        time.sleep(retry_after + random.uniform(0.1, 0.5))
+                        continue
+                    data = response.json() if "application/json" in response.headers.get("content-type", "") else {}
+                    raise RateLimitError(
+                        status_code=429,
+                        retry_after=retry_after,
+                        cStat=data.get("cStat", "429"),
+                        xMotivo=data.get("xMotivo", "Limite de requisições excedido."),
+                        raw_response=data,
+                    )
+
+                # Erros transitórios de servidor (502, 503, 504) -> aplicar retry
+                if response.status_code in (502, 503, 504) and attempt < self.config.max_retries - 1:
+                    sleep_time = (2 ** attempt) + random.uniform(0.1, 0.5)
+                    time.sleep(sleep_time)
+                    continue
+
+                # Erros estruturados 4xx ou 5xx
+                data = response.json() if "application/json" in response.headers.get("content-type", "") else {}
+                raise PairusAPIError(
+                    status_code=response.status_code,
+                    cStat=data.get("cStat", str(response.status_code)),
+                    xMotivo=data.get("xMotivo") or data.get("detail") or f"Erro na requisição: {response.text[:200]}",
+                    raw_response=data,
+                )
+
+            except (httpx.ConnectError, httpx.TimeoutException) as exc:
+                last_exception = exc
+                if attempt < self.config.max_retries - 1:
+                    sleep_time = (2 ** attempt) + random.uniform(0.1, 0.5)
+                    time.sleep(sleep_time)
+                    continue
+                break
+
+        raise NetworkError(f"Falha de conexão com a API PAIRUS após {self.config.max_retries} tentativas: {last_exception}")
+
+
+class AsyncBaseResource:
+    """Classe base assíncrona com lógica de retentativas automáticas."""
+
+    def __init__(self, config: ClientConfig, client: httpx.AsyncClient) -> None:
+        self.config = config
+        self.client = client
+
+    async def _request(
+        self,
+        method: str,
+        path: str,
+        params: dict[str, Any] | None = None,
+        json_data: dict[str, Any] | None = None,
+        headers: dict[str, str] | None = None,
+    ) -> dict[str, Any]:
+        url = f"{self.config.base_url}/{path.lstrip('/')}"
+        req_headers = {
+            "Accept": "application/json",
+            "X-API-Key": self.config.api_key,
+            "User-Agent": "Pairus-Python-SDK/1.0.0",
+        }
+        if headers:
+            req_headers.update(headers)
+
+        last_exception: Exception | None = None
+
+        for attempt in range(self.config.max_retries):
+            try:
+                response = await self.client.request(
+                    method=method,
+                    url=url,
+                    params=params,
+                    json=json_data,
+                    headers=req_headers,
+                    timeout=self.config.timeout,
+                )
+
+                if response.status_code == 200:
+                    return response.json()
+
+                if response.status_code == 401:
+                    data = response.json() if "application/json" in response.headers.get("content-type", "") else {}
+                    raise AuthenticationError(
+                        status_code=401,
+                        cStat=data.get("cStat", "401"),
+                        xMotivo=data.get("xMotivo", "Chave de API inválida ou não autorizada."),
+                        raw_response=data,
+                    )
+
+                if response.status_code == 429:
+                    retry_after_str = response.headers.get("Retry-After")
+                    retry_after = float(retry_after_str) if retry_after_str else 2.0
+                    if attempt < self.config.max_retries - 1:
+                        await asyncio.sleep(retry_after + random.uniform(0.1, 0.5))
+                        continue
+                    data = response.json() if "application/json" in response.headers.get("content-type", "") else {}
+                    raise RateLimitError(
+                        status_code=429,
+                        retry_after=retry_after,
+                        cStat=data.get("cStat", "429"),
+                        xMotivo=data.get("xMotivo", "Limite de requisições excedido."),
+                        raw_response=data,
+                    )
+
+                if response.status_code in (502, 503, 504) and attempt < self.config.max_retries - 1:
+                    sleep_time = (2 ** attempt) + random.uniform(0.1, 0.5)
+                    await asyncio.sleep(sleep_time)
+                    continue
+
+                data = response.json() if "application/json" in response.headers.get("content-type", "") else {}
+                raise PairusAPIError(
+                    status_code=response.status_code,
+                    cStat=data.get("cStat", str(response.status_code)),
+                    xMotivo=data.get("xMotivo") or data.get("detail") or f"Erro na requisição: {response.text[:200]}",
+                    raw_response=data,
+                )
+
+            except (httpx.ConnectError, httpx.TimeoutException) as exc:
+                last_exception = exc
+                if attempt < self.config.max_retries - 1:
+                    sleep_time = (2 ** attempt) + random.uniform(0.1, 0.5)
+                    await asyncio.sleep(sleep_time)
+                    continue
+                break
+
+        raise NetworkError(f"Falha de conexão assíncrona com a API PAIRUS após {self.config.max_retries} tentativas: {last_exception}")

pairus_product_data-1.0.0/pairus_product_data/resources/fiscal.py

@@ -0,0 +1,102 @@
+"""Recurso de predição fiscal e Reforma Tributária."""
+
+from typing import Any
+from pairus_product_data.models.fiscal import (
+    TaxPredictionItemInput,
+    TaxPredictionResponse,
+)
+from pairus_product_data.resources.base import BaseResource, AsyncBaseResource
+
+
+class FiscalResource(BaseResource):
+    """Namespace fiscal (Síncrono)."""
+
+    def predict(
+        self,
+        regime_tributario: str,
+        uf_origem: str,
+        uf_destino: str | None = None,
+        finalidade: str = "revenda",
+        destinatario_contribuinte: bool = True,
+        xProd: str | None = None,
+        gtin: str | None = None,
+        ncm: str | None = None,
+        cest: str | None = None,
+        itens: list[dict[str, Any] | TaxPredictionItemInput] | None = None,
+    ) -> TaxPredictionResponse:
+        """Executa a predição fiscal completa (IBS, CBS, IS, ICMS, IPI, PIS, COFINS e regras anti-rejeição).
+
+        Args:
+            regime_tributario: 'simples_nacional', 'lucro_presumido' ou 'lucro_real'.
+            uf_origem: UF emissora (sigla de 2 letras).
+            uf_destino: UF destinatária (sigla de 2 letras).
+            finalidade: 'revenda', 'consumo_final' ou 'industrializacao'.
+            destinatario_contribuinte: Se o cliente é contribuinte do ICMS.
+            xProd: Descrição do produto (modo individual).
+            gtin: Código de barras (modo individual).
+            ncm: Código NCM (modo individual).
+            cest: Código CEST (modo individual).
+            itens: Lista de itens para cálculo em lote da Nota Fiscal.
+
+        Returns:
+            TaxPredictionResponse: Estrutura tributária completa e validada.
+        """
+        payload: dict[str, Any] = {
+            "regime_tributario": regime_tributario,
+            "uf_origem": uf_origem,
+            "uf_destino": uf_destino or uf_origem,
+            "finalidade": finalidade,
+            "destinatario_contribuinte": destinatario_contribuinte,
+        }
+        if xProd:
+            payload["xProd"] = xProd
+        if gtin:
+            payload["gtin"] = gtin
+        if ncm:
+            payload["ncm"] = ncm
+        if cest:
+            payload["cest"] = cest
+        if itens:
+            payload["itens"] = [i.model_dump() if hasattr(i, "model_dump") else i for i in itens]
+
+        data = self._request("POST", "/v2/fiscal/predict", json_data=payload)
+        return TaxPredictionResponse(**data)
+
+
+class AsyncFiscalResource(AsyncBaseResource):
+    """Namespace fiscal (Assíncrono)."""
+
+    async def predict(
+        self,
+        regime_tributario: str,
+        uf_origem: str,
+        uf_destino: str | None = None,
+        finalidade: str = "revenda",
+        destinatario_contribuinte: bool = True,
+        xProd: str | None = None,
+        gtin: str | None = None,
+        ncm: str | None = None,
+        cest: str | None = None,
+        itens: list[dict[str, Any] | TaxPredictionItemInput] | None = None,
+    ) -> TaxPredictionResponse:
+        """Executa a predição fiscal assíncrona completa."""
+        payload: dict[str, Any] = {
+            "regime_tributario": regime_tributario,
+            "uf_origem": uf_origem,
+            "uf_destino": uf_destino or uf_origem,
+            "finalidade": finalidade,
+            "destinatario_contribuinte": destinatario_contribuinte,
+        }
+        if xProd:
+            payload["xProd"] = xProd
+        if gtin:
+            payload["gtin"] = gtin
+        if ncm:
+            payload["ncm"] = ncm
+        if cest:
+            payload["cest"] = cest
+        if itens:
+            payload["itens"] = [i.model_dump() if hasattr(i, "model_dump") else i for i in itens]
+
+        data = await self._request("POST", "/v2/fiscal/predict", json_data=payload)
+        return TaxPredictionResponse(**data)

pairus_product_data-1.0.0/pairus_product_data/resources/products.py

@@ -0,0 +1,66 @@
+"""Recurso de consulta de produtos e catálogo GTIN."""
+
+from pairus_product_data.models.product import ProductDetails
+from pairus_product_data.resources.base import BaseResource, AsyncBaseResource
+
+
+class ProductsResource(BaseResource):
+    """Namespace de produtos (Síncrono)."""
+
+    def get(self, gtin: str) -> ProductDetails:
+        """Consulta um produto por código de barras GTIN/EAN.
+
+        Args:
+            gtin: Código GTIN numérico (8, 12, 13 ou 14 dígitos).
+
+        Returns:
+            ProductDetails: Detalhes completos do produto catalogado.
+        """
+        gtin_limpo = "".join(filter(str.isdigit, str(gtin)))
+        data = self._request("GET", f"/api/produtos/{gtin_limpo}")
+        
+        prod_dict = data.get("produto") or data
+        return ProductDetails(
+            gtin=prod_dict.get("GTIN") or prod_dict.get("gtin") or gtin_limpo,
+            xProd=prod_dict.get("xProd") or prod_dict.get("descricao") or "Descrição Indisponível",
+            ncm=prod_dict.get("NCM") or prod_dict.get("ncm"),
+            cest=prod_dict.get("CEST") or prod_dict.get("cest"),
+            marca=prod_dict.get("marca"),
+            fabricante=prod_dict.get("fabricante"),
+            categoria=prod_dict.get("categoria"),
+            imagem_url=prod_dict.get("imagem_url") or prod_dict.get("thumbnail"),
+            peso_bruto=float(prod_dict.get("peso_bruto") or 0.0) if prod_dict.get("peso_bruto") else None,
+            peso_liquido=float(prod_dict.get("peso_liquido") or 0.0) if prod_dict.get("peso_liquido") else None,
+            quantidade_embalagem=int(prod_dict.get("quantidade_embalagem") or 1),
+        )
+
+
+class AsyncProductsResource(AsyncBaseResource):
+    """Namespace de produtos (Assíncrono)."""
+
+    async def get(self, gtin: str) -> ProductDetails:
+        """Consulta um produto por código de barras GTIN/EAN de forma assíncrona.
+
+        Args:
+            gtin: Código GTIN numérico (8, 12, 13 ou 14 dígitos).
+
+        Returns:
+            ProductDetails: Detalhes completos do produto catalogado.
+        """
+        gtin_limpo = "".join(filter(str.isdigit, str(gtin)))
+        data = await self._request("GET", f"/api/produtos/{gtin_limpo}")
+        
+        prod_dict = data.get("produto") or data
+        return ProductDetails(
+            gtin=prod_dict.get("GTIN") or prod_dict.get("gtin") or gtin_limpo,
+            xProd=prod_dict.get("xProd") or prod_dict.get("descricao") or "Descrição Indisponível",
+            ncm=prod_dict.get("NCM") or prod_dict.get("ncm"),
+            cest=prod_dict.get("CEST") or prod_dict.get("cest"),
+            marca=prod_dict.get("marca"),
+            fabricante=prod_dict.get("fabricante"),
+            categoria=prod_dict.get("categoria"),
+            imagem_url=prod_dict.get("imagem_url") or prod_dict.get("thumbnail"),
+            peso_bruto=float(prod_dict.get("peso_bruto") or 0.0) if prod_dict.get("peso_bruto") else None,
+            peso_liquido=float(prod_dict.get("peso_liquido") or 0.0) if prod_dict.get("peso_liquido") else None,
+            quantidade_embalagem=int(prod_dict.get("quantidade_embalagem") or 1),
+        )

pairus_product_data-1.0.0/pairus_product_data/webhooks.py

@@ -0,0 +1,75 @@
+"""Helper oficial para validação criptográfica de Webhooks HMAC-SHA256."""
+
+import hashlib
+import hmac
+import json
+from typing import Any
+
+from pairus_product_data.exceptions import InvalidSignatureError
+from pairus_product_data.models.webhook import WebhookPayload
+
+
+class Webhooks:
+    """Helper estático para validação de assinaturas de Webhooks da PAIRUS."""
+
+    @staticmethod
+    def compute_signature(payload_bytes: bytes, secret: str) -> str:
+        """Calcula a assinatura HMAC-SHA256 esperada para o payload informado."""
+        return hmac.new(
+            key=secret.encode("utf-8"),
+            msg=payload_bytes,
+            digestmod=hashlib.sha256,
+        ).hexdigest()
+
+    @classmethod
+    def verify_signature(
+        cls,
+        payload: bytes | str | dict[str, Any],
+        signature: str | None,
+        secret: str,
+    ) -> bool:
+        """Verifica de forma segura (resistente a timing attacks) a assinatura de um webhook.
+
+        Args:
+            payload: Corpo bruto da requisição (bytes ou string) ou dicionário já decodificado.
+            signature: Valor do cabeçalho 'X-Pairus-Signature'.
+            secret: Segredo do webhook (webhook_secret) configurado no painel PAIRUS.
+
+        Returns:
+            bool: True se a assinatura for válida e autêntica, False caso contrário.
+        """
+        if not signature or not secret:
+            return False
+
+        if isinstance(payload, bytes):
+            payload_bytes = payload
+        elif isinstance(payload, str):
+            payload_bytes = payload.encode("utf-8")
+        elif isinstance(payload, dict):
+            payload_bytes = json.dumps(payload, sort_keys=True).encode("utf-8")
+        else:
+            return False
+
+        expected_signature = cls.compute_signature(payload_bytes, secret)
+        # Comparação constante no tempo contra timing attacks
+        return hmac.compare_digest(expected_signature, signature.strip())
+
+    @classmethod
+    def construct_event(
+        cls,
+        payload: bytes | str,
+        signature: str | None,
+        secret: str,
+    ) -> WebhookPayload:
+        """Verifica a assinatura e converte o payload bruto em um modelo WebhookPayload tipado.
+
+        Raises:
+            InvalidSignatureError: Se a assinatura criptográfica for inválida.
+            ValueError: Se o payload JSON estiver corrompido.
+        """
+        if not cls.verify_signature(payload, signature, secret):
+            raise InvalidSignatureError("A assinatura do webhook ('X-Pairus-Signature') é inválida ou expirada.")
+
+        raw_str = payload.decode("utf-8") if isinstance(payload, bytes) else payload
+        data = json.loads(raw_str)
+        return WebhookPayload(**data)

pairus_product_data-1.0.0/pyproject.toml

@@ -0,0 +1,68 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "pairus-product-data"
+version = "1.0.0"
+description = "SDK oficial da PAIRUS para consulta de dados de produto (GTIN/EAN), catálogo e predição fiscal da Reforma Tributária (IBS/CBS/IS)."
+readme = "README.md"
+requires-python = ">=3.10"
+license = { text = "MIT" }
+authors = [
+    { name = "PAIRUS Soluções Tecnológicas", email = "suporte@pairus.com.br" }
+]
+keywords = [
+    "pairus",
+    "gtin",
+    "ean",
+    "fiscal",
+    "tributacao",
+    "reforma-tributaria",
+    "ibs",
+    "cbs",
+    "imposto-seletivo",
+    "nfe",
+    "sefaz"
+]
+classifiers = [
+    "Development Status :: 5 - Production/Stable",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+    "Typing :: Typed",
+]
+dependencies = [
+    "httpx>=0.25.0",
+    "pydantic>=2.0.0"
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8.0.0",
+    "pytest-asyncio>=0.23.0",
+    "ruff>=0.4.0",
+    "mypy>=1.10.0"
+]
+
+[project.urls]
+Homepage = "https://pairus.com.br"
+Documentation = "https://pairus.com.br/docs"
+Repository = "https://github.com/marcos2r/api-consulta-gtin"
+
+[tool.hatch.build.targets.wheel]
+packages = ["pairus_product_data"]
+
+[tool.ruff]
+line-length = 120
+target-version = "py310"
+
+[tool.mypy]
+python_version = "3.10"
+strict = true
+plugins = ["pydantic.mypy"]

pairus_product_data-1.0.0/tests/test_client.py

@@ -0,0 +1,29 @@
+from unittest.mock import MagicMock
+import pytest
+from pairus_product_data import PairusProductData, AuthenticationError
+
+def test_client_init_env(monkeypatch):
+    monkeypatch.setenv("PAIRUS_API_KEY", "pk_test_12345")
+    client = PairusProductData()
+    assert client.config.api_key == "pk_test_12345"
+
+def test_client_init_explicit():
+    client = PairusProductData(api_key="pk_explicit_abc", timeout=10.0)
+    assert client.config.api_key == "pk_explicit_abc"
+    assert client.config.timeout == 10.0
+
+def test_client_auth_error():
+    mock_http = MagicMock()
+    mock_resp = MagicMock()
+    mock_resp.status_code = 401
+    mock_resp.headers = {"content-type": "application/json"}
+    mock_resp.json.return_value = {"cStat": "401", "xMotivo": "Chave inválida"}
+    mock_http.request.return_value = mock_resp
+
+    client = PairusProductData(api_key="invalid_key", client=mock_http)
+    with pytest.raises(AuthenticationError) as exc_info:
+        client.products.get("7891000744703")
+
+    assert exc_info.value.status_code == 401
+    assert exc_info.value.cStat == "401"
+    assert "Chave inválida" in str(exc_info.value)

pairus_product_data-1.0.0/tests/test_fiscal.py

@@ -0,0 +1,62 @@
+from unittest.mock import MagicMock
+from pairus_product_data import PairusProductData
+
+def test_fiscal_predict_individual():
+    mock_http = MagicMock()
+    mock_resp = MagicMock()
+    mock_resp.status_code = 200
+    mock_resp.json.return_value = {
+        "status": "success",
+        "provider": "PAIRUS Soluções Tecnológicas",
+        "xProd": "Refrigerante Coca-Cola 350ml",
+        "dados_tributarios": {
+            "ncm_sugerido": "22021000",
+            "cest_sugerido": "1701100",
+            "cfop": "5102",
+            "cfop_devolucao": "1202",
+            "icms_cst_csosn": "102",
+            "icms_aliquota": 0.0,
+            "icms_aliquota_st": 18.0,
+            "icms_mva_st": 40.0,
+            "icms_reducao_bc": 0.0,
+            "icms_reducao_bc_st": 0.0,
+            "icms_modalidade_bc": "3",
+            "icms_modalidade_bc_st": "4",
+            "pis_cst": "01",
+            "pis_aliquota": 1.65,
+            "cofins_cst": "01",
+            "cofins_aliquota": 7.6,
+            "ibscbs": {
+                "cst": "000",
+                "cClassTrib": "000001",
+                "cbs_aliquota": 8.8,
+                "cbs_diferimento": 0.0,
+                "cbs_reducao_aliquota": 0.0,
+                "cbs_aliquota_efetiva": 8.8,
+                "ibs_aliquota_estadual": 10.0,
+                "ibs_aliquota_municipal": 7.7,
+                "ibs_diferimento": 0.0,
+                "ibs_reducao_aliquota": 0.0,
+                "ibs_aliquota_efetiva": 17.7
+            },
+            "aliquota_efetiva_unificada": 26.5,
+            "motor_ia": "pairus_ai_rag_v3",
+            "avisos": []
+        }
+    }
+    mock_http.request.return_value = mock_resp
+
+    client = PairusProductData(api_key="pk_test_123", client=mock_http)
+    res = client.fiscal.predict(
+        xProd="Refrigerante Coca-Cola 350ml",
+        regime_tributario="simples_nacional",
+        uf_origem="SP",
+        uf_destino="RJ"
+    )
+
+    assert res.status == "success"
+    assert res.dados_tributarios is not None
+    assert res.dados_tributarios.ncm_sugerido == "22021000"
+    assert res.dados_tributarios.ibscbs.cst == "000"
+    assert res.dados_tributarios.ibscbs.cbs_aliquota_efetiva == 8.8
+    assert res.dados_tributarios.aliquota_efetiva_unificada == 26.5

pairus_product_data-1.0.0/tests/test_products.py

@@ -0,0 +1,28 @@
+from unittest.mock import MagicMock
+from pairus_product_data import PairusProductData
+
+def test_products_get_success():
+    mock_http = MagicMock()
+    mock_resp = MagicMock()
+    mock_resp.status_code = 200
+    mock_resp.json.return_value = {
+        "status": "success",
+        "provider": "PAIRUS Soluções Tecnológicas",
+        "produto": {
+            "GTIN": "7891000744703",
+            "xProd": "Cerveja Skol Lata 269ml",
+            "NCM": "22030000",
+            "CEST": "0300100",
+            "marca": "Skol"
+        }
+    }
+    mock_http.request.return_value = mock_resp
+
+    client = PairusProductData(api_key="pk_test_123", client=mock_http)
+    prod = client.products.get("7891000744703")
+
+    assert prod.gtin == "7891000744703"
+    assert prod.xProd == "Cerveja Skol Lata 269ml"
+    assert prod.ncm == "22030000"
+    assert prod.cest == "0300100"
+    assert prod.marca == "Skol"

pairus_product_data-1.0.0/tests/test_webhooks.py

@@ -0,0 +1,23 @@
+from pairus_product_data.webhooks import Webhooks
+from pairus_product_data.exceptions import InvalidSignatureError
+import pytest
+
+def test_webhook_signature_verification():
+    payload = b'{"data":{"gtin":"7891000744703"},"event":"pairus.fiscal.update","timestamp":"2026-08-29T19:00:00"}'
+    secret = "whsec_test_secret_12345678"
+
+    signature = Webhooks.compute_signature(payload, secret)
+    assert Webhooks.verify_signature(payload, signature, secret) is True
+    assert Webhooks.verify_signature(payload, "invalid_signature", secret) is False
+
+def test_webhook_construct_event():
+    payload = b'{"data":{"gtin":"7891000744703"},"event":"pairus.fiscal.update","timestamp":"2026-08-29T19:00:00"}'
+    secret = "whsec_test_secret_12345678"
+    signature = Webhooks.compute_signature(payload, secret)
+
+    event = Webhooks.construct_event(payload, signature, secret)
+    assert event.event == "pairus.fiscal.update"
+    assert event.data["gtin"] == "7891000744703"
+
+    with pytest.raises(InvalidSignatureError):
+        Webhooks.construct_event(payload, "invalid_signature", secret)