tilde-afip 0.1.0a1__tar.gz

tilde_afip-0.1.0a1/.gitignore

@@ -0,0 +1,6 @@
+__pycache__/
+*.egg-info/
+.pytest_cache/
+dist/
+build/
+.venv/

tilde_afip-0.1.0a1/GENERATION.md

@@ -0,0 +1,13 @@
+# Generación — tilde-afip (Python)
+
+Igual que el SDK TypeScript, el cliente usa un **transport propio sobre la stdlib** (`urllib`,
+cero dependencias de runtime) en vez del cliente generado por Kiota. El facade/auth/errors/webhooks
+son runtime-agnósticos; la cobertura tipada completa de operaciones se generará del contrato
+(`openapi/tilde-api-v1.json`) cuando se adopte un codegen estable (Kiota Python u OpenAPI Generator).
+
+Estructura:
+- `client.py` — TildeClient (transport + recurso `invoices` + `request()` genérico).
+- `auth.py` — OAuth2 client credentials con cache/refresh.
+- `errors.py` — familias tipadas (modelo de error común).
+- `webhooks.py` — verifier HMAC (verify-before-parse, anti-replay, constant-time).
+- `_http.py` — transport stdlib inyectable (para tests).

tilde_afip-0.1.0a1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Tilde
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

tilde_afip-0.1.0a1/PKG-INFO

@@ -0,0 +1,113 @@
+Metadata-Version: 2.4
+Name: tilde-afip
+Version: 0.1.0a1
+Summary: SDK oficial de Tilde para Python — facturación electrónica ARCA (ex AFIP) en Argentina. Server-side.
+Project-URL: Homepage, https://tildeafip.com
+Project-URL: Documentation, https://tildeafip.com/developers
+Project-URL: Repository, https://sistemasat-gustavo.visualstudio.com/Tilde/_git/Tilde
+Author: Tilde
+License: MIT License
+        
+        Copyright (c) 2026 Tilde
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+License-File: LICENSE
+Keywords: afip,arca,argentina,facturacion,invoicing,sdk,tilde
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+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: Typing :: Typed
+Requires-Python: >=3.10
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# tilde-afip
+
+SDK oficial de **Tilde** para Python — facturación electrónica **ARCA (ex AFIP)** en Argentina.
+
+> ⚠️ **Server-side / backend-to-backend.** No uses Client Credentials en código que corra en un cliente no confiable. El `client_secret` nunca debe filtrarse.
+
+> Estado: **alpha** (`0.1.0a1`). API sujeta a cambios hasta `1.0.0`.
+
+## Instalación
+```bash
+pip install tilde-afip
+```
+Requiere **Python 3.10+**. Sin dependencias de runtime (transport sobre la stdlib).
+
+## Quickstart
+```python
+from tilde_afip import TildeClient
+
+tilde = TildeClient(
+    client_id="...",
+    client_secret="...",
+    environment="sandbox",        # "production" por default
+    scopes=["invoicing:write"],
+)
+
+invoice = tilde.invoices.create({ ... }, idempotency_key=my_key)
+print(invoice["cae"])
+```
+El token OAuth2 (client credentials) se obtiene y cachea automáticamente.
+
+## Errores tipados
+```python
+from tilde_afip import TildeValidationError
+
+try:
+    tilde.invoices.create(req, idempotency_key=key)
+except TildeValidationError as e:
+    print(e.code, e.status, e.retryable, e.correlation_id, e.body.get("errors"))
+```
+Familias: `TildeValidationError`, `TildeAuthenticationError`, `TildeAuthorizationError`,
+`TildeRateLimitError`, `TildeConflictError`, `TildeNotFoundError`, `TildePaymentRequiredError`, `TildeApiError`.
+
+## Webhooks
+Verificá con el **raw body**, antes de parsear:
+```python
+from tilde_afip import construct_event
+
+event = construct_event(
+    payload=raw_body,                       # str | bytes, tal cual llegó
+    signature_header=request.headers["X-Tilde-Signature"],
+    secret=webhook_secret,
+)
+if event["type"] == "invoice.authorized":
+    ...
+```
+HMAC-SHA256 en tiempo constante, con anti-replay por timestamp.
+
+## Entornos
+| Entorno | Base URL |
+|---|---|
+| `production` | `https://api.tildeafip.com/v1` |
+| `sandbox` | `https://sandbox.api.tildeafip.com/v1` |
+
+## Acceso genérico
+Cualquier endpoint de la API: `tilde.request("GET", "/cuit-profiles")`. El recurso `invoices`
+está tipado como ejemplo; la cobertura tipada completa se generará del contrato.
+
+## Licencia
+Ver `LICENSE`.

