SMS HTTP API

Grazie alle SMS HTTP API puoi integrare il tuo software con il nostro gateway SMS in modo semplice e rapido.

Le HTTP API si basano su semplici chiamate HTTP GET quindi per l'integrazione potrai utilizzare un Client HTTP scritto in un qualsiasi linguaggio di programmazione.

Tramite le HTTP API sono possibili le seguenti operazioni:

• inviare SMS
• cercare e visualizzare il dettaglio degli SMS inviati
• visualizzare i dati relativi al proprio profilo direttamente dalla piattaforma Smshosting

Url base dei servizi

L'indirizzo base da utilizzare per accedere alle HTTP API è il seguente

oppure per i rivenditori

Effettuare una richiesta

Tutte le richiesta alle HTTP API necessitano di essere autenticate tramite 2 parametri passati in GET authKey e authSecret.

Questi parametri vanno valorizzati con i codici AUTH_KEY e AUTH_SECRET associati al tuo account Smshosting.

👉 Visita la sezione gestione sicurezza API nella tua area riservata per recuperare tali valori.

Puoi testare le tue credenziali chiamando semplicemente da browser il seguente URL:

oppure eseguendo da shell Linux il comando

Nel caso l'autenticazione non vada a buon fine viene restituito l'errore HTTP 400.

Tutte le richieste alle HTTP API devono essere encodate in UTF-8.

Scegliere il formato di risposta

Le REST API di Smshosting possono restituire le informazioni sia nel formato JSON (default) sia XML.

Per ottenere la risposta nel formato desiderato utilizza l'header HTTP "Accept" nella tua richiesta.

Accept:application/json per ottenere un JSON

Accept:application/xml per ottenere un XML

Gestire la risposta

Codici di risposta (HTTP Status Code)

Per ogni richiesta le HTTP API restituiscono uno dei seguenti HTTP Status Code:

200  - Richiesta completata correttamente

400  - Parametro mancante o autenticazione fallita

404  - Risorsa non trovata

405  - Metodo HTTP non consentito

500  - Errore imprevisto del server

Contenuto risposta

Ad ogni chiamata HTTP GET completata con successo (HTTP status uguale a 200) le REST API restituiscono come contenuto un JSON/XML.

Se una chiamata dovesse terminare con un errore (HTTP status diverso da 200) viene restituito un JSON/XML esplicativo dell'errore:

errorCode  - Codice HTTP status

errorMsg  - Codice di errore esplicativo del problema occorso

Ad esempio, nel caso l'autenticazione fallisca, le REST API restituiscono un HTTP Status 400 e come contenuto:

{
   "errorMsg":"BAD_CREDENTIALS",
   "errorCode":400
}

Paginazione

Alcune risorse (ricerca sms inviati o ricevuti, ricerca contatti, etc.) restituiscono i risultati paginati.

Ad esempio la ricerca sms inviati restiruisce il seguente JSON:

{
   "metadata":{
      "count":1,
      "offset":0,
      "limit":20
   },
   "smsList":[
      {
         "id":389395385,
         "to":"393480000000",
         "text":"Test Sms",
         "from":"mrossi",
         "status":"DELIVERED",
         "insertDate":"2014-01-13T15:01:35+0100",
         "sentDate":"2014-01-13T15:01:37+0100",
         "deliveryDate":"2014-01-13T15:01:40+0100",
         "transactionId":"72810108d4114097b9edb42b255b273c",
         "price":0.0945
      }
   ]
}

Il campo metadata  contiene le informazioni utili a gestire la paginazione dei risultati.

La proprietà count  indica il numero totale di risultati trovati per quella ricerca.

I campi offset  e limit  indicano rispettivamente l'indice del primo risultato ed il numero di risultati restituiti dalla chiamata.

Offset  e limit  possono essere usati come parametri nella richiesta in modo da controllare il range di risultati restituiti.

Ad esempio se una ricerca trova 100 risultati e la dimensione della pagina è di 20 elementi:

{
   "metadata":{
      "count":100,
      "offset":0,
      "limit":20
   },
   .......
}

sarà possibile ottenere 5 pagine usando i seguenti valori di offset  e limit :

pagina 1 - offset=0&limit=20

pagina 2 - offset=20&limit=20

pagina 3 - offset=40&limit=20

pagina 4 - offset=60&limit=20

pagina 5 - offset=80&limit=20