Saldo y facturación

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())

const res = await fetch("https://api.olostep.com/user/credits/info", {
  headers: { Authorization: "Bearer <API-TOKEN>" },
})
console.log(await res.json())

curl -s "https://api.olostep.com/user/credits/info" \
  -H "Authorization: Bearer <API-TOKEN>"

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

Cada lote en 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:

{ "credits": 10000 }

Campo	Descripción
`credits`	Número de créditos a comprar

Valores soportados: 10,000, 20,000, 80,000, y 100,000. Para detalles de la API, consulta Compra de recarga.

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())

const res = await fetch("https://api.olostep.com/user/purchase-topup", {
  method: "POST",
  headers: {
    Authorization: "Bearer <API-TOKEN>",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ credits: 10000 }),
})
console.log(res.status)
console.log(await res.json())

curl -s -X POST "https://api.olostep.com/user/purchase-topup" \
  -H "Authorization: Bearer <API-TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{"credits": 10000}'

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
}

202 — el pago aún se está procesando. Los créditos se añaden una vez que Stripe confirma el pago:

{
  "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

Comenzar

Características

Saldo y facturación

Consulta el saldo de crédito

Respuesta

Compra una recarga

Requisitos

Respuestas

Errores comunes

​Consulta el saldo de crédito

​Respuesta

​Compra una recarga

​Requisitos

​Respuestas

​Errores comunes

Consulta el saldo de crédito

Respuesta

Compra una recarga

Requisitos

Respuestas

Errores comunes