tilde_afip-0.1.0a1/README.md

@@ -0,0 +1,69 @@
+# tilde-afip
+
+SDK oficial de **Tilde** para Python — facturación electrónica **ARCA (ex AFIP)** en Argentina.
+
+> ⚠️ **Server-side / backend-to-backend.** No uses Client Credentials en código que corra en un cliente no confiable. El `client_secret` nunca debe filtrarse.
+
+> Estado: **alpha** (`0.1.0a1`). API sujeta a cambios hasta `1.0.0`.
+
+## Instalación
+```bash
+pip install tilde-afip
+```
+Requiere **Python 3.10+**. Sin dependencias de runtime (transport sobre la stdlib).
+
+## Quickstart
+```python
+from tilde_afip import TildeClient
+
+tilde = TildeClient(
+    client_id="...",
+    client_secret="...",
+    environment="sandbox",        # "production" por default
+    scopes=["invoicing:write"],
+)
+
+invoice = tilde.invoices.create({ ... }, idempotency_key=my_key)
+print(invoice["cae"])
+```
+El token OAuth2 (client credentials) se obtiene y cachea automáticamente.
+
+## Errores tipados
+```python
+from tilde_afip import TildeValidationError
+
+try:
+    tilde.invoices.create(req, idempotency_key=key)
+except TildeValidationError as e:
+    print(e.code, e.status, e.retryable, e.correlation_id, e.body.get("errors"))
+```
+Familias: `TildeValidationError`, `TildeAuthenticationError`, `TildeAuthorizationError`,
+`TildeRateLimitError`, `TildeConflictError`, `TildeNotFoundError`, `TildePaymentRequiredError`, `TildeApiError`.
+
+## Webhooks
+Verificá con el **raw body**, antes de parsear:
+```python
+from tilde_afip import construct_event
+
+event = construct_event(
+    payload=raw_body,                       # str | bytes, tal cual llegó
+    signature_header=request.headers["X-Tilde-Signature"],
+    secret=webhook_secret,
+)
+if event["type"] == "invoice.authorized":
+    ...
+```
+HMAC-SHA256 en tiempo constante, con anti-replay por timestamp.
+
+## Entornos
+| Entorno | Base URL |
+|---|---|
+| `production` | `https://api.tildeafip.com/v1` |
+| `sandbox` | `https://sandbox.api.tildeafip.com/v1` |
+
+## Acceso genérico
+Cualquier endpoint de la API: `tilde.request("GET", "/cuit-profiles")`. El recurso `invoices`
+está tipado como ejemplo; la cobertura tipada completa se generará del contrato.
+
+## Licencia
+Ver `LICENSE`.

tilde_afip-0.1.0a1/examples/issue_invoice.py

@@ -0,0 +1,23 @@
+import os
+import uuid
+
+from tilde_afip import TildeClient, TildeValidationError, construct_event
+
+tilde = TildeClient(
+    client_id=os.environ["TILDE_CLIENT_ID"],
+    client_secret=os.environ["TILDE_CLIENT_SECRET"],
+    environment="sandbox",
+    scopes=["invoicing:write"],
+)
+
+try:
+    invoice = tilde.invoices.create({"...": "campos"}, idempotency_key=str(uuid.uuid4()))
+    print("CAE:", invoice.get("cae"))
+except TildeValidationError as e:
+    print("validación:", e.code, e.body.get("errors"))
+
+
+def on_webhook(raw_body: bytes, signature: str) -> None:
+    event = construct_event(payload=raw_body, signature_header=signature, secret=os.environ["TILDE_WEBHOOK_SECRET"])
+    if event["type"] == "invoice.authorized":
+        print("autorizado:", event["id"])

