icon_qa

INTRODUZIONE API REST

Usi l'app Postman?
 

RIVENDITORI (BETA)


Per poter utilizzare le API elencate in questa pagina è necessario avere un account rivenditori e richiedere la specifica abilitazione.
RICHIEDI ABILITAZIONE

Nuovo SubAccount

Crea un nuovo SubAccount.

URI

POST https://api.smshosting.it/rest/api/reseller/subuser

Richiesta

  Il "Content-Type" per le richieste POST deve essere "application/x-www-form-urlencoded"
ParametroObbligatorioTipoDescrizione
username Si String

Lo username deve essere una stringa alfanumerica di lunghezza compresa tra 5 e 50 caratteri.

Oltre a lettere e numeri può contenere i seguenti caratteri: .@_-

password Si String

La password deve essere una stringa alfanumerica di lunghezza compresa tra 5 e 20 caratteri.

name Si String Nome
lastname Si String

Cognome

email Si String Indirizzo email valido
companyType Si Boolean

Valorizzare a true nel caso l'account sia associato ad un azienda

Possibili valori true/false

businessname

No

(Si nel caso companyType sia valorizzato a true )

Boolean Ragione sociale dell'azienda
address No String Indirizzo
city No String Città
postcode No String Codice di avviamento postale
province No String Provincia
country No String Nazione
birthdate No String Data di nascita nel formato yyyy-MM-dd'T'HH:mm:ssZ
phone No String Telefono
msisdn No String Cellulare
taxcode No String Codice Fiscale
vatnumber No String Partita IVA

Risposta

HTTP Status Code

CodiceDescrizione
200 ok
400

Parametri non validi

I possibili errorMsg sono:

BAD_ACCOUNT_TYPE - L'account con il quale si sta effettuando la chiamata non è un rivenditore

BAD_ACCOUNT_PERMISSION - L'account con il quale si sta effettuando la chiamata non è abilitato ad utilizzare questa API

BAD_USERNAME - Lo username non è valido

USERNAME_ALREADY_EXISTS - Esiste già un utente registrato con lo stesso username.

BAD_PASSWORD - La password non è valida

BAD_NAME - parametro name non valido

BAD_LASTNAME - parametro lastname non valido

BAD_EMAIL- parametro email non valido

BAD_BUSINESSNAME - parametro businessname non valido

GENERIC_ERROR - errore interno al server

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

Dati User

ProprietàDescrizione
id Identificativo univoco del SubAccount
name Nome
lastname Cognome
username Username dell'account
email Indirizzo Email
businessname Nome società se si tratta di azienda
address Indirizzo
city Città
postcode Codice di avviamento postale
province Provincia
country Nazione
birthdate Data di nascita
phone Telefono
msisdn Numero di cellulare
sender Mittente predefinito
senderAlias Elenco dei mittenti utilizzabili per l'invio
taxcode Codice fiscale
vatnumber Partita IVA
registrationDate Data di registrazione nel formato yyyy-MM-dd'T'HH:mm:ssZ
expirationDate

Data di scadenza account nel fomato yyyy-MM-dd'T'HH:mm:ssZ

Nota: Il tuo profilo su SmsHosting.it scade dopo un anno dal tuo ultimo ordine.

credit Credito residuo
italysms Numero di sms inviabili verso l'italia con il tuo credito residuo
authKey Chiave per le chiamare API
authSecret Secret per le chiamare API

 Esempio:

curl --user AUTH_KEY:AUTH_SECRET -XPOST https://api.smshosting.it/rest/api/reseller/subuser \
-d "username=demoapirest" \
-d "password=password" \
-d "name=Mario" \
-d "lastname=Rossi" \
-d "email=info@smshosting.it"
{
   "id":"1",
   "name":"Mario",
   "lastname":"Rossi",
   "username":"demoapirest",
   "email":"info@smshosting.it",
   "address":"",
   "city":"",
   "postcode":"",
   "province":"",
   "country":"",
   "phone":"",
   "msisdn":"",
   "sender":"smstools.it",
   "registrationDate":"2015-08-04T12:04:56+0200",
   "expirationDate":"2016-08-04T12:04:56+0200",
   "credit":0.6,
   "italysms":5,
   "italysmsLow":8,
   "senderAlias":[],
   "authKey": "0000",
   "authSecret": "0000"
}

