# Documentazione della API di SMS Nitro

Tutto quello che serve per acquistare un numero temporaneo, leggere il codice di verifica e chiudere l’ordine dal tuo codice. JSON su HTTPS, una chiave API, gli stessi prezzi e la stessa regola di addebito della dashboard.

## Come funziona la API di SMS Nitro?

Invii POST /v1/orders con app e paese e ricevi un numero di telefono. Poi interroghi GET /v1/orders/{id} ogni 3-5 secondi finché l’SMS compare in messages e chiami finish. Se l’SMS non arriva, annulli e l’importo bloccato torna sul saldo: paghi solo i codici che arrivano.

## Avvio rapido in quattro chiamate

1. **Crea la chiave** Fai la prima ricarica, apri Dashboard > API e genera la chiave. Inviala nell’intestazione X-Api-Key.
2. **Acquista un numero** POST /v1/orders con product e country. Il prezzo viene bloccato sul saldo.
3. **Leggi il codice** Interroga GET /v1/orders/{id} ogni 3-5 secondi finché messages contiene l’SMS.
4. **Chiudi l’ordine** POST finish se il codice ha funzionato, oppure cancel se non è arrivato nulla, per riavere l’importo.

## La API in sintesi

| Voce | Valore |
|---|---|
| URL di base | https://smsnitro.com/api/v1 |
| Formato | JSON su HTTPS, UTF-8. Prezzi come stringa decimale (USD), date in ISO 8601 (UTC) |
| Autenticazione | Intestazione X-Api-Key, oppure Authorization: Bearer |
| Addebito | Prezzo bloccato all’acquisto, addebitato solo quando arriva l’SMS, rimborsato altrimenti |
| Durata del numero | Fino a 20 minuti per attivazione |
| Limiti | 500 acquisti al minuto, 30 richieste di nuovo invio al minuto |
| Specifica | OpenAPI 3.1 su /developers/openapi.json |

## La tua prima richiesta

Verifica che la chiave funzioni leggendo il saldo. Una risposta 200 con balance e frozen significa che puoi già acquistare numeri. Frozen è l’importo bloccato dagli ordini che aspettano ancora un SMS.

**Richiesta**

```bash
curl https://smsnitro.com/api/v1/balance \
  -H "X-Api-Key: $SMSNITRO_API_KEY"
```

**Risposta**

```json
{
  "balance": "12.50",
  "frozen": "0.45",
  "currency": "USD"
}
```

## FAQ

**Esiste un ambiente di prova?** No. Le chiamate usano il catalogo reale, ma senza SMS non viene addebitato nulla, quindi provare il flusso completo costa solo i codici che ricevi davvero.

**I prezzi via API sono diversi da quelli della dashboard?** No. La API usa lo stesso catalogo, gli stessi prezzi e lo stesso saldo del sito, senza maggiorazioni.

**Dove si trova la specifica OpenAPI?** Il documento OpenAPI 3.1 degli endpoint pubblici è su https://smsnitro.com/developers/openapi.json. Importalo in Postman, Insomnia o in un generatore di codice.

**Come ottengo una chiave API?** Crea l’account, fai la prima ricarica e genera la chiave in Dashboard > API. Ogni account ha una sola chiave attiva.

## Articoli

- [Autenticazione](https://smsnitro.com/it/sviluppatori/autenticazione): Come autenticarsi alla API di SMS Nitro: dove generare la chiave, le intestazioni X-Api-Key e Bearer, come sostituirla e perché non deve mai stare nel front-end.
- [Riferimento degli endpoint](https://smsnitro.com/it/sviluppatori/endpoint): Tutti gli endpoint della API REST v1 di SMS Nitro: saldo, servizi, paesi, ordini, finish, cancel, resend e ban, con parametri, richieste curl e risposte JSON.
- [Ciclo dell’ordine e addebito](https://smsnitro.com/it/sviluppatori/ciclo-dell-ordine): Cosa significa ogni stato dell’ordine su SMS Nitro, quando il saldo viene addebitato o rimborsato, quanto dura il numero e quando annullare o chiedere un altro SMS.
- [Errori e limiti d’uso](https://smsnitro.com/it/sviluppatori/errori): I codici HTTP restituiti dalla API di SMS Nitro (400, 401, 402, 404, 409, 429, 502), cosa significa ciascuno, i limiti d’uso e una strategia di nuovi tentativi.
- [Verifica via SMS in Python](https://smsnitro.com/it/sviluppatori/python): Ricevi codici di verifica via SMS in Python con la API di SMS Nitro e requests: acquista il numero, attendi il codice, completa o annulla. Script completo.
- [Verifica via SMS in Node.js](https://smsnitro.com/it/sviluppatori/nodejs): Ricevi codici di verifica via SMS in Node.js 18+ con fetch e la API di SMS Nitro: acquista il numero, attendi il codice, completa o annulla. Con tipi TypeScript.
- [Verifica via SMS in PHP](https://smsnitro.com/it/sviluppatori/php): Ricevi codici di verifica via SMS in PHP 8 con cURL e la API di SMS Nitro: acquista il numero, attendi il codice, completa o annulla. Script completo da copiare.

Fonte: https://smsnitro.com/it/sviluppatori