tilde_afip-0.1.0a1/pyproject.toml

@@ -0,0 +1,38 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "tilde-afip"
+version = "0.1.0a1"
+description = "SDK oficial de Tilde para Python — facturación electrónica ARCA (ex AFIP) en Argentina. Server-side."
+readme = "README.md"
+requires-python = ">=3.10"
+license = { file = "LICENSE" }
+authors = [{ name = "Tilde" }]
+keywords = ["tilde", "arca", "afip", "facturacion", "argentina", "invoicing", "sdk"]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Intended Audience :: Developers",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Typing :: Typed",
+]
+dependencies = []
+
+[project.urls]
+Homepage = "https://tildeafip.com"
+Documentation = "https://tildeafip.com/developers"
+Repository = "https://sistemasat-gustavo.visualstudio.com/Tilde/_git/Tilde"
+
+[project.optional-dependencies]
+dev = ["pytest>=8.0"]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/tilde_afip"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

tilde_afip-0.1.0a1/src/tilde_afip/__init__.py

@@ -0,0 +1,48 @@
+"""SDK oficial de Tilde para Python — facturación electrónica ARCA (ex AFIP). Server-side."""
+from __future__ import annotations
+
+from .auth import ClientCredentialsTokenProvider
+from .client import TildeClient, InvoicesResource, __version__
+from .environment import BASE_URLS, TildeEnvironment, base_url_for
+from .errors import (
+    TildeApiError,
+    TildeAuthenticationError,
+    TildeAuthorizationError,
+    TildeConflictError,
+    TildeError,
+    TildeNotFoundError,
+    TildePaymentRequiredError,
+    TildeRateLimitError,
+    TildeValidationError,
+    error_from_response,
+)
+from .webhooks import (
+    WebhookVerificationError,
+    construct_event,
+    sign,
+    verify_signature,
+)
+
+__all__ = [
+    "TildeClient",
+    "InvoicesResource",
+    "ClientCredentialsTokenProvider",
+    "TildeEnvironment",
+    "BASE_URLS",
+    "base_url_for",
+    "TildeError",
+    "TildeAuthenticationError",
+    "TildeAuthorizationError",
+    "TildeValidationError",
+    "TildeRateLimitError",
+    "TildeConflictError",
+    "TildeNotFoundError",
+    "TildePaymentRequiredError",
+    "TildeApiError",
+    "error_from_response",
+    "verify_signature",
+    "construct_event",
+    "sign",
+    "WebhookVerificationError",
+    "__version__",
+]

tilde_afip-0.1.0a1/src/tilde_afip/_http.py

@@ -0,0 +1,29 @@
+"""Transport HTTP mínimo sobre la stdlib (urllib). Inyectable para tests."""
+from __future__ import annotations
+
+import urllib.error
+import urllib.request
+from dataclasses import dataclass
+from typing import Callable, Mapping, Optional
+
+
+@dataclass
+class HttpResponse:
+    status: int
+    headers: Mapping[str, str]
+    text: str
+
+
+# (method, url, headers, body_bytes) -> HttpResponse
+Transport = Callable[[str, str, Mapping[str, str], Optional[bytes]], HttpResponse]
+
+
+def urllib_transport(method: str, url: str, headers: Mapping[str, str], body: Optional[bytes]) -> HttpResponse:
+    req = urllib.request.Request(url, data=body, method=method)
+    for key, value in headers.items():
+        req.add_header(key, value)
+    try:
+        with urllib.request.urlopen(req) as resp:  # noqa: S310 (urls controladas por el SDK)
+            return HttpResponse(resp.status, dict(resp.headers), resp.read().decode("utf-8"))
+    except urllib.error.HTTPError as exc:
+        return HttpResponse(exc.code, dict(exc.headers), exc.read().decode("utf-8"))

tilde_afip-0.1.0a1/src/tilde_afip/auth.py

