vektra-erp 1.0.0__tar.gz

vektra_erp-1.0.0/LICENSE

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

vektra_erp-1.0.0/PKG-INFO

@@ -0,0 +1,113 @@
+Metadata-Version: 2.4
+Name: vektra-erp
+Version: 1.0.0
+Summary: SDK de Python de la API v1 de Vektra ERP (facturación electrónica con ARCA), generado desde el OpenAPI.
+License: MIT
+Project-URL: Homepage, https://vektra.digital/api-factura-electronica-arca
+Keywords: vektra,erp,arca,afip,factura-electronica,api,sdk
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Natural Language :: Spanish
+Classifier: Typing :: Typed
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# SDK de Python — API v1 de Vektra ERP
+
+Cliente de la API v1 generado desde el OpenAPI (`/api/v1/openapi.json`), con type hints (`TypedDict` para los cuerpos). **Sin dependencias**: usa `urllib` de la biblioteca estándar. Python 3.9 o más.
+
+> **Estado:** vive en el repositorio (`sdk/python/`); todavía no está publicado en PyPI. Para usarlo, copiá la carpeta `vektra_erp/` a tu proyecto o instalalo desde el repo (`pip install ./sdk/python`).
+> `tipos.py` y `operaciones.py` son **generados**: no se editan, se regeneran con `npm run sdk:generar` (desde la raíz del repo). El resto (`cliente.py`, `errores.py`) es código a mano.
+
+## Empezar
+
+```python
+import os
+from vektra_erp import ClienteVektra
+
+vektra = ClienteVektra(
+    clave=os.environ["VEKTRA_CLAVE"],  # erp_... (producción) o erp_test_... (sandbox)
+    base_url="https://tuempresa.erp.vektra.digital",  # la dirección de tu instalación
+)
+```
+
+Producción y sandbox usan **la misma dirección**; lo que cambia es la clave. Con una clave `erp_test_...` (`vektra.es_sandbox`) las facturas son simuladas: nada llega a ARCA ni a tu contabilidad.
+
+Opciones: `max_reintentos` (429; 2 por defecto), `espera_maxima` (60 s), `timeout` (30 s).
+
+## Emitir una factura (con idempotencia)
+
+```python
+from vektra_erp import nueva_idempotency_key
+
+# Guardá la clave junto a tu pedido: si se corta, repetís con la MISMA clave y no se factura dos veces.
+idempotency_key = nueva_idempotency_key()
+
+factura = vektra.emitir_factura(
+    {
+        "referencia": "pedido-1001",
+        "cliente": {"documento": "30715974823", "razonSocial": "Cliente de ejemplo S.A.", "condicionIva": 1},
+        "puntoVenta": 1,
+        "renglones": [{"descripcion": "Servicio mensual", "cantidad": 1, "precioUnitario": 1000, "iva": 21}],
+    },
+    idempotency_key=idempotency_key,
+)
+```
+
+Repetir el pedido con la misma `Idempotency-Key` y el mismo cuerpo devuelve la misma factura; con otro cuerpo falla con `clave_reutilizada`.
+
+## Errores
+
+Todo error de la API se lanza como `ErrorApi` (formato estable `{error, code, campo, request_id}`); un corte de red, como `ErrorDeRed`. Ambas heredan de `ErrorVektra`.
+
+```python
+from vektra_erp import ErrorApi, ErrorDeRed
+
+try:
+    vektra.emitir_factura(cuerpo, idempotency_key=idempotency_key)
+except ErrorApi as e:
+    print(e.status, e.code, e.message, e.campo, e.request_id)  # 422 validacion «...» renglones.0.iva req_...
+except ErrorDeRed:
+    # No sabés si el servidor llegó a procesar el pedido: repetí con la misma idempotency_key.
+    raise
+```
+
+### 422 con `pendiente: true` (ARCA no confirmó)
+
+Si ARCA no contesta a tiempo, la API responde 422 `pendiente_arca` con `pendiente: true`: el comprobante **puede haberse autorizado igual**. No lo repitas con otra clave ni sin `referencia`: usá la misma `idempotency_key` o consultá la factura.
+
+```python
+try:
+    vektra.emitir_factura(cuerpo, idempotency_key=idempotency_key)
+except ErrorApi as e:
+    if e.pendiente:
+        # e.datos trae el comprobante tal como quedó (con su id); e.request_id sirve para soporte.
+        quedo = vektra.listar_facturas(referencia="pedido-1001")
+    else:
+        raise
+```
+
+## Reintentos ante 429
+
+Un 429 (`limite_pedidos`) se reintenta solo, esperando los segundos de `Retry-After`. Si pide esperar más de `espera_maxima`, o se agotan los reintentos, se lanza `ErrorApi` (`e.retry_after` trae los segundos). El 503 `servicio_no_disponible` no se reintenta solo.
+
+## Más ejemplos
+
+```python
+pagina = vektra.listar_facturas(desde="2026-01-01", hasta="2026-01-31", estado="autorizado", limit=50)
+pdf = vektra.descargar_pdf_factura(factura["id"])  # bytes
+```
+
+Los métodos van en snake_case (`listar_clientes`, `crear_punto_venta`, `obtener_cotizacion`...). Los parámetros de ruta son posicionales, el cuerpo va después y los filtros de consulta, por nombre. Los objetos anidados sin nombre en el OpenAPI se tipan como `Dict[str, Any]`.
+
+## Pruebas
+
+```bash
+cd sdk/python && python3 -m unittest discover -s tests -t .
+```
+
+`src/app/api/v1/sdk.test.ts` (Vitest) falla si lo generado no coincide con el OpenAPI actual y corre estas pruebas si hay `python3`.

