Specyfikacja API bramki SMS/MMS/TTS wersja 1.3.1 Piotr Isajew (pki@ex.com.pl) 21 lutego 2011 c 2011 EXPERTUS, http://www.ex.com.pl
1. Wprowadzenie API działa w oparciu o proste komunikaty XML przekazywane za pomocą metody HTTP POST. API umożliwia: wysyłanie wiadomości SMS z losowych numerów 9-cyfrowych wysyłanie wiadomości SMS z predefiniowanego numeru, w tym numeru alfanumerycznego (tzw. nadpis ) wysyłanie wiadomości MMS z losowych numerów 9-cyfrowych wysyłanie wiadomości głosowych w przypadku, gdy wiadomość SMS jest kierowana na numer stacjonarny otrzymywanie informacji o stanie wiadomości zleconych do wysłania otrzymywanie wiadomości SMS przesłanych w odpowiedzi na wiadomości wysłane z systemu W zależności od wariantu podpisanej umowy nie wszystkie z powyższych funkcji mogą być dostępne. Domyślnie komunikacja z wykorzystaniem API jest jednokierunkowa transakcje są inicjowane przez klienta i potwierdzane synchronicznie przez bramkę. Przy tego typu dostępie nie ma możliwości odbierania odpowiedzi na wysłane SMSy. Na życzenie klienta istnieje możliwość skonfigurowania komunikacji dwukierunkowej, umożliwiającej asynchroniczne powiadamianie klienta o zmianie stanu wysyłanych wiadomości oraz otrzymywanie wiadomości SMS przesyłanych w odpowiedzi na wysłane wiadomości (patrz też 2.4). 1.1 Parametry konfiguracyjne Konfiguracja dostępu wymaga określenia dla klienta następujących parametrów: adres URL bramki, na który będą przesyłane żądania, nazwa użytkownika i hasło klienta wykorzystywane do uwierzytelniania żądań. adres IP, z którego będą przesyłane żądania. Ponadto, jeśli dla klienta została aktywowana funkcja przekazywania potwierdzeń dostarczenia wiadomości lub odpowiedzi, konieczne jest określenie adresu URL po stronie klienta, na który będą przekazywane potwierdzenia dostarczenia wiadomości (por. 2.4). Dodatkowo skonfigurowanie dostępu będzie wymagało określenia parametrów, o których mowa w części 3. 1
1.2 Standardy kodowania Ilekroć w komunikatach API przekazywane są teksty, oczekuje się, że będą one kodowane z użyciem kodowania UTF-8. 1.3 Reprezentacja dat Wszystkie daty należy podawać z wykorzystaniem czasu lokalnego (CET). 2
2. Postać komunikatów Komunikaty przekazywane są w postaci obiektów XML, przekazywanych jako dane w metodzie HTTP POST na docelowy adres URL. 2.1 Komunikaty przesyłane od klienta do bramki Wszystkie komunikaty przekazywane od klienta do bramki mają następującą postać: <?xml version="1.0" encoding="utf-8"?> <gateway-request type=""> <request-auth> <partnerlogin>testuser</partnerlogin> <partnerpassword>testpassword</partnerpassword> </request-auth> <request-data> </request-data> </gateway-request> Atrybut type określa rodzaj przesyłanego komunikatu, determinujący, jakie elementy mogą się pojawić w części request-data. Rodzaje przesyłanych komunikatów pokazane są w tablicy 2.1. Jeżeli żądanie POST przesłane do serwera nie zawiera komunikatu o podanej wcześniej postaci, przesyłany komunikat ma błędy składniowe, czy też dane uwierzytelniające nie są poprawne, to brama odpowiada komunikatem ERROR, po którym opcjonalnie następuje informacja o rodzaju błędu. W przypadku, kiedy żądanie przesłane do bramki jest poprawne, bramka odpowiada komunikatem o postaci: Typ komunikatu sms-send-request mms-send-request sms-status-request mms-status-request Znaczenie żądanie wysłania wiadomości SMS żądanie wysłania wiadomości MMS zapytanie o stan wiadomości SMS, których wysłanie zostało wcześniej zlecone zapytanie o stan wiadomości MMS, których wysłanie zostało wcześniej zlecone Tablica 2.1: Komunikaty przesyłane od klienta 3
Komunikat sms-send-request sms-status-request mms-send-request mms-status-request Lokalizacja schematu http://www.superbramka.pl/ns/1_3/sms-send-request.xsd http://www.superbramka.pl/ns/1_3/sms-status-request.xsd http://www.superbramka.pl/ns/1_3/mms-send-request.xsd http://www.superbramka.pl/ns/1_3/mms-status-request.xsd Tablica 2.2: Lokalizacja schematów umożliwiających weryfikację przesyłanych dokumentów <?xml version="1.0" encoding="utf-8"?> <gateway-response type=""> </gateway-response> Element gateway-response zawiera elementy odnoszące się do poszczególnych elementów zawartych w części request-data, którego dotyczy odpowiedź. Atrybut type determinuje rodzaj elementów które zawarte są w odpowiedzi i obecnie może przyjmować następujące wartości: sms-send-response tj. odpowiedź dotyczy żądania wysłania SMSów sms-status-response tj. odpowiedź dotyczy zapytania o stan wcześniej wysłanych SMSów mms-send-response odpowiedź dotyczy żądanie wysłania MMSów, oraz mms-status-response odpowiedź dotyczy zapytania o stan wcześniej wysłanych MMSów 2.1.1 Walidacja komunikatów Poprawność składniowa komunikatów przesyłanych od klienta do bramki może być zweryfikowana przy użyciu walidatora XML pozwalającego na walidację z użyciem schematów XML rekomendowanych przez W3C (xsd). Adresy, pod którymi opublikowano odpowiednie schematy zawiera tablica 2.2. 2.1.2 Wysyłanie wiadomości SMS W przypadku wysyłania wiadomości SMS żądanie gateway-request powinno być typu sms-sendrequest. Wówczas część request-data zawiera jeden lub więcej elementów sms-send-request, o postaci: <sms-send-request> <!-- elementy wymagane --> <message-id>12346562</message-id> <msisdn>601601601</msisdn> <sms-text>example of very simple send-request</sms-text> <!-- elementy opcjonalne --> <dont-send-before>2010-03-01 17:00</dont-send-before> <tts-text>text</tts-text> <src-addr>test</src-addr> </sms-send-request> 4
W żądaniu muszą wystąpić wszystkie elementy oznaczone jako elementy wymagane, a ponadto mogą wystąpić dowolne z elementów oznaczonych jako elementy opcjonalne. Znaczenie poszczególnych elementów jest następujące: message-id liczba naturalna jednoznacznie identyfikująca wiadomość w systemie klienta msisdn numer telefonu, na który ma być dostarczona wiadomość, w formacie 123456789 lub +48123456789 sms-text treść wiadomości (dopuszcza się znaki z zestawu ASCII, oraz polskie znaki diakrytyczne) dont-send-before pozwala na wskazanie najwcześniejszego momentu, w którym system może wysłać wiadomość tts-text alternatywna treść wiadomości, którą należy odczytać przez system TTS jeżeli numer docelowy zostanie zidentyfikowany jako numer stacjonarny (maks. 4000 znaków) src-addr wskazanie numeru, z którego ma zostać wysłana wiadomość (brak tego elementu jest tożsamy z wysłaniem wiadomości z dowolnego numeru 9-cyfrowego) 2.1.3 Wysyłanie wiadomości MMS Postać komunikatu wykorzystywanego do wysłania wiadomości MMS zależy od sposobu jego definicji. Ogólna struktura żądania przedstawiona została poniżej: <mms-send-request> <message-id>4444</message-id> <msisdn>48501501501</msisdn> <message-template> <!-- specyfikacja szablonu wiadomości --> </message-template> <message-subject>temat</message-subject> <message-data> <!-- specyfikacja zawartości wiadomości --> </message-data> </mms-send-request> Szablon wiadomości System umożliwia wysyłanie wyłącznie wiadomości ze zdefiniowanym szablonem SMIL. Może to być jeden z szablonów zdefiniowanych w webowym interfejsie administracyjnym, bądź szablon zdefiniowany w treści MMS a. W przypadku użycia szablonu zdefiniowanego w interfejsie administracyjnym element message-template powinien zawierać identyfikator tego szablonu, np.: <message-template> <template-id>11</template-id> </message-template> Możliwe jest również podanie treści szablonu SMIL bezpośrednio w komunikacie, np.: 5
<message-template> <smil-data> <smil> <head> <layout> <region id="a" top="0" left="0" height="100%" fit="meet"/> </layout> </head> <body> <par> <img src="obrazek_1.jpg" region="a"/> </par> </body> </smil> </smil-data> </message-template> Oczekuje się, że w zdefiniowanym szablonie źródła poszczególnych elementów będą podane jako nazwy plików (bez katalogów) z rozszerzeniem odpowiadającym typom plików. Nazwy plików nie muszą odnosić się do istniejących plików w systemie klienta mają charakter wirtualny. Zawartość wiadomości Dla każdego z obiektów zdefiniowanych w szablonie SMIL w części message-data musi zostać określona zawartość tego obiektu. Zawartości poszczególnych obiektów określa się w odpowiadających im elementach message-part: <message-data> <message-part type="rodzaj specyfikacji" name="nazwa obiektu"> <!-- zawartość obiektu --> </message-part> </message-data> Atrybut name określa obiekt szablonu, którego dotyczy dany element message-part (np.: obrazek1.jpg). Nazwa powinna być podana jako nazwa pliku (bez ścieżki katalogów). Rozszerzenie powinno umożliwiać ustalenie typu MIME zawartości pliku. Atrybut type określa sposób określenia zawartości obiektu i może przyjmować następujące wartości: base64 zawartość binarna obiektu jest podana bezpośrednio wewnątrz elementu message-part kodowana zgodnie z base64. href wewnątrz elementu message-part znajduje się adres URL z pod którego można pobrać zawartość binarną obiektu text obiekt jest obiektem tekstowym i wewnątrz elementu message-part znajduje się treść tego obiektu System nie limituje w żaden sposób ilości oraz wielkości poszczególnych obiektów, należy jednak pamiętać, że całkowita wielkość jednej wiadomości MMS jest ograniczona do 280KB. 6
2.1.4 Zapytanie o stan wysyłanej wiadomości Zapytanie o stan wysłanej wiadomości powinno, w części request-data zawierać jeden lub więcej elementów sms-status-request, (lub mms-status-request) o postaci: <sms-status-request> <message-id>1243124314</message-id> </sms-status-request> gdzie message-id jest liczbą naturalną jednoznacznie identyfikującą wiadomość w systemie klienta. 2.2 Komunikaty przesyłane od bramki do klienta Wszystkie komunikaty przesyłane przez serwer do klienta mają postać: <?xml version="1.0" encoding="utf-8"?> <gateway-response type=""> </gateway-response> Atrybut type determinuje zawartość elementów odpowiedzi. Może on obecnie przyjmować następujące wartości: sms-send-response oznacza, że gateway-response zawiera elementy typu sms-send-response sms-status-response oznacza, że gateway-response zawiera elementy typu sms-status-response mms-send-response zawiera odpowiedź na żądanie wysłania MMS a (mms-status-response) mms-status-response element gateway-response zawiera elementy mms-status-response status-notification jest używany przy powiadomieniach asynchronicznych; w tym przypadku element gateway-response może zawierać zarówno elementy mms-status-response jak i smsstatus-response 2.2.1 Odpowiedź na żadanie wysłania wiadomości W odpowiedzi na żądanie wysłania wiadomości generowana jest odpowiedź typu sms-send-response, składająca się z elementów sms-send-response (analogicznie dla MMS) o postaci: <sms-send-response> <message-id>121212</message-id> <result>ok ERROR</result> </sms-send-response> Zawartość elementu result informuje o wyniku żądania wysłania w odniesieniu do danej wiadomości: OK oznacza, że wiadomość została przyjęta do wysłania ERROR oznacza, że wiadomość nie została zaakceptowana do wysłania; może to być wynikiem awarii systemu lub błędu w żądaniu wysłania wiadomości (np. brak wymaganych elementów, zła postać numeru, wykorzystanie id wykorzystanego wcześniej do wysłania innej wiadomości) 7
2.2.2 Odpowiedź na zapytanie o stan wiadomości Odpowiedź na zapytanie o stan wysłania wiadomości zawiera elementy sms-status-response (analogiczna sytuacja dla wiadomości MMS), o postaci: <gateway-response type="sms-status-response"> <sms-status-response> <message-id>12346562</message-id> <part>0</part> <status>pending processing sent confirmed paused failed not found</status> <status-time>yyyy-mm-dd HH:MM</status-time> <sent-time>yyyy-mm-dd HH:MM</sent-time> <delivered-time>yyyy-mm-dd HH:MM</delivered-time> </sms-status-response> </gateway-response> Element part podaje numer kolejny części wiadomości (wartość istotna w przypadku gdy dochodzi do podziału wiadomości na części). Element status określa stan wiadomości. Dozwolone wartości: pending wiadomość została przyjęta przez system do wysłania ale jeszcze nie została wysłana processing jest podejmowana próba wysłania wiadomości sent wiadomość została wysłana do sieci GSM confirmed otrzymano potwierdzenie dostarczenia wiadomości paused administracyjnie wstrzymano przetwarzanie wiadomości przez system failed próba wysłania wiadomości zakończyła się niepowodzeniem i nie będą podejmowane kolejne próby wysłania tej wiadomości not found wiadomość o podanym message-id nie została znaleziona w systemie Elementy status-time, sent-time, delivered-time zawierają znaczniki czasowe dotyczące wiadomości. Ich znaczenie jest następujące: status-time określa moment ostatniej zmiany stanu wiadomości sent-time określa moment wysłania wiadomości delivered-time określa moment dostarczenia wiadomości do odbiorcy (w przypadku jeżeli wiadomość była wysłana z żądaniem potwierdzenia i otrzymano potwierdzenie) 2.3 Dodatkowe uwagi 2.3.1 Ograniczenia czasowe przy wysyłaniu wiadomości W przypadku, jeżeli w żądaniu wysłania wiadomości nie wystąpi żadne graniczenie czasu, system, będzie próbował wysłać wiadomość od momentu przyjęcia zgłoszenia, do skutku lub wystąpienia nieodwracalnego błędu. Jeżeli w żądaniu ograniczenie dont-send-before ma wartość wcześniejszą niż moment wysyłania żądania, to jego wartość zostanie skorygowana na moment wysyłania żądania. 8
2.3.2 Dostarczanie potwierdzeń odebrania wiadomości System umożliwia wysyłanie wiadomości z żądaniem potwierdzenia ich dostarczenia. Należy przy tym zwrócić uwagę na to, że techniczna implementacja potwierdzenia zależy od sieci i telefonu odbiorcy wiadomości. W szczególności nie otrzymanie potwierdzenia pomimo żądania nie oznacza, że wiadomość nie została dostarczona do odbiorcy. Na życzenie klienta istnieje możliwość skonfigurowania komunikacji dwukierunkowej. Przy takiej konfiguracji system dostarcza powiadomienia o zmianie stanu poszczególnych wiadomości. Powiadomienia są wysyłane za pomocą metody HTTP POST na adres URL wskazany przez klienta. W treści żądania przesyłany jest komunikat gateway-response typu sms-status-response. W przypadku komunikacji dwukierunkowej dopuszczalna jest sytuacja, w której bramka wysyła do systemu klienta komunikat z potwierdzeniem tylko raz. W przypadku, gdy system klienta jest nieosiągalny lub komunikacja zostanie przerwana bramka nie ma obowiązku ponawiać próby przesłania potwierdzenia. System klienta powinien jednak móc obsłużyć sytuację, w której w ramach komunikatu gateway-response otrzyma potwierdzenie tej samej wiadomości więcej niż jeden raz. 2.3.3 Ograniczenie wielkości komunikatu Ze względów wydajnościowych, w komunikatach zawierających żądania przesyłane od klienta do bramki, wprowadzone jest odgórne ograniczenie ilości elementów zawartych w części request-data. Na dzień tworzenia niniejszego dokumentu to ograniczenie wynosi 1000. W przypadku przekroczenia tego ograniczenia, bramka odpowie komunikatem ERROR i całe żądanie zostanie nieprzetworzone. 2.4 Komunikacja dwukierunkowa Do skonfigurowania komunikacji dwukierunkowej konieczne jest podanie przez klienta adresu URL, na który bramka będzie przekazywać komunikaty. Bramka będzie wówczas przesyłać komunikaty opisane w 2.2 w treści żądania HTTP POST przesłanego na wskazany przez klienta adres. Jeżeli serwer HTTP obsługujący połączenie ze strony klienta wygeneruje w odpowiedzi kod HTTP 200, to uznaje się, że dane zostały dostarczone i ich transmisja nie będzie ponawiana. 2.4.1 Odbieranie odpowiedzi na wysłane wiadomości Przekazywanie do klienta odpowiedzi na wysłane wiadomości odbywa się poprzez użycie dodatkowego typu komunikatu gateway-response incoming-sms-message. Każdy z elementów tego komunikatu reprezentuje jedną wiadomość odebraną przez system i zawiera następujące elementy: message-id liczba naturalna jednoznacznie identyfikująca przekazywaną wiadomość w systemie SMS msisdn numer telefonu, z którego odebrano wiadomość received-time moment odebrania wiadomości przez system SMS sms-text treść wiadomości 9
3. Zabezpieczenie komunikacji W celu zabezpieczenia komunikacji dostęp do bramki będzie możliwy tylko za pośrednictwem tunelu IPsec. W związku z tym w celu udostępnienia połączenia konieczne będzie określenie przez klienta adresu IP zakończenia tunelu po stronie klienta, oraz skonfigurowanie firewalla i routingu w taki sposób, żeby był możliwy dostęp do bramki SMS. 10
4. Przykłady Niniejszy rozdział zawiera przykłady związane z testowaniem i integracją API. Dla uproszczenia i maksymalnej przejrzystości przykłady nie zawierają żadnej obsługi błędów. W przykładach, które tego wymagają nie uwzględniono również specjalnego kodowania znaków specjalnych, które mogą się pojawić w treści SMS a podczas rzeczywistej eksploatacji. Autorzy rozwiązań bazujących na przykładach z tego rozdziału powinni wziąć powyższe pod uwagę. 4.1 Wysyłanie wiadomości SMS za pomoca programu wget Do przesłania bramce SMS żądania wykorzystującego API można się posłużyć programami takimi jak wget czy curl. Na przykład polecenie: wget -O- -q --post-file=req.xml http://api-test/rbroker powoduje przesłanie do serwisu testowego bramki żądania zawartego w pliku req.xml, i wypisanie na standardowym wyjściu odpowiedzi bramki. Jeżeli plik req.xml ma postać: <?xml version="1.0" encoding="utf-8"?> <gateway-request type="sms-send-request"> <request-auth> <partnerlogin>test</partnerlogin> <partnerpassword>test</partnerpassword> </request-auth> <request-data> <sms-send-request> <message-id>5</message-id> <msisdn>+48601601601</msisdn> <sms-text>przykladowy sms</sms-text> </sms-send-request> </request-data> </gateway-request> to przykładowa odpowiedź systemu będzie miała postać: <?xml version="1.0" encoding="utf-8" standalone="no"?> <gateway-response type="sms-send-response"> <sms-send-response> <message-id>5</message-id> <result>ok</result> </sms-send-response> </gateway-response> Co oznacza, że system przyjął wiadomość i będzie podejmował próby jej wysłania. 11
4.2 Wysyłanie wiadomości SMS za pomoca PHP W najprostszym przypadku wysyłanie wiadomości SMS ze skryptów PHP może odbywać się z wykorzystaniem funkcji jak np.: function sendsms($msgid, $destnumber, $text) { $h = curl_init(); $request = <?xml version="1.0" encoding="utf-8"?> <gateway-request. type="sms-send-request"> <request-auth><partnerlogin>przypominamy_test. </partnerlogin><partnerpassword>naniby</partnerpassword></request-auth>. <request-data><sms-send-request><message-id>. $msgid. </message-id>. <msisdn>. $destnumber. </msisdn><sms-text>. $text. </sms-text><confirmation-request/></sms-send-request></request-data>. </gateway-request> ; } curl_setopt($h, CURLOPT_URL, http://api-test/rbroker ); curl_setopt($h, CURLOPT_RETURNTRANSFER, true); curl_setopt($h, CURLOPT_POST, true); curl_setopt($h, CURLOPT_POSTFIELDS, $request); $rv = curl_exec($h); curl_close($h); return $rv; Wówczas wywołanie funkcji $res = sendsms(5, +48601601601, Przykladowy sms ); Spowoduje podobnie jak w przykładzie 4.1 przekazanie do systemu żądania wysłania pojedynczego SMS a. Treść odpowiedzi serwera będzie w tym przypadku zwrócona przez funkcję i dostępna w zmiennej $res. 4.3 Odbiór wiadomości przychodzacych za pomoca PHP Przykładowy skrypt PHP obsługujący żądania POST kierowane na adres URL przyjmujący po stronie klienta powiadomienia z systemu mógłby mieć postać: <?php function parseinput($input) { $doc = new DomDocument(); $doc->loadxml($input); $root = $doc->firstchild; if($root->nodename == gateway-response && $root->attributes->getnameditem( type )->value == incoming-sms-message ) { for($item = $root->firstchild; $item!= NULL; $item = $item->nextsibling) { if($item->nodename == incoming-sms-message ) { $msgdata = array(); 12
for($fld = $item->firstchild; $fld!= NULL; $fld = $fld->nextsibling) { $msgdata[$fld->nodename] = $fld->nodevalue; } } } // Tu sensowna obsługa odebranych wiadomości echo "Odebrano wiadomość #". $msgdata[ message-id ]. " z numeru ". $msgdata[ msisdn ]. " o treści: ". $msgdata[ sms-text ]. "<br/>\n"; } } $in = file_get_contents( php://input ); parseinput($in);?> 13