@@ -0,0 +1,72 @@
+"""Autenticación OAuth2 Client Credentials con cache + refresh. Server-side only."""
+from __future__ import annotations
+
+import json
+import time
+from typing import Callable, Optional
+from urllib.parse import urlencode
+
+from ._http import HttpResponse, Transport, urllib_transport
+from .errors import TildeAuthenticationError
+
+
+class ClientCredentialsTokenProvider:
+    """Obtiene y cachea el access token (OAuth2 client credentials). Refresca antes de expirar."""
+
+    def __init__(
+        self,
+        *,
+        client_id: str,
+        client_secret: str,
+        token_url: str,
+        scopes: Optional[list[str]] = None,
+        transport: Optional[Transport] = None,
+        now: Optional[Callable[[], float]] = None,
+        refresh_skew_seconds: float = 30.0,
+    ) -> None:
+        self._client_id = client_id
+        self._client_secret = client_secret
+        self._token_url = token_url
+        self._scopes = scopes
+        self._transport: Transport = transport or urllib_transport
+        self._now = now or time.time
+        self._refresh_skew = refresh_skew_seconds
+        self._token: Optional[str] = None
+        self._expires_at: float = 0.0
+
+    def get_token(self) -> str:
+        """Devuelve un access token válido (cacheado si no expiró)."""
+        if self._token is not None and self._now() < self._expires_at - self._refresh_skew:
+            return self._token
+        return self._request_token()
+
+    def invalidate(self) -> None:
+        self._token = None
+
+    def _request_token(self) -> str:
+        form = {
+            "grant_type": "client_credentials",
+            "client_id": self._client_id,
+            "client_secret": self._client_secret,
+        }
+        if self._scopes:
+            form["scope"] = " ".join(self._scopes)
+        body = urlencode(form).encode("utf-8")
+        headers = {
+            "content-type": "application/x-www-form-urlencoded",
+            "accept": "application/json",
+        }
+        resp: HttpResponse = self._transport("POST", self._token_url, headers, body)
+        if resp.status < 200 or resp.status >= 300:
+            desc = f"token endpoint respondió {resp.status}"
+            try:
+                payload = json.loads(resp.text)
+                desc = payload.get("error_description") or payload.get("error") or desc
+            except (ValueError, AttributeError):
+                pass
+            raise TildeAuthenticationError(desc, status=resp.status, code="token_request_failed")
+
+        payload = json.loads(resp.text)
+        self._token = payload["access_token"]
+        self._expires_at = self._now() + float(payload["expires_in"])
+        return self._token

tilde_afip-0.1.0a1/src/tilde_afip/client.py

