OnniSMS Rajapintakuvaus v1.1
1.0 Yleistä OnniSMS on HTTPS/XML pohjainen rajapinta tekstiviestin lähettämiseen. Palvelun käyttöön tarvitaan käyttäjätunnus, salasana ja palvelimen osoite, jotka saa tekemällä sopimuksen palvelusta Onnisys Oy:n kanssa. 2.0 Tekstiviestien lähettäminen Tekstiviestin lähettäminen tapahtuu lähettämällä seuraavanlainen XML-sanoma HTTPS POST:lla: <?xml version="1.0"?> <onnisms> <version>1.0</version> <request type="send"> <from></from> <to></to> <message><![cdata[ ]]></message> <username></username> <password></password> </request> </onnisms> Kenttien sisältö on seuraava Kenttä Käyttötarkoitus Sallitut arvot version Rajapinnan 1.0 versionumero from Tekstiviestin lähettäjän ilmaiseva merkkijono Alphanumeerisena enintään 11 merkkiä. Sallitut merkit (a-z, A-Z, 0-9). Matkapuhelinnumerona enintään 15 numeroa. Numero ilmoitetaan kansainvälisessä muodossa (esim. Suomessa +358...) to Tekstiviestin Matkapuhelinnumero
vastaanottajan puhelinnumero kansainvälisessä muodossa (esim. Suomessa +358..) message Tekstiviestin sisältö Tekstiviestin sisältö CDATA-lohkon sisällä, enintään 160 merkkiä username Käyttäjätunnus rajapintaan Onnisys Oy ilmoittaa password Salasana rajapintaan Onnisys Oy ilmoittaa Onnistuneesta rajapintakutsusta palautuu lähettäjälle seuraavanlainen sanoma <onnisms><response><code>200</code><smsid>123456789</smsid></r esponse></onnisms> Onnistuneesta lähetyksestä palautuva smsid on yksilöivä numeerinen tunniste tekstiviestille. Sen pituus on enintään 12 numeroa. Smsid:n avulla on mahdollista erillisellä kutsulla kysyä tekstiviestin toimitustila. Tämä toiminto on kuvattu kappaleessa 3. Mahdolliset vaihtoehdot response code:lle ovat Response code Merkitys 200 Viesti vastaanotettu lähetettäväksi 401 Kirjautuminen rajapintaan epäonnistui, tarkista käyttäjätunnus ja salasana 500 Sisällöllinen virhe pyynnössä Mikäli response code on 500 palautuu lisäsi errormsg elementti, joka ilmaisee tarkemman syyn. Esimerkiksi: <onnisms><response><code>500</code><errormsg>unknown request type!</errormsg></response></onnisms>
3.0 Tekstiviestien toimitustiedon kysyminen Tekstiviestin lähetyksen rajapinnasta palautuvan smsid-numeron avulla on mahdollista myöhemmin kysyä tekstiviestin toimitustilanne. Tämä tapahtuu lähettämällä seuraavanlainen XML-sanoma HTTPS POST:lla rajapintaan: <?xml version="1.0"?> <onnisms> <version>1.0</version> <request type="query"> <smsid></smsid> <username></username> <password></password> </request> </onnisms> Kenttien sisältö on seuraava Kenttä Käyttötarkoitus Sallitut arvot version Rajapinnan 1.0 versionumero smsid Tekstiviestin yksilöivä numero Tekstiviestin lähetyksen palautunut arvo username Käyttäjätunnus rajapintaan Onnisys Oy ilmoittaa password Salasana rajapintaan Onnisys Oy ilmoittaa Onnistuneesta rajapintakutsusta palautuu lähettäjälle seuraavanlainen vastaus <onnisms><response><code>200</code><smsid>123456789</smsid><status>1</sta tus><statustime>2014-09-27 15:01:55</statustime></response></onnisms>
Code 200 ilmaisen kyselyn onnistuneen. Smsid sisältää saman arvon kuin rajapintaan lähetetyssä kyselyssä on. Statukselle on mahdollisia seuraavat arvot Status-kentän arvo Merkitys 0 Viesti on otettu välitettäväksi, mutta sitä ei ole vielä pystytty toimittamaan vastaanottajalle 1 Viesti on onnistuneesti toimitettu 2 Operaattori on hylännyt viestin 3 Viestin toimitus on epäonnistunut (esimerkiksi tuntematon puhelinnumero) Statustime sisältää aikaleiman, jolloin viestin tilassa on viimeksi tapahtunut muutos. Kellonaika on Suomen aikaa. Kenttä on muotoa vvvv-kk-pp tt:mm:ss. Mikäli kysely epäonnistuu palautuu seuraavanlainen virheilmoitus: <onnisms><response><code>500</code><errormsg>smsid must be wrong or unknown.</errormsg><smsid>123456789</smsid></response></onnisms> Code 500 ilmaisee kyselyn epäonnistuneen. Lisäksi palautuu tarkempi virheilmoitus errmsg-kentässä. 4.0 Lisätiedot Mikäli haluat lisätietoja rajapintojen käyttöstä voit ottaa yhteyttä Onnisysin asiakaspalveluun.