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.

IN QUESTA GUIDA

Invio codice

Controlla codice

Annulla codice

Cerca codice

Invio codice

Invia un codice numerico ad un destinatario.

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


URI


Richiesta

Il " Content-Type" per le richieste  POST deve essere " application/x-www-form-urlencoded"
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 errorMsg  sono:

ANTISPAM  - sono stati inviati più di 10 sms negli ultimi 60 minuti allo stesso destinatatio.

BAD_TO  - parametro to non valido

BAD_TEXT_PLACEHOLDER  -  text manca ${verify_code} oppure contiene dei placeholder non sostituibili

BAD_TEXT  - parametro text non valido

BAD_FROM  - parametro from non valido

BAD_ENCODING  - parametro encoding non valido

BAD_APP_ID  - parametro app_id non valido

BAD_COD_LEN  - parametro code_len non valido

BAD_RETRY  - parametro max_retry non valido

BAD_TTL  - parametro ttl non valido

NO_CREDIT  - credito insufficiente per effetturare l'invio

GENERIC_ERROR  - errore interno al server
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 errorMsg  sono:

VERIFY ID ERROR  - parametro verify_id non valido
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

VERIFIED  - Il codice corrisponde

FAILED  - Il codice NON corrisponde

EXPIRED  - Il codice è scaduto

VERIFY ID ERROR  - Il parametro verify_id non è corretto.

REUSED  - Il codice è stato gia verificato.

CANCELLED  - Il codice è stato cancellato

 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:

DELETE


Risposta

HTTP Status Code

Codice Descrizione
200 ok
400

Parametri non validi

I possibili errorMsg  sono:

VERIFY ID ERROR  - parametro verify_id non è valido

BAD STATUS  - la richiesta non è cancellabile, è già inutilizzabile

BAD_COMMAND  - parametro command non è valido
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 errorMsg  sono:

NO_PARAMS  - Nessun parametro valorizzato

VERIFY ID ERROR  - Parametro verify_id non valido
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"
   }]
}

Articoli correlati