@@ -0,0 +1,120 @@
+"""Cliente oficial de Tilde para Python (server-side).
+
+**No usar en frontend**: el client_secret nunca debe ejecutarse client-side.
+"""
+from __future__ import annotations
+
+import json
+from typing import Any, Optional
+from urllib.parse import urlencode
+
+from ._http import Transport, urllib_transport
+from .auth import ClientCredentialsTokenProvider
+from .environment import base_url_for
+from .errors import error_from_response
+
+__version__ = "0.1.0a1"
+
+
+class TildeClient:
+    """Cliente de la API de Tilde. Maneja OAuth2 (token cache/refresh), idempotencia,
+    correlación y mapeo de errores tipados.
+
+    Ejemplo::
+
+        tilde = TildeClient(client_id=..., client_secret=..., environment="sandbox")
+        invoice = tilde.invoices.create(request, idempotency_key=key)
+    """
+
+    def __init__(
+        self,
+        *,
+        client_id: str,
+        client_secret: str,
+        environment: str = "production",
+        scopes: Optional[list[str]] = None,
+        base_url: Optional[str] = None,
+        transport: Optional[Transport] = None,
+    ) -> None:
+        self._base_url = (base_url or base_url_for(environment)).rstrip("/")
+        self._transport: Transport = transport or urllib_transport
+        self.tokens = ClientCredentialsTokenProvider(
+            client_id=client_id,
+            client_secret=client_secret,
+            token_url=f"{self._base_url}/oauth2/token",
+            scopes=scopes,
+            transport=self._transport,
+        )
+        self.invoices = InvoicesResource(self)
+
+    def request(
+        self,
+        method: str,
+        path: str,
+        *,
+        body: Any = None,
+        query: Optional[dict[str, Any]] = None,
+        idempotency_key: Optional[str] = None,
+        correlation_id: Optional[str] = None,
+    ) -> Any:
+        """Request genérico autenticado. Devuelve el JSON parseado (o None en 204)."""
+        url = self._base_url + path
+        if query:
+            clean = {k: v for k, v in query.items() if v is not None}
+            if clean:
+                url = f"{url}?{urlencode(clean)}"
+
+        headers = {
+            "authorization": f"Bearer {self.tokens.get_token()}",
+            "accept": "application/json",
+            "user-agent": f"tilde-sdk-python/{__version__}",
+        }
+        if idempotency_key:
+            headers["idempotency-key"] = idempotency_key
+        if correlation_id:
+            headers["x-correlation-id"] = correlation_id
+
+        payload: Optional[bytes] = None
+        if body is not None:
+            headers["content-type"] = "application/json"
+            payload = json.dumps(body).encode("utf-8")
+
+        resp = self._transport(method, url, headers, payload)
+        corr = resp.headers.get("x-correlation-id") or correlation_id
+
+        if resp.status < 200 or resp.status >= 300:
+            err_body: Optional[dict[str, Any]] = None
+            try:
+                err_body = json.loads(resp.text)
+            except ValueError:
+                pass
+            raise error_from_response(resp.status, err_body, corr)
+
+        if resp.status == 204 or not resp.text:
+            return None
+        return json.loads(resp.text)
+
+
+class InvoicesResource:
+    """Recurso de comprobantes."""
+
+    def __init__(self, client: TildeClient) -> None:
+        self._client = client
+
+    def create(self, request: dict[str, Any], *, idempotency_key: str, correlation_id: Optional[str] = None) -> dict[str, Any]:
+        """Emite un comprobante. Requiere ``idempotency_key``."""
+        return self._client.request(
+            "POST", "/invoices", body=request, idempotency_key=idempotency_key, correlation_id=correlation_id
+        )
+
+    def get(self, invoice_id: str) -> dict[str, Any]:
+        return self._client.request("GET", f"/invoices/{invoice_id}")
+
+    def list(self, *, skip: int = 0, take: int = 50) -> dict[str, Any]:
+        return self._client.request("GET", "/invoices", query={"skip": skip, "take": take})
+
+    def void(self, invoice_id: str, *, idempotency_key: str, correlation_id: Optional[str] = None) -> dict[str, Any]:
+        """Anula un comprobante (emite la nota de crédito). Requiere ``idempotency_key``."""
+        return self._client.request(
+            "POST", f"/invoices/{invoice_id}/void", idempotency_key=idempotency_key, correlation_id=correlation_id
+        )

tilde_afip-0.1.0a1/src/tilde_afip/environment.py

@@ -0,0 +1,18 @@
+"""Entornos de la API de Tilde."""
+from __future__ import annotations
+
+from typing import Literal
+
+TildeEnvironment = Literal["production", "sandbox"]
+
+BASE_URLS: dict[str, str] = {
+    "production": "https://api.tildeafip.com/v1",
+    "sandbox": "https://sandbox.api.tildeafip.com/v1",
+}
+
+
+def base_url_for(environment: str) -> str:
+    try:
+        return BASE_URLS[environment]
+    except KeyError as exc:
+        raise ValueError(f"Entorno desconocido: {environment!r}") from exc

tilde_afip-0.1.0a1/src/tilde_afip/errors.py

