icon_qa

INTRODUZIONE API REST

Usi l'app Postman?
 

INVIO PUSH (BETA)

Invio Push/SMS

Invio di un messaggio testo+Immagine ad uno o più destinatari singoli o verso uno o più gruppi della rubrica.

Tramite il parametro onlyPush è possibile stabilire se verranno inviati solo messaggi Push oppure, nel caso un destinatario non disponga di alcuna applicazione, possa essere inviato un SMS.

È possibile testare l'invio valorizzando il parametro sandbox a true nella richiesta.

Per maggiori informazioni fare riferimento alla tabella parametri sottostante.

URI

POST https://api.smshosting.it/rest/api/push/send

Richiesta

  Il "Content-Type" per la richiesta POST deve essere:
  - "application/x-www-form-urlencoded" nel caso NON si voglia allegare un file
  - "multipart/form-data" nel caso si voglia allegare un file
ParametroObbligatorioTipoDescrizione
to

No

(Obbligatorio valorizzare almeno uno tra il campo to e group)

String

Il destinatario del messaggio.

Deve essere un numero di cellulare compreso di prefisso internazionale.
È possibile specificare più numeri di telefono separandoli con il carattere virgola ",".

Ad esempio:

393481234567 oppure 393481234567,393481234568,393481234568

group

No

(Obbligatorio valorizzare almeno uno tra il campo to e group)

String

Id del gruppo in Rubrica al quale inviare

È possibile specificare più gruppi della rubrica separandoli con il carattere virgola ",".

Ad esempio se nellla rubrica sono presenti i gruppi Amici(id=1) e Scuola(id=2) sarà possibile indicare:

1 oppure 1,2

text

No

(Obbligatorio valorizzare almeno uno tra il campo text e file)

String

Testo del messaggio Push

file

No

(Obbligatorio valorizzare almeno uno tra il campo text e file)

String

Immagine del messaggio Push da uploadare

Richiede il content type multipart/form-data

onlyPush No String

Nel caso sia valorizzato a true verranno inviati solo messaggi push.Se un destinatario non può essere raggiunto tramire Push verrà escluso dall'invio

Nel caso sia valorizzato a false verranno inviati messaggi Push quando possibile ed SMS nei restanti casi.

 

Default: true

Possibili valori true/false

date No String

Sms differito

Data (in formato yyyy-MM-ddTHH:mm:ssZ) alla quale sarà inviato il messaggio.Se non viene specificato alcun valore il messaggio viene inviato immediatamente.

Ad esempio:

2014-12-25T08:00:00+0200 indica il 25/12/2014 alle 08:00:00 riferito al GMT +2

transactionId No String

Un identificatore personale dell'invio.

Consente di assegnare a tutti i messaggi inviati con una chiamata lo stesso identificatore in modo da utilizzare questo parametro per ricevere lo stato dei messaggi. massimo 60 caratteri

sandbox No Boolean

Consente di testare la chiamata senza inviare effettivamente il messaggio.

Parametro utile in fase di sviluppo di eventuali integrazioni con le REST API.

Possibili valori true/false

smsFrom

No

String

Il mittente dell'eventuale SMS che sarà inviato a quelli che non possono essere raggiunti via Push.

Può essere un numero di telefono validato oppure una stringa alfanumerica di 11 caratteri. Se non specificato viene usato il mittente di default del proprio profilo.

smsText

No

(Obbligatorio nel caso onlyPush sia valorizzato a false)

String

Il testo dell'eventuale SMS che sarà inviato a quelli che non possono essere raggiunti via Push.

Se il testo supera i 160 caratteri vengono inviati più Sms concatenati fino ad una massimo di 5.

smsEncoding

No

String

L'encoding da utilizzare per il testo del SMS.

I possibili valori sono:

7BIT - Encoding standard per i messaggi GSM. La lunghezza massima per un singolo sms è di 160 caratteri.

UCS2 - Encoding a 8-bit per inviare messaggi GSM con contenuto non ASCII. La lunghezza massima per un singolo sms è di 70 caratteri.

AUTO - L'encoding da utilizzare viene automaticamente identificato in base al contenuto del campo testo.

Default : 7BIT

Risposta

HTTP Status Code

CodiceDescrizione
200 ok
400

Parametri non validi

I possibili errorMsg sono:

PUSH_UNAVAILABLE - nessun piano Push attivo

BAD_TRANSACTIONID - parametro transactionId non valido

BAD_DATE - formato data differito non valida

