LINK Mobility Implementation Guide REST API SMS
LINK Mobility poskytuje službu pro doručování zpráv, mikroplatby a služby založené na poloze. Platforma funguje jako transparentní, white-label obsahový akvizitor a transakční směrovač mezi poskytovateli služeb a operátory.
LINK Mobility poskytuje RESTful API, které lze použít pro přístup ke službám LINK Mobility, jako je odesílání SMS. Toto API je navrženo tak, aby se snadno používalo a bylo kompatibilní se všemi moderními jazyky a frameworky. Pomocí jazyka dle vašeho výběru může vaše aplikace používat Link Mobility REST API k implementaci výkonných funkcí pro zasílání zpráv a platby
© LINK Mobility, 10. března 2021
Právní informace
Informace uvedené v tomto dokumentu jsou výhradním vlastnictvím a autorským právem společnosti Netsize. Je důvěrný a je určen pro čistě informativní použití. Není závazný a může podléhat změnám bez upozornění. Jakékoli neoprávněné zveřejnění nebo použití bude považováno za nezákonné.
Netsize™ a linkmobility™ jsou chráněny francouzskými zákony, zákony EHS a mezinárodními zákony na ochranu duševního vlastnictví.
Všechny ostatní uvedené ochranné známky jsou výhradním vlastnictvím jejich příslušných vlastníků.
Nic zde obsaženého nelze vykládat jako udělování jakékoli licence nebo práva v rámci patentu, autorských práv nebo ochranné známky společnosti Netsize.
NETSIZE
Société anonyme au capital de 5 478 070 eur
Siège social :62, avenue Emile Zola92100 Boulogne – Francie
418 712 477 RCS Nanterre
http://www.LinkMobility.com
http://www.linkmobility.com
Rozsah dokumentu
Tento dokument popisuje, jak poskytovatel služeb používá LINK Mobility REST API pro SMS. Je určen pro technické architekty a projektanty, kteří realizují služby Poskytovatele služeb.
1. Základní použití
Odeslání SMS je velmi snadné. Odešlete požadavek HTTP do LINK Mobility, který lze provést pouze pomocí a web prohlížeč.
2. Funkční Overview
Systém LINK Mobility poskytuje následující základní funkce pro SMS zprávy:
Odesílání zpráv SMS s mobilním zakončením (MT), jako jsou textové nebo binární (např. WAP Push) zprávy s prémiovou a standardní sazbou.
Příjem zpráv o doručení zaslaných zpráv MT.
Příjem mobilních SMS zpráv (MO), prémiová a standardní sazba.
SMS REST API je určeno pro odesílání standardních MT SMS zpráv.
Rozhraní API odesílá všechny SMS zprávy asynchronně, což umožňuje funkce jako:
„Fire-and-forget“ – Poskytovatel služby chce mít předvídatelnější doby odezvy a nechce čekat na výsledek od Provozovatele.
Funkce opakování – LINK Mobility odešle zprávu znovu, pokud má operátor dočasné problémy.
2.1 Odeslání SMS zprávy
Poskytovatel služeb Netsize Consumer
- Odeslat zprávu MT
- ID zpětné zprávy
- Odeslat SMS zprávu
- Doručte zprávu o doručení
- Odeslat zprávu o doručení
Základní postup odesílání SMS zpráv je popsán následovně:
Poskytovatel služeb požádá o zaslání SMS zprávy příjemci prostřednictvím systému LINK Mobility.
ID zprávy se vrátí poskytovateli služeb. Toto ID lze použít např. pro korelaci zprávy se správnou zprávou o doručení.
LINK Mobility zpracovává směrování a doručuje SMS zprávu adresovanému spotřebiteli.
Hlášení o doručení se spustí, např. při doručení SMS zprávy na zařízení Zákazníka.
Zpráva o doručení je zaslána Poskytovateli služby. Zpráva obsahuje stejné ID zprávy, jaké bylo vráceno v kroku 2.
Alternativní postup: Neplatný požadavek
Pokud jsou zadané parametry nebo přihlašovací údaje uživatele v požadavku neplatné, bude poskytovateli služeb vrácena chyba. Chyba označuje důvod odmítnutí a tok končí. Nejsou vrácena žádná ID zpráv.
3. Koncový bod
Ke zdroji SMS se přistupuje pomocí cesty:
/restapi/v1/sms
Example URL
https://europe.ipx.com/restapi/v1/sms
Pro zabezpečení připojení je LINK Mobility REST API přístupné pouze přes HTTPS.
Certifikát serveru Link Mobility je podepsán Thawte Server CA.
4. Operace
Služba SMS poskytuje následující operace:
| Jméno | Cesta |
| Poslat | /restapi/v1/sms/odeslat |
4.1 Odeslat
Operace odeslání se používá k odeslání SMS jednomu příjemci.
Tato operace je určena pro základní i pokročilé uživatele. V nejjednodušším případě je k doručení SMS potřeba pouze cílová adresa a text zprávy. LINK Mobility detekuje schéma kódování dat a v případě potřeby provede automatické zřetězení zprávy do více částí zprávy.
Pro pokročilé použití může poskytovatel služeb použít volitelné parametry pro úplnou kontrolu formátování zprávy včetně hlavičky uživatelských dat.
Poskytovatel služby může posílat zřetězené zprávy, ale příprava uživatelských dat a hlavičky uživatelských dat musí být provedena poskytovatelem služby a zpráva musí být odeslána prostřednictvím vícenásobných požadavků na odeslání směrem k LINK Mobility.
5. Autentizace
Uživatelské jméno a heslo jsou odesílány v každém požadavku pomocí schématu HTTP Basic Authentication Scheme.
https://www.w3.org/Protocols/HTTP/1.0/spec.html#BasicAA
Pověření se odesílají v hlavičce Authorization v požadavku HTTP. Klient vytvoří pole záhlaví, jak je popsáno zde:
https://en.wikipedia.org/wiki/Basic_access_authentication#Client_side
Napřample, pokud je uživatelské jméno john a changeme je heslo, výsledná autorizační hlavička je:
Oprávnění: Základní am9objpjaGFuZ2VtZSA=
Jako záložní možnost lze zadat uživatelské jméno a heslo jako parametry požadavku. Toto je doporučeno pouze pro klienty, kteří nepodporují Basic Auth.
6. Odeslání žádosti
6.1 Řetězec dotazu
Parametry požadavku jsou odeslány jako řetězec dotazu obsahující dvojice název/hodnota. Řetězec dotazu je zakódován pomocí Percent Encoding (URL kódování).
http://www.w3schools.com/tags/ref_urlencode.asp
Napřample, Ahoj světe! je zakódováno jako Hello+World%21.
6.2 Parametry povinného požadavku
| Jméno | Maximální délka | Popis |
| cílová adresa | 40 | MSISDN, na které má být SMS zpráva odeslána, počínaje kódem země. Přample: 46123456789. Na některých trzích (kde musí být MSISDN spotřebitele zatemněno) může být touto hodnotou také alfanumerický alias s předponou „#“. |
| text zprávy | 1600 | Obsah SMS zprávy. |
6.3 Volitelné parametry požadavku (pro pokročilé použití)
| Jméno | Maximální délka | Popis |
| originatingAddress | 16 | Původní adresa pro odchozí SMS zprávu. Typ původní adresy je definován parametrem originatorTON. Maximální délka krátkého čísla je 16. Alfanumerický odesílatel je omezen na výchozí abecedu GSM s maximální délkou 11 znaků. Maximální délka odesílatele MSISDN je 15 (s použitím stejného formátu jako prvek destinationAddress). Může být vynecháno, když originatingAddress a originatingTON jsou vybrány systémem. Tato funkce je závislá na trhu a konfiguraci. Chování se může lišit podle integrace operátora. |
| původceTON | 1 | Typ čísla výchozí adresy (TON): 0 – Krátké číslo 1 – Alfanumerická (maximální délka 11) 2 – MSISDN Lze vynechat, když originatingAdresa a originatingTON budou vybrány systémem. Tato funkce je závislá na trhu a konfiguraci. Chování se může lišit podle integrace operátora. |
| userDataHeader | 280 | Záhlaví uživatelských dat spolu s uživatelskými daty může obsahovat až 140, tj. 280 při hex-kódování, oktetů. Tento parametr je vždy hex-kódován. |
| DCS | 3 | Schéma kódování dat. Chování se může lišit podle integrace operátora. |
| PID | 3 | ID protokolu. Chování se může lišit podle integrace operátora. |
| relativníValidityTime | 6 | Relativní doba platnosti v sekundách (vztažená k době odeslání do LINK Mobility). Maximální hodnota je 604800 (7 dní) a výchozí hodnota je 48 hodin. Chování se může lišit podle integrace operátora. |
| dodací lhůta | 20 | Časamp kdy má být SMS zpráva doručena (zpožděná doba doručení). Viz část o formátu data a času. |
| statusReportFlags | 1 | Doručit žádost o zprávu: 0 – Žádná zpráva o doručení (výchozí) 1 – Požadovaná zpráva o doručení 9 – Požadovaná zpráva o doručení serveru (LINK Mobility nepřesílá zprávu poskytovateli služeb, ale zpřístupňuje ji ve zprávách atd.) |
| campaignName | 50 | Transakce LINK Mobility jsou tags tímto jménem. Používá se ke seskupování transakcí v sestavách Link Mobility. |
| maxConcatenatedMessages | 1 | Hodnota mezi 1 a 10, která definuje, kolik zřetězených zpráv je povoleno. Výchozí hodnota je 3. |
| correlationId | 100 | ID poskytnuté poskytovatelem služeb, které bude uvedeno ve zprávě o doručení. |
| uživatelské jméno | 100 | Poskytuje se jako alternativa k základnímu ověřování HTTP. |
| heslo | 100 | Poskytuje se jako alternativa k základnímu ověřování HTTP. |
6.4 Metody požadavku HTTP
Pro maximální interoperabilitu rozhraní API podporuje metody požadavku HTTP GET i POST. Žádné jiné metody HTTP nejsou povoleny.
6.4.1 ZÍSKAT
Kódovaný řetězec dotazu je připojen k URL.
ZÍSKAT
https://europe.ipx.com/restapi/v1/sms/send?destinationAddress=461234
56789&messageText=Ahoj+svět%21
Oprávnění: Základní am9objpjaGFuZ2VtZSA=
6.4.2 PŘÍSPĚVEK
Kódovaný řetězec dotazu je odeslán v těle zprávy požadavku HTTP. Content-Type je application/x-www-form-urlzakódované.
ZVEŘEJNIT https://europe.ipx.com/restapi/v1/sms/send
Hostitel: europe.ipx.com
Typ obsahu: application / x-www-form-urlzakódované
Oprávnění: Základní am9objpjaGFuZ2VtZSA=
Obsah - délka: 57
destinationAddress=46123456789&messageText=Hello+World%21
6.5 Datum a čas
Parametry v REST API představující datum a čas jsou vždy v časovém pásmu UTC (Coordinated Universal Time). Timestamps jsou reprezentovány jako řetězec v tomto přesném formátu:
2017-04-25T23:20:50Z
To představuje 20 minut a 50 sekund po 23. hodině 25. dubna 2017 v UTC.
7. Zpráva s odpovědí
Po přijetí a interpretaci zprávy požadavku API odpoví zprávou HTTP.
7.1 Stavový kód HTTP
REST API vždy vrací stavový kód HTTP 200 OK pro zpracované požadavky. Tělo zprávy obsahuje parametr responseCode, který se používá k určení přesného výsledku.
7.2 Tělo zprávy
Tělo zprávy se skládá z JSON popisujícího výsledek požadavku.
http://json.org/
Link Mobility JSON je v souladu s Google JSON Style Guide.
https://google.github.io/styleguide/jsoncstyleguide.xml
7.3 Parametry odezvy
| Jméno | Maximální délka | Popis |
| responseCode | 3 | 0 znamená úspěšnou transakci. |
| responseMessage | 255 | Textový popis odpovědi, např. text chyby. |
| timestamp | 20 | Datum a čas, kdy LINK Mobility zpracovala požadavek. (Viz část Formát data/času). |
| traceId | 36 | Interní identifikátor Link Mobility. Používá se pro podporu a řešení problémů. |
| messageIds | 10 x 36 | Pole jedinečných ID zpráv LINK Mobility pro každou úspěšnou zprávu (pokud je zpráva zřetězena, vrátí se více ID zpráv). V případě poruchy vynecháno. |
7.4 Přample odpovědi
Úspěch
HTTP/1.1 200 OK
Content-Type: application/json
Obsah - délka: 144
Datum: Čt, 15. září 2016 13:20:31 GMT
{“responseCode”:0,”responseMessage”:”Success”,”timestamp”:”2016-09-15T13:20:31Z”, “traceId”:”f678d30879fd4adc25f2″,”messageIds”:[“1-4850879008”]}
Zde je stejný JSON formátovaný pro čitelnost:
{
“responseCode“:0,
“responseMessage":"Úspěch",
“timestamp“:”2016-0915T13:20:31Z”,
“traceId“:”f678d30879fd4adc25f2”,
“messageIds“:[“1-4850879008”] }
Selhání
HTTP/1.1 200 OK
Content-Type: application/json
Obsah - délka: 148
Datum: Čt, 15. září 2016 13:20:31 GMT
{“responseCode”:1,”responseMessage”:” Neplatné přihlášení nebo neoprávněné použití API”,”timestamp”:”2016-09-15T13:20:31Z”,”traceId”:”f678d30879fd4adc25f2″}
Úspěch
HTTP/1.1 200 OK
Content-Type: application/json
Obsah - délka: 144
Datum: Čt, 15. září 2016 13:20:31 GMT
{“responseCode”:0,”responseMessage”:”Success”,”timestamp”:”2016-09-15T13:20:31Z”, “traceId”:”f678d30879fd4adc25f2″,”messageIds”:[“1-4850879008”]}
Zde je stejný JSON formátovaný pro čitelnost:
{
“responseCode“:0,
“responseMessage":"Úspěch",
“timestamp“:”2016-0915T13:20:31Z”,
“traceId“:”f678d30879fd4adc25f2”,
“messageIds“:[“1-4850879008”] }
Selhání
HTTP/1.1 200 OK
Content-Type: application/json
Obsah - délka: 148
Datum: Čt, 15. září 2016 13:20:31 GMT
{“responseCode”:1,”responseMessage”:” Neplatné přihlášení nebo neoprávněné použití API”,”timestamp”:”2016-09-15T13:20:31Z”,”traceId”:”f678d30879fd4adc25f2″}
7.5 Kódy odpovědí
V odpovědi na odeslání lze vrátit následující kódy odezvy:
| Kód | Text | Popis |
| 0 | Úspěch | Úspěšně provedeno. |
| 1 | Neplatné přihlášení nebo neoprávněné použití API | Nesprávné uživatelské jméno nebo heslo nebo poskytovatel služeb je blokován službou LINK Mobility. |
| 2 | Spotřebitel je blokován Mobilitou odkazů | Spotřebitel je blokován LINK Mobility. |
| 3 | Provoz není zajišťován LINK Mobility | Operace je pro poskytovatele služeb zablokována. |
| 4 | Spotřebitel je LINK Mobility neznámý | LINK Mobility spotřebitele nezná. Nebo pokud byl v požadavku použit alias; alias nenalezen. |
| 5 | Zákazník zablokoval tuto službu v LINK Mobility | Zákazník zablokoval tuto službu v LINK Mobility. |
| 6 | Původní adresa není podporována | Původní adresa není podporována. |
| 7 | Původní adresa alfa není podporována účtem | Počáteční adresa alfa není podporována účtem. |
| 8 | Původní adresa MSISDN není podporována | Původní adresa MSISDN není podporována. |
| 9 | Rozšíření GSM není podporováno | Rozšíření GSM není podporováno. |
| 10 | Unicode není podporováno | Unicode není podporováno. |
| 11 | Zpráva o stavu není podporována | Zpráva o stavu není podporována. |
| 12 | Požadovaná funkce není podporována | Požadovaná schopnost (jiná než výše uvedená) pro odeslání zprávy není podporována. |
| 13 | Je překročena maximální míra omezení poskytovatele obsahu | Poskytovatel služby odesílá SMS zprávy do LINK Mobility příliš rychle. |
| 14 | ID protokolu není podporováno účtem | ID protokolu není podporováno. |
| 15 | Byl překročen limit zřetězení zpráv | Počet zřetězených zpráv překračuje maximální požadovaný počet. |
| 16 | Nelze směrovat zprávu. | LINK Mobility nedokázal směrovat zprávu. |
| 17 | Zakázané časové období | Není povoleno odesílat zprávy během časového období |
| 18 | Příliš nízký zůstatek na účtu poskytovatele služeb | Poskytovatel služeb je zablokován z důvodu příliš nízkého zůstatku |
| 50 | Částečný úspěch | Částečný úspěch při odesílání SMS zprávy více příjemcům. |
| 99 | Interní chyba serveru | Jiná chyba Link Mobility, pro více informací kontaktujte podporu LINK Mobility. |
| 100 | Neplatná cílová adresa | Cílová adresa (MSISDN nebo alias) je neplatná. |
| 102 | Neplatné odkazované (propojené) ID | Referenční ID je neplatné, možná je referenční ID již použito, je příliš staré nebo neznámé. |
| 103 | Neplatný název účtu | Název účtu je neplatný. |
| 105 | Neplatná metadata služby | Metadata služby jsou neplatná. |
| 106 | Neplatná původní adresa | Původní adresa je neplatná. |
| 107 | Neplatná alfanumerická výchozí adresa | Alfanumerická výchozí adresa je neplatná. |
| 108 | Neplatná doba platnosti | Doba platnosti je neplatná. |
| 109 | Neplatná dodací lhůta | Dodací lhůta je neplatná. |
| 110 | Neplatný obsah zprávy/uživatelská data | Údaje o uživateli, tj. SMS zpráva, jsou neplatné. |
| 111 | Neplatná délka zprávy | Délka SMS zprávy je neplatná. |
| 112 | Neplatné záhlaví uživatelských dat | Záhlaví uživatelských dat je neplatné. |
| 113 | Neplatné schéma kódování dat | DCS je neplatný. |
| 114 | Neplatné ID protokolu | PID je neplatný. |
| 115 | Neplatné příznaky hlášení stavu | Příznaky zprávy o stavu jsou neplatné. |
| 116 | Neplatné TON | Původce TON je neplatný. |
| 117 | Neplatné campaign jméno | campaign jméno je neplatný. |
| 120 | Neplatný limit pro maximální počet zřetězených zpráv | Maximální počet zřetězených zpráv je neplatný. |
| 121 | Neplatná výchozí adresa msisdn | Původní adresa MSISDN je neplatná. |
| 122 | Neplatné ID korelace | ID korelace je neplatné. |
8. Volitelné funkce
8.1 Oprava MSISDN
Korekce MSISDN je volitelná funkce, kterou lze na požádání povolit podporou LINK Mobility.
Tato funkce opraví cílové adresy a zarovná je do požadovaného formátu E.164. Kromě korekce formátu může systém také provádět funkce specifické pro trh, jako je překlad mezinárodních francouzských čísel pro opravu čísel DOM-TOM (départements et territoires d'outre-mer), pokud je to možné.
Níže je uvedena řada examppočet oprav:
| Odeslaná cílová adresa | Opravená cílová adresa |
| +46(0)702233445 | 46702233445 |
| (0046)72233445 | 46702233445 |
| +460702233445 XNUMX XNUMX XNUMX | 46702233445 |
| 46(0)702233445 | 46702233445 |
| 46070-2233445 | 46702233445 |
| 0046702233445 | 46702233445 |
| +46(0)702233445aaa | 46702233445 |
| 336005199999 | 2626005199999 (francouzské číslo přeloženo na číslo DOM-TOM) |
Navíc je možné povolit národní telefonní čísla pro vybraný trh. Když je tato funkce povolena, všechna mezinárodní čísla pro jiné trhy musí být odeslána s počátečním znaménkem „+“, aby se odlišila od vybraného trhu.
Níže je několik exampmnožství oprav provedených při použití Švédska (kód země 46) jako výchozího trhu pro národní čísla.
| Odeslaná cílová adresa | Opravená cílová adresa |
| 0702233445 | 46702233445 |
| 070-2233 445 | 46702233445 |
| 070.2233.4455 | 46702233445 |
| 460702233445 | 46702233445 |
| +460702233445 XNUMX XNUMX XNUMX | 46702233445 |
| +458022334455 XNUMX XNUMX XNUMX | 458022334455 |
| 45802233445 | Neplatné, protože chybí znaménko „+“. |
Uvědomte si, že opravené MSISDN bude použito LINK Mobility a bude vráceno ve zprávách o doručení.
Pro více informací prosím kontaktujte podporu LINK Mobility.
8.2 Nahrazení postavy
Nahrazení znaků je volitelná funkce, kterou lze na vyžádání aktivovat podporou LINK Mobility.
Tato funkce převede znaky abecedy jiné než GSM v uživatelských datech (text SMS) na ekvivalentní znaky abecedy GSM, když je DCS nastaveno na „GSM“ (17). Napřample „Seqüência de teste em Português“ bude přeloženo na „Seqüencia de teste em Portugues“.
9. Zprávy o doručení
Poskytovatel služby může, pokud je zřízen, požadovat potvrzení o doručení SMS zpráv nebo oznámení o doručení zaslaných zpráv MT. Tyto zprávy se spouštějí v SMSC operátora, když je MT zpráva buď doručena cílovému spotřebiteli nebo vymazána, např. vypršela nebo z nějakého důvodu není směrovatelná.
Poskytovateli služby je hlášen pouze konečný stav SMS zprávy, tj. doručena nebo smazána. Vygeneruje se pouze jedna zpráva na zprávu MT. Se stavem odstraněno se může použít kód příčiny. Tento kód příčiny udává důvod, proč SMS zpráva nebyla doručena.
Zprávy jsou směrovány přes LINK Mobility a odesílány poskytovateli služeb pomocí protokolu HTTP.
Pro příjem zpráv musí poskytovatel služeb implementovat napřample Java Servlet nebo stránka ASP.NET. Oba přijímají požadavky HTTP GET nebo POST.
Parametry
Žádost obsahuje následující parametry:
| Parametr | Typ | M/O/I* | Výchozí hodnota | Maximální délka | Popis |
| MessageId | řetězec | M | – | 22 | ID zprávy zprávy MT, které tato zpráva odpovídá. |
| DestinationAddress | řetězec | M | – | 40 | MSISDN spotřebitele, tj. cílová adresa původní zprávy MT. |
| StatusCode | celé číslo | M | 1 | Stavový kód označuje stav zprávy MT. Použitelné stavové kódy jsou: 0 – Dodáno 2 – Smazáno (platí kód důvodu) |
|
| TimeStamp | řetězec | M | – | 20 | Čas udávající, kdy LINK Mobility přijala zprávu o doručení. Časové pásmo časuamp je SEČ nebo SELČ (s letním časem definovaným pro EU). Formát: yyyyMMdd HH:mm:ss. |
| Operátor | řetězec | M | – | 100 | Jméno Operátora použité při odeslání SMS zprávy nebo název účtu použitý při odeslání SMS zprávy. Seznam dostupných operátorů poskytuje podpora LINK Mobility. |
| ReasonCode | celé číslo | O | – | 3 | Kód důvodu označuje, proč zpráva skončila ve stavu smazáno. Použitelné kódy příčiny jsou: 100 – platnost vypršela 101 – Zamítnuto 102 – Chyba formátu 103 – Jiná chyba 110 – Předplatitel neznámý 111 – Účastník zakázán 112 – Účastník není zřízen 113 – Účastník nedostupný 120 – Chyba SMSC 121 – přetížení SMSC 122 – SMSC roaming 130 – Chyba sluchátka 131 – Překročena paměť sluchátka Chování se může lišit podle integrace operátora. |
| OperatorTimeStamp | řetězec | O | – | 20 | Čas udávající, kdy bylo hlášení spuštěno v SMSC Operátora (pokud Operátor poskytuje). Časové pásmo časuamp je SEČ nebo SELČ (s letním časem definovaným pro EU). Formát: yyyyMMdd HH:mm:ss. |
| StatusText | řetězec | O | – | 255 | Zástupný symbol pro dodatečné informace od Provozovatele, např. textový popis stavu/důvodu. Chování se může lišit podle integrace operátora. |
| CorrelationId | řetězec | O | – | 100 | ID korelace poskytnuté v SendRequest nebo SendTextRequest. |
| Kód sítě operátora | celé číslo | O | – | 6 | Kód mobilní sítě (MCC + MNC) operátora. |
* M = povinné, O = volitelné, I = ignorováno.
Poskytovatel služeb musí poskytnout LINK Mobility s cílem URL pro zprávy o doručení (volitelně včetně přihlašovacích údajů pro základní ověřování HTTP). Poskytovatel služeb si může vybrat, kterou preferovanou metodu HTTP použije:
HTTP POST (doporučeno)
HTTP GET.
Example pomocí HTTP GET (úspěšně doručeno):
https://user:password@www.serviceprovider.com/receivereport?%20MessageId=122&DestinationAddress=46762050312&Operator=Vodafone&TimeStamp=20100401%2007%3A47%3A44&StatusCode=0
Example pomocí HTTP GET (nedoručeno, provozovatel dodal timetamp na akci):
Parametry jsou URL kódovat.
Kódování znaků:
Poskytovatel služeb si může vybrat, které preferované kódování znaků použije:
UTF-8 (doporučeno)
ISO-8859-1.
9.1 Potvrzení poskytovatele služeb
Poskytovatel služeb by měl potvrdit každou zprávu o doručení. Potvrzení může být kladné, tj. úspěšně přijaté hlášení o doručení, nebo záporné, tj. neúspěšné.
Poznámka: LINK Mobility má pro potvrzení o doručení časový limit pro čtení 30 sekund. Časový limit spustí opakování doručení (pokud je povoleno opakování) nebo zrušení doručení (pokud je opakování zakázáno). To znamená, že aplikace Service Provider musí zajistit rychlou odezvu, zejména při vysoké zátěži.
Důrazně se doporučuje potvrdit zprávu o doručení společnosti LINK Mobility před jejím zpracováním.
Pravidlo pro pozitivní a negativní uznání je popsáno takto:
Pozitivní potvrzení, ACK, doručena zpráva o doručení:
Kód odpovědi rozsahu HTTP 200 v kombinaci s následujícím obsahem ve formátu XML:
Negativní potvrzení, NAK, doručenka nebyla doručena:
Jakákoli jiná odpověď než kladné potvrzení, napřample, negativní potvrzení je spuštěno jakýmkoli chybovým kódem HTTP nebo následujícím obsahem XML:
Obsah XML lze použít pro řízení mechanismu opakování LINK Mobility. NAK způsobí pokus o opakování, pokud je povolen. Pro poskytovatele služeb, kteří nejsou nakonfigurováni pro mechanismus opakování, je obsah XML volitelný.
Níže je uveden požadavek HTTP POST a odpověď, napřampsoubor protokolu o doručení doručený poskytovateli služeb:
HTTP požadavek:
POST /context/app HTTP/1.1
Typ obsahu: application / x-www-form-urlencoded;charset=utf-8
Hostitel: server:port
Obsah-délka: xx
MessageId=213123213&DestinationAddress=46762050312&Operator=Telia& OperatorTimeStamp=20130607%2010%3A45%3A00&TimeStamp=20130607%2010%3A 45%3A02&StatusCode=0
HTTP odpověď:
HTTP/1.1 200 OK
Content-Type: text/plain
9.2 Zkuste to znovu
Systém LINK Mobility může provádět opakované pokusy o neúspěšné, tj. nepotvrzené doručení zprávy o doručení. Poskytovatel služeb si může zvolit preferované chování opakování:
Žádný další pokus (výchozí) – zpráva bude zahozena při neúspěšném pokusu o připojení, při vypršení časového limitu čtení nebo při jakémkoli chybovém kódu HTTP.
Zkuste to znovu – zpráva bude znovu odeslána pro každý typ problému s připojením, časový limit čtení nebo negativní potvrzení.
Když je povoleno opakování pro NAK, je důležité pochopit, které scénáře vygenerují pokus o opakování z LINK Mobility a jak tento pokus funguje. Každý poskytovatel služeb má svou vlastní frontu opakování, kde jsou zprávy seřazeny podle času zprávamp. Link Mobility se vždy snaží nejprve doručit starší zprávy, i když není zaručeno individuální pořadí zpráv doručených poskytovateli služeb. Hlavním důvodem vyřazení zpráv z fronty opakování je jeden ze dvou důvodů: buď vyprší TTL zprávy, nebo se (teoreticky) zaplní fronta opakování. TTL je závislé na operátorovi a účtu, tj. může se lišit v závislosti na operátorovi a/nebo typu zprávy, např. prémiová SMS nebo SMS zpráva se standardní sazbou.
Poskytovatelé služeb s povoleným opakováním musí zkontrolovat jedinečné ID zprávy MT, aby zajistili, že zpráva již nebyla přijata.
Je důležité, aby Poskytovatel služeb dodržel tato jednoduchá pravidla, když dojde k chybě při zpracování zprávy o doručení, pokud je důvodem chyby: Dočasné, např. databáze není dostupná, měl by být vrácen NAK. LINK Mobility zprávu odešle znovu.
Trvalý a opakovaný pokus pravděpodobně způsobí stejný druh problému, mělo by být vráceno ACK. Napřample, když zprávu nebylo možné správně analyzovat nebo způsobila neočekávanou chybu běhu.
Příslušné jednání zajistí, že nedojde k žádnému zablokování nebo snížení propustnosti v důsledku opakovaného zasílání zprávy o doručení.
10. Implementační tipy
1. Je možné použít váš web prohlížeč odesílat požadavky do API. Díky tomu je velmi snadné zkoumat a vyhodnocovat služby bez jakýchkoli vývojových nástrojů.
2. Chrome nebo Firefox se doporučují společně s rozšířením, jako je JSONView zobrazit pěkně naformátovaný JSON.
3. Použili jsme SoapUI pro testování POST, základní autentizace a pro kontrolu nezpracovaných zpráv HTTP požadavků a odpovědí.
4. cURL nástroj je užitečný pro odesílání požadavků POST se základní autentizací. Viz napřample níže.
curl PŘÍSPĚVEK \
-H “Typ obsahu: aplikace/x-www-form-urlzakódováno” \
-H “Autorizace: Základní am9objpjaGFuZ2VtZSA=” \
https://europe.ipx.com/restapi/v1/sms/send \
–data “destinationAddress=46123456789&messageText=Hello+World%21”
________________
Transformace personalizované komunikace
Dokumenty / zdroje
 |
LINK Mobility Implementation Guide REST API SMS [pdfUživatelská příručka Mobility Implementation Guide REST API SMS, Mobility, Implementation Guide REST API SMS, REST API SMS, API SMS, SMS |
