LINK Mobility Implementation Guide REST API SMS User Guide

Przewodnik po implementacji LINK Mobility REST API SMS

LINK Mobility zapewnia usługę dostarczania wiadomości, mikropłatności i usług opartych na lokalizacji. Platforma działa jako przejrzysty, white-label content acquirer i router transakcji między dostawcami usług i operatorami.

LINK Mobility udostępnia interfejs API RESTful, który może być używany do uzyskiwania dostępu do usług LINK Mobility, takich jak wysyłanie wiadomości SMS. Ten interfejs API jest zaprojektowany tak, aby był łatwy w użyciu i kompatybilny ze wszystkimi nowoczesnymi językami i frameworkami. Używając języka swojego wyboru, Twoja aplikacja może używać interfejsu API REST Link Mobility do implementacji zaawansowanych funkcji przesyłania wiadomości i płatności

© LINK Mobility, 10 marca 2021 r.

Informacje prawne

Informacje zawarte w tym dokumencie są wyłączną własnością i prawami autorskimi Netsize. Są one poufne i przeznaczone wyłącznie do celów informacyjnych. Nie są wiążące i mogą podlegać zmianom bez powiadomienia. Każde nieautoryzowane ujawnienie lub użycie będzie uważane za niezgodne z prawem.

Netsize™ i linkmobility™ są chronione przez francuskie, europejskie i międzynarodowe prawa własności intelektualnej.

Wszystkie inne wymienione znaki towarowe są wyłączną własnością ich właścicieli.

Żadna z informacji zawartych w niniejszym dokumencie nie powinna być interpretowana jako udzielenie licencji lub prawa na mocy patentu, praw autorskich lub znaku towarowego firmy Netsize.

ROZMIAR NETTO
Société anonyme au capital de 5 478 070 euro
Siege social :62, avenue Emile Zola92100 Boulogne – Francja
418 712 477 RCS Nanterre
http://www.LinkMobility.com
http://www.linkmobility.com

Zakres dokumentu

Niniejszy dokument opisuje sposób, w jaki Dostawca Usług korzysta z LINK Mobility REST API dla SMS. Jest on przeznaczony dla architektów technicznych i projektantów, którzy wdrażają usługi Dostawcy Usług.

1. Podstawowe użytkowanie

Wysyłanie SMS-ów jest bardzo proste. Wysyłasz żądanie HTTP do LINK Mobility, co można wykonać za pomocą zaledwie web przeglądarka.

2. Koniec funkcjonalnyview

System LINK Mobility zapewnia następujące podstawowe funkcjonalności wiadomości SMS:
Wysyłanie wiadomości SMS z wykorzystaniem technologii Mobile Terminated (MT), takich jak wiadomości tekstowe lub binarne (np. WAP Push), o stawkach premium i standard.

Otrzymywanie raportów doręczenia wysłanych wiadomości MT.

Odbieranie wiadomości SMS z telefonów komórkowych (MO), stawki premium i standardowe.
Interfejs API SMS REST jest przeznaczony do wysyłania standardowych wiadomości SMS MT.

API wysyła wszystkie wiadomości SMS asynchronicznie, umożliwiając takie funkcje jak:

„Wystrzel i zapomnij” – Dostawca Usługi chce mieć bardziej przewidywalny czas reakcji i nie chce czekać na wynik od Operatora.

Ponów próbę – LINK Mobility ponownie wyśle ​​wiadomość, jeśli operator napotka tymczasowe problemy.

2.1 Wysyłanie wiadomości SMS

                                       
Dostawca usług Netsize Konsument

1. Wyślij wiadomość MT
2. Identyfikator wiadomości zwrotnej
3. Wyślij wiadomość SMS
4. Dostarcz raport o dostarczeniu
5. Wyślij raport o dostarczeniu

Podstawowy przebieg wysyłania wiadomości SMS jest opisany poniżej:

Dostawca Usługi składa żądanie wysłania wiadomości SMS do odbiorcy za pośrednictwem systemu LINK Mobility.

Identyfikator wiadomości jest zwracany do Dostawcy usługi. Ten identyfikator może być używany np. do korelowania wiadomości z prawidłowym raportem dostarczenia.

LINK Mobility zajmuje się routingiem i dostarczaniem wiadomości SMS do zaadresowanego Konsumenta.
Raport doręczenia jest generowany np. wtedy, gdy wiadomość SMS zostanie dostarczona na urządzenie Konsumenta.

