Saldo y facturación

Usa 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 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 del API, consulta Obtener información de crédito.

import requests

response = requests.get(
    "https://api.olostep.com/user/credits/info",
    headers={"Authorization": "Bearer <YOUR_API_KEY>"},
)
print(response.json())

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

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

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 utiliza `SUB_BASE` si no hay uno 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 de 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 del API, consulta Comprar recarga.

import requests

response = requests.post(
    "https://api.olostep.com/user/purchase-topup",
    headers={
        "Authorization": "Bearer <YOUR_API_KEY>",
        "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 <YOUR_API_KEY>",
    "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 <YOUR_API_KEY>" \
  -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 — el pago fue 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 son emitidos 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 intentar de nuevo

Recargas automáticas

Para evitar que tu saldo se agote, revísalo en un horario y compra una recarga cuando caiga por debajo de un umbral. Esto usa los dos endpoints anteriores y funciona en cualquier lugar donde puedas ejecutar un script: un trabajo cron, un paso de CI, una función sin servidor o un agente de IA antes de un trabajo grande.

Llama a GET /user/credits/info y lee credits.
Si credits está por debajo de tu umbral, llama a POST /user/purchase-topup con una de las cantidades soportadas.
En 200 o 202, detente. Los créditos llegan una vez que Stripe confirma el pago, así que no compres de nuevo en la siguiente verificación hasta que el saldo se haya actualizado.

import os
import requests

API = "https://api.olostep.com"
HEADERS = {"Authorization": f"Bearer {os.environ['OLOSTEP_API_KEY']}"}
THRESHOLD = 2000      # recargar cuando el saldo caiga por debajo de esto
TOPUP_CREDITS = 10000  # 10000, 20000, 80000, o 100000

credits = requests.get(f"{API}/user/credits/info", headers=HEADERS).json()["credits"]

if credits < THRESHOLD:
    res = requests.post(
        f"{API}/user/purchase-topup",
        headers=HEADERS,
        json={"credits": TOPUP_CREDITS},
    )
    print(res.status_code, res.json())
else:
    print(f"Saldo OK: {credits} créditos")

const API = "https://api.olostep.com"
const headers = {
  Authorization: `Bearer ${process.env.OLOSTEP_API_KEY}`,
  "Content-Type": "application/json",
}
const THRESHOLD = 2000 // recargar cuando el saldo caiga por debajo de esto
const TOPUP_CREDITS = 10000 // 10000, 20000, 80000, o 100000

const { credits } = await (await fetch(`${API}/user/credits/info`, { headers })).json()

if (credits < THRESHOLD) {
  const res = await fetch(`${API}/user/purchase-topup`, {
    method: "POST",
    headers,
    body: JSON.stringify({ credits: TOPUP_CREDITS }),
  })
  console.log(res.status, await res.json())
} else {
  console.log(`Saldo OK: ${credits} créditos`)
}

#!/usr/bin/env bash
# Requiere jq. Recargar cuando el saldo caiga por debajo de THRESHOLD.
THRESHOLD=2000
TOPUP_CREDITS=10000

credits=$(curl -s "https://api.olostep.com/user/credits/info" \
  -H "Authorization: Bearer $OLOSTEP_API_KEY" | jq '.credits')

if [ "$credits" -lt "$THRESHOLD" ]; then
  curl -s -X POST "https://api.olostep.com/user/purchase-topup" \
    -H "Authorization: Bearer $OLOSTEP_API_KEY" \
    -H "Content-Type: application/json" \
    -d "{\"credits\": $TOPUP_CREDITS}"
else
  echo "Saldo OK: $credits créditos"
fi

Para ejecutar la verificación cada hora con cron:

0 * * * * OLOSTEP_API_KEY=your_key /usr/bin/python3 /path/to/refill.py

Elige un umbral que cubra tu uso entre verificaciones. Si ejecutas la verificación cada hora y usas alrededor de 1,000 créditos por hora, un umbral de 2,000 deja un margen mientras se procesa una recarga.

Cada ejecución puede cargar tu tarjeta guardada. Ejecuta solo un trabajo de recarga por equipo y maneja 429 (purchase_topup_cooldown) y 503 (payment_status_unknown) esperando la siguiente verificación programada en lugar de intentar de nuevo de inmediato. Un 402 (payment_failed) significa que tu tarjeta fue rechazada; actualízala en el panel antes de la próxima ejecución.

Get Started

Features

Balance & Billing

Consulta el saldo de crédito

Respuesta

Compra una recarga

Requisitos

Respuestas

Errores comunes

Recargas automáticas

​Consulta el saldo de crédito

​Respuesta

​Compra una recarga

​Requisitos

​Respuestas

​Errores comunes

​Recargas automáticas

Consulta el saldo de crédito

Respuesta

Compra una recarga

Requisitos

Respuestas

Errores comunes

Recargas automáticas