icon_qa

INTRODUZIONE API REST

Usi l'app Postman?
 

CONTATTI RUBRICA

Cerca Contatti

Cerca i contatti

URI

GET https://api.smshosting.it/rest/api/phonebook/contact/search

Richiesta

ParametroObbligatorioTipoDescrizione
name Si String

Nome completo del contatto.

La ricerca viene effettuata sui campi name e lastname

offset No Integer

Posizione del primo risultato che verrà restituito.

Esempio:

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

Default : 0

limit No Integer

Numero di risultati che verranno restituiti.

Default : 20

Risposta

HTTP Status Code

CodiceDescrizione
200 ok
400

Parametri non validi

I possibili errorMsg sono:

NO_PARAMS - Parametro name mancante

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

La chiamata ritorna una lista con di contatti presenti in rubrica.

ProprietàDescrizione
contacts

Lista di contatti

Per il dettaglio delle proprietà di ogni singolo contatto vedi la funzione Dettaglio contatto.

metadata

Metadata utili per la paginazioni

Per maggiori dettagli sul funzionamento della paginazione visita la pagina dedicata

 Esempio:

curl --user AUTH_KEY:AUTH_SECRET  https://api.smshosting.it/rest/api/phonebook/contact/search?name=Mario
{
   "metadata":{
      "count":1,
      "offset":0,
      "limit":20
   },
   "contacts":[
      {
         "msisdn":"393480000000",
         "name":"Mario",
         "lastname":"Rossi",
         "email":"mario.rossi@fake.it",
         "groups":[
            {
               "id":13197,
               "name":"Amici"
            },
            {
               "id":1947,
               "name":"Lavoro"
            }
         ],
         "customFields":[
            {
               "fieldKey": "f_indirizzo",
               "fieldName": "Indirizzo",
               "fieldValue": "via roma 1"
            },
            {
               "fieldKey": "f_cap",
               "fieldName": "CAP",
               "fieldValue": "30000"
            }
         ]
      }
   ]
}

Dettaglio contatto

Anagrafica di un contatto

URI

GET https://api.smshosting.it/rest/api/phonebook/contact/{msisdn}

Richiesta

