LINK Mobility Implementation Guide REST API SMS
A LINK Mobility szolgáltatást nyújt üzenetek kézbesítéséhez, mikrofizetésekhez és helyfüggő szolgáltatásokhoz. A platform átlátható, fehér címkével ellátott tartalomszerzőként és tranzakciós útválasztóként működik a szolgáltatók és az üzemeltetők között.
A LINK Mobility egy RESTful API-t biztosít, amellyel elérheti a LINK Mobility szolgáltatásait, például SMS-küldést. Ezt az API-t úgy tervezték, hogy könnyen használható legyen, és minden modern nyelvvel és keretrendszerrel kompatibilis. Az Ön által választott nyelv használatával az alkalmazás a Link Mobility REST API segítségével hatékony üzenetküldési és fizetési lehetőségeket valósíthat meg
© LINK Mobility, 10. március 2021
Jogi információk
A jelen dokumentumban közölt információk a Netsize kizárólagos tulajdonát és szerzői jogát képezik. Bizalmas és szigorúan tájékoztató jellegű. Nem kötelező érvényű, és előzetes értesítés nélkül változhat. Minden jogosulatlan közzététel vagy felhasználás jogellenesnek minősül.
A Netsize™ és a linkmobility™-t a francia, az EGK és a nemzetközi szellemi tulajdonjogok védik.
Az összes többi idézett védjegy a megfelelő tulajdonosok kizárólagos tulajdona.
Semmi sem értelmezhető úgy, mint amely a Netsize szabadalma, szerzői joga vagy védjegye alapján licencet vagy jogot biztosít.
NETSIZE
Société anonyme au capital de 5 478 070 euró
Siège social :62, avenue Emile Zola 92100 Boulogne – Franciaország
418 712 477 RCS Nanterre
http://www.LinkMobility.com
http://www.linkmobility.com
A dokumentum hatálya
Ez a dokumentum leírja, hogy a Szolgáltató hogyan használja a LINK Mobility REST API-t SMS-ekhez. A Szolgáltató szolgáltatásait megvalósító műszaki építészek és tervezők számára készült.
1. Alapvető használat
Nagyon egyszerű SMS-t küldeni. HTTP-kérést küld a LINK Mobility-nek, amelyet egyszerűen a web böngésző.
2. Funkcionális Overview
A LINK Mobility rendszer a következő alapvető funkciókat biztosítja az SMS-üzenetekhez:
Mobil terminált (MT) SMS üzenetek, például szöveges vagy bináris (pl. WAP Push) emelt és normál díjas üzenetek küldése.
Kézbesítési jelentések fogadása a beküldött MT üzenetekről.
Mobil eredetű (MO) SMS-ek fogadása, emelt és normál díjas.
Az SMS REST API szabványos MT SMS üzenetek küldésére szolgál.
Az API aszinkron módon küldi el az összes SMS-t, lehetővé téve olyan funkciókat, mint például:
„Tűz és felejt” – a Szolgáltató kiszámíthatóbb válaszidőt szeretne, és nem akarja megvárni az eredményt az Üzemeltetőtől.
Újrapróbálkozás funkció – A LINK Mobility újraküldi az üzenetet, ha a Kezelőnek átmeneti problémái vannak.
2.1 SMS üzenet küldése
Szolgáltató Netsize Consumer
- MT üzenet küldése
- Üzenet azonosítója
- SMS üzenet küldése
- Szállítási jelentés kézbesítése
- Szállítási jelentés küldése
Az SMS-üzenetek küldésének alapvető folyamata a következő:
A Szolgáltató a LINK Mobility rendszeren keresztül kér SMS üzenetet küldeni egy címzettnek.
Üzenetazonosítót küld vissza a Szolgáltató. Ez az azonosító használható például az üzenet és a megfelelő kézbesítési jelentés korrelálására.
A LINK Mobility kezeli az útválasztást, és kézbesíti az SMS-t a címzett Fogyasztónak.
Kézbesítési jelentés indul, pl. amikor az SMS üzenetet kézbesítik a Fogyasztó készülékére.
A kézbesítési jelentést megküldjük a Szolgáltatónak. A jelentés ugyanazt az üzenetazonosítót tartalmazza, mint a 2. lépésben.
Alternatív folyamat: Érvénytelen kérés
Ha a kérésben megadott paraméterek vagy felhasználói hitelesítő adatok érvénytelenek, hibaüzenetet küld a Szolgáltató. A hiba jelzi az elutasítás okát, és a folyamat véget ér. Nem küldenek vissza üzenetazonosítókat.
3. Végpont
Az SMS-erőforrás a következő elérési út használatával érhető el:
/restapi/v1/sms
Example URL
https://europe.ipx.com/restapi/v1/sms
A kapcsolat biztonsága érdekében a LINK Mobility REST API csak HTTPS-en keresztül érhető el.
A Link Mobility szervertanúsítványt a Thawte Server CA írja alá.
4. Műveletek
Az SMS szolgáltatás a következő műveleteket biztosítja:
| Név | Útvonal |
| Elküld | /restapi/v1/sms/send |
4.1 Küldés
A küldési művelet arra szolgál, hogy SMS-t küldjön egyetlen címzettnek.
Ez a művelet alapvető és haladó felhasználóknak egyaránt szól. A legegyszerűbb esetben csak a célcím és az üzenet szövege szükséges az SMS kézbesítéséhez. A LINK Mobility észleli az adatkódolási sémát, és szükség esetén automatikusan több üzenetrészre fűzi össze az üzenetet.
Haladó használat esetén a Szolgáltató opcionális paraméterekkel teljes körűen szabályozhatja az üzenet formázását, beleértve a felhasználói adatfejlécet is.
A Szolgáltató küldhet összefűzött üzeneteket, de a felhasználói adatok és a felhasználói adatok fejlécének előkészítését a Szolgáltatónak kell elvégeznie, és az üzenetet többszöri küldési kéréssel kell elküldeni a LINK Mobility felé.
5. Hitelesítés
A felhasználónevet és a jelszót a HTTP Basic Authentication Scheme használatával minden kérésben elküldik.
https://www.w3.org/Protocols/HTTP/1.0/spec.html#BasicAA
A hitelesítési adatok a HTTP-kérés engedélyezési fejlécében kerülnek elküldésre. Az ügyfél a fejléc mezőt az itt leírtak szerint állítja össze:
https://en.wikipedia.org/wiki/Basic_access_authentication#Client_side
Plample, ha a felhasználónév john, a changeme pedig a jelszó, akkor a kapott Authorization fejléc:
Engedélyezés: Alapvető am9objpjaGFuZ2VtZSA=
Tartalékként a felhasználónév és a jelszó megadható kérésparaméterként. Ez csak olyan ügyfelek számára ajánlott, amelyek nem támogatják az Alapszintű hitelesítést.
6. Kérelem benyújtása
6.1 Lekérdezési karakterlánc
A kérés paraméterei név/érték párokat tartalmazó lekérdezési karakterláncként kerülnek elküldésre. A lekérdezési karakterlánc százalékos kódolással (URL kódolás).
http://www.w3schools.com/tags/ref_urlencode.asp
Plample, Hello World! Hello+World%21-ként van kódolva.
6.2 Kötelező kérési paraméterek
| Név | Max hossz | Leírás |
| célCím | 40 | Az MSISDN, amelyre az SMS-t el kell küldeni, országkóddal kezdve. Voltample: 46123456789. Egyes piacokon (ahol a fogyasztói MSISDN-t el kell rejteni) ez az érték alfanumerikus álnév is lehet, „#” előtaggal. |
| üzenetSzöveg | 1600 | Az SMS üzenet tartalma. |
6.3 Választható kérési paraméterek (haladó használathoz)
| Név | Max hossz | Leírás |
| származási cím | 16 | A kimenő SMS-üzenet kiindulási címe. A kiinduló cím típusát az originatorTON paraméter határozza meg. A rövid szám maximális hossza 16. Az alfanumerikus küldő a GSM alapértelmezett ábécéjére korlátozódik, legfeljebb 11 karakter hosszúsággal. Az MSISDN küldő maximális hossza 15 (ugyanazt a formátumot használja, mint a destinationAddress elem). Kihagyható, ha az originatingAddress és az originatingTON értéket a rendszer választja ki. Ez a funkció piac- és konfigurációfüggő. A viselkedés a kezelői integrációtól függően változhat. |
| kezdeményezőTON | 1 | A kiindulási cím számtípusa (TON): 0 – Rövid szám 1 – Alfa-numerikus (maximális hossza 11) 2 – MSISDN Kihagyható, ha az originatingAddress és az originatingTON értéket a rendszer választja ki. Ez a funkció piac- és konfigurációfüggő. A viselkedés a kezelői integrációtól függően változhat. |
| userDataHeader | 280 | A felhasználói adatok fejléce a felhasználói adatokkal együtt legfeljebb 140, azaz hexadecimálisan 280 oktettet tartalmazhat. Ez a paraméter mindig hexadecimális kódolású. |
| DCS | 3 | Adatkódolási séma. A viselkedés a kezelői integrációtól függően változhat. |
| PID | 3 | Protokollazonosító. A viselkedés a kezelői integrációtól függően változhat. |
| relatívValidityTime | 6 | Relatív érvényességi idő másodpercben (a LINK Mobility-hez való benyújtás idejéhez viszonyítva). A maximális érték 604800 (7 nap), az alapértelmezett érték pedig 48 óra. A viselkedés a kezelői integrációtól függően változhat. |
| szállítási idő | 20 | Legidősebbamp mikor kell az SMS-t kézbesíteni (késett kézbesítési idő). Lásd a dátum és idő formátumáról szóló részt. |
| statusReportFlags | 1 | Jelentéskérés kézbesítése: 0 – Nincs kézbesítési jelentés (alapértelmezett) 1 – Szállítási jelentést kértek 9 – Szerver kézbesítési jelentés kért (a LINK Mobility nem továbbítja a jelentést a Szolgáltatónak, hanem elérhetővé teszi jelentésekben stb.) |
| campaignName | 50 | A LINK Mobility tranzakciók tagged ezzel a névvel. A tranzakciók csoportosítására szolgál a Link Mobility jelentésekben. |
| maxConcatenatedMessages | 1 | 1 és 10 közötti érték, amely meghatározza, hogy hány összefűzött üzenet engedélyezett. Az alapértelmezett a 3. |
| correlationId | 100 | A Szolgáltató által megadott azonosító, amely a kézbesítési jelentésben is megjelenik. |
| felhasználónév | 100 | A HTTP alapszintű hitelesítés alternatívájaként szolgál. |
| jelszó | 100 | A HTTP alapszintű hitelesítés alternatívájaként szolgál. |
6.4 HTTP-kérési módszerek
A maximális együttműködés érdekében az API támogatja a HTTP GET és a POST kérési metódusokat is. Más HTTP-módszerek nem engedélyezettek.
6.4.1 GET
A kódolt lekérdezési karakterlánc hozzáfűződik a URL.
KAP
https://europe.ipx.com/restapi/v1/sms/send?destinationAddress=461234
56789&messageText=Hello+World%21
Engedélyezés: Alapvető am9objpjaGFuZ2VtZSA=
6.4.2 POST
A kódolt lekérdezési karakterlánc a HTTP-kérés üzenetének törzsében kerül elküldésre. A tartalom típusa: application/x-www-form-urlkódolt.
POST https://europe.ipx.com/restapi/v1/sms/send
Házigazda: europe.ipx.com
Tartalom típusa: jelentkezés/x-www-űrlap-urlkódolt
Engedélyezés: Alapvető am9objpjaGFuZ2VtZSA=
Tartalom-hossz: 57
destinationAddress=46123456789&messageText=Hello+World%21
6.5 Dátum és idő
A REST API dátumot és időt képviselő paraméterei mindig UTC időzónában (Coordinated Universal Time) vannak. Timestamps karakterláncként vannak ábrázolva pontosan ebben a formátumban:
2017-04-25T23:20:50Z
Ez 20 perc 50 másodpercet jelent 23. április 25-i 2017. óra után UTC-ben.
7. Válaszüzenet
Egy kérés üzenet fogadása és értelmezése után az API HTTP válaszüzenettel válaszol.
7.1 HTTP állapotkód
A REST API mindig 200 OK HTTP-állapotkódot ad vissza a feldolgozott kérésekhez. Az üzenet törzse egy válaszCode paramétert tartalmaz, amely a pontos eredmény meghatározására szolgál.
7.2 Az üzenet törzse
Az üzenet törzse a kérelem eredményét leíró JSON-ból áll.
http://json.org/
A Link Mobility JSON megfelel a Google JSON Style Guide előírásainak.
https://google.github.io/styleguide/jsoncstyleguide.xml
7.3 Válaszparaméterek
| Név | Max hossz | Leírás |
| válaszkód | 3 | A 0 a sikeres tranzakciót jelzi. |
| válaszüzenet | 255 | Válasz szöveges leírása, pl. hibaszöveg. |
| timestamp | 20 | Dátum és idő, amikor a LINK Mobility feldolgozta a kérést. (Lásd a dátum/idő formátum című részt). |
| traceId | 36 | Link Mobility belső azonosító. Támogatásra és hibaelhárításra használják. |
| üzenetazonosítók | 10 x 36 | A LINK Mobility egyedi üzenetazonosítók tömbje minden sikeres üzenethez (több üzenetazonosítót ad vissza, ha az üzenet össze van kapcsolva). Meghibásodás esetén kihagyva. |
7.4 Plample válaszokat
Siker
HTTP/1.1 200 OK
Tartalom típusa: Application/json
Tartalom-hossz: 144
Dátum: 15. szeptember 2016., csütörtök, 13:20:31 GMT
{"responseCode":0,"responseMessage":"Siker","timestamp”:”2016-09-15T13:20:31Z”, “traceId”:”f678d30879fd4adc25f2″,”messageIds”:[“1-4850879008”]}
Itt van ugyanaz a JSON, amely az olvashatóság érdekében formázott:
{
“válaszkód":0,
“válaszüzenet":"Siker",
“timestamp“:”2016-0915T13:20:31Z”,
“traceId“:”f678d30879fd4adc25f2”,
“üzenetazonosítók":["1-4850879008"] }
Hiba
HTTP/1.1 200 OK
Tartalom típusa: Application/json
Tartalom-hossz: 148
Dátum: 15. szeptember 2016., csütörtök, 13:20:31 GMT
{"responseCode":1,"responseMessage":" Érvénytelen bejelentkezés vagy nem engedélyezett API-használat","timestamp”:”2016-09-15T13:20:31Z”,”traceId”:”f678d30879fd4adc25f2″}
Siker
HTTP/1.1 200 OK
Tartalom típusa: Application/json
Tartalom-hossz: 144
Dátum: 15. szeptember 2016., csütörtök, 13:20:31 GMT
{"responseCode":0,"responseMessage":"Siker","timestamp”:”2016-09-15T13:20:31Z”, “traceId”:”f678d30879fd4adc25f2″,”messageIds”:[“1-4850879008”]}
Itt van ugyanaz a JSON, amely az olvashatóság érdekében formázott:
{
“válaszkód":0,
“válaszüzenet":"Siker",
“timestamp“:”2016-0915T13:20:31Z”,
“traceId“:”f678d30879fd4adc25f2”,
“üzenetazonosítók":["1-4850879008"] }
Hiba
HTTP/1.1 200 OK
Tartalom típusa: Application/json
Tartalom-hossz: 148
Dátum: 15. szeptember 2016., csütörtök, 13:20:31 GMT
{"responseCode":1,"responseMessage":" Érvénytelen bejelentkezés vagy nem engedélyezett API-használat","timestamp”:”2016-09-15T13:20:31Z”,”traceId”:”f678d30879fd4adc25f2″}
7.5 Válaszkódok
A következő válaszkódok adhatók vissza a küldési válaszban:
| Kód | Szöveg | Leírás |
| 0 | Siker | Sikeresen végrehajtva. |
| 1 | Érvénytelen bejelentkezés vagy jogosulatlan API-használat | Helytelen felhasználónév vagy jelszó, vagy a szolgáltatót letiltja a LINK Mobility. |
| 2 | A fogyasztót a Link Mobility blokkolja | A Fogyasztót a LINK Mobility blokkolja. |
| 3 | A műveletet nem a LINK Mobility biztosítja | A művelet le van tiltva a Szolgáltató számára. |
| 4 | A fogyasztó ismeretlen a LINK Mobility számára | A Fogyasztó ismeretlen a LINK Mobility számára. Vagy ha álnevet használtak a kérésben; alias nem található. |
| 5 | A fogyasztó letiltotta ezt a szolgáltatást a LINK Mobilitásban | A Fogyasztó letiltotta ezt a szolgáltatást a LINK Mobilitásban. |
| 6 | A kiindulási cím nem támogatott | A kiindulási cím nem támogatott. |
| 7 | Az alfa-eredetű címet a fiók nem támogatja | Az alfa-eredetű címet a fiók nem támogatja. |
| 8 | Az MSISDN származási címe nem támogatott | Az MSISDN kiindulási címe nem támogatott. |
| 9 | A kiterjesztett GSM nem támogatott | A kiterjesztett GSM nem támogatott. |
| 10 | Unicode nem támogatott | Unicode nem támogatott. |
| 11 | Az állapotjelentés nem támogatott | Az állapotjelentés nem támogatott. |
| 12 | A szükséges képesség nem támogatott | Az üzenet küldéséhez szükséges (a fentiektől eltérő) képesség nem támogatott. |
| 13 | Túllépte a tartalomszolgáltató maximális szabályozási sebességét | A Szolgáltató túl gyorsan küldi az SMS-eket a LINK Mobility részére. |
| 14 | A fiók nem támogatja a protokollazonosítót | A protokollazonosító nem támogatott. |
| 15 | Üzenetösszefűzési korlát túllépve | Az összefűzött üzenetek száma meghaladja a kért maximális számot. |
| 16 | Az üzenetet nem lehet továbbítani. | LINK A mobilitás nem tudta továbbítani az üzenetet. |
| 17 | Tiltott időszak | Az időtartam alatt nem küldhet üzenetet |
| 18 | Túl alacsony egyenleg a szolgáltatói számlán | A szolgáltató le van tiltva a túl alacsony egyenleg miatt |
| 50 | Részleges siker | Részleges siker, ha SMS-t küld több címzettnek. |
| 99 | Belső szerver hiba | Egyéb Link Mobility hiba, további információért forduljon a LINK Mobility ügyfélszolgálatához. |
| 100 | Érvénytelen célcím | A célcím (MSISDN vagy álnév) érvénytelen. |
| 102 | Érvénytelen hivatkozott (linkelt) azonosító | A referenciaazonosító érvénytelen, lehet, hogy a referenciaazonosító már használatban van, túl régi vagy ismeretlen. |
| 103 | Érvénytelen fióknév | A fióknév érvénytelen. |
| 105 | Érvénytelen szolgáltatási metaadatok | A szolgáltatás metaadatai érvénytelenek. |
| 106 | Érvénytelen kiindulási cím | A kiindulási cím érvénytelen. |
| 107 | Érvénytelen alfanumerikus származási cím | Az alfanumerikus kiindulási cím érvénytelen. |
| 108 | Érvénytelen érvényességi idő | Az érvényességi idő érvénytelen. |
| 109 | Érvénytelen szállítási idő | A szállítási idő érvénytelen. |
| 110 | Érvénytelen üzenettartalom/felhasználói adatok | A felhasználói adatok, azaz az SMS üzenet érvénytelen. |
| 111 | Érvénytelen üzenethossz | Az SMS üzenet hossza érvénytelen. |
| 112 | Érvénytelen felhasználói adatfejléc | A felhasználói adatok fejléce érvénytelen. |
| 113 | Érvénytelen adatkódolási séma | A DCS érvénytelen. |
| 114 | Érvénytelen protokollazonosító | A PID érvénytelen. |
| 115 | Érvénytelen állapotjelentés-jelzők | Az állapotjelentés jelzői érvénytelenek. |
| 116 | Érvénytelen TON | Az eredeti TON érvénytelen. |
| 117 | Érvénytelen campaign név | A campaz aign neve érvénytelen. |
| 120 | Érvénytelen az összefűzött üzenetek maximális számának korlátja | Az összefűzött üzenetek maximális száma érvénytelen. |
| 121 | Érvénytelen msisdn származási cím | Az MSISDN eredeti címe érvénytelen. |
| 122 | Érvénytelen korrelációs azonosító | A korrelációs azonosító érvénytelen. |
8. Választható szolgáltatások
8.1 MSISDN javítás
Az MSISDN-javítás egy opcionális szolgáltatás, amelyet kérésre a LINK Mobility támogatása engedélyezhet.
Ez a funkció kijavítja a célcímeket, és a szükséges E.164 formátumhoz igazítja azokat. A formátumkorrekción kívül a rendszer piacspecifikus funkciókat is végrehajthat, mint például a nemzetközi francia számok lefordítása a DOM-TOM (départements et territoires d'outre-mer) számok helyesbítésére, ha szükséges.
Az alábbiakban számos exampkevesebb korrekció:
| Elküldött célcím | Javított célcím |
| +46(0)702233445 | 46702233445 |
| (0046)72233445 | 46702233445 |
| +460702233445 | 46702233445 |
| 46(0)702233445 | 46702233445 |
| 46070-2233445 | 46702233445 |
| 0046702233445 | 46702233445 |
| +46(0)702233445aaa | 46702233445 |
| 336005199999 | 2626005199999 (A francia szám DOM-TOM számra fordítva) |
Ezenkívül lehetséges nemzeti telefonszámok engedélyezése egy kiválasztott piacon. Ha ez a funkció engedélyezve van, minden más piacra vonatkozó nemzetközi számot el kell küldeni egy kezdeti „+” jellel, hogy megkülönböztessük őket a kiválasztott piactól.
Az alábbiakban több exampSvédország (46-os országkód) a nemzeti számok alapértelmezett piacaként végzett korrekciók csökkentése.
| Elküldött célcím | Javított célcím |
| 0702233445 | 46702233445 |
| 070-2233 445 | 46702233445 |
| 070.2233.4455 | 46702233445 |
| 460702233445 | 46702233445 |
| +460702233445 | 46702233445 |
| +458022334455 | 458022334455 |
| 45802233445 | Érvénytelen, mert hiányzik a „+” jel |
Ne feledje, hogy a javított MSISDN-t a LINK Mobility fogja használni, és ez visszakerül a kézbesítési jelentésekben.
További információért forduljon a LINK Mobility ügyfélszolgálatához.
8.2 Karaktercsere
A karaktercsere egy opcionális funkció, amelyet kérésre a LINK Mobility támogatása engedélyezhet.
Ez a funkció lefordítja a felhasználói adatokban (SMS-szöveg) a nem GSM ábécé karaktereit egyenértékű GSM ábécé karakterekre, ha a DCS beállítása „GSM” (17). PlampA „Seqüência de teste em Português” szót „Seqüencia de teste em Portugues”-ra fordítják.
9. Szállítási jelentések
A Szolgáltató az elküldött MT üzenetekről SMS-kézbesítési jelentést vagy kézbesítési értesítést kérhet, amennyiben biztosított. Ezek a jelentések akkor indulnak el az Üzemeltető SMSC-ben, amikor az MT üzenetet kézbesítik a megcélzott Fogyasztóhoz, vagy törölték, pl. lejárt, vagy valamilyen okból nem irányítható.
A Szolgáltató csak az SMS üzenet végleges állapotát jelenti, azaz kézbesítette vagy törölte. MT üzenetenként csak egy jelentés készül. A törölt állapot esetén előfordulhat, hogy egy okkód érvényesül. Ez az okkód határozza meg az SMS-üzenet kézbesítésének elmaradásának okát.
A jelentések a LINK Mobility-n keresztül kerülnek továbbításra, és a HTTP protokoll használatával elküldik a Szolgáltatónak.
A jelentések fogadásához a Szolgáltatónak plampegy Java Servlet vagy egy ASP.NET oldal. Mindkettő HTTP GET vagy POST kéréseket kap.
Paraméterek
A kérelem a következő paramétereket tartalmazza:
| Paraméter | Írja be | M/O/I* | Alapértelmezett érték | Max hossz | Leírás |
| MessageId | húr | M | – | 22 | Annak az MT-üzenetnek az üzenetazonosítója, amelynek ez a jelentés megfelel. |
| DestinationAddress | húr | M | – | 40 | A Fogyasztó MSISDN-je, azaz az eredeti MT üzenet célcíme. |
| ÁllapotKód | egész szám | M | 1 | Az állapotkód az MT üzenet állapotát jelzi. Az alkalmazható állapotkódok: 0 – kézbesítve 2 – Törölve (az okkód érvényes) |
|
| TimeStamp | húr | M | – | 20 | Idő, amely jelzi, hogy a LINK Mobility mikor kapta meg a kézbesítési jelentést. A legidősebb időzónaamp CET vagy CEST (az EU-ban meghatározott nyári időszámítással). Formátum: ééééhhhn ÓÓ:pp:pp. |
| Operátor | húr | M | – | 100 | Az SMS küldésekor használt Üzemeltető neve vagy az SMS küldésekor használt fióknév. Az elérhető operátorok listáját a LINK Mobility támogatás biztosítja. |
| ReasonCode | egész szám | O | – | 3 | Az ok kódja jelzi, hogy az üzenet miért lett törölve. Az alkalmazható okkódok a következők: 100 – Lejárt 101 – Elutasítva 102 – Formázási hiba 103 – Egyéb hiba 110 – Előfizető ismeretlen 111 – Előfizető tiltva 112 – Az előfizető nincs biztosítva 113 – Az előfizető nem elérhető 120 – SMSC hiba 121 – SMSC torlódás 122 – SMSC roaming 130 – Kézibeszélő hiba 131 – A kézibeszélő memóriája túllépve A viselkedés a kezelői integrációtól függően változhat. |
| OperatorTimeStamp | húr | O | – | 20 | Idő, amely jelzi, hogy a jelentés mikor indult az Üzemeltető SMSC-jében (ha az Üzemeltető megadta). A legidősebb időzónaamp CET vagy CEST (az EU-ban meghatározott nyári időszámítással). Formátum: ééééhhhn ÓÓ:pp:pp. |
| ÁllapotSzöveg | húr | O | – | 255 | Helyőrző az Üzemeltetőtől származó további információkhoz, pl. az állapot/ok egyértelmű szöveges leírása. A viselkedés a kezelői integrációtól függően változhat. |
| CorrelationId | húr | O | – | 100 | A SendRequestben vagy a SendTextRequestben megadott korrelációs azonosító. |
| OperatorNetworkCode | egész szám | O | – | 6 | Az Üzemeltető mobilhálózati kódja (MCC + MNC). |
* M = kötelező, O = opcionális, I = figyelmen kívül hagyva.
A Szolgáltatónak biztosítania kell a LINK Mobility-t a céllal URL kézbesítési jelentésekhez (opcionálisan a hitelesítési adatokkal is az alap HTTP-hitelesítéshez). A Szolgáltató kiválaszthatja, hogy melyik HTTP-módszert használja:
HTTP POST (ajánlott)
HTTP GET.
Example HTTP GET használatával (sikeresen kézbesítve):
https://user:password@www.serviceprovider.com/receivereport?%20MessageId=122&DestinationAddress=46762050312&Operator=Vodafone&TimeStamp=20100401%2007%3A47%3A44&StatusCode=0
Example HTTP GET használatával (nincs kézbesítve, az Üzemeltető megadta a timestamp az eseményhez):
A paraméterek a következők URL kódolt.
Karakter kódolás:
A Szolgáltató választhat, hogy melyik preferált karakterkódolást használja:
UTF-8 (ajánlott)
ISO-8859-1.
9.1 Szolgáltatói visszaigazolás
A Szolgáltató minden kézbesítési jelentést köteles tudomásul venni. A nyugtázás lehet pozitív, azaz a kézbesítési jelentés sikeresen érkezett, vagy negatív, azaz sikertelen.
Megjegyzés: A LINK Mobility 30 másodperces olvasási időkorláttal rendelkezik a kézbesítési jelentések nyugtázásához. Az időtúllépés a kézbesítés újrapróbálkozását (ha az újrapróbálkozás engedélyezve van) vagy a kézbesítés törlését (ha az újrapróbálkozás le van tiltva) indítja el. Ez azt jelenti, hogy a Szolgáltató alkalmazásnak gyors válaszidőt kell biztosítania, különösen nagy terhelés esetén.
A LINK Mobility felé történő kézbesítési jelentés feldolgozása előtt erősen ajánlott tudomásul venni.
A pozitív és negatív nyugtázás szabálya a következő:
Pozitív visszaigazolás, ACK, kézbesítési jelentés kézbesítve:
HTTP 200 tartomány válaszkódja a következő XML formátumú tartalommal kombinálva:
Negatív nyugtázás, NAK, kézbesítési jelentés nem kézbesítve:
Bármilyen, a pozitív visszaigazoláson kívüli válasz, plample, negatív nyugtázást vált ki bármely HTTP hibakód vagy a következő XML-tartalom:
Az XML-tartalom a LINK Mobility újrapróbálkozási mechanizmus vezérlésére használható. A NAK újrapróbálkozást okoz, ha engedélyezve van. Az újrapróbálkozási mechanizmushoz nem konfigurált szolgáltatók számára az XML-tartalom nem kötelező.
Az alábbiakban egy HTTP POST kérés és válasz látható, plampa Szolgáltatónak kézbesített kézbesítési jelentésről:
HTTP kérés:
POST /context/app HTTP/1.1
Tartalom típusa: jelentkezés/x-www-űrlap-urlkódolt;charset=utf-8
Host: szerver:port
Tartalom-hossz: xx
MessageId=213123213&DestinationAddress=46762050312&Operator=Telia& OperatorTimeStamp=20130607%2010%3A45%3A00&TimeStamp=20130607%2010%3A 45%3A02&StatusCode=0
HTTP válasz:
HTTP/1.1 200 OK
Tartalom típusa: szöveges/sima
9.2 Próbálja újra
A LINK Mobility rendszer újrapróbálkozhat a sikertelen, azaz nem nyugtázott kézbesítési jelentéskézbesítések esetén. A Szolgáltató kiválaszthatja a kívánt újrapróbálkozási viselkedést:
Nincs újrapróbálkozás (alapértelmezett) – az üzenetet a rendszer elveti, ha a csatlakozási kísérlet sikertelen, olvasási időtúllépés vagy bármilyen HTTP hibakód esetén.
Próbálja újra – az üzenet minden típusú csatlakozási probléma, olvasási időtúllépés vagy negatív nyugtázás esetén újra elküldésre kerül.
Ha a NAK újrapróbálkozása engedélyezve van, fontos megérteni, hogy mely forgatókönyvek generálnak újrapróbálkozási kísérletet a LINK Mobility szolgáltatásból, és hogyan működik az újrapróbálkozás. Minden Szolgáltatónak saját újrapróbálkozási sora van, ahol az üzenetek az üzenetidők szerint vannak rendezveamp. A Link Mobility mindig a régebbi üzeneteket igyekszik először kézbesíteni, annak ellenére, hogy a Szolgáltatóhoz eljuttatott üzenetek egyedi sorrendje nem garantált. Az üzenetek újrapróbálkozási sorból való kidobásának fő oka két ok egyike: vagy az üzenet TTL lejár, vagy (elméletileg) az újrapróbálkozási sor megtelik. A TTL Operátor- és fiókfüggő, azaz változhat az Üzemeltetőtől és/vagy az üzenet típusától függően, pl. emelt díjas SMS vagy normál díjas SMS üzenet.
Az újrapróbálkozás engedélyezésével rendelkező szolgáltatóknak ellenőrizniük kell az MT üzenet egyedi azonosítóját, hogy megbizonyosodjanak arról, hogy az üzenetet még nem kapták meg.
Fontos, hogy a Szolgáltató betartsa ezeket az egyszerű szabályokat, amikor hiba történik a kézbesítési jelentés feldolgozása során, ha a hiba oka: Ideiglenes, pl. nem elérhető adatbázis, NAK-t kell visszaküldeni. LINK A Mobility újraküldi az üzenetet.
Az állandó és az újrapróbálkozás valószínűleg ugyanazt a problémát okozza, ezért egy ACK-t kell visszaadni. Plample, amikor az üzenetet nem sikerült megfelelően értelmezni, vagy váratlan futásidejű hibát okozott.
A megfelelő cselekvés biztosítja, hogy a kézbesítési jelentés ismételt újraküldése ne okozzon blokkolást vagy átviteli csökkenést.
10. Végrehajtási tippek
1. Lehetőség van a saját web böngészőt, hogy kérelmeket küldjön el az API-nak. Ez nagyon egyszerűvé teszi a szolgáltatások felfedezését és értékelését fejlesztői eszközök nélkül.
2. A Chrome vagy a Firefox egy olyan bővítménnyel együtt ajánlott, mint a JSONView szép formázott JSON megjelenítéséhez.
3. A SoapUI-t használtuk a POST, az alapszintű hitelesítés tesztelésére, valamint a nyers HTTP kérés- és válaszüzenetek vizsgálatára.
4. A cURL eszköz hasznos POST-kérések alapszintű hitelesítéssel történő elküldéséhez. Lásd plample lent.
curl POST \
-H „Tartalom-típus: Application/x-www-form-urlkódolva” \
-H “Engedélyezés: Alap am9objpjaGFuZ2VtZSA=” \
https://europe.ipx.com/restapi/v1/sms/send \
–data “destinationAddress=46123456789&messageText=Hello+World%21”
_______________
A személyre szabott kommunikáció átalakítása
Dokumentumok / Források
 |
LINK Mobility Implementation Guide REST API SMS [pdf] Felhasználói útmutató Mobilitási megvalósítási útmutató REST API SMS, mobilitás, megvalósítási útmutató REST API SMS, REST API SMS, API SMS, SMS |