Modifica SubAccount

Modifica l'anagrafica di un SubAccount.

URI

PUT https://api.smshosting.it/rest/api/reseller/subuser/<id>

Richiesta

  Il "Content-Type" per le richieste PUT deve essere "application/x-www-form-urlencoded"
ParametroObbligatorioTipoDescrizione
name Si String Nome
lastname Si String

Cognome

email Si String Indirizzo email valido
companyType Si Boolean

Valorizzare a true nel caso l'account sia associato ad un azienda

Possibili valori true/false

businessname

No

(Si nel caso companyType sia valorizzato a true )

Boolean Ragione sociale dell'azienda
address No String Indirizzo
city No String Città
postcode No String Codice di avviamento postale
province No String Provincia
country No String Nazione
birthdate No String Data di nascita nel formato yyyy-MM-dd'T'HH:mm:ssZ
phone No String Telefono
msisdn No String Cellulare
taxcode No String Codice Fiscale
vatnumber No String Partita IVA

Risposta

HTTP Status Code

CodiceDescrizione
200 ok
400

Parametri non validi

I possibili errorMsg sono:

BAD_ACCOUNT_TYPE - L'account con il quale si sta effettuando la chiamata non è un rivenditore

BAD_ACCOUNT_PERMISSION - L'account con il quale si sta effettuando la chiamata non è abilitato ad utilizzare questa API

SUBUSER_NOT_EXISTS - SubAccount non trovato

BAD_NAME - parametro name non valido

BAD_LASTNAME - parametro lastname non valido

BAD_EMAIL- parametro email non valido

BAD_BUSINESSNAME - parametro businessname non valido

GENERIC_ERROR - errore interno al server

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

Dati User

Fare riferimento alla chiamata nuovo SubAccount per il dettaglio dei dati ritornati

 Esempio:

curl --user AUTH_KEY:AUTH_SECRET -XPUT https://api.smshosting.it/rest/api/reseller/subuser/1 \
-d "name=Mario" \
-d "lastname=Rossi" \
-d "email=info@smshosting.it"
{
   "id":"1",
   "name":"Mario",
   "lastname":"Rossi",
   "username":"demoapirest",
   "email":"info@smshosting.it",
   "address":"",
   "city":"",
   "postcode":"",
   "province":"",
   "country":"",
   "phone":"",
   "msisdn":"",
   "sender":"smstools.it",
   "registrationDate":"2015-08-04T12:04:56+0200",
   "expirationDate":"2016-08-04T12:04:56+0200",
   "credit":0.6,
   "italysms":5,
   "italysmsLow":8,
   "senderAlias":[],
   "authKey": "0000",
   "authSecret": "0000"
}

Cancella SubAccount

Cancella in modo definitivo un SubAccount.

URI

DELETE https://api.smshosting.it/rest/api/reseller/subuser/<id>

Richiesta

Nessun parametro richiesto

Risposta

HTTP Status Code

CodiceDescrizione
200 ok
400

Parametri non validi

I possibili errorMsg sono:

BAD_ACCOUNT_TYPE - L'account con il quale si sta effettuando la chiamata non è un rivenditore

BAD_ACCOUNT_PERMISSION - L'account con il quale si sta effettuando la chiamata non è abilitato ad utilizzare questa API

SUBUSER_NOT_EXISTS - SubAccount non trovato

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

 

 Esempio:

curl --user AUTH_KEY:AUTH_SECRET -XDELETE https://api.smshosting.it/rest/api/reseller/subuser/1

Carica SubAccount

Carica il dettaglio completo di un SubAccount.

URI

GET https://api.smshosting.it/rest/api/reseller/subuser/<id>

Richiesta

Nessun parametro richiesto

Risposta

HTTP Status Code

