SMS Gateway v1.6.0 HTTPS interfész leírás v1.3

SMS Gateway v1.6.0 HTTPS interfész leírás v1.3 2012. március 12.

Kivonat Jelen dokumentáció az SMS alkalmazásokat fejlesztő és üzemeltető társaságok részére készült. A dokumentációban kitérünk a HTTPS alapú interfész működésére, konfigurálhatóságára, kezelésére.

Tartalomjegyzék 1. Általános célkitűzés

2

2. A HTTPS interfész működése 2.1. SMS fogadás . . . . . . . . . . . . . . . . . . . 2.1.1. SMS paraméterek (fogadás) . . . . . . 2.1.2. Fogadott SMS nyugtázása . . . . . . . 2.2. SMS küldés . . . . . . . . . . . . . . . . . . . 2.2.1. SMS paraméterek (küldés) . . . . . . . 2.2.2. Feladott SMS nyugtázása . . . . . . . 2.3. Kézbesítés értesítő fogadása (DeliveryReport) 2.3.1. DeliveryReport paraméterek (fogadás)

2 2 2 3 4 4 6 7 7

. . . . . . . .

. . . . . . . .

. . . . . . . .

. . . . . . . .

. . . . . . . .

. . . . . . . .

. . . . . . . .

. . . . . . . .

. . . . . . . .

. . . . . . . .

. . . . . . . .

. . . . . . . .

. . . . . . . .

. . . . . . . .

. . . . . . . .

. . . . . . . .

A. GSM karakter kódolás

8

B. Hibakódok

9

1

Vodafone SMS Gateway HTTPS interfész

1.

Általános célkitűzés

A jelenlegi bérelt vonali illetve VPN összeköttetések mellett egy új, egyszerűbb, HTTPS alapú kapcsolódási alternatívát vezetünk be. Célunk, hogy az SMS Gateway és az SMS alkalmazások közti kapcsolatot HTTPS interfészen keresztül gyorsabban ki tudjuk építeni így biztosítsuk, hogy partnereink minél gyorsabban és egyszerűbben el tudjanak indulni szolgáltatásaikkal.

2.

A HTTPS interfész működése

SMS alkalmazásokat működtető vállalatok részére lehetőséget biztosítunk SMS-ek fogadásra, küldésre, kézbesítési riport lekérdezésére HTTPS interfészen keresztül.

2.1.

SMS fogadás

SMS fogadásához a partnernek rendelkeznie kell egy a Vodafone hálózatából elérhető webszerverrel. Biztonsági okokból csak HTTPS protokol használható. A webszerveren levő tanúsítvány lehet ún. „self-signed” is. Partnernek meg kell adnia egy URL-t, ahova Vodafone rendszere HTTP POST metódussal a partnernek szóló SMS-t elküldi. A POST application/x-www-form-urlencoded kódolással, UTF-8 karakterkódolással kerül kiküldésre. 2.1.1.

SMS paraméterek (fogadás)

username† : (string) Felhasználó név. password† : (string) Jelszó. type: (string) Az üzenet típusa. Fix érték: SMSMessage. id: (string) Az SMS azonosítója. timestamp: (timestamp) Az SMS időbélyege. Formátum: yyyyMMddHHmmss. src? : (address) Az SMS feladója. dst? : (address) Az SMS címzettje. text‡ : (string) Az SMS szövege (UTF-8 kódolásban). dcs‡ : (integer) Data Coding Scheme a GSM 03.40 szabvány szerint. udh‡ : (byte[]) Bináris fejléc (User Data Header). A byteok hexadecimális formában vannak kódolva. udb‡ : (byte[]) Bináris adat (User Data Binary). A byteok hexadecimális formában vannak kódolva. srcport‡ : (integer) Forrás port. 2


