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 @araitek/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 conPATCH /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/verifyen 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/syncpara armar menús y pantallas sin un pedido por feature. Cada fila traeresets_aty 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.1
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| cobrala-1.0.1.tar.gz | 24.1 kB | Without provenance | Details for cobrala-1.0.1.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| cobrala-1.0.1-py3-none-any.whl | Python 3 | none | any | Details for cobrala-1.0.1-py3-none-any.whl |
Total release size: 33.8 kB
Release files / cobrala-1.0.1.tar.gz
| Download URL | cobrala-1.0.1.tar.gz |
|---|---|
| Size | 24.1 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
e42f873ed57f0a88c4069451475b4fc41870f21e3d197256493703ac3cb39d55
|
|
BLAKE2b-256 checksum How to use checksums |
05083e0a369c81cee5a0e292ca9b91fafd5cd2bb92208b5fd5f404800510bea9
|
| 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.1-py3-none-any.whl
| Download URL | cobrala-1.0.1-py3-none-any.whl |
|---|---|
| Size | 9.7 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
2a4d8a2ca58b0bcda81f16fe28b1f572ec98b18ba395941ee272acd3f3c9a474
|
|
BLAKE2b-256 checksum How to use checksums |
1ab9c3a7923bc597e24af0b7258a97cacfa2cbea4401b719f94ab167a50dd63c
|
| 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.1
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.