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. 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.
Utilizza 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 <API-TOKEN>"},
)
print(response.json())
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 | Crediti totali rimanenti in tutti i lotti non scaduti |
breakdown | Dettaglio per lotto: tipo, unità allocate e rimanenti, scadenza |
active_subscription | Piano attuale (predefinito SUB_BASE se nessuno è attivo) |
allow_usage | Se il team può ancora consumare crediti |
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 a Checkout o interfaccia di pagamento incorporata.
Passa l’importo dei crediti nel corpo della richiesta:
| Campo | Descrizione |
|---|
credits | Numero di crediti da acquistare |
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())
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 superi il tempo di attesa, la risposta è 429 con un’intestazione
Retry-After.
Risposte
200 — pagamento riuscito:
{
"success": true,
"payment_intent_id": "pi_xxx",
"credits": 10000
}
{
"success": true,
"status": "processing",
"payment_intent_id": "pi_xxx",
"message": "Il pagamento è in elaborazione. I crediti verranno aggiunti una volta che il pagamento sarà confermato.",
"credits": 10000
}
I crediti vengono emessi dal webhook di Stripe dopo la conferma del pagamento, non direttamente dalla risposta HTTP. Considera 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 nel file |
| 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 |
