SubitoSMS – JSON API
SubitoSMS mette a disposizione API di integrazione basate su oggetti JSON.
È possibile inviare SMS singoli o multipli (bulk) in una sola richiesta. In caso di invio bulk viene restituito un unico ID di gruppo, utilizzabile per verificare lo stato di ciascun SMS.
Azioni disponibili
Tutte le richieste JSON devono essere inviate all’endpoint:
https://www.subitosms.it/json.php
Il gateway JSON espone tre azioni principali:
• credit – verifica del credito residuo
• send – invio di SMS singoli o multipli
• status – verifica dello stato di invio e consegna
Utilizzo delle JSON API
Per utilizzare le API è necessario effettuare una richiesta HTTP POST specificando:
• l’azione tramite il parametro action
• un oggetto JSON contenente autenticazione e dati
Auth array
Ogni richiesta deve includere un array di autenticazione:
{"auth":{"username":"mickey","password":"foobar"},"data":[]}
Verifica credito
Endpoint:
POST /json.php?action=credit
La richiesta JSON deve includere l’array auth. L’array data può essere vuoto.
Risposta verifica credito
{ "data":{ "Italy":"4021", "Foreign":"91", "ItalyLow":"90", "AddressBooks":"12", "Polls":"6", "Credit":null } }
Significato dei campi:
• Italy – SMS disponibili verso operatori italiani
• Foreign – SMS disponibili verso operatori esteri
• ItalyLow – SMS verso Italia senza mittente alfanumerico
• AddressBooks – rubriche disponibili
• Polls – sondaggi SMS disponibili
Controllo stato spedizioni
Permette di ottenere lo stato di uno o più invii (singoli o bulk).
Ogni SMS ha un proprio codice interno ed espone:
• sender – mittente
• dest – destinatario
• text – testo del messaggio
• code – codice interno SMS
• status – stato di consegna
POST /json.php?action=status
Esempio richiesta stato
{ "auth":[{"username":"mickey","password":"foobar"}], "data":[{"id":12293682},{"id":12279076}] }
Esempio risposta stato
[ { "id":12293682, "messages":[ {"sender":"Example1","dest":"+39335123456","text":"First message","status":"1","code":1803322} ] }, { "id":12279076, "messages":[ {"sender":"Example2","dest":"+39335123456","text":"Second message","status":"1","code":1741411}, {"sender":"Example3","dest":"+39347123456","text":"Third message","status":"1","code":1741412} ] } ]
Se un ID non è valido, l’array corrispondente nella risposta sarà vuoto.
Valori di stato
• -100: errore gateway
• -50: destinatario bloccato
• -2 / -1: non processato
• 0: accettato dal gateway
• 1: consegnato
• 2: non consegnato
• 4: in buffer
• 8: spedito
• 16: rifiutato
Invio SMS
POST /json.php?action=send
Parametri richiesti:
• sender – mittente (numero GSM o stringa max 11 caratteri)
• dest – numero GSM destinatario
• text – testo del messaggio (fino a 4 SMS concatenati)
Esempio richiesta invio
{ "auth":[{"username":"mickey","password":"foobar"}], "data":[ {"sender":"SubitoSMS","dest":"+39335123456","text":"Hello message"}, {"sender":"SubitoSMS","dest":"+393356359515","text":"Hello message"} ] }
Risposta invio
{"data":{"id":"12293682"}}
L’ID restituito deve essere salvato per il controllo dello stato.
Gestione errori
{"error":{"message":"Wrong username or password","code":4}}
Codici di errore
1 – Errore di sintassi o auth mancante
2 – Username non definito
3 – Password non definita
4 – Credenziali errate
5 – Credito insufficiente
6 – ID mancante per richiesta status
7 – Azione non definita
Requisiti PHP
Sono necessari:
• supporto JSON
• supporto cURL