Protocollo

REST SOAP

API Backoffice

Invio SMS

Ricezione SMS

API Clienti finali

Invio SMS

Ricezione SMS

Appendici

 
 

API White Label

Cos'è il White Label e come usare

Skebby offre ai propri clienti rivenditori una piattaforma completamente personalizzabile per la commercializzazione dei servizi SMS in totale anonimato con proprio dominio, logo e colori ai propri clienti. Il Distributore/Rivenditore White Label acquista SMS da Skebby a prezzi speciali e stabilisce i tariffe per i propri clienti in totale autonomia guadagnando la differenza. Grazie ad un sistema multilivello la piattaforma permette al Distributore White Label di gestire diverse tipologie di clienti (Rivenditori o Clienti Finali) manualmente tramite l'interfaccia web o in automatico tramite API.

La piattaforma White Label può essere utilizzata in due modalità :

  1. Interfaccia web SMS Messenger White Label + API Back Office White Label
    Se non disponi di una tua interfaccia web per l'invio di SMS Skebby ti fornisce una piattaforma integrata multilivello con l'interfaccia web SMS Messenger personalizzabile con il tuo dominio, marchio, colori e grafica dalla quale i tuoi clienti potranno effettuare l'accesso e usufruire dei servizi di Invio e Ricezione SMS. Puoi gestire i tuoi clienti manualmente da interfaccia web White Label oppure in automatico tramite API Back Office White Label.
    Invio SMS tuoi Clienti >> SMS Messenger White Label
    Gestione dei tuoi clienti >> API Back Office (automatico)
    >> Interfaccia Web White Label (manuale)
  2. Tua interfaccia web proprietaria + API Invio SMS e API Back office White Label
    Se disponi di una tua interfaccia web per l'invio di SMS potrai integrarla direttamente con l'SMS Gateway Skebby ed utilizzare poi tutte le API White Label all'interno della tua piattaforma per la creazione e gestione dei tuoi clienti ed il billing dei servizi SMS. Skebby mette a disposizione un'ampia documentazione delle funzionalità del software inclusi esempi di codice per un immediato copia e incolla, rendendo semplice e a costo quasi zero l'integrazione.
    Invio SMS tuoi Clienti >> Tua interfaccia web + API Clienti Finali / Invio SMS
    Gestione dei tuoi clienti >> API Back Office (automatico)
    >> Interfaccia web White Label (manuale)

Struttura Multilivello White Label

La piattaforma White Label Skebby permette di operare con una struttura di rivendita SMS a 2 livelli (Distributore - Rivenditore - Cliente Finale).  Potrai attivare e gestire sia Clienti Finali sia Clienti Rivenditori rivendendo a tua volta i servizi SMS in White Label sul tuo canale. Avrai la possibilità, infatti, di assegnare ai tuoi clienti Rivenditori un dominio dedicato e consentire loro di personalizzare interamente l’interfaccia web d’invio SMS Messenger con il loro logo, dominio etc su cui fare accedere i loro Clienti Finali. Tramite la piattaforma White Label inoltre potrai gestire i tuoi clienti (Rivenditori o Clienti Finali) ed inviare SMS preventivamente acquistati.

Tipologia API White Label

Il programma White Label mette a disposizione degli sviluppatori due tipologie di API:

  • API Backoffice
  • API Clienti finali

Un utente del sistema deve effettuare chiamate sempre e solo al server del proprio fornitore, sia quando usa le API Backoffice sia quando usa le API Clienti finali. Quello infatti è l'unico server presso cui abbia un account.

API Backoffice

Con queste API il Distributore / Rivenditore può gestire i clienti di cui è direttamente responsabile.

Restrizioni del servizio:

  • Il Distributore ha dei Clienti Finali e può avere dei Rivenditori.
  • Il Distributore può accedere alle risorse di tutti i clienti creati direttamente da lui, ovvero i propri Rivenditori e i propri Clienti Finali ma non ai Clienti Finali dei Rivenditori.
  • Il Rivenditore può accedere esclusivamente alle risorse dei propri Clienti Finali.
  • Il Rivenditore ha esclusivamente dei Clienti Finali e non può dotarsi di altri Rivenditori.

N.B.Tramite queste API non è possibile gestire le risorse della propria utenza. Per farlo si devono usare le API Clienti.

API Clienti finali

Con queste API Distributori, Rivenditori e Clienti Finali possono gestire servizi e funzionalità relative alla propria utenza ad esempio per inviare SMS andando in Invio SMS> Messaggio oppure effettuare interrogazioni in merito alle stesse.

Esempio di accesso ai domini

Un utente Distributore titolare del dominio sms.api.distributore.it crea gli account dei suoi clienti usando l'API Backoffice sull'host del suo fornitore all'URL http://api.smsmessenger.it. I clienti così creati invece utilizzeranno le API Backoffice e Clienti finali tramite il server del Distributore a http://sms.api.distributore.it

Analogamente il Distributore gestisce i dati del proprio account tramite http://api.smsmessenger.it, questa volta usando le API Clienti finali.

Note stilistiche documentazione API

All'interno della documentazione, per semplificare la comprensione, adotteremo i seguenti accorgimenti:

  • Si farà riferimento a Distributori e Rivenditori con il termine collettivo Distributori / Rivenditori (con la lettera minuscola), perché nella maggior parte dei casi questi due tipi di utenti hanno gli stessi ruoli e poteri amministrativi.
  • Quando vi fosse la necessità di distinguerli vi si farà riferimento esplicitamente con il nome di Distributori e Rivenditori (entrambi con la prima lettera maiuscola).

I parametri obbligatori sono contrassegnati con un asterisco .

API Esempi di utilizzo

Questa colonna contiene esempi di URL, richieste e risposte.

I prezzi compaiono solo a titolo di esempio e non corrispondono a reali offerte commerciali.

 

Autenticazione

Sono supportate la HTTP Basic Authentication e la HTTP Digest Authentication. Si raccomanda di utilizzare la Digest Authentication.

Basic Authentication

curl -D - -u username:password --basic \
http://api.smsmessenger.it/resources

Digest authentication

curl -D - -u username:password --digest \
http://api.smsmessenger.it/resources

Negli esempi si userà la Digest Authentication. Il default di curl è la Basic Authentication, quando è disponibile sul server.

 

Formato delle URL

Le URL seguono le convenzioni REST in cui i verbi HTTP indicano le operazioni eseguite sulle risorse indicate dalla URL.

Le URL delle API Backoffice hanno il prefisso resellers seguito dal nome della risorsa. Tutte le altre URL, che corrispondono alle API Cliente finale, se si riferiscono ad un particolare utente hanno il prefisso customers davanti al nome della risorsa, mentre hanno il formato /risorsa se restituiscono dati uguali per tutti i clienti.

Elenco oggetti in una risorsa
curl -D - -u username:password \
http://api.smsmessenger.it/resources

Dettaglio di un oggetto
curl -D - -u username:password \
http://api.smsmessenger.it/resources/id_risorsa

Creazione di un oggetto
curl -D - -u username:password \
-d attributo1=valore \
-d attributo2=valore \
-X POST http://api.smsmessenger.it/resources

Modifica di un oggetto
curl -D - -u username:password \
-d attributo1=nuovo_valore \
-d attributo2=nuovo_valore \
-X PUT http://api.smsmessenger.it/resources/id_risorsa

Cancellazione di un oggetto
curl -D - -u username:password \
-X DELETE http://api.smsmessenger.it/resources/id_risorsa

 

Formato dei dati

I valori di ritorno delle API sono in formato JSON e sono illustrati con esempi nella colonna di destra a fianco alle descrizioni delle chiamate all'API.

I numeri interi sono restituiti come numeri, ad esempio {"id_mt_price":3}.

I numeri decimali sono restituiti come stringhe per evitare errori di approssimazioni e lasciare all'applicazione client la massima libertà di manipolarli, ad esempio {"price":"0.100000"}. Si deve utilizzare il punto per separare la parte intera da quella decimale. L'uso della virgola non è consentito.

I boolean sono restituiti come numeri interi, 1 per true e 0 per false.

Le date sono restituite come stringhe nel formato ISO 8601 aaaa-mm-ggTOO:MM:SS+oooo, ad esempio {"created_at": "2013-05-09T10:15:34+0200"}.

Le stesse convenzioni si applicano per i valori inviati all'API.

Si indicherà il formato dei numeri decimali e la lunghezza delle stringhe nelle specifiche delle singole API. In generale i campi monetari hanno un formato decimal(X, Y) con Y cifre dopo la virgola e X - Y cifre prima della virgola. Il formato esatto viene indicato negli elenchi dei parametri delle singole chiamate.

I campi non inizializzati per cui non è previsto un default vengono restituiti come null, ad esempio: {"note": null}.

L'encoding usato dall'API è UTF-8 ma alcuni attributi di alcune risorse possono richiedere dati in formato ASCII 7 bit (ad esempio lo username di Cliente).

I valori passati negli esempi sono urlencoded

 

Errori

Il server utilizza i codici di risposta HTTP convenzionali per indicare il successo o il fallimento di una richiesta API. In generale, i codici della serie 2xx indicano successo, i codici della serie 4xx indicano un errore causato da informazioni passate in maniera non corretta (ad esempio un parametro obbligatorio mancante ecc), i codici della serie 5xx indicano un errore del server.

In caso d'errore il body della risposta è un array JSON chiamato errors composto da un hash con le chiavi

  • target: il nome del campo su cui si è verificato l'errore, ad esempio un attributo mancante in una chiamata all'API
  • errors: un ulteriore array con i messaggi d'errore relativi a target, così strutturato
    • code: il codice d'errore
    • reason: il messaggio d'errore

Per comporre un messaggio d'errore personalizzato è sufficiente estrarre target e code. In alcuni casi i target potrebbero avere degli array errors con più di un elemento.

I valori possibili di code e reason sono:

  • alnuminvalid: Invalid type given. String, integer or float expected
  • alnumstringempty: The input is an empty string
  • callbackinvalid: The input is not valid
  • callbackvalue: An exception has been raised within the callback
  • datefalseformat: The input does not fit the date format <formato>
  • dateinvalid: Invalid type given. String, integer, array or DateTime expected
  • dateinvaliddate: The input does not appear to be a valid date
  • hostnamecannotdecodepunycode: The input appears to be a DNS hostname but the given punycode notation cannot be decoded
  • hostnamedashcharacter: The input appears to be a DNS hostname but contains a dash in an invalid position
  • hostnameinvalid: Invalid type given. String expected
  • hostnameinvalidhostname: The input does not match the expected structure for a DNS hostname
  • hostnameinvalidhostnameschema: The input appears to be a DNS hostname but cannot match against hostname schema for TLD <dominio>
  • hostnameinvalidlocalname: The input does not appear to be a valid local network name
  • hostnameinvaliduri: The input does not appear to be a valid URI hostname
  • hostnameipaddressnotallowed: The input appears to be an IP address, but IP addresses are not allowed
  • hostnamelocalnamenotallowed: The input appears to be a local network name but local network names are not allowed
  • hostnameundecipherabletld: The input appears to be a DNS hostname but cannot extract TLD part
  • hostnameunknowntld: The input appears to be a DNS hostname but cannot match TLD against known list
  • norecordfound: No record matching the input was found
  • notalnum: The input contains characters which are non alphabetic and no digits
  • notbetween: The input is not between <min> and <max>, inclusively
  • notbetweenstrict: The input is not strictly between <min> and <>
  • recordfound: A record matching the input was found
  • regexerrorous: There was an internal error while using the pattern <pattern>
  • regexinvalid: Invalid type given. String expected
  • skinvalid: errore generico di validazione
  • skinvalidbody: Not valid
  • skinvalidcountry: Must be a string with length = <lunghezza>
  • skinvalidemail: Must be a valid email no longer than <lunghezza>
  • skinvalidid: Must be a valid id
  • skinvalidmoney: Must be greater than 0 and less than <max valuta>
  • skinvalidphone: Must be a valid phone number
  • skinvalidrecipient: Must specify from 1 to <max destinatari> recipients
  • skinvalidsender: Must specify a verified sender_number (max 11 digit) OR sender_string
  • skinvalidstring: Must be an alphanumeric string with max length
  • stringlengthtoolong: The input is more than <max> characters long
  • stringlengthtooshort: The input is less than <min> characters long

Codici errore HTTP

  • 200 OK
  • 400 Bad Request
  • 403 Forbidden
  • 404 Not Found
  • 405 Method Not Allowed
  • 500 Internal Server Error

JSON di errore

Questi sono i messaggi d'errore che si hanno effettuando una chiamata all'API di creazione clienti indicando solo il parametro obbligatorio type.


{
"errors": [{
  "target":"username",
  "errors": [{
    "code":"isEmpty",
    "reason":"Value is required and can't be empty"
  }] }, {
  "target":"password",
  "errors": [{
    "code":"isEmpty",
    "reason":"Value is required and can't be empty"
  }] }, {
  "target":"email",
  "errors": [{
    "code":"isEmpty",
    "reason":"Value is required and can't be empty"
  }] }, {
  "target":"domain",
  "errors": [{
    "code":"isEmpty",
    "reason":"Value is required and can't be empty"
  }] }, {
  "target":"locale",
  "errors": [{
    "code":"isEmpty",
    "reason":"Value is required and can't be empty"
  }] }, {
  "target":"timezone",
  "errors": [{
    "code":"isEmpty",
    "reason":"Value is required and can't be empty"
  }] }, {
  "target":"international_prefix",
  "errors": [{
    "code":"isEmpty",
    "reason":"Value is required and can't be empty"
  }] }
]}
 

Indice delle chiamate

In questa sezione si riassumono le chiamate delle API Backoffice e Clienti finali classificandole per il verbo HTTP che utilizzano. Secondo le convenzioni REST il verbo GET si usa per accedere ai contenuti di una risorsa, POST per creare un nuovo elemento, PUT e DELETE rispettivamente per modificarne e cancellarne uno esistente.

Poiché a seconda dell'URL indicata il verbo GET è usato sia per elencare gli elementi di una risorsa che per restituire un suo elemento dato un id, nelle tabelle si distinguono i due casi come GET per l'elenco e GET ID per il singolo elemento.

Alle chiamate che operano su risorse innestate si dedicano delle righe apposite delle tabelle. Ad esempio la GET / con cui si ottengono i Servizi in un Profilo è contenuta nella riga Servizi in un Profilo.

API Backoffice

RisorsaGET /GET /idPOSTPUTDELETE
Cliente  
Servizio      
Profilo cliente
Servizi in un Profilo        
Invio - Tariffa
Invio - Prezzi  
Invio - Ricarica  
Allerte    
Ricezione - Tariffa
Ricezione - Prezzi      
Ricezione - Ricarica Flat  
Keyword vendute  

API Clienti finali

RisorsaGET /GET /idPOSTPUTDELETE
Cliente      
Verifica Cliente      
Servizio        
Profilo cliente        
Invio - Tariffa        
Invio - Prezzi        
Invio - Ricarica        
Allerte    
Richiesta di verifica        
Numeri verificati    
Messaggi        
Notifica      
Ricezione - Tariffa      
Ricezione - Prezzi        
Ricezione - Ricarica Flat        
Keyword vendute    
Recapiti  
 

Inoltro Servizi di Ricezione

Il servizio di "Ricezione SMS" permette di ricevere SMS su un numero dedicato o su un numero condiviso tramite keyword, direttamente sul proprio server tramite una chiamata HTTP / Rest / Soap o attraverso l'invio di una email agli indirizzi indicati.

Alla ricezione di un SMS partirà una chiamata server-to-server (s2s) verso l'url o l'indirizzo email.

Per maggiori informazioni sull'impostazione dei Recapiti, fate riferimento alla sezione: Recapiti

 

API Backoffice

Negli esempi di questa sezione un utente user, nel ruolo di un Distributore, esegue delle chiamate amministrative al server White Label, qui indicato genericamente come server.

 

Cliente

La risorsa racchiude in sè tutti i dati principali dell'account di un cliente.
Il Distributore/Rivenditore avrà la possibilità di cancellare, modificare, creare e visualizzare la risorsa Cliente di cui è direttamente responsabile.
I valori usati dall'API in corrispondenza dei tre tipi di Cliente (attributo type) sono:

  • Distributore: wholesaler.
  • Rivenditore: reseller.
  • Cliente Finale: customer.

I clienti sono sempre identificati per username nelle chiamate dell'API e lo username è case insensitive nelle ricerche, ma viene memorizzato così come è passato in creazione. domain ed email sono case insensitive per definizione.

Si ricorda che l'API usa l'encoding UTF-8 per i dati trasferiti. Per alcuni attributi di Cliente si usa un sottoinsieme ASCII 7-bit. Sono i tre elencati qui sotto, di cui si danno anche i limiti di lunghezza e di formato:

  • Lo username può contenere solo lettere maiuscole, minuscole, cifre e i quattro caratteri - . @ _ (trattino, punto, at, underscore). Ha lunghezza minima di 3 caratteri e massima di 40.
  • Il domain ha lunghezza massima di 255 caratteri.
  • L'email ha lunghezza massima di 60 caratteri.
 

Elenco Clienti

Elenca i Rivenditori / Clienti Finali dell'utente, a seconda del proprio livello di accesso. I dati sono restituiti in un array.

È supportata la paginazione tramite l'uso dei parametri opzionali offset e limit.

È supportata la ricerca tramite la combinazione dei parametri opzionali business_name, phone ed email. Se nella stringa da ricercare compaiono degli asterischi * viene effettuata una ricerca per sottostringhe con le modalità del carattere % nello statement LIKE di SQL. In assenza di asterischi si effettua una ricerca sull'intero valore dell'attributo. La ricerca è case insensitive. Un valore vuoto passato come parametro di ricerca fa match con la stringa vuota e non con un campo con valore NULL. L'API non mette a disposizione metodi per fare ricerche su campi con valore NULL.

I diversi campi di ricerca sono combinati per default in AND ma si possono combinare in ORindicando il parametro andor nell'url.

Si possono combinare paginazione e ricerche.

Sintassi
GET /resellers/username-reseller/customers
con argomenti opzionali
  • offset offset
  • limit limite
  • email email
  • business-name nome
  • phone telefono
  • fk-profileid profilo
  • typetipo
  • op and/or
Argomenti URL
username_reseller*
stringusername con il quale ci si è registrati al servizio
offset
integer (positivo)in combinazione con il parametro limit definisce il sottoinsieme dell'array dei customer restituito dalla ricerca: offset indica l'indice del primo elemento da restituire.
limit
integer (positivo, default 50, max 100)indica la lunghezza dell'array da restituire e va usato in combinazione con offset; in assenza di limit si restituiscono sempre solo 50 elementi anche quando non è specificato l'offset
email
string (max 60 caratteri)il testo da ricercare all'interno dell'attributo email dei clienti secondo le modalità spiegate nell'introduzione di questa chiamata API
username
string (max 100 caratteri)il testo da ricercare all'interno dell'attributo username dei clienti secondo le modalità spiegate nell'introduzione di questa chiamata API
business_name
string (max 100 caratteri)il testo da ricercare all'interno dell'attributo business_name dei clienti secondo le modalità spiegate nell'introduzione di questa chiamata API
phone
string (max 50 caratteri)il testo da ricercare all'interno dell'attributo phone dei clienti secondo le modalità spiegate nell'introduzione di questa chiamata API
fk_profile
integeridentificativo del profilo dell'utente
type
string (max 50 caratteri)tipo di utente
Parametri da utilizzare
Tipi di utenti
op
stringAND (default) o OR, indica come si combinano i diversi campi di ricerca (email, business_name, phone)

ESEMPI DI RICHIESTE

curl -D - -u user:password --digest \
http://api.smsmessenger.it/resellers/user/customers

curl -D - -u user:password --digest \
http://api.smsmessenger.it/resellers/user/customers?offset=50&limit=50

ESEMPI DI RICERCHE

curl -D - -u user:password --digest \
'http://api.smsmessenger.it/resellers/user/customers?business_name=*mario*rossi*'

curl -D - -u user:password --digest \
'http://api.smsmessenger.it/resellers/user/customers?email=*example*'

Valori di ritorno
total
numero totale dei Clienti trovati, indipendentemente dal valore di limit
result
L'array dei Clienti trovati, al massimo in numero pari al valore di limit e a partire da offset, se indicato.

result è un array di

domain
dominio dell'utente che ha creato questo
business_name
nome, cognome e/o ragione sociale
contact
informazioni di contatto
created_at
ora e data in cui è stato creato l'utente
admin_domain
dominio dell'utente
email
email associata all'account
id_default_new_profile
identificativo numerico del profilo di default
id_profile
identificativo numerico del profilo
international_prefix
prefisso nazione (it, gb ..)
locale
lingua dell'utente (it_IT, en_US)
note
note sull'utente
phone
numero di telefono
status
stato in cui si trova l'account (active, disable)
timezone
fuso orario dell'utente
type
i vari tipi di utenti (wholesaler, reseller, customer)
username
username dell'utente
currency
moneta dell'utente

ESEMPIO DI RISPOSTA

Si tratta della risposta alla seconda call dell'esempio

Status Code: 200

{
"total":2,
result: [{
  "admin_domain":"example.com",
  "business_name":null,
  "contact":null,
  "created_at":"2013-04-30T12:44:06+0200",
  "domain":"server",
  "email":"mariorossi@example.com",
  "id_default_new_profile":15,
  "id_profile":4,
  "international_prefix":"it",
  "locale":"it_IT",
  "note":null,
  "phone":null,
  "status":"active",
  "timezone":"itrom",
  "type":"reseller",
  "username":"mariorossi",
  "currency":"EUR",
  },
  {
  "admin_domain":null,
  "business_name":null,
  "contact":null,
  "created_at":"2013-04-30T13:01:04+0200",
  "domain":"server",
  "email":"giorgiobianchi@example.org",
  "id_default_new_profile":null,
  "id_profile":4,
  "international_prefix":"it",
  "locale":"it_IT",
  "note":null,
  "phone":null,
  "status":"active",
  "timezone":"itrom",
  "type":"customer",
  "username":"giorgiobianchi",
  "currency":"USD"
  }]
}

 

Visualizzazione Cliente

Recupera le informazioni di un singolo Rivenditore / Cliente Finale a seconda del proprio livello di accesso.
Sintassi
GET /resellers/username-reseller/customers/username
Argomenti URL
username_reseller*
string (40 caratteri)username con il quale ci si è registrati al servizio
username*
string (40 caratteri)username con il quale il proprio Rivenditore / Cliente Finale si è registrato al servizio e di cui si vogliono visualizzare le informazioni

ESEMPIO DI RICHIESTA

curl -D - -u user:password --digest \
http://api.smsmessenger.it/resellers/user/customers/mariorossi

Valori di ritorno
domain
dominio dell'utente che ha creato questo
business_name
nome e cognome e/o ragione sociale
contact
informazioni di contatto
created_at
ora e data in cui è stato creato l'utente
admin_domain
dominio dell'utente
email
email associata all'account
id_profile
identificativo numerico del profilo
id_default_new_profile
identificativo numerico del profilo di default
international_prefix
prefisso nazione (it, gb ..)
locale
lingua dell'utente (it_IT, en_US)
note
note sull'utente
phone
numero di telefono
status
stato in cui si trova l'account (active, disable)
timezone
fuso orario dell'utente
type
i vari tipi di utenti (wholesaler, reseller, customer)
username
username dell'utente
currency
moneta dell'utente

ESEMPIO DI RISPOSTA

Status Code: 200