dstport‡ : (integer) Cél port. mss† : (integer) Összefűzött SMS esetén az üzenet sorszáma. A számozás 1-től indul. mts† : (integer) Összefűzött SMS esetén az üzenetek száma. mrn† : (integer) Összefűzott SMS esetén az üzenet referencia száma. Ez a referenciaszám az összefűzött SMS minden darabjában ugyanaz. imsi† : (string) Az SMS feladójának IMSI azonosítója. smsc† : (string) Az SMS központ (SMSC) gateway címe. vmsc† : (string) A Visited MSC gateway címe. pid† : (integer) Protokol azonosító. Megjegyzések: ? A telefonszámokat alapesetben nemzetközi formátumban (+36xxyyyzzzz) küldjük. Indokolt esetben más formátum is beállítható (pl. 06xxyyyzzzz). † A paraméter opcionális, nem minden üzenetben szerepel. ‡ Szöveges sms esetén a text mező mindig ki van töltve. Bináris SMS esetén text mezőt nem küldünk, a dcs, udh és udb mezőket mindig küldjük. Ha van udh mező, az tartalmazza a multipart és a port információkat is – ezek az értékek megegyeznek a megfelelő paraméterek értékeivel (mss, mts, mrn, srcport, dstport). Az udh mező tartalmazhat még ezeken kívül egyéb (pl. telefon specifikus) információkat is, ezeket más módon nem adjuk át, csak az udh mezőben kódolva. Speciális esetként az UCS2 kódolású bináris SMS (dcs = 8) text paramétere van csak kitöltve a dekódolt szövegtartalommal (az udb ilyenkor üres). Az optimális teljesítmény érdekében a partner szerverének a HTTP/1.1 protokolt támogatnia kell. Egy megnyitott HTTP kapcsolaton több üzenetet is küldhetünk, a kapcsolat csak akkor bomlik le, ha huzamosabb ideig nincs SMS forgalom. 2.1.2.

Fogadott SMS nyugtázása

Az SMS átvételét partnernek nyugtáznia kell (HTTP 200 OK). Amennyiben meghatározott időn belül (alap esetben 1 perc) nem kapunk vissza pozitív nyugtát, az SMS-t újra megpróbáljuk kikézbesíteni. Az újrakézbesítést egyre növekvő időközönkét az SMS érvényességének lejártáig folytatjuk. Az üres választ sikeres átvételként kezeljük. Lehetőség van a válaszban hibakódot illetve hibaüzenetet megadni, ami naplózásra kerül. Ez esetben egy text/plain típusú HTTP válaszban, UTF-8 karakterkódolással, url-encoded formátumban kell a következő paramétereket megadni: errorcode† : (integer) Hibakód. A 0 hibakód jelenti a sikeres kézbesítést. Ha ez a paraméter nem szerepel, akkor sikeresnek tekintjük a kézbesítést. errormsg† : (string) A hiba szöveges leírása. Példa: errorcode=1&errormsg=adatb%c3%a1zis+hiba 3


2.2.

SMS küldés

