Saldo e fatturazione

Utilizza gli endpoint di fatturazione utente per leggere il saldo dei crediti del tuo team e acquistare ricariche con un metodo di pagamento salvato. Entrambi gli endpoint richiedono l’autenticazione con la tua chiave API. Le chiavi non valide restituiscono 402.

Controlla il saldo dei crediti

GET /user/credits/info restituisce il saldo dei crediti del team autenticato, una suddivisione per lotto, i dettagli dell’abbonamento attivo e se l’uso è consentito. Usa questo endpoint per alimentare widget di fatturazione, dashboard di utilizzo o controlli preliminari prima di eseguire lavori di grandi dimensioni. Per i dettagli dell’API, vedi Ottieni informazioni sui crediti.

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

Risposta

{
  "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	Descrizione
`credits`	Totale dei crediti rimanenti su tutti i lotti non scaduti
`breakdown`	Dettaglio per lotto: tipo, unità allocate e rimanenti, scadenza
`active_subscription`	Piano attuale (predefinito su `SUB_BASE` se nessuno è attivo)
`allow_usage`	Se il team può ancora consumare crediti

Ogni lotto in breakdown ha un purchase_kind di Subscription, Top-up, Manual, Setup, o Pending.

Acquista una ricarica

POST /user/purchase-topup addebita una carta salvata su Stripe e acquista crediti in un solo passaggio. Non c’è reindirizzamento al Checkout o interfaccia di pagamento incorporata. Passa l’importo dei crediti nel corpo della richiesta:

{ "credits": 10000 }

Campo	Descrizione
`credits`	Numero di crediti da acquistare

Valori supportati: 10,000, 20,000, 80,000, e 100,000. Per i dettagli dell’API, vedi Acquista ricarica.

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

Requisiti

Il team deve avere un cliente Stripe con almeno una carta salvata.
È consentito un solo tentativo di acquisto ogni 60 secondi per team. Se raggiungi il cooldown, la risposta è 429 con un’intestazione Retry-After.

Risposte

200 — pagamento riuscito:

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

202 — il pagamento è ancora in elaborazione. I crediti vengono aggiunti una volta che Stripe conferma il pagamento:

{
  "success": true,
  "status": "processing",
  "payment_intent_id": "pi_xxx",
  "message": "Il pagamento è in elaborazione. I crediti verranno aggiunti una volta confermato il pagamento.",
  "credits": 10000
}

I crediti vengono emessi dal webhook di Stripe dopo la conferma del pagamento, non direttamente dalla risposta HTTP. Tratta 200 come successo del pagamento; esegui il polling di GET /user/credits/info se hai bisogno di confermare il saldo aggiornato.

Errori comuni

Stato	Errore	Quando
400	`missing_topup_selector`	`credits` non è stato inviato
400	`invalid_credits`	L’importo dei crediti non è nella lista consentita
400	`no_stripe_customer`	Il team non ha un cliente Stripe
400	`no_payment_method`	Nessuna carta salvata in archivio
402	`payment_failed`	Nessuna carta salvata ha completato l’addebito
429	`purchase_topup_cooldown`	È stato tentato un altro acquisto entro 60 secondi
503	`payment_status_unknown`	Errore ambiguo di Stripe; attendi prima di riprovare

Ricariche automatiche

Per evitare che il tuo saldo si esaurisca, controllalo a intervalli regolari e acquista una ricarica quando scende sotto una soglia. Questo utilizza i due endpoint sopra e funziona ovunque tu possa eseguire uno script: un cron job, un passaggio CI, una funzione serverless o un agente AI prima di un lavoro di grandi dimensioni.

Chiama GET /user/credits/info e leggi credits.
Se credits è sotto la tua soglia, chiama POST /user/purchase-topup con uno degli importi supportati.
Su 200 o 202, fermati. I crediti arrivano una volta che Stripe conferma il pagamento, quindi non acquistare di nuovo al prossimo controllo finché il saldo non è aggiornato.

import os
import requests

API = "https://api.olostep.com"
HEADERS = {"Authorization": f"Bearer {os.environ['OLOSTEP_API_KEY']}"}
THRESHOLD = 2000      # ricarica quando il saldo scende sotto questo valore
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} crediti")

const API = "https://api.olostep.com"
const headers = {
  Authorization: `Bearer ${process.env.OLOSTEP_API_KEY}`,
  "Content-Type": "application/json",
}
const THRESHOLD = 2000 // ricarica quando il saldo scende sotto questo valore
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} crediti`)
}

#!/usr/bin/env bash
# Richiede jq. Ricarica quando il saldo scende sotto 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 crediti"
fi

Per eseguire il controllo ogni ora con cron:

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

Scegli una soglia che copra il tuo utilizzo tra i controlli. Se esegui il controllo ogni ora e usi circa 1.000 crediti all’ora, una soglia di 2.000 lascia un margine mentre una ricarica è in elaborazione.

Ogni esecuzione può addebitare la tua carta salvata. Esegui solo un lavoro di ricarica per team e gestisci 429 (purchase_topup_cooldown) e 503 (payment_status_unknown) aspettando il prossimo controllo programmato invece di riprovare subito. Un 402 (payment_failed) significa che la tua carta è stata rifiutata; aggiornala nel dashboard prima della prossima esecuzione.

Get Started

Features

Balance & Billing

Controlla il saldo dei crediti

Risposta

Acquista una ricarica

Requisiti

Risposte

Errori comuni

Ricariche automatiche

​Controlla il saldo dei crediti

​Risposta

​Acquista una ricarica

​Requisiti

​Risposte

​Errori comuni

​Ricariche automatiche

Controlla il saldo dei crediti

Risposta

Acquista una ricarica

Requisiti

Risposte

Errori comuni

Ricariche automatiche