@@ -0,0 +1,88 @@
+"""Errores tipados del SDK, sobre el modelo de error común de Tilde (super-set RFC7807)."""
+from __future__ import annotations
+
+from typing import Any
+
+
+class TildeError(Exception):
+    """Error base del SDK. Todas las familias derivan de acá."""
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        status: int,
+        code: str,
+        retryable: bool = False,
+        correlation_id: str | None = None,
+        body: dict[str, Any] | None = None,
+    ) -> None:
+        super().__init__(message)
+        self.status = status
+        self.code = code
+        self.retryable = retryable
+        self.correlation_id = correlation_id
+        self.body = body
+
+
+class TildeAuthenticationError(TildeError):
+    """401 — credenciales/token inválidos."""
+
+
+class TildeAuthorizationError(TildeError):
+    """403 — sin permiso/scope."""
+
+
+class TildeValidationError(TildeError):
+    """400/422 — request inválido."""
+
+
+class TildeRateLimitError(TildeError):
+    """429 — rate limit."""
+
+
+class TildeConflictError(TildeError):
+    """409 — conflicto (p.ej. idempotencia)."""
+
+
+class TildeNotFoundError(TildeError):
+    """404 — recurso inexistente."""
+
+
+class TildePaymentRequiredError(TildeError):
+    """402 — suscripción inactiva."""
+
+
+class TildeApiError(TildeError):
+    """5xx u otros."""
+
+
+_STATUS_MAP: dict[int, type[TildeError]] = {
+    400: TildeValidationError,
+    401: TildeAuthenticationError,
+    402: TildePaymentRequiredError,
+    403: TildeAuthorizationError,
+    404: TildeNotFoundError,
+    409: TildeConflictError,
+    422: TildeValidationError,
+    429: TildeRateLimitError,
+}
+
+
+def error_from_response(
+    status: int, body: dict[str, Any] | None, correlation_id: str | None = None
+) -> TildeError:
+    """Construye el error tipado a partir del status + body común + header de correlación."""
+    body = body or {}
+    code = body.get("code") or body.get("error") or f"http_{status}"
+    detail = body.get("detail") or body.get("message") or body.get("title") or f"HTTP {status}"
+    retryable = body.get("retryable", status == 429 or status >= 500)
+    cls = _STATUS_MAP.get(status, TildeApiError)
+    return cls(
+        detail,
+        status=status,
+        code=code,
+        retryable=bool(retryable),
+        correlation_id=correlation_id,
+        body={"status": status, "code": code, "retryable": retryable, **body},
+    )

tilde_afip-0.1.0a1/src/tilde_afip/webhooks.py

@@ -0,0 +1,87 @@
+"""Verificación de webhooks de Tilde (HMAC-SHA256, estilo Stripe).
+
+Se firma ``"{timestamp}.{raw_body}"`` con el secreto de la suscripción. Verificá SIEMPRE con el
+**raw body** ANTES de parsear, en tiempo constante, y rechazá timestamps fuera de tolerancia.
+"""
+from __future__ import annotations
+
+import hashlib
+import hmac
+import json
+import time
+from typing import Any
+
+SIGNATURE_HEADER = "X-Tilde-Signature"
+TIMESTAMP_HEADER = "X-Tilde-Timestamp"
+EVENT_HEADER = "X-Tilde-Event"
+EVENT_ID_HEADER = "X-Tilde-Event-Id"
+
+
+class WebhookVerificationError(Exception):
+    """La firma del webhook es inválida, está fuera de tolerancia o el header es malformado."""
+
+
+def sign(secret: str, timestamp_seconds: int, body: str) -> str:
+    """Firma hex (v1) de ``"{timestamp}.{body}"``."""
+    msg = f"{timestamp_seconds}.{body}".encode("utf-8")
+    return hmac.new(secret.encode("utf-8"), msg, hashlib.sha256).hexdigest()
+
+
+def _parse_signature_header(header: str) -> tuple[int, str]:
+    t: int | None = None
+    v1: str | None = None
+    for part in header.split(","):
+        key, _, value = part.partition("=")
+        key = key.strip()
+        value = value.strip()
+        if key == "t":
+            try:
+                t = int(value)
+            except ValueError:
+                t = None
+        elif key == "v1":
+            v1 = value
+    if t is None or not v1:
+        raise WebhookVerificationError("Header de firma malformado (se esperaba t=...,v1=...).")
+    return t, v1
+
+
+def verify_signature(
+    *,
+    payload: str | bytes,
+    signature_header: str,
+    secret: str,
+    tolerance_seconds: int = 300,
+    now_seconds: int | None = None,
+) -> None:
+    """Verifica la firma. Lanza :class:`WebhookVerificationError` si es inválida. No parsea el body."""
+    body = payload.decode("utf-8") if isinstance(payload, bytes) else payload
+    now = int(time.time()) if now_seconds is None else now_seconds
+    t, v1 = _parse_signature_header(signature_header)
+
+    if abs(now - t) > tolerance_seconds:
+        raise WebhookVerificationError("Timestamp fuera de tolerancia (posible replay).")
+
+    expected = sign(secret, t, body)
+    if not hmac.compare_digest(expected, v1):
+        raise WebhookVerificationError("Firma inválida.")
+
+
+def construct_event(
+    *,
+    payload: str | bytes,
+    signature_header: str,
+    secret: str,
+    tolerance_seconds: int = 300,
+    now_seconds: int | None = None,
+) -> dict[str, Any]:
+    """Verifica la firma y, sólo si es válida, parsea y devuelve el evento."""
+    verify_signature(
+        payload=payload,
+        signature_header=signature_header,
+        secret=secret,
+        tolerance_seconds=tolerance_seconds,
+        now_seconds=now_seconds,
+    )
+    body = payload.decode("utf-8") if isinstance(payload, bytes) else payload
+    return json.loads(body)

