Solde & facturation

Utilisez les points de terminaison de facturation utilisateur pour lire le solde de crédits de votre équipe et acheter des recharges avec un moyen de paiement enregistré. Les deux points de terminaison nécessitent une authentification avec votre clé API. Les clés invalides renvoient 402.

Vérifier le solde de crédits

GET /user/credits/info renvoie le solde de crédits de l’équipe authentifiée, une répartition par lot, les détails de l’abonnement actif et si l’utilisation est autorisée. Utilisez ce point de terminaison pour alimenter des widgets de facturation, des tableaux de bord d’utilisation ou des vérifications préalables avant d’exécuter de gros travaux. Pour les détails de l’API, voir Obtenir des informations sur les crédits.

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

Réponse

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

Champ	Description
`credits`	Total des crédits restants sur tous les lots non expirés
`breakdown`	Détail par lot : type, unités allouées et restantes, expiration
`active_subscription`	Plan actuel (repli sur `SUB_BASE` si aucun n’est actif)
`allow_usage`	Si l’équipe peut encore consommer des crédits

Chaque lot dans breakdown a un purchase_kind de Subscription, Top-up, Manual, Setup ou Pending.

Acheter une recharge

POST /user/purchase-topup débite une carte enregistrée sur Stripe et achète des crédits en une seule étape. Il n’y a pas de redirection vers Checkout ni d’interface de paiement intégrée. Passez le montant des crédits dans le corps de la requête :

{ "credits": 10000 }

Champ	Description
`credits`	Nombre de crédits à acheter

Valeurs prises en charge : 10,000, 20,000, 80,000, et 100,000. Pour les détails de l’API, voir Acheter une recharge.

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}'

Exigences

L’équipe doit avoir un client Stripe avec au moins une carte enregistrée.
Une seule tentative d’achat est autorisée toutes les 60 secondes par équipe. Si vous atteignez le délai d’attente, la réponse est 429 avec un en-tête Retry-After.

Réponses

200 — paiement réussi :

{
  "success": true,
  "payment_intent_id": "pi_xxx",
  "credits": 10000
}

202 — le paiement est toujours en cours de traitement. Les crédits sont ajoutés une fois que Stripe confirme le paiement :

{
  "success": true,
  "status": "processing",
  "payment_intent_id": "pi_xxx",
  "message": "Le paiement est en cours de traitement. Les crédits seront ajoutés une fois le paiement confirmé.",
  "credits": 10000
}

Les crédits sont émis par le webhook Stripe après confirmation du paiement, et non directement à partir de la réponse HTTP. Considérez 200 comme un succès de paiement ; interrogez GET /user/credits/info si vous devez confirmer le solde mis à jour.

Erreurs courantes

Statut	Erreur	Quand
400	`missing_topup_selector`	`credits` n’a pas été envoyé
400	`invalid_credits`	Le montant des crédits n’est pas dans la liste autorisée
400	`no_stripe_customer`	L’équipe n’a pas de client Stripe
400	`no_payment_method`	Aucune carte enregistrée
402	`payment_failed`	Aucune carte enregistrée n’a complété le débit
429	`purchase_topup_cooldown`	Un autre achat a été tenté dans les 60 secondes
503	`payment_status_unknown`	Erreur Stripe ambiguë ; attendez avant de réessayer

Recharges automatiques

Pour éviter que votre solde ne s’épuise, vérifiez-le selon un calendrier et achetez une recharge lorsqu’il tombe en dessous d’un seuil. Cela utilise les deux points de terminaison ci-dessus et fonctionne partout où vous pouvez exécuter un script : une tâche cron, une étape CI, une fonction sans serveur ou un agent IA avant un gros travail.

Appelez GET /user/credits/info et lisez credits.
Si credits est en dessous de votre seuil, appelez POST /user/purchase-topup avec l’un des montants pris en charge.
Sur 200 ou 202, arrêtez. Les crédits arrivent une fois que Stripe confirme le paiement, donc n’achetez pas à nouveau lors de la prochaine vérification tant que le solde n’a pas été mis à jour.

import os
import requests

API = "https://api.olostep.com"
HEADERS = {"Authorization": f"Bearer {os.environ['OLOSTEP_API_KEY']}"}
THRESHOLD = 2000      # recharge lorsque le solde tombe en dessous de ce seuil
TOPUP_CREDITS = 10000  # 10000, 20000, 80000, ou 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"Solde OK : {credits} crédits")

const API = "https://api.olostep.com"
const headers = {
  Authorization: `Bearer ${process.env.OLOSTEP_API_KEY}`,
  "Content-Type": "application/json",
}
const THRESHOLD = 2000 // recharge lorsque le solde tombe en dessous de ce seuil
const TOPUP_CREDITS = 10000 // 10000, 20000, 80000, ou 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(`Solde OK : ${credits} crédits`)
}

#!/usr/bin/env bash
# Nécessite jq. Recharge lorsque le solde tombe en dessous 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 "Solde OK : $credits crédits"
fi

Pour exécuter la vérification toutes les heures avec cron :

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

Choisissez un seuil qui couvre votre utilisation entre les vérifications. Si vous exécutez la vérification toutes les heures et utilisez environ 1 000 crédits par heure, un seuil de 2 000 laisse une marge pendant qu’une recharge est en cours de traitement.

Chaque exécution peut débiter votre carte enregistrée. N’exécutez qu’un seul travail de recharge par équipe, et gérez 429 (purchase_topup_cooldown) et 503 (payment_status_unknown) en attendant la prochaine vérification programmée au lieu de réessayer immédiatement. Un 402 (payment_failed) signifie que votre carte a été refusée ; mettez-la à jour dans le tableau de bord avant la prochaine exécution.

Commencer

Fonctionnalités

Solde et Facturation

Vérifier le solde de crédits

Réponse

Acheter une recharge

Exigences

Réponses

Erreurs courantes

Recharges automatiques