SMS-t a partner HTTP GET vagy HTTP POST metódussal tud küldeni a Vodafone által meghatározott URL-re (https://smsgw.vodafone.hu/sms). Szöveges és bináris SMS is küldhető, akár összefűzőtt üzenetként is. Szöveg esetén a kódolást meg lehet adni (character-encoding). Ez csak POST metódusnál használható. Ha a karakter kódolás nincs megadva vagy GET metódussal küldi a partner az SMS-t, akkor UTF-8 karakter kódolással értelmezzük az üzenetet. Az optimális teljesítmény érdekében HTTP/1.1 használata javasolt. Egy SMS-ben GSM kódolást használva 160 karakter küldhető, UCS2 kódolást használva pedig 70. Összefűzött SMS használatával egy részletben GSM kódolásban 153 (16 bites referencia szám használatával 152), UCS2 kódolásban egy részletben 67 (16 bites referencia szám használatával 66) karakter küldhető. Összefoglalva: GSM kódolás

UCS2 kódolás

Normál SMS

160

70

Összefűzött SMS, 8 bites referencia

153

67

Összefűzött SMS, 16 bites referencia

152

66

Normál esetben a feladott SMS GMS karatkerkészletre konvertálódik kiküldés előtt. Ilyenkor bizonyos karakterek lecserélődnek a GSM karakterkészletben elérhető hasonló karakterre. Az érintett karaktereket az A függelék 1. táblázata tartalmazza. Bizonyos karakterek a GSM kódolásban 2 karakteren kódolhatóak csak el. Ezen karakterek használatakor ügyelni kell a szöveg hosszának számolásakor, mert előfordulhat, hogy egy 160 karakteres üzenet nem küldhető ki, mivel a kódolás után hosszabb lesz. Ezeket a speciális karaktereket az A függelék 2. táblázata tartalmazza. 2.2.1.

SMS paraméterek (küldés)

action† : (string) Nem kötelező, de ha szerepel, akkor mindig sendsms. username: (string) Felhasználó név. password: (string) Jelszó. type† : (string) Az üzenet típusa. Nem kötelező, de ha szerepel, akkor mindig SMSMessage. src† : (address) Az SMS feladója. dst? : (address) Az SMS címzettje. text‡ : (string) Az SMS szövege. tc† : (integer) Árazási információ (Tariff Class). dcs‡ : (integer) Kódolási mód (Data Coding Scheme) a GSM 03.40 szabvány szerint.

4


udh‡ : (byte[]) Bináris fejléc (User Data Header). A byteokat hexadecimális formában kell kódolni. A rendszer a következő UDH paramétereket kezeli: • IEI_MULTIPART_8BIT_REF • IEI_MULTIPART_16BIT_REF • IEI_APPLICATION_PORT_ADDRESSING_8BIT • IEI_APPLICATION_PORT_ADDRESSING_16BIT Ezeket a paramétereket meg lehet adni az udh mezőbe kódolva, vagy egyedileg is (mss, mts, mrn, srcport, dstport). Amennyiben ezek a paraméterek mindkét helyen szerepelnek, akkor a két helyen kódolt értéknek azonosnak kell lennie. A rendszer által nem kezelt UDH elemeket ellenőrzés és módosítás nélkül adja tovább a telefonnak. Bizonyos telefonokon például csengőhang, háttérkép küldhető megfelelően kódolt UDH/UDB értékekkel. udb‡ : (byte[]) Bináris adat (User Data Binary). A byteokat hexadecimális formában kell kódolni. srcport‡ : (integer) Forrás port. dstport‡ : (integer) Cél port. srr† : (integer) Kézbesítési értesítés kérése. Értékei: 0: Nincs kézbesítési értesítés. 1: Csak sikeres kézbesítés esetén van értesítés. 2: Csak sikertelen kézbesítés esetén van értesítés. 3: Minden esetben van értesítés. vpa† : (timestamp) Érvényességi idő (dátum). Formátum: yyyyMMddHHmmss. vpr† : (integer) Érvényességi idő (relatív). Az SMS érvényességi ideje millisecundumban a feladástól számítva. fda† : (timestamp) Első kézbesítési idő (dátum). Formátum: yyyyMMddHHmmss. fdr† : (integer) Első kézbesítési idő (relatív). Az SMS első kézbesítési ideje millisecundumban a feladástól számítva. mss† : (integer) Összefűzött SMS esetén az üzenet sorszáma. A számozás 1-től indul. mts† : (integer) Összefűzött SMS esetén az üzenetek száma.

5


mrn† : (integer) Összefűzott SMS esetén az üzenet referencia száma. Ennek a referenciaszámnak az összefűzött SMS minden darabjában azonosnak kell lennie. A referenciaszámot célszerű 0 és 255 között választani, mivel így a multipart információ kisebb helyet foglal, az SMS-ben küldhető adatmennyiség 1 bytetal több. Ellenkező esetben a referenciaszám alsó 16 bitjét kódoljuk az üzenetbe. pid† : (integer) Protokol azonosító. Megjegyzések: ? A telefonszámokat általában nemzetközi formátumban (+36xxyyyzzzz) kérjük. Indokolt esetben más formátumban is elfogadjuk (pl. 06xxyyyzzzz). † A paraméter opcionális, megadása nem kötelező. ‡ Szöveges sms esetén a text mező kitöltése kötelező, az udh opcionális, az udb mezőt viszont nem szabad kitölteni. Bináris SMS esetén a text mezőt nem szabad kitölteni, az adatokat az udb mezőben kell küldeni. Az udh mező kitöltése ez esetben is opcionális. Speciális esetként az UCS2 kódolású bináris SMS (dcs = 8) feladható úgy is, hogy az udb paraméter használata helyett a kódolandó szöveg a text paraméterben van megadva. 2.2.2.

Feladott SMS nyugtázása

A Vodafone rendszere a beérkező SMS-re a következő HTTP válaszokat adhatja: 401: Hibás username vagy password. 503: A Vodafone rendszere nem képes átvenni az üzenetet vagy a partner egyidejűjel túl sok SMS-t küld. A párhuzamosan küldhető SMS-ek száma állítható, alap értéke 1. 200: A Vodafone rendszere a kérést sikeresen feldolgozta. Sikeres átvétel esetén (HTTP 200 OK) a rendszer egy text/plain típusú HTTP választ küld UTF-8 karakterkódolással. Ebben url-encoded formátumban a következő paraméterek szerepelnek: type: (string) Az üzenet típusa. Fix érték: SMSMessageResp. id: (string) Az SMS azonosítója. A kézbesítés értesítő (DeliveryReport) is ezt az azonosítót tartalmazza. errorcode: (integer) Hibakód. A 0 hibakód jelenti a sikeres kézbesítést. Az előforduló hibakódok listáját a B függelék 3. táblázata tartalmazza. errormsg† : (string) A hiba szöveges leírása. Példa: type=SMSMessageResp&id=SMGA99%241331288350594%247&errorcode=0

6


2.3.

Kézbesítés értesítő fogadása (DeliveryReport)

Amennyiben a partner az SMS feladásakor kért kézbesítés értesítőt (srr paraméter), az SMS sikeres vagy sikertelen kiküldéséről értesítést küldünk. A partner által megadott URL-re HTTP POST metódussal a következő adatokat küldjük el: 2.3.1.

DeliveryReport paraméterek (fogadás)

username† : (string) Felhasználó név. password† : (string) Jelszó. type: (string) Az üzenet típusa. Fix érték: SMSDeliveryReport. id: (string) Az SMS azonosítója amelyről a kézbesítési értesítést küldjük. state: (integer) Állapot kód. Értékei: 0: Nem elérhető 1: Folyamatban 2: Lejárt 3: Sikertelen kézbesítés 4: Sikeres kézbesítés 5: Nincs válasz 6: Nincs válasz 7: Visszavonva 8: Törölve 9: Visszavonás miatt törölve statuserrorcode: (integer) Rendszer hiba kód. finaldate: (timestamp) A sikeres kézbesítés vagy az utolsó próbálkozás, törlés időpontja. Formátum: yyyyMMddHHmmss.

7


A.

GSM karakter kódolás 1. táblázat: Konvertált karakterek Kód 0x0060 0x00B4 0x00C0 0x00C1 0x00C2 0x00C3 0x00C7 0x00C8 0x00CA 0x00CB 0x00CC 0x00CD 0x00CE 0x00CF 0x00D2 0x00D3 0x00D4 0x00D5 0x00D9 0x00DA 0x00DB 0x00E1 0x00ED 0x00F3 0x00F5 0x00FA 0x00FB 0x0150 0x0151 0x0170 0x0171 0x2013 0x2014 0x2018 0x2019 0x201C 0x201D

Karakter ‘ ´ À Á Â Ã Ç È Ê Ë Ì Í Î Ï Ò Ó Ô Õ Ù Ú Û á í ó õ ú û Ő ő Ű ű – — ‘ ’ “ ”

GSM ’ ’ Å Å Å Å ç É É É ì ì ì ì ò ò Ö Ö ù ù Ü à ì ò ö ù ü Ö ö Ü ü ’ ’ " "

Megnevezés GRAVE ACCENT ACUTE ACCENT LATIN CAPITAL LETTER A WITH GRAVE LATIN CAPITAL LETTER A WITH ACUTE LATIN CAPITAL LETTER A WITH CIRCUMFLEX LATIN CAPITAL LETTER A WITH TILDE LATIN CAPITAL LETTER C WITH CEDILLA LATIN CAPITAL LETTER E WITH GRAVE LATIN CAPITAL LETTER E WITH CIRCUMFLEX LATIN CAPITAL LETTER E WITH DIAERESIS LATIN CAPITAL LETTER I WITH GRAVE LATIN CAPITAL LETTER I WITH ACUTE LATIN CAPITAL LETTER I WITH CIRCUMFLEX LATIN CAPITAL LETTER I WITH DIAERESIS LATIN CAPITAL LETTER O WITH GRAVE LATIN CAPITAL LETTER O WITH ACUTE LATIN CAPITAL LETTER O WITH CIRCUMFLEX LATIN CAPITAL LETTER O WITH TILDE LATIN CAPITAL LETTER U WITH GRAVE LATIN CAPITAL LETTER U WITH ACUTE LATIN CAPITAL LETTER U WITH CIRCUMFLEX LATIN SMALL LETTER A WITH ACUTE LATIN SMALL LETTER I WITH ACUTE LATIN SMALL LETTER O WITH ACUTE LATIN SMALL LETTER O WITH TILDE LATIN SMALL LETTER U WITH ACUTE LATIN SMALL LETTER U WITH CIRCUMFLEX LATIN CAPITAL LETTER O WITH DOUBLE ACUTE LATIN SMALL LETTER O WITH DOUBLE ACUTE LATIN CAPITAL LETTER U WITH DOUBLE ACUTE LATIN SMALL LETTER U WITH DOUBLE ACUTE EN DASH EM DASH LEFT SINGLE QUOTATION MARK RIGHT SINGLE QUOTATION MARK LEFT DOUBLE QUOTATION MARK RIGHT DOUBLE QUOTATION MARK

2. táblázat: Speciális GSM karakterek Kód 0x000C 0x005E 0x007B 0x007D 0x005C 0x005B

Karakter ^ { } \ [

GSM kód 0x1B0A 0x1B14 0x1B28 0x1B29 0x1B2F 0x1B3C

8

Megnevezés FORM FEED CIRCUMFLEX ACCENT LEFT CURLY BRACKET RIGHT CURLY BRACKET REVERSE SOLIDUS LEFT SQUARE BRACKET folytatás a következő oldalon


Kód 0x007E 0x005D 0x007C 0x20AC

B.

Karakter ~ ] | €

2. táblázat – GSM kód 0x1B3D 0x1B3E 0x1B40 0x1B65

folytatás Megnevezés TILDE RIGHT SQUARE BRACKET VERTICAL LINE EURO SIGN

Hibakódok 3. táblázat: Error Codes Dec 0 1 2 3 4 5 6 7

Hex 0x00000000 0x00000001 0x00000002 0x00000003 0x00000004 0x00000005 0x00000006 0x00000007

Name OK InvalidMsgLength InvalidCmdLength InvalidCmdId IncorrectBindStatus AlreadyBound InvalidPriority InvalidRegisteredDeliveryFlag

8 10 11 12 13 14 15 17 19 20 21

0x00000008 0x0000000A 0x0000000B 0x0000000C 0x0000000D 0x0000000E 0x0000000F 0x00000011 0x00000013 0x00000014 0x00000015

SystemError InvalidSrcAddress InvalidDstAddress InvalidMessageId BindFailed InvalidPassword InvalidSystemId CancelFailed ReplaceFailed MsgQueueFull InvalidServiceType

51

0x00000033

InvalidNumOfDestinations

52 64 66 67 68 69 72 73 80 81 83 84 85 88 97

0x00000034 0x00000040 0x00000042 0x00000043 0x00000044 0x00000045 0x00000048 0x00000049 0x00000050 0x00000051 0x00000053 0x00000054 0x00000055 0x00000058 0x00000061

InvalidDistributionListName InvalidDestinationFlag InvalidSubmitWithReplace InvalidESMClass CannotSubmitToDistributionList SubmitFailed InvalidSrcTON InvalidSrcNPI InvalidDstTON InvalidDstNPI InvalidSystemType InvalidReplaceIfPresent InvalidNumberOfMessages Throttled InvalidSchedule

98

0x00000062

InvalidExpiry

99

0x00000063

InvalidDefinedMessageId

Description No error

Incorrect priority parameter usage Incorrect status report request parameter usage General system error Incorrect originator address usage Incorrect destination address

Temporary congestion error Incorrect transport type parameter usage Incorrect number of destination addresses

Incorrect dcs parameter usage

Incorrect first delivery parameter usage Incorrect validity period parameters usage folytatás a következő oldalon

9


100 101 102 103 192 193 194 195 196 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 1073741825 1073741826 1073741828 1073741829 1073741833 1073741925 1073741926 1073741927 1073741928 1073741929 1073741930 1073741931 1073741932 1073742126

Hex 0x00000064 0x00000065 0x00000066 0x00000067 0x000000C0 0x000000C1 0x000000C2 0x000000C3 0x000000C4 0x000000FE 0x000000FF 0x00000100 0x00000101 0x00000102 0x00000103 0x00000104 0x00000105 0x00000106 0x00000107 0x00000108 0x00000109 0x0000010A 0x0000010B 0x0000010C 0x0000010D 0x0000010E 0x0000010F 0x00000110 0x00000111 0x00000112 0x40000001 0x40000002 0x40000004 0x40000005 0x40000009 0x40000065 0x40000066 0x40000067 0x40000068 0x40000069 0x4000006A 0x4000006B 0x4000006C 0x4000012E

3. táblázat – folytatás Name RXTempAppError RXPermAppError RXRejectAppError QueryFailed InvalidParams UnsupportedParameter InvalidParamLength MissingParam InvalidParam DeliveryFailure UnknownError ServiceTypeUnauthorized OperationProhibited ServiceTypeUnavailable ServiceTypeDenied InvalidDCS InvalidSrcAddrSubUnit InvalidDstAddrSubUnit InvalidBroadcastFreqInterval InvalidBroadcastAliasName InvalidBroadcastAreaFormat InvalidNumBroadcastAreas InvalidBroadcastContentType InvalidBroadcastMessageClass BroadcastSubmitFailed BroadcastQueryFailed BroadcastCancelFailed InvalidNumRepeatedBroadcasts InvalidBroadcastServiceGroup InvalidBroadcastChannelIndicator UnexpectedOperation SyntaxError ConnectionLost NoResponse OperationFailed IncorrectAccessType TooManyUsers LoginRefused InvalidWindowSize WindowingDisabled Barring InvalidSubaddr AliasAccountLoginRefused UserDataSyntaxError

1073742127

0x4000012F

InvalidUserData

1073742131 1073742133 1073742135

0x40000133 0x40000135 0x40000137

IncorrectProtocolId IncorrectReplyPath IncorrectCancelEnabledFlag

1073742137

0x40000139

IncorrectTariffClass

Dec

10

Description

Incorrect parameter combination Unsupported parameter error Cannot find information Parameter formatting error

Unexpected operation Syntax error Connection to MC lost No response from MC Requested operation failed Incorrect access type Too many users with this login ID Login refused by MC Invalid window size Windowing disabled Virtual SMS Center-based barring Invalid subaddr Alias account, login refused Syntax error in user data parameter Incorrect bin/head/normal user data parameter combination Incorrect PID parameter usage Incorrect reply path usage Incorrect cancel enabled parameter usage Incorrect tariff class parameter usage folytatás a következő oldalon


Dec 1073742138

Hex 0x4000013A

3. táblázat – folytatás Name IncorrectServiceDescription

1073742140

0x4000013C

IncorrectMessageType

1073742142 1073742143

0x4000013E 0x4000013F

IncorrectMoreMessagesFlag IncorrectOperationTimer

1073742144

0x40000140

IncorrectDialogueId

1073742145

0x40000141

IncorrectAlphaOriginator

1073742146

0x40000142

IncorrectAlphaOriginatorData

1073742224 1073742225 1073742325 1073742624 1073742625 1073742724

0x40000190 0x40000191 0x400001F5 0x40000320 0x40000321 0x40000384

IncorrectAddress IncorrectTimeStamp IncorrectMode ChangingPasswordFailed ChangingPasswordNotAllowed UnsupportedItemRequested

11

Description Incorrect service description parameter usage Incorrect message type parameter usage Incorrect MMs parameter usage Incorrect operation timer parameter usage Incorrect dialogue ID parameter usage Incorrect alpha originator address usage Invalid data for alpha numeric originator Incorrect address parameter usage Incorrect scts parameter usage Incorrect mode parameter usage Changing password failed Changing password not allowed Unsupported item requested

SMS Gateway v1.6.0 HTTPS interfész leírás v1.3

Recommend Documents