BAD_CONTENT_PUSH - non è stato specificato nessun parametro tra text e file

BAD_ENCODING - parametro smsEncoding non valido

BAD_TEXT - parametro smsText non valido

BAD_FROM - parametro smsFrom non valido

BAD_GROUP - parametro group non valido

BAD_CREDIT - credito insufficiente per effetturare l'invio

NO_PUSH - numero push insufficienti per effetturare l'invio

NO_VALID_RECIPIENT - nessun valido destinatario

GENERIC_ERROR - errore interno al server

401 Credenziali non valide
405 Metodo HTTP non consentito
500 Errore generico

Dati Invio

ProprietàDescrizione
from Il mittente dell'eventuale SMS inviato.
text Testo dell'eventuale SMS inviato.
transactionId

identificatore dell'invio

Se non specificato in fase di richiesta verrà generato un transactionId automaticamente dalle REST API

smsInserted Numero Sms inseriti
smsNotInserted Numero messaggi non inseriti
pushInserted Numero Push inserite
sms

Lista dei messaggi.

Ogni messaggio è descritto dalla proprietà:

to - numero di cellulare al quale è stato inviato il messaggio

id - id interno del messaggio.Valore utile per richiedere lo stato del messaggio con la funzione di Cerca Sms

status - Stato del messaggio. Viene valorizzato ad INSERTED nel caso il messaggio sia inserito correttamente, a NOT_INSERTED in caso contrario.

statusDetail - nel caso il messaggio non venga inserito (status = NOT_INSERTED) questo campo riporta un messaggio esplicativo dell'errore avvenuto.
I possibili valori sono :
BADNUMBERFORMAT - Numero del destinatario non corretto
DUPLICATESMS - Sms già inserito nelle ultime 24 ore con identico destinatario, mittente e testo.

type - Tipo messaggio. Valorizzato a PUSH nel caso l'invio sia stato effettuato tramite Push

 Esempio:

curl --user AUTH_KEY:AUTH_SECRET -XPOST https://api.smshosting.it/rest/api/push/send \
-d "to=393480000000" \
-d "text=Test Push"

f = new File('/img/img1.jpg');

