API per SMS OTP
Per accedere alla funzione API per SMS OTP clicca dal menù a sinistra la voce Sviluppatori - SMS OTP.
Le SMS OTP API consentono di inviare codici PIN e sono pensate per semplificare la vita agli sviluppatori, lasciando la generazione e la verifica dei codici in carico al nostro gateway.
Puoi personalizzare il testo dell'SMS, scegliere la lunghezza del PIN generato e il tempo massimo ammesso per la verifica in base alle tue esigenze di sicurezza.
Invio codice
Invia un codice numerico ad un destinatario.
È possibile testare l'invio valorizzando il parametro sandbox
a true nella richiesta.
URI
Richiesta
Parametro | Obbligatorio | Tipo | Descrizione |
---|---|---|---|
to | Si | String | Il destinatario del messaggio. Deve essere un numero di cellulare compreso di prefisso internazionale. Ad esempio: 393481234567 |
text | Si | String | Testo del messaggio. Se il messaggio supera i 160 caratteri vengono inviati più sms concatenati fino ad una massimo di 7. Il testo deve contenere il placeholder che sarà sostituito in fase di invio dal codice. Il placeholder va specificato con la sintassi ${verify_code} Ad esempio: text=SMSHosting codice ${verify_code} |
from | No | String | Il mittente del Sms. Può essere un numero di telefono validato oppure una stringa alfanumerica di 11 caratteri. Se non specificato viene usato il mittente di default del proprio profilo. |
sandbox | No | Boolean | Consente di testare la chiamata senza inviare effettivamente il messaggio. Parametro utile in fase di sviluppo di eventuali integrazioni con le REST API. Possibili valori true/false |
app_id | No | String | Identifica l'applicazione per cui si richiede il codice. È possibile specificare un proprio identificativo Attenzione: Non si possono generare 2 codici attivi contemporaneamente per lo stesso destinatario per la stessa applicazione |
encoding | No | String | L'encoding da utilizzare per il testo del messaggio. I possibili valori sono: 7BIT - Encoding standard per i messaggi GSM. La lunghezza massima per un singolo sms è di 160 caratteri. UCS2 - Encoding a 8-bit per inviare messaggi GSM con contenuto non ASCII. La lunghezza massima per un singolo sms è di 70 caratteri. AUTO - L'encoding da utilizzare viene automaticamente identificato in base al contenuto del campo testo. Default : 7BIT |
code_len | No | Integer | Lunghezza del codice I valori possibili sono da 4 a 6. Default: 4 |
max_retry | No | Integer | Numero massimo di tentativi ammessi. I valori possibili sono da 1 a 20. Default: 3 |
ttl | No | Integer | durata massima in secondi del codice. Il valore minimo è di 10. Default: 300 |
Risposta
HTTP Status Code
Codice | Descrizione |
---|---|
200 | ok |
400 | Parametri non validi I possibili
|
401 | Credenziali non valide |
405 | Metodo HTTP non consentito |
500 | Errore generico |
Risposta
Proprietà | Descrizione |
---|---|
verify_id | Identificativo univoco della richiesta codice. |
Esempio:
curl --user AUTH_KEY:AUTH_SECRET \ -XPOST https://api.smshosting.it/rest/api/verify/send \ -d "to=393480000000" \ -d "text=Codice di sblocco \${verify_code}"
// Send verify code HttpResponse verify_send_response = Unirest.post("https://api.smshosting.it/rest/api/verify/send") .header("accept", "application/json") .basicAuth(SMS_AUTH_KEY, SMS_SECRET_KEY) .field("to", "393470000000") .field("text", "Codice \"&\" ${verify_code}") .asJson();
Unirest\Request::auth(SMS_AUTH_KEY, SMS_SECRET_KEY); $headers = array( 'Accept' => 'application/json' ); $data = array( 'to' => '393470000000', 'text' => 'Codice è ${verify_code}' ); $body = Unirest\Request\Body::form($data); $response = Unirest\Request::post('https://api.smshosting.it/rest/api/verify/send', $headers, $body);
response = unirest.post( "https://api.smshosting.it/rest/api/verify/send", headers={ "Accept": "application/json" }, auth=(SMS_AUTH_KEY, SMS_SECRET_KEY), params={ "to": "393470000000", "text": "Codice ${verify_code}", "sandbox": "true" } )
String body = ""; body = body + "&text=" + HttpUtility.UrlEncode(tbOtpSendText.Text); body = body + "&to=" + HttpUtility.UrlEncode(tbOtpSendTo.Text); body = body + "&from=" + HttpUtility.UrlEncode(tbOtpSendFrom.Text); body = body + "&sandbox=" + cbOtpSendSandbox.Checked; body = body + "&app_id=" + HttpUtility.UrlEncode(tbOtpSendAppId.Text); body = body + "&encoding=" + HttpUtility.UrlEncode(cbOtpSendEncoding.Text); body = body + "&code_len=" + HttpUtility.UrlEncode(tbOtpSendCodLen.Text); body = body + "&max_retry=" + HttpUtility.UrlEncode(tbOtpSendMaxRetry.Text); body = body + "&ttl=" + HttpUtility.UrlEncode(tbOtpSendTtl.Text); HttpResponse jsonResponse = Unirest.post(tbOtpSendUrl.Text) .header("Content-Type", "application/x-www-form-urlencoded") .header("Accept", tbOtpSendAccept.Text) .basicAuth(tbAuth_key.Text, tbAuth_secret.Text) .body(body) .asString();
Scarica il progetto Swift di esempio da GitHub. iOS OTP demo library.
Scarica il progetto Android di esempio da GitHub. iOS OTP demo library.
{ "verify_id": "c6cf59524c65d9c65d134d1137a86336558d19ba" }
Controlla codice
Controlla se il codice corrisponde a quello inviato via SMS.
URI
Richiesta
Parametro | Obbligatorio | Tipo | Descrizione |
---|---|---|---|
verify_id | Si | String | Il codice ricevuto dal comando send. |
verify_code | Si | String | Il numero da testare. |
ip_address | No | String | Ip del'utente per permettere di implementare un filtro antispam. |
Risposta
HTTP Status Code
Codice | Descrizione |
---|---|
200 | ok |
400 | Parametri non validi I possibili
|
401 | Credenziali non valide |
405 | Metodo HTTP non consentito |
500 | Errore generico |
Risposta
Proprietà | Descrizione |
---|---|
id_sms | Id dell'sms inviato. Si può usare con https://api.smshosting.it/rest/api/verify/search per recuperare il messaggio |
verify_status | Esito della verifica
|
Esempio:
curl --user AUTH_KEY:AUTH_SECRET \ -XGET "https://api.smshosting.it/rest/api/verify/check?verify_id=728d03eee5a72e8102a4a905e6325449d27c583b&verify_code=1234"
HttpResponse verify_check_response = Unirest.get("https://api.smshosting.it/rest/api/verify/check") .header("accept", "application/json") .basicAuth(SMS_AUTH_KEY, SMS_SECRET_KEY) .queryString("verify_id", "d95d2904792f1f172643380a9c46820cfbbe7042") .queryString("verify_code", "1234") .asJson();
Unirest\Request::auth(SMS_AUTH_KEY, SMS_SECRET_KEY); $headers = array( 'Accept' => 'application/json' ); $param = array( 'verify_id' => urlencode('11280b70bdadb73aa659c4b9a87d2107b9225027'), 'verify_code' => urlencode('1234') ); $response = Unirest\Request::get('https://api.smshosting.it/rest/api/verify/check', $headers, $param);
response = unirest.get( "https://api.smshosting.it/rest/api/verify/check", headers={ "Accept": "application/json" }, auth=(SMS_AUTH_KEY, SMS_SECRET_KEY), params={ "verify_id": urllib.quote("3d44093fb3ebb065cecff89158f6310812a80344"), "verify_code": urllib.quote("1234") } )
String queryString = "?"; queryString = queryString + "&verify_id=" + HttpUtility.UrlEncode(tbOtpCheckVerifyId.Text); queryString = queryString + "&verify_code=" + HttpUtility.UrlEncode(tbOtpCheckCode.Text); queryString = queryString + "&ip_address=" + HttpUtility.UrlEncode(tbOtpCheckIp.Text); HttpResponse jsonResponse = Unirest.get(tbOtpCheckUrl.Text + queryString) .header("accept", tbOtpCheckAccept.Text) .basicAuth(tbAuth_key.Text, tbAuth_secret.Text) .asString();
{ "id_sms": "410065822", "verify_status": "VERIFIED" }
Annulla codice
Annulla un codice attivo.
Permette di annullare un codice ancora utilizzabile.
URI
POST https://api.smshosting.it/rest/api/verify/command
Richiesta
Il "Content-Type" per le richieste POST deve essere "application/x-www-form-urlencoded"
Parametro | Obbligatorio | Tipo | Descrizione |
---|---|---|---|
verify_id | Si | String | Il codice ricevuto dal comando send. |
command | Si | String | Può assumenre il valore:
|
Risposta
HTTP Status Code
Codice | Descrizione |
---|---|
200 | ok |
400 | Parametri non validi I possibili
|
401 | Credenziali non valide |
405 | Metodo HTTP non consentito |
500 | Errore generico |
Risposta
Proprietà | Descrizione |
---|---|
command | Comando eseguito |
Esempio:
curl --user AUTH_KEY:AUTH_SECRET -XPOST https://api.smshosting.it/rest/api/verify/command \ -d "verify_id=35baca938c120e49e462809b4e62efb5fe6f6bd8" \ -d "command=DELETE"
HttpResponse verify_canc_response = Unirest.post("https://api.smshosting.it/rest/api/verify/command") .basicAuth(SMS_AUTH_KEY, SMS_SECRET_KEY) .field("verify_id", "d95d2904792f1f172643380a9c46820cfbbe7042") .field("command", "DELETE") .asJson();
Unirest\Request::auth(SMS_AUTH_KEY, SMS_SECRET_KEY); $headers = array( 'Accept' => 'application/json' ); $data = array( 'verify_id' => '11280b70bdadb73aa659c4b9a87d2107b9225027', 'command' => urlencode('DELETE') ); $body = Unirest\Request\Body::form($data); $response = Unirest\Request::post('https://api.smshosting.it/rest/api/verify/command', $headers, $body);
response = unirest.post( "https://api.smshosting.it/rest/api/verify/command", headers={ "Accept": "application/json" }, auth=(SMS_AUTH_KEY, SMS_SECRET_KEY), params={ "verify_id": "3d44093fb3ebb065cecff89158f6310812a80344", "command": "DELETE" } )
String body = ""; body = body + "&verify_id=" + HttpUtility.UrlEncode(tbOtpCommandVerifyId.Text); body = body + "&command=" + HttpUtility.UrlEncode(tbOtpCommandCommand.Text); HttpResponse jsonResponse = Unirest.post(tbOtpCommandUrl.Text) .header("Content-Type", "application/x-www-form-urlencoded") .header("Accept", tbOtpCommandAccept.Text) .basicAuth(tbAuth_key.Text, tbAuth_secret.Text) .body(body) .asString();
{ "command": "DELETE" }
Cerca codice
Recupera la storia di un codice.
URI
GET https://api.smshosting.it/rest/api/verify/search
Richiesta
Parametro | Obbligatorio | Tipo | Descrizione |
---|---|---|---|
verify_id | Si | String | Il codice ricevuto dal comando send. |
Risposta
HTTP Status Code
Codice | Descrizione |
---|---|
200 | ok |
400 | Parametri non validi I possibili
|
401 | Credenziali non valide |
405 | Metodo HTTP non consentito |
500 | Errore generico |
Risposta
Proprietà | Descrizione |
---|---|
verify_id | id della richiesta |
verify_status | stato attuale della richiesta |
to | destinatatio dell'SMS |
from | mittente del messaggio |
id_sms | id del SMS inviato. |
codice | codice inviato. Popolato solo se sandbox=true. |
date_submit | data invio del messaggio. |
valid_until | data fine validità. |
checks | enenco dei check registrati. date - data check verify_code - codice inviato verify_status - esito ip_address -ip_address inviato |
Esempio:
curl --user AUTH_KEY:AUTH_SECRET \ -XGET "https://api.smshosting.it/rest/api/verify/search?verify_id=728d03eee5a72e8102a4a905e6325449d27c583b"
HttpResponse verify_search_response = Unirest.get("https://api.smshosting.it/rest/api/verify/search") .basicAuth(SMS_AUTH_KEY, SMS_SECRET_KEY) .queryString("verify_id", "d95d2904792f1f172643380a9c46820cfbbe7042") .asJson();
Unirest\Request::auth(SMS_AUTH_KEY, SMS_SECRET_KEY); $headers = array( 'Accept' => 'application/json' ); $param = array( 'verify_id' => urlencode('11280b70bdadb73aa659c4b9a87d2107b9225027') ); $response = Unirest\Request::get('https://api.smshosting.it/rest/api/verify/search', $headers, $param);
response = unirest.get( "https://api.smshosting.it/rest/api/verify/search", headers={ "Accept": "application/json" }, auth=(SMS_AUTH_KEY, SMS_SECRET_KEY), params={ "verify_id": urllib.quote("3d44093fb3ebb065cecff89158f6310812a80344") } )
String queryString = "?"; queryString = queryString + "&verify_id=" + HttpUtility.UrlEncode(tbOtpSearchVerifyId.Text); HttpResponse jsonResponse = Unirest.get(tbOtpSearchUrl.Text + queryString) .header("accept", cbOtpSearchAccept.Text) .basicAuth(tbAuth_key.Text, tbAuth_secret.Text) .asString();
{ "verify_id": "745ab0c7d2bebd93e7e114ec973a1c997182fcbf", "verify_status": "VERIFIED", "to": "393480000000", "from": "393480000000", "id_sms": "410065825", "date_submit": 1480499821000, "valid_until": 1480500121000, "checks": [ { "date": 1480499858000, "verify_code": "4506", "verify_status": "VERIFIED", "ip_address": "192.168.1.1" }] }