facturalo-pe 1.0.0__tar.gz

facturalo_pe-1.0.0/.gitignore

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

facturalo_pe-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Consultia Digital S.A.C. (Facturalo)
+
+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.

facturalo_pe-1.0.0/PKG-INFO

@@ -0,0 +1,130 @@
+Metadata-Version: 2.5
+Name: facturalo-pe
+Version: 1.0.0
+Summary: SDK oficial de Facturalo para Python: emite facturas, boletas, notas y guías de remisión ante SUNAT, consulta RUC/DNI, idempotencia y verifica webhooks.
+Project-URL: Homepage, https://www.facturalo.pe
+Project-URL: Documentation, https://docs.facturalo.pe
+Project-URL: Source, https://github.com/facturalo-pe/facturalo-python
+Project-URL: Issues, https://github.com/facturalo-pe/facturalo-python/issues
+Author-email: Facturalo <contacto@facturalo.pe>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: boleta,factura,facturacion electronica,facturalo,guia de remision,peru,sunat
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Developers
+Classifier: Natural Language :: Spanish
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Office/Business :: Financial :: Accounting
+Classifier: Typing :: Typed
+Requires-Python: >=3.9
+Requires-Dist: httpx<1,>=0.25
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# Facturalo para Python
+
+SDK oficial de [Facturalo](https://www.facturalo.pe) para Python: emite facturas, boletas, notas de crédito y débito y guías de remisión ante SUNAT, consulta RUC, DNI y tipo de cambio, trabaja el SIRE y verifica los webhooks. Cliente delgado sobre la [API REST v3](https://docs.facturalo.pe), con la misma superficie que los SDKs de [Node.js](https://www.npmjs.com/package/@facturalo-pe/node) y [PHP](https://packagist.org/packages/facturalo-pe/facturalo-php).
+
+```bash
+pip install facturalo-pe
+```
+
+Requiere Python 3.9 o superior.
+
+## Tu primera factura
+
+```python
+import os
+from facturalo import FacturaloClient
+
+facturalo = FacturaloClient(os.environ["FACTURALO_TOKEN"])  # sk_test_... (demo) o sk_live_...
+
+envio = facturalo.documentos.enviar(
+    {
+        "sunatTransaccion": "0101",
+        "tipoComprobante": "01",
+        "serie": "F001",
+        "correlativo": "1",
+        "fechaEmision": "2026-11-03",
+        "moneda": "PEN",
+        "formaPago": "CONTADO",
+        "cliente": {
+            "tipoDocumento": "6",
+            "numeroDocumento": "20000000001",
+            "denominacion": "EMPRESA S.A.C.",
+            "direccion": "AV. LIMA 123 - LIMA - LIMA - LIMA",
+        },
+        "items": [
+            {"unidadMedida": "NIU", "descripcion": "SERVICIO DE CONSULTORÍA", "cantidad": 1, "precioUnitario": 118, "tipoIgv": "10"},
+        ],
+    },
+    idempotency_key="pedido-1001",
+)
+
+print(envio["estado"])            # ACEPTADA o RECHAZADA
+print(envio["enlaces"]["pdf"])    # PDF A4; también pdfTicket, xml y cdr
+```
+
+El token decide el entorno: `sk_test_` envía a SUNAT Beta (demo) y `sk_live_` a producción. Un rechazo de SUNAT no es una excepción: vuelve con `estado == "RECHAZADA"` y el motivo en `envio["sunat"]`.
+
+## Recursos
+
+| Cliente | Token | Recursos |
+|---|---|---|
+| `FacturaloClient` | `sk_test_...` / `sk_live_...` | `documentos` (enviar, generar_xml, consultar, buscar, listar, anular, reenviar, eventos, eliminar, url_archivo, descargar), `guias` (enviar, consultar, consultar_ticket, eventos, listar, descargar), `consultas` (ruc, dni, tipo_cambio, placa, soat, licencia…), `webhooks` (listar, reenviar), `sire.ventas` / `sire.compras` |
+| `FacturaloCuentaClient` | `user_sk_...` | `empresas` (listar, obtener, verificar_ruc, crear, actualizar, webhook, regenerar_token…), `establecimientos`, `consultas` |
+
+```python
+facturalo.consultas.ruc("20100006538")
+facturalo.consultas.tipo_cambio("2026-10-30")
+facturalo.documentos.anular("01", "F001", "1", motivo="Error en los datos del cliente")
+pdf = facturalo.documentos.descargar(envio["documento"]["id"], "pdf")  # bytes
+```
+
+## Errores
+
+Todas heredan de `FacturaloError`. Los errores HTTP son `FacturaloApiError` con `status`, `errors` y `body`:
+
+| Excepción | Cuándo |
+|---|---|
+| `FacturaloValidationError` | 400 / 422: datos inválidos (revisa `e.errors`) |
+| `FacturaloAuthenticationError` | 401: token inválido o revocado |
+| `FacturaloPermissionError` | 403 |
+| `FacturaloNotFoundError` | 404 |
+| `FacturaloRateLimitError` | 429 |
+| `FacturaloConnectionError` | Red, DNS o timeout |
+
+## Reintentos e idempotencia
+
+- Timeout por defecto de 90 s: el envío síncrono espera la respuesta de SUNAT.
+- Los `GET` se reintentan ante 429, 502, 503, 504 o fallos de conexión.
+- Los envíos solo se reintentan si llevan `idempotency_key`: el servidor deduplica y nunca se emite dos veces el mismo comprobante.
+
+## Webhooks
+
+```python
+from facturalo import construir_evento, FacturaloSignatureVerificationError
+
+# Django: request.body · Flask: request.get_data() · FastAPI: await request.body()
+try:
+    evento = construir_evento(cuerpo_crudo, request.headers.get("X-Facturalo-Firma"), os.environ["FACTURALO_WEBHOOK_SECRET"])
+except FacturaloSignatureVerificationError:
+    ...  # responde 400
+
+if evento["evento"] == "documento.sunat.respuesta":
+    ...
+```
+
+La firma es `HMAC-SHA256(secret, cuerpo crudo)` en hexadecimal y se compara en tiempo constante.
+
+## Desarrollo
+
+```bash
+python -m venv .venv && . .venv/bin/activate
+pip install -e ".[dev]"
+pytest
+```
+
+Documentación completa: [docs.facturalo.pe](https://docs.facturalo.pe). Licencia MIT · © Consultia Digital S.A.C. (Facturalo).

facturalo_pe-1.0.0/README.md

@@ -0,0 +1,105 @@
+# Facturalo para Python
+
+SDK oficial de [Facturalo](https://www.facturalo.pe) para Python: emite facturas, boletas, notas de crédito y débito y guías de remisión ante SUNAT, consulta RUC, DNI y tipo de cambio, trabaja el SIRE y verifica los webhooks. Cliente delgado sobre la [API REST v3](https://docs.facturalo.pe), con la misma superficie que los SDKs de [Node.js](https://www.npmjs.com/package/@facturalo-pe/node) y [PHP](https://packagist.org/packages/facturalo-pe/facturalo-php).
+
+```bash
+pip install facturalo-pe
+```
+
+Requiere Python 3.9 o superior.
+
+## Tu primera factura
+
+```python
+import os
+from facturalo import FacturaloClient
+
+facturalo = FacturaloClient(os.environ["FACTURALO_TOKEN"])  # sk_test_... (demo) o sk_live_...
+
+envio = facturalo.documentos.enviar(
+    {
+        "sunatTransaccion": "0101",
+        "tipoComprobante": "01",
+        "serie": "F001",
+        "correlativo": "1",
+        "fechaEmision": "2026-11-03",
+        "moneda": "PEN",
+        "formaPago": "CONTADO",
+        "cliente": {
+            "tipoDocumento": "6",
+            "numeroDocumento": "20000000001",
+            "denominacion": "EMPRESA S.A.C.",
+            "direccion": "AV. LIMA 123 - LIMA - LIMA - LIMA",
+        },
+        "items": [
+            {"unidadMedida": "NIU", "descripcion": "SERVICIO DE CONSULTORÍA", "cantidad": 1, "precioUnitario": 118, "tipoIgv": "10"},
+        ],
+    },
+    idempotency_key="pedido-1001",
+)
+
+print(envio["estado"])            # ACEPTADA o RECHAZADA
+print(envio["enlaces"]["pdf"])    # PDF A4; también pdfTicket, xml y cdr
+```
+
+El token decide el entorno: `sk_test_` envía a SUNAT Beta (demo) y `sk_live_` a producción. Un rechazo de SUNAT no es una excepción: vuelve con `estado == "RECHAZADA"` y el motivo en `envio["sunat"]`.
+
+## Recursos
+
+| Cliente | Token | Recursos |
+|---|---|---|
+| `FacturaloClient` | `sk_test_...` / `sk_live_...` | `documentos` (enviar, generar_xml, consultar, buscar, listar, anular, reenviar, eventos, eliminar, url_archivo, descargar), `guias` (enviar, consultar, consultar_ticket, eventos, listar, descargar), `consultas` (ruc, dni, tipo_cambio, placa, soat, licencia…), `webhooks` (listar, reenviar), `sire.ventas` / `sire.compras` |
+| `FacturaloCuentaClient` | `user_sk_...` | `empresas` (listar, obtener, verificar_ruc, crear, actualizar, webhook, regenerar_token…), `establecimientos`, `consultas` |
+
+```python
+facturalo.consultas.ruc("20100006538")
+facturalo.consultas.tipo_cambio("2026-10-30")
+facturalo.documentos.anular("01", "F001", "1", motivo="Error en los datos del cliente")
+pdf = facturalo.documentos.descargar(envio["documento"]["id"], "pdf")  # bytes
+```
+
+## Errores
+
+Todas heredan de `FacturaloError`. Los errores HTTP son `FacturaloApiError` con `status`, `errors` y `body`:
+
+| Excepción | Cuándo |
+|---|---|
+| `FacturaloValidationError` | 400 / 422: datos inválidos (revisa `e.errors`) |
+| `FacturaloAuthenticationError` | 401: token inválido o revocado |
+| `FacturaloPermissionError` | 403 |
+| `FacturaloNotFoundError` | 404 |
+| `FacturaloRateLimitError` | 429 |
+| `FacturaloConnectionError` | Red, DNS o timeout |
+
+## Reintentos e idempotencia
+
+- Timeout por defecto de 90 s: el envío síncrono espera la respuesta de SUNAT.
+- Los `GET` se reintentan ante 429, 502, 503, 504 o fallos de conexión.
+- Los envíos solo se reintentan si llevan `idempotency_key`: el servidor deduplica y nunca se emite dos veces el mismo comprobante.
+
+## Webhooks
+
+```python
+from facturalo import construir_evento, FacturaloSignatureVerificationError
+
+# Django: request.body · Flask: request.get_data() · FastAPI: await request.body()
+try:
+    evento = construir_evento(cuerpo_crudo, request.headers.get("X-Facturalo-Firma"), os.environ["FACTURALO_WEBHOOK_SECRET"])
+except FacturaloSignatureVerificationError:
+    ...  # responde 400
+
+if evento["evento"] == "documento.sunat.respuesta":
+    ...
+```
+
+La firma es `HMAC-SHA256(secret, cuerpo crudo)` en hexadecimal y se compara en tiempo constante.
+
+## Desarrollo
+
+```bash
+python -m venv .venv && . .venv/bin/activate
+pip install -e ".[dev]"
+pytest
+```
+
+Documentación completa: [docs.facturalo.pe](https://docs.facturalo.pe). Licencia MIT · © Consultia Digital S.A.C. (Facturalo).

facturalo_pe-1.0.0/pyproject.toml

@@ -0,0 +1,39 @@
+[build-system]
+requires = ["hatchling>=1.24"]
+build-backend = "hatchling.build"
+
+[project]
+name = "facturalo-pe"
+version = "1.0.0"
+description = "SDK oficial de Facturalo para Python: emite facturas, boletas, notas y guías de remisión ante SUNAT, consulta RUC/DNI, idempotencia y verifica webhooks."
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+requires-python = ">=3.9"
+authors = [{ name = "Facturalo", email = "contacto@facturalo.pe" }]
+keywords = ["facturalo", "sunat", "facturacion electronica", "factura", "boleta", "guia de remision", "peru"]
+classifiers = [
+  "Development Status :: 5 - Production/Stable",
+  "Intended Audience :: Developers",
+  "Natural Language :: Spanish",
+  "Operating System :: OS Independent",
+  "Programming Language :: Python :: 3",
+  "Topic :: Office/Business :: Financial :: Accounting",
+  "Typing :: Typed",
+]
+dependencies = ["httpx>=0.25,<1"]
+
+[project.optional-dependencies]
+dev = ["pytest>=8"]
+
+[project.urls]
+Homepage = "https://www.facturalo.pe"
+Documentation = "https://docs.facturalo.pe"
+Source = "https://github.com/facturalo-pe/facturalo-python"
+Issues = "https://github.com/facturalo-pe/facturalo-python/issues"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/facturalo"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

facturalo_pe-1.0.0/src/facturalo/__init__.py

@@ -0,0 +1,39 @@
+"""SDK oficial de Facturalo para Python: facturación electrónica SUNAT por API.
+
+    from facturalo import FacturaloClient
+
+    facturalo = FacturaloClient(os.environ["FACTURALO_TOKEN"])
+    envio = facturalo.documentos.enviar(documento, idempotency_key="pedido-1001")
+"""
+
+from .client import FacturaloClient, FacturaloCuentaClient
+from .errors import (
+    FacturaloApiError,
+    FacturaloAuthenticationError,
+    FacturaloConnectionError,
+    FacturaloError,
+    FacturaloNotFoundError,
+    FacturaloPermissionError,
+    FacturaloRateLimitError,
+    FacturaloSignatureVerificationError,
+    FacturaloValidationError,
+)
+from .webhook import construir_evento, verificar_firma
+
+__version__ = "1.0.0"
+
+__all__ = [
+    "FacturaloClient",
+    "FacturaloCuentaClient",
+    "FacturaloError",
+    "FacturaloApiError",
+    "FacturaloAuthenticationError",
+    "FacturaloConnectionError",
+    "FacturaloNotFoundError",
+    "FacturaloPermissionError",
+    "FacturaloRateLimitError",
+    "FacturaloSignatureVerificationError",
+    "FacturaloValidationError",
+    "construir_evento",
+    "verificar_firma",
+]

facturalo_pe-1.0.0/src/facturalo/_http.py

@@ -0,0 +1,127 @@
+"""Transporte HTTP compartido por FacturaloClient y FacturaloCuentaClient. Uso interno."""
+
+from __future__ import annotations
+
+import time
+from typing import Any, Dict, Mapping, Optional
+
+import httpx
+
+from .errors import FacturaloApiError, FacturaloConnectionError
+
+DEFAULT_BASE_URL = "https://api.facturalo.pe/api/v3"
+#: El envío síncrono espera la respuesta de SUNAT: puede tardar varios segundos.
+DEFAULT_TIMEOUT_SECONDS = 90.0
+_MAX_RETRIES = 2
+_RETRYABLE_STATUS = {429, 502, 503, 504}
+
+Json = Dict[str, Any]
+
+
+class HttpClient:
+    def __init__(
+        self,
+        token: str,
+        base_url: Optional[str] = None,
+        http_client: Optional[httpx.Client] = None,
+        timeout: float = DEFAULT_TIMEOUT_SECONDS,
+    ) -> None:
+        self._token = token
+        self._base_url = (base_url or DEFAULT_BASE_URL).rstrip("/")
+        self._http = http_client or httpx.Client(timeout=timeout)
+        self._timeout = timeout
+
+    def request(
+        self,
+        method: str,
+        path: str,
+        body: Optional[Json] = None,
+        query: Optional[Mapping[str, Any]] = None,
+        headers: Optional[Mapping[str, str]] = None,
+    ) -> Any:
+        """Devuelve `data` del sobre `{ success, message, data }`: un dict, o una lista en los listados."""
+        envelope = self._send(method, path, body, query or {}, dict(headers or {}))
+        data = envelope.get("data")
+        return data if isinstance(data, (dict, list)) else {}
+
+    def file_url(self, path: str) -> str:
+        return self._base_url + path
+
+    def download(self, url: str) -> bytes:
+        """Descarga binaria (PDF, XML, CDR). Las URLs de archivos son públicas: no envía el token."""
+        try:
+            response = self._http.get(url, timeout=self._timeout)
+        except httpx.HTTPError as e:
+            raise FacturaloConnectionError("No se pudo conectar con la API de Facturalo.") from e
+        if not 200 <= response.status_code < 300:
+            raise FacturaloApiError.for_status(response.status_code, f"No se pudo descargar {url}")
+        return response.content
+
+    def _send(
+        self,
+        method: str,
+        path: str,
+        body: Optional[Json],
+        query: Mapping[str, Any],
+        extra_headers: Dict[str, str],
+    ) -> Json:
+        headers = {
+            # Facturalo no usa el esquema Bearer: el token va tal cual.
+            "Authorization": self._token,
+            "Accept": "application/json",
+            **extra_headers,
+        }
+        params = {
+            k: ("true" if v else "false") if isinstance(v, bool) else v
+            for k, v in query.items()
+            if v is not None and v != ""
+        }
+
+        # GET siempre. POST solo con Idempotency-Key (el servidor deduplica): nunca se emite dos veces.
+        can_retry = method == "GET" or "Idempotency-Key" in extra_headers
+        attempts = _MAX_RETRIES + 1 if can_retry else 1
+
+        last_error: Optional[Exception] = None
+        for attempt in range(attempts):
+            if attempt > 0:
+                time.sleep((2**attempt) * 0.2)
+            try:
+                response = self._http.request(
+                    method,
+                    self._base_url + path,
+                    json=body,
+                    params=params or None,
+                    headers=headers,
+                    timeout=self._timeout,
+                )
+            except (httpx.ConnectError, httpx.ConnectTimeout) as e:
+                last_error = FacturaloConnectionError("No se pudo conectar con la API de Facturalo.")
+                last_error.__cause__ = e
+                if can_retry:
+                    continue
+                raise last_error from e
+            except httpx.HTTPError as e:
+                raise FacturaloConnectionError("No se pudo conectar con la API de Facturalo.") from e
+
+            try:
+                decoded = response.json()
+            except ValueError:
+                decoded = {}
+            if not isinstance(decoded, dict):
+                decoded = {}
+
+            if 200 <= response.status_code < 300:
+                return decoded
+
+            message = decoded.get("message") if isinstance(decoded.get("message"), str) else response.reason_phrase
+            errors = decoded.get("errors") if isinstance(decoded.get("errors"), dict) else {}
+            error = FacturaloApiError.for_status(response.status_code, message, errors, decoded or None)
+            if can_retry and response.status_code in _RETRYABLE_STATUS and attempt < _MAX_RETRIES:
+                last_error = error
+                continue
+            raise error
+
+        raise last_error or FacturaloConnectionError("No se pudo conectar con la API de Facturalo.")
+
+    def close(self) -> None:
+        self._http.close()

facturalo_pe-1.0.0/src/facturalo/client.py

@@ -0,0 +1,85 @@
+from __future__ import annotations
+
+from typing import Optional
+
+import httpx
+
+from ._http import DEFAULT_TIMEOUT_SECONDS, HttpClient
+from .resources import Consultas, Documentos, Empresas, Establecimientos, Guias, Sire, Webhooks
+
+
+class FacturaloClient:
+    """Cliente con el token de una empresa (sk_test_... demo / sk_live_... producción).
+
+    Emite y consulta comprobantes y guías, consulta RUC/DNI, revisa los webhooks enviados y trabaja el SIRE::
+
+        facturalo = FacturaloClient(os.environ["FACTURALO_TOKEN"])
+        envio = facturalo.documentos.enviar({...})
+    """
+
+    _PREFIJOS = ("sk_test_", "sk_live_")
+
+    def __init__(
+        self,
+        token: str,
+        *,
+        base_url: Optional[str] = None,
+        http_client: Optional[httpx.Client] = None,
+        timeout: float = DEFAULT_TIMEOUT_SECONDS,
+    ) -> None:
+        if not token.startswith(self._PREFIJOS):
+            raise ValueError(
+                "FacturaloClient espera el token de una empresa (sk_test_... / sk_live_...). "
+                "Para el token de usuario (user_sk_...) usa FacturaloCuentaClient."
+            )
+        self._http = HttpClient(token, base_url, http_client, timeout)
+        #: "demo" o "prod", según el token.
+        self.entorno = "prod" if token.startswith("sk_live_") else "demo"
+        self.documentos = Documentos(self._http)
+        self.guias = Guias(self._http)
+        self.consultas = Consultas(self._http)
+        self.webhooks = Webhooks(self._http)
+        self.sire = Sire(self._http)
+
+    def close(self) -> None:
+        self._http.close()
+
+    def __enter__(self) -> "FacturaloClient":
+        return self
+
+    def __exit__(self, *_: object) -> None:
+        self.close()
+
+
+class FacturaloCuentaClient:
+    """Cliente con el token de usuario (user_sk_...): administra empresas, sus tokens, webhooks y establecimientos.
+
+    Útil para software que da de alta las empresas de sus clientes.
+    """
+
+    def __init__(
+        self,
+        token: str,
+        *,
+        base_url: Optional[str] = None,
+        http_client: Optional[httpx.Client] = None,
+        timeout: float = DEFAULT_TIMEOUT_SECONDS,
+    ) -> None:
+        if not token.startswith("user_sk_"):
+            raise ValueError(
+                "FacturaloCuentaClient espera el token de usuario (user_sk_...). "
+                "Para emitir comprobantes usa FacturaloClient con el token de la empresa."
+            )
+        self._http = HttpClient(token, base_url, http_client, timeout)
+        self.empresas = Empresas(self._http)
+        self.establecimientos = Establecimientos(self._http)
+        self.consultas = Consultas(self._http)
+
+    def close(self) -> None:
+        self._http.close()
+
+    def __enter__(self) -> "FacturaloCuentaClient":
+        return self
+
+    def __exit__(self, *_: object) -> None:
+        self.close()

facturalo_pe-1.0.0/src/facturalo/errors.py

@@ -0,0 +1,70 @@
+"""Errores del SDK. Misma jerarquía que los SDKs de Node y PHP."""
+
+from __future__ import annotations
+
+from typing import Any, Dict, Optional
+
+
+class FacturaloError(Exception):
+    """Base de todos los errores del SDK."""
+
+
+class FacturaloConnectionError(FacturaloError):
+    """No se pudo conectar con la API (red, DNS, timeout)."""
+
+
+class FacturaloSignatureVerificationError(FacturaloError):
+    """La firma de un webhook falta o no coincide."""
+
+
+class FacturaloApiError(FacturaloError):
+    """La API respondió con un error HTTP. `status`, `errors` (validación) y `body` (respuesta completa)."""
+
+    def __init__(
+        self,
+        message: str,
+        status: int,
+        errors: Optional[Dict[str, Any]] = None,
+        body: Optional[Dict[str, Any]] = None,
+    ) -> None:
+        super().__init__(message)
+        self.status = status
+        self.errors = errors or {}
+        self.body = body
+
+    @staticmethod
+    def for_status(
+        status: int,
+        message: str,
+        errors: Optional[Dict[str, Any]] = None,
+        body: Optional[Dict[str, Any]] = None,
+    ) -> "FacturaloApiError":
+        cls = {
+            401: FacturaloAuthenticationError,
+            403: FacturaloPermissionError,
+            404: FacturaloNotFoundError,
+            400: FacturaloValidationError,
+            422: FacturaloValidationError,
+            429: FacturaloRateLimitError,
+        }.get(status, FacturaloApiError)
+        return cls(message, status, errors, body)
+
+
+class FacturaloAuthenticationError(FacturaloApiError):
+    """401: token ausente, inválido o revocado."""
+
+
+class FacturaloPermissionError(FacturaloApiError):
+    """403: el token no tiene permiso para esta operación."""
+
+
+class FacturaloNotFoundError(FacturaloApiError):
+    """404: el recurso no existe (o es de otra empresa)."""
+
+
+class FacturaloValidationError(FacturaloApiError):
+    """400 / 422: la petición no pasó validación o la operación no procede. Revisa `errors`."""
+
+
+class FacturaloRateLimitError(FacturaloApiError):
+    """429: demasiadas peticiones."""

facturalo_pe-1.0.0/src/facturalo/resources/__init__.py

@@ -0,0 +1,11 @@
+"""Recursos de la API: una clase por recurso, igual que en los SDKs de Node y PHP."""
+
+from .consultas import Consultas
+from .documentos import Documentos
+from .empresas import Empresas
+from .establecimientos import Establecimientos
+from .guias import Guias
+from .sire import LibroSire, Sire
+from .webhooks import Webhooks
+
+__all__ = ["Consultas", "Documentos", "Empresas", "Establecimientos", "Guias", "LibroSire", "Sire", "Webhooks"]

facturalo_pe-1.0.0/src/facturalo/resources/consultas.py

@@ -0,0 +1,38 @@
+from __future__ import annotations
+
+from typing import Any, Dict, Optional
+from urllib.parse import quote
+
+from .._http import HttpClient
+
+
+class Consultas:
+    """Consultas de RUC, DNI, tipo de cambio, placa, SOAT y licencia."""
+
+    def __init__(self, http: HttpClient) -> None:
+        self._http = http
+
+    def dni(self, dni: str) -> Dict[str, Any]:
+        return self._http.request("GET", f"/consulta/dni/{quote(dni, safe='')}")
+
+    def ruc(self, ruc: str) -> Dict[str, Any]:
+        return self._http.request("GET", f"/consulta/ruc/{quote(ruc, safe='')}")
+
+    def ruc_establecimientos(self, ruc: str) -> Any:
+        return self._http.request("GET", f"/consulta/ruc/{quote(ruc, safe='')}/anexos")
+
+    def ruc_representantes(self, ruc: str) -> Any:
+        return self._http.request("GET", f"/consulta/ruc/{quote(ruc, safe='')}/representantes")
+
+    def tipo_cambio(self, fecha: Optional[str] = None) -> Dict[str, Any]:
+        """Tipo de cambio SUNAT de una fecha (AAAA-MM-DD); sin fecha, el de hoy."""
+        return self._http.request("GET", "/consulta/tipo-cambio", query={"fecha": fecha})
+
+    def placa(self, placa: str) -> Dict[str, Any]:
+        return self._http.request("GET", f"/consulta/placa/{quote(placa, safe='')}")
+
+    def soat(self, placa: str) -> Dict[str, Any]:
+        return self._http.request("GET", f"/consulta/placa/{quote(placa, safe='')}/soat")
+
+    def licencia(self, dni: str) -> Dict[str, Any]:
+        return self._http.request("GET", f"/consulta/licencia/{quote(dni, safe='')}")

facturalo_pe-1.0.0/src/facturalo/resources/documentos.py

@@ -0,0 +1,115 @@
+from __future__ import annotations
+
+from typing import Any, Dict, Optional
+from urllib.parse import quote
+
+from .._http import HttpClient
+
+_EXTENSION = {"pdf": ".pdf", "ticket": ".ticket.pdf", "xml": ".xml", "cdr": ".cdr"}
+
+
+def _id(valor: str) -> str:
+    return quote(valor, safe="")
+
+
+class Documentos:
+    """Facturas, boletas y notas de crédito y débito."""
+
+    def __init__(self, http: HttpClient) -> None:
+        self._http = http
+
+    def enviar(
+        self,
+        documento: Dict[str, Any],
+        *,
+        webhook: bool = False,
+        establecimiento: Optional[str] = None,
+        idempotency_key: Optional[str] = None,
+    ) -> Dict[str, Any]:
+        """Emite el comprobante y espera la respuesta de SUNAT (o responde EN_PROCESO si `webhook=True`).
+
+        Un rechazo de SUNAT no es una excepción: vuelve con `estado == "RECHAZADA"` y el motivo en `sunat`.
+        Con `idempotency_key`, reintentar la misma petición no duplica el comprobante.
+        """
+        body: Dict[str, Any] = {"webhook": webhook, "documento": documento}
+        if establecimiento is not None:
+            body["establecimiento"] = establecimiento
+        headers = {"Idempotency-Key": idempotency_key} if idempotency_key else {}
+        return self._http.request("POST", "/documentos/enviar", body, headers=headers)
+
+    def generar_xml(self, documento: Dict[str, Any], *, establecimiento: Optional[str] = None) -> Dict[str, Any]:
+        """Genera el XML UBL 2.1 sin enviarlo a SUNAT."""
+        body: Dict[str, Any] = {"documento": documento}
+        if establecimiento is not None:
+            body["establecimiento"] = establecimiento
+        return self._http.request("POST", "/documentos/xml", body)
+
+    def consultar(self, id: str) -> Dict[str, Any]:
+        return self._http.request("GET", f"/documentos/{_id(id)}")
+
+    def buscar(self, tipo_comprobante: str, serie: str, correlativo: str) -> Dict[str, Any]:
+        return self._http.request(
+            "GET",
+            "/documentos/buscar",
+            query={"tipo_documento": tipo_comprobante, "serie": serie, "correlativo": correlativo},
+        )
+
+    def listar(
+        self,
+        *,
+        pagina: Optional[int] = None,
+        limite: Optional[int] = None,
+        fecha_inicio: Optional[str] = None,
+        fecha_fin: Optional[str] = None,
+        tipo: Optional[str] = None,
+        estado: Optional[str] = None,
+        buscar: Optional[str] = None,
+        establecimiento: Optional[str] = None,
+    ) -> Any:
+        return self._http.request(
+            "GET",
+            "/empresas/documentos",
+            query={
+                "page": pagina,
+                "limite": limite,
+                "fecha_inicio": fecha_inicio,
+                "fecha_fin": fecha_fin,
+                "tipo": tipo,
+                "estado": estado,
+                "buscar": buscar,
+                "establecimiento": establecimiento,
+            },
+        )
+
+    def anular(self, tipo_comprobante: str, serie: str, correlativo: str, motivo: str) -> Dict[str, Any]:
+        """Comunicación de baja (facturas) o resumen diario (boletas), dentro del plazo de SUNAT."""
+        return self._http.request(
+            "POST",
+            "/documentos/anular",
+            {
+                "documento": {
+                    "tipoComprobante": tipo_comprobante,
+                    "serie": serie,
+                    "correlativo": correlativo,
+                    "motivo": motivo,
+                }
+            },
+        )
+
+    def reenviar(self, id: str) -> Dict[str, Any]:
+        return self._http.request("POST", f"/documentos/{_id(id)}/reenviar")
+
+    def eventos(self, id: str) -> Any:
+        return self._http.request("GET", f"/documentos/{_id(id)}/eventos")
+
+    def eliminar(self, id: str) -> None:
+        self._http.request("DELETE", f"/documentos/{_id(id)}")
+
+    def url_archivo(self, id: str, formato: str = "pdf") -> str:
+        """URL pública del PDF (A4), ticket, XML o CDR."""
+        if formato not in _EXTENSION:
+            raise ValueError("Formato no válido. Usa pdf, ticket, xml o cdr.")
+        return self._http.file_url(f"/documentos/{_id(id)}{_EXTENSION[formato]}")
+
+    def descargar(self, id: str, formato: str = "pdf") -> bytes:
+        return self._http.download(self.url_archivo(id, formato))

facturalo_pe-1.0.0/src/facturalo/resources/empresas.py

@@ -0,0 +1,57 @@
+from __future__ import annotations
+
+from typing import Any, Dict, List, Optional
+from urllib.parse import quote
+
+from .._http import HttpClient
+
+
+def _id(valor: str) -> str:
+    return quote(valor, safe="")
+
+
+class Empresas:
+    """Empresas de la cuenta (token de usuario user_sk_...)."""
+
+    def __init__(self, http: HttpClient) -> None:
+        self._http = http
+
+    def listar(self) -> Any:
+        return self._http.request("GET", "/empresas")
+
+    def obtener(self, id: str) -> Dict[str, Any]:
+        return self._http.request("GET", f"/empresas/{_id(id)}").get("empresa", {})
+
+    def verificar_ruc(self, ruc: str) -> Dict[str, Any]:
+        return self._http.request("GET", f"/empresas/verificar-ruc/{_id(ruc)}")
+
+    def crear(self, empresa: Dict[str, Any]) -> Dict[str, Any]:
+        return self._http.request("POST", "/empresas", {"empresa": empresa}).get("empresa", {})
+
+    def actualizar(self, id: str, empresa: Dict[str, Any]) -> Dict[str, Any]:
+        return self._http.request("PATCH", f"/empresas/{_id(id)}", {"empresa": empresa}).get("empresa", {})
+
+    def actualizar_webhook(self, id: str, webhook: Dict[str, Any]) -> Dict[str, Any]:
+        return self._http.request("PATCH", f"/empresas/{_id(id)}/webhook", {"webhook": webhook}).get("empresa", {})
+
+    def eventos_webhook(self, id: str) -> Any:
+        return self._http.request("GET", f"/empresas/{_id(id)}/webhook/eventos")
+
+    def actualizar_eventos_webhook(self, id: str, entorno: str, eventos: List[str]) -> Any:
+        return self._http.request(
+            "PATCH", f"/empresas/{_id(id)}/webhook/eventos", {"entorno": entorno, "eventos": eventos}
+        )
+
+    def regenerar_token(self, id: str, entorno: str) -> Dict[str, Any]:
+        return self._http.request("POST", f"/empresas/{_id(id)}/regenerar-token", {"entorno": entorno}).get(
+            "empresa", {}
+        )
+
+    def regenerar_secret_webhook(self, id: str, entorno: str) -> Dict[str, Any]:
+        return self._http.request(
+            "POST", f"/empresas/{_id(id)}/webhook/regenerar-secret", {"entorno": entorno}
+        ).get("empresa", {})
+
+    def certificado(self, id: str) -> Optional[Dict[str, Any]]:
+        certificado = self._http.request("GET", f"/empresas/{_id(id)}/certificado").get("certificado")
+        return certificado if isinstance(certificado, dict) else None

facturalo_pe-1.0.0/src/facturalo/resources/establecimientos.py

@@ -0,0 +1,35 @@
+from __future__ import annotations
+
+from typing import Any, Dict
+from urllib.parse import quote
+
+from .._http import HttpClient
+
+
+class Establecimientos:
+    """Establecimientos (sucursales) de una empresa."""
+
+    def __init__(self, http: HttpClient) -> None:
+        self._http = http
+
+    def _base(self, empresa_id: str) -> str:
+        return f"/empresas/{quote(empresa_id, safe='')}/establecimientos"
+
+    def listar(self, empresa_id: str) -> Any:
+        return self._http.request("GET", self._base(empresa_id))
+
+    def obtener(self, empresa_id: str, id: str) -> Dict[str, Any]:
+        return self._http.request("GET", f"{self._base(empresa_id)}/{quote(id, safe='')}").get("establecimiento", {})
+
+    def crear(self, empresa_id: str, establecimiento: Dict[str, Any]) -> Dict[str, Any]:
+        return self._http.request("POST", self._base(empresa_id), {"establecimiento": establecimiento}).get(
+            "establecimiento", {}
+        )
+
+    def actualizar(self, empresa_id: str, id: str, establecimiento: Dict[str, Any]) -> Dict[str, Any]:
+        return self._http.request(
+            "PATCH", f"{self._base(empresa_id)}/{quote(id, safe='')}", {"establecimiento": establecimiento}
+        ).get("establecimiento", {})
+
+    def eliminar(self, empresa_id: str, id: str) -> None:
+        self._http.request("DELETE", f"{self._base(empresa_id)}/{quote(id, safe='')}")

facturalo_pe-1.0.0/src/facturalo/resources/guias.py

@@ -0,0 +1,61 @@
+from __future__ import annotations
+
+from typing import Any, Dict, Optional
+from urllib.parse import quote
+
+from .._http import HttpClient
+
+_FORMATOS = ("pdf", "xml", "cdr")
+
+
+class Guias:
+    """Guías de remisión remitente (09) y transportista (31)."""
+
+    def __init__(self, http: HttpClient) -> None:
+        self._http = http
+
+    def enviar(
+        self, guia: Dict[str, Any], *, webhook: bool = False, idempotency_key: Optional[str] = None
+    ) -> Dict[str, Any]:
+        headers = {"Idempotency-Key": idempotency_key} if idempotency_key else {}
+        return self._http.request("POST", "/guias/enviar", {"webhook": webhook, "guia": guia}, headers=headers)
+
+    def consultar(self, id: str) -> Dict[str, Any]:
+        return self._http.request("GET", f"/guias/{quote(id, safe='')}")
+
+    def consultar_ticket(self, ticket: str) -> Dict[str, Any]:
+        return self._http.request("POST", "/guias/ticket", {"ticket": ticket})
+
+    def eventos(self, id: str) -> Any:
+        return self._http.request("GET", f"/guias/{quote(id, safe='')}/eventos")
+
+    def listar(
+        self,
+        *,
+        pagina: Optional[int] = None,
+        limite: Optional[int] = None,
+        fecha_inicio: Optional[str] = None,
+        fecha_fin: Optional[str] = None,
+        estado: Optional[str] = None,
+        buscar: Optional[str] = None,
+    ) -> Any:
+        return self._http.request(
+            "GET",
+            "/empresas/guias",
+            query={
+                "page": pagina,
+                "limite": limite,
+                "fecha_inicio": fecha_inicio,
+                "fecha_fin": fecha_fin,
+                "estado": estado,
+                "buscar": buscar,
+            },
+        )
+
+    def url_archivo(self, id: str, formato: str = "pdf") -> str:
+        if formato not in _FORMATOS:
+            raise ValueError("Formato no válido. Usa pdf, xml o cdr.")
+        return self._http.file_url(f"/guias/{quote(id, safe='')}.{formato}")
+
+    def descargar(self, id: str, formato: str = "pdf") -> bytes:
+        return self._http.download(self.url_archivo(id, formato))

facturalo_pe-1.0.0/src/facturalo/resources/sire.py

@@ -0,0 +1,68 @@
+from __future__ import annotations
+
+from typing import Any, Dict, Mapping, Optional
+from urllib.parse import quote
+
+from .._http import HttpClient
+
+
+class LibroSire:
+    """Registro de Ventas (RVIE) o de Compras (RCE) del SIRE."""
+
+    def __init__(self, http: HttpClient, libro: str) -> None:
+        self._http = http
+        self._libro = libro
+
+    def _path(self, periodo: str, accion: str) -> str:
+        return f"/sire/{self._libro}/{quote(periodo, safe='')}/{accion}"
+
+    def periodos(self) -> Any:
+        return self._http.request("GET", f"/sire/{self._libro}/periodos")
+
+    def resumen(self, periodo: str, query: Optional[Mapping[str, Any]] = None) -> Any:
+        return self._http.request("GET", self._path(periodo, "resumen"), query=query)
+
+    def resumen_comprobantes(self, periodo: str, query: Optional[Mapping[str, Any]] = None) -> Any:
+        return self._http.request("GET", self._path(periodo, "resumen-comprobantes"), query=query)
+
+    def comprobantes(self, periodo: str, query: Optional[Mapping[str, Any]] = None) -> Any:
+        return self._http.request("GET", self._path(periodo, "comprobantes"), query=query)
+
+    def inconsistencias(self, periodo: str, query: Optional[Mapping[str, Any]] = None) -> Any:
+        return self._http.request("GET", self._path(periodo, "inconsistencias"), query=query)
+
+    def inconsistencia_por_comprobante(self, periodo: str, query: Mapping[str, Any]) -> Any:
+        return self._http.request("GET", self._path(periodo, "inconsistencia-por-comprobante"), query=query)
+
+    def aceptar_propuesta(self, periodo: str, body: Optional[Dict[str, Any]] = None) -> Any:
+        return self._http.request("POST", self._path(periodo, "aceptar-propuesta"), body or {})
+
+    def exportar(self, periodo: str, query: Optional[Mapping[str, Any]] = None) -> Any:
+        return self._http.request("GET", self._path(periodo, "exportar"), query=query)
+
+    def descargar_ticket(self, num_ticket: str) -> Any:
+        return self._http.request("GET", f"/sire/{self._libro}/tickets/{quote(num_ticket, safe='')}/descargar")
+
+    def preliminares(self, periodo: str, query: Optional[Mapping[str, Any]] = None) -> Any:
+        return self._http.request("GET", self._path(periodo, "preliminares"), query=query)
+
+    def eliminar_preliminar(self, periodo: str, body: Dict[str, Any]) -> Any:
+        return self._http.request("PUT", self._path(periodo, "eliminar-preliminar"), body)
+
+    def eliminar_preliminar_registrado(self, periodo: str, body: Dict[str, Any]) -> Any:
+        return self._http.request("PUT", self._path(periodo, "eliminar-preliminar-registrado"), body)
+
+    def conciliar(self, periodo: str, body: Optional[Dict[str, Any]] = None) -> Any:
+        return self._http.request("POST", self._path(periodo, "conciliar"), body or {})
+
+
+class Sire:
+    """SIRE: `sire.ventas` (RVIE) y `sire.compras` (RCE)."""
+
+    def __init__(self, http: HttpClient) -> None:
+        self._http = http
+        self.ventas = LibroSire(http, "ventas")
+        self.compras = LibroSire(http, "compras")
+
+    def conciliacion(self, conciliacion_id: str) -> Any:
+        return self._http.request("GET", f"/sire/conciliaciones/{quote(conciliacion_id, safe='')}")

facturalo_pe-1.0.0/src/facturalo/resources/webhooks.py

@@ -0,0 +1,28 @@
+from __future__ import annotations
+
+from typing import Any, Dict, Optional
+from urllib.parse import quote
+
+from .._http import HttpClient
+
+
+class Webhooks:
+    """Webhooks enviados por Facturalo a tu servidor."""
+
+    def __init__(self, http: HttpClient) -> None:
+        self._http = http
+
+    def listar(
+        self,
+        *,
+        pagina: Optional[int] = None,
+        limite: Optional[int] = None,
+        estado: Optional[str] = None,
+        evento: Optional[str] = None,
+    ) -> Any:
+        return self._http.request(
+            "GET", "/webhooks", query={"page": pagina, "limite": limite, "estado": estado, "evento": evento}
+        )
+
+    def reenviar(self, evento_id: str) -> Dict[str, Any]:
+        return self._http.request("POST", f"/webhooks/{quote(evento_id, safe='')}/reenviar")

facturalo_pe-1.0.0/src/facturalo/webhook.py

@@ -0,0 +1,43 @@
+"""Verificación de webhooks: la firma es HMAC-SHA256(secret, cuerpo crudo) en hexadecimal, en X-Facturalo-Firma."""
+
+from __future__ import annotations
+
+import hashlib
+import hmac
+import json
+from typing import Any, Dict, Optional, Union
+
+from .errors import FacturaloSignatureVerificationError
+
+Payload = Union[str, bytes]
+
+
+def verificar_firma(payload: Payload, firma: Optional[str], secret: str) -> None:
+    """Recalcula la firma y la compara en tiempo constante con el header X-Facturalo-Firma.
+
+    Usa el cuerpo crudo tal como llegó (`request.body` en Django, `await request.body()` en FastAPI,
+    `request.get_data()` en Flask), nunca el JSON ya decodificado.
+
+    :param payload: Cuerpo crudo del request.
+    :param firma: Valor del header X-Facturalo-Firma.
+    :param secret: El secreto del webhook de la empresa (whsec_...), distinto por entorno.
+    :raises FacturaloSignatureVerificationError: si falta la firma o no coincide.
+    """
+    if firma is None or not firma.strip():
+        raise FacturaloSignatureVerificationError("Falta el header X-Facturalo-Firma.")
+    cuerpo = payload.encode("utf-8") if isinstance(payload, str) else payload
+    esperada = hmac.new(secret.encode("utf-8"), cuerpo, hashlib.sha256).hexdigest()
+    if not hmac.compare_digest(esperada, firma.strip().lower()):
+        raise FacturaloSignatureVerificationError("La firma del webhook no coincide.")
+
+
+def construir_evento(payload: Payload, firma: Optional[str], secret: str) -> Dict[str, Any]:
+    """Verifica la firma y devuelve el evento decodificado (id, evento, timestamp, entorno, documento, sunat...)."""
+    verificar_firma(payload, firma, secret)
+    try:
+        evento = json.loads(payload)
+    except ValueError as e:
+        raise FacturaloSignatureVerificationError("El cuerpo del webhook no es JSON válido.") from e
+    if not isinstance(evento, dict):
+        raise FacturaloSignatureVerificationError("El cuerpo del webhook no es JSON válido.")
+    return evento

facturalo_pe-1.0.0/tests/test_client.py

@@ -0,0 +1,109 @@
+import json
+
+import httpx
+import pytest
+
+from facturalo import (
+    FacturaloClient,
+    FacturaloCuentaClient,
+    FacturaloNotFoundError,
+    FacturaloValidationError,
+)
+
+
+def cliente(handler, token="sk_test_abc"):
+    return FacturaloClient(token, http_client=httpx.Client(transport=httpx.MockTransport(handler)))
+
+
+def ok(data, status=200):
+    return httpx.Response(status, json={"success": True, "message": "ok", "data": data})
+
+
+def test_token_de_empresa_obligatorio():
+    with pytest.raises(ValueError):
+        FacturaloClient("user_sk_abc")
+    with pytest.raises(ValueError):
+        FacturaloCuentaClient("sk_test_abc")
+
+
+def test_entorno_segun_token():
+    assert FacturaloClient("sk_test_x").entorno == "demo"
+    assert FacturaloClient("sk_live_x").entorno == "prod"
+
+
+def test_enviar_documento_sin_bearer_y_con_idempotencia():
+    visto = {}
+
+    def handler(request: httpx.Request):
+        visto["auth"] = request.headers["Authorization"]
+        visto["idem"] = request.headers.get("Idempotency-Key")
+        visto["url"] = str(request.url)
+        visto["body"] = json.loads(request.content)
+        return ok({"estado": "ACEPTADA", "enlaces": {"pdf": "https://x/doc.pdf"}})
+
+    r = cliente(handler).documentos.enviar({"serie": "F001"}, idempotency_key="pedido-1")
+    assert r["estado"] == "ACEPTADA"
+    assert visto["auth"] == "sk_test_abc"
+    assert visto["idem"] == "pedido-1"
+    assert visto["url"] == "https://api.facturalo.pe/api/v3/documentos/enviar"
+    assert visto["body"] == {"webhook": False, "documento": {"serie": "F001"}}
+
+
+def test_rechazo_sunat_no_es_excepcion():
+    r = cliente(lambda req: ok({"estado": "RECHAZADA", "sunat": {"codigo": "2800"}})).documentos.enviar({})
+    assert r["estado"] == "RECHAZADA"
+
+
+def test_errores_mapean_por_status():
+    def handler(request):
+        return httpx.Response(422, json={"success": False, "message": "Datos inválidos", "errors": {"serie": ["requerido"]}})
+
+    with pytest.raises(FacturaloValidationError) as e:
+        cliente(handler).documentos.enviar({})
+    assert e.value.status == 422
+    assert e.value.errors == {"serie": ["requerido"]}
+
+    with pytest.raises(FacturaloNotFoundError):
+        cliente(lambda req: httpx.Response(404, json={"message": "No existe"})).documentos.consultar("x")
+
+
+def test_post_sin_idempotencia_no_se_reintenta():
+    llamadas = []
+
+    def handler(request):
+        llamadas.append(1)
+        return httpx.Response(503, json={"message": "caído"})
+
+    with pytest.raises(Exception):
+        cliente(handler).documentos.enviar({})
+    assert len(llamadas) == 1
+
+
+def test_get_se_reintenta(monkeypatch):
+    monkeypatch.setattr("facturalo._http.time.sleep", lambda s: None)
+    llamadas = []
+
+    def handler(request):
+        llamadas.append(1)
+        return httpx.Response(503) if len(llamadas) < 3 else ok({"compra": 3.45})
+
+    assert cliente(handler).consultas.tipo_cambio("2026-10-30") == {"compra": 3.45}
+    assert len(llamadas) == 3
+
+
+def test_query_sin_vacios():
+    visto = {}
+
+    def handler(request):
+        visto["params"] = dict(request.url.params)
+        return ok([])
+
+    cliente(handler).documentos.listar(pagina=2, estado="ACEPTADA")
+    assert visto["params"] == {"page": "2", "estado": "ACEPTADA"}
+
+
+def test_url_archivo():
+    c = cliente(lambda req: ok({}))
+    assert c.documentos.url_archivo("abc", "ticket") == "https://api.facturalo.pe/api/v3/documentos/abc.ticket.pdf"
+    with pytest.raises(ValueError):
+        c.documentos.url_archivo("abc", "zip")

facturalo_pe-1.0.0/tests/test_webhook.py

@@ -0,0 +1,22 @@
+import hashlib
+import hmac
+
+import pytest
+
+from facturalo import FacturaloSignatureVerificationError, construir_evento, verificar_firma
+
+SECRET = "whsec_prueba"
+CUERPO = b'{"id":"evt_1","evento":"documento.sunat.respuesta"}'
+FIRMA = hmac.new(SECRET.encode(), CUERPO, hashlib.sha256).hexdigest()
+
+
+def test_firma_valida():
+    assert construir_evento(CUERPO, FIRMA, SECRET)["evento"] == "documento.sunat.respuesta"
+    verificar_firma(CUERPO.decode(), FIRMA.upper(), SECRET)
+
+
+def test_firma_invalida_o_ausente():
+    with pytest.raises(FacturaloSignatureVerificationError):
+        verificar_firma(CUERPO, "00" * 32, SECRET)
+    with pytest.raises(FacturaloSignatureVerificationError):
+        verificar_firma(CUERPO, None, SECRET)