icon_qa

INTRODUZIONE API REST

Usi l'app Postman?
 

SMS OTP

Invio Codice

Invia un codice numerico ad un destinatario.

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

URI

POST https://api.smshosting.it/rest/api/verify/send

Richiesta

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

Il testo può contenere un 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

CodiceDescrizione
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_PLACEHOLDERtext 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

GET https://api.smshosting.it/rest/api/verify/check

Richiesta

ParametroObbligatorioTipoDescrizione
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

CodiceDescrizione
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"
ParametroObbligatorioTipoDescrizione
verify_id Si String

Il codice ricevuto dal comando send.

command

Si

String Può assumenre il valore:

DELETE

Risposta

HTTP Status Code

CodiceDescrizione
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

ParametroObbligatorioTipoDescrizione
verify_id Si String

Il codice ricevuto dal comando send.

Risposta

HTTP Status Code

CodiceDescrizione
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"
   }]
}