ColourSMS Protokol definíció Version 1.2
1.1 HTTP request A ColourSMS(Westel/Pannon) alkalmazások által kiadott HTTP request formátuma a következő: http://third_party_url/path_to_application A third_party_url a Third Party által megadott URL-t jelenti, míg a path_to_application a Third Party által megadott alkalmazás WEB elérési útvonalát jelenti. A kommunikáció során a HTTP protokoll 1.1-es verzióját támogatja a ColourSMS alkalmazás az alábbi megkötésekkel: Nem támogatja az SSL/TLS feletti kommunikációt. A HTTP szintű kommunikációban csak a 2xx-es status code-ok értelmezettek. Minden mást 1xx, 3xx, 4xx, 5xx hibának vesz az alkalmazás és a továbbítani kívánt SMS undeliverable státuszú lesz. Nem támogatja azon WEB server-ekkel történő kommunikációt, mely nem ad vissza Content-Type és Content-Length header-eket, azaz chunked formátumban továbbítja a client fele a válasz üzenetet. A POST request során használt paraméterek a következőek: Paraméter neve SessionID SrcAddr DestAddr ServiceID Dcs Data Paraméter jelentése Tranzakció azonosító. Funkciója az adott SMS továbbításának egyértelmű azonosítása. Kötelezően jelen van minden request-ben. Az SMS-t feladó MSIsdn-je. Meglété opcionális. Az alkalmazáshoz kirendelt fogadó MSIsdn. Megléte kötelező. Szolgáltatás média azonosító. Értéke ezen szolgáltatásmál kötelezően sms. Megléte kötelező. GSM 03.38 szerinti data coding schema. Az üzenet HTTP encoded szövege. Az SrcAddr és DestAddr formátuma 3630xxxxxxx, 3620xxxxxxx vagy 0630xxxxxxx, 0620xxxxxxx formátumú. Dcs értéke 0-255-ig terjedő értéket vehet fel. Szöveges üzenet esetén értéke 0, bináris üzenet (oplogó, csengőhang, stb ) esetén értéke 245. 1.2 XML response Minden HTTP request-re a TPWEB server XML formátumú üzenetben küldi vissza a mobile client számára továbbítandó válaszát mely egy vagy több SMS-t tartalmazhat. A response HTTP headerben a ColourSMS alkalmazás az alábbi paraméterek meglétét ellenőrzi: Paraméter neve Content-Type Content-Length Paraméter jelentése Értéke kötelezően text/xml Az aktuális XML válaszüzenet hossza Ezen paraméterek hiánya hibás válasz üzenetet feltételez. A XML formátumú üzenet szerkezete a következő: <?xml version="1.0" encoding="iso-8859-1"?> <Reply SessionID=id>
<Header> <FormatVersion>version</FormatVersion> <response> id = A HTTP kérésben kapott azonosító version = 1.0 <response>::= <parameters> <parameters>::= [<Dcs></Dcs>] [<DataHeader></DataHeader>] [<Data></Data>] [<ValidityPeriodRelative></ValidityPeriodRelative>] [<ValidityPeriodAbsolute></ValidityPeriodAbsolute>] [<FirstDeliveryTimeRelative></FirstDeliveryTimeRelative>] [<FirstDeliveryTimeAbsolute></FirstDeliveryTimeAbsolute>] [<Price></Price>] Tag neve Leírása Opcionális Formátum <Dcs> </Dcs> <DataHeader> </DataHeader> <Data> Egy válasz SMS kezdetét jelöli, egy válaszon belül több üzenet is lehet. Egy SMS válasz végét jelöli Speciális SMS paraméter leírása a GSM 03.38 specifikációban Bináris üzenetek típusa Előfizetőknek küldendő üzenet Nem Nem Értéke: 0-255 Jelentése a GSM 03.38- ban leirtaknak megfelelő. Bináris SMS esetén értelmezett. Karakteresen ábrázolt hexadecimális érték. Hossza a <Data> mezővel együtt 280 karakter Szöveges üzenet esetén max. 160 karakter hosszú iso-8859-1 kódulású szöveg. Bináris üzenetek esetén max. 280 karakter hosszú (a <DataHeader> mezővel együtt) karakteresen ábrázolt hexadecimális értékek.
</Data> <ValidityPeriodRelative> </ValidityPeriodRelative> <ValidityPeriodAbsolute> </ValidityPeriodAbsolute> <FirstDeliveryTimeRelative> </FirstDeliveryTimeRelative> <FirstDeliveryTimeAbsolute> A (megadott érték+1)*5 percig lesz érvényes az üzenet az SMSC-be érkezés pillanatától számítva. Az érvényességi idő lejárta után törlődik az SMSC-ből és a kiküldés sikertelen. A kiküldendő SMS eddig az időpontig lesz érvényes. Ezután az SMSC sikertelennek minősíti a kiküldést és törli az SMS-t. A maximális érvényességi idő 30 perc. Ha értéke 1, akkor az SMSC azonnal megpróbálja kikézbesíteni az SMS-t. Egyébként (megadott érték+1)*5 perc késleltetéssel próbálja küldeni az SMSC az üzenetet. Az SMS kiküldésének időpontja Értéke: 0-6 Default értéke: 6 (30 perc) YYYYMMDDHH24MISS pl. 20020329235012 Default értéke: aktuális időpont + 30 perc (-1) 6 Default: -1 </FirstDeliveryTimeAbsolute> <Price> SMS ára forint.fillér </Price> YYYYMMDDHH24MISS pl. 20020329235223 <ValidityPeriodRelative> és <ValidityPeriodAbsolute> egyidejű használata eseten az utolsó értéke a mérvadó. <FirstDeliveryTimeRelative> és <FirstDeliveryTimeAbsolute> egyidejű használata eseten az utolsókent megadott időpont a mérvadó. A használt XML protokoll verzió száma kötelezően 1.0. Minden ettől eltérő verziószámú XML struktúra használata hibát okoz. Character encoding kötelezően ISO-8859-1. Ettől eltérő character set használata nem definiált működést eredményez. A <FirstDeliveryTimeRelative> és <FirstDeliveryTimeAbsolute> tag-ek funkciója jelenleg a Westel irányban nem támogatott szolgáltatás. Az alkalmazás ezen tag-eket figyelmen kívül hagyja. A <Price> tag használata esetén a rendszer figyelmen kívül hagyja annak értékét, mivel az értelmezéséhez szükséges Payment gateway jelen pillanatban hiányzik. Használata hibás működést nem okoz. Néhány példa XML üzenet: 1. Egy két SMS-ből álló válasz üzenet:
<?xml version="1.0" encoding="iso-8859-1"?> <Reply SessionID="771"> <Header> <FormatVersion>1.0</FormatVersion> <ValidityPeriodRelative>2</ValidityPeriodRelative> <FirstDeliveryTimeRelative>2</FirstDeliveryTimeRelative> <Data>Info válaszüzenet!</data> <Price>240</Price> <Data>Ez a második szöveg.</data> <Price>240</Price> 2. Egy binary válasz üzenet: <?xml version="1.0" encoding="iso-8859-1"?> <Reply SessionID="772"> <Header> <FormatVersion>1.0</FormatVersion> <Dcs>245</Dcs> <DataHeader>060504158200</DataHeader> <Data>0012F60300480E018000000000000000010000000000000000000 00000000000000000000800000000000000001</Data>