{
"admin_domain":"example.com",
"business_name":null,
"contact":null,
"created_at":"2013-04-30T12:44:06+0200",
"domain":"server",
"email":"mariorossi@example.com",
"id_default_new_profile":15,
"id_profile":4,
"international_prefix":"it",
"locale":"it_IT",
"note":null,
"phone":null,
"status":"active",
"timezone":"itrom",
"type":"reseller",
"username":"mariorossi",
"currency":"EUR",
}

Il valore di domain è "server" e quindi mariorossi effettua le chiamate all'API "http://api.smsmessenger.it". I clienti di mariorossi le effettuano all'admin_domain, "http://example.com/api".

 

Creazione Cliente

Creazione di un nuovo cliente.

Sintassi
POST /resellers/username-reseller/customers
BODY [parametri]
Argomenti URL
username_reseller*
string (40 caratteri)username con il quale il Distributore/Rivenditore si è registrato al servizio
Parametri BODY
business_name*
string (100 caratteri)nome e cognome e/o ragione sociale
contact
string (50 caratteri)informazioni di contatto
admin_domain
dipendente dal contesto, string (255 caratteri)È obbligatorio per la creazione di Rivenditori mentre non deve essere presente quando si creano Clienti Finali. È il dominio a cui si collegheranno i clienti del Rivenditore.
email*
string (60 caratteri)email associata all'account
id_profile
integerL'id del profilo da associare all'utente creato. In sua assenza si usa il profilo di default dell'utente che lo sta creando.
international_prefix*
string (2 caratteri)prefisso nazione (it, gb ..)
Parametri da utilizzare
Lista codici nazioni
locale*
stringlingua dell'utente
Parametri da utilizzare
  • it_IT
  • en_US
password*
string (min 5, max 32 caratteri)password dell'account non deve essere uguale allo username, si raccomanda di usare la massima lunghezza possibile
phone
string (50 caratteri)numero di telefono
note
string (255 caratteri)note per il Distributore/Rivenditore
type*
stringi vari tipi di utenti
Parametri da utilizzare
  • reseller
  • customer
timezone*
string (8 caratteri)fuso orario dell'utente
Parametri da utilizzare
Lista abbreviazioni
username*
string (min 3, max 40 caratteri)username dell'utente, sono permesse solo lettere e cifre
currency
stringmoneta dell'utente
Parametri da utilizzare
  • EUR
  • GBP
  • USD

ESEMPIO DI RICHIESTA

curl -D - -u user:password --digest \
-X POST \
http://api.smsmessenger.it/resellers/user/customers \
-d "business_name=Mario%20Rossi%20SpA" \
-d "domain=example.com" \
-d "email=mariorossi%40example.com" \
-d "international_prefix=it" \
-d "locale=it_IT" \
-d "password=password" \
-d "timezone=itrom" \
-d "type=reseller" \
-d "username=mariorossi" \
-d "currency=EUR"

Valori di ritorno
admin_domain
dominio amministrato dall'utente creato
business_name
nome e cognome e/o ragione sociale
contact
informazioni di contatto
created_at
ora e data in cui è stato creato l'utente
domain
dominio a cui l'utente creato dovrà collegarsi per operare (quello del suo Distributore/Rivenditore)
email
email associata all'account
id_profile
identificativo numerico del profilo
id_default_new_profile
identificativo numerico del profilo che sarà assegnato per default ai clienti di questo Distributore/Rivenditore (non si applica ai Clienti Finali); contiene i servizi disponibili al Distributore/Rivenditore
international_prefix
prefisso nazione (it, gb ..)
locale
lingua dell'utente (it_IT, en_US)
note
note sull'utente
phone
cognome utente
status
stato in cui si trova l'account (active, disable)
timezone
fuso orario dell'utente
type
i vari tipi di utenti (reseller, customer)
username
username dell'utente
currency
moneta dell'utente

ESEMPIO DI RISPOSTA

Status Code: 200

{
"admin_domain": "example.com",
"business_name": "Mario Rossi SpA",
"contact": null,
"created_at": "2013-04-30T12:44:06+0200",
"credit": null,
"domain": "server",
"email": "mariorossi@example.com",
"id_default_new_profile": 15,
"id_profile": 4,
"international_prefix": "it",
"locale": "it_IT",
"note": null,
"phone": null,
"status": "active",
"timezone": "itrom",
"type": "reseller",
"username": "mariorossi",
"currency": "EUR"
}

 

Modifica Cliente

Modifica i Rivenditori / Clienti Finali a seconda del proprio livello di accesso.

Sintassi
PUT /resellers/username-reseller/customers/username-customer
BODY [parametri]
Argomenti URL
username_reseller*
string (40 caratteri)username con il quale il Distributore/Rivenditore si è registrato al servizio
username_customer*
string (40 caratteri)username con il quale il proprio Rivenditore / Cliente Finale si è registrato al servizio e di cui si vogliono visualizzare le informazioni
Parametri BODY
business_name
string (100 caratteri)nome e cognome e/o ragione sociale
contact
string (50 caratteri)informazioni di contatto
admin_domain
dipendente dal contesto, string (255 caratteri)È obbligatorio per la creazione di Rivenditori mentre non deve essere presente quando si creano Clienti Finali. È il dominio a cui si collegheranno i clienti del Rivenditore.
email
string (60 caratteri)email associata all'account
id_profile
integerL'id del profilo da associare all'utente creato. In sua assenza si usa il profilo di default dell'utente che lo sta creando.
international_prefix
string (2 caratteri)prefisso nazione (it, gb ..)
Parametri da utilizzare
Lista codici nazioni
locale
stringlingua dell'utente
Parametri da utilizzare
  • it_IT
  • en_US
password
string (min 5, max 32 caratteri)password dell'account non deve essere uguale allo username, si raccomanda di usare la massima lunghezza possibile
phone
string (50 caratteri)numero di telefono
note
string (255 caratteri)note per il Distributore/Rivenditore
status
stringlo stato dell'utente
Parametri da utilizzare
  • active
  • disable
type
stringi vari tipi di utenti
Parametri da utilizzare
  • reseller
  • customer
timezone
string (8 caratteri)fuso orario dell'utente
Parametri da utilizzare
Lista abbreviazioni
username
string (min 3, max 40 caratteri)username dell'utente, sono permesse solo lettere e cifre
currency
stringmoneta dell'utente
Parametri da utilizzare
  • EUR
  • GBP
  • USD

ESEMPIO DI RICHIESTA

curl -D - -u user:password --digest \
-X PUT \
http://api.smsmessenger.it/resellers/user/customers/giorgiobianchi \
-d "contact=Informazioni di contatto"

Valori di ritorno
domain
dominio dell'utente che ha creato questo cliente
business_name
nome e cognome e/o ragione sociale
contact
informazioni di contatto
created_at
ora e data in cui è stato creato l'utente
admin_domain
dominio di questo cliente, solo se non è un Cliente Finale
email
email associata all'account
id_profile
identificativo numerico del profilo
id_default_new_profile
identificativo numerico del profilo di default
international_prefix
prefisso nazione (it, gb ..)
locale
lingua dell'utente (it_IT, en_US)
note
note sull'utente
phone
numero di telefono
status
stato in cui si trova l'account (active, disable)
timezone
fuso orario dell'utente
type
i vari tipi di utenti (reseller, customer)
username
username dell'utente
currency
moneta dell'utente

ESEMPIO DI RISPOSTA

Status Code: 200

{
"admin_domain":null,
"business_name":null,
"contact":"Informazioni di contatto",
"created_at":"2013-04-30T13:01:04+0200",
"domain":"server",
"email":"giorgiobianchi@example.org",
"id_default_new_profile":null,
"id_profile":4,
"international_prefix":"",
"locale":"it_IT",
"note":null,
"phone":null,
"status":"active",
"timezone":"",
"type":"customer",
"username":"giorgiobianchi",
"currency":"EUR"
}

 

Servizio

Questa risorsa gestisce i nomi con cui i Distributori / Rivenditori rinominano i servizi a loro disposizione.
Restrizioni:

  • Il Servizio è creato in automatico durante la creazione Distributore/Rivenditore e non può essere creato individualmente con una chiamata API..
  • Un Distributore come default ha i nomi dei servizi assegnati dal suo fornitore..
  • Un Rivenditore come default ha i nomi dei servizi assegnati dal suo Distributore..
  • I Distributori / Rivenditori potranno cambiare quei nomi in seguito..

I servizi sono identificati da un codice alfabetico (service-type) indipendentemente dai nomi assegnati. È garantita la corrispondenza tra questi type e questi servizi

  • F -> fixed: bassa qualità
  • D -> dynamic no report: senza notifica
  • R -> dynamic with report: con notifica

I servizi vengono aggregati in Profili, come spiegato più avanti.

 

Elenco Servizi

Recupera l'elenco dei servizi creati dal Distributore/Rivenditore.

Sintassi
GET /resellers/username-reseller/services
Argomenti URL
username_reseller*
string (40 caratteri)username con il quale ci si è registrati al servizio

ESEMPIO DI RICHIESTA


curl -D - -u user:password --digest \
http://api.smsmessenger.it/resellers/user/services

Valori di ritorno
id_service
id del servizio
type
tipo di servizio
name
nome del servizio

ESEMPIO DI RISPOSTA

Status Code: 200

[{
"id_service":4,
"type":"R",
"name":"SMS Classic Plus",
},
{
"id_service":5,
"type":"D",
"name":"SMS Classic",
}]

 

Modifica Servizio

Si usa esclusivamente per modificare il nome di un servizio.

Sintassi
PUT /resellers/username-reseller/services/id-service
BODY [parametri]
Argomenti URL
username_reseller*
string (40 caratteri)username con il quale ci si è registrati al servizio
id_service*
integerid del servizio di cui si vogliono restituire informazioni
Parametri BODY
name
stringnome del servizio

ESEMPIO DI RICHIESTA

Nell'esempio precedente "SMS Classic Plus" aveva id_service = 4. Con questa call lo si rinomina in "SMS con notifica"

curl -D - -u user:password --digest \
-X PUT \
http://api.smsmessenger.it/resellers/user/services/4 \
-d "name=SMS%20con%20notifica"

Valori di ritorno
id_service
id del servizio
type
tipo di servizio
name
nome del servizio

ESEMPIO DI RISPOSTA

Status Code: 200

{
"id_service":4,
"type":"R",
"name":"SMS con notifica",
}
 

Profilo cliente

Il profilo definisce i tipi di Servizi che il Distributore rende disponibili ai suoi Rivenditori e Clienti Finali, o quelli resi disponibili da un Rivenditore ai suoi Clienti Finali.
Ad esempio il profilo di default potrebbe contenere tutte le tipologie di SMS (Classic, Classic +, Basic) e la possibilità o meno di ricevere SMS.
Creare ed associare ai clienti profili diversi, vuol dire "oscurare" - non rendere disponibili - alcuni dei servizi offerti.
Restrizioni:

  • Un Distributore/Rivenditore può creare più profili da assegnare ai propri clienti diretti.
  • Ad ogni cliente creato può essere assegnato un solo profilo.

Ai Rivenditori che vengono creati viene già preparato un profilo identico per Servizi a quello del Distributore che li ha creati.

 

Elenco Profili clienti

Recupera l'elenco dei profili creati dai Distributori / Rivenditori.

Sintassi
GET /resellers/username-reseller/profiles
Argomenti URL
username_reseller*
string (40 caratteri)username con il quale ci si è registrati al servizio

ESEMPIO DI RICHIESTA

curl -D - -u user:password --digest \
http://api.smsmessenger.it/resellers/user/profiles

Valori di ritorno
id_profile
identificativo numerico del profilo cliente
name
nome scelto per il profilo

ESEMPIO DI RISPOSTA

Status Code: 200

[{
"id_profile":5,
"name":"Invio SMS"
},
{
"id_profile":6,
"name":"Ricezione SMS"
}]

 

Visualizzazione Profilo cliente

Recupera le informazioni riguardanti il profilo cliente.
Viene inoltre restituito il numero di clienti con quel determinato profilo, con le seguenti restrizioni:

  • nel conteggio vengono presi in considerazione solo i clienti di cui il Distributore/Rivenditore è direttamente responsabile.
Sintassi
GET /resellers/username-reseller/profiles/id-profile
Argomenti URL
id_profile*
integeridentificativo numerico del profilo di cui si vogliono restituite le informazioni

ESEMPIO DI RICHIESTA

curl -D - -u user:password --digest \
http://api.smsmessenger.it/resellers/user/profiles/5

Valori di ritorno
assigned_users
numero dei clienti che stanno usando questo profilo
id_profile
identificativo numerico del profilo cliente
name
nome scelto per il profilo
services
array degli id dei Servizi nel profilo

ESEMPIO DI RISPOSTA

Status Code: 200

{
"assigned_users":0
"id_profile":5,
"name":"Invio SMS",
"services":[4, 5]
}

 

Visualizzazione Servizi in un Profilo

Recupera le informazioni riguardanti i servizi contenuti in un Profilo.

Sintassi
GET /resellers/username-reseller/profiles/id-profile/services
Argomenti URL
username_reseller*
stringusername con il quale ci si è registrati al servizio
id_profile*
integeridentificativo numerico del profilo di cui si vogliono restituite le informazioni

ESEMPIO DI RICHIESTA

curl -D - -u user:password --digest \
http://api.smsmessenger.it/resellers/user/profiles/5/services

Valori di ritorno

Un array di:

id_service
identificativo numerico del servizio
type
codice che identifica il servizio
name
nome scelto per il servizio

ESEMPIO DI RISPOSTA

Status Code: 200

[{
"id_service":4,
"type":"R",
"name":"SMS Classic Plus",
},
{
"id_service":5,
"type":"D",
"name":"SMS Classic",
}]

 

Creazione Profilo cliente

Creazione di un nuovo profilo cliente.

