kodebar 0.1.0__py3-none-any.whl

kodebar/__init__.py

@@ -0,0 +1,245 @@
+"""
+Kodebar SDK — consulta de produtos por código de barras (GTIN/EAN)
+https://kodebar.korvensistemas.com.br
+"""
+
+import re
+import time
+import requests
+
+__version__ = "0.1.0"
+
+DEFAULT_BASE_URL = "https://kodebar.korvensistemas.com.br"
+GTIN_RE = re.compile(r"^\d{8,14}$")
+
+
+class KodebarError(Exception):
+    """Erro genérico da API Kodebar."""
+    def __init__(self, message, status=None, code=None):
+        super().__init__(message)
+        self.status = status
+        self.code = code
+
+
+class KodebarNotFoundError(KodebarError):
+    """Produto não encontrado (404)."""
+    def __init__(self, gtin):
+        super().__init__(f"Produto não encontrado: {gtin}", 404, "NOT_FOUND")
+        self.gtin = gtin
+
+
+class KodebarRateLimitError(KodebarError):
+    """Rate limit excedido (429)."""
+    def __init__(self, message="Rate limit excedido", retry_after=60):
+        super().__init__(message, 429, "RATE_LIMITED")
+        self.retry_after = retry_after
+
+
+class Kodebar:
+    """
+    Cliente da API Kodebar.
+
+    Args:
+        api_key: Sua API key do Kodebar.
+        base_url: URL base da API (default: https://kodebar.korvensistemas.com.br).
+        timeout: Timeout em segundos (default: 10).
+        max_retries: Retries em caso de 429/5xx (default: 2).
+    """
+
+    def __init__(self, api_key, *, base_url=None, timeout=10, max_retries=2):
+        if not api_key or not isinstance(api_key, str):
+            raise ValueError("API key é obrigatória")
+        self.api_key = api_key
+        self.base_url = (base_url or DEFAULT_BASE_URL).rstrip("/")
+        self.timeout = timeout
+        self.max_retries = max_retries
+        self._session = requests.Session()
+        self._session.headers.update({
+            "X-API-Key": self.api_key,
+            "User-Agent": f"kodebar-python/{__version__}",
+        })
+
+    def _request(self, method, path, *, params=None, json=None):
+        url = f"{self.base_url}{path}"
+        if params:
+            params = {k: v for k, v in params.items() if v is not None}
+
+        last_error = None
+        for attempt in range(self.max_retries + 1):
+            try:
+                resp = self._session.request(
+                    method, url,
+                    params=params, json=json,
+                    timeout=self.timeout,
+                )
+                try:
+                    data = resp.json()
+                except Exception:
+                    data = {}
+
+                if resp.ok:
+                    return data
+
+                if resp.status_code == 404:
+                    gtin = (params or {}).get("gtin", path)
+                    raise KodebarNotFoundError(gtin)
+
+                if resp.status_code == 429:
+                    retry_after = int(resp.headers.get("Retry-After", "60"))
+                    err = KodebarRateLimitError(
+                        data.get("erro", "Rate limit excedido"),
+                        retry_after,
+                    )
+                    if attempt < self.max_retries:
+                        time.sleep(min(retry_after, 5))
+                        continue
+                    raise err
+
+                if resp.status_code >= 500 and attempt < self.max_retries:
+                    time.sleep(1 * (attempt + 1))
+                    continue
+
+                raise KodebarError(
+                    data.get("erro", f"Erro HTTP {resp.status_code}"),
+                    resp.status_code,
+                )
+
+            except KodebarError:
+                raise
+            except Exception as e:
+                last_error = e
+                if attempt < self.max_retries:
+                    time.sleep(1 * (attempt + 1))
+                    continue
+
+        raise last_error or KodebarError("Falha na requisição")
+
+    @staticmethod
+    def _validate_gtin(gtin):
+        g = str(gtin).strip()
+        if not GTIN_RE.match(g):
+            raise ValueError(f'GTIN inválido: "{gtin}" (deve ter 8-14 dígitos)')
+        return g
+
+    # ── Endpoints públicos ──
+
+    def lookup(self, gtin):
+        """
+        Consulta um produto pelo GTIN/EAN.
+
+        Args:
+            gtin: Código de barras (8-14 dígitos).
+
+        Returns:
+            dict com gtin, nome, thumbnail, ncm, cached, source.
+
+        Raises:
+            KodebarNotFoundError: Produto não encontrado.
+        """
+        g = self._validate_gtin(gtin)
+        return self._request("GET", "/gtin/lookup", params={"gtin": g})
+
+    def search(self, query, *, limit=None, offset=None):
+        """
+        Busca produtos por nome.
+
+        Args:
+            query: Termo de busca.
+            limit: Máximo de resultados.
+            offset: Offset para paginação.
+
+        Returns:
+            dict com results, total, limit, offset.
+        """
+        if not query or not query.strip():
+            raise ValueError("Termo de busca é obrigatório")
+        return self._request("GET", "/gtin/search", params={
+            "q": query.strip(), "limit": limit, "offset": offset,
+        })
+
+    def autocomplete(self, query, *, limit=None):
+        """
+        Autocomplete rápido por nome.
+
+        Args:
+            query: Termo parcial.
+            limit: Máximo de resultados (max 10).
+
+        Returns:
+            dict com results.
+        """
+        if not query or not query.strip():
+            raise ValueError("Termo de busca é obrigatório")
+        return self._request("GET", "/gtin/autocomplete", params={
+            "q": query.strip(), "limit": limit,
+        })
+
+    def bulk(self, gtins):
+        """
+        Consulta em lote.
+
+        Args:
+            gtins: Lista de GTINs.
+
+        Returns:
+            dict com results, found, missed.
+        """
+        if not gtins or not isinstance(gtins, (list, tuple)):
+            raise ValueError("Lista de GTINs é obrigatória")
+        validated = [self._validate_gtin(g) for g in gtins]
+        return self._request("POST", "/gtin/bulk", json={"gtins": validated})
+
+    # ── Conta ──
+
+    def me(self):
+        """Info da sua conta (tier, uso, limite)."""
+        return self._request("GET", "/account/me")
+
+    def usage(self, days=30):
+        """
+        Histórico de uso diário.
+
+        Args:
+            days: Quantidade de dias (default: 30).
+        """
+        return self._request("GET", "/account/usage", params={"days": days})
+
+    def logs(self, limit=50):
+        """
+        Últimas consultas realizadas.
+
+        Args:
+            limit: Máximo de registros (default: 50).
+        """
+        return self._request("GET", "/account/logs", params={"limit": limit})
+
+    def resolved_misses(self, *, days=None, limit=None):
+        """GTINs que eram miss e agora estão encontrados."""
+        return self._request("GET", "/account/resolved-misses", params={
+            "days": days, "limit": limit,
+        })
+
+    # ── Webhooks ──
+
+    def list_webhooks(self):
+        """Lista webhooks registrados."""
+        return self._request("GET", "/webhooks")
+
+    def create_webhook(self, url, event=None):
+        """
+        Registra um webhook.
+
+        Args:
+            url: URL de callback.
+            event: Evento (gtin.updated, gtin.created, miss.resolved).
+        """
+        if not url:
+            raise ValueError("URL do webhook é obrigatória")
+        body = {"url": url}
+        if event:
+            body["event"] = event
+        return self._request("POST", "/webhooks/subscribe", json=body)
+
+    def delete_webhook(self, webhook_id):
+        """Remove um webhook."""
+        return self._request("DELETE", f"/webhooks/{webhook_id}")

