> ## Documentation Index
> Fetch the complete documentation index at: https://docs.olostep.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Saldo & fatturazione

> Controlla il saldo dei tuoi crediti e acquista ricariche in modo programmato.

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](/get-started/authentication). 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](/api-reference/billing/credits-info).

<CodeGroup>
  ```python Python theme={null}
  import requests

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

  ```js Node theme={null}
  const res = await fetch("https://api.olostep.com/user/credits/info", {
    headers: { Authorization: "Bearer <API-TOKEN>" },
  })
  console.log(await res.json())
  ```

  ```bash cURL theme={null}
  curl -s "https://api.olostep.com/user/credits/info" \
    -H "Authorization: Bearer <API-TOKEN>"
  ```
</CodeGroup>

### Risposta

```json theme={null}
{
  "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:

```json theme={null}
{ "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](/api-reference/billing/purchase-topup).

<CodeGroup>
  ```python Python theme={null}
  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())
  ```

  ```js Node theme={null}
  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())
  ```

  ```bash cURL theme={null}
  curl -s -X POST "https://api.olostep.com/user/purchase-topup" \
    -H "Authorization: Bearer <API-TOKEN>" \
    -H "Content-Type: application/json" \
    -d '{"credits": 10000}'
  ```
</CodeGroup>

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

```json theme={null}
{
  "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:

```json theme={null}
{
  "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
}
```

<Note>
  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.
</Note>

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