ruraldte 0.1.0__tar.gz

ruraldte-0.1.0/.gitignore

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

ruraldte-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Comunidad Rural SpA (RuralDTE)
+
+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.

ruraldte-0.1.0/PKG-INFO

@@ -0,0 +1,68 @@
+Metadata-Version: 2.4
+Name: ruraldte
+Version: 0.1.0
+Summary: SDK Python del API v1 de RuralDTE — emisión de DTE ante el SII de Chile (emitir = encolar), folios/CAF, webhooks y API keys.
+Project-URL: Homepage, https://ruraldte.cl
+Project-URL: Documentation, https://ruraldte.cl/docs
+License-Expression: MIT
+License-File: LICENSE
+Keywords: boleta-electronica,chile,dte,factura-electronica,facturacion,sii
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Office/Business :: Financial
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+
+# ruraldte (Python)
+
+SDK Python del API v1 de [RuralDTE](https://ruraldte.cl) — emisión de documentos
+tributarios electrónicos (DTE) ante el SII de Chile. Cero dependencias (solo stdlib).
+
+## Instalación
+
+```bash
+pip install ruraldte
+```
+
+> Cobertura actual (MVP): `documents.emit`, `documents.list`, `documents.states`,
+> folios, emisores, webhooks y keys. El SDK TypeScript
+> ([`@ruraldte/sdk`](https://www.npmjs.com/package/@ruraldte/sdk)) cubre además
+> pagos, cesiones, conectores, intercambio, reportes y más — la API REST los
+> soporta todos aunque este SDK aún no.
+
+```python
+import os
+from ruraldte import RuralDte, RuralDteError
+
+rd = RuralDte(api_key=os.environ["RURALDTE_API_KEY"])
+
+# Emitir = encolar (202 { "status": "queued" }). El SII confirma asíncrono.
+try:
+    doc = rd.documents.emit({
+        "emisorId": "…",
+        "tipo": 33,                 # factura electrónica
+        "ambiente": "cert",
+        "receptor": {"rut": "11111111-1", "razonSocial": "ACME SpA"},
+        "montos": {"total": 1190, "neto": 1000, "iva": 190},  # CLP enteros
+    }, idempotency_key="orden-123")
+    print(doc["id"], doc["status"])
+
+    # Pollear el desenlace (o suscribir un webhook a dte.aceptado/dte.rechazado).
+    print(rd.documents.states(doc["id"]))
+except RuralDteError as e:
+    print(e.status, e.code, e.detail, "retryable:", e.is_retryable)
+```
+
+Recursos: `documents` (emit/list/states), `folios` (stock/request),
+`emisores` (list/create/upload_credential), `webhooks` (list/register/disable),
+`keys` (list/create/revoke).
+
+Config: `RuralDte(api_key, base_url=…, timeout=30)`. La key fija el ambiente
+permitido (`rdte_test_*` → test/cert, `rdte_live_*` → prod).
+
+Docs y OpenAPI: <https://ruraldte.cl/docs>
+
+Tests: `python3 -m unittest discover -s tests -t .`
+
+MIT © Comunidad Rural SpA

ruraldte-0.1.0/README.md

@@ -0,0 +1,52 @@
+# ruraldte (Python)
+
+SDK Python del API v1 de [RuralDTE](https://ruraldte.cl) — emisión de documentos
+tributarios electrónicos (DTE) ante el SII de Chile. Cero dependencias (solo stdlib).
+
+## Instalación
+
+```bash
+pip install ruraldte
+```
+
+> Cobertura actual (MVP): `documents.emit`, `documents.list`, `documents.states`,
+> folios, emisores, webhooks y keys. El SDK TypeScript
+> ([`@ruraldte/sdk`](https://www.npmjs.com/package/@ruraldte/sdk)) cubre además
+> pagos, cesiones, conectores, intercambio, reportes y más — la API REST los
+> soporta todos aunque este SDK aún no.
+
+```python
+import os
+from ruraldte import RuralDte, RuralDteError
+
+rd = RuralDte(api_key=os.environ["RURALDTE_API_KEY"])
+
+# Emitir = encolar (202 { "status": "queued" }). El SII confirma asíncrono.
+try:
+    doc = rd.documents.emit({
+        "emisorId": "…",
+        "tipo": 33,                 # factura electrónica
+        "ambiente": "cert",
+        "receptor": {"rut": "11111111-1", "razonSocial": "ACME SpA"},
+        "montos": {"total": 1190, "neto": 1000, "iva": 190},  # CLP enteros
+    }, idempotency_key="orden-123")
+    print(doc["id"], doc["status"])
+
+    # Pollear el desenlace (o suscribir un webhook a dte.aceptado/dte.rechazado).
+    print(rd.documents.states(doc["id"]))
+except RuralDteError as e:
+    print(e.status, e.code, e.detail, "retryable:", e.is_retryable)
+```
+
+Recursos: `documents` (emit/list/states), `folios` (stock/request),
+`emisores` (list/create/upload_credential), `webhooks` (list/register/disable),
+`keys` (list/create/revoke).
+
+Config: `RuralDte(api_key, base_url=…, timeout=30)`. La key fija el ambiente
+permitido (`rdte_test_*` → test/cert, `rdte_live_*` → prod).
+
+Docs y OpenAPI: <https://ruraldte.cl/docs>
+
+Tests: `python3 -m unittest discover -s tests -t .`
+
+MIT © Comunidad Rural SpA

ruraldte-0.1.0/pyproject.toml

@@ -0,0 +1,27 @@
+[project]
+name = "ruraldte"
+version = "0.1.0"
+description = "SDK Python del API v1 de RuralDTE — emisión de DTE ante el SII de Chile (emitir = encolar), folios/CAF, webhooks y API keys."
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+requires-python = ">=3.9"
+dependencies = []  # solo stdlib (urllib): cero dependencias en runtime
+keywords = ["dte", "sii", "chile", "factura-electronica", "boleta-electronica", "facturacion"]
+classifiers = [
+  "Development Status :: 4 - Beta",
+  "Intended Audience :: Developers",
+  "Programming Language :: Python :: 3",
+  "Topic :: Office/Business :: Financial",
+]
+
+[project.urls]
+Homepage = "https://ruraldte.cl"
+Documentation = "https://ruraldte.cl/docs"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["ruraldte"]

ruraldte-0.1.0/ruraldte/__init__.py

@@ -0,0 +1,19 @@
+# ruraldte · SDK Python del API v1 de RuralDTE.
+#   from ruraldte import RuralDte
+#   rd = RuralDte(api_key=os.environ["RURALDTE_API_KEY"])
+#   doc = rd.documents.emit({...})   # 202 {"status": "queued"}
+from __future__ import annotations
+
+from .client import DEFAULT_BASE_URL, RuralDte
+from .constants import CERTIFIED_TIPOS, SCOPES, WEBHOOK_EVENTS
+from .errors import RuralDteError
+
+__all__ = [
+    "RuralDte",
+    "RuralDteError",
+    "DEFAULT_BASE_URL",
+    "CERTIFIED_TIPOS",
+    "WEBHOOK_EVENTS",
+    "SCOPES",
+]
+__version__ = "0.0.0"

ruraldte-0.1.0/ruraldte/client.py

@@ -0,0 +1,162 @@
+# ============================================================================
+# ruraldte · cliente del API v1 (stdlib, sin dependencias)
+# ----------------------------------------------------------------------------
+# Cliente fino sobre urllib. Auth por API key: Authorization: Bearer rdte_*.
+# La key NUNCA se loguea. "emitir = encolar": documents.emit() devuelve 202
+# {"status": "queued"} — pollea documents.states() o usa webhooks para el cierre.
+# Montos: SIEMPRE pesos CLP enteros (sin centavos).
+# ============================================================================
+from __future__ import annotations
+
+import json
+import urllib.error
+import urllib.parse
+import urllib.request
+from typing import Any, Optional
+
+from .errors import RuralDteError
+
+# Backend en vivo. En producción, apúntalo a https://api.ruraldte.cl cuando el
+# dominio enrute /functions/v1/* a las edge functions.
+DEFAULT_BASE_URL = "https://wfaijmddlkrwkqhlmcwm.supabase.co/functions/v1"
+
+
+class RuralDte:
+    def __init__(
+        self,
+        api_key: str,
+        base_url: str = DEFAULT_BASE_URL,
+        timeout: float = 30.0,
+        opener: Any = None,
+    ) -> None:
+        if not api_key:
+            raise RuralDteError(0, "config", "api_key es requerido")
+        self._api_key = api_key
+        self._base_url = base_url.rstrip("/")
+        self._timeout = timeout
+        # opener inyectable (tests). Default: el de urllib.
+        self._opener = opener or urllib.request.build_opener()
+        self.documents = _Documents(self)
+        self.folios = _Folios(self)
+        self.emisores = _Emisores(self)
+        self.webhooks = _Webhooks(self)
+        self.keys = _Keys(self)
+
+    def _request(
+        self,
+        method: str,
+        fn: str,
+        path: str = "",
+        query: Optional[dict] = None,
+        body: Optional[Any] = None,
+        idempotency_key: Optional[str] = None,
+    ) -> Any:
+        url = f"{self._base_url}/{fn}{path}"
+        if query:
+            items = {k: v for k, v in query.items() if v is not None}
+            if items:
+                url += "?" + urllib.parse.urlencode(items)
+
+        headers = {"authorization": f"Bearer {self._api_key}"}
+        data = None
+        if body is not None:
+            data = json.dumps(body).encode("utf-8")
+            headers["content-type"] = "application/json"
+        if idempotency_key:
+            headers["idempotency-key"] = idempotency_key
+
+        req = urllib.request.Request(url, data=data, headers=headers, method=method)
+        try:
+            with self._opener.open(req, timeout=self._timeout) as resp:
+                text = resp.read().decode("utf-8")
+                return json.loads(text) if text else {}
+        except urllib.error.HTTPError as e:
+            raw = e.read().decode("utf-8") if e.fp is not None else ""
+            try:
+                payload = json.loads(raw) if raw else {}
+            except ValueError:
+                payload = {}
+            raise RuralDteError(
+                e.code, payload.get("error", "error"), payload.get("detail", str(e.reason))
+            ) from None
+        except urllib.error.URLError as e:
+            raise RuralDteError(0, "network_error", str(e.reason)) from None
+
+
+class _Documents:
+    def __init__(self, c: "RuralDte") -> None:
+        self._c = c
+
+    def emit(self, input: dict, idempotency_key: Optional[str] = None) -> Any:
+        """Emitir = encolar (202). Pasa idempotency_key para reintentos seguros."""
+        return self._c._request("POST", "v1-documents", body=input, idempotency_key=idempotency_key)
+
+    def list(self, limit: Optional[int] = None) -> Any:
+        return self._c._request("GET", "v1-documents", query={"limit": limit})
+
+    def states(self, id: str) -> Any:
+        return self._c._request("GET", "v1-documents", path=f"/{id}/states")
+
+
+class _Folios:
+    def __init__(self, c: "RuralDte") -> None:
+        self._c = c
+
+    def stock(self, emisor_id: Optional[str] = None) -> Any:
+        return self._c._request("GET", "v1-folios", query={"emisorId": emisor_id})
+
+    def request(self, emisor_id: str, tipo: int, cantidad: int) -> Any:
+        return self._c._request(
+            "POST", "v1-folios", path="/request",
+            body={"emisorId": emisor_id, "tipo": tipo, "cantidad": cantidad},
+        )
+
+    def gaps(self, emisor_id: Optional[str] = None) -> Any:
+        """Folios QUEMADOS sin que el SII los viera (huecos a declarar — Declaración de Avance)."""
+        return self._c._request("GET", "v1-folios", path="/gaps", query={"emisorId": emisor_id})
+
+
+class _Emisores:
+    def __init__(self, c: "RuralDte") -> None:
+        self._c = c
+
+    def list(self) -> Any:
+        return self._c._request("GET", "v1-emisores")
+
+    def create(self, input: dict) -> Any:
+        return self._c._request("POST", "v1-emisores", body=input)
+
+    def upload_credential(self, emisor_id: str, input: dict) -> Any:
+        return self._c._request("POST", "v1-emisores", path=f"/{emisor_id}/credentials", body=input)
+
+    def revoke_credential(self, emisor_id: str) -> Any:
+        """Revoca el certificado activo del emisor (deja de descifrarse para firmar)."""
+        return self._c._request("POST", "v1-emisores", path=f"/{emisor_id}/credentials/revoke")
+
+
+class _Webhooks:
+    def __init__(self, c: "RuralDte") -> None:
+        self._c = c
+
+    def list(self) -> Any:
+        return self._c._request("GET", "v1-webhooks")
+
+    def register(self, url: str, events: Optional[list] = None) -> Any:
+        return self._c._request("POST", "v1-webhooks", body={"url": url, "events": events or []})
+
+    def disable(self, id: str) -> Any:
+        return self._c._request("POST", "v1-webhooks", path=f"/{id}/disable")
+
+
+class _Keys:
+    def __init__(self, c: "RuralDte") -> None:
+        self._c = c
+
+    def list(self) -> Any:
+        return self._c._request("GET", "v1-keys")
+
+    def create(self, input: Optional[dict] = None) -> Any:
+        return self._c._request("POST", "v1-keys", body=input or {})
+
+    def revoke(self, id: str) -> Any:
+        return self._c._request("POST", "v1-keys", path=f"/{id}/revoke")

ruraldte-0.1.0/ruraldte/constants.py

@@ -0,0 +1,22 @@
+# ============================================================================
+# ruraldte · catálogos (espejo del backend, para referencia/validación local)
+# ============================================================================
+from __future__ import annotations
+
+# Tipos de DTE certificados que el API acepta emitir.
+CERTIFIED_TIPOS = (39, 41, 33, 34, 52, 56, 61, 110, 111, 112)
+
+# Eventos de webhook (suscríbete a un subconjunto, o a todos con []).
+WEBHOOK_EVENTS = (
+    "dte.encolado",
+    "dte.aceptado",
+    "dte.con_reparos",
+    "dte.rechazado",
+    "dte.manual_pending",
+    "folios.bajos",
+    "sii.incidente",
+    "sii.recuperado",
+)
+
+# Scopes finos que una API key puede pedir ([] = sin restricción).
+SCOPES = ("dte:create", "dte:read", "caf:read", "emisores:read", "webhooks:write")

ruraldte-0.1.0/ruraldte/errors.py

@@ -0,0 +1,28 @@
+# ============================================================================
+# ruraldte · errores tipados
+# ----------------------------------------------------------------------------
+# Toda falla del API se levanta como RuralDteError. El envelope del servidor es
+# {"error": <código>, "detail": <mensaje>} + el status HTTP. status=0 = falla de
+# cliente (red/timeout).
+# ============================================================================
+from __future__ import annotations
+
+
+class RuralDteError(Exception):
+    """Error del API de RuralDTE."""
+
+    def __init__(self, status: int, code: str, detail: str) -> None:
+        super().__init__(f"[{code}] {detail}")
+        self.status = status  # HTTP status (0 = red/timeout/cliente)
+        self.code = code  # código estable del API (campo "error")
+        self.detail = detail  # mensaje legible (campo "detail")
+
+    @property
+    def is_auth(self) -> bool:
+        """401/403: key inválida/revocada o sin scope/ambiente."""
+        return self.status in (401, 403)
+
+    @property
+    def is_retryable(self) -> bool:
+        """Conviene reintentar: red (0), rate-limit (429) o 5xx."""
+        return self.status == 0 or self.status == 429 or self.status >= 500

ruraldte-0.1.0/tests/test_client.py

@@ -0,0 +1,129 @@
+# ============================================================================
+# ruraldte · tests OFFLINE (opener mockeado, sin red). Corre con:
+#   python3 -m unittest discover -s tests -t .
+# ============================================================================
+from __future__ import annotations
+
+import io
+import json
+import unittest
+import urllib.error
+
+from ruraldte import RuralDte, RuralDteError
+
+BASE = "https://api.test/v1"
+
+
+class FakeResp:
+    def __init__(self, body: str) -> None:
+        self._b = body.encode("utf-8")
+
+    def read(self) -> bytes:
+        return self._b
+
+    def __enter__(self) -> "FakeResp":
+        return self
+
+    def __exit__(self, *a: object) -> bool:
+        return False
+
+
+class FakeOpener:
+    """Reemplaza urllib opener: captura los requests y responde/levanta canned."""
+
+    def __init__(self, body: str = "{}", error: Exception | None = None) -> None:
+        self.body = body
+        self.error = error
+        self.requests: list = []
+
+    def open(self, req, timeout=None):  # noqa: ANN001
+        self.requests.append(req)
+        if self.error is not None:
+            raise self.error
+        return FakeResp(self.body)
+
+
+class TestClient(unittest.TestCase):
+    def test_requires_api_key(self):
+        with self.assertRaises(RuralDteError):
+            RuralDte("")
+
+    def test_emit_post_headers_body(self):
+        op = FakeOpener(json.dumps({"id": "doc-1", "folio": 7, "status": "queued"}))
+        rd = RuralDte("rdte_test_abc", base_url=BASE, opener=op)
+        res = rd.documents.emit({"emisorId": "em-1", "tipo": 33}, idempotency_key="k1")
+        self.assertEqual(res["id"], "doc-1")
+        req = op.requests[0]
+        self.assertEqual(req.method, "POST")
+        self.assertEqual(req.full_url, f"{BASE}/v1-documents")
+        self.assertEqual(req.headers["Authorization"], "Bearer rdte_test_abc")
+        self.assertEqual(req.headers["Idempotency-key"], "k1")
+        self.assertIn(b'"emisorId"', req.data)
+
+    def test_base_url_trailing_slash(self):
+        op = FakeOpener(json.dumps({"documents": []}))
+        rd = RuralDte("k", base_url=BASE + "/", opener=op)
+        rd.documents.list()
+        self.assertEqual(op.requests[0].full_url, f"{BASE}/v1-documents")
+
+    def test_list_limit_query(self):
+        op = FakeOpener(json.dumps({"documents": []}))
+        rd = RuralDte("k", base_url=BASE, opener=op)
+        rd.documents.list(limit=50)
+        self.assertEqual(op.requests[0].full_url, f"{BASE}/v1-documents?limit=50")
+
+    def test_states_path(self):
+        op = FakeOpener(json.dumps({"id": "doc-1", "states": []}))
+        rd = RuralDte("k", base_url=BASE, opener=op)
+        rd.documents.states("doc-1")
+        self.assertEqual(op.requests[0].full_url, f"{BASE}/v1-documents/doc-1/states")
+
+    def test_folios_stock_and_request(self):
+        op = FakeOpener(json.dumps({"stock": []}))
+        rd = RuralDte("k", base_url=BASE, opener=op)
+        rd.folios.stock(emisor_id="em-9")
+        self.assertEqual(op.requests[0].full_url, f"{BASE}/v1-folios?emisorId=em-9")
+
+        op2 = FakeOpener(json.dumps({"tipo": 33, "cantidad": 50}))
+        rd2 = RuralDte("k", base_url=BASE, opener=op2)
+        rd2.folios.request(emisor_id="em-9", tipo=33, cantidad=50)
+        self.assertEqual(op2.requests[0].method, "POST")
+        self.assertEqual(op2.requests[0].full_url, f"{BASE}/v1-folios/request")
+
+    def test_http_error_maps_to_ruraldteerror(self):
+        err = urllib.error.HTTPError(
+            f"{BASE}/v1-documents", 409, "Conflict", {},
+            io.BytesIO(b'{"error":"caf_missing","detail":"no hay CAF"}'),
+        )
+        rd = RuralDte("k", base_url=BASE, opener=FakeOpener(error=err))
+        with self.assertRaises(RuralDteError) as ctx:
+            rd.documents.emit({})
+        self.assertEqual(ctx.exception.status, 409)
+        self.assertEqual(ctx.exception.code, "caf_missing")
+        self.assertEqual(ctx.exception.detail, "no hay CAF")
+        self.assertFalse(ctx.exception.is_auth)
+        self.assertFalse(ctx.exception.is_retryable)
+
+    def test_auth_and_retryable_flags(self):
+        err401 = urllib.error.HTTPError(BASE, 401, "Unauthorized", {}, io.BytesIO(b'{"error":"unauthorized","detail":"x"}'))
+        rd = RuralDte("k", base_url=BASE, opener=FakeOpener(error=err401))
+        with self.assertRaises(RuralDteError) as c1:
+            rd.documents.list()
+        self.assertTrue(c1.exception.is_auth)
+
+        err503 = urllib.error.HTTPError(BASE, 503, "Unavailable", {}, io.BytesIO(b'{"error":"x","detail":"y"}'))
+        rd2 = RuralDte("k", base_url=BASE, opener=FakeOpener(error=err503))
+        with self.assertRaises(RuralDteError) as c2:
+            rd2.documents.list()
+        self.assertTrue(c2.exception.is_retryable)
+
+    def test_network_error(self):
+        rd = RuralDte("k", base_url=BASE, opener=FakeOpener(error=urllib.error.URLError("refused")))
+        with self.assertRaises(RuralDteError) as ctx:
+            rd.documents.list()
+        self.assertEqual(ctx.exception.status, 0)
+        self.assertEqual(ctx.exception.code, "network_error")
+
+
+if __name__ == "__main__":
+    unittest.main()