CodiceDescrizione
200 ok
400

Parametri non validi

I possibili errorMsg sono:

BAD_ACCOUNT_TYPE - L'account con il quale si sta effettuando la chiamata non è un rivenditore

BAD_ACCOUNT_PERMISSION - L'account con il quale si sta effettuando la chiamata non è abilitato ad utilizzare questa API

SUBUSER_NOT_EXISTS - SubAccount non trovato

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

Dati User

Fare riferimento alla chiamata nuovo SubAccount per il dettaglio dei dati ritornati

 Esempio:

curl --user AUTH_KEY:AUTH_SECRET https://api.smshosting.it/rest/api/reseller/subuser/1
{
   "id":"1",
   "name":"Mario",
   "lastname":"Rossi",
   "username":"demoapirest",
   "email":"info@smshosting.it",
   "address":"",
   "city":"",
   "postcode":"",
   "province":"",
   "country":"",
   "phone":"",
   "msisdn":"",
   "sender":"smstools.it",
   "registrationDate":"2015-08-04T12:04:56+0200",
   "expirationDate":"2016-08-04T12:04:56+0200",
   "credit":0.6,
   "italysms":5,
   "italysmsLow":8,
   "senderAlias":[],
   "authKey": "0000",
   "authSecret": "0000"
}

Cerca SubAccount

Ritorna la lista dei SubAccount con possibilità di filtrare i risultati

URI

GET https://api.smshosting.it/rest/api/reseller/subuser/search

Richiesta

ParametroObbligatorioTipoDescrizione
query No String

Ricerca SubAccount per username,nome e cognome

fromDate No String

Data dalla quale i SubAccount sono stati registrati in formato yyyy-MM-ddTHH:mm:ssZ

toDate No String Data alla quale i SubAccount sono stati registrati in formato yyyy-MM-ddTHH:mm:ssZ
offset No Integer

Posizione del primo risultato che verrà restituito.

Esempio:

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

Default : 0

limit No Integer

Numero di risultati che verranno restituiti.

Default : 20

Risposta

HTTP Status Code

CodiceDescrizione
200 ok
400

Parametri non validi

I possibili errorMsg sono:

BAD_ACCOUNT_TYPE - L'account con il quale si sta effettuando la chiamata non è un rivenditore

BAD_ACCOUNT_PERMISSION - L'account con il quale si sta effettuando la chiamata non è abilitato ad utilizzare questa API

SUBUSER_NOT_EXISTS - SubAccount non trovato

BAD_DATE - Formato date non valido

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

Dati User

Ritorna una lista di SubAccount.Fare riferimento alla chiamata nuovo SubAccount per il dettaglio di un singolo record

 Esempio:

curl --user AUTH_KEY:AUTH_SECRET https://api.smshosting.it/rest/api/reseller/subuser/search
{
  "metadata": {
    "count": 1,
    "offset": 0,
    "limit": 20
  },
  "subUserList": [
   { 
    "id":"1",
    "name":"Mario",
    "lastname":"Rossi",
    "username":"demoapirest",
    "email":"info@smshosting.it",
    "address":"",
    "city":"",
    "postcode":"",
    "province":"",
    "country":"",
    "phone":"",
    "msisdn":"",
    "sender":"smstools.it",
    "registrationDate":"2015-08-04T12:04:56+0200",
    "expirationDate":"2016-08-04T12:04:56+0200",
    "credit":0.6,
    "italysms":5,
    "italysmsLow":8,
    "senderAlias":[],
    "authKey": "0000",
    "authSecret": "0000"
   }
  ]
}

Crea Ordine

Crea ed attiva un ordine per un determinato SubAccount.

E' possbile assegnare un pacchetto SMS esistente o alternativamente creare un nuovo pacchetto indicando semplicemente il numero di SMS da assegnare.

URI

POST https://api.smshosting.it/rest/api/reseller/subuser/<id>/order

Richiesta

  Il "Content-Type" per le richieste POST deve essere "application/x-www-form-urlencoded"