vektra_erp-1.0.0/README.md

@@ -0,0 +1,95 @@
+# SDK de Python — API v1 de Vektra ERP
+
+Cliente de la API v1 generado desde el OpenAPI (`/api/v1/openapi.json`), con type hints (`TypedDict` para los cuerpos). **Sin dependencias**: usa `urllib` de la biblioteca estándar. Python 3.9 o más.
+
+> **Estado:** vive en el repositorio (`sdk/python/`); todavía no está publicado en PyPI. Para usarlo, copiá la carpeta `vektra_erp/` a tu proyecto o instalalo desde el repo (`pip install ./sdk/python`).
+> `tipos.py` y `operaciones.py` son **generados**: no se editan, se regeneran con `npm run sdk:generar` (desde la raíz del repo). El resto (`cliente.py`, `errores.py`) es código a mano.
+
+## Empezar
+
+```python
+import os
+from vektra_erp import ClienteVektra
+
+vektra = ClienteVektra(
+    clave=os.environ["VEKTRA_CLAVE"],  # erp_... (producción) o erp_test_... (sandbox)
+    base_url="https://tuempresa.erp.vektra.digital",  # la dirección de tu instalación
+)
+```
+
+Producción y sandbox usan **la misma dirección**; lo que cambia es la clave. Con una clave `erp_test_...` (`vektra.es_sandbox`) las facturas son simuladas: nada llega a ARCA ni a tu contabilidad.
+
+Opciones: `max_reintentos` (429; 2 por defecto), `espera_maxima` (60 s), `timeout` (30 s).
+
+## Emitir una factura (con idempotencia)
+
+```python
+from vektra_erp import nueva_idempotency_key
+
+# Guardá la clave junto a tu pedido: si se corta, repetís con la MISMA clave y no se factura dos veces.
+idempotency_key = nueva_idempotency_key()
+
+factura = vektra.emitir_factura(
+    {
+        "referencia": "pedido-1001",
+        "cliente": {"documento": "30715974823", "razonSocial": "Cliente de ejemplo S.A.", "condicionIva": 1},
+        "puntoVenta": 1,
+        "renglones": [{"descripcion": "Servicio mensual", "cantidad": 1, "precioUnitario": 1000, "iva": 21}],
+    },
+    idempotency_key=idempotency_key,
+)
+```
+
+Repetir el pedido con la misma `Idempotency-Key` y el mismo cuerpo devuelve la misma factura; con otro cuerpo falla con `clave_reutilizada`.
+
+## Errores
+
+Todo error de la API se lanza como `ErrorApi` (formato estable `{error, code, campo, request_id}`); un corte de red, como `ErrorDeRed`. Ambas heredan de `ErrorVektra`.
+
+```python
+from vektra_erp import ErrorApi, ErrorDeRed
+
+try:
+    vektra.emitir_factura(cuerpo, idempotency_key=idempotency_key)
+except ErrorApi as e:
+    print(e.status, e.code, e.message, e.campo, e.request_id)  # 422 validacion «...» renglones.0.iva req_...
+except ErrorDeRed:
+    # No sabés si el servidor llegó a procesar el pedido: repetí con la misma idempotency_key.
+    raise
+```
+
+### 422 con `pendiente: true` (ARCA no confirmó)
+
+Si ARCA no contesta a tiempo, la API responde 422 `pendiente_arca` con `pendiente: true`: el comprobante **puede haberse autorizado igual**. No lo repitas con otra clave ni sin `referencia`: usá la misma `idempotency_key` o consultá la factura.
+
+```python
+try:
+    vektra.emitir_factura(cuerpo, idempotency_key=idempotency_key)
+except ErrorApi as e:
+    if e.pendiente:
+        # e.datos trae el comprobante tal como quedó (con su id); e.request_id sirve para soporte.
+        quedo = vektra.listar_facturas(referencia="pedido-1001")
+    else:
+        raise
+```
+
+## Reintentos ante 429
+
+Un 429 (`limite_pedidos`) se reintenta solo, esperando los segundos de `Retry-After`. Si pide esperar más de `espera_maxima`, o se agotan los reintentos, se lanza `ErrorApi` (`e.retry_after` trae los segundos). El 503 `servicio_no_disponible` no se reintenta solo.
+
+## Más ejemplos
+
+```python
+pagina = vektra.listar_facturas(desde="2026-01-01", hasta="2026-01-31", estado="autorizado", limit=50)
+pdf = vektra.descargar_pdf_factura(factura["id"])  # bytes
+```
+
+Los métodos van en snake_case (`listar_clientes`, `crear_punto_venta`, `obtener_cotizacion`...). Los parámetros de ruta son posicionales, el cuerpo va después y los filtros de consulta, por nombre. Los objetos anidados sin nombre en el OpenAPI se tipan como `Dict[str, Any]`.
+
+## Pruebas
+
+```bash
+cd sdk/python && python3 -m unittest discover -s tests -t .
+```
+
+`src/app/api/v1/sdk.test.ts` (Vitest) falla si lo generado no coincide con el OpenAPI actual y corre estas pruebas si hay `python3`.

