# Riferimento degli endpoint

Dieci endpoint coprono l’intero flusso: controllare il saldo, consultare app e paesi, acquistare un numero, leggere l’SMS e chiudere l’ordine.

## Quali endpoint ha la API di SMS Nitro?

GET /v1/balance, GET /v1/services, GET /v1/services/{product}/countries, POST /v1/orders, GET /v1/orders, GET /v1/orders/{id} e POST /v1/orders/{id}/finish, /cancel, /resend e /ban. Si trovano tutti sotto https://smsnitro.com/api e richiedono l’intestazione X-Api-Key.

## Tutti gli endpoint

| Endpoint | Cosa fa |
|---|---|
| GET /v1/balance | Saldo disponibile e importo bloccato dagli ordini aperti (USD) |
| GET /v1/services | App disponibili con il prezzo di partenza. Facoltativi: country, server (1 o 2), search |
| GET /v1/services/{product}/countries | Paesi di un’app con prezzo, tasso di successo e prefisso. Facoltativo: server |
| POST /v1/orders | Acquista un numero. Corpo: product (obbligatorio), country, operator, server |
| GET /v1/orders | I tuoi ordini, dal più recente. Facoltativi: limit (da 1 a 100, predefinito 50), offset |
| GET /v1/orders/{id} | Un ordine sincronizzato in tempo reale: qui compare l’SMS |
| POST /v1/orders/{id}/finish | Chiude l’attivazione dopo aver usato il codice |
| POST /v1/orders/{id}/cancel | Annulla prima di qualsiasi SMS e rimborsa l’importo bloccato |
| POST /v1/orders/{id}/resend | Chiede un altro SMS sullo stesso numero, dopo il primo codice |
| POST /v1/orders/{id}/ban | Restituisce un numero che l’app segnala come già usato |

## Consultare app e paesi

Usa gli endpoint del catalogo per scegliere cosa acquistare. Il valore di product (per esempio telegram) è l’identificativo da inviare all’acquisto. Nell’elenco dei paesi, rate3 e rate24 sono i tassi recenti di consegna in percentuale, e offers mostra il prezzo di ogni server.

**App disponibili in un paese**

```bash
curl "https://smsnitro.com/api/v1/services?country=usa" \
  -H "X-Api-Key: $SMSNITRO_API_KEY"
```

**Risposta**

```json
[
  { "product": "telegram", "price": "0.30", "count": 850,
    "rate": null, "countries": [], "countries_count": 120 }
]
```

**Paesi di un’app**

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

**Risposta**

```json
[
  {
    "country": "usa", "name": "United States", "iso": "us", "dial_code": "+1",
    "price": "0.45", "count": 1200, "rate3": 95.0, "rate24": null, "server": 1,
    "offers": [
      { "server": 1, "price": "0.45", "count": 1200, "rate3": 95.0 },
      { "server": 2, "price": "0.52", "count": 300, "rate3": 88.0 }
    ]
  }
]
```

## Acquistare un numero

Invia product e country. Il paese accetta l’identificativo del catalogo (usa, england), il codice ISO (gb) o il nome in inglese, e il valore predefinito è usa. Ometti server per lasciare che la API scelga il migliore. La risposta è l’ordine con stato PENDING e il numero da inserire nell’app.

| Campo | Descrizione |
|---|---|
| product | Obbligatorio. Identificativo dell’app in GET /v1/services |
| country | Facoltativo. Identificativo del catalogo, ISO 3166-1 alpha-2 o nome in inglese. Predefinito: usa |
| operator | Facoltativo. Operatore, predefinito any |
| server | Facoltativo. 1 o 2. Senza: automatico |

**Richiesta**

```bash
curl -X POST https://smsnitro.com/api/v1/orders \
  -H "X-Api-Key: $SMSNITRO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"product": "telegram", "country": "usa"}'
```

**Risposta (201 Created)**

```json
{
  "id": 123456,
  "provider_order_id": "987654321",
  "country": "usa",
  "operator": "any",
  "product": "telegram",
  "phone": "+12025550123",
  "status": "PENDING",
  "price": "0.45",
  "created_at": "2026-10-24T12:00:00Z",
  "expires": "2026-10-24T12:20:00Z",
  "messages": [],
  "awaiting_resend": false,
  "server": 1
}
```

## Leggere l’SMS

Interroga l’ordine ogni 3-5 secondi. Quando arriva l’SMS lo stato diventa RECEIVED e messages contiene il mittente, il testo completo e il codice estratto. Usa code quando è valorizzato; se è vuoto, leggi text.

**Richiesta**

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

**Risposta dopo l’SMS**

```json
{
  "id": 123456,
  "phone": "+12025550123",
  "status": "RECEIVED",
  "price": "0.45",
  "expires": "2026-10-24T12:20:00Z",
  "messages": [
    {
      "sender": "Telegram",
      "text": "Telegram code: 48291",
      "code": "48291",
      "received_at": "2026-10-24T12:01:10Z"
    }
  ],
  "awaiting_resend": false,
  "server": 1
}
```

## Completare, annullare, richiedere o restituire

Ogni azione restituisce l’ordine aggiornato. Le regole su quando è consentita ciascuna sono nella pagina del ciclo dell’ordine.

**Azioni sull’ordine**

```bash
# Done: the code worked
curl -X POST https://smsnitro.com/api/v1/orders/123456/finish -H "X-Api-Key: $SMSNITRO_API_KEY"

# No SMS: cancel and get the frozen amount back
curl -X POST https://smsnitro.com/api/v1/orders/123456/cancel -H "X-Api-Key: $SMSNITRO_API_KEY"

# Another SMS on the same number (after the first code, no extra cost)
curl -X POST https://smsnitro.com/api/v1/orders/123456/resend -H "X-Api-Key: $SMSNITRO_API_KEY"

# The app says the number is already used: return it
curl -X POST https://smsnitro.com/api/v1/orders/123456/ban -H "X-Api-Key: $SMSNITRO_API_KEY"
```

## Elencare i tuoi ordini

**Richiesta**

```bash
curl "https://smsnitro.com/api/v1/orders?limit=20&offset=0" \
  -H "X-Api-Key: $SMSNITRO_API_KEY"
```

## FAQ

**C’è un webhook quando arriva l’SMS?** No. Interroga GET /v1/orders/{id} ogni 3-5 secondi; l’SMS compare appena arriva.

**Cos’è il campo server?** I numeri arrivano da due server di fornitura. Il server 1 è quello principale, il 2 l’alternativa. Senza il campo sceglie la API; indicalo per confrontare i prezzi o riprovare sull’altro.

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