Fortumo mobiilimakse/Dünaamilise SMS API tehnilised andmed

Dünaamiline SMS- teenus on kõige paindlikum teenustüüp Fortumos. See võimaldab luua pea ükskõik millise SMS- teenuse, mille peale võid tulla, kuid selleks on vaja mõningaid programmeerimisoskusi ja veebiserverit, kus Sa saaksid oma programmi (näiteks php- skripti) majutada. Suhtlus meie serveri ja Sinu skripti vahel toimub HTTP GET päringutega. On olemas kolm võimalikku HTTP päringut, mida on kirjeldatud allpool. Parameetrid, mida päringus kasutatakse, on alati samad. Kõige tähtsam ja kohustuslik sõnumite protsessis on esimene tüüp.

Sõnumi edastamine

Kui Su teenusele tuleb sõnum, teeb Fortumo HTTP GET päringu URL-le, mille oled määratlenud oma teenuse konfiguratsioonis (näiteks http://yourdomain.com/sms.php). Sisu, mille Fortumo vastusena saab sinu URL-lt (või tegelikult esimesed 120 tähemärki sellest) saadetakse tagasi kasutajale vastussõnumina. Selle HTTP GET päringu parameetrid määravad ära kasutaja telefoninumbri, sõnumi sisu jne. Seega saad kasutada kogu seda informatsiooni vastussõnumi genereerimiseks.

Maksustamise raportid

Riikides, kus on MT-maksustamine, annavad mobiilioperaatorid sõnumi maksustamise edukuse (või ebaõnnestumise) kohta teada kohe pärast vastussõnumi väljasaatmist. Kui Sa soovid saada seda informatsiooni, peaksid Sa võimaldama maksustamise raportid oma dünaamilise SMS-teenuse konfiguratsioonis. Me saadame Sulle maksustamise raporti Sinu määratud URL-le kohe pärast sõnumi edastamist. Igasugune vastus Sinu skriptilt loetakse kui edukaks edastuseks.Sinu vastust maksustamise raportile ei edastata mobiilioperaatorile, seega ei saa Sa kasutada maksustamise raporte selleks, et edastada vastussõnumeid. Kasuta esimest päringut.

Sinu skripti testimine

Sinu kontol on sisseehitatud testimise funktsioon.Pärast oma URL-li lisamist oma kontole, võid minna „Testimine“ alajaotusesse menüüribal ja algatada test päringu meie serverilt Sinu skriptile.Test päringus esitatakse parameeter test ja see märgitakse kui „true“ ehk tõene.

Parameetrid

message: Sõnumi sisust märksõnad maha arvata. Näiteks, kui sõnum on TXT KEY 123, on see parameeter 123. Parameeter jääb tühjaks, kui on olemas ainult märksõna ja ei ole lisateksti sõnumis.
sender: Sõnumisaatja telefoninumber rahvusvahelises formaadis ilma plussmärgita. Näiteks, 4560123456 või 358401234567
country: Saatja mobiilioperaatori riigikood. Lähtuvalt ISO 3166-1 standardist kasutatakse kahetähelisi koode (SE- Rootsi, FI - Soome, NO - Norra, LT - Leedu, LV - Läti, EE - Eesti jne). Palun pane tähele, et see EI pruugi ilmtingimata olla saatja tegelik asukoht. Näiteks saatja Rootsi numbriga, võib sõnumi saata roamingu kaudu Norrast, ja Sul peab ikka olema SE riigi lahtris.
price: Lõppkasutaja sõnumi hind kohalikus valuutas, k.a. käibemaks.
currency: Kohaliku valuuta sümbol lähtuvalt ISO 4217-le (EUR, SEK, NOK, DKK, LTL, LVL, EEK, USD, GBP jne).
service_id: String, mis identifitseerib Sinu teenuse. Näiteks f7fa12b381d290e268f99e382578d64a. String muutub vajalikuks siis kui Sul on mitu teenust sama URL-ga, sellisel juhul saad oma teenuseid just selle stringi abil eristada.
message_id: String, mis on unikaalne iga sõnumi kohta, mille su teenus vastu võtab.
keyword: Sõnumi märksõna osa. Näiteks, kui sõnum on TXT KEY 123, on see parameeter TXT KEY.
shortcode: Lühinumber, millele sõnum saadeti.
operator: Sõnumi saatja mobiilioperaatori nimi
billing_type: Võib olla MO või MT. Loe maksustamise süsteemide kohta rohkem Fortumo FAQ-st.
status: Maksustamise staatus, mis on kas pending (sõnumi edastamise päringus), ok või failed (maksustamise raportis).
test: See parameeter eksisteerib päringus vaid juhul kui sõnum on sinu poolt saadetud Fortumo testimise funktsiooni kaudu ja selle väärtus on alati 'true'.
sig: Päringu allkiri, et sa saaksid kontrollida, kas päring tuleb ikka Fortumolt. Vaata allpoolt Turvalisuse alt, et uurida, kuidas see käib.

Inimestel on tavaliselt vaja message ja ehk sender parameetreid, kuid edasijõudnumatele kasutajatele oleme lisanud ka teisi.

Turvalisus

On väga tähtis, et teenuse skripti kutsuks välja ainult Fortumo, mitte keegi teine. Selleks on olemas mitmeid turvameetmeid, mis rahuldavad suurema osa teenusepakkujaid.:

Vaata järele, kas päringut tegeva serveri IP aadress on ikka ühe Fortumo serveri oma. Meie praegused IP aadressid on 81.20.151.38, 81.20.148.122, 79.125.125.1 ja 209.20.83.207. Me anname sulle e-mailiga teada, kuid need muutuvad. PHP-s saad seda kontrollida $_SERVER["REMOTE_ADDR"] muutujaga.
Ära vali väga ilmset ja lihtsat nime oma registrile või skriptile. Näiteks, http://yourdomain.com/sms.php ei ole nii hea kui http://yourdomain.com/go850g3oigjrtog/sms.php.
Veendu, et kaasas olev allkiri kattuks. Kõik päringud on märgistatud ühiselt, mis on ainult teada Sulle ja Fortumole. Viimase õigsust saad kontrollida teenuse seadete vaatest. Allkiri lisatakse sig parameetrina ja arvutatakse md5 summana, kus päringu parameeter ja märge on kokku liidetud. Sa võid prooviks teha sama arvutuse ning veenduda kas sig parameeter päringus on sama, mille iseseisvalt said. Palun vaata allolevat PHP näidist, et näha kuidas arvutus täpselt käib.

Näidis sms.php

<?php

  //set true if you want to use script for billing reports
  //first you need to enable them in your account
  $billing_reports_enabled = false;

  // check that the request comes from Fortumo server
  if(!in_array($_SERVER['REMOTE_ADDR'],
      array('81.20.151.38', '81.20.148.122', '79.125.125.1', '209.20.83.207'))) {
    header("HTTP/1.0 403 Forbidden");
    die("Error: Unknown IP");
  }

  // check the signature
  $secret = ''; // insert your secret between ''
  if(empty($secret) || !check_signature($_GET, $secret)) {
    header("HTTP/1.0 404 Not Found");
    die("Error: Invalid signature");
  }

  $sender = $_GET['sender'];
  $message = $_GET['message'];
  $message_id = $_GET['message_id'];//unique id
  //hint:use message_id to log your messages
  //additional parameters: country, price, currency, operator, keyword, shortcode 
  // do something with $sender and $message
  $reply = "Thank you $sender for sending $message";

  // print out the reply
  echo($reply);
 
 //customize this according to your needs
  if($billing_reports_enabled 
    && preg_match("/Failed/i", $_GET['status']) 
    && preg_match("/MT/i", $_GET['billing_type'])) {
   // find message by $_GET['message_id'] and suspend it
  }


  function check_signature($params_array, $secret) {
    ksort($params_array);

    $str = '';
    foreach ($params_array as $k=>$v) {
      if($k != 'sig') {
        $str .= "$k=$v";
      }
    }
    $str .= $secret;
    $signature = md5($str);

    return ($params_array['sig'] == $signature);
  }
?>

Kopeeri kood