Sintassi
POST /resellers/username-reseller/profiles
BODY [parametri]
Argomenti URL
username_reseller*
string (40 caratteri)username con il quale ci si è registrati al servizio
Parametri BODY
name*
string (50 caratteri)nome del profilo.
Ad esempio
tutto-incluso (profilo che permette agli utenti sia la ricezione che l'invio di SMS)
invio (profilo che consente esclusivamente l'invio di SMS)
ricezione (profilo che consente esclusivamente la ricezione di SMS)
services*
array(integer)elenco dei Servizi da associare al profilo elenco, espressi come array nella forma services[]=id1&services[]=id2&...

ESEMPIO DI RICHIESTA

curl -D - -u user:password --digest \
-X POST http://api.smsmessenger.it/resellers/user/profiles \
-d "name=Tutto%20incluso" \
-d "services[]=4" \
-d "services[]=5"

I servizi con id_service = 4 e 5 devono essere tra quelli restituiti da ResellersServiceList()

Valori di ritorno
id_profile
identificativo numerico del profilo cliente
name
nome scelto per il profilo

ESEMPIO DI RISPOSTA

Status Code: 200

{
"id_profile":16,
"name":"Tutto incluso"
}

 

Modifica Profilo cliente


Modifica di un profilo cliente esistente.
Restrizioni:
  • Non si possono modificare profili già venduti a clienti.


Sintassi
PUT /resellers/username-reseller/profiles/id-profile
BODY [parametri]
Argomenti URL
username_reseller*
string (40 caratteri)username con il quale ci si è registrati al servizio
id_profile*
integeridentificativo numerico del profilo
name
stringnome del servizio
services
array(integer, integer)elenco servizi da associare a questo profilo

ESEMPIO DI RICHIESTA

curl -D - -u user:password --digest \
-X PUT \
http://api.smsmessenger.it/resellers/user/profiles/16 \
-d "name=profilo%20modificato" \
-d "services[]=4"

Al Profilo 16 creato in precedenza è stato cambiato il nome. Inoltre ora è costituito dal solo Servizio 4. Il Servizio 5 è stato rimosso dal profilo perché non è stato incluso nell'array services[].

Valori di ritorno
id_profile
identificativo numerico del profilo cliente
name
nome scelto per il profilo

ESEMPIO DI RISPOSTA

Status Code: 200

{
"id_profile":16,
"name":"profilo modificato"
}

 

Assegnazione di un Profilo a un cliente

L'assegnazione e la modifica di un profilo si effettua operando sul parametro id-profile della risorsa Cliente (si veda Modifica cliente). Pertanto si utilizza quella API e non l'API Profilo. Il valore di ritorno è il Cliente a cui si è assegnato il profilo.

Dei parametri della update si indica solo quello necessario ad assegnare un profilo, tuttavia l'assegnazione può essere effettuata all'interno di una più ampia operazione di Modifica cliente.

Sintassi
PUT /resellers/username-reseller/customers/username-customer
BODY [parametri]
Argomenti URL
username_reseller*
string (40 caratteri)username con il quale ci si è registrati al servizio
username_customer*
string (40 caratteri)username con il quale il proprio Rivenditore / Cliente Finale si è registrato al servizio e di cui si vogliono visualizzare le informazioni
Parametri BODY
id_profile*
integeridentificativo numerico del profile da associare al cliente

ESEMPIO DI RICHIESTA

curl -D - -u user:password --digest \
-X PUT http://api.smsmessenger.it/resellers/user/customers/mariorossi \
-d "id_profile=16"

Valori di ritorno

Per l'elenco si faccia riferimento alla chiamata API Modifica Cliente

ESEMPIO DI RISPOSTA

Per l'esempio si faccia riferimento alla chiamata API Modifica Cliente

 

Cancellazione Profilo cliente

Cancellazione di un profilo cliente esistente. Non si possono cancellare profili già venduti a clienti (assignedUsers > 0).

Sintassi
DELETE /resellers/username-reseller/profiles/id-profile
Argomenti URL
username_reseller*
string (40 caratteri)username con il quale ci si è registrati al servizio
id_profile*
integeridentificativo numerico del profilo di cui si vogliono restituite le informazioni

ESEMPIO DI RICHIESTA

curl -D - -u user:password --digest \
-X DELETE \
http://api.smsmessenger.it/resellers/user/profiles/16

Valori di ritorno
true o un hash con l'errore a seconda dell'esito dell'operazione.

ESEMPIO DI RISPOSTA

Status Code: 200

{
"errors":[{
  "target":"services",
  "errors":[{
    "code":"skInvalid",
     "reason":"You can't delete a profile already assigned"
  }]
}]
}

Fallisce in quanto nell'esempio precedente avevamo assegnato questo profilo ad un Cliente

 

Tariffa (per invio SMS)

La risorsa Tariffa è accessibile solo dall'entità che ne è direttamente responsabile ed è il contenitore al cui interno si definiscono i Prezzi per nazione e per Servizio, come mostrato da questa tabella.

Servizio 1Servizio 2
Country 1PrezzoPrezzo
Country 2PrezzoPrezzo
defaultPrezzoPrezzo

Il contenuto delle celle della tabella sono i prezzi richiesti per un dato servizio per una data nazione e devono essere definiti con l'API della risorsa Prezzi di Invio a cui si passeranno il Servizio e lo stato o l'area geografica che permettono di definire la cella da valorizzare nella tabella. Gli stati e le aree geografiche sono un elenco fisso da cui si può scegliere e sono definiti nell'API dei Prezzi di invio.

Impostando l'attributo resellable (la rivendibilità) a false non si possono creare Ricariche con questa tariffa. Non ci sono impatti sulle ricariche esistenti, con cui i clienti potranno continuare a spedire messaggi.

Ogni Tariffa viene creata con un Prezzo di default per ogni Servizio che la compone. Indica il costo dei servizi quando non è stata specificata una combinazione Servizio/nazione o area geografica. I prezzi di default sono creati con il prezzo massimo possibile per il Servizio corrispondente e si possono modificare con l'API dei Prezzi, ma non cancellare.

 

Elenco Tariffe

Recupera l'elenco delle Tariffe di invio create da un Distributore/Rivenditore.

Sintassi
GET /resellers/username-reseller/mtrates
Argomenti URL
username_reseller*
string (40 caratteri)username con il quale ci si è registrati al servizio

ESEMPIO DI RICHIESTA

curl -D - -u user:password --digest \
http://api.smsmessenger.it/resellers/user/mtrates

Valori di ritorno
Un array di:
created_at
data e ora di creazione della tariffa
id_mt_rate
identificativo numerico della tariffa
name
nome della tariffa
note
note sulla tariffa
resellable
specifica se è creare ricariche con la tariffa (boolean)

ESEMPIO DI RISPOSTA

Status Code: 200

[{
"created_at":"2013-05-06T16:48:13+0200",
"id_mt_rate":1,
"name":"Estate",
"note":"rivenderla da giugno",
"resellable":0
},
{
"created_at":"2013-05-06T16:50:27+0200",
"id_mt_rate":2,
"name":"Autunno",
"note":"rivenderla da settembre",
"resellable":0
}]

 

Visualizzazione Tariffa

Recupera le informazioni di una singola Tariffa

Sintassi
GET /resellers/username-reseller/mtrates/id-mt-rate
Argomenti URL
username_reseller*
string (40 caratteri)username con il quale ci si è registrati al servizio
id_mt_rate*
integerid della tariffa di cui si vogliono ottenere indicazioni

ESEMPIO DI RICHIESTA

curl -D - -u user:password --digest \
http://api.smsmessenger.it/resellers/user/mtrates/1

Valori di ritorno
created_at
data e ora di creazione della tariffa
id_mt_rate
identificativo numerico della tariffa
name
nome della tariffa
note
note sulla tariffa
resellable
boolean che indica se è possibile creare ricariche con la tariffa

ESEMPIO DI RISPOSTA

Status Code: 200

{
"id_mt_rate":1,
"name":"Estate",
"note":"rivenderla da giugno",
"resellable":0,
"created_at":"2013-05-06T16:48:13+0200"
}

 

Creazione Tariffa

Creazione di una nuova Tariffa di invio.

Sintassi
POST /resellers/username-reseller/mtrates
BODY [parametri]
Argomenti URL
username_reseller*
string (40 caratteri)username con il quale ci si è registrati al servizio
Parametri BODY
name*
string (50 caratteri)nome della tariffa
note
string (255 caratteri)note sulla tariffa
resellable
booleanindica se la tariffa può essere venduta

ESEMPIO DI RICHIESTA

curl -D - -u user:password --digest \
-X POST \
http://api.smsmessenger.it/resellers/user/mtrates \
-d "name=Estate" \
-d "note=rivenderla%20da%20giugno" \
-d "resellable=0" \

Valori di ritorno
created_at
data e ora di creazione della tariffa
id_mt_rate
identificativo numerico della tariffa
name
nome della tariffa
note
note sulla tariffa
resellable
indica se è possibile rivendere la tariffa

ESEMPIO DI RISPOSTA

Status Code: 200

{
"id_mt_rate":1,
"name":"Estate",
"note":"rivenderla da giugno",
"resellable":0,
"created_at":"2013-05-06T16:48:13+0200"
}

 

Modifica Tariffa

Modifica di una Tariffa.

Sintassi
PUT /resellers/username-reseller/mtrates/id-mt-rate
BODY [parametri]
Argomenti URL
username_reseller*
string (40 caratteri)username con il quale ci si è registrati al servizio
Parametri BODY
name
string (50 caratteri)nome della tariffa
note
string (255 caratteri)note sulla tariffa
resellable
booleanindica se è possibile creare ricariche per la tariffa

ESEMPIO DI RICHIESTA

curl -D - -u user:password --digest \
-X PUT \
http://api.smsmessenger.it/resellers/user/mtrates/1 \
-d "note=Tariffa%20estate%202013" \
-d "resellable=1"

Valori di ritorno
id_mt_rate
identificativo numerico della tariffa
name
nome della tariffa
note
note sulla tariffa
resellable
indica la rivendibilità della tariffa, 1 se lo è, 0 se non lo è
created_at
data e ora di creazione della tariffa

ESEMPIO DI RISPOSTA

Status Code: 200

{
"id_mt_rate":1,
"name":"Estate",
"note":"Tariffa estate 2013",
"resellable":1,
"created_at":"2013-05-06T16:48:13+0200"
}

 

Cancellazione Tariffa

Cancellazione di una Tariffa esistente. Non si possono cancellare tariffe a cui siano già state associate delle ricariche. Per farlo vanno prima cancellate quelle.

Sintassi
DELETE /resellers/username-reseller/mtrates/id-mt-rate
Argomenti URL
username_reseller*
string (40 caratteri)username con il quale ci si è registrati al servizio
id_mt_rate*
integerid della tariffa che si vuole cancellare

ESEMPIO DI RICHIESTA

curl -D - -u user:password --digest \
-X DELETE \
http://api.smsmessenger.it/resellers/user/mtrates/1

Valori di ritorno
true o false a seconda dell'esito dell'operazione.

ESEMPIO DI RISPOSTA

Status Code: 200

{
"errors":[{
  "target":"mtrate",
  "errors":[{
    "code":"skCannotDelete",
     "reason":"To delete a mtrate, delete the associated mtprices first"
   }]
}]
}

Prima si deve chiamare l'API per ottenere l'elenco degli MtPrice relativi a questa MtRate e cancellarli.

 

Prezzo (per invio SMS)

I prezzi di un servizio di invio sono definiti per nazione e area geografica, e indicano ad esempio quanto costa inviare un messaggio 'SMS Classic' (un servizio) verso l'Italia (una country) o verso i paesi UE (un'area geografica).

Questi sono i passi che compongono il procedimento per determinare il costo di un messaggio:

  • Dal numero di telefono di destinazione si risale alla country.
  • Dato il tipo di messaggio si risale al Servizio corrispondente.
  • Dato il mittente si risale alla sua Ricarica più vecchia associata ad una Tariffa che abbia prezzi per quel Servizio.
  • Dati tariffa, servizio e country si cerca un Prezzo. Se esiste, quello è il costo del messaggio.
  • Se il Prezzo non esiste si cerca quello per la combinazione di tariffa, servizio ed area geografica a cui appartiene la country (l'elenco è qui). Se esiste, quello è il costo del messaggio.
  • Se non si è trovata nessuna corrispondenza il costo del messaggio sarà determinato dal prezzo di default per la combinazione di tariffa e servizio. Ogni Tariffa viene creata con un prezzo di default per ogni servizio. Questi default si possono solo modificare ma non cancellare per cui è garantito che un prezzo venga sempre trovato.

I prezzi per le country contengono l'attributo country (sigla ISO 3166 a due caratteri) mentre quelli per le aree geografiche contengono l'attributo id-geographical-area (un codice numerico). I prezzi di default non hanno nessuno di quei due attributi.

I Prezzi sono sempre associati ad una Tariffa per cui l'invio con la stessa combinazione di Servizio e nazione (o area geografica) può essere offerta a prezzi diversi purché in tariffe diverse. Ad esempio, facendo riferimento alle tariffe d'esempio Estate e Autunno usate in precedenza, il Servizio 'SMS Classic' per l'invio verso la UE potrebbe essere offerto ad una cifra più bassa nella tariffa Estate e ad una più alta in quella Autunno.

Il Prezzo ha un attributo position che può essere usato per indicare l'ordine di presentazione dei prezzi. Il suo effettivo utilizzo e le modalità in cui avviene dipendono dal client.

Le chiamate all'API dei prezzi differiscono da quelle delle altre risorse in quanto transazionali su un insieme di prezzi. Le chiamate per gli elenchi e le cancellazioni operano su tutti i prezzi con la stessa country, area geografica o di default (in quest'ultimo caso non è prevista la cancellazione). La chiamate di creazione non creano un singolo prezzo, ma tutti quelli con la stessa country o area geografica che quindi vanno passati tutti insieme. Analogamente le chiamate di modifica operano su tutti i prezzi per una country, area geografica o di default.

Per mantenere compatta la documentazione ed evitare ripetizioni nella sintassi delle chiamate compariranno tutte e tre le varianti. Negli elenchi degli argomenti e dei valori di ritorno si ricorderà che country e id_geographical_area sono restituiti solo per alcune chiamate.

 

Elenco Prezzi

L'elenco può essere richiesto a tre livelli di dettaglio.

  • Elenco dei prezzi di una country o di una singola area geografica.
  • Elenco dei prezzi di tutte le country, o di tutte aree geografiche o di default
  • Elenco complessivo, in cui data una Tariffa si restituisce l'elenco di tutti i suoi Prezzi, per country, area geografica e di default.
Sintassi
GET /resellers/username-reseller/mtrates/id-mt-rate/mtprices/countries/country
GET /resellers/username-reseller/mtrates/id-mt-rate/mtprices/geoareas/id-geographical-area

GET /resellers/username-reseller/mtrates/id-mt-rate/mtprices/countries
GET /resellers/username-reseller/mtrates/id-mt-rate/mtprices/geoareas
GET /resellers/username-reseller/mtrates/id-mt-rate/mtprices/defaults

GET /resellers/username-reseller/mtrates/id-mt-rate/mtprices
Argomenti URL
username_reseller*
string (40 caratteri)username con il quale ci si è registrati al servizio
id_mt_rate*
integerid della tariffa
country
string (2 caratteri)codice della country
id_geographical_area
integerid dell'area geoagrafica

ESEMPIO DI RICHIESTA

curl -D - -u user:password --digest \
http://api.smsmessenger.it/resellers/user/mtrates/1/mtprices/countries/it

curl -D - -u user:password --digest \
http://api.smsmessenger.it/resellers/user/mtrates/1/mtprices/geoareas/3

curl -D - -u user:password --digest \
http://api.smsmessenger.it/resellers/user/mtrates/1/mtprices/countries

curl -D - -u user:password --digest \
http://api.smsmessenger.it/resellers/user/mtrates/1/mtprices/geoareas

curl -D - -u user:password --digest \
http://api.smsmessenger.it/resellers/user/mtrates/1/mtprices/defaults

curl -D - -u user:password --digest \
http://api.smsmessenger.it/resellers/user/mtrates/1/mtprices

Valori di ritorno
Array di
id
sigla country o codice area geografica, non compare nei valori di ritorno per i defaults
mtprices
array dei prezzi per l'id indicato

L'array mtprices è composto da elementi con questi attributi:

country
sigla della nazione, compare solo nei valori di ritorno per countries
id_geographical_area
identificativo numerico dell'area geografica, solo nei valori di ritorno per geoareas
id_mt_price
identificativo numerico del prezzo
id_mt_rate
identificativo numerico della tariffa
id_service
identificativo numerico del servizio
position
ordine di presentazione
price
prezzo del servizio

ESEMPIO DI RISPOSTA

Risposta alla GET .../mtprices/defaults

Status Code: 200

[{
  "id":"it",
  "mtprices":[{
  "country":"it",
    "id_mt_price":3,
    "id_mt_rate":1,
    "id_service":1,
    "position":null,
    "price":"0.100000"
  }, {
    "country":"it",
    "id_mt_price":4,
    "id_mt_rate":1,
    "id_service":2,
    "position":null,
    "price":"0.190000"
  }]
}]

Risposta alla GET .../mtprices/defaults

Status Code: 200

[{
  "id":3,
  "mtprices":[{
    "id_geographical_area":3,
    "id_mt_price":7,
    "id_mt_rate":1,
    "id_service":1,
    "position":null,
    "price":"0.150000"
   }, {
    "id_geographical_area":3,
    "id_mt_price":8,
    "id_mt_rate":1,
    "id_service":2,
    "position":null,
    "price":"0.250000"
   }]
}

Risposta alla GET .../mtprices/defaults

La risposta è divisa in sotto array, uno per ogni country. L'id della country è presente a livello di array ed è ripetuto all'interno dei singoli Prezzi.

Status Code: 200

[{
  "id":"it",
  "mtprices":[{
  "country":"it",
    "id_mt_price":3,
    "id_mt_rate":1,
    "id_service":1,
    "position":null,
    "price":"0.100000"
  }, {
    "country":"it",
    "id_mt_price":4,
    "id_mt_rate":1,
    "id_service":2,
    "position":null,
    "price":"0.190000"
  }]
}, {
  "id":"fr",
  "mtprices":[{
  "country":"fr",
    "id_mt_price":5,
    "id_mt_rate":1,
    "id_service":1,
    "position":null,
    "price":"0.120000"
  }, {
    "country":"fr",
    "id_mt_price":6,
    "id_mt_rate":1,
    "id_service":2,
    "position":null,
    "price":"0.210000"
  }]
}]

Risposta alla GET .../mtprices/defaults

La risposta ha una struttura analoga alla precedente, con divisione per id_geographical_area.

Status Code: 200

[{
  "id":3,
  "mtprices":[{
    "id_geographical_area":3,
    "id_mt_price":7,
    "id_mt_rate":1,
    "id_service":1,
    "position":null,
    "price":"0.150000"
   }, {
    "id_geographical_area":3,
    "id_mt_price":8,
    "id_mt_rate":1,
    "id_service":2,
    "position":null,
    "price":"0.250000"
   }]
}, {
  "id":6,
  "mtprices":[{
    "id_geographical_area":6,
    "id_mt_price":9,
    "id_mt_rate":1,
    "id_service":1,
    "position":null,
    "price":"0.200000"
   }, {
    "id_geographical_area":6,
    "id_mt_price":10,
    "id_mt_rate":1,
    "id_service":2,
    "position":null,
    "price":"0.290000"
   }]
}]

Risposta alla GET .../mtprices/defaults

Si noti come l'array dei prezzi di default non sia diviso in ulteriori array, in quanto non esiste un altro livello gerarchico.

Status Code: 200

[{
"id_mt_price":1,
"id_mt_rate":1,
"id_service":1,
"position":null,
"price":"0.064000"
},
{
"id_mt_price":2,
"id_mt_rate":1,
"id_service":2,
"position":null,
"price":"0.068000"
}]

Risposta alla GET .../mtprices

Per brevità si dà solo la struttura generale della risposta con le classi degli oggetti contenuti negli array. I formati degli array sono identici a quelli delle tre risposte precedenti.

Status Code: 200

{
"countries":[
  {"id":"it", "mtprices":[ array degli MtPrice 3 e 4]}
  {"id":"fr", "mtprices":[ array degli MtPrice 5 e 6]}
],
"geoareas": [
  {"id":3, "mtprices":[ array degli MtPrice 7 e 8 ]},
  {"id":6, "mtprices":[ array degli MtPrice 9 e 10]}
],
"defaults": [ array degli MtPrice 1 e 2 ]
}

 

Creazione Prezzo

Crea tutti i prezzi per una data country o area geografica, uno per ogni Servizio nella Tariffa. Si deve passare come argomento l'array comprendente tutti i prezzi che saranno creati all'interno di una transazione e immediatamente disponibili (fatto salvo l'attributo resellable della Tariffa).

Non si possono creare i prezzi di default perché sono già creati insieme alla Tariffa.

L'elenco delle aree geografiche con i loro codici numerici e le nazioni che le compongono è qui.

Sintassi
POST /resellers/username-reseller/mtrates/id-mt-rate/mtprices/countries/country
POST /resellers/username-reseller/mtrates/id-mt-rate/mtprices/geoareas/id-geographical-area
BODY [parametri]
Argomenti URL
username_reseller*
string (40 caratteri)username con il quale ci si è registrati al servizio
id_mt_rate*
integerid della tariffa
country
solo per le chiamate country, string (2 caratteri)sigla ISO della nazione
Parametri da utilizzare
Lista codici nazioni
id_geographical_area
solo per le chiamate geoarea, integeridentificativo numerico dell'area geografica
Parametri da utilizzare
Lista codici area geografica
Parametri BODY
id_service*
integeridentificativo numerico del servizio di cui si vuole specificare il prezzo
price*
decimal(11, 6)prezzo del servizio, deve essere indicato con il punto decimale e non con la virgola
position
integerordine di presentazione

ESEMPIO DI RICHIESTA

Per creare i prezzi di una country

curl -D - -u user:password --digest \
-X POST \
http://api.smsmessenger.it/resellers/user/mtrates/1/mtprices/countries/it \
-d "mtprices[0][id_service]=1" \
-d "mtprices[0][price]=0.10" \
-d "mtprices[1][id_service]=2" \
-d "mtprices[1][price]=0.19"

Per creare i prezzi di un'area geografica

curl -D - -u user:password --digest \
-X POST \
http://api.smsmessenger.it/resellers/user/mtrates/1/mtprices/geoareas/3 \
-d "mtprices[0][id_service]=1" \
-d "mtprices[0][price]=0.15" \
-d "mtprices[1][id_service]=2" \
-d "mtprices[1][price]=0.25"

Valori di ritorno
Un array di
id_mt_price
identificativo numerico del prezzo
id_mt_rate
identificativo numerico della tariffa
id_service
identificativo numerico del servizio
position
Determina la riga della tabella Prezzi in cui la GUI dovrebbe visualizzare questo prezzo
price
prezzo del servizio

ESEMPIO DI RISPOSTA

Risposta alla POST .../countries/it

Status Code: 200

[{
"id_mt_price":3,
"id_mt_rate":1,
"id_service":1,
"position":null,
"price":"0.100000"
}, {
"id_mt_price":4,
"id_mt_rate":1,
"id_service":2,
"position":null,
"price":"0.190000"
}]

Risposta alla POST .../geoareas/3

Status Code: 200

[{
"id_mt_price":5,
"id_mt_rate":1,
"id_service":1,
"position":null,
"price":"0.120000"
}, {
"id_mt_price":6,
"id_mt_rate":1,
"id_service":2,
"position":null,
"price":"0.210000"
}]

 

Modifica Prezzo

La modifica dei Prezzi è transazionale ed avviene simultaneamente su tutti i Prezzi di una stessa country, area geografica o di default. Tutti quei Prezzi vanno passati come argomento, anche quelli dei servizi che non vengono modificati.

L'elenco delle aree geografiche con i loro codici numerici e le nazioni che le compongono è qui.

Sintassi
PUT /resellers/username-reseller/mtrates/id-mt-rate/mtprices/countries/country
PUT /resellers/username-reseller/mtrates/id-mt-rate/mtprices/geoareas/id-geographical-area
PUT /resellers/username-reseller/mtrates/id-mt-rate/mtprices/defaults
BODY [parametri]
Argomenti URL
username_reseller*
string (40 caratteri)username con il quale ci si è registrati al servizio
id_mt_rate*
integerid della tariffa da modificare
country
solo per le chiamate country, string (2 caratteri)sigla ISO della nazione
Parametri da utilizzare
Lista codici nazioni
id_geographical_area
solo per le chiamate geoarea, integeridentificativo numerico dell'area geografica
Parametri da utilizzare
Lista codici area geografica
Parametri BODY
id_mt_price*
integerid del prezzo
id_service*
integerid del servizio
position
integerordine di visualizzazione
price*
decimal(11, 6)prezzo del servizio

ESEMPIO DI RICHIESTA

Per modificare i prezzi di una country

curl -D - -u user:password --digest \
-X PUT \
http://api.smsmessenger.it/resellers/user/mtrates/1/mtprices/countries/it \
-d "mtprices[0][id_mt_price]=3" \
-d "mtprices[0][id_service]=1" \
-d "mtprices[0][price]=0.10" \
-d "mtprices[1][id_mt_price]=4" \
-d "mtprices[1][id_service]=2" \
-d "mtprices[1][price]=0.20"

Per modificare i prezzi di default

curl -D - -u user:password --digest \
-X PUT \
http://api.smsmessenger.it/resellers/user/mtrates/1/mtprices/geoareas/3 \
-d "mtprices[0][id_mt_price]=5" \
-d "mtprices[0][id_service]=1" \
-d "mtprices[0][price]=0.15" \
-d "mtprices[1][id_mt_price]=6" \
-d "mtprices[1][id_service]=2" \
-d "mtprices[1][price]=0.26"

Per modificare i prezzi di default

curl -D - -u user:password --digest \
-X PUT \
http://api.smsmessenger.it/resellers/user/mtrates/1/mtprices/defaults \
-d "mtprices[0][id_mt_price]=1" \
-d "mtprices[0][id_service]=1" \
-d "mtprices[0][price]=0.30" \
-d "mtprices[1][id_mt_price]=2" \
-d "mtprices[1][id_service]=2" \
-d "mtprices[1][price]=0.40"

Valori di ritorno

Viene restituito un array di Prezzi contenente i prezzi aggiornati. Gli elementi dell'array hanno gli attributi

id_mt_price
identificativo numerico del prezzo
id_mt_rate
identificativo numerico della tariffa
id_service
identificativo numerico del servizio
id_geographical_area
identificativo numerico dell'area geografica, solo per le chiamate geoarea
country
sigla della nazione, solo per le chiamate country
position
ordine di presentazione
price
prezzo del servizio

ESEMPIO DI RISPOSTA

Status Code: 200

{
"country":"fr",
"id_geographical_area":null,
"id_mt_price":4,
"id_mt_rate":1,
"id_service":2,
"position":null,
"price":"0.032000"
}

 

Cancellazione Prezzo

Le cancellazioni sono transazionali ed avvengono simultaneamente su tutti i Prezzi di una stessa country o area geografica. Non si possono cancellare i prezzi di default. Quei prezzi sono creati insieme alla Tariffa e si possono solo modificare.

L'elenco delle aree geografiche con i loro codici numerici e le nazioni che le compongono è qui.

Sintassi
DELETE /resellers/username-reseller/mtrates/id-mt-rate/mtprices/countries/country
DELETE /resellers/username-reseller/mtrates/id-mt-rate/mtprices/geoareas/id-geographical-area
Argomenti URL
username_reseller*
string (40 caratteri)username con il quale ci si è registrati al servizio
id_mt_rate*
integerid della tariffa di cui cancellare i prezzi
country
solo per le chiamate country, string (2 caratteri)sigla ISO della nazione
Parametri da utilizzare
Lista codici nazioni
id_geographical_area
solo per le chiamate geoarea, integeridentificativo numerico dell'area geografica
Parametri da utilizzare
Lista codici area geografica

ESEMPIO DI RICHIESTA

Per cancellare i prezzi di una country

curl -D - -u user:password --digest \
-X DELETE \
http://api.smsmessenger.it/resellers/user/mtrates/1/mtprices/countries/it

Per cancellare i prezzi di un'area geografica

curl -D - -u user:password --digest \
-X DELETE \
http://api.smsmessenger.it/resellers/user/mtrates/1/mtprices/geoareas/3

Valori di ritorno
true o false a seconda dell'esito dell'operazione.

ESEMPIO DI RISPOSTA

Status Code: 200

true

 

Ricarica (per invio SMS)

Le Ricariche sono create da chi le vende. Per il cliente è disponibile solo una call per elencarle, nell'API Clienti finali.

 

Elenco Ricariche

Recupera l'elenco delle Ricariche di un cliente.

Sintassi
GET /resellers/username-reseller/customers/username-customer/mtrecharges
Argomenti URL
username_reseller*
string (40 caratteri)username con il quale ci si è registrati al servizio
username_customer*
string (40 caratteri)username del Rivenditore / Cliente Finale

ESEMPIO DI RICHIESTA

curl -D - -u user:password --digest \
http://api.smsmessenger.it/resellers/user/customers/mariorossi/mtrecharges

Valori di ritorno
Un array di:
id_mt_recharge
numero identificativo della ricarica
id_mt_rate
numero identificativo della tariffa
money_purchased
credito acquistato
money_available
credito disponibile
status
stato della ricarica
created_at
data e ora creazione della ricarica

ESEMPIO DI RISPOSTA

Status Code: 200

[{
"id_mt_recharge":1,
"id_mt_rate":3,
"money_purchased":"50.00",
"money_available":"23.824700",
"status":"active",
"created_at":"2013-05-07T17:11:00+0200"
},
{
"id_mt_recharge":2,
"id_mt_rate":3,
"money_purchased":"50.00",
"money_available":"50.00",
"status":"active",
"created_at":"2012-05-12T13:23:00+0200"
}]

 

Creazione Ricarica

Creazione di una nuova Ricarica.

Sintassi
POST /resellers/username-reseller/customers/username-customer/mtrecharges
BODY [parametri]
Argomenti URL
username_reseller*
string (40 caratteri)username con il quale ci si è registrati al servizio
username_customer*
string (40 caratteri)username del Rivenditore / Cliente Finale a cui si vuole associare la ricarica
Parametri BODY
id_mt_rate*
integeridentificativo numerico della tariffa per questa ricarica
money_purchased*
decimal(11, 6)credito da caricare

ESEMPIO DI RICHIESTA

curl -D - -u user:password --digest \
-X POST \
http://api.smsmessenger.it/resellers/user/customers/mariorossi/mtrecharges \
-d "id_mt_rate=3" \
-d "money_purchased=50.00"

Valori di ritorno
id_mt_recharge
numero identificativo della ricarica
id_mt_rate
numero identificativo della tariffa
money_purchased
credito acquistato
money_available
credito disponibile
status
stato della ricarica
created_at
data e ora creazione della ricarica

ESEMPIO DI RISPOSTA

Status Code: 200

{
"id_mt_recharge":7,
"id_mt_rate":3,
"money_purchased":"50.00",
"money_available":"50.00",
"status":"active",
"created_at":"2013-05-16T15:45:24+0200"
}

 

Modifica Ricarica

È possibile modificare solo lo status. Per modificare money_available si deve bloccare la ricarica e crearne una nuova con il valore desiderato.

Sintassi
PUT /resellers/username-reseller/customers/username-customer/mtrecharges/id-mt-recharge
BODY [parametri]
Argomenti URL
username_reseller*
string (40 caratteri)username con il quale ci si è registrati al servizio
username_customer*
string (40 caratteri)username del Rivenditore / Cliente Finale associato alla ricarica
id_mt_recharge*
integerid della ricarica da modificare, deve essere una ricarica di username-customer
Parametri BODY
status*
stringlo stato della ricarica
Parametri da utilizzare
  • active
  • blocked

ESEMPIO DI RICHIESTA

curl -D - -u user:password --digest \
-X PUT \
http://api.smsmessenger.it/resellers/user/customers/mariorossi/mtrecharges/7 \
-d "status=blocked"

Valori di ritorno
id_mt_recharge
numero identificativo della ricarica
id_mt_rate
numero identificativo della tariffa
money_purchased
credito acquistato
money_available
credito disponibile
status
stato della ricarica
created_at
data e ora creazione della ricarica

ESEMPIO DI RISPOSTA

Status Code: 200

{
"id_mt_recharge":7,
"id_mt_rate":3,
"money_purchased":"50.00",
"money_available":"50.00",
"status":"blocked",
"created_at":"2013-05-16T15:45:24+0200"
}

 

Cancellazione Ricarica

Cancellazione di una Ricarica.

Sintassi
DELETE /resellers/username-reseller/customers/username-customer/mtrecharges/id-mt-recharge
Argomenti URL
username_reseller*
stringusername con il quale ci si è registrati al servizio
username_customer*
stringusername del Rivenditore / Cliente Finale a cui si vuole cancellare la ricarica
id_mt_recharge*
integerid della ricarica da cancellare

ESEMPIO DI RICHIESTA

curl -D - -u user:password --digest \
-X DELETE \
http://api.smsmessenger.it/resellers/user/customers/mariorossi/mtrecharges/7

Valori di ritorno
true o false a seconda dell'esito dell'operazione.

ESEMPIO DI RISPOSTA

Status Code: 200

true

 

Allerta (per invio SMS)

Permette di gestire le allerte per le ricariche dei propri clienti. Le allerte vengono create insieme al cliente e non si possono cancellare.

Le allerte sono tre e sono contraddistinte da una position e da una money-threeshold. La position ha esclusivamente lo scopo di identificare un'allerta in fase di modifica. Non ha influenza sull'ordine in cui scattano le notifiche, che è regolato solo dai valori di money-threeshold. Questo significa che è indifferente avere money-threeshold pari a 100, 50, 10 nelle position 1, 2 e 3 o in quelle 3, 2, 1.

 

Elenco Allerte

Recupera l'elenco delle allerte di un proprio cliente. Contiene sempre tre MtAlert con position 1, 2 e 3.

Sintassi
GET /reseller/username-reseller/customers/username-customer/mtalerts
Argomenti URL
username_reseller*
string (40 caratteri)username con il quale ci si è registrati al servizio
username_customer*
stringusername del cliente di cui si vogliono elencare le allerte

ESEMPIO DI RICHIESTA

curl -D - -u user:password --digest \
http://api.smsmessenger.it/reseller/user/customers/mariorossi/mtalerts

Valori di ritorno
Un array di:
position
posizione dell'allerta
username
username del cliente a cui è associata l'allerta
money_threshold
limite entro il quale va mandata l'allerta
email_address_1
prima email a cui mandare l'allerta
email_address_2
seconda email a cui mandare l'allerta
email_address_3
terza email a cui mandare l'allerta
sms_phone_1
primo numero di telefono a cui mandare l'allerta
sms_phone_2
secondo numero di telefono a cui mandare l'allerta

ESEMPIO DI RISPOSTA

Status Code: 200

[{
"position":1,
"username":"mariorossi",
"money_threshold":"100.000000",
"email_address_1":"allarme1@example.com",
"email_address_2":null,
"email_address_3":null,
"sms_phone_1":"395556677888",
"sms_phone_2":null
},
{
"position":2,
"money_threshold":"50.000000",
"username":"mariorossi",
"email_address_1":"allarme1@example.com",
"email_address_2":"allarme2@example.com",
"email_address_3":null,
"sms_phone_1":"395556677888",
"sms_phone_2":null
},
{
"position":3,
"username":"mariorossi",
"money_threshold":"20.000000",
"email_address_1":"allarme1@example.com",
"email_address_2":"allarme2@example.com",
"email_address_3":null,
"sms_phone_1":"395556677888",
"sms_phone_2":null
}]

 

Visualizzazione Allerta

Recupera il dettaglio di una allerta di un proprio cliente.

Sintassi
GET /reseller/username-reseller/customers/username-customer/mtalerts/position
Argomenti URL
username_reseller*
string (40 caratteri)username con il quale ci si è registrati al servizio
username_customer*
stringusername del cliente a cui si riferisce l'allerta
position*
integerposizione dell'allerta di cui si vogliono informazioni

ESEMPIO DI RICHIESTA

curl -D - -u mariorossi:password --digest \
http://server/resellers/user/customers/mariorossi/mtalerts/1

Valori di ritorno
position
posizione dell'allerta
username
username del cliente a cui è associata l'allerta
money_threshold
limite entro il quale va mandata l'allerta
email_address_1
prima email a cui mandare l'allerta
email_address_2
seconda email a cui mandare l'allerta
email_address_3
terza email a cui mandare l'allerta
sms_phone_1
primo numero di telefono a cui mandare l'allerta
sms_phone_2
secondo numero di telefono a cui mandare l'allerta

ESEMPIO DI RISPOSTA

Status Code: 200

{
"position":1,
"username":"mariorossi",
"money_threshold":"100.000000",
"email_address_1":"allarme1@example.com",
"email_address_2":null,
"email_address_3":null,
"sms_phone_1":"395556677888",
"sms_phone_2":null
}

 

Modifica Allerta

Modifica una allerta di un proprio cliente.

Sintassi
PUT /reseller/username-reseller/customers/username-customer/mtalerts/position
BODY [parametri]
Argomenti URL
username_reseller*
string (40 caratteri)username con il quale ci si è registrati al servizio
username_customer*
stringusername del cliente a cui si riferisce l'allerta
position*
integerposizione dell'allerta di cui si vogliono informazioni
Parametri BODY
money_threshold
decimal(11, 6)limite entro il quale va mandata l'allerta
email_address_1
string (60 caratteri)prima email a cui mandare l'allerta
email_address_2
string (60 caratteri)seconda email a cui mandare l'allerta
email_address_3
string (60 caratteri)terza email a cui mandare l'allerta
sms_phone_1
string (20 caratteri, solo cifre)primo numero di telefono a cui mandare l'allerta
sms_phone_2
string (20 caratteri, solo cifre, niente +)secondo numero di telefono a cui mandare l'allerta


ESEMPIO DI RICHIESTA

curl -D - -u mariorossi:password --digest \
-X PUT \
http://server/resellers/user/customers/mariorossi/mtalerts/3 \
-d "money_threshold=10.00" \
-d "email_address_1=test%40example.com" \
-d "email_address_2=ceo%40example.com" \
-d "email_address_3=info%40example.com" \
-d "sms_phone_1=39333728374" \
-d "sms_phone_2=338291283"

Valori di ritorno
position
posizione dell'allerta
username
username del cliente a cui è associata l'allerta
money_threshold
limite entro il quale va mandata l'allerta
email_address_1
prima email a cui mandare l'allerta
email_address_2
seconda email a cui mandare l'allerta
email_address_3
terza email a cui mandare l'allerta
sms_phone_1
primo numero di telefono a cui mandare l'allerta
sms_phone_2
secondo numero di telefono a cui mandare l'allerta

ESEMPIO DI RISPOSTA

Status Code: 200

{
"position":1,
"username":"mariorossi",
"money_threshold":"10.00",
"email_address_1":"test@example.com",
"email_address_2":"ceo@example.com",
"email_address_3":"info@example.com",
"sms_phone_1":"39333728374",
"sms_phone_2":"338291283"
}

 

Tariffa (per ricezione SMS)

La risorsa Tariffa è accessibile solo dall'entità che ne è direttamente responsabile ed è il contenitore al cui interno si definiscono i Prezzi di Ricezione. Al momento sono disponibili solo le tariffe flat pertanto i prezzi sono definiti al mese.

Una risorsa Tariffa definisce il nome della tariffa e il suo stato di rivendibilità. I dettagli relativi al prezzo richiesto devono essere definiti con l'API della risorsa Prezzi di ricezione.

La rivendibilità permette di creare tariffe non subito rivendibili ai propri clienti o di bloccare delle tariffe dopo che sono arrivate alla fine del periodo programmato per la loro vendita.

Ogni Tariffa viene creata con un Prezzo di default per ogni Servizio che la compone. Indica il costo dei servizi quando non è stata specificata una combinazione Servizio/nazione o area geografica. I prezzi di default sono creati con il prezzo massimo possibile per il Servizio corrispondente e si possono modificare con l'API dei Prezzi, ma non cancellare.

 

Elenco Tariffe

Sintassi
GET /resellers/username-reseller/morates
Argomenti URL
username_reseller*
string (40 caratteri)username con il quale ci si è registrati al servizio

ESEMPIO DI RICHIESTA

curl -D - -u user:password --digest \
http://api.smsmessenger.it/resellers/user/morates

Valori di ritorno
Un array di:
created_at
data e ora di creazione della tariffa
id_mo_rate
identificativo numerico della tariffa
name
nome della tariffa
note
note sulla tariffa
resellable
specifica se è possibile rivendere la tariffa (boolean)

ESEMPIO DI RISPOSTA

Status Code: 200

[{
"id_mo_rate":10,
"name":"Ricezione",
"note":null,
"resellable":1,
"created_at":"2013-05-16T15:22:48+0200"
}]

 

Visualizzazione Tariffa

Recupera le informazioni di una singola Tariffa

Sintassi
GET /resellers/username-reseller/morates/id-mo-rate
Argomenti URL
username_reseller*
string (40 caratteri)username con il quale ci si è registrati al servizio
id_mo_rate*
integerid della tariffa di cui si vogliono ottenere indicazioni

ESEMPIO DI RICHIESTA

curl -D - -u user:password --digest \
http://api.smsmessenger.it/resellers/user/morates/10

Valori di ritorno
created_at
data e ora di creazione della tariffa
id_mo_rate
identificativo numerico della tariffa
name
nome della tariffa
note
note sulla tariffa
resellable
boolean che indica se è possibile creare ricariche per la tariffa

ESEMPIO DI RISPOSTA

Status Code: 200

{
"id_mo_rate":10,
"name":"Ricezione",
"note":null,
"resellable":1,
"created_at":"2013-05-16T15:22:48+0200"
}

 

Creazione Tariffa

Creazione di una nuova Tariffa di invio.

La tariffa viene creata con i relativi Prezzi che potranno poi essere impostati usando l'API di modifica Prezzi.

Sintassi
POST /resellers/username-reseller/morates
BODY [parametri]
Argomenti URL
username_reseller*
string (40 caratteri)username con il quale ci si è registrati al servizio
Parametri BODY
name*
string (50 caratteri)nome della tariffa
note
string (255 caratteri)note sulla tariffa
resellable
booleanindica se si possono creare ricariche per questa tariffa

ESEMPIO DI RICHIESTA

curl -D - -u user:password --digest \
-X POST \
http://api.smsmessenger.it/resellers/user/morates \
-d "name=Ricezione" \
-d "resellable=1"
Valori di ritorno
created_at
data e ora di creazione della tariffa
id_mo_rate
identificativo numerico della tariffa
name
nome della tariffa
note
note sulla tariffa
resellable
indica se si possono creare ricariche per questa tariffa

ESEMPIO DI RISPOSTA

Status Code: 200

{
"id_mo_rate":10,
"name":"Ricezione",
"note":null,
"resellable":1,
"created_at":"2013-05-16T15:22:48+0200"
}

 

Modifica Tariffa

Modifica di una Tariffa.

Sintassi
PUT /resellers/username-reseller/morates/id-mo-rate
BODY [parametri]
Argomenti URL
username_reseller*
string (40 caratteri)username con il quale ci si è registrati al servizio
Parametri BODY
name
string (50 caratteri)nome della tariffa
note
string (255 caratteri)note sulla tariffa
resellable
booleanindica se è possibile creare ricariche per la tariffa


ESEMPIO DI RICHIESTA

curl -D - -u user:password --digest \
-X PUT \
http://api.smsmessenger.it/resellers/user/morates/10 \
-d "name=Ricezione%20estate%202013" \
-d "note=vendere%20da%20giugno" \
-d "resellable=0"

Valori di ritorno
id_mo_rate
identificativo numerico della tariffa
name
nome della tariffa
note
note sulla tariffa
resellable
indica se è possibile creare ricariche per la tariffa, 1 se lo è, 0 se non lo è
created_at
data e ora di creazione della tariffa

ESEMPIO DI RISPOSTA

Status Code: 200

{
"id_mo_rate":10,
"name":"Ricezione estate 2013",
"note":"rivendere da giugno",
"resellable":0,
"created_at":"2013-05-16T15:22:48+0200"
}

 

Cancellazione Tariffa

Cancellazione di una Tariffa esistente. Non si possono cancellare tariffe a cui siano già state associate delle ricariche. Per farlo vanno prima cancellate quelle.

Cancellando una Tariffa sono rimossi anche i prezzi a lei collegati. Questo è l'unico modo in cui è possibile cancellare un Prezzo di ricarica.

Sintassi
DELETE /resellers/username-reseller/morates/id-mo-rate
Argomenti URL
username_reseller*
string (40 caratteri)username con il quale ci si è registrati al servizio
id_mo_rate*
integerid della tariffa che si vuole cancellare

ESEMPIO DI RICHIESTA

curl -D - -u user:password --digest \
-X DELETE \
http://api.smsmessenger.it/resellers/user/morates/10

Valori di ritorno
true o false a seconda dell'esito dell'operazione.

ESEMPIO DI RISPOSTA

Status Code: 200

true

 

Prezzo (per ricezione SMS)

Definisce il costo di ricevere un messaggio su un numero dedicato o condiviso. I Prezzi sono creati insieme alla tariffa e si possono modificare. L'unico modo per cancellarli è rimuovere la Tariffa a cui sono associati.

 

Elenco Prezzi

Recupera l'elenco dei Prezzi.

Sintassi
GET /resellers/username-reseller/morates/id-mo-rate/moprices
Argomenti URL
username_reseller*
string (40 caratteri)username con il quale ci si è registrati al servizio
id_mo_rate*
integerid della tariffa

ESEMPIO DI RICHIESTA

curl -D - -u user:password --digest \
http://api.smsmessenger.it/resellers/user/morates/10/moprices

Valori di ritorno
Un array di:
id_mo_price
identificativo numerico del prezzo
id_mo_rate
identificativo numerico della tariffa
price
il costo di un mese
type
dedicated se il prezzo è per un numero dedicato o shared per un numero condiviso

ESEMPIO DI RISPOSTA

Status Code: 200

[{
"id_mo_price":1,
"id_mo_rate":10,
"price":"30.00",
"type":"dedicated"
},
{
"id_mo_price":2,
"id_mo_rate":10,
"price":null,
"type":"shared"
}]

Il prezzo per la ricezione su numero dedicato è stato impostato mentre quello per la ricezione su numero condiviso deve ancora essere definito.

 

Modifica Prezzo

Permette di impostare il valore di prezzo di ricezione, che è l'unico attributo modificabile. La risorsa è creata con prezzo null insieme alla Tariffa corrispondente.

Sintassi
PUT /resellers/username-reseller/mtrates/id-mo-rate/moprices/id-mo-price
BODY [parametri]
Argomenti URL
username_reseller*
string (40 caratteri)username con il quale ci si è registrati al servizio
id_mo_rate*
integerid della tariffa
id_mt_price*
integerid del prezzo da modificare
Parametri BODY
price*
decimal(11, 6)il costo di un mese

ESEMPIO DI RICHIESTA

curl -D - -u user:password --digest \
-X PUT \
http://api.smsmessenger.it/resellers/user/morates/10/moprices/2 \
-d "price=20.00"

Valori di ritorno
id_mo_price
identificativo numerico del prezzo
id_mo_rate
identificativo numerico della tariffa
price
il costo di un mese
type
dedicated se il prezzo è per un numero dedicato o shared per un numero condiviso

ESEMPIO DI RISPOSTA

Status Code: 200

{
"id_mo_price":2,
"id_mo_rate":10,
"price":"20.00",
"type":"shared"
}

 

Ricarica flat (per ricezione SMS)

Le Ricariche flat indicano per quanti mesi il cliente ha comprato un servizio di ricezione su un numero condiviso o dedicato, al costo indicato dal Prezzo associato alla Tariffa.

Il riferimento al numero dedicato o condiviso è dato dall'attributo id-mo-sold-keyword che indica la Keyword venduta. Per avere un elenco di id per le proprie keyword si deve far riferimento alla chiamata Elenco Keyword

Le Ricariche si possono bloccare usando la chiamata di modifica e cambiandone lo stato a revoked o blocked.

 

Elenco Ricariche

Recupera l'elenco delle Ricariche di un cliente.

Sintassi
GET /resellers/username-reseller/customers/username-customer/morechargesflat
Argomenti URL
username_reseller*
string (40 caratteri)username con il quale ci si è registrati al servizio
username_customer*
string (40 caratteri)username del Rivenditore / Cliente Finale

ESEMPIO DI RICHIESTA

curl -D - -u user:password --digest \
http://api.smsmessenger.it/resellers/user/customers/mariorossi/morechargesflat

Valori di ritorno
Un array di:
created_at
data e ora creazione della ricarica
id_mo_recharge_flat
numero identificativo della ricarica
id_mo_rate
numero identificativo della tariffa
id_mo_sold_keyword
numero identificativo della keyword (per ricezione su numeri condivisi)
months_purchased
numero di mesi acquistati al prezzo indicato dalla Tariffa
status
stato della ricarica (active, revoked, blocked, expired)
username
username del cliente

ESEMPIO DI RISPOSTA

Status Code: 200

[{
"created_at":"2013-05-17T11:50:01+0200",
"id_mo_recharge_flat":1,
"id_mo_rate":3,
"id_mo_sold_keyword":2,
"months_purchased":3,
"status":"active",
"username":"mariorossi",
},
{
"created_at":"2013-05-17T11:52:15+0200",
"id_mo_recharge_flat":1,
"id_mo_rate":3,
"id_mo_sold_keyword":3,
"months_purchased":2,
"status":"active",
"username":"mariorossi"
}]

 

Creazione Ricarica

Creazione di una nuova Ricarica.

Trattandosi di una ricarica flat il prezzo applicato è quello che tra i prezzi restituiti dalla tariffa ha type = dedicated o shared, a seconda che la mo_soldkeyword associata alla ricarica sia relativa ad un numero dedicato o condiviso.

Il prezzo a cui è stata comprata la ricarica viene copiato nella ricarica per mantenere il riferimento anche quando il prezzo fosse cambiato successivamente.

Sintassi
POST /resellers/username-reseller/customers/username-customer/morechargesflat
BODY [parametri]
Argomenti URL
username_reseller*
string (40 caratteri)username con il quale ci si è registrati al servizio
username_customer*
string (40 caratteri)username del Rivenditore / Cliente Finale a cui si vuole associare la ricarica
Parametri BODY
id_mo_rate*
integeridentificativo numerico della tariffa per questa ricarica
id_mo_sold_keyword*
integeridentificativo numerico della keyword per cui si compra la ricarica
months_purchased*
intnumero di mesi da accreditare

ESEMPIO DI RICHIESTA

curl -D - -u user:password --digest \
-X POST \
http://api.smsmessenger.it/resellers/user/customers/mariorossi/morechargesflat \
-d "id_mo_rate=10" \
-d "id_mo_sold_keyword=2" \
-d "months_purchased=3"

Valori di ritorno
created_at
data e ora creazione della ricarica
id_mo_recharge_flat
numero identificativo della ricarica
id_mo_rate
numero identificativo della tariffa
id_mo_sold_keyword
numero identificativo della keyword (per ricezione su numeri condivisi)
months_purchased
numero di mesi acquistati al prezzo indicato dalla Tariffa
single_month_price
copia del prezzo indicato dalla Tariffa al momento della creazione della Ricarica
status
stato della ricarica (active, revoked, blocked, expired)
username
username del cliente

ESEMPIO DI RISPOSTA

Status Code: 200

{
"created_at":"2013-05-17T11:50:01+0200",
"id_mo_recharge_flat":1,
"id_mo_rate":10,
"id_mo_sold_keyword":2,
"months_purchased":3,
"single_month_price":"30.00",
"status":"active",
"username":"mariorossi",
}

 

Modifica Ricarica

È possibile modificare solo lo status. Per modificare money_available si deve bloccare la ricarica e crearne una nuova con il valore desiderato.

Sintassi
PUT /resellers/username-reseller/customers/username-customer/morechargesflat/id-mo-recharge-flat
BODY [parametri]
Argomenti URL
username_reseller*
string (40 caratteri)username con il quale ci si è registrati al servizio
username_customer*
string (40 caratteri)username del Rivenditore / Cliente Finale associato alla ricarica
id_mo_recharge_flat*
integerid della ricarica da modificare, deve essere una ricarica di username-customer
Parametri BODY
status*
stringlo stato della ricarica
Parametri da utilizzare
  • active
  • revoked
  • blocked
  • expired

ESEMPIO DI RICHIESTA

curl -D - -u user:password --digest \
-X PUT \
http://api.smsmessenger.it/resellers/user/customers/mariorossi/morechargesflat/1 \
-d "status=blocked"

Valori di ritorno
created_at
data e ora creazione della ricarica
id_mo_recharge_flat
numero identificativo della ricarica
id_mo_rate
numero identificativo della tariffa
id_mo_sold_keyword
numero identificativo della keyword (per ricezione su numeri condivisi)
months_purchased
numero di mesi acquistati al prezzo indicato dalla Tariffa
single_month_price
copia del prezzo indicato dalla Tariffa al momento della creazione della Ricarica
status
stato della ricarica (active, revoked, blocked, expired)
username
username del cliente

ESEMPIO DI RISPOSTA

Status Code: 200

{
"created_at":"2013-05-17T11:50:01+0200",
"id_mo_recharge_flat":1,
"id_mo_rate":10,
"id_mo_sold_keyword":2,
"months_purchased":3,
"single_month_price":"30.00",
"status":"blocked",
"username":"mariorossi",
}

 

Cancellazione Ricarica

Cancellazione di una Ricarica.

Sintassi
DELETE /resellers/username-reseller/customers/username-customer/morechargesflat/id-mo-recharge-flat
Argomenti URL
username_reseller*
stringusername con il quale ci si è registrati al servizio
username_customer*
stringusername del Rivenditore / Cliente Finale a cui si vuole cancellare la ricarica
id_mo_recharge_flat*
integerid della ricarica da cancellare

ESEMPIO DI RICHIESTA

curl -D - -u user:password --digest \
-X DELETE \
http://api.smsmessenger.it/resellers/user/customers/mariorossi/morechargesflat/1

Valori di ritorno
true o false a seconda dell'esito dell'operazione.

ESEMPIO DI RISPOSTA

Status Code: 200

true

 

Keyword vendute (per ricezione SMS)

Le Keyword includono sia i numeri dedicati che quelli condivisi. A distinguerli è il valore del campo subkeyword che è null per i numeri dedicati ed è una stringa di caratteri per una Keyword su numeri condivisi.

La ricezione su un numero dedicato (es: +39.1234) avviene inviando ai recapiti associati alla Keyword ogni messaggio che arriva a quel numero. Il numero è ad uso esclusivo di un solo utente.

La ricezione su un numero condiviso avviene estraendo la prima parola del messaggio ricevuto (es: numero +39.1234 e prima parola "SMS") e trovando la Keyword con subkeyword uguale a quella parola. Il messaggio viene inviato ai recapiti associati alla Keyword, che apparterranno tutti allo stesso utente.

Le Keyword sono organizzate in una gerarchia che tiene traccia dei livelli di rivendita. Un Distributore ha una Keyword creata in automatico quando l'acquista. Un suo Rivenditore ha una Keyword creata dal Distributore quando questi gliela rivende e lo stesso avviene per il Cliente Finale.

Un numero dedicato può essere rivenduto come tale o si possono creare subkeyword e rivenderlo come numero condiviso. Per un dato numero non è permessa la creazione di ulteriori subkeyword a qualsiasi livello della gerarchia. Quindi è possibile avere le due keyword "1234 CIAO" e "1234 HELLO" ma non "1234 CIAO HELLO" con più keyword in successione nello stesso messaggio.

Il collegamento tra un livello e l'altro della gerarchia è dato dall'attributo id-parent-keyword.

Per creare Keyword per sé stessi si deve usare l'API clienti di ricezione.

La scadenza della Keyword avviene al termine del giorno indicato in expires-at.

 

Elenco Keyword vendute

Recupera l'elenco delle Keyword vendute.

Sintassi
GET /resellers/username-reseller/customers/username-customer/mosoldkeywords
Argomenti URL
username_reseller*
string (40 caratteri)username con il quale ci si è registrati al servizio
username_customer*
string (40 caratteri)username del Rivenditore / Cliente Finale

ESEMPIO DI RICHIESTA

curl -D - -u user:password --digest \
http://api.smsmessenger.it/resellers/user/customers/mariorossi/mosoldkeywords

Valori di ritorno
Un array di:
alert_enabled
indica la presenza di un'allerta sulla scadenza della keyword
created_at
data e ora di creazione della keyword
expires_at
data e ora di scadenza della keyword
id_parent_keyword
identificativo numerico della keyword padre, null se questa è la prima della gerarchia
id_mo_sold_keyword
identificativo numerico della keyword
number
numero su cui vengono ricevuti i messaggi
status
stato della keyword ('test', 'active', 'grace', 'expired', 'revoked', 'blocked')
subkeyword
la prima parola della Keyword o null per una Keyword che rappresenta un numero dedicato
username
username del cliente

ESEMPIO DI RISPOSTA

Status Code: 200

[{
"alert_enabled":0,
"created_at":"2013-05-20T14:37:34+0200",
"expires_at":"2013-08-20T23:59:59+0200",
"id_parent_keyword":1,
"id_mo_sold_keyword":2,
"number":"1234",
"status":"active",
"subkeyword":"SMS",
"username":"mariorossi"
}]

 

Visualizzazione Keyword venduta

Mostra il dettaglio di una Keyword.

Sintassi
GET /resellers/username-reseller/customers/username-customer/mosoldkeywords/id-mo-sold-keyword
Argomenti URL
username_reseller*
string (40 caratteri)username con il quale ci si è registrati al servizio
username_customer*
string (40 caratteri)username del Rivenditore / Cliente Finale
id_mo_sold_keyword*
intidentificativo numerico della keyword

ESEMPIO DI RICHIESTA

curl -D - -u user:password --digest \
http://api.smsmessenger.it/resellers/user/customers/mariorossi/mosoldkeywords/2

Valori di ritorno
alert_enabled
indica la presenza di un'allerta sulla scadenza della keyword
created_at
data e ora di creazione della keyword
expires_at
data e ora di scadenza della keyword
id_parent_keyword
identificativo numerico della keyword padre, null se questa è la prima della gerarchia
id_mo_sold_keyword
identificativo numerico della keyword
number
numero su cui vengono ricevuti i messaggi
status
stato della keyword ('test', 'active', 'grace', 'expired', 'revoked', 'blocked')
subkeyword
la prima parola della Keyword o null per una Keyword che rappresenta un numero dedicato
username
username del cliente

ESEMPIO DI RISPOSTA

Status Code: 200

{
"alert_enabled":0,
"created_at":"2013-05-20T14:37:34+0200",
"expires_at":"2013-08-20T23:59:59+0200",
"id_parent_keyword":1,
"id_mo_sold_keyword":2,
"number":"1234",
"status":"active",
"subkeyword":"SMS",
"username":"mariorossi"
}

 

Creazione Keyword vendute

Si devono indicare l'id-parent-keyword, pari all'id-mo-sold-keyword di una propria Keyword, la subkeyword, che è null per la rivendita di un numero dedicato, e la data di scadenza della Keyword. La Keyword scade al termine del giorno indicato.

Il parametro id-parent-keyword deve essere una delle proprie keyword, che potete trovare con la chamata Elenco keyword

Sintassi
POST /resellers/username-reseller/customers/username-customer/mosoldkeywords
Argomenti URL
username_reseller*
string (40 caratteri)username con il quale ci si è registrati al servizio
username_customer*
string (40 caratteri)username del Rivenditore / Cliente Finale
Parametri BODY
id_parent_keyword*
intid numerico della keyword padre
subkeyword
string (50 caratteri)prima parola del messaggio, solo quando si crea una subkeyword per un numero dedicato

ESEMPIO DI RICHIESTA

curl -D - -u user:password --digest \
-X POST \
http://api.smsmessenger.it/resellers/user/customers/mariorossi/mosoldkeywords
-d "id_parent_keyword=1"
-d "subkeyword=SMS"

Valori di ritorno
created_at
data e ora di creazione della keyword
id_parent_keyword
identificativo numerico della keyword padre, null se questa è la prima della gerarchia
id_mo_soldkeyword
identificativo numerico della keyword
number
numero su cui vengono ricevuti i messaggi
subkeyword
la prima parola della Keyword o null per una Keyword che rappresenta un numero dedicato
username
username del cliente

ESEMPIO DI RISPOSTA

Status Code: 200

[{
"created_at":"2013-05-20T14:37:34+0200",
"expires_at":"2013-08-20T23:59:59+0200",
"id_parent_keyword":null,
"id_mo_soldkeyword":1,
"number":"1234",
"status":"active",
"subkeyword":"SMS",
"username":"mariorossi"
}]

 

Modifica keyword vendute

Per rivendere una keyword ad un altro cliente se ne deve creare una nuova, con la stessa subeyword e un diverso periodo di validità. Si consiglia anche di lasciare un periodo di grazia affinché al nuovo assegnatario della Keyword non arrivino messaggi destinati al precedente: è possibile che i mittenti non siano a conoscenza della fine del periodo d'uso della Keyword e mandino messaggi oltra sua la data di scadenza.

Due o più Keyword con la stessa subkeyword non possono essere attive nello stesso periodo temporale.

Sintassi
PUT /resellers/username-reseller/customers/username-customer/mosoldkeywords/id-mo-sold-keyword
Argomenti URL
id_mo_sold_keyword*
intidentificativo numerico della keyword
username_reseller*
string (40 caratteri)username con il quale ci si è registrati al servizio
username_customer*
string (40 caratteri)username del Rivenditore / Cliente Finale
Parametri BODY

ESEMPIO DI RICHIESTA

curl -D - -u user:password --digest \
-X PUT \
http://api.smsmessenger.it/resellers/user/customers/mariorossi/mosoldkeywords

Valori di ritorno
created_at
data e ora di creazione della keyword
id_parent_keyword
identificativo numerico della keyword padre, null se questa è la prima della gerarchia
id_mo_soldkeyword
identificativo numerico della keyword
number
numero su cui vengono ricevuti i messaggi
subkeyword
la prima parola della Keyword o null per una Keyword che rappresenta un numero dedicato
username
username del cliente

ESEMPIO DI RISPOSTA

Status Code: 200

{
"alert_enabled":0,
"created_at":"2013-05-20T14:37:34+0200",
"expires_at":"2013-08-20T23:59:59+0200",
"full":1,
"id_parent_keyword":null,
"id_mo_soldkeyword":1,
"number":"1234",
"status":"blocked",
"subkeyword":"SMS",
"username":"mariorossi"
}

 

API Clienti finali

per gestire i dati dei propri clienti. Negli esempi successivi si trova ad accedere ai dati del proprio account e lo deve fare tramite l'API Clienti finali in quanto per questo tipo di accesso il ruolo all'interno della gerarchia degli utenti non ha importanza. Le URL chiamate dauser fanno riferimento sempre allo stesso server, perché le operatività amministrativa e non amministrativa di uno stesso utente avvengono sempre sullo stesso server con lo stesso account. Negli esempi compaiono anche chiamate fatte da uno dei clienti di user, che vengono rivolte al server nell'admin-domain di user.

 

Cliente

La risorsa permette l'accesso ai dati del proprio account.

 

Visualizzazione Cliente

Un utente può usare questa chiamata API solo per accedere alle informazioni del proprio account, pertanto per il parametro username_customer è accettato solo il valore del proprio nome utente.

Sintassi
GET /customers/username-customer
Argomenti URL
username_customer*
string (40 caratteri)username con il quale ci si è registrati al servizio

ESEMPIO DI RICHIESTA

curl -D - -u mariorossi:password --digest \
http://server/customers/mariorossi

Valori di ritorno
domain
dominio a cui l'utente effettua le chiamate API
business_name
nome e cognome e/o ragione sociale
contact
informazioni di contatto
created_at
ora e data in cui è stato creato l'utente
admin_domain
dominio dell'utente, null per i Clienti Finali
email
email associata all'account
id_profile
identificativo numerico del profilo
id_default_new_profile
identificativo numerico del profilo di default
international_prefix
prefisso nazione (it, gb ..)
locale
lingua dell'utente (it_IT, en_US)
note
note sull'utente
phone
numero di telefono
status
stato in cui si trova l'account(active, disable)
timezone
fuso orario dell'utente
type
i vari tipi di utenti (reseller, customer)
username
username dell'utente
currency
moneta dell'utente

ESEMPIO DI RISPOSTA

Status Code: 200

{
"admin_domain":"example.com",
"business_name":null,
"contact":null,
"created_at":"2013-04-30T12:44:06+0200",
"domain":"server",
"email":"mariorossi@example.com",
"id_default_new_profile":15,
"id_profile":4,
"international_prefix":"it",
"locale":"it_IT",
"note":null,
"phone":null,
"status":"active",
"timezone":"itrom",
"type":"reseller",
"username":"mariorossi",
"currency":"EUR"
}

mariorossi è il reseller creato da user negli esempi precedenti.

L'attributo admin_domain = example.com è il server gestito da mariorossi, a cui fanno le chiamate i suoi clienti.
L'attributo domain = server è il server del fornitore di mariorossi ed è quello a cui mariorossi fa le chiamate.
Il fornitore di mariorossi (che è user) invece fa le sue chiamate a api.smsmessenger.it, come mostrato in tutti gli esempi.

 

Modifica Cliente


Modifica dei dati del proprio profilo.

Sintassi
PUT /customers/username-customer
BODY [parametri]
Argomenti URL
username_customer*
stringusername con il quale ci si è registrati al servizio
Parametri BODY
business_name
stringnome e cognome e/o ragione sociale
contact
stringinformazioni di contatto
admin_domain
solo per i Distributori / Rivenditori, stringdominio dell'utente
email
stringemail associata all'account
locale
stringlingua dell'utente
Parametri da utilizzare
  • it_IT
  • en_US
id_default_new_profile
solo per i Distributori / Rivenditori, integeridentificativo numerico profilo di default
international_prefix
string (2 caratteri)prefisso nazione (it, uk, ...)
Parametri da utilizzare
Lista codici nazioni
phone
stringnumero di telefono
currency
stringmoneta dell'utente
Parametri da utilizzare
  • EUR
  • GBP
  • USD


ESEMPIO DI RICHIESTA

curl -D - -u user:password --digest \
-X PUT \
http://server/customers/user \
-d "business_name=Nuova%20Sample%20Company" \
-d "phone=%2B390212345678"

Si noti come il + all'inizio del numero di telefono viene codificato come %2B

Valori di ritorno
domain
dominio dell'utente che ha creato questo
business_name
nome e cognome e/o ragione sociale
contact
informazioni di contatto
created_at
ora e data in cui è stato creato l'utente
admin_domain
dominio dell'utente
email
email associata all'account
id_default_new_profile
identificativo numerico del profilo di default
international_prefix
prefisso nazione (it, uk, ...)
locale
lingua dell'utente (it_IT, en_US)
note
note sull'utente
phone
numero di telefono
timezone
fuso orario dell'utente
status
stato in cui si trova l'account (active, disable)
type
i vari tipi di utenti (wholesaler, reseller, customer)
username
username dell'utente
currency
moneta dell'utente

ESEMPIO DI RISPOSTA

Status Code: 200

{
"admin_domain":"server",
"business_name":"Nuova Sample Company",
"contact":null,
"created_at":"2013-04-20T11:47:19+0200",
"domain":"example.net",
"email":"user@example.net",
"id_default_new_profile":2,
"id_profile":1,
"international_prefix":"it",
"locale":"it_IT",
"note":null,
"phone":"+390212345678",
"status":"active",
"timezone":"itrom",
"type":"wholesaler",
"username":"user",
"currency":"EUR"
 }

 

Servizio

La risorsa permette l'accesso a tutti i servizi usufruibili dalla propria utenza.

 

Elenco Servizi

Recupera l'elenco dei propri servizi. Sono visibili solo quelli inclusi nel proprio Profilo.

Sintassi
GET /customers/username-customer/services
Argomenti URL
username_customer*
stringusername con il quale ci si è registrati al servizio

ESEMPIO DI RICHIESTA

curl -D - -u user:password --digest \
http://api.smsmessenger.it/customers/user/services

curl -D - -u mariorossi:password --digest \
http://server/customers/mariorossi/services

mariorossi è un cliente di user e quindi effettua le chiamate al server di user.

Valori di ritorno
Un array di:
id_service
id del servizio
type
tipo di servizio, con gli stessi codici descritti qui
name
nome del servizio

ESEMPIO DI RISPOSTA

Questa è la risposta alla chiamata di mariorossi

Status Code: 200

[{
"id_service":4,
"type":"R",
"name":"SMS con notifica",
},
{
"id_service":5,
"type":"D",
"name":"SMS Classic",
}]

L'esempio assume che questi siano i servizi contenuti nel profilo attualmente assegnato a mariorossi.

 

Profilo cliente

Tramite l'API Clienti finali si accede alle informazioni sui Profili messi a disposizione dal rivenditore al cliente. Maggiori informazioni sui Profili sono date nella parte a loro dedicata nell'API Backoffice.

 

Visualizzazione Profilo cliente

Recupera le informazioni di dettaglio di un profilo.
Sintassi
GET /customers/username-customer/profiles/id-profile
Argomenti URL
username_customer*
string (40 caratteri)username con il quale ci si è registrati al servizio
id_profile*
integeridentificativo numerico del profilo

ESEMPIO DI RICHIESTA

curl -D - -u mariorossi:password --digest \
http://server/customer/mariorossi/profiles/5

Valori di ritorno
id_profile
identificativo numerico del profilo
name
nome del profilo

ESEMPIO DI RISPOSTA

Status Code: 200

{
"id_profile":5,
"name":"Invio SMS"
}

 

Tariffa (per invio SMS)

Permette di accedere ai dati delle Tariffe del proprio Distributore/Rivenditore.

 

Visualizzazione Tariffa

Mostra i dettagli di una Tariffa.

Sintassi
GET /customers/username-customer/mtrates/id-mt-rate
Argomenti URL
username_customer*
stringusername con il quale ci si è registrati al servizio
id_mt_rate*
integerl'id della Tariffa da visualizzare

ESEMPIO DI RICHIESTA

curl -D - -u user:password --digest \
http://server/customers/mariorossi/mtrates/2

Valori di ritorno
id_mt_rate
identificativo numerico della tariffa
name
nome della tariffa
note
note sulla tariffa
resellable
specifica se è possibile rivendere la tariffa (boolean)
created_at
data e ora di creazione della tariffa

ESEMPIO DI RISPOSTA

Status Code: 200

{
"id_mt_rate":2,
"name":"Autunno",
"note":"rivenderla da settembre",
"resellable":0,
"created_at":"2013-05-06T16:50:27+0200"
}

Ai codici degli mt_rate si risale con MtRechargeList()

 

Prezzo (per invio SMS)

Permette di accedere ai prezzi pagati dalla propria utenza.

 

Elenco Prezzi

Recupera l'elenco di tutti i Prezzi di tutte le country, o di tutte le aree geografiche o i prezzi default. Se l'MtRate non esiste restituisce un elenco vuoto. I Prezzi sono restituiti in un array.

Sintassi
GET /customers/username-customer/mtrates/id-mt-rate/mtprices/countries
GET /customers/username-customer/mtrates/id-mt-rate/mtprices/geoareas
GET /customers/username-customer/mtrates/id-mt-rate/mtprices/defaults
GET /customers/username-customer/mtrates/id-mt-rate/mtprices
Argomenti URL
username_customer*
string (40 caratteri)username con il quale ci si è registrati al servizio
id_mt_rate*
integeridentificativo numerico della tariffa di cui si vogliono restituire i prezzi

ESEMPIO DI RICHIESTA

Richiesta per i prezzi delle aree geografiche

curl -D - -u mariorossi:password --digest \
http://server/customers/mariorossi/mtrates/3/mtprices/countries

Richiesta per i prezzi delle aree geografiche

curl -D - -u mariorossi:password --digest \
http://server/customers/mariorossi/mtrates/3/mtprices/geoareas

Richiesta per i prezzi di default

curl -D - -u mariorossi:password --digest \
http://server/customers/mariorossi/mtrates/3/mtprices/defaults

Richiesta per tutti i prezzi

curl -D - -u mariorossi:password --digest \
http://server/customers/mariorossi/mtrates/3/mtprices

Valori di ritorno
Array di
id
sigla country o codice area geografica, non compare nei valori di ritorno per i defaults
mtprices
array dei prezzi per l'id indicato

L'array mtprices è composto da elementi con questi attributi:

country
sigla della nazione, compare solo nei valori di ritorno per countries
id_geographical_area
identificativo numerico dell'area geografica, solo nei valori di ritorno per geoareas
id_mt_price
identificativo numerico del prezzo
id_mt_rate
identificativo numerico della tariffa
id_service
identificativo numerico del servizio
position
ordine di presentazione
price
prezzo del servizio

ESEMPIO DI RISPOSTA

Risposta alla GET .../countries

La risposta è divisa in sotto array, uno per ogni country. L'id della country è presente a livello di array ed è ripetuto all'interno dei singoli Prezzi.

Status Code: 200

[{
  "id":"it",
  "mtprices":[{
  "country":"it",
    "id_mt_price":23,
    "id_mt_rate":3,
    "id_service":1,
    "position":null,
    "price":"0.120000"
  }, {
    "country":"it",
    "id_mt_price":24,
    "id_mt_rate":3,
    "id_service":2,
    "position":null,
    "price":"0.210000"
  }]
}, {
  "id":"fr",
  "mtprices":[{
  "country":"fr",
    "id_mt_price":25,
    "id_mt_rate":3,
    "id_service":1,
    "position":null,
    "price":"0.140000"
  }, {
    "country":"fr",
    "id_mt_price":26,
    "id_mt_rate":3,
    "id_service":2,
    "position":null,
    "price":"0.230000"
  }]
}]

Risposta alla GET .../geoareas

La risposta ha una struttura analoga alla precedente, con divisione per id_geographical_area.

Status Code: 200

[{
  "id":3,
  "mtprices":[{
    "id_geographical_area":3,
    "id_mt_price":27,
    "id_mt_rate":3,
    "id_service":1,
    "position":null,
    "price":"0.170000"
   }, {
    "id_geographical_area":3,
    "id_mt_price":28,
    "id_mt_rate":3,
    "id_service":2,
    "position":null,
    "price":"0.270000"
   }]
}, {
  "id":6,
  "mtprices":[{
    "id_geographical_area":6,
    "id_mt_price":29,
    "id_mt_rate":3,
    "id_service":1,
    "position":null,
    "price":"0.220000"
   }, {
    "id_geographical_area":6,
    "id_mt_price":30,
    "id_mt_rate":3,
    "id_service":2,
    "position":null,
    "price":"0.310000"
   }]
}]

Risposta alla GET .../defaults

Si noti come l'array dei prezzi di default non sia diviso in ulteriori array, in quanto non esiste un altro livello gerarchico.

Status Code: 200

[{
"id_mt_price":21,
"id_mt_rate":3,
"id_service":1,
"position":null,
"price":"0.064000"
},
{
"id_mt_price":22,
"id_mt_rate":3,
"id_service":2,
"position":null,
"price":"0.068000"
}]

Risposta alla GET .../mtprices

Viene restituito un oggetto con 3 proprietà: geoareas, countries e defaults. Ognuna di queste proprietà contiene una struttura dati identica alle risposte descritte sopra per geoaree, nazioni e prezzi di default.

Status Code: 200

{
  "geoareas":[{
    "id":3,
    "mtprices":[{
      "id_geographical_area":3,
      "id_mt_price":27,
      "id_mt_rate":3,
      "id_service":1,
      "position":null,
      "price":"0.170000"
     }, {
      "id_geographical_area":3,
      "id_mt_price":28,
      "id_mt_rate":3,
      "id_service":2,
      "position":null,
      "price":"0.270000"
     }]
  }, {
    "id":6,
    "mtprices":[{
      "id_geographical_area":6,
      "id_mt_price":29,
      "id_mt_rate":3,
      "id_service":1,
      "position":null,
      "price":"0.220000"
     }, {
      "id_geographical_area":6,
      "id_mt_price":30,
      "id_mt_rate":3,
      "id_service":2,
      "position":null,
      "price":"0.310000"
     }]
  }],
  "countries":[{
    "id":"it",
    "mtprices":[{
    "country":"it",
      "id_mt_price":23,
      "id_mt_rate":3,
      "id_service":1,
      "position":null,
      "price":"0.120000"
    }, {
      "country":"it",
      "id_mt_price":24,
      "id_mt_rate":3,
      "id_service":2,
      "position":null,
      "price":"0.210000"
    }]
  }, {
    "id":"fr",
    "mtprices":[{
    "country":"fr",
      "id_mt_price":25,
      "id_mt_rate":3,
      "id_service":1,
      "position":null,
      "price":"0.140000"
    }, {
      "country":"fr",
      "id_mt_price":26,
      "id_mt_rate":3,
      "id_service":2,
      "position":null,
      "price":"0.230000"
    }]
  }],
  "defaults":[{
    "id_mt_price":21,
    "id_mt_rate":3,
    "id_service":1,
    "position":null,
    "price":"0.064000"
  }, {
    "id_mt_price":22,
    "id_mt_rate":3,
    "id_service":2,
    "position":null,
    "price":"0.068000"
  }]
}

 

Ricarica (per invio SMS)

Permette di accedere alle Ricariche attribuite alla propria utenza.

 

Elenco Ricariche

Recupera l'elenco delle Ricariche di un cliente.

I valori di ritorno sono identici a quelli che vedrebbe ilDistributore/Rivenditore dell'utente con unaGET.

Sintassi
GET /customers/username-customer/mtrecharges
Argomenti URL
username_customer*
string (40 caratteri)username con il quale ci si è registrati al servizio

ESEMPIO DI RICHIESTA

curl -D - -u mariorossi:password --digest \
http://server/customers/mariorossi/mtrecharges

curl -D - -u user:password --digest \
http://api.smsmessenger.it/resellers/user/customers/mariorossi/mtrecharges

Le due chiamate producono lo stesso risultato

Valori di ritorno
Un array di:
id_mt_recharge
numero identificativo della ricarica
id_mt_rate
numero identificativo della tariffa
money_purchased
credito acquistato
money_available
credito disponibile
status
stato della ricarica
created_at
data e ora creazione della ricarica

ESEMPIO DI RISPOSTA

Status Code: 200

[{
"id_mt_recharge":1,
"id_mt_rate":3,
"money_purchased":"50.00",
"money_available":"23.824700",
"status":"active",
"created_at":"2013-05-07T17:11:00+0200"
},
{
"id_mt_recharge":2,
"id_mt_rate":3,
"money_purchased":"50.00",
"money_available":"50.00",
"status":"active",
"created_at":"2012-05-12T13:23:00+0200"
}]

 

Allerta (per invio SMS)

Permette di gestire le allerte per le ricariche dei propri clienti. Le allerte vengono create insieme al cliente e non si possono cancellare.

Le allerte sono tre e sono contraddistinte da una position e da una money-threeshold. La position ha esclusivamente lo scopo di identificare un'allerta in fase di modifica. Non ha influenza sull'ordine in cui scattano le notifiche, che è regolato solo dai valori di money-threeshold. Questo significa che è indifferente avere money-threeshold pari a 100, 50, 10 nelle position 1, 2 e 3 o in quelle 3, 2, 1.

 

Elenco Allerte

Recupera l'elenco delle allerte di un proprio cliente. Contiene sempre tre MtAlert con position 1, 2 e 3.

Sintassi
GET /customers/username-customer/mtalerts
Argomenti URL
username_customer*
string (40 caratteri)username con il quale ci si è registrati al servizio

ESEMPIO DI RICHIESTA

curl -D - -u user:password --digest \
http://api.smsmessenger.it/customers/mariorossi/mtalerts

Valori di ritorno
Un array di:
position
posizione dell'allerta
username
username del cliente a cui è associata l'allerta
money_threshold
limite entro il quale va mandata l'allerta
email_address_1
prima email a cui mandare l'allerta
email_address_2
seconda email a cui mandare l'allerta
email_address_3
terza email a cui mandare l'allerta
sms_phone_1
primo numero di telefono a cui mandare l'allerta
sms_phone_2
secondo numero di telefono a cui mandare l'allerta

ESEMPIO DI RISPOSTA

Status Code: 200

[{
"position":1,
"username":"mariorossi",
"money_threshold":"100.000000",
"email_address_1":"allarme1@example.com",
"email_address_2":null,
"email_address_3":null,
"sms_phone_1":"395556677888",
"sms_phone_2":null
},
{
"position":2,
"money_threshold":"50.000000",
"username":"mariorossi",
"email_address_1":"allarme1@example.com",
"email_address_2":"allarme2@example.com",
"email_address_3":null,
"sms_phone_1":"395556677888",
"sms_phone_2":null
},
{
"position":3,
"username":"mariorossi",
"money_threshold":"20.000000",
"email_address_1":"allarme1@example.com",
"email_address_2":"allarme2@example.com",
"email_address_3":null,
"sms_phone_1":"395556677888",
"sms_phone_2":null
}]

 

Visualizzazione Allerta

Recupera il dettaglio di una allerta di un proprio cliente.

Sintassi
GET /customers/username-customer/mtalerts/position
Argomenti URL
username_customer*
string (40 caratteri)username con il quale ci si è registrati al servizio
position*
integerposizione dell'allerta di cui si vogliono informazioni

ESEMPIO DI RICHIESTA

curl -D - -u mariorossi:password --digest \
http://server/customers/mariorossi/mtalerts/1

Valori di ritorno
position
posizione dell'allerta
username
username del cliente a cui è associata l'allerta
money_threshold
limite entro il quale va mandata l'allerta
email_address_1
prima email a cui mandare l'allerta
email_address_2
seconda email a cui mandare l'allerta
email_address_3
terza email a cui mandare l'allerta
sms_phone_1
primo numero di telefono a cui mandare l'allerta
sms_phone_2
secondo numero di telefono a cui mandare l'allerta

ESEMPIO DI RISPOSTA

Status Code: 200

{
"position":1,
"username":"mariorossi",
"money_threshold":"100.000000",
"email_address_1":"allarme1@example.com",
"email_address_2":null,
"email_address_3":null,
"sms_phone_1":"395556677888",
"sms_phone_2":null
}

 

Modifica Allerta

Modifica una propria allerta.

Sintassi
PUT /customers/username-customer/mtalerts/position
BODY [parametri]
Argomenti URL
username_customer*
string (40 caratteri)username con il quale ci si è registrati al servizio
position*
integerposizione dell'allerta di cui si vogliono informazioni
Parametri BODY
money_threshold
decimal(11, 6)limite entro il quale va mandata l'allerta
email_address_1
string (60 caratteri)prima email a cui mandare l'allerta
email_address_2
string (60 caratteri)seconda email a cui mandare l'allerta
email_address_3
string (60 caratteri)terza email a cui mandare l'allerta
sms_phone_1
string (20 caratteri, solo cifre)primo numero di telefono a cui mandare l'allerta
sms_phone_2
string (20 caratteri, solo cifre, niente +)secondo numero di telefono a cui mandare l'allerta


ESEMPIO DI RICHIESTA

curl -D - -u mariorossi:password --digest \
-X PUT \
http://server/customers/mariorossi/mtalerts/3 \
-d "money_threshold=10.00" \
-d "email_address_1=test%40example.com" \
-d "email_address_2=ceo%40example.com" \
-d "email_address_3=info%40example.com" \
-d "sms_phone_1=39333728374" \
-d "sms_phone_2=338291283"

Valori di ritorno
position
posizione dell'allerta
username
username del cliente a cui è associata l'allerta
money_threshold
limite entro il quale va mandata l'allerta
email_address_1
prima email a cui mandare l'allerta
email_address_2
seconda email a cui mandare l'allerta
email_address_3
terza email a cui mandare l'allerta
sms_phone_1
primo numero di telefono a cui mandare l'allerta
sms_phone_2
secondo numero di telefono a cui mandare l'allerta

ESEMPIO DI RISPOSTA

Status Code: 200

{
"position":1,
"username":"mariorossi",
"money_threshold":"10.00",
"email_address_1":"test@example.com",
"email_address_2":"ceo@example.com",
"email_address_3":"info@example.com",
"sms_phone_1":"39333728374",
"sms_phone_2":"338291283"
}

 

Messaggio (per invio SMS)

Permette di inviare gli SMS.

 

Creazione Messaggio

Si possono inviare SMS dei tre tipi elencati nei Servizi

  • F -> fixed
  • D -> dynamic no report
  • R -> dynamic with report

Per poter indicare un sender-string o un sender-number l'utente deve aver effettuato la procedura di verifica di almeno un numero di telefono.

Sintassi
POST /mtmessages
BODY [parametri]
Parametri BODY
sms_type*
stringtipo di SMS da inviare, identificato da una lettera maiuscola.
recipients*
array(string, string, ...)Contiene i numeri di telefono dei destinatari
I numeri di telefono devono essere in formato internazionale senza i prefissi "+" o "00".
text*
stringTesto del messaggio
La lunghezza massima dipende dal tipo di SMS.
f -> 1560 caratteri spezzati su 10 messaggi consecutivi (1 di 10, 2 di 10, ...). Il primo messaggio della serie è composto da 160 caratteri, il secondo da 152, i successivi da 156.
d e r -> 1530 caratteri o 10 SMS concatenati in un unico messaggio. Per le modalità di conteggio si veda
sender_number
solo per D e R, alternativo a sender_string, integerPermette di specificare un qualsiasi numero di telefono come mittente.
Il numero è soggetto alle spcifiche agcom.
Sono permessi solo numeri di mittente verificati.
sender_string
solo per D e R, alternativo a sender_number, string (11 caratteri)Permette di specificare una stringa alfanumerica da utilizzare come mittente.
LA stringa è soggetta alle spcifiche agcom.
Per poter essere usata l'utente deve aver verificato almeno un numero.
delivery_start
date (ISO 8601)Il formato prevede la separazione di data ed ora con il carattere T e l'indicazione del fuso orario come differenza in ore e minuti rispetto a UTC. Ad esempio 2013-05-20t0730000200.
Tramite questa API non è prevista la ripetizione degli invii, che va impostata esplicitamente con la chiamata di questa API per ogni messaggio che si vuole spedire.
encoding_scheme
solo per D e R, stringConsente di usare usare i caratteri non appartenenti all'alfabeto latino (es. Arabo, Cinese, Coreano, Cirillico, Giapponese e simili)
Valori accettati:
  • normal-7-bit-default
  • ucs2
L'uso di "ucs2" e di "normal" fa riferimento allo standard gsm-0338 e non va confuso con UTF-8 e UTF-16. Ad esempio la lettera "à" è è rappresentata con 7 bit in GSM mentre è ne ha 8 in UTF-8.
La conversione dall'encoding del parametro text (sempre UTF-8) a quella indicata per l'invio avviene all'interno del metodo di invio SMS.
Per i messaggi di tipo F l'encoding è "normal".
validity_period
solo per D e R, integerÈ possibile specificare per quanti minuti (o ore) l'operatore deve riprovare ad inviare l'SMS in caso di destinazione non raggiungibile. Si esprime in minuti ed è un numero intero (valore minimo 5 minuti). Il default è 2 giorni = 2880 minuti (60*48).
user_reference
solo per R, integerStringa di riferimento di al più 20 caratteri, personalizzabile che verrà restituita insieme al rapporto di consegna.
Caratteri supportati: [a-zA-Z0-9-_+:;]
ESEMPIO RICHIESTA
curl -D - -u mariorossi:password --digest \
-X POST http://server/mtmessages \
-d sms_type=R \
-d "recipients[]=393211234567&recipients[]=393212345678" \
-d "text=Testo%20del%20messaggio" \
-d "sender_string=Mario%20Rossi" \
-d "delivery_start=2013-05-20T07:30:00%2B0200" \
-d encoding_scheme=normal \
-d validity_period=2800 \
-d "user_reference=Esempio_uso_API"
 

In delivery_date il carattere + del fuso orario è stato codificato come %2B.

Si noti l'uso dell'underscore al posto dello spazio in user_reference.

Nota: Modalità di conteggio SMS lunghi tradizionali

Il costo del messaggio sarà conteggiato ogni 153 caratteri, ad eccezione del primo SMS che ne avrà a disposizione 160, fino ad un massimo di 1530 o 10 SMS concatenati.

Caratteri 	Numero di SMS addebitati
0-160 	        1
161-306 	2
307-459 	3
460-612 	4
613-765 	5
766-918		6
919-1071 	7
1072-1224 	8
1225-1377 	9
1378-1530 	10

Alcuni caratteri contano doppio:

[ 	        Parentesi quadra aperta
\ 	        Backslash
] 	        Parentesi quadra chiusa
^ 	        Potenza
{ 	        Parentesi graffa aperta
| 	        Barra verticale
} 	        Parentesi graffa chiusa
~ 	        Tilde
€ 	        Simbolo dell'euro

Per maggiori dettagli consulta http://en.wikipedia.org/wiki/GSM_03.38

sms-ucs2

Il costo del messaggio sarà conteggiato ogni 67 caratteri, ad eccezione del primo SMS che ne avrà a disposizione 70, fino ad un massimo di 670 caratteri o 10 SMS concatenati.

Caratteri  	Numero di SMS addebitati
0-70 	        1
71-134 	        2
135-201 	3
202-268 	4
269-335 	5
336-402 	6
403-469 	7
470-536 	8
537-603 	9
604-670 	10
Valori di ritorno
id_dispatch
id dell'operazione di invio
status
success o il messaggio che indica le ragioni per cui non è stato possibile spedire l'SMS

ESEMPIO DI RISPOSTA

Status Code: 200

{
"id_dispatch":999999999
}

 

Destinazione Notifiche

Questa risorsa gestisce la destinazione a cui verranno recapitate le notifiche dei messaggi SMS inviati, per quei messaggi che prevedono la notifica.

Qualora la destinazione non fosse raggiungibile, il server proverà a riconsegnare il rapporto ogni 30 minuti per un massimo di 6 tentativi (3 ore massimo dall'invio), successivamente ai quali l'inoltro verrà scartato.

Dopo aver modificato l'url di inoltro è necessario attendere 20 secondi prima che l'impostazione sia resa effettiva.

La risorsa viene creata vuota insieme al Cliente. È possibile visualizzarla e modificarla per cambiare la destinazione. Non è possibile cancellarla.

I parametri inviati all'URL di destinazione sono

  • dispatch_idNumero identificativo della spedizione
  • message_idNumero identificativo del singolo SMS
  • recipientNumero di telefono a cui è stato inviato l'SMS
  • statusCodice del rapporto di consegna (vedi sotto per il dettaglio)
  • error_codeDettaglio del rapporto di consegna (vedi sotto)
  • user_referenceStringa di riferimento, viene restituita se specificata durante l'invio di SMS Classic con rapporto di consegna
  • server_date_timeData di ricezione dai nostri sistemi del rapporto di consegna in formato rfc-2822.
  • operator_date_timeData di ricezione del rapporto di consegna fornita del provider in formato rfc-2822.

Tutti i parametri sono inviati come stringhe di testo.

Il parametro status può assumere i seguenti valori

  • deliveredMessaggio consegnato
  • expiredMessaggio scaduto (telefono spento/non raggiungibile)
  • deletedErrore rete operatore
  • undeliverableMessaggio non spedito (Vedi sotto variabile error_code)
  • unknownErrore generico
  • rejectdMessaggio rifiutato dall'operatore

Il parametro error_code può assumere i seguenti valori

  • 101Malfunzionamento generico operatore
  • 201Malfunzionamento rete operatore
  • 202Messaggio rifiutato dall'operatore
  • 203Destinatario non raggiungibile (in roaming)
  • 301Destinatario non valido (inesistente/in portabilità/non abilitato)
  • 302Numero errato
  • 303Servizio SMS non abilitato
  • 304Testo riconosciuto come spam
  • 401Messaggio scaduto (telefono spento/non raggiungibile)
  • 501Telefono non supporta l'SMS
  • 502Telefono con memoria piena
  • 901Mappatura errata del malfunzionamento
  • 902Servizio temporaneamente non disponibile
  • 903Nessun operatore disponibile
  • 904Messaggio privo di testo
  • 905Destinatario non valido
  • 906Destinatari duplicati
  • 907Compilazione messaggio non corretta
  • 909User_reference non corretta
  • 910Testo troppo lungo
 

Visualizzazione Destinazione Notifiche

Mostra l'attuale destinazione delle notifiche.

Sintassi
GET /customers/username-customer/forwardnotification
Argomenti URL
username_customer*
string (40 caratteri)username dell'utente

ESEMPIO DI RICHIESTA

curl -D - -u mariorossi:password --digest \
http://server/customers/mariorossi/forwardnotification

Valori di ritorno
method
il metodo di notifica
version
la versione del sistema di notifica, normalmente pari a 2
url
l'URL a cui mandare le modifiche

ESEMPIO DI RISPOSTA

Status Code: 200

{
  "method":"get",
  "url":"http://un.server/e/una/url",
  "version":2
}

 

Aggiornamento Notifiche

Modifica la destinazione delle notifiche.

Sintassi
PUT /customers/username-customer/forwardnotification
BODY [parametri]
Argomenti URL
username_customer*
string (40 caratteri)username dell'utente
Parametri BODY
method
stringil metodo di notifica
Parametri da utilizzare
  • no
  • get
  • post
  • rest
  • soap
url
l'URL a cui mandare le modifiche

ESEMPIO DI RICHIESTA

curl -D - -u mariorossi:password --digest \
-X PUT
http://server/customers/mariorossi/forwardnotification \
-d method=get \
-d url=http%3A%2F%2Fun.server%2Fe%2Funa%2Furl

Valori di ritorno
method
il metodo di notifica
version
la versione del sistema di notifica, normalmente pari a 2
url
l'URL a cui mandare le modifiche

ESEMPIO DI RISPOSTA

Status Code: 200

{
"method":"get",
"version":2,
"url":"http://un.server/e/una/url"
}

 

Verifica numeri di invio

Solo i clienti con numeri verificati possono mandare messaggi. La verifica permette di associare un numero ad un cliente registrato. La procedura si compone di due chiamate.

La prima è una POST che genera un token e lo spedisce con un SMS al numero indicato come parametro. Il cliente leggerà il token nel messaggio e lo userà nella seconda chiamata, che è una POST con cui invia al server il token e il suo numero di telefono. Se la combinazione coincide con quella generata in precedenza il numero è verificato ed autorizzato a spedire messaggi.

In aggiunta a queste due chiamate l'API ne espone altre due che servono ad elencare i numeri e a cancellare un numero già verificato.

Nota. Poiché il token di verifica è un oggetto concettualmente separato dai numeri verificati, lo si è considerato come una risorsa a sé e infatti in Richiesta di verifica noterete cheha una URL diversa dalle altre.Tuttavia la sua API è costituita dalla sola chiamata di creazione e il token è usato solo per verificare i numeri di invio. Pertanto, allo scopo di semplificare l'orientamento nella documentazione, si è deciso di includere la chiamata in questa sezione e non crearne una a parte.

 

Richiesta di verifica

Genera un token e lo spedisce con un SMS al numero indicato come parametro.

Sintassi
POST /customers/username-customer/numberverificationtoken
BODY [parametri]

Forma alternativa deprecata:
POST /customers/username-customer/verify/request
BODY [parametri]
Argomenti URL
username_customer*
string (40 caratteri)username del cliente da verificare
Parametri BODY
number*
int (20 cifre)il numero da verificare, in formato internazionale con il prefisso senza + né 00

ESEMPIO DI RICHIESTA

curl -D - -u mariorossi:password \
-X POST \
http://server/customers/mariorossi/numberverificationtoken \
-d number=3934567890

Valori di ritorno
dispatch_id
il codice che identifica l'sms inviato.

ESEMPIO DI RISPOSTA

Status Code: 200

{"dispatch_id":"999308731"}

 

Conferma della verifica

Si usa per inviare al server il token e il numero di telefono del cliente che ha ricevuto il messaggio di verifica inviato in seguito alla chiamata precedente.

Sintassi
POST /customers/username-customer/verifiednumbers/confirm
BODY [parametri]

Forma alternativa deprecata:
POST /customers/username-customer/verify/check
BODY [parametri]
Argomenti URL
username_customer*
string (40 caratteri)username del cliente da verificare
Parametri BODY
number*
int (20 cifre)il numero da verificare
token*
stringil token inviato al cliente e ricevuto all'interno dell'SMS di verifica

ESEMPIO DI RICHIESTA

curl -D - -u mariorossi:password \
-X POST \
http://server/customers/mariorossi/verifiednumbers/confirm \
-d number=3934567890 \
-d token=73001922

Valori di ritorno
number
il numero verificato

ESEMPIO DI RISPOSTA

Status Code: 200

[{
  "number": "3934567890"
}]

 

Elenco numeri verificati

Restituisce i numeri che sono stati verificati.

Sintassi
GET /customers/username-customer/verifiednumbers

Forma alternativa deprecata:
POST /customers/username-customer/numbers
BODY [parametri]
Argomenti URL
username_customer*
string (40 caratteri)username con il quale ci si è registrati al servizio

ESEMPIO DI RICHIESTA

curl -D - -u mariorossi:password --digest \
http://server/customers/mariorossi/verifiednumbers

Valori di ritorno
Un array di
id_number
identificativo del numero verificato
number
numero verificato
validated_at
data validazione

ESEMPIO DI RISPOSTA

Status Code: 200

[{
  "id_number": "10",
  "number": "3934567890",
  "validated_at": "2013-04-30T15:12:26+0200",
}]

 

Cancellazione numeri verificati

Elimina uno dei numeri verificati.

Sintassi
DELETE /customers/username-customer/verifiednumbers/number

Forma alternativa deprecata:
DELETE /customers/username-customer/numbers/number
Argomenti URL
number*
stringil numero da cancellare

ESEMPIO DI RICHIESTA

curl -D - -u mariorossi:password --digest \
-X DELETE \
http://server/customers/mariorossi/verifiednumbers/3934567890

Valori di ritorno
number
il numero eliminato

ESEMPIO DI RISPOSTA

Status Code: 200

{
  "number": "3934567890"
}

 

Tariffa (per ricezione SMS)

Permette di accedere ai dati delle Tariffe del proprio Distributore/Rivenditore.

 

Elenco Tariffe

Recupera l'elenco delle Tariffe.

L'url è identica per tutti gli utenti dello stesso server in quanto i dati restituiti sono gli stessi.

Sintassi
GET /morates

ESEMPIO DI RICHIESTA

curl -D - -u mariorossi:password --digest \
http://server/morates

Valori di ritorno
Un array di:
created_at
data e ora di creazione della tariffa
id_mo_rate
identificativo numerico della tariffa
name
nome della tariffa
note
note sulla tariffa
resellable
specifica se è possibile rivendere la tariffa (boolean)

ESEMPIO DI RISPOSTA

Status Code: 200

[{
"id_mo_rate":10,
"name":"Ricezione estate 2013",
"note":"vendere da giugno",
"resellable":0,
"created_at":"2013-05-16T15:22:48+0200"
}]

Sono le Tariffe restituite da GET /resellers/user/morates

 

Visualizzazione Tariffa

Mostra il dettaglio di una Tariffa.

L'url è identica per tutti gli utenti dello stesso server in quanto i dati restituiti sono gli stessi.

Sintassi
GET /morates/id-mo-rate
Argomenti URL
id_mo_rate*
intidentificativo numerico della Tariffa

ESEMPIO DI RICHIESTA

curl -D - -u mariorossi:password --digest \
http://server/morates/10

Valori di ritorno
created_at
data e ora di creazione della tariffa
id_mo_rate
identificativo numerico della tariffa
name
nome della tariffa
note
note sulla tariffa
resellable
specifica se è possibile rivendere la tariffa (boolean)

ESEMPIO DI RISPOSTA

Status Code: 200

{
"id_mo_rate":10,
"name":"Ricezione estate 2013",
"note":"vendere da giugno",
"resellable":0,
"created_at":"2013-05-16T15:22:48+0200"
}

 

Prezzo (per ricezione SMS)

Permette di visualizzare i prezzi associati alle Tariffe del proprio Distributore/Rivenditore.
 

Elenco Prezzi

Recupera l'elenco dei Prezzi associati ad una Tariffa.

Sintassi
GET /morates/id-mo-rate/moprices
Argomenti URL
id_mo_rate*
integeridentificativo numerico della tariffa di cui si vogliono restituire i prezzi

ESEMPIO DI RICHIESTA

curl -D - -u mariorossi:password --digest \
http://server/api/morates/10/moprices

Valori di ritorno
id_mo_price
identificativo numerico del prezzo
id_mo_rate
identificativo numerico della tariffa
price
il costo di un mese
type
dedicated se il prezzo è per un numero dedicato o shared per un numero condiviso

ESEMPIO DI RISPOSTA

Status Code: 200

[{
"id_mo_price":1,
"id_mo_rate":10,
"price":"30.00",
"type":"dedicated"
},
{
"id_mo_price":2,
"id_mo_rate":10,
"price":"20.00",
"type":"shared"
}]

 

Ricarica flat (per ricezione SMS)

Permette di accedere alle Ricariche attribuite alla propria utenza.

 

Elenco Ricariche

Recupera l'elenco delle Ricariche di un cliente.

I valori di ritorno sono identici a quelli che vedrebbe il Distributore/Rivenditore dell'utente con unaGET .

Sintassi
GET /customers/username-customer/morechargesflat
Argomenti URL
username_customer*
string (40 caratteri)username con il quale ci si è registrati al servizio

ESEMPIO DI RICHIESTA

curl -D - -u mariorossi:password --digest --digest \
http://server/customers/mariorossi/morechargesflat

curl -D - -u user:password --digest \
http://api.smsmessenger.it/resellers/user/customers/mariorossi/morechargesflat

Le due chiamate producono lo stesso risultato

Valori di ritorno
Un array di:
id_mo_recharge
numero identificativo della ricarica
id_mo_rate
numero identificativo della tariffa
money_purchased
credito acquistato
money_available
credito disponibile
status
stato della ricarica
created_at
data e ora creazione della ricarica

ESEMPIO DI RISPOSTA

Status Code: 200

[{
"created_at":"2013-05-17T11:50:01+0200",
"id_mo_recharge_flat":1,
"id_mo_rate":3,
"id_mo_sold_keyword":2,
"months_purchased":3,
"status":"active",
"username":"mariorossi",
},
{
"created_at":"2013-05-17T11:52:15+0200",
"id_mo_recharge_flat":1,
"id_mo_rate":3,
"id_mo_sold_keyword":3,
"months_purchased":2,
"status":"active",
"username":"mariorossi"
}]

 

Keyword vendute (per ricezione SMS)

Permette di visualizzare i dati delle Keyword a disposizione della propria utenza.

 

Elenco keyword

Recupera l'elenco delle Keyword comprate dal proprio Distributori / Rivenditori. Equivale alla GET effettuata dal Distributori / Rivenditori.

Sintassi
GET /customers/username-customer/mosoldkeywords
Argomenti URL
username_customer*
string (40 caratteri)username del Rivenditore / Cliente Finale

ESEMPIO DI RICHIESTA

curl -D - -u mariorossi:password --digest \
http://server/customers/mariorossi/mosoldkeywords

Valori di ritorno
Un array di:
alert_enabled
indica la presenza di un'allerta sulla scadenza della keyword
created_at
data e ora di creazione della keyword
expires_at
data e ora di scadenza della keyword
id_parent_keyword
identificativo numerico della keyword padre, null se questa è la prima della gerarchia
id_mo_sold_keyword
identificativo numerico della keyword
number
numero su cui vengono ricevuti i messaggi
status
stato della keyword ('test', 'active', 'grace', 'expired', 'revoked', 'blocked')
subkeyword
la prima parola della Keyword o null per una Keyword che rappresenta un numero dedicato
username
username del cliente

ESEMPIO DI RISPOSTA

Status Code: 200

[{
"alert_enabled":0,
"created_at":"2013-05-20T14:37:34+0200",
"expires_at":"2013-08-20T23:59:59+0200",
"id_parent_keyword":1,
"id_mo_sold_keyword":2,
"number":"1234",
"status":"active",
"subkeyword":"SMS",
"username":"mariorossi"
}]

 

Visualizzazione Keyword

Mostra il dettaglio di una Keyword.

Sintassi
GET /customers/username-customer/mosoldkeywords/id-mo-sold-keyword
Argomenti URL
username_customer*
string (40 caratteri)username del Rivenditore / Cliente Finale
id_mo_sold_keyword*
intidentificativo numerico della keyword

ESEMPIO DI RICHIESTA

curl -D - -u mariorossi:password --digest \
http://server/customers/mariorossi/mosoldkeywords/2

Valori di ritorno
alert_enabled
indica la presenza di un'allerta sulla scadenza della keyword
created_at
data e ora di creazione della keyword
expires_at
data e ora di scadenza della keyword
id_parent_keyword
identificativo numerico della keyword padre, null se questa è la prima della gerarchia
id_mo_sold_keyword
identificativo numerico della keyword
number
numero su cui vengono ricevuti i messaggi
status
stato della keyword ('test', 'active', 'grace', 'expired', 'revoked', 'blocked')
subkeyword
la prima parola della Keyword o null per una Keyword che rappresenta un numero dedicato
username
username del cliente

ESEMPIO DI RISPOSTA

Status Code: 200

{
"alert_enabled":0,
"created_at":"2013-05-20T14:37:34+0200",
"expires_at":"2013-08-20T23:59:59+0200",
"id_parent_keyword":1,
"id_mo_sold_keyword":2,
"number":"1234",
"status":"active",
"subkeyword":"SMS",
"username":"mariorossi"
}

 

Creazione Keyword vendute

Questa API permette di creare una Keyword per sé stessi a partire da una già in proprio possesso.

Si devono indicare tre argomenti.

Il primo è l'id-parent-keyword della keyword padre. Deve essere una propria Keyword che abbia subkeyword uguale a NULL, ossia essere un numero dedicato.

Il secondo è la subkeyword, che è la prima parola del messaggio e viene usata per identificare a chi consegnarlo.

Il terzo è la data di scadenza. Si indica solo anno, mese e giorno perché la keyword scade sempre a fine giornata. Le chiamate di visualizzazione ed elenco mostreranno l'intera ora, con ora minuti e secondi pari a 23:59:59.

Sintassi
POST /customers/username-customer/mosoldkeywords
Argomenti URL
username_customer*
string (40 caratteri)il proprio username, per creare una keyword per sé stessi
Parametri BODY
id_parent_keyword*
intid numerico della keyword padre
subkeyword*
string (50 caratteri)prima parola del messaggio

ESEMPIO DI RICHIESTA

curl -D - -u user:password --digest \
-X POST \
http://api.smsmessenger.it/customers/mariorossi/mosoldkeywords
-d "id_parent_keyword=4"
-d "subkeyword=HELLO"

Si assume che ci sia una mosoldkeyword con id_mo_sold_keyword == 4 e subkeyword == NULL

Valori di ritorno
created_at
data e ora di creazione della keyword
id_parent_keyword
identificativo numerico della keyword padre, null se questa è la prima della gerarchia
id_mo_soldkeyword
identificativo numerico della keyword
number
numero su cui vengono ricevuti i messaggi
subkeyword
la prima parola della Keyword o null per una Keyword che rappresenta un numero dedicato
username
username del cliente

ESEMPIO DI RISPOSTA

Status Code: 200

[{
"created_at":"2013-05-21T14:02:17+0200",
"expires_at":"2013-08-21T23:59:59+0200",
"id_parent_keyword":4,
"id_mo_soldkeyword":5,
"number":"1234",
"status":"active",
"subkeyword":"HELLO",
"username":"mariorossi"
}]

 

Recapiti (per ricezione SMS)

I Recapiti indicano a che indirizzo inviare i messaggi ricevuti. Si possono creare più Recapiti per una data Keyword. In presenza di più di un Recapito la consegna viene fatta a tutti.

Le consegne vengono effettuate con le seguenti modalità (tra parentesi il codice corrispondente al servizio):

  • email-email
  • http-get-get
  • http-post-post
  • rest-legacy-rest
  • soap-soap

Nel dettaglio

email

Indirizzo di mail a cui inviare il messaggio con i seguenti parametri

  • string-userdatetime: l'orario di arrivo dell'SMS
  • string-sender: numero del mittente dell'SMS in formato internazionale senza + o 00, ad esempio: 393334455666
  • string-text: testo dell'SMS

http-get

Il server chiamerà l'URL specificata nell'attributo info passando i seguenti parametri in GET:
  • string-sender: numero del mittente dell'SMS in formato internazionale senza + o 00, ad esempio: 393334455666
  • string-receiver: il numero su cui è arrivato l'SMS in formato internazionale senza + o 00, ad esempio: 393334455666
  • string-text: testo dell'SMS
  • string-encoding: il set di caratteri usati per il testo (ISO-8859-1)
  • string-date: la data di arrivo dell'SMS
  • string-time: l'orario di arrivo dell'SMS
  • string-timestamp: il timestamp di arrivo dell'SMS; per comodità del programmatore passiamo tre formati differenti di data / ora
  • string-smstype: il tipo di SMS ricevuto

Esempio di body HTTP per ricezione SMS con parametri in GET:

type=GET&sender=393471234567&receiver=393477654321&
text=Ciao+Mario+come+stai&encoding=ISO-8859-1&
date=2013-06-07&time=10%3A32%3A32&timestamp=1305880352&
smsType=standard

http-post

Il server chiamerà l'URL specificato nell'attributo info passando i seguenti parametri in POST:

  • string-sender: numero del mittente dell'SMS in formato internazionale senza + o 00, ad esempio: 393334455666
  • string-receiver: il numero su cui è arrivato l'SMS in formato internazionale senza + o 00, ad esempio: 393334455666
  • string-text: testo dell'SMS
  • string-encoding: il set di caratteri usati per il testo (ISO-8859-1)
  • string-date: la data di arrivo dell'SMS
  • string-time: l'orario di arrivo dell'SMS
  • string-timestamp: il timestamp di arrivo dell'SMS; per comodità del programmatore passiamo tre formati differenti di data / ora
  • string-smstype: il tipo di SMS ricevuto

Esempio di body HTTP per ricezione SMS con parametri in POST:

type=POST&sender=393471234567&receiver=393477654321&
text=Ciao+Mario+come+stai&encoding=ISO-8859-1&
date=2013-06-07&time=10%3A32%3A32&timestamp=1305880352&
smsType=standard

rest-legacy

Questa è la modalità REST legacy delle API. La si mantiene per compatibilità ma non è REST nel senso dell'API White Label. È equivalente all'HTTP GET con la differenza che all'URL specificata nell'attributo info aggiunge "restGet" i seguenti parametri:
  • string-sender: numero del mittente dell'SMS in formato internazionale senza + o 00, ad esempio: 393334455666
  • string-receiver: il numero su cui è arrivato l'SMS in formato internazionale senza + o 00, ad esempio: 393334455666
  • string-text: testo dell'SMS
  • string-encoding: il set di caratteri usati per il testo (ISO-8859-1)
  • string-date: la data di arrivo dell'SMS
  • string-time: l'orario di arrivo dell'SMS
  • string-timestamp: il timestamp di arrivo dell'SMS; per comodità del programmatore passiamo tre formati differenti di data / ora
  • string-smstype: il tipo di SMS ricevuto

Esempio di body HTTP per ricezione SMS con metodo REST:

method=smsin&sender=393471234567&receiver=393477654321&
text=Ciao+Mario+come+stai&encoding=ISO-8859-1&
date=2013-06-07&time=10%3A32%3A32&timestamp=1305880352&
smsType=standard

soap

Il server chiamerà l'URL specificato nell'attributo info invocando il metodo SOAP "smsin" con i seguenti parametri (nell'ordine in cui sono qui indicati):

  • string-sender: numero del mittente dell'SMS in formato internazionale senza + o 00, ad esempio: 393334455666
  • string-receiver: il numero su cui è arrivato l'SMS in formato internazionale senza + o 00, ad esempio: 393334455666
  • string-text: testo dell'SMS
  • string-date: la data di arrivo dell'SMS
  • string-time: l'orario di arrivo dell'SMS
  • string-timestamp: il timestamp di arrivo dell'SMS; per comodità del programmatore passiamo tre formati differenti di data / ora
  • string-smstype: il tipo di SMS ricevuto

Esempio di body HTTP per ricezione SMS con metodo SOAP:


<?xml version="1.0" encoding="UTF-8"?>
<env:Envelope xmlns:env="http://www.w3.org/2003/05/soap-envelope" xmlns:ns1="url richiamata"
  xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xmlns:enc="http://www.w3.org/2003/05/soap-encoding">
  <env:Body>
    <ns1:smsin env:encodingStyle="http://www.w3.org/2003/05/soap-encoding">
      <sender xsi:type="xsd:string">393471234567</sender>
      <receiver xsi:type="xsd:int">393477654321</receiver>
      <text xsi:type="xsd:string">Ciao Mario come stai</text>
      <date xsi:type="xsd:string">2013-06-07</date>
      <time xsi:type="xsd:string">10:32:32</time>
      <timestamp xsi:type="xsd:string">1305880352</timestamp>
      <smsType xsi:type="xsd:string">standard</smsType>
    </ns1:smsin>
  </env:Body>
</env:Envelope>
 

Elenco Recapiti

Mostra i Recapiti associati ad una Keyword.

Sintassi
GET /customers/username-customer/mosoldkeywords/id-mo-sold-keyword/forwardinfo
Argomenti URL
username_customer*
string (40 caratteri)username del Rivenditore / Cliente Finale
id_mo_sold_keyword*
intidentificativo numerico della keyword

ESEMPIO DI RICHIESTA

curl -D - -u mariorossi:password --digest \
http://server/customers/mariorossi/mosoldkeywords/2/forwardinfo

Valori di ritorno
Array di
enabled
boolean che indica se la consegna è stata attivata
encoding
l'encoding desiderato per la consegna ('ISO-8859-1', 'UTF-8')
id_forward_info
identificativo numerico del Recapito
id_mo_sold_keyword
identificativo numerico della Keyword
info
indirizzo a cui inviare il messaggio (email, url)
type
indica il tipo di consegna ('email', 'get', 'post', 'rest', 'soap', 'sms_dynamic_id', 'sms_fixed_id')

ESEMPIO DI RISPOSTA

Status Code: 200

[{
"enabled":1,
"encoding":"UTF-8",
"id_forward_info":1,
"id_mo_sold_keyword":2,
"info":"mariorossi@example.com",
"type":"email"
}]

 

Visualizzazione Recapito

Mostra il dettaglio di un Recapito.

Sintassi
GET /customers/username-customer/mosoldkeywords/id-mo-sold-keyword/forwardinfo/id-forward-info
Argomenti URL
username_customer*
string (40 caratteri)username del Rivenditore / Cliente Finale
id_mo_sold_keyword*
intidentificativo numerico della keyword
id_forward_info*
intidentificativo numerico del recapito

ESEMPIO DI RICHIESTA

curl -D - -u mariorossi:password --digest \
http://server/customers/mariorossi/mosoldkeywords/2/forwardinfo/1

Valori di ritorno
enabled
boolean che indica se la consegna è stata attivata
encoding
l'encoding desiderato per la consegna ('ISO-8859-1', 'UTF-8')
id_forward_info
identificativo numerico del Recapito
id_mo_sold_keyword
identificativo numerico della Keyword
info
indirizzo a cui inviare il messaggio (email, url)
type
indica il tipo di consegna ('email', 'get', 'post', 'rest', 'soap', 'sms_dynamic_id', 'sms_fixed_id')

ESEMPIO DI RISPOSTA

Status Code: 200

{
"enabled":1,
"encoding":"UTF-8",
"id_forward_info":1,
"id_mo_sold_keyword":2,
"info":"mariorossi@example.com",
"type":"email"
}

 

Creazione Recapito

Crea un Recapito per una Keyword.

Sintassi
POST /customers/username-customer/mosoldkeywords/id-mo-sold-keyword/forwardinfo
BODY [parametri]
Argomenti URL
username_customer*
string (40 caratteri)username del Rivenditore / Cliente Finale
id_mo_sold_keyword*
intidentificativo numerico della keyword
Parametri BODY
enabled
booleanboolean che indica se la consegna è stata attivata (default a true)
encoding
stringl'encoding desiderato per la consegna
Parametri da utilizzare
  • ISO-8859-1
  • UTF-8
info
string (255 caratteri)indirizzo a cui inviare il messaggio (email, url); se non indicato il Recapito non sarà attivato
type
stringindica il tipo di consegna, il default è l'email
Parametri da utilizzare
  • email
  • get
  • post
  • rest
  • soap
  • sms_dynamic_id
  • sms_fixed_id

ESEMPIO DI RICHIESTA

curl -D - -u mariorossi:password --digest \
-X POST
http://server/customers/mariorossi/mosoldkeywords/2/forwardinfo
-d enabled=1 \
-d encoding=UTF-8 \
-d info=mariorossi%40example.com \
-d type=email

Valori di ritorno
enabled
boolean che indica se la consegna è stata attivata
encoding
l'encoding desiderato per la consegna ('ISO-8859-1','UTF-8')
id_forward_info
identificativo numerico del Recapito
info
indirizzo a cui inviare il messaggio (email, url)
type
indica il tipo di consegna ('email', 'get', 'post', 'rest', 'soap', 'sms_dynamic_id', 'sms_fixed_id')

ESEMPIO DI RISPOSTA

Status Code: 200

{
"enabled":1,
"encoding":"UTF-8",
"id_forward_info":1,
"id_mo_sold_keyword":2,
"info":"mariorossi@example.com",
"type":"email"
}

 

Modifica Recapito

Modifica un Recapito per una Keyword.

Sintassi
PUT /customers/username-customer/mosoldkeywords/id-mo-sold-keyword/forwardinfo/id-forward-info
BODY [parametri]
Argomenti URL
username_customer*
string (40 caratteri)username del Rivenditore / Cliente Finale
id_mo_sold_keyword*
intidentificativo numerico della keyword
id_forward_info*
intidentificativo numerico del recapito
Parametri BODY
enabled
booleanboolean che indica se la consegna è stata attivata (default a true)
encoding
stringl'encoding desiderato per la consegna
Parametri da utilizzare
  • ISO-8859-1
  • UTF-8
info
string (255 caratteri)indirizzo a cui inviare il messaggio (email, url). Se non indicato il Recapito non sarà attivato. È obbligatorio passare anche il valore di type.
type
obbligatorio quando è presente info, stringindica il tipo di consegna
Parametri da utilizzare
  • email
  • get
  • post
  • rest
  • soap
  • sms_dynamic_id
  • sms_fixed_id

ESEMPIO DI RICHIESTA

curl -D - -u mariorossi:password --digest \
-X PUT
http://server/customers/mariorossi/mosoldkeywords/2/forwardinfo/1
-d encoding=ISO-8859-1 \
-d info=sms-alerts%40example.com \
-d type=email

Valori di ritorno
enabled
boolean che indica se la consegna è stata attivata
encoding
l'encoding desiderato per la consegna ('ISO-8859-1','UTF-8')
id_forward_info
identificativo numerico del Recapito
id_mo_sold_keyword
identificativo numerico della Keyword
info
indirizzo a cui inviare il messaggio (email, url)
type
indica il tipo di consegna ('email', 'get', 'post', 'rest', 'soap', 'sms_dynamic_id', 'sms_fixed_id')

ESEMPIO DI RISPOSTA

Status Code: 200

{
"enabled":1,
"encoding":"ISO-8859-1",
"id_forward_info":1,
"id_mo_sold_keyword":2,
"info":"sms-alerts@example.com",
"type":"email"
}

 

Aree geografiche e country

I codici delle nazioni sono definiti dallo standard ISO 3166. Il server utilizza la versione a due caratteri.

Codici per id_geographical_area

Il server suddivide le nazioni nelle seguenti aree geografiche, di cui si dà il codice numerico da usare nelle chiamate all'API e l'elenco delle nazioni che le compongono.

Africa

I codici delle nazioni nell'area geografica Africa sono

  • AC Ascension Island
  • AO Angola
  • BF Burkina Faso
  • BI Burundi
  • BJ Benin
  • BW Botswana
  • CD Congo [DRC]
  • CF Central African Republic
  • CG Congo [Republic]
  • CI Ivory Coast
  • CM Cameroon
  • CV Cape Verde
  • DJ Djibouti
  • DZ Algeria
  • EG Egypt
  • ER Eritrea
  • ET Ethiopia
  • GA Gabon
  • GH Ghana
  • GM Gambia
  • GN Guinea
  • GQ Equatorial Guinea
  • GW Guinea-Bissau
  • IO British Indian Ocean Territory
  • KE Kenya
  • KM Comoros
  • LR Liberia
  • LS Lesotho
  • LY Libya
  • MA Morocco
  • MG Madagascar
  • ML Mali
  • MR Mauritania
  • MU Mauritius
  • MW Malawi
  • MZ Mozambique
  • NA Namibia
  • NE Niger
  • NG Nigeria
  • RW Rwanda
  • SC Seychelles
  • SD Sudan
  • SL Sierra Leone
  • SN Senegal
  • SO Somalia
  • SS South Sudan
  • ST São Tomé and Príncipe
  • SZ Swaziland
  • TD Chad
  • TF French Southern Territories
  • TG Togo
  • TN Tunisia
  • TZ Tanzania
  • UG Uganda
  • ZA South Africa
  • ZM Zambia
  • ZW Zimbabwe

Asia Pacific

I codici delle nazioni nell'area geografica Asia Pacific sono

  • AF Afghanistan
  • AS American Samoa
  • AU Australia
  • BD Bangladesh
  • BN Brunei
  • BT Bhutan
  • CK Cook Islands
  • CN China
  • FJ Fiji
  • FM Micronesia
  • GU Guam
  • HK Hong Kong
  • ID Indonesia
  • IN India
  • IR Iran
  • JP Japan
  • KG Kyrgyzstan
  • KH Cambodia
  • KI Kiribati
  • KP North Korea
  • KR South Korea
  • LA Laos
  • LK Sri Lanka
  • MH Marshall Islands
  • MM Myanmar [Burma]
  • MN Mongolia
  • MO Macau
  • MP Northern Mariana Islands
  • MV Maldives
  • MY Malaysia
  • NC New Caledonia
  • NF Norfolk Island
  • NP Nepal
  • NR Nauru
  • NU Niue
  • NZ New Zealand
  • PF French Polynesia
  • PG Papua New Guinea
  • PH Philippines
  • PK Pakistan
  • PW Palau
  • SB Solomon Islands
  • SG Singapore
  • TH Thailand
  • TJ Tajikistan
  • TK Tokelau
  • TL East Timor
  • TM Turkmenistan
  • TO Tonga
  • TV Tuvalu
  • TW Taiwan
  • UZ Uzbekistan
  • VN Vietnam
  • VU Vanuatu
  • WF Wallis and Futuna
  • WS Samoa

Europe

I codici delle nazioni nell'area geografica Europe sono

  • AD Andorra
  • AL Albania
  • AM Armenia
  • AT Austria
  • AZ Azerbaijan
  • BA Bosnia and Herzegovina
  • BE Belgium
  • BG Bulgaria
  • BY Belarus
  • CH Switzerland
  • CY Cyprus
  • CZ Czech Republic
  • DE Germany
  • DK Denmark
  • EE Estonia
  • ES Spain
  • FI Finland
  • FO Faroe Islands
  • FR France
  • GB U.K.
  • GE Georgia
  • GI Gibraltar
  • GL Greenland
  • GR Greece
  • HR Croatia
  • HU Hungary
  • IE Ireland
  • IS Iceland
  • IT Italy
  • LI Liechtenstein
  • LT Lithuania
  • LU Luxembourg
  • LV Latvia
  • MC Monaco
  • MD Moldova
  • ME Montenegro
  • MK Macedonia [FYROM]
  • MT Malta
  • NL Netherlands
  • NO Norway
  • PL Poland
  • PT Portugal
  • RO Romania
  • RS Serbia
  • RU Russia
  • SE Sweden
  • SI Slovenia
  • SK Slovakia
  • SM San Marino
  • TR Turkey
  • UA Ukraine

Latin America

I codici delle nazioni nell'area geografica Latin America sono

  • AG Antigua and Barbuda
  • AI Anguilla
  • AN Netherlands Antilles
  • AR Argentina
  • AW Aruba
  • BB Barbados
  • BM Bermuda
  • BO Bolivia
  • BR Brazil
  • BS Bahamas
  • BZ Belize
  • CL Chile
  • CO Colombia
  • CR Costa Rica
  • CU Cuba
  • DM Dominica
  • EC Ecuador
  • FK Falkland Islands [Islas Malvinas]
  • GD Grenada
  • GF French Guiana
  • GP Guadeloupe
  • GT Guatemala
  • GY Guyana
  • HN Honduras
  • HT Haiti
  • JM Jamaica
  • KN Saint Kitts and Nevis
  • KY Cayman Islands
  • LC Saint Lucia
  • MQ Martinique
  • MS Montserrat
  • MX Mexico
  • NI Nicaragua
  • PA Panama
  • PE Peru
  • PY Paraguay
  • SR Suriname
  • SV El Salvador
  • TC Turks and Caicos Islands
  • TT Trinidad and Tobago
  • UY Uruguay
  • VC Saint Vincent and the Grenadines
  • VE Venezuela
  • VG British Virgin Islands
  • VI U.S. Virgin Islands

Middle East

I codici delle nazioni nell'area geografica Middle East sono

  • AE United Arab Emirates
  • BH Bahrain
  • IL Israel
  • IQ Iraq
  • JO Jordan
  • KW Kuwait
  • LB Lebanon
  • OM Oman
  • QA Qatar
  • SA Saudi Arabia
  • SY Syria
  • YE Yemen

Northern America

I codici delle nazioni nell'area geografica Northern America sono

  • PM Saint Pierre and Miquelon
  • SH Saint Helena
  • US U.S.

Il Canada è compreso negli Stati Uniti (US) in quanto ha il loro stesso prefisso internazionale.

 

Sigle dei fusi orari

  • ciabj Africa/Abidjan
  • ghacc Africa/Accra
  • etadd Africa/Addis_Ababa
  • dzalg Africa/Algiers
  • erasm Africa/Asmera
  • mlbko Africa/Bamako
  • cfbgf Africa/Bangui
  • gmbjl Africa/Banjul
  • gwoxb Africa/Bissau
  • mwblz Africa/Blantyre
  • cgbzv Africa/Brazzaville
  • bibjm Africa/Bujumbura
  • egcai Africa/Cairo
  • macas Africa/Casablanca
  • esceu Africa/Ceuta
  • gncky Africa/Conakry
  • sndkr Africa/Dakar
  • tzdar Africa/Dar_es_Salaam
  • djjib Africa/Djibouti
  • cmdla Africa/Douala
  • eheai Africa/El_Aaiun
  • slfna Africa/Freetown
  • bwgbe Africa/Gaborone
  • zwhre Africa/Harare
  • zajnb Africa/Johannesburg
  • ugkla Africa/Kampala
  • sdkrt Africa/Khartoum
  • rwkgl Africa/Kigali
  • cdfih Africa/Kinshasa
  • nglos Africa/Lagos
  • galbv Africa/Libreville
  • tglfw Africa/Lome
  • aolad Africa/Luanda
  • cdfbm Africa/Lubumbashi
  • zmlun Africa/Lusaka
  • gqssg Africa/Malabo
  • mzmpm Africa/Maputo
  • lsmsu Africa/Maseru
  • szqmn Africa/Mbabane
  • somgq Africa/Mogadishu
  • lrmlw Africa/Monrovia
  • kenbo Africa/Nairobi
  • tdndj Africa/Ndjamena
  • nenim Africa/Niamey
  • mrnkc Africa/Nouakchott
  • bfoua Africa/Ouagadougou
  • bjptn Africa/Porto-Novo
  • sttms Africa/Sao_Tome
  • lytip Africa/Tripoli
  • tntun Africa/Tunis
  • nawdh Africa/Windhoek
  • usadk America/Adak
  • usanc America/Anchorage
  • aiaxa America/Anguilla
  • aganu America/Antigua
  • braux America/Araguaina
  • arirj America/Argentina/La_Rioja
  • arrgl America/Argentina/Rio_Gallegos
  • arsla America/Argentina/Salta
  • aruaq America/Argentina/San_Juan
  • arluq America/Argentina/San_Luis
  • artuc America/Argentina/Tucuman
  • arush America/Argentina/Ushuaia
  • awaua America/Aruba
  • pyasu America/Asuncion
  • brssa America/Bahia
  • bbbgi America/Barbados
  • brbel America/Belem
  • bzbze America/Belize
  • caybx America/Blanc-Sablon
  • brbvb America/Boa_Vista
  • cobog America/Bogota
  • usboi America/Boise
  • arbue America/Buenos_Aires
  • caycb America/Cambridge_Bay
  • brcgr America/Campo_Grande
  • mxcun America/Cancun
  • veccs America/Caracas
  • arctc America/Catamarca
  • gfcay America/Cayenne
  • kygec America/Cayman
  • uschi America/Chicago
  • mxchi America/Chihuahua
  • cayzs America/Coral_Harbour
  • arcor America/Cordoba
  • crsjo America/Costa_Rica
  • brcgb America/Cuiaba
  • ancur America/Curacao
  • gldkshvn America/Danmarkshavn
  • cayda America/Dawson
  • caydq America/Dawson_Creek
  • usden America/Denver
  • usdet America/Detroit
  • dmdom America/Dominica
  • caedm America/Edmonton
  • brern America/Eirunepe
  • svsal America/El_Salvador
  • brfor America/Fortaleza
  • caglb America/Glace_Bay
  • glgoh America/Godthab
  • cagoo America/Goose_Bay
  • tcgdt America/Grand_Turk
  • gdgnd America/Grenada
  • gpbbr America/Guadeloupe
  • gtgua America/Guatemala
  • ecgye America/Guayaquil
  • gygeo America/Guyana
  • cahal America/Halifax
  • cuhav America/Havana
  • mxhmo America/Hermosillo
  • usknx America/Indiana/Knox
  • usaeg America/Indiana/Marengo
  • uswsq America/Indiana/Petersburg
  • ustel America/Indiana/Tell_City
  • usinvev America/Indiana/Vevay
  • usoea America/Indiana/Vincennes
  • uswlz America/Indiana/Winamac
  • usind America/Indianapolis
  • cayev America/Inuvik
  • caiql America/Iqaluit
  • jmkin America/Jamaica
  • arjuj America/Jujuy
  • usjnu America/Juneau
  • usmoc America/Kentucky/Monticello
  • bolpb America/La_Paz
  • pelim America/Lima
  • uslax America/Los_Angeles
  • uslui America/Louisville
  • brmcz America/Maceio
  • nimga America/Managua
  • brmao America/Manaus
  • gpmsb America/Marigot
  • mqfdf America/Martinique
  • mxmzt America/Mazatlan
  • armdz America/Mendoza
  • usmnm America/Menominee
  • mxmid America/Merida
  • mxmex America/Mexico_City
  • pmmqc America/Miquelon
  • camon America/Moncton
  • mxmty America/Monterrey
  • uymvd America/Montevideo
  • camtr America/Montreal
  • msmni America/Montserrat
  • bsnas America/Nassau
  • usnyc America/New_York
  • cathu America/Thunder_Bay
  • usome America/Nome
  • brfen America/Noronha
  • usndcnt America/North_Dakota/Center
  • usndnsl America/North_Dakota/New_Salem
  • papty America/Panama
  • capnt America/Pangnirtung
  • srpbm America/Paramaribo
  • usphx America/Phoenix
  • htpap America/Port-au-Prince
  • ttpos America/Port_of_Spain
  • brpvh America/Porto_Velho
  • prsju America/Puerto_Rico
  • caffs America/Rainy_River
  • cayek America/Rankin_Inlet
  • brrec America/Recife
  • careg America/Regina
  • careb America/Resolute
  • brrbr America/Rio_Branco
  • brstm America/Santarem
  • clscl America/Santiago
  • dosdq America/Santo_Domingo
  • brsao America/Sao_Paulo
  • globy America/Scoresbysund
  • usnavajo America/Shiprock
  • gpsbh America/St_Barthelemy
  • casjf America/St_Johns
  • knbas America/St_Kitts
  • lccas America/St_Lucia
  • vistt America/St_Thomas
  • vcsvd America/St_Vincent
  • cayyn America/Swift_Current
  • hntgu America/Tegucigalpa
  • glthu America/Thule
  • mxtij America/Tijuana
  • cator America/Toronto
  • vgtov America/Tortola
  • cavan America/Vancouver
  • cayxy America/Whitehorse
  • cawnp America/Winnipeg
  • usyak America/Yakutat
  • cayzf America/Yellowknife
  • aqcas Antarctica/Casey
  • aqdav Antarctica/Davis
  • aqddu Antarctica/DumontDUrville
  • aqmaw Antarctica/Mawson
  • aqmcm Antarctica/McMurdo
  • aqplm Antarctica/Palmer
  • aqrot Antarctica/Rothera
  • aqams Antarctica/South_Pole
  • aqsyw Antarctica/Syowa
  • aqvos Antarctica/Vostok
  • sjlyr Arctic/Longyearbyen
  • yeade Asia/Aden
  • kzala Asia/Almaty
  • joamm Asia/Amman
  • rudyr Asia/Anadyr
  • kzaau Asia/Aqtau
  • kzakx Asia/Aqtobe
  • tmasb Asia/Ashgabat
  • iqbgw Asia/Baghdad
  • bhbah Asia/Bahrain
  • azbak Asia/Baku
  • thbkk Asia/Bangkok
  • lbbey Asia/Beirut
  • kgfru Asia/Bishkek
  • bnbwn Asia/Brunei
  • inccu Asia/Calcutta
  • mncoq Asia/Choibalsan
  • cnckg Asia/Chongqing
  • lkcmb Asia/Colombo
  • sydam Asia/Damascus
  • bddac Asia/Dhaka
  • tldil Asia/Dili
  • aedxb Asia/Dubai
  • tjdyu Asia/Dushanbe
  • gaza Asia/Gaza
  • cnhrb Asia/Harbin
  • hkhkg Asia/Hong_Kong
  • mnhvd Asia/Hovd
  • ruikt Asia/Irkutsk
  • idjkt Asia/Jakarta
  • iddjj Asia/Jayapura
  • jeruslm Asia/Jerusalem
  • afkbl Asia/Kabul
  • rupkc Asia/Kamchatka
  • pkkhi Asia/Karachi
  • cnkhg Asia/Kashgar
  • npktm Asia/Katmandu
  • rukra Asia/Krasnoyarsk
  • mykul Asia/Kuala_Lumpur
  • mykch Asia/Kuching
  • kwkwi Asia/Kuwait
  • momfm Asia/Macau
  • rugdx Asia/Magadan
  • idmak Asia/Makassar
  • phmnl Asia/Manila
  • ommct Asia/Muscat
  • cynic Asia/Nicosia
  • ruovb Asia/Novosibirsk
  • ruoms Asia/Omsk
  • kzura Asia/Oral
  • khpnh Asia/Phnom_Penh
  • idpnk Asia/Pontianak
  • kpfnj Asia/Pyongyang
  • qadoh Asia/Qatar
  • kzkzo Asia/Qyzylorda
  • mmrgn Asia/Rangoon
  • saruh Asia/Riyadh
  • vnsgn Asia/Saigon
  • ruuus Asia/Sakhalin
  • uzskd Asia/Samarkand
  • krsel Asia/Seoul
  • cnsha Asia/Shanghai
  • sgsin Asia/Singapore
  • twtpe Asia/Taipei
  • uztas Asia/Tashkent
  • getbs Asia/Tbilisi
  • irthr Asia/Tehran
  • btthi Asia/Thimphu
  • jptyo Asia/Tokyo
  • mnuln Asia/Ulaanbaatar
  • cnurc Asia/Urumqi
  • lavte Asia/Vientiane
  • ruvvo Asia/Vladivostok
  • ruyks Asia/Yakutsk
  • ruyek Asia/Yekaterinburg
  • amevn Asia/Yerevan
  • ptpdl Atlantic/Azores
  • bmbda Atlantic/Bermuda
  • eslpa Atlantic/Canary
  • cvrai Atlantic/Cape_Verde
  • fotho Atlantic/Faeroe
  • ptfnc Atlantic/Madeira
  • isrey Atlantic/Reykjavik
  • gsgrv Atlantic/South_Georgia
  • shshn Atlantic/St_Helena
  • fkpsy Atlantic/Stanley
  • auadl Australia/Adelaide
  • aubne Australia/Brisbane
  • aubhq Australia/Broken_Hill
  • aukns Australia/Currie
  • audrw Australia/Darwin
  • aueuc Australia/Eucla
  • auhba Australia/Hobart
  • auldc Australia/Lindeman
  • auldh Australia/Lord_Howe
  • aumel Australia/Melbourne
  • auper Australia/Perth
  • ausyd Australia/Sydney
  • utc Etc/GMT
  • utcw01 Etc/GMT+1
  • utcw10 Etc/GMT+10
  • utcw11 Etc/GMT+11
  • utcw12 Etc/GMT+12
  • utcw02 Etc/GMT+2
  • utcw03 Etc/GMT+3
  • utcw04 Etc/GMT+4
  • utcw05 Etc/GMT+5
  • utcw06 Etc/GMT+6
  • utcw07 Etc/GMT+7
  • utcw08 Etc/GMT+8
  • utcw09 Etc/GMT+9
  • utce01 Etc/GMT-1
  • utce10 Etc/GMT-10
  • utce11 Etc/GMT-11
  • utce12 Etc/GMT-12
  • utce13 Etc/GMT-13
  • utce14 Etc/GMT-14
  • utce02 Etc/GMT-2
  • utce03 Etc/GMT-3
  • utce04 Etc/GMT-4
  • utce05 Etc/GMT-5
  • utce06 Etc/GMT-6
  • utce07 Etc/GMT-7
  • utce08 Etc/GMT-8
  • utce09 Etc/GMT-9
  • unk Etc/Unknown
  • nlams Europe/Amsterdam
  • adalv Europe/Andorra
  • grath Europe/Athens
  • rsbeg Europe/Belgrade
  • deber Europe/Berlin
  • skbts Europe/Bratislava
  • bebru Europe/Brussels
  • robuh Europe/Bucharest
  • hubud Europe/Budapest
  • mdkiv Europe/Chisinau
  • dkcph Europe/Copenhagen
  • iedub Europe/Dublin
  • gigib Europe/Gibraltar
  • gggci Europe/Guernsey
  • fihel Europe/Helsinki
  • imdgs Europe/Isle_of_Man
  • trist Europe/Istanbul
  • jesth Europe/Jersey
  • rukgd Europe/Kaliningrad
  • uaiev Europe/Kiev
  • ptlis Europe/Lisbon
  • silju Europe/Ljubljana
  • gblon Europe/London
  • lulux Europe/Luxembourg
  • esmad Europe/Madrid
  • mtmla Europe/Malta
  • fimhq Europe/Mariehamn
  • bymsq Europe/Minsk
  • mcmon Europe/Monaco
  • rumow Europe/Moscow
  • noosl Europe/Oslo
  • frpar Europe/Paris
  • metgd Europe/Podgorica
  • czprg Europe/Prague
  • lvrix Europe/Riga
  • itrom Europe/Rome
  • rukuf Europe/Samara
  • smsai Europe/San_Marino
  • basjj Europe/Sarajevo
  • uasip Europe/Simferopol
  • mkskp Europe/Skopje
  • bgsof Europe/Sofia
  • sesto Europe/Stockholm
  • eetll Europe/Tallinn
  • altia Europe/Tirane
  • uauzh Europe/Uzhgorod
  • livdz Europe/Vaduz
  • vavat Europe/Vatican
  • atvie Europe/Vienna
  • ltvno Europe/Vilnius
  • ruvog Europe/Volgograd
  • plwaw Europe/Warsaw
  • hrzag Europe/Zagreb
  • uaozh Europe/Zaporozhye
  • chzrh Europe/Zurich
  • mgtnr Indian/Antananarivo
  • iodga Indian/Chagos
  • cxxch Indian/Christmas
  • cccck Indian/Cocos
  • kmyva Indian/Comoro
  • tfpfr Indian/Kerguelen
  • scmaw Indian/Mahe
  • mvmle Indian/Maldives
  • muplu Indian/Mauritius
  • ytmam Indian/Mayotte
  • rereu Indian/Reunion
  • wsapw Pacific/Apia
  • nzakl Pacific/Auckland
  • nzcht Pacific/Chatham
  • clipc Pacific/Easter
  • vuvli Pacific/Efate
  • kipho Pacific/Enderbury
  • tkfko Pacific/Fakaofo
  • fjsuv Pacific/Fiji
  • tvfun Pacific/Funafuti
  • ecgps Pacific/Galapagos
  • pfgmr Pacific/Gambier
  • sbhir Pacific/Guadalcanal
  • gugum Pacific/Guam
  • ushnl Pacific/Honolulu
  • umjon Pacific/Johnston
  • kicxi Pacific/Kiritimati
  • fmksa Pacific/Kosrae
  • mhkwa Pacific/Kwajalein
  • mhmaj Pacific/Majuro
  • pfnhv Pacific/Marquesas
  • ummdy Pacific/Midway
  • nrinu Pacific/Nauru
  • nuiue Pacific/Niue
  • nfnlk Pacific/Norfolk
  • ncnou Pacific/Noumea
  • asppg Pacific/Pago_Pago
  • pwror Pacific/Palau
  • pnpcn Pacific/Pitcairn
  • fmpni Pacific/Ponape
  • pgpom Pacific/Port_Moresby
  • ckrar Pacific/Rarotonga
  • mpspn Pacific/Saipan
  • pfppt Pacific/Tahiti
  • kitrw Pacific/Tarawa
  • totbu Pacific/Tongatapu
  • fmtkk Pacific/Truk
  • umawk Pacific/Wake
  • wfmau Pacific/Walli
 

Specifiche AGCOM

ALLEGATO A

SET DI CARATTERI AMMESSI PER LA COSTITUZIONE DEGLI ALIAS

Con riferimento al paragrafo 6.2.1 “GSM 7 bit Default Alphabet” dello standard tecnico “ Digital cellular telecommunications system (Phase 2+); Universal Mobile Telecommunications System (UMTS); LTE; Alphabets and language-specific information ”, 3GPP TS 23.038 version 11.0.0 (2012-10) Release 11, per la costituzione degli alias è ammissibile solo quanto segue.

  1. le lettere dell’alfabeto internazionale minuscole e maiuscole:
    • ABCDEFGHIJKLMNOPQRSTUVXYWZ (codici HEX rispettivamente da 41 a 5A)
    • abcdefghijklmnopqrstuvxywz (codici HEX rispettivamente da 61 a 6A)
  2. Le lettere minuscole accentate presenti nella tastiera italiana:
    • èéùìò (codici HEX rispettivamente da 04 a 08)
    • à (codice HEX 7F)
  3. Le cifre da 0 a 9
    • 0123456789 (codici HEX rispettivamente da 30 a 39)
  4. Comuni segni di punteggiatura:
    • SP (spazio: codice HEX 20 )
    • ! (punto esclamativo: codice HEX 21 )
    • ‘ (apostrofo: codice HEX 27 )
    • , (virgola: codice HEX 2C)
    • . (punto : codice HEX 2E)
    • : (due punti: codice HEX 3A)
    • ; (punto e virgola: codice HEX 3B)
    • ? (punto interrogativo: codice HEX 3F)
    • i precedenti caratteri non possono essere preceduti dal carattere spazio.
    • Non è consentito l’uso consecutivo di spazi
    • “ (virgolette, codice HEX 22 )
    • In un Alias, possono essere presenti esclusivamente due virgolette: una come apertura ed una come chiusura. La prima non può precedere un spazio e la seconda non può seguire uno spazio.
  5. Comuni simboli di valuta
    • € (euro: codice di due caratteri HEX 1B 65)
    • £ (lira: codice HEX 01 )
    • $ (dollaro: codice HEX 02 )
  6. Comuni simboli matematici
    • % (percentuale: codice HEX 25 )
    • ( (parentesi tonda aperta: codice HEX 28)
    • ) (parentesi tonda chiusa: codice HEX 29)
    • + (più: codice HEX 2B)
    • – (meno o anche trattino: codice HEX 2D)
    • = (uguale: codice HEX 3D)
  7. Simboli utilizzati in internet:
    • @ (chiocciolina o “ at ” : codice HEX 00)
    • _ ( sottolineato o “underscore” : codice HEX 11)
    • # (cancelletto o “ hash ” : codice HEX 23)
    • & (and: codice HEX 26 )
    • * (asterisco o “star” : codice HEX 2A)

In definitiva, la lista dei caratteri ammessi e le relative codifiche in esadecimale ETSI da utilizzare nella trasmissione degli SMS/MMS nonché le relative codifiche in esadecimale UTF-8 da utilizzare nella comunicazione verso la banca dati dell’Autorità sono:

Carattere

Codifica ETSI

Codifica UTF-8

Carattere

Codifica ETSI

Codifica UTF-8

Carattere

Codifica ETSI

Codifica UTF-8

@

00

40

8

38

38

Z

5A

5A

£

01

C2 A3

9

39

39

a

61

61

$

02

24

:

3A

3A

b

62

62

è

04

C3 A8

;

3B

3B

c

63

63

é

05

C3 A9

=

3D

3D

d

64

64

ù

06

C3 B9

?

3F

3F

e

65

65

ì

07

C3 AC

A

41

41

f

66

66

ò

08

C3 B2

B

42

42

g

67

67

_

11

5F

C

43

43

h

68

68

SP

20

20

D

44

44

i

69

69

!

21

21

E

45

45

j

6A

6A

'

22

22

F

46

46

k

6B

6B

#

23

23

G

47

47

l

6C

6C

%

25

25

H

48

48

m

6D

6D

&

26

26

I

49

49

n

6E

6E

'

27

27

J

4A

4A

o

6F

6F

(

28

28

K

4B

4B

p

70

70

)

29

29

L

4C

4C

q

71

71

*

2A

2A

M

4D

4D

r

72

72

+

2B

2B

N

4E

4E

s

73

73

,

2C

2C

O

4F

4F

t

74

74

-

2D

2D

P

50

50

u

75

75

.

2E

2E

Q

51

51

v

76

76

0

30

30

R

52

52

w

77

77

1

31

31

S

53

53

x

78

78

2

32

32

T

54

54

y

79

79

3

33

33

U

55

55

z

7A

7A

4

34

34

V

56

56

à

7F

C3 A0

5

35

35

W

57

57

1B 65

E2 82 AC

6

36

36

X

58

58

7

37

37

Y

59

59

Di conseguenza, la tabella dei caratteri utilizzabili organizzata secondo la codifica ETSI è la seguente.

b7

0

0

0

0

1

1

1

1

b6

0

0

1

1

0

0

1

1

b5

0

1

0

1

0

1

0

1

b4

b3

b2

b1

HEX

0

1

2

3

4

5

6

7

0

0

0

0

0

@
40

 

SP
20

0
30

 

P
50

 

p
70

0

0

0

1

1

£
C2 A3

_
5F

!
21

1
31

A
41

Q
51

a
61

q
71

0

0

1

0

2

$
24

 

'
22

2
32

B
42

R
52

b
62

r
72

0

0

1

1

3

 

 

#
23

3
33

C
43

S
53

c
63

s
73

0

1

0

0

4

è
C3 A8

 

 

4
34

D
44

T
54

d
64

t
74

0

1

0

1

5

è
C3 A9

 

%
25

5
35

E
45

U
55

e
65

u
75

0

1

1

0

6

ù
C3 B9

 

&
26

6
36

F
46

V
56

f
66

v
76

0

1

1

1

7

ì
C3 AC

 

'
27

7
37

G
47

W
57

g
67

w
77

1

0

0

0

8

ò
C3 B2

 

(
28

8
38

H
48

X
58

h
68

x
78

1

0

0

1

9

 

 

)
29

9
39

I
49

Y
59

i
69

y
79

1

0

1

0

A

 

 

*
2A

:
3A

J
4A

Z
5A

j
6A

z
7A

1

0

1

1

B

 

1)

+
2B

;
3B

K
4B

 

k
6B

 

1

1

0

0

C

 

 

,
2C

 

L
4C

 

l
6C

 

1

1

0

1

D

 

 

-
2D

=
3D

M
4D

     

m
6D

     

1

1

1

0

E

     

     

.
2E

     

N
4E

     

n
6E

     

1

1

1

1

F

     

     

     

?
3F

O
4F

     

o
6F

à
C3 A0

SP corrisponde al carattere spazio

1) non è un carattere ma indica il codice (HEX 1B) da anteporre per indicare i caratteri presenti nella Extension table . In particolare alla codifica HEX 1B 65 corrisponde il carattere €, la cui codifica UTF-8 è E2 82 AC. Il carattere € è l’unico carattere utilizzabile della Extension table .

In ciascuna cella è riportata in prima riga il carattere relativo alla codifica secondo lo standard 3GPP TS 23.038 version 11.0.0 (2012-10)

In seconda riga è riportata la relativa codifica UTF-8 da utilizzare nelle comunicazioni verso il DB dell' AGCOM