Skip to main content

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.

pip install cobrala
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.

Metadata

Release files for cobrala 1.0.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for cobrala 1.0.0
File Size Uploaded Provenance Actions
cobrala-1.0.0.tar.gz 24.0 kB Without provenance Details for cobrala-1.0.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for cobrala 1.0.0
File Interpreter ABI Platform Actions
cobrala-1.0.0-py3-none-any.whl Python 3 none any Details for cobrala-1.0.0-py3-none-any.whl

Total release size: 33.7 kB

Release files / cobrala-1.0.0.tar.gz

Download URL cobrala-1.0.0.tar.gz
Size 24.0 kB
Tags Source
SHA-256 checksum
How to use checksums
c1850ae74b37088650dcde39c9548645e280e03fefeb3395685323bbb1c598c2
BLAKE2b-256 checksum
How to use checksums
a5c18cb0b3df9078ac5a8692e4cd853d52b69d590ec75e8c7c8afb62e5fdcdb0
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.12.16

Release files / cobrala-1.0.0-py3-none-any.whl

Download URL cobrala-1.0.0-py3-none-any.whl
Size 9.7 kB
Tags Python 3
SHA-256 checksum
How to use checksums
9f3c692291f6cf80e85c10e6f8e59b05df8b58f2af1005b9df38b91c53c1b9fb
BLAKE2b-256 checksum
How to use checksums
4b8a06af704f21514943ba42bad4442f6bfb194d24ea0525bc67587752251ecd
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.12.16

Security for cobrala 1.0.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

1.0.0 This release

2 release files No provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page