Raport o dostarczeniu jest wysyłany do Dostawcy Usługi. Raport zawiera ten sam identyfikator wiadomości, który został zwrócony w kroku 2.

Alternatywny przepływ: nieprawidłowe żądanie

Jeśli podane parametry lub dane uwierzytelniające użytkownika w żądaniu są nieprawidłowe, do Dostawcy usługi zwracany jest błąd. Błąd wskazuje przyczynę odrzucenia, a przepływ kończy się. Nie są zwracane żadne identyfikatory wiadomości.

3. Punkt końcowy

Dostęp do zasobu SMS uzyskuje się za pomocą ścieżki:
/restapi/v1/sms
Example URL
https://europe.ipx.com/restapi/v1/sms
Ze względów bezpieczeństwa połączenie interfejsu API REST LINK Mobility jest dostępne wyłącznie za pośrednictwem protokołu HTTPS.
Certyfikat serwera Link Mobility jest podpisany przez Thawte Server CA.

4. Operacje

Usługa SMS zapewnia następujące operacje:

Nazwa	Ścieżka
Wysłać	/restapi/v1/sms/wyślij

4.1 Wyślij

Operacja wysyłania służy do wysłania wiadomości SMS do pojedynczego odbiorcy.

Ta operacja jest przeznaczona zarówno dla użytkowników podstawowych, jak i zaawansowanych. W najprostszym przypadku do dostarczenia wiadomości SMS wymagany jest tylko adres docelowy i tekst wiadomości. LINK Mobility wykryje schemat kodowania danych i w razie potrzeby wykona automatyczne łączenie wiadomości w wiele części wiadomości.

W przypadku zaawansowanego wykorzystania Dostawca Usługi może użyć opcjonalnych parametrów, które pozwalają na pełną kontrolę formatowania wiadomości, łącznie z nagłówkiem danych użytkownika.

Dostawca usług może wysyłać połączone wiadomości, ale przygotowanie danych użytkownika i nagłówka danych użytkownika musi zostać wykonane przez Dostawcę usług, a wiadomość musi zostać wysłana za pomocą wielu żądań wysłania w kierunku LINK Mobility.

5. Uwierzytelnianie

Nazwa użytkownika i hasło są przesyłane w każdym żądaniu za pomocą podstawowego schematu uwierzytelniania HTTP.

https://www.w3.org/Protocols/HTTP/1.0/spec.html#BasicAA

Poświadczenia są wysyłane w nagłówku Authorization w żądaniu HTTP. Klient konstruuje pole nagłówka, jak opisano tutaj:

https://en.wikipedia.org/wiki/Basic_access_authentication#Client_side

Na przykładampjeśli nazwa użytkownika to john a changeme to hasło, to wynikowy nagłówek autoryzacji wygląda następująco:

Autoryzacja: Podstawowa am9objpjaGFuZ2VtZSA=

Jako rozwiązanie awaryjne nazwę użytkownika i hasło można przesłać jako parametry żądania. Jest to zalecane tylko dla klientów, którzy nie obsługują Basic Auth.

6. Złożenie wniosku

6.1 Ciąg zapytania

Parametry żądania są przesyłane jako ciąg zapytania zawierający pary nazwa/wartość. Ciąg zapytania jest kodowany przy użyciu Percent Encoding (URL kodowanie).

http://www.w3schools.com/tags/ref_urlencode.asp

Na przykładample, Hello World! jest kodowane jako Hello+World%21.

6.2 Obowiązkowe parametry żądania

Nazwa	Maksymalna długość	Opis
Adres docelowy	40	MSISDN, na który należy wysłać wiadomość SMS, zaczynając od kodu kraju. Np.ample: 46123456789. W przypadku niektórych rynków (gdzie numer MSISDN konsumenta musi być ukryty) wartość ta może być również alfanumerycznym aliasem poprzedzonym znakiem „#”.
wiadomośćTekst	1600	Treść wiadomości SMS.

6.3 Opcjonalne parametry żądania (do zaawansowanego wykorzystania)

