Guida API SMS: Integrazione per Sviluppatori
La sezione API DEV è progettata per chi desidera integrare le funzionalità di GenioSms (come l'invio di codici OTP, notifiche di domotica o alert di sistema) direttamente nel proprio software.
Scalabilità Multi-Dispositivo
GenioSms agisce come un gateway distribuito. Puoi collegare un numero illimitato di smartphone alla stessa lista tramite lo stesso PIN:
● Quando invii un comando tramite API, la richiesta viene inoltrata a tutti i dispositivi collegati.
● Il primo telefono disponibile prende in carico la richiesta ed effettua l'invio materiale dell'SMS.
● Questo sistema garantisce velocità e ridondanza: se un telefono è occupato o offline, gli altri subentrano immediatamente.
1. Come integrare il codice
L'integrazione è immediata grazie agli esempi pronti all'uso:
1. Individua l'API di tuo interesse nella tabella del pannello.
2. Clicca sul pulsante "CODE" a destra della riga.
3. Copia lo snippet di codice nel linguaggio che preferisci (PHP, Perl, Python, ecc.).
Per una panoramica completa dei parametri, consulta la nostra [Guida API Estesa].
2. Sicurezza e Autorizzazioni IP
Per proteggere il tuo account, puoi limitare l'accesso alle API:
● Consenti solo da IP: Se attivo, solo l'indirizzo IP del tuo server potrà inviare comandi.
● Cross-Domain: Configura il dominio corretto se le chiamate provengono da un'applicazione web esterna.
3. Gestione della Risposta (JSON Response)
Ogni chiamata API restituisce un oggetto JSON che conferma la presa in carico del messaggio da parte del gateway:
{
"response": "200",
"status_code": "2"
}
Legenda dei codici:
● Response "200": La richiesta è sintatticamente corretta ed è stata consegnata con successo ai dispositivi associati.
● Attenzione: questo indica che il telefono ha ricevuto il comando, non che l'SMS è già arrivato al destinatario finale.
● Status_code: Indica il livello di autorizzazione della chiamata.
| Codice | Stato | Descrizione |
|---|---|---|
| 1 | ok_ip | Invio consentito perché l'indirizzo IP è autorizzato. |
| 2 | ok_over_ip | Invio consentito da qualsiasi IP perché over_ip > 0 e l'API key = 0. |
| 3 | api_key_error | Invio non consentito: token API errato. |
| 4 | unauthorized_ip | Invio non consentito: indirizzo IP non autorizzato. |
| 5 | param_error | Invio non consentito: parametri errati (deprecato). |
| 6 | token_or_id_device_error | Invio non consentito: token del dispositivo o ID device errato. |
| 7 | missing_to_number | Invio non consentito: numero di destinazione mancante. |
| 8 | missing_msg | Invio non consentito: messaggio da inviare mancante. |
| 9 | balance_error | Invio non consentito: credito insufficiente. |
4. Tracking avanzato con IPN (Instant Process Notification)
Per conoscere l'esito reale dell'SMS sul telefono del destinatario, non interrogare le API in loop, ma usa l'IPN. Quando lo stato del messaggio cambia sul dispositivo mobile, il nostro server effettua una chiamata POST verso il tuo script, notificando gli eventi:
● Sent: Messaggio inviato con successo dalla SIM.
● Delivered: Messaggio consegnato e ricevuto dal destinatario (Rapporto di consegna).
Video Tutorial: Creazione API e test con cURL
In questo video vedremo come generare le chiavi, trovare il codice di esempio e testare un invio reale direttamente da riga di comando utilizzando cURL.