ParametroObbligatorioTipoDescrizione
packId

No

(Obbligatorio valorizzare almeno uno tra il campo packId e newPackSmsItaly)

Integer

Identificativo del pacchetto SMS da attivare. Utilizzare la chiamata lista pacchetti per recuperare gli identificativi

newPackSmsItaly

No

(Obbligatorio valorizzare almeno uno tra il campo packId e newPackSmsItaly)

Integer

Numero di SMS da assegnare creando un nuovo pacchetto

newPackUnitCostItaly No Double Costo singolo usato nella creazione del nuovo pacchetto. Viene utilizzato in combinazione con il parametro newPackSmsItaly

Default: 0.07 €

Risposta

HTTP Status Code

CodiceDescrizione
200 ok
400

Parametri non validi

I possibili errorMsg sono:

BAD_ACCOUNT_TYPE - L'account con il quale si sta effettuando la chiamata non è un rivenditore

BAD_ACCOUNT_PERMISSION - L'account con il quale si sta effettuando la chiamata non è abilitato ad utilizzare questa API

NO_PARAMS - Nessun parametro valorizzato

BAD_PACKID - parametro packId non valido

BAD_SMS - parametro newPackSmsItaly non valido

BAD_UNITCOST - parametro newPackUnitCostItaly non valido

NO_CREDIT - il rivenditpre non ha abbastanza credito per completare l'operazione

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

 Esempio:

curl --user AUTH_KEY:AUTH_SECRET -XPOST https://api.smshosting.it/rest/api/reseller/subuser/1/order \
-d "newPackSmsItaly=14" 

Lista pacchetti SMS configurati

Ritorna la lista dei pacchetti ordinabili.

URI

GET https://api.smshosting.it/rest/api/reseller/pack/list

Richiesta

Nessun dato richiesto

Risposta

HTTP Status Code

CodiceDescrizione
200 ok
400

Parametri non validi

I possibili errorMsg sono:

BAD_ACCOUNT_TYPE - L'account con il quale si sta effettuando la chiamata non è un rivenditore

BAD_ACCOUNT_PERMISSION - L'account con il quale si sta effettuando la chiamata non è abilitato ad utilizzare questa API

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

Dati Pacchetto

ProprietàDescrizione
id Identificativo del pacchetto
smsItaly numero SMS inviabili in Italia
unitCostItaly costo singolo SMS italia
unitCostOtherZoneA costo singolo SMS estero zona A
unitCostOtherZoneB costo singolo SMS estero zona B
unitCostOtherZoneC costo singolo SMS estero zona C
totalCost costo totale pacchetto
validFromDate valido da data
validToDate valido a data

 Esempio:

curl --user AUTH_KEY:AUTH_SECRET https://api.smshosting.it/rest/api/reseller/pack/list
[
  {
    "id": 1,
    "smsItaly": 0,
    "unitCostItaly": 0.105,
    "unitCostOtherZoneA": 0.084,
    "unitCostOtherZoneB": 0.105,
    "unitCostOtherZoneC": 0.158,
    "totalCost": 0,
    "validFromDate": "09.10.2004",
    "validToDate": "30.12.2005"
  }
]

Rimuovi credito SubAccount

Rimuove il credito da un SubAccount e lo riassegna all'account rivenditore.

URI

POST https://api.smshosting.it/rest/api/reseller/subuser/<id>/credit/remove

Richiesta

Nessun parametro richiesto

Risposta

HTTP Status Code

CodiceDescrizione
200 ok
400

Parametri non validi

I possibili errorMsg sono:

BAD_ACCOUNT_TYPE - L'account con il quale si sta effettuando la chiamata non è un rivenditore

BAD_ACCOUNT_PERMISSION - L'account con il quale si sta effettuando la chiamata non è abilitato ad utilizzare questa API

SUBUSER_NOT_EXISTS - SubAccount non trovato

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

 

 Esempio:

curl --user AUTH_KEY:AUTH_SECRET -XPOST https://api.smshosting.it/rest/api/reseller/subuser/1/credit/remove