ParametroObbligatorioTipoDescrizione
msisdn Si (parametro da specificare nell'URI) String Numero di cellulare del contatto compreso di prefisso internazionale

Risposta

HTTP Status Code

CodiceDescrizione
200 ok
401 Credenziali non valide
404 Contatto non trovato
405 Metodo HTTP non consentito
500 Errore generico

Proprietà contatto:

ProprietàDescrizione
msisdn Numero di cellulare del contatto
name Nome del contatto
lastname Cogome del contatto
email Indirizzo Email
customFields

Lista dei campi personalizzati che sono stati valorizzati per il contatto

Per ogni campo viene indicato il nome, la chiave ed il valore corrente

groups

Lista dei gruppi a cui il contatto appartiene.

Per ogni gruppo viene indicato l'id interno ed il campo name

 Esempio:

curl --user AUTH_KEY:AUTH_SECRET  https://api.smshosting.it/rest/api/phonebook/contact/393480000000
   {
         "msisdn":"393480000000",
         "name":"Mario",
         "lastname":"Rossi",,
         "email":"mario.rossi@fake.it",
         "groups":[
            {
               "id":13197,
               "name":"Amici"
            },
            {
               "id":1947,
               "name":"Lavoro"
            }
         ],
         "customFields":[
            {
               "fieldKey": "f_indirizzo",
               "fieldName": "Indirizzo",
               "fieldValue": "via roma 1"
            },
            {
               "fieldKey": "f_cap",
               "fieldName": "CAP",
               "fieldValue": "30000"
            }
         ]
      }

Nuovo contatto

Aggiungere contatto in rubrica

URI

POST https://api.smshosting.it/rest/api/phonebook/contact

Richiesta

  Il "Content-Type" per le richieste POST deve essere "application/x-www-form-urlencoded"
ParametroObbligatorioTipoDescrizione
msisdn Si String Numero di cellulare del contatto compreso di prefisso internazionale
name Si String Nome del contatto
lastname No String Cogome del contatto
email No String Indirizzo Email
${fieldKey} No String

Chiave/valore del campo pesonalizzato che si vuole popolare

L'elenco delle chiavi disponibili, da usare come nome parametro, può essere recuperato tramite il servizio lista campi personalizzati

groupsId No String

Id inteno del gruppo ai quale assegnare il contatto.

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

Ad esempio:

1245 oppure 1245,3432

Risposta

HTTP Status Code

CodiceDescrizione
200 ok
400

Parametri non validi

I possibili errorMsg sono:

BAD_CONTACT_NAME - Parametro name mancante

BAD_CONTACT_MSISDN - Parametro msisdn mancante o non valido

BAD_CONTACT_COUNTRY - Codice nazione non valido

BAD_CONTACT_GROUP - Gruppo non valido

CONTACT_ALREADY_EXISTS - Esiste già un contatto con questo msisdn

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

In caso il contatto venga creato correttamente (HTTP status 200) viene restituito il dettaglio del contatto

Per il dettaglio delle proprietà del contatto vedi la funzione Dettaglio contatto.

 Esempio:

curl --user AUTH_KEY:AUTH_SECRET  -XPOST https://api.smshosting.it/rest/api/phonebook/contact \
-d "msisdn=393480000000" \
-d "name=Mario" \
-d "lastname=Rossi" \
-d "f_indirizzo=via roma 1"
{
   "msisdn":"393480000000",
   "name":"Mario",
   "lastname":"Rossi"
   "groups":[
      {
         "id":-1,
         "name":"NOTASSIGNED"
      }
   ],
   "customFields":[
      {
          "fieldKey": "f_indirizzo",
          "fieldName": "Indirizzo",
          "fieldValue": "via roma 1"
      }
   ]
}

Aggiungi contatti

Carica massivamente contatti.

URI

GET https://api.smshosting.it/rest/api/phonebook/contact/addContactBulk

Richiesta

  Il "Content-Type" per le richieste POST deve essere "multipart/form-data"
ParametroObbligatorioTipoDescrizione
file Si File File csv contenente i contatti da caricare. Il formato del file è identico all'import via web. Maggiori informazioni...

Risposta

HTTP Status Code

CodiceDescrizione
200 ok
401 Credenziali non valide
405 Metodo HTTP non consentito
500 Errore generico

Risposta

ProprietàDescrizione
status SUBMITTED File formalmente corretto. Elaborazione in corso
REJECT File non corretto. Nessuna elaborazione
BUSY C'è gia una elaborazione in corso. Attendere il termine. (Vedi metodo successivo)
error Descrizione errore

 Esempio:

curl --user AUTH_KEY:AUTH_SECRET \
-XPOST "https://api.smshosting.it/rest/api/phonebook/contact/addContactBulk" \
-F "file=@prova_rubrica.csv"

HttpResponse contactAddBulk_response = Unirest.post("https://api.smshosting.it/rest/api/phonebook/contact/addContactBulk")
        .header("accept", "application/json")
        .basicAuth(SMS_AUTH_KEY, SMS_SECRET_KEY)
        .field("file", new File("prova_rubrica.csv"))
        .asJson();


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

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

$param = array(
);
$files = array('file' => 'prova_rubrica.csv');

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

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


  
response = unirest.post(
    "https://api.smshosting.it/rest/api/phonebook/contact/addContactBulk",
    headers={
        "Accept": "application/json"
        },
    auth=(setup.AUTH_KEYS,setup.AUTH_SECRET),
    params={
        "file": open("prova_rubrica.csv", mode="r")
        }
    )


  
byte[] data = contact_addbulk_file.FileBytes;
  
HttpResponse jsonResponse = Unirest.post("https://api.smshosting.it/rest/api/phonebook/contact/addContactBulk")
    .header("accept", "application/json")
    .basicAuth(tbAuth_key.Text, tbAuth_secret.Text)
    .field("file", data)
    .asString();

  {
    "status": "SUBMITTED"
  }  

Aggiungi contatti stato

Controlla lo stato della coda inserimento massivo contatti.

URI

GET https://api.smshosting.it/rest/api/phonebook/contact/addContactBulk_status

Richiesta

ParametroObbligatorioTipoDescrizione

Risposta

HTTP Status Code

CodiceDescrizione
200 ok
401 Credenziali non valide
405 Metodo HTTP non consentito
500 Errore generico

Risposta

ProprietàDescrizione
progress Percentuale di progressione
free disponibile per invio successivo

 Esempio:

curl --user AUTH_KEY:AUTH_SECRET \
-XGET "https://api.smshosting.it/rest/api/phonebook/contact/addContactBulk_status"

HttpResponse contactAddBulkStatus_response = Unirest.get("https://api.smshosting.it/rest/api/phonebook/contact/addContactBulk_status")
      .header("accept", "application/json")
      .basicAuth(SMS_AUTH_KEY, SMS_SECRET_KEY)
      .asJson();



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

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

$response = Unirest\Request::get('https://api.smshosting.it/rest/api/phonebook/contact/addContactBulk_status', $headers);


  
response = unirest.get(
    "https://api.smshosting.it/rest/api/phonebook/contact/addContactBulk_status",
    headers={
        "Accept": "application/json"
        },
    auth=(SMS_AUTH_KEY, SMS_SECRET_KEY),
    params={
        }
    )

  
HttpResponse jsonResponse = Unirest.get("https://api.smshosting.it/rest/api/phonebook/contact/addContactBulk_status")
    .header("accept", "application/json")
    .basicAuth(tbAuth_key.Text, tbAuth_secret.Text)
    .asString();

{
  "progress": "100%",
  "free": true
}

Aggiorna contatto

Modificare un contatto in rubrica

URI

PUT https://api.smshosting.it/rest/api/phonebook/contact/{msisdn}

Richiesta

  Il "Content-Type" per le richieste POST deve essere "application/x-www-form-urlencoded"
ParametroObbligatorioTipoDescrizione
msisdn Si (parametro da specificare nell'URI) String Numero di cellulare del contatto compreso di prefisso internazionale
name Si String Nome del contatto
lastname No String Cogome del contatto
email No String Indirizzo Email
${fieldKey} No String

Chiave/valore del campo pesonalizzato che si vuole popolare

L'elenco delle chiavi disponibili, da usare come nome parametro, può essere recuperato tramite il servizio lista campi personalizzati

groupsId No String

Id inteno del gruppo ai quale assegnare il contatto.

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

Ad esempio:

1245 oppure 1245,3432

Risposta

HTTP Status Code

CodiceDescrizione
200 ok
400

Parametri non validi

I possibili errorMsg sono:

BAD_CONTACT_NAME - Parametro name mancante

BAD_CONTACT_MSISDN - Parametro msisdn mancante o non valido

BAD_CONTACT_COUNTRY - Codice nazione non valido

BAD_CONTACT_GROUP - Gruppo non valido

CONTACT_ALREADY_EXISTS - Esiste già un contatto con questo msisdn

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

In caso il gruppo venga creato correttamente viene restituito lo stato HTTP status 200

 Esempio:

curl --user AUTH_KEY:AUTH_SECRET  -XPUT https://api.smshosting.it/rest/api/phonebook/contact/393480000000 \
-d "name=Mario" \
-d "lastname=Bianchi"
HTTP status 200

Elimina contatto

Eliminare un contatto in rubrica

URI

DELETE https://api.smshosting.it/rest/api/phonebook/contact/{msisdn}

Richiesta

ParametroObbligatorioTipoDescrizione
msisdn Si (parametro da specificare nell'URI) String Numero di cellulare del contatto compreso di prefisso internazionale

Risposta

HTTP Status Code

CodiceDescrizione
204 ok
401 Credenziali non valide
404 Contatto non trovato
405 Metodo HTTP non consentito
500 Errore generico

In caso il gruppo venga eliminato correttamente viene restituito lo stato HTTP status 200

 Esempio:

curl --user AUTH_KEY:AUTH_SECRET  -XDELETE https://api.smshosting.it/rest/api/phonebook/contact/393480000000
HTTP status 204