HttpResponse sms_send_response = Unirest.post("https://api.smshosting.it/rest/api/push/send")
        .header("accept", "application/json")
        .basicAuth(AUTH_KEYS, AUTH_SECRET)
        .field("to", "39347000000")
        .field("text", "ciao")
        .field("file", f)
        .asString();
  
  Unirest\Request::auth($AUTH_KEYS, $AUTH_SECRET);

  $headers = array(
    'Accept' => 'application/json'
  );
  $param = array(
  'to' => '39347000000',
  'text' => 'ciao'
  );
  $files = array('file' => '/image/icon1024.png');

  $body = Unirest\Request\Body::multipart($param, $files);

  $response = Unirest\Request::post('https://api.smshosting.it/rest/api/push/send', $headers,$body);

  response = unirest.post(
      "https://api.smshosting.it/rest/api/push/send",
      headers={
          "Accept": "application/json"
      },
      auth=(AUTH_KEYS,AUTH_SECRET),
      params={
          "to": "39347000000",
          "text": "ciao ciao",
          "file": open("/img/da_2441.jpg", mode="r")
      }

 byte[] data=null;

data = File.ReadAllBytes(@"/img/img01.jpg");
HttpResponse jsonResponse = Unirest.post("https://api.smshosting.it/rest/api/push/send")
    .header("Accept", "application/json")
    .basicAuth(AUTH_KEYS,AUTH_SECRET)
    .field("to", "39347000000")
    .field("text", "ciao")
    .field("file",data)
    .asString();

{
   "transactionId":"d41ebeeb38b6a04818aa707818d3161e",
   "smsInserted":0,
   "smsNotInserted":0,
"pushInserted": 1, "sms":[ { "id":389310742, "to":"393412345678", "status":"INSERTED",
"type":"PUSH" } ] }

Calcolo del preventivo di un invio Push/SMS

Calcolo del numero di Push e del credito necessario per un invio Push/SMS

URI

POST https://api.smshosting.it/rest/api/push/estimate

Richiesta

  Il "Content-Type" per la richiesta POST deve essere:
  - "application/x-www-form-urlencoded" nel caso NON si voglia allegare un file
  - "multipart/form-data" nel caso si voglia allegare un file
ParametroObbligatorioTipoDescrizione
to

No

(Obbligatorio valorizzare almeno uno tra il campo to e group)

String

Il destinatario del messaggio.

Deve essere un numero di cellulare compreso di prefisso internazionale.
È possibile specificare più numeri di telefono separandoli con il carattere virgola ",".

Ad esempio:

393481234567 oppure 393481234567,393481234568,393481234568

group

No

(Obbligatorio valorizzare almeno uno tra il campo to e group)

String

Id del gruppo in Rubrica al quale inviare

È possibile specificare più gruppi della rubrica separandoli con il carattere virgola ",".

Ad esempio se nellla rubrica sono presenti i gruppi Amici(id=1) e Scuola(id=2) sarà possibile indicare:

1 oppure 1,2

text

No

(Obbligatorio valorizzare almeno uno tra il campo text e file)

String

Testo del messaggio Push

file

No

(Obbligatorio valorizzare almeno uno tra il campo text e file)

String

Immagine del messaggio Push da uploadare

Richiede il content type multipart/form-data

onlyPush No String

Nel caso sia valorizzato a true verranno inviati solo messaggi push.Se un destinatario non può essere raggiunto tramire Push verrà escluso dall'invio

Nel caso sia valorizzato a false verranno inviati messaggi Push quando possibile ed SMS nei restanti casi.

 

Default: true

Possibili valori true/false

smsFrom

No

String

Il mittente dell'eventuale SMS che sarà inviato a quelli che non possono essere raggiunti via Push.

Può essere un numero di telefono validato oppure una stringa alfanumerica di 11 caratteri. Se non specificato viene usato il mittente di default del proprio profilo.

smsText

No

(Obbligatorio nel caso onlyPush sia valorizzato a false)

String

Il testo dell'eventuale SMS che sarà inviato a quelli che non possono essere raggiunti via Push.

Se il testo supera i 160 caratteri vengono inviati più Sms concatenati fino ad una massimo di 5.

smsEncoding

No

String

L'encoding da utilizzare per il testo del SMS.

I possibili valori sono:

7BIT - Encoding standard per i messaggi GSM. La lunghezza massima per un singolo sms è di 160 caratteri.

UCS2 - Encoding a 8-bit per inviare messaggi GSM con contenuto non ASCII. La lunghezza massima per un singolo sms è di 70 caratteri.

AUTO - L'encoding da utilizzare viene automaticamente identificato in base al contenuto del campo testo.

Default : 7BIT

Risposta

HTTP Status Code

CodiceDescrizione
200 ok
400

Parametri non validi

I possibili errorMsg sono:

PUSH_UNAVAILABLE - nessun piano Push attivo

BAD_CONTENT_PUSH - non è stato specificato nessun parametro tra text e file

BAD_ENCODING - parametro smsEncoding non valido

BAD_TEXT - parametro smsText non valido

BAD_FROM - parametro smsFrom non valido

BAD_GROUP - parametro group non valido

NO_VALID_RECIPIENT - nessun valido destinatario

GENERIC_ERROR - errore interno al server

401 Credenziali non valide
405 Metodo HTTP non consentito
500 Errore generico

Dati relativi al preventivo

ProprietàDescrizione
cost Costo dell'invio
userCredit Credito residuo dell'utente
smsCount Numero SMS da inviare
pushCount Numero Push da inviare
pushAvailable Numero Push disponibili

 Esempio:

curl --user AUTH_KEY:AUTH_SECRET -XPOST https://api.smshosting.it/rest/api/push/estimate \
-d "to=393480000000" \
-d "text=Test Push"


HttpResponse sms_estimate_response = Unirest.post("https://api.smshosting.it/rest/api/push/estimate")
        .basicAuth(SMS_AUTH_KEY, SMS_SECRET_KEY)
        .field("to", "393470000000")
        .field("text", "Ciao")
        .asJson();

Unirest\Request::auth(SMS_AUTH_KEY, SMS_SECRET_KEY);

$headers = array(
  'Accept' => 'application/json'
);

$data = array(
  'to' => '393470000000',
  'text' => 'ciao'
);
$body = Unirest\Request\Body::form($data);
$response = Unirest\Request::post('https://api.smshosting.it/rest/api/push/estimate', $headers, $body);

response = unirest.post(
    "https://api.smshosting.it/rest/api/sms/estimate",
    headers={
        "Accept": "application/json"
        },
    auth=(SMS_AUTH_KEY, SMS_SECRET_KEY),
    params={
        "to": "393470000000",
        "text": "ciao"
        }
    )

byte[] data = null;

HttpResponse jsonResponse = Unirest.post("https://api.smshosting.it/rest/api/sms/estimate")
    .header("Accept", "application/json")
    .basicAuth(SMS_AUTH_KEY, SMS_SECRET_KEY)
    .field("to", "39347000000")
    .field("text", "ciao")
    .field("file", data)
    .asString();

{
   "cost":0,
   "userCredit":15.484,
"smsCount":0,
"pushCount":1,
"pushAvailable":899 }

Cerca messaggi Push/SMS

Ricerca dei messaggi Push/SMS inviati.

URI

GET https://api.smshosting.it/rest/api/push/search

Richiesta

ParametroObbligatorioTipoDescrizione
id No * String

Id interno del messaggio inviato

È possibile specificare più id separandoli con il carattere virgola ",".

Ad esempio:

12312 oppure 432432,543543,435435

transactionId

No *

String TransactionId assegnato all'invio
msisdn

No *

String Numero al quale è stato inviato il messaggio
fromDate No * String Data dalla quale gli sms sono stati inviati in formato yyyy-MM-ddTHH:mm:ssZ
toDate No String Data fino alla quale gli sms sono stati inviati in formato yyyy-MM-ddTHH:mm:ssZ
status No * String Stato degli sms
offset No Integer

Posizione del primo risultato che verrà restituito.

Esempio:

Se la ricerca trova 100 sms, il campo offset viene valorizzato a 50 ed il campo limit a 10 verranno restituiti gli sms da 51 a 60.

Default : 0

limit No Integer

Numero di risultati che verranno restituiti.

Default : 20

* È richiesto che almeno un parametro sia valorizzato

Risposta

HTTP Status Code

CodiceDescrizione
200 ok
400

Parametri non validi

I possibili errorMsg sono:

PUSH_UNAVAILABLE - nessun piano Push attivo

NO_PARAMS - Nessun parametro valorizzato

BAD_ID - Parametro id non valido

BAD_MSISDN - Parametro msisdn non valido

BAD_DATE - Formato date non valido

BAD_STATUS - Parametro status non valido

401 Credenziali non valide
405 Metodo HTTP non consentito
500 Errore generico

La chiamata ritorna una lista di sms inviati.

ProprietàDescrizione
smsList

Lista degli sms ricevuti

Ogni sms è descritto dalle proprietà:

id - id interno messaggio

to - destinatario del messaggio

text - testo del messaggio

from - mittente del messaggio

status - stato del messaggio.Vedi la tabella sottostante.

insertDate - data inserimento del messaggio nel formato yyyy-MM-ddTHH:mm:ssZ

sentDate - data invio del messaggio nel formato yyyy-MM-ddTHH:mm:ssZ

deliveryDate - data consegna del messaggio nel formato yyyy-MM-ddTHH:mm:ssZ

transactionId - Identificatore dell'invio

price - costo del messaggio

type - tipo messaggio. Valorizzato a PUSH nel caso l'invio sia stato effettuato tramite Push

multimediaContent - identificativo id e tipo type dell'immagine inviata. L'id può essere usato nella chiamata Carica immagine per recupere il contenuto dell'immagine

metadata

Metadata utili per la paginazioni

Per maggiori dettagli sul funzionamento della paginazione visita la pagina dedicata

I possibili stati di un sms(campo status) sono

CodiceDescrizione
PENDING Sms in coda per l'invio
SENT Sms inviato all'operartore
NOSENT Sms non inviato all'operartore
DELIVERED Sms consegnato al cellulare del destinatario
NOTDELIVERED Sms non consegnato al cellulare

 Esempio:

curl --user AUTH_KEY:AUTH_SECRET  https://api.smshosting.it/rest/api/push/search?fromDate=2011-01-01T00:00:00-0200

HttpResponse sms_search_response = Unirest.get("https://api.smshosting.it/rest/api/push/search")
        .basicAuth(SMS_AUTH_KEY, SMS_SECRET_KEY)
        .queryString("id", "419853396")
        .asJson();

Unirest\Request::auth(SMS_AUTH_KEY, SMS_SECRET_KEY);

$headers = array(
  'Accept' => 'application/json'
);

$param = array(
  'id' => urlencode('419853396')
);

$response = Unirest\Request::get('https://api.smshosting.it/rest/api/push/search', $headers, $param);
response = unirest.get(
    "https://api.smshosting.it/rest/api/sms/search",
    headers={
        "Accept": "application/json"
        },
    auth=(SMS_AUTH_KEY, SMS_SECRET_KEY),
    params={
        "id": urllib.quote("419853396")
        }
    )

String queryString = "?";
queryString = queryString + "&id=419853396" ;

HttpResponse jsonResponse = Unirest.get("https://api.smshosting.it/rest/api/sms/search")
    .header("accept", "application/json")
    .basicAuth(SMS_AUTH_KEY, SMS_SECRET_KEY)
    .asString();

{
   "metadata":{
      "count":1,
      "offset":0,
      "limit":20
   },
   "smsList":[
      {
         "id":389395385,
         "to":"393480000000",
         "text":"Test Push",
         "status":"SENT",
         "insertDate":"2014-01-13T15:01:35+0100",
         "sentDate":"2014-01-13T15:01:37+0100",
         "deliveryDate":"2014-01-13T15:01:40+0100",
         "transactionId":"72810108d4114097b9edb42b255b273c",
         "multimediaContent": {
"id": "Efwchkk3WmI=",
"type": "IMAGE"
}       }    ] }

Scarica immagine

Ritorna l'immagine inviata via Push.

Usare la funzione di Ricerca Push/SMS per recuperare l'id della risorsa

URI

GET https://api.smshosting.it/rest/api/push/multimedia/{id}

Richiesta

ParametroObbligatorioTipoDescrizione
id Si String

Id interno dell'immagine

Risposta

HTTP Status Code

CodiceDescrizione
200 ok
400

Parametri non validi

I possibili errorMsg sono:

PUSH_UNAVAILABLE - nessun piano Push attivo

NO_PARAMS - Nessun parametro valorizzato

BAD_ID - Parametro id non valido

401 Credenziali non valide
405 Metodo HTTP non consentito
500 Errore generico

La chiamata ritorna direttamente il contenuto dell'immagine.

Crea link invito

Crea un link per invitare un numero di telefono ad aderire alle applicazioni utli per le Push.

Il link ottenuto può essere inviato via SMS oppure condiviso sui social, via Email, etc

URI

POST https://api.smshosting.it/rest/api/push/invitation

Richiesta

  Il "Content-Type" per la richiesta POST deve essere "application/x-www-form-urlencoded"
ParametroObbligatorioTipoDescrizione
to Si String

numero di telefono per il quale generare l'invito

Risposta

HTTP Status Code

CodiceDescrizione
200 ok
400

Parametri non validi

I possibili errorMsg sono:

PUSH_UNAVAILABLE - nessun piano Push attivo

NO_PARAMS - Nessun parametro valorizzato

BAD_TO - Numero non valido

401 Credenziali non valide
405 Metodo HTTP non consentito
500 Errore generico

Dati relativi all'invito

<a/tr>

ProprietàDescrizione
to numero di telefono per il quale è stato generato l'invito
url Url dell'invito

 Esempio:

curl --user AUTH_KEY:AUTH_SECRET -XPOST https://api.smshosting.it/rest/api/push/invitation \
-d "to=393480000000"

HttpResponse sms_cancel_response = Unirest.post("https://api.smshosting.it/rest/api/push/invitation")
        .basicAuth(SMS_AUTH_KEY, SMS_SECRET_KEY)
        .field("to", "393480000000")
        .asJson();

Unirest\Request::auth(SMS_AUTH_KEY, SMS_SECRET_KEY);

$headers = array(
  'Accept' => 'application/json'
);

$data = array(
  'to' => '393480000000'
);
$body = Unirest\Request\Body::form($data);

$response = Unirest\Request::post('https://api.smshosting.it/rest/api/push/invitation', $headers, $body);

response = unirest.post(
    "https://api.smshosting.it/rest/api/push/invitation",
    headers={
        "Accept": "application/json"
        },
    auth=(SMS_AUTH_KEY, SMS_SECRET_KEY),
    params={
        "to": "393480000000"
        }
    )


 String body = "";
body = body + "&to=" + HttpUtility.UrlEncode(tbPushInvitationTo.Text);

HttpResponse jsonResponse = Unirest.post("https://api.smshosting.it/rest/api/push/invitation")
    .header("Content-Type", "application/x-www-form-urlencoded")
    .header("Accept", "application/json")
    .basicAuth(SMS_AUTH_KEY, SMS_SECRET_KEY)
    .body(body)
    .asString();

{
   "to":"393480000000",
   "url":"cqui.it/5izKw2"
}