tilde_afip-0.1.0a1/tests/test_auth_and_errors.py

@@ -0,0 +1,78 @@
+import pytest
+
+from tilde_afip import (
+    ClientCredentialsTokenProvider,
+    TildeApiError,
+    TildeAuthenticationError,
+    TildeRateLimitError,
+    TildeValidationError,
+    error_from_response,
+)
+from tilde_afip._http import HttpResponse
+
+
+def make_transport(responses):
+    """Transport falso: devuelve respuestas de una lista, registrando llamadas."""
+    calls = []
+
+    def transport(method, url, headers, body):
+        calls.append({"method": method, "url": url, "headers": dict(headers), "body": body})
+        return responses[len(calls) - 1]
+
+    transport.calls = calls  # type: ignore[attr-defined]
+    return transport
+
+
+def token_response(tok="tok-1", expires_in=3600):
+    return HttpResponse(200, {}, f'{{"access_token":"{tok}","token_type":"Bearer","expires_in":{expires_in}}}')
+
+
+BASE = dict(client_id="cid", client_secret="secret", token_url="https://api.tildeafip.com/v1/oauth2/token")
+
+
+def test_token_cached_until_expiry():
+    t = make_transport([token_response("tok-1")])
+    clock = {"now": 0.0}
+    p = ClientCredentialsTokenProvider(**BASE, transport=t, now=lambda: clock["now"])
+    assert p.get_token() == "tok-1"
+    assert p.get_token() == "tok-1"
+    assert len(t.calls) == 1  # type: ignore[attr-defined]
+
+
+def test_token_refreshes_after_expiry():
+    t = make_transport([token_response("tok-1", 3600), token_response("tok-2", 3600)])
+    clock = {"now": 0.0}
+    p = ClientCredentialsTokenProvider(**BASE, transport=t, now=lambda: clock["now"])
+    assert p.get_token() == "tok-1"
+    clock["now"] = 3600.0
+    assert p.get_token() == "tok-2"
+    assert len(t.calls) == 2  # type: ignore[attr-defined]
+
+
+def test_token_sends_grant_and_scope():
+    t = make_transport([token_response()])
+    p = ClientCredentialsTokenProvider(**BASE, scopes=["invoicing:write"], transport=t, now=lambda: 0.0)
+    p.get_token()
+    body = t.calls[0]["body"].decode()  # type: ignore[attr-defined]
+    assert "grant_type=client_credentials" in body
+    assert "scope=invoicing%3Awrite" in body
+
+
+def test_token_error_raises_auth():
+    t = make_transport([HttpResponse(401, {}, '{"error":"invalid_client"}')])
+    p = ClientCredentialsTokenProvider(**BASE, transport=t, now=lambda: 0.0)
+    with pytest.raises(TildeAuthenticationError):
+        p.get_token()
+
+
+def test_error_mapping():
+    assert isinstance(error_from_response(422, {"code": "x"}), TildeValidationError)
+    assert isinstance(error_from_response(429, None), TildeRateLimitError)
+    assert error_from_response(429, None).retryable is True
+    assert isinstance(error_from_response(503, None), TildeApiError)
+
+
+def test_error_legacy_shape():
+    e = error_from_response(404, {"error": "not_found", "message": "no existe"})
+    assert e.code == "not_found"
+    assert str(e) == "no existe"