kodebar-0.1.0.dist-info/METADATA

@@ -0,0 +1,103 @@
+Metadata-Version: 2.4
+Name: kodebar
+Version: 0.1.0
+Summary: SDK oficial da API Kodebar — consulta de produtos por código de barras (GTIN/EAN)
+Author-email: Kodebar <contato@korvensistemas.com.br>
+License: MIT
+Project-URL: Homepage, https://kodebar.korvensistemas.com.br
+Project-URL: Documentation, https://kodebar.korvensistemas.com.br/docs
+Project-URL: Repository, https://github.com/kodebar/kodebar-python
+Keywords: kodebar,gtin,ean,barcode,produto,api,brasil
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Software Development :: Libraries
+Requires-Python: >=3.7
+Description-Content-Type: text/markdown
+Requires-Dist: requests>=2.20
+
+# kodebar
+
+SDK oficial da [API Kodebar](https://kodebar.korvensistemas.com.br) — consulta de produtos brasileiros por código de barras (GTIN/EAN).
+
+## Instalação
+
+```bash
+pip install kodebar
+```
+
+## Uso rápido
+
+```python
+from kodebar import Kodebar
+
+kb = Kodebar("sua-api-key")
+
+# Consultar um produto
+produto = kb.lookup("7891234567890")
+print(produto["nome"])       # "Produto Exemplo 500ml"
+print(produto["thumbnail"])  # URL da imagem
+
+# Buscar por nome
+busca = kb.search("arroz integral")
+for p in busca["results"]:
+    print(p["gtin"], p["nome"])
+
+# Autocomplete
+sugestoes = kb.autocomplete("coca")
+
+# Consulta em lote
+lote = kb.bulk(["7891234567890", "7898765432100"])
+print(f'{lote["found"]} encontrados, {lote["missed"]} não encontrados')
+```
+
+## Configuração
+
+```python
+kb = Kodebar("sua-api-key",
+    timeout=15,       # timeout em segundos (default: 10)
+    max_retries=3,    # retries em 429/5xx (default: 2)
+)
+```
+
+## Métodos
+
+| Método | Descrição | Tier mínimo |
+|--------|-----------|-------------|
+| `lookup(gtin)` | Consulta por GTIN/EAN | Teste (grátis) |
+| `search(query, limit=, offset=)` | Busca por nome | Básico |
+| `autocomplete(query, limit=)` | Autocomplete rápido | Básico |
+| `bulk(gtins)` | Consulta em lote | Básico |
+| `me()` | Info da conta | Teste |
+| `usage(days=30)` | Histórico de uso | Teste |
+| `logs(limit=50)` | Últimas consultas | Teste |
+| `resolved_misses(days=, limit=)` | Misses resolvidos | Básico |
+| `list_webhooks()` | Lista webhooks | Básico |
+| `create_webhook(url, event=)` | Cria webhook | Básico |
+| `delete_webhook(id)` | Remove webhook | Básico |
+
+## Tratamento de erros
+
+```python
+from kodebar import Kodebar, KodebarNotFoundError, KodebarRateLimitError
+
+kb = Kodebar("sua-api-key")
+
+try:
+    produto = kb.lookup("0000000000000")
+except KodebarNotFoundError as e:
+    print(f"Produto não encontrado: {e.gtin}")
+except KodebarRateLimitError as e:
+    print(f"Rate limit! Tente novamente em {e.retry_after} segundos")
+except KodebarError as e:
+    print(f"Erro: {e} (status: {e.status})")
+```
+
+## Crie sua conta grátis
+
+[kodebar.korvensistemas.com.br/painel](https://kodebar.korvensistemas.com.br/painel)
+
+## Licença
+
+MIT

kodebar-0.1.0.dist-info/RECORD

@@ -0,0 +1,5 @@
+kodebar/__init__.py,sha256=owUJJDdFVtuUPfiG-DX0PnZFKj08jodqjL-1cdnn73E,7559
+kodebar-0.1.0.dist-info/METADATA,sha256=bV_5U0zqCJ5HLewg_f7kYv6mJJDFBK6Awl5wKE_gfjE,3110
+kodebar-0.1.0.dist-info/WHEEL,sha256=K260EYznzXsJYBQGqmI8VTxEdiZYNvDZwW9cBh9-_MA,91
+kodebar-0.1.0.dist-info/top_level.txt,sha256=m7JsV4Gt0swuIqtu01aswcemkKfwIfyplC0bXr4nWqE,8
+kodebar-0.1.0.dist-info/RECORD,,

kodebar-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (83.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

kodebar-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+kodebar