cobrala 1.0.0__tar.gz

cobrala-1.0.0/.gitignore

@@ -0,0 +1,16 @@
+*.egg-info/
+*.py[cod]
+.cache/
+.coverage
+.env
+.env.*
+.mypy_cache/
+.pytest_cache/
+.ruff_cache/
+.venv*/
+.venv/
+__pycache__/
+build/
+dist/
+htmlcov/
+venv/

cobrala-1.0.0/.gitlab-ci.yml

@@ -0,0 +1,87 @@
+# CI del paquete. La raíz del repositorio es el paquete.
+#
+# Publicar es empujar un tag:
+#
+#     git tag -a v1.0.0 -m "1.0.0" && git push --tags
+#
+# El tag corre lint, tipos y tests; recién si pasan se construye y se sube a
+# PyPI. La subida usa trusted publishing (OIDC), así que no hay ningún token
+# guardado en el repositorio.
+
+stages:
+  - check
+  - build
+  - publish
+
+default:
+  image: python:3.12
+  cache:
+    key:
+      files:
+        - pyproject.toml
+    paths:
+      - .cache/pip
+  before_script:
+    - pip install -e ".[dev]"
+
+variables:
+  PIP_CACHE_DIR: "$CI_PROJECT_DIR/.cache/pip"
+
+# Verificación
+
+lint:
+  stage: check
+  script:
+    - ruff check src tests
+    - mypy
+
+# Los tests no usan la red ni a Cobrala: un servidor local contesta lo que pide
+# cada test, y las rutas se comparan con el OpenAPI de tests/fixtures/.
+test:
+  stage: check
+  parallel:
+    matrix:
+      - PYTHON: ["3.9", "3.10", "3.11", "3.12", "3.13"]
+  image: python:$PYTHON
+  script:
+    - pytest -q
+
+# Empaquetado y publicación, solo con tag
+
+build:
+  stage: build
+  rules:
+    - if: $CI_COMMIT_TAG
+  before_script:
+    - pip install build twine
+  script:
+    # El tag y la versión del paquete tienen que decir lo mismo: si no, se
+    # publicaría una versión distinta de la que quedó marcada en el historial.
+    - |
+      VERSION=$(python -c "import tomllib; print(tomllib.load(open('pyproject.toml','rb'))['project']['version'])")
+      if [ "$CI_COMMIT_TAG" != "v$VERSION" ]; then
+        echo "El tag es $CI_COMMIT_TAG y pyproject.toml dice $VERSION."
+        echo "Esperaba el tag v$VERSION."
+        exit 1
+      fi
+    - python -m build
+    - twine check dist/*
+  artifacts:
+    paths:
+      - dist/
+    expire_in: 1 month
+
+publish:
+  stage: publish
+  rules:
+    - if: $CI_COMMIT_TAG
+  dependencies:
+    - build
+  id_tokens:
+    PYPI_ID_TOKEN:
+      aud: pypi
+  before_script:
+    - pip install -U twine
+  # Sin usuario ni contraseña: twine detecta el token OIDC y lo canjea solo.
+  script:
+    - twine upload dist/*

cobrala-1.0.0/CHANGELOG.md

@@ -0,0 +1,26 @@
+# Changelog
+
+Los cambios notables de cada versión. El formato sigue
+[Keep a Changelog](https://keepachangelog.com/es-ES/1.1.0/) y el versionado es
+[semántico](https://semver.org/lang/es/).
+
+## [1.0.0] - 2026-11-14
+
+Primera versión publicada.
+
+### Agregado
+
+- Una función por cada ruta de la Access API (`/v1`): el catálogo (planes,
+  productos y features), los clientes (crearlos, editarlos y cambiarles el
+  código, y el link del portal), los permisos (verificar, consumir sin contar dos
+  veces, fijar el consumo y sincronizar), las suscripciones (bajas, cambios de
+  plan y su vista previa), los cobros (el link de pago y el comprobante), los
+  documentos y el checkout de suscripciones y de productos.
+- `every`, para recorrer una lista página por página.
+- `verify_webhook`, que verifica la firma de un webhook sobre el cuerpo crudo, y
+  `entitlement_rows`, que les pone nombre a las filas de los permisos.
+- `CobralaError` con el código estable de cada rechazo; `unreachable` cuando
+  Cobrala no contesta.
+- Los `429` se reintentan dos veces, esperando lo que dice `Retry-After`.
+- `AsyncCobrala`, con los mismos métodos para `await`.
+- Sin dependencias: solo la biblioteca estándar, Python 3.9 o más.

cobrala-1.0.0/LICENSE

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

cobrala-1.0.0/PKG-INFO

@@ -0,0 +1,114 @@
+Metadata-Version: 2.5
+Name: cobrala
+Version: 1.0.0
+Summary: Python SDK for the Access API of Cobrala: plans, entitlements, usage and checkout
+Project-URL: Homepage, https://cobrala.com.py/
+Project-URL: Documentación de la API, https://access-api.cobrala.com.py/docs
+Author: Araitek
+License-Expression: MIT
+License-File: LICENSE
+Keywords: checkout,cobrala,cobros,entitlements,paraguay,suscripciones
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Developers
+Classifier: Natural Language :: Spanish
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Typing :: Typed
+Requires-Python: >=3.9
+Provides-Extra: dev
+Requires-Dist: mypy>=1.8; extra == 'dev'
+Requires-Dist: pytest>=7; extra == 'dev'
+Requires-Dist: ruff>=0.4; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# cobrala (Python)
+
+SDK de la Access API de Cobrala, para Python 3.9 o más y sin dependencias. Envuelve cada ruta de la API, que además publica su OpenAPI en `/docs`, y se autentica con `X-API-Key: sk_...`. La versión para TypeScript y JavaScript tiene las mismas funciones: `npm install cobrala`.
+
+```bash
+pip install cobrala
+```
+
+```python
+from cobrala import Cobrala, CobralaError, verify_webhook
+
+cobrala = Cobrala(api_key="sk_...", base_url="https://access-api.cobrala.com.py")
+
+# Mostrar los planes en tu sitio
+for plan in cobrala.every(cobrala.plans):
+    print(plan["name"], plan["intervals"][0]["prices"][0]["price"])
+
+# Vender: abrí la url que vuelve
+sale = cobrala.checkout_subscription(
+    price_id=17, client_code="USR-42", legal_name="Ana", email="ana@example.com",
+    return_url="https://example.com/gracias",
+)
+
+# Verificar y consumir
+if cobrala.verify("USR-42", "facturas")["allowed"]:
+    cobrala.consume("USR-42", "facturas", idempotency_key="factura-9921")
+
+# Un rechazo tiene su código
+try:
+    cobrala.change_plan(sale["subscription_id"], price_id=18, actor="customer")
+except CobralaError as error:
+    if error.code == "grace_pay_first":
+        ...
+
+# Un webhook, sobre el cuerpo crudo
+valid = verify_webhook(secret, raw_body, headers["X-Webhook-Timestamp"], headers["X-Webhook-Signature"])
+```
+
+`AsyncCobrala` tiene los mismos métodos, para `await`. El SDK no guarda respuestas: lo que dice la API tiene que estar bien siempre.
+
+## Lo que resolvés en tu sistema
+
+**La clave va solo en tu servidor.** Nunca en el navegador ni en una app móvil: quien la tenga hace todo lo que sus permisos dejan. Cada clave es de un servicio.
+
+**Qué campo es el `client_code`.** Elegí un dato que tu sistema ya tenga, único y que no cambie: el id de tu usuario, por ejemplo `USR-42`. Es lo que une a tu usuario con su cliente en Cobrala.
+- Si tu usuario ya existe, mandalo en el checkout. Si el cliente no existe en Cobrala, se crea en la misma llamada con el nombre y el correo que mandes.
+- Si todavía no tiene cuenta (la página de precios abierta), no mandes código: Cobrala crea un cliente con un código generado (`CLI-8F3A21BC`) y lo devuelve junto con la dirección. Guardalo al abrirle la cuenta, o cambialo por el tuyo con `PATCH /v1/clients/{code}`.
+- Cobrala nunca une clientes por correo: el mismo correo con otro código es otro cliente, porque dos personas pueden compartirlo. Para unir a uno que ya estaba cargado, buscalo con `GET /v1/clients?email=` y cambiale el código.
+
+**Verificar en vivo o con una copia.** Las dos cosas son válidas:
+- En vivo, `POST /v1/entitlements/verify` en cada acción sensible: siempre dice lo correcto, y cuenta contra el límite de 50 pedidos por segundo de tu clave.
+- Con copia, `GET /v1/entitlements/sync` para armar menús y pantallas sin un pedido por feature. Cada fila trae `resets_at` y el vencimiento más cercano: un reinicio o un vencimiento no es un cambio y no te llega como tal, así que tu copia tiene que mirar esas fechas.
+
+**Cada cuánto sincronizar.** Lo normal: el webhook `entitlements.changed` en el momento y, por las dudas, una sincronización cada 15 minutos con `since` igual al `as_of` de la anterior. Sin webhooks, sincronizá más seguido y al entrar cada usuario.
+
+**Qué hacer si Cobrala no contesta.** Lo decidís vos según tu negocio. Con copia local, seguí con lo último que sabés. Sin copia, elegí entre dejar pasar (mejor para el usuario) o cortar (mejor para una feature cara), y dejalo escrito en tu código. El SDK reintenta solo los `429`, dos veces, esperando lo que dice `Retry-After`; si Cobrala no contesta, da un error con el código `unreachable`.
+
+**Registrar consumo sin contar dos veces.** Mandá `idempotency_key` en cada consumo, con un valor propio del evento (`factura-9921`). Si reintentás con la misma clave, la API contesta lo que contestó y no suma.
+
+**Vender.** Tu servidor pide el checkout con el `price_id` y abre la `url` que vuelve: es la página de Cobrala, donde el cliente paga. El resultado nunca lo dice la vuelta del navegador: confirmalo por webhook o verificando. El `return_url` es solo el botón "Volver a" de esa página.
+
+**Cambiar de plan.** Con `operator` rige en el acto o se programa, y la diferencia sigue el flujo normal. Con `customer`, subir primero se paga por la `url` que devuelve y bajar se programa. `POST /v1/subscriptions/{id}/change-plan/preview` dice qué va a pasar antes de confirmar.
+
+**Webhooks.** Verificá la firma sobre el cuerpo crudo, antes de parsearlo; el SDK trae la función. Las filas de `entitlements.changed` y de la sincronización tienen la misma forma, `[incluida, límite, resets_at, vencimiento]`, y el SDK trae otra función que les pone nombre.
+
+## Lo que necesita cada función
+
+| Qué hace | Ruta | Permiso |
+|---|---|---|
+| Planes, productos, features | `GET /v1/plans`, `/v1/products`, `/v1/features` | `plans`, `products`, `features` |
+| Clientes | `GET /v1/clients`, `/v1/clients/{code}` | `clients` |
+| Crear y editar clientes | `POST /v1/clients`, `PATCH /v1/clients/{code}` | `clients_write` |
+| Verificar y sincronizar | `POST /v1/entitlements/verify`, `GET /v1/entitlements/sync` | `entitlements` |
+| Consumir o fijar el consumo | `POST /v1/entitlements/consume`, `/set` | `entitlements_write` |
+| Ver suscripciones y preview del cambio | `GET /v1/subscriptions`, `POST .../change-plan/preview` | `subscriptions` |
+| Bajas y cambios de plan | `POST .../cancel`, `.../cancel/revert`, `.../change-plan`, `.../change-plan/cancel` | `subscriptions_write` |
+| Ver cobros y pedir su link | `GET /v1/payments`, `POST /v1/payments/{id}/pay-link` | `payments` |
+| Subir un comprobante | `POST /v1/payments/{id}/receipt` | `payments_receipt` |
+| Documentos y su PDF | `GET /v1/documents` | `documents` |
+| Vender | `POST /v1/checkout/subscription`, `/product` | `checkout` |
+| Abrir el portal ya autenticado | `POST /v1/clients/{code}/portal-link` | `portal` |
+
+Los rechazos son siempre `{"code": ..., "message": ..., "data": {...}}`, y el `code` es estable. Con la cuenta congelada, la clave lee pero no escribe (`account_frozen`); sin la API en el plan, contesta `plan_without_api`.
+
+## Licencia
+
+MIT. Ver [`LICENSE`](LICENSE).

cobrala-1.0.0/README.md

@@ -0,0 +1,87 @@
+# cobrala (Python)
+
+SDK de la Access API de Cobrala, para Python 3.9 o más y sin dependencias. Envuelve cada ruta de la API, que además publica su OpenAPI en `/docs`, y se autentica con `X-API-Key: sk_...`. La versión para TypeScript y JavaScript tiene las mismas funciones: `npm install cobrala`.
+
+```bash
+pip install cobrala
+```
+
+```python
+from cobrala import Cobrala, CobralaError, verify_webhook
+
+cobrala = Cobrala(api_key="sk_...", base_url="https://access-api.cobrala.com.py")
+
+# Mostrar los planes en tu sitio
+for plan in cobrala.every(cobrala.plans):
+    print(plan["name"], plan["intervals"][0]["prices"][0]["price"])
+
+# Vender: abrí la url que vuelve
+sale = cobrala.checkout_subscription(
+    price_id=17, client_code="USR-42", legal_name="Ana", email="ana@example.com",
+    return_url="https://example.com/gracias",
+)
+
+# Verificar y consumir
+if cobrala.verify("USR-42", "facturas")["allowed"]:
+    cobrala.consume("USR-42", "facturas", idempotency_key="factura-9921")
+
+# Un rechazo tiene su código
+try:
+    cobrala.change_plan(sale["subscription_id"], price_id=18, actor="customer")
+except CobralaError as error:
+    if error.code == "grace_pay_first":
+        ...
+
+# Un webhook, sobre el cuerpo crudo
+valid = verify_webhook(secret, raw_body, headers["X-Webhook-Timestamp"], headers["X-Webhook-Signature"])
+```
+
+`AsyncCobrala` tiene los mismos métodos, para `await`. El SDK no guarda respuestas: lo que dice la API tiene que estar bien siempre.
+
+## Lo que resolvés en tu sistema
+
+**La clave va solo en tu servidor.** Nunca en el navegador ni en una app móvil: quien la tenga hace todo lo que sus permisos dejan. Cada clave es de un servicio.
+
+**Qué campo es el `client_code`.** Elegí un dato que tu sistema ya tenga, único y que no cambie: el id de tu usuario, por ejemplo `USR-42`. Es lo que une a tu usuario con su cliente en Cobrala.
+- Si tu usuario ya existe, mandalo en el checkout. Si el cliente no existe en Cobrala, se crea en la misma llamada con el nombre y el correo que mandes.
+- Si todavía no tiene cuenta (la página de precios abierta), no mandes código: Cobrala crea un cliente con un código generado (`CLI-8F3A21BC`) y lo devuelve junto con la dirección. Guardalo al abrirle la cuenta, o cambialo por el tuyo con `PATCH /v1/clients/{code}`.
+- Cobrala nunca une clientes por correo: el mismo correo con otro código es otro cliente, porque dos personas pueden compartirlo. Para unir a uno que ya estaba cargado, buscalo con `GET /v1/clients?email=` y cambiale el código.
+
+**Verificar en vivo o con una copia.** Las dos cosas son válidas:
+- En vivo, `POST /v1/entitlements/verify` en cada acción sensible: siempre dice lo correcto, y cuenta contra el límite de 50 pedidos por segundo de tu clave.
+- Con copia, `GET /v1/entitlements/sync` para armar menús y pantallas sin un pedido por feature. Cada fila trae `resets_at` y el vencimiento más cercano: un reinicio o un vencimiento no es un cambio y no te llega como tal, así que tu copia tiene que mirar esas fechas.
+
+**Cada cuánto sincronizar.** Lo normal: el webhook `entitlements.changed` en el momento y, por las dudas, una sincronización cada 15 minutos con `since` igual al `as_of` de la anterior. Sin webhooks, sincronizá más seguido y al entrar cada usuario.
+
+**Qué hacer si Cobrala no contesta.** Lo decidís vos según tu negocio. Con copia local, seguí con lo último que sabés. Sin copia, elegí entre dejar pasar (mejor para el usuario) o cortar (mejor para una feature cara), y dejalo escrito en tu código. El SDK reintenta solo los `429`, dos veces, esperando lo que dice `Retry-After`; si Cobrala no contesta, da un error con el código `unreachable`.
+
+**Registrar consumo sin contar dos veces.** Mandá `idempotency_key` en cada consumo, con un valor propio del evento (`factura-9921`). Si reintentás con la misma clave, la API contesta lo que contestó y no suma.
+
+**Vender.** Tu servidor pide el checkout con el `price_id` y abre la `url` que vuelve: es la página de Cobrala, donde el cliente paga. El resultado nunca lo dice la vuelta del navegador: confirmalo por webhook o verificando. El `return_url` es solo el botón "Volver a" de esa página.
+
+**Cambiar de plan.** Con `operator` rige en el acto o se programa, y la diferencia sigue el flujo normal. Con `customer`, subir primero se paga por la `url` que devuelve y bajar se programa. `POST /v1/subscriptions/{id}/change-plan/preview` dice qué va a pasar antes de confirmar.
+
+**Webhooks.** Verificá la firma sobre el cuerpo crudo, antes de parsearlo; el SDK trae la función. Las filas de `entitlements.changed` y de la sincronización tienen la misma forma, `[incluida, límite, resets_at, vencimiento]`, y el SDK trae otra función que les pone nombre.
+
+## Lo que necesita cada función
+
+| Qué hace | Ruta | Permiso |
+|---|---|---|
+| Planes, productos, features | `GET /v1/plans`, `/v1/products`, `/v1/features` | `plans`, `products`, `features` |
+| Clientes | `GET /v1/clients`, `/v1/clients/{code}` | `clients` |
+| Crear y editar clientes | `POST /v1/clients`, `PATCH /v1/clients/{code}` | `clients_write` |
+| Verificar y sincronizar | `POST /v1/entitlements/verify`, `GET /v1/entitlements/sync` | `entitlements` |
+| Consumir o fijar el consumo | `POST /v1/entitlements/consume`, `/set` | `entitlements_write` |
+| Ver suscripciones y preview del cambio | `GET /v1/subscriptions`, `POST .../change-plan/preview` | `subscriptions` |
+| Bajas y cambios de plan | `POST .../cancel`, `.../cancel/revert`, `.../change-plan`, `.../change-plan/cancel` | `subscriptions_write` |
+| Ver cobros y pedir su link | `GET /v1/payments`, `POST /v1/payments/{id}/pay-link` | `payments` |
+| Subir un comprobante | `POST /v1/payments/{id}/receipt` | `payments_receipt` |
+| Documentos y su PDF | `GET /v1/documents` | `documents` |
+| Vender | `POST /v1/checkout/subscription`, `/product` | `checkout` |
+| Abrir el portal ya autenticado | `POST /v1/clients/{code}/portal-link` | `portal` |
+
+Los rechazos son siempre `{"code": ..., "message": ..., "data": {...}}`, y el `code` es estable. Con la cuenta congelada, la clave lee pero no escribe (`account_frozen`); sin la API en el plan, contesta `plan_without_api`.
+
+## Licencia
+
+MIT. Ver [`LICENSE`](LICENSE).

cobrala-1.0.0/pyproject.toml

@@ -0,0 +1,56 @@
+[build-system]
+requires = ["hatchling>=1.27"]
+build-backend = "hatchling.build"
+
+[project]
+name = "cobrala"
+version = "1.0.0"
+description = "Python SDK for the Access API of Cobrala: plans, entitlements, usage and checkout"
+readme = "README.md"
+requires-python = ">=3.9"
+license = "MIT"
+authors = [{ name = "Araitek" }]
+keywords = ["cobrala", "suscripciones", "cobros", "entitlements", "checkout", "paraguay"]
+classifiers = [
+    "Development Status :: 5 - Production/Stable",
+    "Intended Audience :: Developers",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Typing :: Typed",
+    "Natural Language :: Spanish",
+]
+dependencies = []
+
+[project.urls]
+Homepage = "https://cobrala.com.py/"
+"Documentación de la API" = "https://access-api.cobrala.com.py/docs"
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=7",
+    "mypy>=1.8",
+    "ruff>=0.4",
+]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/cobrala"]
+
+[tool.ruff]
+line-length = 125
+target-version = "py39"
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "B", "SIM"]
+
+[tool.mypy]
+strict = true
+files = ["src/cobrala"]
+# The SDK returns the JSON of the API as it arrived, without its own types.
+warn_return_any = false
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

cobrala-1.0.0/src/cobrala/__init__.py

@@ -0,0 +1,18 @@
+"""
+cobrala: the Python SDK of the Access API of Cobrala.
+
+    from cobrala import Cobrala
+
+    cobrala = Cobrala(api_key="sk_...", base_url="https://access-api.cobrala.com.py")
+    verdict = cobrala.verify("USR-42", "invoices")
+    if verdict["allowed"]:
+        cobrala.consume("USR-42", "invoices", idempotency_key="factura-1")
+
+It keeps no answers: what the API says has to be right every time. Only the
+standard library is needed. ``AsyncCobrala`` has the same methods, to
+``await``.
+"""
+from .client import AsyncCobrala, Cobrala, CobralaError, entitlement_rows
+from .webhooks import verify_webhook
+
+__all__ = ["AsyncCobrala", "Cobrala", "CobralaError", "entitlement_rows", "verify_webhook"]