vitrin 0.1.0__py3-none-any.whl

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/_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/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/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/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/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/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/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/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/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/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.dist-info/METADATA

@@ -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.dist-info/RECORD

@@ -0,0 +1,14 @@
+vitrin/__init__.py,sha256=0AUat6eX5M_LLPjMTw6qNUiH1Zia_wFKcFO996FLsv8,2216
+vitrin/_client.py,sha256=rzJUmPJFN1-44sqH2ggVVGTxeUBq63QOyQqG1YOtn2o,6120
+vitrin/errors.py,sha256=RJdDJKyn_jtSxKmmyH-1Z_lwoNvasl-MG1LDgfLAn10,1740
+vitrin/webhooks.py,sha256=0weud42f4O50Zvz4RXgnhzFzAmj0OaUQvaLaJxE9zrI,2287
+vitrin/resources/__init__.py,sha256=Q2jNfQkBbZvFDmNJ0Z2lk_yMfkSRs0KdG_erVkBDFCk,279
+vitrin/resources/balance.py,sha256=F8g74BDO7v6Uj0STh2PtgpJDb0NKJ36jPv8PGgCBsdo,436
+vitrin/resources/charges.py,sha256=ftN4RDzYucaum4Cvi73XL_h6FE11-o9dp3WxxaI5omI,2039
+vitrin/resources/customers.py,sha256=tUr51aYgBWvWYzf3YNuWgahDTAaIX-wBMW642eHpkpg,882
+vitrin/resources/plans.py,sha256=ZhTl2ff9f7oUeGySCXMayBvT7niwDEV-aUvrNRTSOno,811
+vitrin/resources/products.py,sha256=2RenNKxdDUJsjSDYIZpdXat1iWk5OQnUylklVNX759g,870
+vitrin/resources/subscriptions.py,sha256=VOvBzl-Rm2Hm7Xm-K7SgOpoM_e67D1JI266253nuJ24,767
+vitrin-0.1.0.dist-info/METADATA,sha256=B4t2XpJkXw52zPh_7hc3kn9tcb871cLfN212kgG3pNk,4862
+vitrin-0.1.0.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+vitrin-0.1.0.dist-info/RECORD,,

vitrin-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.29.0
+Root-Is-Purelib: true
+Tag: py3-none-any