# Chiave API

La chiave API collega script, bot e gestionali a SMS Nitro per acquistare numeri e leggere i codici senza passare dal pannello. Può spendere il tuo saldo come faresti tu, quindi va custodita come una password.

## Dove si trova la chiave API di SMS Nitro?

Nella sezione API del pannello, che si sblocca dopo la prima ricarica confermata. Lì generi la chiave, che viene mostrata una sola volta: copiala e conservala in un posto sicuro. Ogni account ha una sola chiave attiva e generarne una nuova revoca subito la precedente. La stessa chiave vale per l'API REST e per l'endpoint compatibile con SMS-Activate.

## Generare la chiave

1. **Fai la prima ricarica** L'accesso all'API si attiva con il primo deposito confermato, a partire da 5 USD.
2. **Apri la sezione API** Qui vedi se hai una chiave attiva, il suo prefisso, la data di creazione e l'ultimo utilizzo.
3. **Genera e copia** La chiave completa compare una sola volta. Salvala in un gestore di password o in una variabile d'ambiente del server.

## Dove si usa la chiave

- API REST: base https://smsnitro.com/api/v1, con la chiave nell'header X-Api-Key oppure come Authorization: Bearer. Le risposte sono in JSON.
- Endpoint compatibile con SMS-Activate: https://smsnitro.com/api/stubs/handler_api.php, con la chiave nel parametro api_key. Utile per bot e programmi che parlano già quel protocollo.
- Per sapere se il codice è arrivato si fa il controllo dello stato dell'ordine a intervalli regolari: non ci sono notifiche push verso il tuo server.
- Sono disponibili SDK per Python e Node e una collezione Postman per provare le chiamate.
- Gli acquisti via API seguono le regole del pannello: prezzo bloccato, addebito solo se arriva il codice, importo restituito senza SMS.

## Risposte dell'endpoint compatibile

- NO_KEY o BAD_KEY: chiave mancante, scritta male o revocata dopo averne generata una nuova.
- NO_BALANCE: saldo insufficiente per l'acquisto. Ricarica e riprova.
- WRONG_COUNTRY o BAD_SERVICE: paese o app non validi per quella richiesta.
- STATUS_WAIT_CODE e STATUS_OK: SMS ancora in attesa, oppure SMS consegnato con il codice.
- EARLY_CANCEL_DENIED: annullamento chiesto troppo presto; riprova dopo qualche minuto.
- BAD_STATUS: azione non consentita nello stato attuale, per esempio annullare dopo aver ricevuto il codice.

## Come proteggere la chiave

- Non condividerla e non pubblicarla in repository, screenshot o chat: chi ce l'ha può usare il tuo saldo.
- Tienila in variabili d'ambiente o in un gestore di segreti, mai nel codice di un'app che gira su telefoni o browser.
- Se pensi che sia trapelata, o se chi la conosceva lascia il team, generane una nuova: la vecchia smette di funzionare in quel momento.
- Controlla la data di ultimo utilizzo nel pannello e, se vedi attività che non riconosci, rigenera la chiave e apri un ticket.
- Cambiare la password dell'account non cambia la chiave API: sono indipendenti.

## Limiti e volumi alti

Ci sono limiti di richieste per proteggere il servizio. Controllare lo stato di un ordine ogni pochi secondi è normale; interrogare il catalogo in un ciclo continuo no. Se prevedi volumi elevati, contatta l'assistenza prima di partire.

## FAQ

**Perché non riesco a generare la chiave API?** Perché l'accesso all'API si attiva dopo il primo deposito confermato. Ricarica il saldo e nella sezione API del pannello comparirà il pulsante per generare la chiave. Con le cripto, aspetta la conferma della transazione.

**Ho perso la chiave API, potete rimandarmela?** No. Conserviamo solo una versione cifrata e la chiave completa viene mostrata una volta sola. Generane una nuova dal pannello: la precedente viene revocata subito e va sostituita nei tuoi sistemi.

**L'API è compatibile con SMS-Activate?** Sì. L'endpoint handler_api.php usa lo stesso protocollo, quindi molti bot e programmi funzionano cambiando solo indirizzo e chiave. Per integrazioni nuove l'API REST in JSON è più comoda.

**Posso avere più chiavi API sullo stesso account?** No. Ogni account ha una sola chiave attiva. Generarne una nuova revoca la precedente, così la rotazione è semplice e non restano chiavi vecchie in circolazione.

Source: https://smsnitro.com/it/aiuto/chiave-api