tilde_afip-0.1.0a1/tests/test_contract.py

@@ -0,0 +1,38 @@
+"""CT-1 — Contract test contra el golden fixture compartido por los 4 SDKs."""
+import json
+import os
+
+import pytest
+
+from tilde_afip import construct_event, sign, verify_signature
+from tilde_afip.webhooks import WebhookVerificationError
+
+FIXTURE = json.load(
+    open(os.path.join(os.path.dirname(__file__), "..", "..", "..", "sdk-tests", "fixtures", "webhook-signature.json"))
+)
+
+
+def test_sign_matches_golden():
+    assert sign(FIXTURE["secret"], FIXTURE["timestamp"], FIXTURE["body"]) == FIXTURE["expectedSignature"]
+
+
+def test_accepts_valid():
+    verify_signature(
+        payload=FIXTURE["body"],
+        signature_header=FIXTURE["signatureHeader"],
+        secret=FIXTURE["secret"],
+        now_seconds=FIXTURE["timestamp"] + 5,
+    )
+
+
+def test_rejects_tampered_and_old():
+    with pytest.raises(WebhookVerificationError):
+        verify_signature(payload=FIXTURE["body"] + " ", signature_header=FIXTURE["signatureHeader"], secret=FIXTURE["secret"], now_seconds=FIXTURE["timestamp"])
+    with pytest.raises(WebhookVerificationError):
+        verify_signature(payload=FIXTURE["body"], signature_header=FIXTURE["signatureHeader"], secret=FIXTURE["secret"], now_seconds=FIXTURE["timestamp"] + 10_000)
+
+
+def test_construct_event():
+    evt = construct_event(payload=FIXTURE["body"], signature_header=FIXTURE["signatureHeader"], secret=FIXTURE["secret"], now_seconds=FIXTURE["timestamp"])
+    assert evt["type"] == "invoice.authorized"
+    assert evt["data"]["cae"] == "75123456789013"

tilde_afip-0.1.0a1/tests/test_webhooks.py

@@ -0,0 +1,46 @@
+import pytest
+
+from tilde_afip import construct_event, sign, verify_signature
+from tilde_afip.webhooks import WebhookVerificationError
+
+SECRET = "whsec_test"
+BODY = '{"id":"evt_1","type":"invoice.authorized","createdAt":"2026-06-17T00:00:00Z","data":{"cae":"123"}}'
+T = 1_718_900_000
+
+
+def header(t: int, body: str) -> str:
+    return f"t={t},v1={sign(SECRET, t, body)}"
+
+
+def test_accepts_valid_signature():
+    verify_signature(payload=BODY, signature_header=header(T, BODY), secret=SECRET, now_seconds=T + 5)
+
+
+def test_rejects_tampered_body():
+    with pytest.raises(WebhookVerificationError):
+        verify_signature(payload=BODY + " ", signature_header=header(T, BODY), secret=SECRET, now_seconds=T)
+
+
+def test_rejects_wrong_secret():
+    with pytest.raises(WebhookVerificationError, match="inválida"):
+        verify_signature(payload=BODY, signature_header=header(T, BODY), secret="otro", now_seconds=T)
+
+
+def test_rejects_old_timestamp():
+    with pytest.raises(WebhookVerificationError, match="replay"):
+        verify_signature(payload=BODY, signature_header=header(T, BODY), secret=SECRET, now_seconds=T + 10_000)
+
+
+def test_rejects_malformed_header():
+    with pytest.raises(WebhookVerificationError, match="malformado"):
+        verify_signature(payload=BODY, signature_header="garbage", secret=SECRET, now_seconds=T)
+
+
+def test_accepts_bytes_payload():
+    verify_signature(payload=BODY.encode(), signature_header=header(T, BODY), secret=SECRET, now_seconds=T)
+
+
+def test_construct_event_returns_parsed():
+    evt = construct_event(payload=BODY, signature_header=header(T, BODY), secret=SECRET, now_seconds=T)
+    assert evt["type"] == "invoice.authorized"
+    assert evt["data"]["cae"] == "123"