Nazwa	Maksymalna długość	Opis
Adres początkowy	16	Adres źródłowy dla wychodzącej wiadomości SMS. Typ adresu źródłowego jest definiowany przez parametr originatorTON. Maksymalna długość krótkiego numeru wynosi 16. Nadawca danych alfanumerycznych może używać domyślnego alfabetu GSM o maksymalnej długości 11 znaków. Maksymalna długość numeru MSISDN nadawcy wynosi 15 (używając tego samego formatu, co element destinationAddress). Można pominąć, gdy originatingAddress i originatingTON są wybrane przez system. Ta funkcja jest zależna od rynku i konfiguracji. Zachowanie może się różnić w zależności od integracji operatora.
twórcaTON	1	Typ numeru adresu nadawcy (TON): 0 – Krótki numer 1 – Alfanumeryczny (maksymalna długość 11) 2 – MSISDN Można pominąć, gdy originatingAddress i originatingTON zostaną wybrane przez system. Ta funkcja jest zależna od rynku i konfiguracji. Zachowanie może się różnić w zależności od integracji operatora.
Nagłówek danych użytkownika	280	Nagłówek User Data wraz z User Data może zawierać do 140, tj. 280 w kodowaniu szesnastkowym, oktetów. Ten parametr jest zawsze kodowany szesnastkowo.
DCS	3	Schemat kodowania danych. Zachowanie może się różnić w zależności od integracji operatora.
PID	3	Identyfikator protokołu. Zachowanie może się różnić w zależności od integracji operatora.
względny czas ważności	6	Względny czas ważności w sekundach (względem czasu na przesłanie do LINK Mobility). Maksymalna wartość to 604800 (7 dni), a domyślna to 48 godzin. Zachowanie może się różnić w zależności od integracji operatora.
Czas dostawy	20	Czasamp kiedy wiadomość SMS powinna zostać dostarczona (opóźniony czas dostarczenia). Zobacz sekcję dotyczącą formatu daty i godziny.
statusRaportFlags	1	Dostarcz żądanie raportu: 0 – Brak raportu o dostarczeniu (domyślnie) 1 – Poproszono o raport dostawy 9 – Żądano raportu dostarczenia serwera (LINK Mobility nie przesyła raportu do Dostawcy Usługi, ale udostępnia go w raportach itp.)
campaignName	50	Transakcje LINK Mobility to tagged z tą nazwą. Jest ona używana do grupowania transakcji w raportach Link Mobility.
maxConcatenatedMessages	1	Wartość od 1 do 10, która definiuje, ile połączonych wiadomości jest dozwolonych. Domyślna wartość to 3.
Identyfikator korelacji	100	Identyfikator podany przez Dostawcę Usługi, który będzie widoczny w Raporcie Dostawy.
nazwa użytkownika	100	Dostarczane jako alternatywa dla uwierzytelniania podstawowego HTTP.
hasło	100	Dostarczane jako alternatywa dla uwierzytelniania podstawowego HTTP.

6.4 Metody żądania HTTP

Aby zapewnić maksymalną interoperacyjność, API obsługuje zarówno metody żądania HTTP GET, jak i POST. Żadne inne metody HTTP nie są dozwolone.

6.4.1 POBIERZ

Zakodowany ciąg zapytania jest dołączany do URL.

DOSTAWAĆ
https://europe.ipx.com/restapi/v1/sms/send?destinationAddress=461234
56789&messageText=Witaj+świecie%21
Autoryzacja: Podstawowa am9objpjaGFuZ2VtZSA=

6.4.2 POSTY

Zakodowany ciąg zapytania jest przesyłany w treści wiadomości żądania HTTP. Content-Type to application/x-www-form-urlzakodowane.

POST https://europe.ipx.com/restapi/v1/sms/send
Gospodarz: europe.ipx.com
Typ zawartości: aplikacja/x-www-form-urlzakodowany
Autoryzacja: Podstawowa am9objpjaGFuZ2VtZSA=
Długość treści: 57

destinationAddress=46123456789&messageText=Witaj+świecie%21

6.5 Data i godzina

Parametry w REST API reprezentujące datę i godzinę są zawsze w strefie czasowej UTC (Coordinated Universal Time).amps są reprezentowane jako ciąg znaków w tym dokładnym formacie:
2017-04-25T23:20:50Z
Oznacza to 20 minut i 50 sekund po godzinie 23 dnia 25 kwietnia 2017 roku według czasu UTC.

7. Wiadomość odpowiedzi

Po otrzymaniu i zinterpretowaniu komunikatu żądania API odpowiada komunikatem odpowiedzi HTTP.

7.1 Kod statusu HTTP

Interfejs API REST zawsze zwraca kod statusu HTTP 200 OK dla przetworzonych żądań. Treść wiadomości zawiera parametr responseCode, który służy do określenia dokładnego wyniku.

7.2 Treść wiadomości