vektra_erp-1.0.0/pyproject.toml

@@ -0,0 +1,30 @@
+[build-system]
+requires = ["setuptools>=61"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "vektra-erp"
+version = "1.0.0"
+description = "SDK de Python de la API v1 de Vektra ERP (facturación electrónica con ARCA), generado desde el OpenAPI."
+readme = "README.md"
+license = { text = "MIT" }
+requires-python = ">=3.9"
+dependencies = []
+keywords = ["vektra", "erp", "arca", "afip", "factura-electronica", "api", "sdk"]
+classifiers = [
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3 :: Only",
+  "License :: OSI Approved :: MIT License",
+  "Operating System :: OS Independent",
+  "Natural Language :: Spanish",
+  "Typing :: Typed",
+]
+
+[project.urls]
+Homepage = "https://vektra.digital/api-factura-electronica-arca"
+
+[tool.setuptools]
+packages = ["vektra_erp"]
+
+[tool.setuptools.package-data]
+vektra_erp = ["py.typed"]

vektra_erp-1.0.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

vektra_erp-1.0.0/tests/test_cliente.py

@@ -0,0 +1,78 @@
+"""Pruebas del SDK de Python con un transporte simulado (sin red). Se corren con: python -m unittest discover -s tests"""
+
+import json
+import unittest
+
+from vektra_erp import ClienteVektra, ErrorApi
+
+
+def respuesta(status, cuerpo=None, **cabeceras):
+    datos = b"" if cuerpo is None else json.dumps(cuerpo).encode("utf-8")
+    return status, {k.lower().replace("_", "-"): str(v) for k, v in cabeceras.items()}, datos
+
+
+class Simulado:
+    def __init__(self, *respuestas):
+        self.respuestas = list(respuestas)
+        self.pedidos = []
+
+    def __call__(self, metodo, url, cabeceras, cuerpo, timeout):
+        self.pedidos.append((metodo, url, cabeceras, cuerpo))
+        return self.respuestas.pop(0)
+
+
+def cliente(transporte, **kw):
+    return ClienteVektra("erp_abc_secreto", "https://erp.ejemplo.com/", transporte=transporte, dormir=lambda s: None, **kw)
+
+
+class PruebasCliente(unittest.TestCase):
+    def test_emite_una_factura_con_idempotency_key(self):
+        t = Simulado(respuesta(201, {"id": "f1", "estado": "autorizado"}))
+        f = cliente(t).emitir_factura({"cliente": {"documento": "30715974823"}, "renglones": []}, idempotency_key="k-1")
+        self.assertEqual(f["id"], "f1")
+        metodo, url, cab, cuerpo = t.pedidos[0]
+        self.assertEqual((metodo, url), ("POST", "https://erp.ejemplo.com/api/v1/facturas"))
+        self.assertEqual(cab["Authorization"], "Bearer erp_abc_secreto")
+        self.assertEqual(cab["Idempotency-Key"], "k-1")
+        self.assertEqual(json.loads(cuerpo)["cliente"]["documento"], "30715974823")
+
+    def test_consulta_y_ruta(self):
+        t = Simulado(respuesta(200, {"paging": {}, "resultados": []}), respuesta(200, {"id": "x"}))
+        c = cliente(t)
+        c.listar_facturas(punto_venta=2, estado="autorizado", cae=None)
+        c.obtener_factura("a b")
+        self.assertEqual(t.pedidos[0][1], "https://erp.ejemplo.com/api/v1/facturas?estado=autorizado&puntoVenta=2")
+        self.assertTrue(t.pedidos[1][1].endswith("/api/v1/facturas/a%20b"))
+
+    def test_422_pendiente(self):
+        cuerpo = {"error": "ARCA no confirmó", "code": "pendiente_arca", "request_id": "req_1", "pendiente": True, "id": "f9"}
+        with self.assertRaises(ErrorApi) as ctx:
+            cliente(Simulado(respuesta(422, cuerpo))).emitir_factura({"cliente": {}, "renglones": []})
+        e = ctx.exception
+        self.assertEqual((e.status, e.code, e.request_id, e.pendiente), (422, "pendiente_arca", "req_1", True))
+        self.assertEqual(e.datos["id"], "f9")
+
+    def test_reintenta_el_429_con_retry_after(self):
+        esperas = []
+        t = Simulado(respuesta(429, {"error": "x", "code": "limite_pedidos"}, Retry_After=3), respuesta(200, {"paging": {}}))
+        c = ClienteVektra("erp_abc_x", "https://e.com", transporte=t, dormir=esperas.append)
+        c.listar_facturas()
+        self.assertEqual((len(t.pedidos), esperas), (2, [3.0]))
+
+    def test_429_sin_reintentos_restantes_falla(self):
+        t = Simulado(*[respuesta(429, {"error": "x", "code": "limite_pedidos"}, Retry_After=1)] * 3)
+        with self.assertRaises(ErrorApi) as ctx:
+            cliente(t).listar_facturas()
+        self.assertEqual((ctx.exception.code, len(t.pedidos)), ("limite_pedidos", 3))
+
+    def test_sandbox(self):
+        self.assertTrue(ClienteVektra("erp_test_abc_x", "https://e.com").es_sandbox)
+        self.assertFalse(ClienteVektra("erp_abc_x", "https://e.com").es_sandbox)
+
+    def test_pdf_devuelve_bytes(self):
+        t = Simulado((200, {}, b"%PDF-1.4"))
+        self.assertEqual(cliente(t).descargar_pdf_factura("f1"), b"%PDF-1.4")
+
+
+if __name__ == "__main__":
+    unittest.main()

vektra_erp-1.0.0/vektra_erp/__init__.py

@@ -0,0 +1,7 @@
+"""SDK de Python de la API v1 de Vektra ERP (generado desde el OpenAPI)."""
+
+from . import tipos
+from .cliente import ClienteVektra, nueva_idempotency_key
+from .errores import ErrorApi, ErrorDeRed, ErrorVektra
+
+__all__ = ["ClienteVektra", "ErrorApi", "ErrorDeRed", "ErrorVektra", "nueva_idempotency_key", "tipos"]

vektra_erp-1.0.0/vektra_erp/cliente.py

@@ -0,0 +1,160 @@
+"""Cliente HTTP de la API v1 de Vektra ERP, sobre ``urllib`` (sin dependencias)."""
+
+from __future__ import annotations
+
+import json
+import time
+import urllib.error
+import urllib.parse
+import urllib.request
+import uuid
+from email.utils import parsedate_to_datetime
+from typing import Any, Callable, Dict, Optional, Tuple
+
+from .errores import ErrorApi, ErrorDeRed
+from .operaciones import OperacionesApi
+
+PREFIJO_SANDBOX = "erp_test_"
+
+#: ``(status, cabeceras, cuerpo)``; las cabeceras con las claves en minúscula.
+Respuesta = Tuple[int, Dict[str, str], bytes]
+#: ``(metodo, url, cabeceras, cuerpo, timeout) -> Respuesta``. Se puede reemplazar (pruebas, proxies).
+Transporte = Callable[[str, str, Dict[str, str], Optional[bytes], Optional[float]], Respuesta]
+
+
+def nueva_idempotency_key() -> str:
+    """Una ``Idempotency-Key`` nueva (UUID v4). Guardala junto al pedido para poder repetirlo sin duplicarlo."""
+    return str(uuid.uuid4())
+
+
+def _transporte_urllib(
+    metodo: str, url: str, cabeceras: Dict[str, str], cuerpo: Optional[bytes], timeout: Optional[float]
+) -> Respuesta:
+    pedido = urllib.request.Request(url, data=cuerpo, headers=cabeceras, method=metodo)
+    try:
+        with urllib.request.urlopen(pedido, timeout=timeout) as r:  # noqa: S310 (la URL la arma el cliente con http/https)
+            return r.status, {k.lower(): v for k, v in r.headers.items()}, r.read()
+    except urllib.error.HTTPError as e:
+        return e.code, {k.lower(): v for k, v in e.headers.items()}, e.read()
+    except (urllib.error.URLError, TimeoutError, OSError) as e:
+        raise ErrorDeRed(f"No se pudo completar el pedido {metodo} {url}: {e}") from e
+
+
+def _leer_retry_after(valor: Optional[str]) -> Optional[float]:
+    """Segundos de un ``Retry-After`` (número o fecha HTTP), o ``None`` si no vino o no se entiende."""
+    if not valor:
+        return None
+    try:
+        segundos = float(valor)
+        return segundos if segundos >= 0 else None
+    except ValueError:
+        pass
+    try:
+        return max(0.0, parsedate_to_datetime(valor).timestamp() - time.time())
+    except (TypeError, ValueError):
+        return None
+
+
+class ClienteVektra(OperacionesApi):
+    """Cliente de la API v1. Los métodos (``emitir_factura``, ``listar_clientes``...) salen del OpenAPI.
+
+    Los errores de la API se lanzan como :class:`ErrorApi`; un 429 se reintenta solo, esperando lo que pide ``Retry-After``.
+
+    :param clave: la clave de la API (``erp_...`` de producción, ``erp_test_...`` de sandbox).
+    :param base_url: la dirección de tu instalación. Producción y sandbox usan la misma.
+    :param max_reintentos: reintentos ante 429 (por defecto 2; 0 los desactiva).
+    :param espera_maxima: tope de la espera entre reintentos, en segundos; si el servidor pide más, falla con el 429.
+    :param timeout: tiempo máximo de cada pedido, en segundos (``None``: sin límite).
+    :param transporte: reemplaza el envío HTTP (pruebas).
+    :param dormir: reemplaza la espera (pruebas).
+    """
+
+    def __init__(
+        self,
+        clave: str,
+        base_url: str,
+        *,
+        max_reintentos: int = 2,
+        espera_maxima: float = 60.0,
+        timeout: Optional[float] = 30.0,
+        transporte: Optional[Transporte] = None,
+        dormir: Callable[[float], None] = time.sleep,
+    ) -> None:
+        if not clave:
+            raise ValueError("Falta la clave de la API (erp_... o erp_test_...).")
+        if not base_url.startswith(("http://", "https://")):
+            raise ValueError("base_url tiene que empezar con http:// o https://.")
+        self._clave = clave
+        self.base_url = base_url.rstrip("/")
+        #: La clave es de prueba: las facturas son simuladas, nada llega a ARCA ni a la contabilidad.
+        self.es_sandbox = clave.startswith(PREFIJO_SANDBOX)
+        self._max_reintentos = max_reintentos
+        self._espera_maxima = espera_maxima
+        self._timeout = timeout
+        self._transporte = transporte or _transporte_urllib
+        self._dormir = dormir
+
+    def _url(self, ruta: str, en_ruta: Optional[Dict[str, Any]], consulta: Optional[Dict[str, Any]]) -> str:
+        valores = en_ruta or {}
+        for nombre, valor in valores.items():
+            if valor is None:
+                raise ValueError(f"Falta el parámetro de ruta «{nombre}».")
+            ruta = ruta.replace("{" + nombre + "}", urllib.parse.quote(str(valor), safe=""))
+        pares = []
+        for k, v in (consulta or {}).items():
+            for x in v if isinstance(v, (list, tuple)) else [v]:
+                if x is not None:
+                    pares.append((k, "true" if x is True else "false" if x is False else str(x)))
+        texto = urllib.parse.urlencode(pares)
+        return f"{self.base_url}{ruta}{'?' + texto if texto else ''}"
+
+    def _pedir(
+        self,
+        metodo: str,
+        ruta: str,
+        *,
+        ruta_params: Optional[Dict[str, Any]] = None,
+        consulta: Optional[Dict[str, Any]] = None,
+        cabecera: Optional[Dict[str, Any]] = None,
+        cuerpo: Any = None,
+        respuesta: str = "json",
+        idempotency_key: Optional[str] = None,
+    ) -> Any:
+        cabeceras = {
+            "Authorization": f"Bearer {self._clave}",
+            "Accept": "*/*" if respuesta == "binario" else "application/json",
+            "User-Agent": "vektra-erp-python/1.0",
+        }
+        for k, v in (cabecera or {}).items():
+            if v is not None:
+                cabeceras[k] = str(v)
+        datos = None if cuerpo is None else json.dumps(cuerpo).encode("utf-8")
+        if datos is not None:
+            cabeceras["Content-Type"] = "application/json"
+        if idempotency_key:
+            cabeceras["Idempotency-Key"] = idempotency_key
+        url = self._url(ruta, ruta_params, consulta)
+
+        intento = 0
+        while True:
+            status, recibidas, bytes_ = self._transporte(metodo, url, cabeceras, datos, self._timeout)
+            request_id = recibidas.get("x-request-id")
+            retry_after = _leer_retry_after(recibidas.get("retry-after"))
+            if status == 429 and intento < self._max_reintentos:
+                espera = retry_after if retry_after is not None else float(2**intento)
+                if espera <= self._espera_maxima:
+                    self._dormir(espera)
+                    intento += 1
+                    continue
+            if status >= 400:
+                texto = bytes_.decode("utf-8", errors="replace")
+                try:
+                    cuerpo_error: Any = json.loads(texto) if texto else {}
+                except ValueError:
+                    cuerpo_error = texto
+                raise ErrorApi.desde_respuesta(status, cuerpo_error, request_id, retry_after)
+            if respuesta == "binario":
+                return bytes_
+            if respuesta == "vacio" or status == 204 or not bytes_:
+                return None
+            return json.loads(bytes_.decode("utf-8"))

vektra_erp-1.0.0/vektra_erp/errores.py

@@ -0,0 +1,83 @@
+"""Errores del SDK.
+
+La API responde todo error como ``{ error, code, campo?, request_id }`` (más los datos que la respuesta ya llevaba, por ejemplo la
+factura que quedó pendiente). También se entiende la forma anidada ``{ error: { code, message, field, request_id } }``.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Dict, Optional
+
+
+class ErrorVektra(Exception):
+    """Base de todos los errores del SDK."""
+
+
+class ErrorDeRed(ErrorVektra):
+    """No hubo respuesta: corte de red, tiempo agotado o servidor inalcanzable."""
+
+
+class ErrorApi(ErrorVektra):
+    """La API contestó con un error (HTTP 4xx o 5xx)."""
+
+    def __init__(
+        self,
+        status: int,
+        code: str,
+        message: str,
+        campo: Optional[str] = None,
+        request_id: Optional[str] = None,
+        retry_after: Optional[float] = None,
+        datos: Optional[Dict[str, Any]] = None,
+    ) -> None:
+        super().__init__(message)
+        self.status = status
+        #: Código estable para programar contra él (``validacion``, ``limite_pedidos``...).
+        self.code = code
+        self.message = message
+        #: El campo del pedido que falló (``cliente.documento``), si corresponde.
+        self.campo = campo
+        #: El ``X-Request-Id`` del pedido: mandalo a soporte.
+        self.request_id = request_id
+        #: Segundos que pidió esperar el servidor (``Retry-After``), si mandó.
+        self.retry_after = retry_after
+        #: El cuerpo completo de la respuesta (con la factura en un 422 ``pendiente_arca``).
+        self.datos: Dict[str, Any] = datos or {}
+
+    @property
+    def pendiente(self) -> bool:
+        """ARCA no confirmó el comprobante (422 ``pendiente_arca``): puede haberse autorizado igual.
+
+        No lo repitas sin la misma ``referencia`` o ``Idempotency-Key``; ``datos`` trae el comprobante tal como quedó.
+        """
+        return self.datos.get("pendiente") is True
+
+    def __str__(self) -> str:
+        extra = f" (campo {self.campo})" if self.campo else ""
+        return f"[{self.status} {self.code}] {self.message}{extra}"
+
+    @classmethod
+    def desde_respuesta(
+        cls, status: int, cuerpo: Any, request_id: Optional[str] = None, retry_after: Optional[float] = None
+    ) -> "ErrorApi":
+        """Arma el error desde el cuerpo ya leído de una respuesta no exitosa."""
+        datos = cuerpo if isinstance(cuerpo, dict) else {}
+        anidado = datos.get("error") if isinstance(datos.get("error"), dict) else None
+
+        def texto(valor: Any) -> Optional[str]:
+            return valor if isinstance(valor, str) and valor else None
+
+        mensaje = (
+            texto(anidado.get("message") if anidado else datos.get("error"))
+            or (cuerpo if isinstance(cuerpo, str) and cuerpo else None)
+            or f"HTTP {status}"
+        )
+        return cls(
+            status=status,
+            code=texto(anidado.get("code") if anidado else datos.get("code")) or "error_interno",
+            message=mensaje,
+            campo=texto(anidado.get("field") if anidado else datos.get("campo")),
+            request_id=texto(anidado.get("request_id") if anidado else datos.get("request_id")) or request_id,
+            retry_after=retry_after,
+            datos=datos,
+        )