Saldo & 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. 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())

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

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

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

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
}

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

Inizia

Funzionalità

Saldo e Fatturazione

Controlla il saldo dei crediti

Risposta

Acquista una ricarica

Requisiti

Risposte

Errori comuni

​Controlla il saldo dei crediti

​Risposta

​Acquista una ricarica

​Requisiti

​Risposte

​Errori comuni

Controlla il saldo dei crediti

Risposta

Acquista una ricarica

Requisiti

Risposte

Errori comuni