Treść wiadomości składa się z kodu JSON opisującego wynik żądania.
http://json.org/
Format Link Mobility JSON jest zgodny ze stylem Google JSON Style Guide.
https://google.github.io/styleguide/jsoncstyleguide.xml

7.3 Parametry odpowiedzi

Nazwa	Maksymalna długość	Opis
kod odpowiedzi	3	0 oznacza pomyślną transakcję.
odpowiedźWiadomość	255	Opis tekstowy odpowiedzi, np. tekst błędu.
godzinaamp	20	Data i godzina przetworzenia żądania przez LINK Mobility. (Patrz sekcja dotycząca formatu daty/godziny).
Identyfikator śledzenia	36	Wewnętrzny identyfikator Link Mobility. Używany do wsparcia i rozwiązywania problemów.
identyfikatory wiadomości	10x36	Tablica unikatowych identyfikatorów wiadomości LINK Mobility dla każdej pomyślnie wysłanej wiadomości (w przypadku łączenia wiadomości zwracanych jest wiele identyfikatorów wiadomości). Pomijane w przypadku awarii.

7.4ampodpowiedzi

Sukces

HTTP/1.1 200 OK
Typ zawartości: application/json
Długość treści: 144
Data: czw., 15 wrz 2016 13:20:31 GMT
{“responseCode”:0,”responseMessage”:”Sukces”,”timestamp”:”2016-09-15T13:20:31Z”, “traceId”:”f678d30879fd4adc25f2″,”messageIds”:[“1-4850879008”]}

Oto ten sam kod JSON sformatowany w celu ułatwienia czytania:

{
„kod odpowiedzi„:0,
„odpowiedźWiadomość":"Sukces",
„godzinaamp“:”2016-0915T13:20:31Z”,
„Identyfikator śledzenia“:”f678d30879fd4adc25f2”,
„identyfikatory wiadomości“:[“1-4850879008”]
}

Awaria

HTTP/1.1 200 OK
Typ zawartości: application/json
Długość treści: 148
Data: czw., 15 wrz 2016 13:20:31 GMT
{“responseCode”:1,”responseMessage”:” Nieprawidłowe logowanie lub nieautoryzowane użycie API”,”timestamp”:”2016-09-15T13:20:31Z”,”traceId”:”f678d30879fd4adc25f2″}

Sukces

HTTP/1.1 200 OK
Typ zawartości: application/json
Długość treści: 144
Data: czw., 15 wrz 2016 13:20:31 GMT
{“responseCode”:0,”responseMessage”:”Sukces”,”timestamp”:”2016-09-15T13:20:31Z”, “traceId”:”f678d30879fd4adc25f2″,”messageIds”:[“1-4850879008”]}

Oto ten sam kod JSON sformatowany w celu ułatwienia czytania:

{
„kod odpowiedzi„:0,
„odpowiedźWiadomość":"Sukces",
„godzinaamp“:”2016-0915T13:20:31Z”,
„Identyfikator śledzenia“:”f678d30879fd4adc25f2”,
„identyfikatory wiadomości“:[“1-4850879008”]
}

Awaria

HTTP/1.1 200 OK
Typ zawartości: application/json
Długość treści: 148
Data: czw., 15 wrz 2016 13:20:31 GMT
{“responseCode”:1,”responseMessage”:” Nieprawidłowe logowanie lub nieautoryzowane użycie API”,”timestamp”:”2016-09-15T13:20:31Z”,”traceId”:”f678d30879fd4adc25f2″}

7.5 Kody odpowiedzi

W odpowiedzi wysyłanej można zwrócić następujące kody odpowiedzi:

Kod	Tekst	Opis
0	Sukces	Pomyślnie wykonano.
1	Nieprawidłowe logowanie lub nieautoryzowane użycie API	Nieprawidłowa nazwa użytkownika lub hasło lub dostawca usług zostanie zablokowany przez LINK Mobility.
2	Konsument jest blokowany przez Link Mobility	Konsument jest blokowany przez LINK Mobility.
3	Operacja nie jest zapewniana przez LINK Mobility	Operacja jest zablokowana dla Dostawcy Usługi.
4	Konsument nie jest znany firmie LINK Mobility	Konsument nie jest znany firmie LINK Mobility. Lub jeśli w żądaniu użyto aliasu; alias nie został znaleziony.
5	Konsument zablokował tę usługę w LINK Mobility	Konsument zablokował tę usługę w LINK Mobility.
6	Adres źródłowy nie jest obsługiwany	Adres źródłowy nie jest obsługiwany.
7	Adres źródłowy Alpha nie jest obsługiwany przez konto	Adres źródłowy alfa nie jest obsługiwany przez to konto.
8	Adres źródłowy MSISDN nie jest obsługiwany	Adres źródłowy MSISDN nie jest obsługiwany.
9	Rozszerzenie GSM nie jest obsługiwane	Rozszerzenie GSM nie jest obsługiwane.
10	Unicode nie jest obsługiwany	Unicode nie jest obsługiwany.
11	Raport o stanie nie jest obsługiwany	Raport o stanie nie jest obsługiwany.
12	Wymagana możliwość nie jest obsługiwana	Wymagana możliwość (inna niż powyższa) wysłania wiadomości nie jest obsługiwana.
13	Przekroczono maksymalną wartość ograniczenia przepustowości dostawcy treści	Dostawca usług wysyła wiadomości SMS do LINK Mobility zbyt szybko.
14	Identyfikator protokołu nie jest obsługiwany przez konto	Identyfikator protokołu nie jest obsługiwany.
15	Przekroczono limit łączenia wiadomości	Liczba połączonych wiadomości przekracza maksymalną żądaną liczbę.
16	Nie można skierować wiadomości.	LINK Mobility nie był w stanie skierować wiadomości.
17	Okres zakazu	Nie wolno wysyłać wiadomości w tym okresie
18	Zbyt niskie saldo na koncie dostawcy usług	Dostawca usług jest zablokowany z powodu zbyt niskiego salda
50	Częściowy sukces	Częściowy sukces przy wysyłaniu wiadomości SMS do wielu odbiorców.
99	Wewnętrzny błąd serwera	W przypadku innych błędów związanych z usługą Link Mobility skontaktuj się z pomocą techniczną LINK Mobility, aby uzyskać więcej informacji.
100	Nieprawidłowy adres docelowy	Adres docelowy (MSISDN lub alias) jest nieprawidłowy.
102	Nieprawidłowy identyfikator referencyjny (powiązany)	Identyfikator odniesienia jest nieprawidłowy. Być może jest już używany, jest za stary lub nieznany.
103	Nieprawidłowa nazwa konta	Nazwa konta jest nieprawidłowa.
105	Nieprawidłowe metadane usługi	Metadane usługi są nieprawidłowe.
106	Nieprawidłowy adres nadawcy	Adres źródłowy jest nieprawidłowy.
107	Nieprawidłowy alfanumeryczny adres źródłowy	Alfanumeryczny adres źródłowy jest nieprawidłowy.
108	Nieprawidłowy czas ważności	Czas ważności jest nieprawidłowy.
109	Nieprawidłowy czas dostawy	Podany czas dostawy jest nieprawidłowy.
110	Nieprawidłowa treść wiadomości/dane użytkownika	Dane użytkownika, tj. wiadomość SMS, są nieprawidłowe.
111	Nieprawidłowa długość wiadomości	Długość wiadomości SMS jest nieprawidłowa.
112	Nieprawidłowy nagłówek danych użytkownika	Nagłówek danych użytkownika jest nieprawidłowy.
113	Nieprawidłowy schemat kodowania danych	DCS jest nieprawidłowy.
114	Nieprawidłowy identyfikator protokołu	PID jest nieprawidłowy.
115	Nieprawidłowe flagi raportu o stanie	Flagi raportu statusu są nieprawidłowe.
116	Nieprawidłowy TON	Oryginalny TON jest nieprawidłowy.
117	Nieprawidłowy campimię i nazwisko	campNazwa aign jest nieprawidłowa.
120	Nieprawidłowy limit maksymalnej liczby połączonych wiadomości	Maksymalna liczba połączonych wiadomości jest nieprawidłowa.
121	Nieprawidłowy adres źródłowy msisdn	Adres źródłowy MSISDN jest nieprawidłowy.
122	Nieprawidłowy identyfikator korelacji	Identyfikator korelacji jest nieprawidłowy.

8. Funkcje opcjonalne

8.1 Korekta MSISDN

Korekta numeru MSISDN to opcjonalna funkcja, którą na życzenie można włączyć za pośrednictwem pomocy technicznej LINK Mobility.

