Utiliza los endpoints de facturación de usuario para leer el saldo de crédito de tu equipo y comprar recargas con un método de pago guardado. Ambos endpoints requieren autenticación con tu clave API. Las claves inválidas devuelven 402.
Consulta el saldo de crédito
GET /user/credits/info devuelve el saldo de crédito del equipo autenticado, un desglose por lote, detalles de la suscripción activa y si se permite el uso.
Usa este endpoint para alimentar widgets de facturación, tableros de uso o verificaciones previas antes de ejecutar trabajos grandes.
Para detalles de la API, consulta Obtener información de crédito.
import requests
response = requests.get(
"https://api.olostep.com/user/credits/info",
headers={"Authorization": "Bearer <API-TOKEN>"},
)
print(response.json())
Respuesta
{
"credits": 12500,
"breakdown": [
{
"purchase_kind": "Subscription",
"allocated_units": 10000,
"remaining_units": 8500,
"expiry_date": 1735689600
},
{
"purchase_kind": "Top-up",
"allocated_units": 5000,
"remaining_units": 4000,
"expiry_date": 1743465600
}
],
"active_subscription": {
"id": "SUB_PRO",
"display_name": "Pro",
"credits": 10000,
"created_at": 1704067200
},
"allow_usage": true
}
| Campo | Descripción |
|---|
credits | Créditos totales restantes en todos los lotes no vencidos |
breakdown | Detalle por lote: tipo, unidades asignadas y restantes, vencimiento |
active_subscription | Plan actual (se usa SUB_BASE si ninguno está activo) |
allow_usage | Si el equipo aún puede consumir créditos |
breakdown tiene un purchase_kind de Subscription, Top-up, Manual, Setup o Pending.
Compra una recarga
POST /user/purchase-topup carga una tarjeta guardada en Stripe y compra créditos en un solo paso. No hay redirección a Checkout ni interfaz de pago incrustada.
Pasa la cantidad de créditos en el cuerpo de la solicitud:
| Campo | Descripción |
|---|
credits | Número de créditos a comprar |
import requests
response = requests.post(
"https://api.olostep.com/user/purchase-topup",
headers={
"Authorization": "Bearer <API-TOKEN>",
"Content-Type": "application/json",
},
json={"credits": 10000},
)
print(response.status_code)
print(response.json())
Requisitos
- El equipo debe tener un cliente de Stripe con al menos una tarjeta guardada.
- Solo se permite un intento de compra cada 60 segundos por equipo. Si alcanzas el tiempo de espera, la respuesta es 429 con un encabezado
Retry-After.
Respuestas
200 — pago exitoso:
{
"success": true,
"payment_intent_id": "pi_xxx",
"credits": 10000
}
{
"success": true,
"status": "processing",
"payment_intent_id": "pi_xxx",
"message": "El pago está en proceso. Los créditos se añadirán una vez que el pago sea confirmado.",
"credits": 10000
}
Los créditos se emiten por el webhook de Stripe después de la confirmación del pago, no directamente desde la respuesta HTTP. Trata 200 como éxito de pago; consulta GET /user/credits/info si necesitas confirmar el saldo actualizado.
Errores comunes
| Estado | Error | Cuándo |
|---|
| 400 | missing_topup_selector | credits no fue enviado |
| 400 | invalid_credits | La cantidad de créditos no está en la lista permitida |
| 400 | no_stripe_customer | El equipo no tiene un cliente de Stripe |
| 400 | no_payment_method | No hay tarjeta guardada en el archivo |
| 402 | payment_failed | Ninguna tarjeta guardada completó el cargo |
| 429 | purchase_topup_cooldown | Se intentó otra compra dentro de los 60 segundos |
| 503 | payment_status_unknown | Error ambiguo de Stripe; espera antes de reintentar |
