vitrin 0.1.0__tar.gz

vitrin-0.1.0/.gitignore

@@ -0,0 +1,11 @@
+__pycache__/
+*.py[cod]
+*.egg-info/
+build/
+dist/
+.venv/
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+.coverage
+.DS_Store

vitrin-0.1.0/PKG-INFO

@@ -0,0 +1,184 @@
+Metadata-Version: 2.4
+Name: vitrin
+Version: 0.1.0
+Summary: SDK oficial Python para a API da Vitrin Digital
+Project-URL: Homepage, https://vitrin.digital
+Project-URL: Documentation, https://vitrin.digital/docs/integracao
+Project-URL: Repository, https://github.com/vitrindigital/vitrin
+Author: Vitrin Digital
+License-Expression: MIT
+Keywords: boleto,checkout,pagamentos,pix,vitrin,vitrin-digital
+Classifier: Development Status :: 4 - Beta
+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: Topic :: Office/Business :: Financial
+Requires-Python: >=3.10
+Requires-Dist: requests>=2.31
+Provides-Extra: dev
+Requires-Dist: mypy>=1.10; extra == 'dev'
+Requires-Dist: pytest-mock>=3.12; extra == 'dev'
+Requires-Dist: pytest>=8; extra == 'dev'
+Requires-Dist: responses>=0.25; extra == 'dev'
+Requires-Dist: ruff>=0.7; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# vitrin (Python)
+
+SDK oficial Python para a [API da Vitrin Digital](https://api.vitrin.digital).
+
+```bash
+pip install vitrin
+```
+
+> **Python 3.10+** requerido. Única dependência runtime: `requests`.
+
+## Setup
+
+```python
+import os
+from vitrin import Vitrin
+
+vitrin = Vitrin(
+    api_key=os.environ["VITRIN_API_KEY"],
+    # opcionais:
+    # base_url="https://api.vitrin.digital/api/v1",
+    # timeout=30.0,
+    # max_retries=3,
+)
+```
+
+Use `vd_test_*` em desenvolvimento, `vd_live_*` em produção.
+
+## Recursos
+
+### Clientes
+
+```python
+customer = vitrin.customers.create(
+    name="Maria Silva",
+    email="maria@example.com",
+    cpf_cnpj="12345678901",
+)
+
+vitrin.customers.list(page=1)
+vitrin.customers.update(customer["id"], phone="11987654321")
+vitrin.customers.delete(customer["id"])
+```
+
+### Cobranças
+
+```python
+charge = vitrin.charges.create(
+    customer_id=customer["id"],
+    amount=99.90,
+    billing_type="PIX",
+    description="Mensalidade abril",
+    idempotency_key=f"mensalidade-{customer['id']}-2026-04",  # evita duplo-débito em retry
+)
+
+print(charge["pix_qr_code"])
+print(charge["pix_copy_paste"])
+
+# Reembolso parcial
+vitrin.charges.refund(charge["id"], amount=50.0, pin="123456")
+```
+
+### Planos & Assinaturas
+
+```python
+plan = vitrin.plans.create(name="Pro Mensal", price=99.0, billing_cycle="monthly")
+
+sub = vitrin.subscriptions.create(
+    customer_id=customer["id"],
+    plan_id=plan["id"],
+    billing_type="CREDIT_CARD",
+    credit_card_token="tok_xxx",
+)
+
+vitrin.subscriptions.cancel(sub["id"], pin="123456")
+```
+
+### Saldo & Recebíveis
+
+```python
+vitrin.balance.retrieve()
+# → { "available": ..., "total": ..., "pending": ..., "withdrawal_fees": {...} }
+
+vitrin.balance.scheduled(90)
+# → cronograma 90d: PIX D+1, Boleto D+2, Cartão Nx D+30·n
+```
+
+## Webhooks
+
+```python
+from flask import Flask, request, abort
+from vitrin import webhooks, VitrinError
+import os
+
+app = Flask(__name__)
+
+@app.post("/webhooks/vitrin")
+def handle_webhook():
+    try:
+        event = webhooks.construct_event(
+            payload=request.get_data(),                          # body cru, NÃO parsed
+            signature=request.headers.get("X-Vitrin-Signature"),
+            timestamp=request.headers.get("X-Vitrin-Timestamp"),
+            event_type=request.headers.get("X-Vitrin-Event"),
+            event_id=request.headers.get("X-Vitrin-Event-Id"),
+            secret=os.environ["VITRIN_WEBHOOK_SECRET"],
+        )
+        print(event.type, event.id, event.data)
+        return "", 200
+    except VitrinError as e:
+        return str(e), 400
+```
+
+## Tratamento de erros
+
+```python
+from vitrin import (
+    VitrinError, VitrinAuthError, VitrinValidationError,
+    VitrinRateLimitError, VitrinNotFoundError, VitrinServerError,
+)
+
+try:
+    vitrin.charges.create(...)
+except VitrinValidationError as e:
+    print("Campos inválidos:", e.field_errors)
+except VitrinAuthError:
+    print("Chave inválida ou sem permissão")
+except VitrinRateLimitError:
+    print("Aguarde antes de tentar de novo")
+except VitrinError as e:
+    print(f"Erro Vitrin: {e.status_code} {e.request_id} {e.message}")
+```
+
+Retry automático em **429** e **5xx** com backoff exponencial (default: 3 tentativas). 4xx (exceto 429) não são retentados.
+
+## Idempotência
+
+Inclua `idempotency_key` em POSTs sensíveis. Se o request chegar duas vezes (retry de rede, deploy etc), a Vitrin reconhece pela chave e devolve a mesma resposta — sem cobrar duas vezes.
+
+```python
+vitrin.charges.create(
+    customer_id="cus_1",
+    amount=100,
+    billing_type="PIX",
+    idempotency_key=f"pedido-{order_id}",  # único por pedido
+)
+```
+
+## Acesso bruto
+
+```python
+data = vitrin.request("/some/path/", method="POST", body={"foo": "bar"})
+```
+
+## Licença
+
+MIT

vitrin-0.1.0/README.md

@@ -0,0 +1,156 @@
+# vitrin (Python)
+
+SDK oficial Python para a [API da Vitrin Digital](https://api.vitrin.digital).
+
+```bash
+pip install vitrin
+```
+
+> **Python 3.10+** requerido. Única dependência runtime: `requests`.
+
+## Setup
+
+```python
+import os
+from vitrin import Vitrin
+
+vitrin = Vitrin(
+    api_key=os.environ["VITRIN_API_KEY"],
+    # opcionais:
+    # base_url="https://api.vitrin.digital/api/v1",
+    # timeout=30.0,
+    # max_retries=3,
+)
+```
+
+Use `vd_test_*` em desenvolvimento, `vd_live_*` em produção.
+
+## Recursos
+
+### Clientes
+
+```python
+customer = vitrin.customers.create(
+    name="Maria Silva",
+    email="maria@example.com",
+    cpf_cnpj="12345678901",
+)
+
+vitrin.customers.list(page=1)
+vitrin.customers.update(customer["id"], phone="11987654321")
+vitrin.customers.delete(customer["id"])
+```
+
+### Cobranças
+
+```python
+charge = vitrin.charges.create(
+    customer_id=customer["id"],
+    amount=99.90,
+    billing_type="PIX",
+    description="Mensalidade abril",
+    idempotency_key=f"mensalidade-{customer['id']}-2026-04",  # evita duplo-débito em retry
+)
+
+print(charge["pix_qr_code"])
+print(charge["pix_copy_paste"])
+
+# Reembolso parcial
+vitrin.charges.refund(charge["id"], amount=50.0, pin="123456")
+```
+
+### Planos & Assinaturas
+
+```python
+plan = vitrin.plans.create(name="Pro Mensal", price=99.0, billing_cycle="monthly")
+
+sub = vitrin.subscriptions.create(
+    customer_id=customer["id"],
+    plan_id=plan["id"],
+    billing_type="CREDIT_CARD",
+    credit_card_token="tok_xxx",
+)
+
+vitrin.subscriptions.cancel(sub["id"], pin="123456")
+```
+
+### Saldo & Recebíveis
+
+```python
+vitrin.balance.retrieve()
+# → { "available": ..., "total": ..., "pending": ..., "withdrawal_fees": {...} }
+
+vitrin.balance.scheduled(90)
+# → cronograma 90d: PIX D+1, Boleto D+2, Cartão Nx D+30·n
+```
+
+## Webhooks
+
+```python
+from flask import Flask, request, abort
+from vitrin import webhooks, VitrinError
+import os
+
+app = Flask(__name__)
+
+@app.post("/webhooks/vitrin")
+def handle_webhook():
+    try:
+        event = webhooks.construct_event(
+            payload=request.get_data(),                          # body cru, NÃO parsed
+            signature=request.headers.get("X-Vitrin-Signature"),
+            timestamp=request.headers.get("X-Vitrin-Timestamp"),
+            event_type=request.headers.get("X-Vitrin-Event"),
+            event_id=request.headers.get("X-Vitrin-Event-Id"),
+            secret=os.environ["VITRIN_WEBHOOK_SECRET"],
+        )
+        print(event.type, event.id, event.data)
+        return "", 200
+    except VitrinError as e:
+        return str(e), 400
+```
+
+## Tratamento de erros
+
+```python
+from vitrin import (
+    VitrinError, VitrinAuthError, VitrinValidationError,
+    VitrinRateLimitError, VitrinNotFoundError, VitrinServerError,
+)
+
+try:
+    vitrin.charges.create(...)
+except VitrinValidationError as e:
+    print("Campos inválidos:", e.field_errors)
+except VitrinAuthError:
+    print("Chave inválida ou sem permissão")
+except VitrinRateLimitError:
+    print("Aguarde antes de tentar de novo")
+except VitrinError as e:
+    print(f"Erro Vitrin: {e.status_code} {e.request_id} {e.message}")
+```
+
+Retry automático em **429** e **5xx** com backoff exponencial (default: 3 tentativas). 4xx (exceto 429) não são retentados.
+
+## Idempotência
+
+Inclua `idempotency_key` em POSTs sensíveis. Se o request chegar duas vezes (retry de rede, deploy etc), a Vitrin reconhece pela chave e devolve a mesma resposta — sem cobrar duas vezes.
+
+```python
+vitrin.charges.create(
+    customer_id="cus_1",
+    amount=100,
+    billing_type="PIX",
+    idempotency_key=f"pedido-{order_id}",  # único por pedido
+)
+```
+
+## Acesso bruto
+
+```python
+data = vitrin.request("/some/path/", method="POST", body={"foo": "bar"})
+```
+
+## Licença
+
+MIT

vitrin-0.1.0/pyproject.toml

@@ -0,0 +1,54 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "vitrin"
+version = "0.1.0"
+description = "SDK oficial Python para a API da Vitrin Digital"
+readme = "README.md"
+requires-python = ">=3.10"
+license = "MIT"
+authors = [{ name = "Vitrin Digital" }]
+keywords = ["vitrin", "vitrin-digital", "pagamentos", "pix", "boleto", "checkout"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "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",
+    "Topic :: Office/Business :: Financial",
+]
+dependencies = [
+    "requests>=2.31",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8",
+    "pytest-mock>=3.12",
+    "responses>=0.25",
+    "ruff>=0.7",
+    "mypy>=1.10",
+]
+
+[project.urls]
+Homepage = "https://vitrin.digital"
+Documentation = "https://vitrin.digital/docs/integracao"
+Repository = "https://github.com/vitrindigital/vitrin"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/vitrin"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py310"
+
+[tool.ruff.lint]
+select = ["E", "F", "W", "I", "N", "UP", "B", "C4", "SIM"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+python_files = ["test_*.py"]

vitrin-0.1.0/src/vitrin/__init__.py

@@ -0,0 +1,83 @@
+"""SDK oficial Python para a API da Vitrin Digital.
+
+Uso típico::
+
+    from vitrin import Vitrin
+
+    vitrin = Vitrin(api_key=os.environ["VITRIN_API_KEY"])
+
+    customer = vitrin.customers.create(
+        name="Maria Silva",
+        email="maria@example.com",
+        cpf_cnpj="12345678901",
+    )
+    charge = vitrin.charges.create(
+        customer_id=customer["id"],
+        amount=99.90,
+        billing_type="PIX",
+        idempotency_key=f"pedido-{order_id}",
+    )
+    print(charge["pix_qr_code"])
+
+Validação de webhook::
+
+    from vitrin import webhooks
+    event = webhooks.construct_event(
+        payload=request.body,
+        signature=request.headers["X-Vitrin-Signature"],
+        secret=os.environ["VITRIN_WEBHOOK_SECRET"],
+    )
+"""
+
+from ._client import Client, DEFAULT_BASE_URL
+from .errors import (
+    VitrinError,
+    VitrinAuthError,
+    VitrinValidationError,
+    VitrinRateLimitError,
+    VitrinNotFoundError,
+    VitrinServerError,
+    VitrinNetworkError,
+)
+from .resources import Charges, Customers, Plans, Subscriptions, Products, BalanceAPI
+from . import webhooks
+
+__version__ = '0.1.0'
+
+__all__ = [
+    'Vitrin',
+    'webhooks',
+    'VitrinError',
+    'VitrinAuthError',
+    'VitrinValidationError',
+    'VitrinRateLimitError',
+    'VitrinNotFoundError',
+    'VitrinServerError',
+    'VitrinNetworkError',
+]
+
+
+class Vitrin:
+    """Entry-point do SDK. Instanciar com a `api_key` da org."""
+
+    def __init__(
+        self,
+        api_key: str,
+        *,
+        base_url: str = DEFAULT_BASE_URL,
+        timeout: float = 30.0,
+        max_retries: int = 3,
+    ) -> None:
+        self.client = Client(
+            api_key=api_key, base_url=base_url, timeout=timeout, max_retries=max_retries,
+        )
+        self.charges = Charges(self.client)
+        self.customers = Customers(self.client)
+        self.plans = Plans(self.client)
+        self.subscriptions = Subscriptions(self.client)
+        self.products = Products(self.client)
+        self.balance = BalanceAPI(self.client)
+
+    def request(self, path: str, **kwargs):  # type: ignore[no-untyped-def]
+        """Acesso bruto pra endpoints não cobertos pelos resources."""
+        return self.client.request(path, **kwargs)

vitrin-0.1.0/src/vitrin/_client.py

@@ -0,0 +1,191 @@
+"""HTTP client interno do SDK.
+
+Wrapper sobre `requests.Session` com:
+- Headers padrão (Authorization, User-Agent, Content-Type)
+- Mapeamento de status HTTP → :class:`vitrin.errors.VitrinError`
+- Retry automático em 429/5xx com backoff exponencial e jitter
+- Idempotency-Key opcional pra POSTs
+"""
+
+from __future__ import annotations
+
+import json as _json
+import platform
+import random
+import time
+from typing import Any
+from urllib.parse import urljoin
+
+import requests
+
+from .errors import (
+    VitrinAuthError,
+    VitrinError,
+    VitrinNetworkError,
+    VitrinNotFoundError,
+    VitrinRateLimitError,
+    VitrinServerError,
+    VitrinValidationError,
+)
+
+DEFAULT_BASE_URL = 'https://api.vitrin.digital/api/v1'
+SDK_VERSION = '0.1.0'
+
+
+class Client:
+    def __init__(
+        self,
+        api_key: str,
+        *,
+        base_url: str = DEFAULT_BASE_URL,
+        timeout: float = 30.0,
+        max_retries: int = 3,
+        session: requests.Session | None = None,
+    ) -> None:
+        if not api_key:
+            raise ValueError('api_key é obrigatório')
+        self.api_key = api_key
+        self.base_url = base_url.rstrip('/')
+        self.timeout = timeout
+        self.max_retries = max_retries
+        self.session = session or requests.Session()
+
+    def request(
+        self,
+        path: str,
+        *,
+        method: str = 'GET',
+        body: Any = None,
+        query: dict[str, Any] | None = None,
+        idempotency_key: str | None = None,
+    ) -> Any:
+        url = urljoin(self.base_url + '/', path.lstrip('/'))
+        headers = self._build_headers(has_body=body is not None, idempotency_key=idempotency_key)
+        params = _filter_query(query)
+
+        last_exc: VitrinError | None = None
+
+        for attempt in range(self.max_retries + 1):
+            try:
+                resp = self.session.request(
+                    method=method,
+                    url=url,
+                    headers=headers,
+                    params=params,
+                    data=_json.dumps(body) if body is not None else None,
+                    timeout=self.timeout,
+                )
+            except requests.exceptions.Timeout as e:
+                last_exc = VitrinNetworkError(f'Timeout após {self.timeout}s')
+                if attempt < self.max_retries:
+                    time.sleep(_backoff(attempt))
+                    continue
+                raise last_exc from e
+            except requests.exceptions.RequestException as e:
+                last_exc = VitrinNetworkError(str(e))
+                if attempt < self.max_retries:
+                    time.sleep(_backoff(attempt))
+                    continue
+                raise last_exc from e
+
+            request_id = resp.headers.get('x-request-id')
+
+            if 200 <= resp.status_code < 300:
+                if resp.status_code == 204 or not resp.content:
+                    return None
+                try:
+                    return resp.json()
+                except ValueError:
+                    return resp.text
+
+            try:
+                parsed = resp.json()
+            except ValueError:
+                parsed = resp.text
+
+            err = _map_error(resp.status_code, parsed, request_id)
+            retriable = resp.status_code == 429 or resp.status_code >= 500
+            if retriable and attempt < self.max_retries:
+                retry_after = _parse_retry_after(resp.headers.get('retry-after'))
+                time.sleep(retry_after if retry_after is not None else _backoff(attempt))
+                last_exc = err
+                continue
+            raise err
+
+        raise last_exc or VitrinError('Esgotou tentativas sem erro identificado')
+
+    def _build_headers(self, *, has_body: bool, idempotency_key: str | None) -> dict[str, str]:
+        py_version = platform.python_version()
+        ua = f'vitrin-python/{SDK_VERSION} python/{py_version}'
+        headers: dict[str, str] = {
+            'Authorization': f'Bearer {self.api_key}',
+            'Accept': 'application/json',
+            'User-Agent': ua,
+        }
+        if has_body:
+            headers['Content-Type'] = 'application/json'
+        if idempotency_key:
+            headers['Idempotency-Key'] = idempotency_key
+        return headers
+
+
+def _filter_query(query: dict[str, Any] | None) -> dict[str, Any] | None:
+    if not query:
+        return None
+    return {k: v for k, v in query.items() if v is not None and v != ''}
+
+
+def _map_error(status: int, body: Any, request_id: str | None) -> VitrinError:
+    message = _extract_message(body) or f'HTTP {status}'
+    common = {'status_code': status, 'body': body, 'request_id': request_id}
+
+    if status in (401, 403):
+        return VitrinAuthError(message, **common)
+    if status == 404:
+        return VitrinNotFoundError(message, **common)
+    if status == 429:
+        return VitrinRateLimitError(message, **common)
+    if status >= 500:
+        return VitrinServerError(message, **common)
+    if status in (400, 422):
+        return VitrinValidationError(
+            message, **common, field_errors=_extract_field_errors(body),
+        )
+    return VitrinError(message, **common)
+
+
+def _extract_message(body: Any) -> str | None:
+    if not isinstance(body, dict):
+        return None
+    if isinstance(body.get('error'), str):
+        return body['error']
+    if isinstance(body.get('detail'), str):
+        return body['detail']
+    for v in body.values():
+        if isinstance(v, list) and v and isinstance(v[0], str):
+            return v[0]
+    return None
+
+
+def _extract_field_errors(body: Any) -> dict[str, list[str]]:
+    if not isinstance(body, dict):
+        return {}
+    out: dict[str, list[str]] = {}
+    for k, v in body.items():
+        if isinstance(v, list) and all(isinstance(x, str) for x in v):
+            out[k] = v
+    return out
+
+
+def _parse_retry_after(value: str | None) -> float | None:
+    if not value:
+        return None
+    try:
+        return float(value)
+    except ValueError:
+        return None
+
+
+def _backoff(attempt: int) -> float:
+    base = 0.25 * (2 ** attempt)
+    return base + random.uniform(0, base * 0.5)

vitrin-0.1.0/src/vitrin/errors.py

@@ -0,0 +1,64 @@
+"""Hierarquia de erros do SDK Vitrin.
+
+Todos descendem de :class:`VitrinError`.
+"""
+
+from __future__ import annotations
+from typing import Any
+
+
+class VitrinError(Exception):
+    """Erro base do SDK Vitrin. Toda chamada à API que falha levanta isso ou subclasse."""
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        status_code: int | None = None,
+        body: Any = None,
+        request_id: str | None = None,
+    ) -> None:
+        super().__init__(message)
+        self.message = message
+        self.status_code = status_code
+        self.body = body
+        self.request_id = request_id
+
+    def __repr__(self) -> str:  # pragma: no cover
+        return f'<{type(self).__name__}: {self.message} (status={self.status_code})>'
+
+
+class VitrinAuthError(VitrinError):
+    """401/403 — chave inválida, expirada, ou sem permissão."""
+
+
+class VitrinValidationError(VitrinError):
+    """400/422 — DRF retornou erros de campo ou body inválido."""
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        status_code: int | None = None,
+        body: Any = None,
+        request_id: str | None = None,
+        field_errors: dict[str, list[str]] | None = None,
+    ) -> None:
+        super().__init__(message, status_code=status_code, body=body, request_id=request_id)
+        self.field_errors = field_errors or {}
+
+
+class VitrinRateLimitError(VitrinError):
+    """429 — você ultrapassou o rate limit."""
+
+
+class VitrinNotFoundError(VitrinError):
+    """404 — recurso não encontrado."""
+
+
+class VitrinServerError(VitrinError):
+    """5xx — falha do lado do servidor."""
+
+
+class VitrinNetworkError(VitrinError):
+    """Falha antes da resposta HTTP — DNS, timeout, conexão recusada."""

vitrin-0.1.0/src/vitrin/resources/__init__.py

@@ -0,0 +1,8 @@
+from .charges import Charges
+from .customers import Customers
+from .plans import Plans
+from .subscriptions import Subscriptions
+from .products import Products
+from .balance import BalanceAPI
+
+__all__ = ['Charges', 'Customers', 'Plans', 'Subscriptions', 'Products', 'BalanceAPI']

vitrin-0.1.0/src/vitrin/resources/balance.py

@@ -0,0 +1,14 @@
+from __future__ import annotations
+from typing import Any
+from .._client import Client
+
+
+class BalanceAPI:
+    def __init__(self, client: Client) -> None:
+        self._client = client
+
+    def retrieve(self) -> dict[str, Any]:
+        return self._client.request('/balance/')
+
+    def scheduled(self, days_ahead: int = 90) -> dict[str, Any]:
+        return self._client.request('/balance/scheduled/', query={'days_ahead': days_ahead})

vitrin-0.1.0/src/vitrin/resources/charges.py

@@ -0,0 +1,65 @@
+from __future__ import annotations
+from typing import Any
+from .._client import Client
+
+
+class Charges:
+    """Cobranças avulsas — PIX, Boleto, Cartão."""
+
+    def __init__(self, client: Client) -> None:
+        self._client = client
+
+    def create(
+        self,
+        *,
+        customer_id: str,
+        amount: float | str,
+        billing_type: str,
+        description: str = '',
+        due_date: str | None = None,
+        installments: int = 1,
+        credit_card_token: str | None = None,
+        idempotency_key: str | None = None,
+    ) -> dict[str, Any]:
+        body = {
+            'customer_id': customer_id,
+            'amount': amount,
+            'billing_type': billing_type,
+            'description': description,
+            'installments': installments,
+        }
+        if due_date:
+            body['due_date'] = due_date
+        if credit_card_token:
+            body['credit_card_token'] = credit_card_token
+        return self._client.request(
+            '/charges/', method='POST', body=body, idempotency_key=idempotency_key,
+        )
+
+    def retrieve(self, charge_id: str) -> dict[str, Any]:
+        return self._client.request(f'/transactions/{charge_id}/')
+
+    def list(self, **params: Any) -> dict[str, Any]:
+        return self._client.request('/reports/transactions/', query=params)
+
+    def refund(
+        self,
+        charge_id: str,
+        *,
+        pin: str,
+        amount: float | str | None = None,
+    ) -> dict[str, Any]:
+        body: dict[str, Any] = {'pin': pin}
+        if amount is not None:
+            body['amount'] = amount
+        return self._client.request(
+            f'/payments/{charge_id}/refund/', method='POST', body=body,
+        )
+
+    def cancel(self, charge_id: str, *, pin: str) -> dict[str, Any]:
+        return self._client.request(
+            f'/payments/{charge_id}/cancel/', method='POST', body={'pin': pin},
+        )
+
+    def status(self, charge_id: str) -> dict[str, Any]:
+        return self._client.request(f'/payments/{charge_id}/status/')

vitrin-0.1.0/src/vitrin/resources/customers.py

@@ -0,0 +1,25 @@
+from __future__ import annotations
+from typing import Any
+from .._client import Client
+
+
+class Customers:
+    def __init__(self, client: Client) -> None:
+        self._client = client
+
+    def create(self, **fields: Any) -> dict[str, Any]:
+        return self._client.request('/customers/', method='POST', body=fields)
+
+    def retrieve(self, customer_id: str) -> dict[str, Any]:
+        return self._client.request(f'/customers/{customer_id}/')
+
+    def list(self, **params: Any) -> dict[str, Any]:
+        return self._client.request('/customers/', query=params)
+
+    def update(self, customer_id: str, **fields: Any) -> dict[str, Any]:
+        return self._client.request(
+            f'/customers/{customer_id}/', method='PATCH', body=fields,
+        )
+
+    def delete(self, customer_id: str) -> None:
+        self._client.request(f'/customers/{customer_id}/', method='DELETE')

vitrin-0.1.0/src/vitrin/resources/plans.py

@@ -0,0 +1,23 @@
+from __future__ import annotations
+from typing import Any
+from .._client import Client
+
+
+class Plans:
+    def __init__(self, client: Client) -> None:
+        self._client = client
+
+    def create(self, **fields: Any) -> dict[str, Any]:
+        return self._client.request('/plans/', method='POST', body=fields)
+
+    def retrieve(self, plan_id: str) -> dict[str, Any]:
+        return self._client.request(f'/plans/{plan_id}/')
+
+    def list(self, **params: Any) -> dict[str, Any]:
+        return self._client.request('/plans/', query=params)
+
+    def update(self, plan_id: str, **fields: Any) -> dict[str, Any]:
+        return self._client.request(f'/plans/{plan_id}/', method='PATCH', body=fields)
+
+    def delete(self, plan_id: str) -> None:
+        self._client.request(f'/plans/{plan_id}/', method='DELETE')

vitrin-0.1.0/src/vitrin/resources/products.py

@@ -0,0 +1,25 @@
+from __future__ import annotations
+from typing import Any
+from .._client import Client
+
+
+class Products:
+    def __init__(self, client: Client) -> None:
+        self._client = client
+
+    def create(self, **fields: Any) -> dict[str, Any]:
+        return self._client.request('/products/', method='POST', body=fields)
+
+    def retrieve(self, product_id: str) -> dict[str, Any]:
+        return self._client.request(f'/products/{product_id}/')
+
+    def list(self, **params: Any) -> dict[str, Any]:
+        return self._client.request('/products/', query=params)
+
+    def update(self, product_id: str, **fields: Any) -> dict[str, Any]:
+        return self._client.request(
+            f'/products/{product_id}/', method='PATCH', body=fields,
+        )
+
+    def delete(self, product_id: str) -> None:
+        self._client.request(f'/products/{product_id}/', method='DELETE')

vitrin-0.1.0/src/vitrin/resources/subscriptions.py

@@ -0,0 +1,22 @@
+from __future__ import annotations
+from typing import Any
+from .._client import Client
+
+
+class Subscriptions:
+    def __init__(self, client: Client) -> None:
+        self._client = client
+
+    def create(self, **fields: Any) -> dict[str, Any]:
+        return self._client.request('/subscriptions/', method='POST', body=fields)
+
+    def retrieve(self, sub_id: str) -> dict[str, Any]:
+        return self._client.request(f'/subscriptions/{sub_id}/')
+
+    def list(self, **params: Any) -> dict[str, Any]:
+        return self._client.request('/subscriptions/', query=params)
+
+    def cancel(self, sub_id: str, *, pin: str) -> dict[str, Any]:
+        return self._client.request(
+            f'/subscriptions/{sub_id}/cancel/', method='POST', body={'pin': pin},
+        )

vitrin-0.1.0/src/vitrin/webhooks.py

@@ -0,0 +1,74 @@
+"""Validação de webhooks Vitrin → seu backend Python.
+
+A Vitrin envia POST com:
+    X-Vitrin-Signature: HMAC-SHA256 hex do body cru com o webhook_secret
+    X-Vitrin-Timestamp: epoch UTC em segundos
+    X-Vitrin-Event:     tipo do evento
+    X-Vitrin-Event-Id:  ID único pra idempotência
+
+Use :func:`construct_event` no handler do seu backend antes de processar.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import hmac
+import json
+import time
+from dataclasses import dataclass, field
+from typing import Any
+
+from .errors import VitrinError
+
+
+@dataclass
+class WebhookEvent:
+    type: str
+    id: str
+    timestamp_ms: int
+    data: dict[str, Any] = field(default_factory=dict)
+
+
+def construct_event(
+    *,
+    payload: bytes | str,
+    signature: str | None,
+    secret: str,
+    timestamp: str | None = None,
+    event_type: str | None = None,
+    event_id: str | None = None,
+    tolerance_ms: int = 300_000,
+) -> WebhookEvent:
+    """Valida a assinatura HMAC + timestamp e retorna o evento parseado."""
+    if not signature:
+        raise VitrinError('Header X-Vitrin-Signature ausente.')
+    if not secret:
+        raise VitrinError('webhook secret é obrigatório.')
+
+    raw = payload.encode('utf-8') if isinstance(payload, str) else payload
+    expected = hmac.new(secret.encode('utf-8'), raw, hashlib.sha256).hexdigest()
+    if not hmac.compare_digest(expected, signature.strip()):
+        raise VitrinError('Assinatura inválida — payload pode ter sido adulterado.')
+
+    if tolerance_ms > 0 and timestamp:
+        try:
+            ts_ms = int(timestamp) * 1000
+        except ValueError as e:
+            raise VitrinError('X-Vitrin-Timestamp inválido.') from e
+        drift = abs(int(time.time() * 1000) - ts_ms)
+        if drift > tolerance_ms:
+            raise VitrinError(
+                f'Webhook fora da janela de tolerância (drift {drift}ms > {tolerance_ms}ms).'
+            )
+
+    try:
+        data = json.loads(raw.decode('utf-8'))
+    except (ValueError, UnicodeDecodeError) as e:
+        raise VitrinError('Payload não é JSON válido.') from e
+
+    return WebhookEvent(
+        type=event_type or '',
+        id=event_id or '',
+        timestamp_ms=int(timestamp) * 1000 if timestamp else int(time.time() * 1000),
+        data=data,
+    )

vitrin-0.1.0/tests/test_client.py

@@ -0,0 +1,136 @@
+"""Testes do client HTTP (mocked com responses)."""
+
+import pytest
+import responses
+
+from vitrin import (
+    Vitrin,
+    VitrinAuthError,
+    VitrinNotFoundError,
+    VitrinRateLimitError,
+    VitrinServerError,
+    VitrinValidationError,
+)
+
+BASE = 'https://api.vitrin.digital/api/v1'
+
+
+def test_rejects_construction_without_api_key():
+    with pytest.raises(ValueError):
+        Vitrin(api_key='')
+
+
+@responses.activate
+def test_request_sends_authorization_header():
+    responses.add(responses.GET, f'{BASE}/whatever/', json={'ok': True}, status=200)
+    Vitrin(api_key='vd_test_xyz').request('/whatever/')
+    call = responses.calls[0].request
+    assert call.headers['Authorization'] == 'Bearer vd_test_xyz'
+    assert 'vitrin-python/' in call.headers['User-Agent']
+
+
+@responses.activate
+def test_query_params_drop_none():
+    responses.add(responses.GET, f'{BASE}/list', json=[], status=200)
+    Vitrin(api_key='k').request('/list', query={'page': 2, 'unset': None, 'empty': ''})
+    url = responses.calls[0].request.url
+    assert 'page=2' in url
+    assert 'unset' not in url
+    assert 'empty' not in url
+
+
+@responses.activate
+def test_204_returns_none():
+    responses.add(responses.DELETE, f'{BASE}/x/', status=204)
+    assert Vitrin(api_key='k').request('/x/', method='DELETE') is None
+
+
+@responses.activate
+def test_401_maps_to_auth_error():
+    responses.add(responses.GET, f'{BASE}/x/', json={'error': 'invalid'}, status=401)
+    with pytest.raises(VitrinAuthError):
+        Vitrin(api_key='k', max_retries=0).request('/x/')
+
+
+@responses.activate
+def test_404_maps_to_not_found():
+    responses.add(responses.GET, f'{BASE}/x/', json={'detail': 'not found'}, status=404)
+    with pytest.raises(VitrinNotFoundError):
+        Vitrin(api_key='k', max_retries=0).request('/x/')
+
+
+@responses.activate
+def test_422_maps_to_validation_with_field_errors():
+    responses.add(
+        responses.POST, f'{BASE}/x/',
+        json={'amount': ['positivo'], 'cpf_cnpj': ['inválido']},
+        status=422,
+    )
+    try:
+        Vitrin(api_key='k', max_retries=0).request('/x/', method='POST', body={})
+    except VitrinValidationError as e:
+        assert e.field_errors['amount'] == ['positivo']
+        assert e.field_errors['cpf_cnpj'] == ['inválido']
+    else:
+        pytest.fail('should have raised')
+
+
+@responses.activate
+def test_429_retries_then_succeeds():
+    responses.add(responses.GET, f'{BASE}/x/',
+                  json={'error': 'rate'}, status=429,
+                  headers={'retry-after': '0'})
+    responses.add(responses.GET, f'{BASE}/x/', json={'ok': True}, status=200)
+    result = Vitrin(api_key='k', max_retries=3).request('/x/')
+    assert result == {'ok': True}
+    assert len(responses.calls) == 2
+
+
+@responses.activate
+def test_503_retries_and_gives_up():
+    for _ in range(3):
+        responses.add(responses.GET, f'{BASE}/x/', json={'error': 'down'}, status=503)
+    with pytest.raises(VitrinServerError):
+        Vitrin(api_key='k', max_retries=2).request('/x/')
+    assert len(responses.calls) == 3  # 1 inicial + 2 retries
+
+
+@responses.activate
+def test_400_does_not_retry():
+    responses.add(responses.POST, f'{BASE}/x/', json={'error': 'bad'}, status=400)
+    with pytest.raises(VitrinValidationError):
+        Vitrin(api_key='k', max_retries=5).request('/x/', method='POST', body={})
+    assert len(responses.calls) == 1
+
+
+@responses.activate
+def test_idempotency_key_forwarded():
+    responses.add(responses.POST, f'{BASE}/charges/',
+                  json={'id': 'tx_1'}, status=201)
+    Vitrin(api_key='k').charges.create(
+        customer_id='cus_1', amount=100, billing_type='PIX',
+        idempotency_key='order-42',
+    )
+    assert responses.calls[0].request.headers['Idempotency-Key'] == 'order-42'
+
+
+@responses.activate
+def test_charges_create_posts_body():
+    responses.add(responses.POST, f'{BASE}/charges/',
+                  json={'id': 'tx_1'}, status=201)
+    Vitrin(api_key='k').charges.create(
+        customer_id='cus_1', amount=99.90, billing_type='PIX', description='x',
+    )
+    body = responses.calls[0].request.body
+    if isinstance(body, bytes):
+        body = body.decode('utf-8')
+    assert '"customer_id": "cus_1"' in body
+    assert '"billing_type": "PIX"' in body
+
+
+@responses.activate
+def test_customers_namespaces_exposed():
+    responses.add(responses.GET, f'{BASE}/customers/cus_x/',
+                  json={'id': 'cus_x', 'name': 'Maria'}, status=200)
+    v = Vitrin(api_key='k')
+    assert v.customers.retrieve('cus_x')['name'] == 'Maria'

vitrin-0.1.0/tests/test_webhooks.py

@@ -0,0 +1,82 @@
+"""Testes do helper de webhooks."""
+
+import hashlib
+import hmac
+import time
+
+import pytest
+
+from vitrin import VitrinError, webhooks
+
+SECRET = 'whsec_test'
+
+
+def _sign(payload: bytes) -> str:
+    return hmac.new(SECRET.encode(), payload, hashlib.sha256).hexdigest()
+
+
+def test_constructs_event_with_valid_signature():
+    payload = b'{"IdTransaction":"tx_1","amount":100}'
+    evt = webhooks.construct_event(
+        payload=payload,
+        signature=_sign(payload),
+        secret=SECRET,
+        timestamp=str(int(time.time())),
+        event_type='Autorizado',
+        event_id='evt_1',
+    )
+    assert evt.type == 'Autorizado'
+    assert evt.id == 'evt_1'
+    assert evt.data['IdTransaction'] == 'tx_1'
+
+
+def test_rejects_invalid_signature():
+    with pytest.raises(VitrinError, match='Assinatura'):
+        webhooks.construct_event(
+            payload=b'{"x":1}',
+            signature='a' * 64,
+            secret=SECRET,
+        )
+
+
+def test_rejects_missing_signature():
+    with pytest.raises(VitrinError, match='Signature'):
+        webhooks.construct_event(payload=b'{}', signature=None, secret=SECRET)
+
+
+def test_rejects_old_timestamp():
+    payload = b'{}'
+    old = str(int(time.time()) - 600)
+    with pytest.raises(VitrinError, match='tolerância'):
+        webhooks.construct_event(
+            payload=payload, signature=_sign(payload),
+            secret=SECRET, timestamp=old,
+        )
+
+
+def test_accepts_old_timestamp_when_tolerance_zero():
+    payload = b'{}'
+    old = str(int(time.time()) - 600)
+    evt = webhooks.construct_event(
+        payload=payload, signature=_sign(payload),
+        secret=SECRET, timestamp=old, tolerance_ms=0,
+    )
+    assert evt is not None
+
+
+def test_accepts_string_payload():
+    payload = '{"x":1}'
+    evt = webhooks.construct_event(
+        payload=payload,
+        signature=_sign(payload.encode()),
+        secret=SECRET,
+    )
+    assert evt.data == {'x': 1}
+
+
+def test_rejects_non_json_payload():
+    payload = b'not json'
+    with pytest.raises(VitrinError, match='JSON'):
+        webhooks.construct_event(
+            payload=payload, signature=_sign(payload), secret=SECRET,
+        )