Ta funkcja skoryguje adresy docelowe i dopasuje je do wymaganego formatu E.164. Oprócz korekty formatu system może również wykonywać funkcje specyficzne dla rynku, takie jak tłumaczenie międzynarodowych numerów francuskich na poprawne numery DOM-TOM (départements et territoires d'outre-mer), gdy ma to zastosowanie.

Poniżej znajduje się kilka byłychamplisty poprawek:

Przesłany adres docelowy	Skorygowany adres docelowy
+46(0)702233445	46702233445
(0046)72233445	46702233445
+460702233445	46702233445
46(0)702233445	46702233445
46070-2233445	46702233445
0046702233445	46702233445
+46(0)702233445aaa	46702233445
336005199999	2626005199999 (Liczba francuska przetłumaczona na liczbę DOM-TOM)

Dodatkowo możliwe jest zezwolenie na krajowe numery telefonów dla wybranego rynku. Gdy ta funkcja jest włączona, wszelkie międzynarodowe numery dla innych rynków muszą być wysyłane ze znakiem `+' początkowym, aby odróżnić je od wybranego rynku.

Poniżej kilka npampLiczba poprawek wprowadzonych przy używaniu Szwecji (kod kraju 46) jako domyślnego rynku dla numerów krajowych.

Przesłany adres docelowy	Skorygowany adres docelowy
0702233445	46702233445
070-2233 445	46702233445
070.2233.4455	46702233445
460702233445	46702233445
+460702233445	46702233445
+458022334455	458022334455
45802233445	Nieprawidłowe, ponieważ brakuje znaku „+”

Należy pamiętać, że poprawiony numer MSISDN zostanie użyty przez firmę LINK Mobility i będzie uwzględniany w raportach doręczenia.

Więcej informacji można uzyskać, kontaktując się z pomocą techniczną LINK Mobility.

8.2 Zamiana znaków

Podmiana znaków to opcjonalna funkcja, którą na życzenie można włączyć za pośrednictwem działu obsługi klienta LINK Mobility.

Funkcja ta tłumaczy znaki alfabetu innego niż GSM w danych użytkownika (tekst SMS) na odpowiadające im znaki alfabetu GSM, gdy DCS jest ustawiony na „GSM” (17). Na przykładample „Seqüência de teste em Português” zostanie przetłumaczone na „Seqüencia de teste em Portugues”.

9. Raporty dostawy

Dostawca usług może, jeśli jest zaopatrzony, zażądać raportów o dostarczeniu wiadomości SMS lub powiadomień o dostarczeniu dla wysłanych wiadomości MT. Raporty te są wyzwalane w SMSC operatora, gdy wiadomość MT zostanie dostarczona do docelowego konsumenta lub usunięta, np. wygasła lub z jakiegoś powodu niemożliwa do przekierowania.

Dostawcy usługi zgłaszany jest tylko ostateczny status wiadomości SMS, tj. dostarczona lub usunięta. Generowany jest tylko jeden raport na wiadomość MT. W przypadku statusu usuniętego może mieć zastosowanie kod przyczyny. Ten kod przyczyny określa powód, dla którego wiadomość SMS nie została dostarczona.

Raporty są przesyłane przez LINK Mobility i do Dostawcy Usługi za pomocą protokołu HTTP.

Aby otrzymywać raporty, Dostawca Usług musi wdrożyć np.ample serwlet Java lub strona ASP.NET. Oba odbierają żądania HTTP GET lub POST.

Parametry

Żądanie zawiera następujące parametry:

Parametr	Typ	M/O/I*	Wartość domyślna	Maksymalna długość	Opis
Identyfikator wiadomości	smyczkowy	M	–	22	Identyfikator wiadomości MT, której odpowiada ten raport.
Adres docelowy	smyczkowy	M	–	40	Numer MSISDN Konsumenta, czyli adres docelowy oryginalnej wiadomości MT.
Kod statusu	liczba całkowita	M		1	Kod statusu wskazuje status komunikatu MT. Obowiązujące kody statusu to: 0 – Dostarczono 2 – Usunięto (obowiązuje kod przyczyny)
CzasStamp	smyczkowy	M	–	20	Czas wskazujący, kiedy LINK Mobility otrzymał raport o dostarczeniu. Strefa czasowa najdawniejszych czasówamp to CET lub CEST (z czasem letnim zdefiniowanym w UE). Format: rrrrMMdd GG:mm:ss.
Operator	smyczkowy	M	–	100	Nazwa operatora użyta przy wysyłaniu wiadomości SMS lub nazwa konta użyta przy wysyłaniu wiadomości SMS. Listę dostępnych operatorów udostępnia dział wsparcia LINK Mobility.
Kod przyczyny	liczba całkowita	O	–	3	Kod przyczyny wskazuje, dlaczego wiadomość otrzymała status usuniętej. Obowiązujące kody przyczyn to: 100 – Wygasło 101 – Odrzucone 102 – Błąd formatu 103 – Inny błąd 110 – Nieznany abonent 111 – Abonent zablokowany 112 – Abonent nie został zaopatrzony 113 – Abonent niedostępny 120 – Awaria SMSC 121 – Przeciążenie SMSC 122 – Roaming SMSC 130 – Błąd słuchawki 131 – Przekroczono pamięć słuchawki Zachowanie może się różnić w zależności od integracji z operatorem.
OperatorCzasStamp	smyczkowy	O	–	20	Czas wskazujący, kiedy raport został wygenerowany w systemie SMSC Operatora (jeśli został podany przez Operatora). Strefa czasowa najdawniejszych czasówamp to CET lub CEST (z czasem letnim zdefiniowanym w UE). Format: rrrrMMdd GG:mm:ss.
tekst stanu	smyczkowy	O	–	255	Miejsce zastępcze na dodatkowe informacje od Operatora, np. przejrzysty opis stanu/powodu. Zachowanie może się różnić w zależności od integracji Operatora.
Identyfikator korelacji	smyczkowy	O	–	100	Identyfikator korelacji podany w żądaniu SendRequest lub SendTextRequest.
OperatorNetworkCode	liczba całkowita	O	–	6	Kod sieci komórkowej (MCC + MNC) operatora.

* M = Obowiązkowe, O = Opcjonalne, I = Ignorowane.
Dostawca usług musi dostarczyć LINK Mobility cel URL dla raportów dostawy (opcjonalnie obejmujących poświadczenia dla podstawowego uwierzytelniania HTTP). Dostawca usług może wybrać preferowaną metodę HTTP do użycia:
HTTP POST (zalecane)
Pobranie protokołu HTTP GET.

Example przy użyciu HTTP GET (dostarczono pomyślnie):
https://user:password@www.serviceprovider.com/receivereport?%20MessageId=122&DestinationAddress=46762050312&Operator=Vodafone&TimeStamp=20100401%2007%3A47%3A44&StatusCode=0

Example przy użyciu HTTP GET (niedostarczone, operator dostarczył timestamp na wydarzenie):

https://user:password@www.serviceprovider.com/receivereport?MessageId=123&DestinationAddress=46762050312&Operator=Vodafone&OperatorTimeStamp=20100401%2007%3A47%3A59&TimeStamp=20100401%2007%3A47%3A51&StatusCode=2&StatusText=Delivery%20failed&ReasonCode=10

Parametry są następujące: URL zakodowano.

Kodowanie znaków:
Dostawca usług może wybrać preferowane kodowanie znaków:
UTF-8 (zalecane)
PN-ISO-8859-1.

9.1 Potwierdzenie Dostawcy Usług

Dostawca usług powinien potwierdzić każdy raport o dostarczeniu. Potwierdzenie może być pozytywne, tj. raport o dostarczeniu został pomyślnie odebrany, lub negatywne, tj. niepowodzenie.

Uwaga: LINK Mobility ma limit czasu odczytu potwierdzeń wynoszący 30 sekund dla raportów o dostarczeniu. Limit czasu spowoduje ponowną próbę dostarczenia (jeśli ponawianie jest włączone) lub anulowanie dostarczenia (jeśli ponawianie jest wyłączone). Oznacza to, że aplikacja Service Provider musi zapewnić szybkie czasy reakcji, szczególnie przy dużym obciążeniu.

Zdecydowanie zaleca się potwierdzenie raportu doręczenia firmie LINK Mobility przed jego przetworzeniem.

Regułę potwierdzenia pozytywnego i negatywnego opisano następująco:

Pozytywne potwierdzenie, ACK, raport o dostarczeniu dostarczony:
Kod odpowiedzi zakresu HTTP 200 w połączeniu z następującą treścią w formacie XML:

Negatywne potwierdzenie, NAK, raport o dostarczeniu nie został dostarczony:
Jakakolwiek odpowiedź inna niż pozytywne potwierdzenie, np.ample, negatywne potwierdzenie jest wyzwalane przez dowolny kod błędu HTTP lub następującą zawartość XML:

Zawartość XML może być używana do kontrolowania mechanizmu ponawiania próby LINK Mobility. NAK spowoduje ponowną próbę, jeśli jest włączony. W przypadku Dostawców Usług nieskonfigurowanych dla mechanizmu ponawiania próby zawartość XML jest opcjonalna.

Poniżej znajduje się żądanie i odpowiedź HTTP POSTampplik raportu o dostarczeniu dostarczonego Dostawcy Usługi:

Żądanie HTTP:

POST /kontekst/aplikacja HTTP/1.1
Typ zawartości: aplikacja/x-www-form-urlzakodowane;charset=utf-8
Host: serwer:port
Długość treści: xx

MessageId=213123213&DestinationAddress=46762050312&Operator=Telia& OperatorTimeStamp=20130607%2010%3A45%3A00&TimeStamp=20130607%2010%3A 45%3A02&StatusCode=0

Odpowiedź HTTP:

HTTP/1.1 200 OK
Typ zawartości: tekst/zwykły

9.2 Ponów próbę

System LINK Mobility może wykonywać próby ponownych prób dla nieudanych, tj. niepotwierdzonych, raportów o dostarczeniu. Dostawca usług może wybrać preferowane zachowanie ponownych prób:

Brak ponownej próby (domyślnie) – wiadomość zostanie odrzucona w przypadku nieudanej próby połączenia, przekroczenia limitu czasu odczytu lub wystąpienia jakiegokolwiek kodu błędu HTTP.

Spróbować ponownie – wiadomość zostanie wysłana ponownie w przypadku każdego rodzaju problemu z połączeniem, przekroczenia limitu czasu odczytu lub negatywnego potwierdzenia.

Gdy włączona jest ponowna próba dla NAK, ważne jest zrozumienie, które scenariusze wygenerują ponowną próbę z LINK Mobility i jak działa ponowna próba. Każdy dostawca usług ma własną kolejkę ponownych prób, w której wiadomości są uporządkowane według czasu wiadomościamp. Link Mobility zawsze próbuje dostarczać starsze wiadomości jako pierwsze, nawet jeśli kolejność dostarczania wiadomości do dostawcy usługi nie jest gwarantowana. Głównym powodem usuwania wiadomości z kolejki ponownych prób jest jeden z dwóch powodów: albo wygaśnięcie TTL wiadomości, albo (teoretycznie) zapełnienie kolejki ponownych prób. TTL zależy od operatora i konta, tj. może się różnić w zależności od operatora i/lub typu wiadomości, np. SMS premium lub standardowa stawka SMS.

Dostawcy usług, którzy mają włączoną opcję ponawiania prób, muszą sprawdzić unikalny identyfikator komunikatu MT, aby mieć pewność, że komunikat nie został już odebrany.

Ważne jest, aby Dostawca Usług zastosował się do tych prostych zasad w przypadku wystąpienia błędu w trakcie przetwarzania raportu doręczenia, jeśli powód błędu jest: tymczasowy, np. baza danych niedostępna, należy zwrócić kod NAK. LINK Mobility ponownie wyśle ​​wiadomość.

Trwała i ponowna próba prawdopodobnie spowodują ten sam rodzaj problemu, należy zwrócić ACK. Na przykładample, gdy nie można poprawnie przeanalizować wiadomości lub wystąpił nieoczekiwany błąd w czasie wykonywania.

Podjęcie odpowiednich działań zapewni, że nie dojdzie do zablokowania połączenia ani pogorszenia przepustowości z powodu wielokrotnego wysyłania raportu doręczenia.

10. Wskazówki dotyczące wdrażania

1. Można używać swojego web przeglądarka do przesyłania żądań do API. Dzięki temu bardzo łatwo jest eksplorować i oceniać usługi bez żadnych narzędzi programistycznych.

2. Zalecane są przeglądarki Chrome lub Firefox wraz z rozszerzeniem, takim jak JSONView aby wyświetlić ładnie sformatowany JSON.

3. Użyliśmy SoapUI do przetestowania POST, uwierzytelniania podstawowego oraz do inspekcji surowych komunikatów żądań i odpowiedzi HTTP.

https://www.soapui.org/

4. cURL narzędzie jest przydatne do przesyłania żądań POST z uwierzytelnianiem podstawowym. Zobacz np.ampzobacz poniżej.

https://curl.haxx.se/

curl POST \
-H „Typ zawartości: aplikacja/x-www-form-urlzakodowane” \
-H „Autoryzacja: Podstawowa am9objpjaGFuZ2VtZSA=” \
https://europe.ipx.com/restapi/v1/sms/send \
–data “destinationAddress=46123456789&messageText=Witaj+świecie%21”

_______________

Transformacja spersonalizowanej komunikacji