BRAMKA HTTP SMS XML Dokumentacja techniczna. wersja 3.32

BRAMKA HTTP SMS XML Dokumentacja techniczna wersja 3.32 autor: Michał Jastrzębski ostatnia aktualizacja : 27.05.2015

Historia zmian Data Osoba Opis zmian 2006-12-01 Marcin Mańk Pierwsza wersja 2007-08-20 Michał Jastrzębski Zmiana akceptowanych znaków w treściach SMS 2008-04-28 Michał Jastrzębski Statusy błędów przy komunikacji PARTNER- Ebill/SmsBulk. 2008-04-29 Michał Jastrzębski Raporty doręczeń 2008-09-10 Michał Jastrzębski Błędny opis pola status przy raporcie doręczeń SMS, dodanie pola ERROR 9.12.2008 Michał Jastrzębski Dodanie informacji o ilości liczby znaków dla SMS tekstowego. 19.12.2008 Michał Jastrzębski Dodanie przykładowego formularza z wysyłką SMS 3.12.2009 Michał Jastrzębski Informacja o ilości SMS rozliczeniowych w SMS, informacja o wewn. ID serwisu w SMSach przychodzących 26.12.2010 Michał Jastrzębski Zmiana w Raporty doręczeń. 28.12.2010 Michał Jastrzębski Błędny URL w raportach doręczeń. 27.05.2015 Michał Jastrzębski Błędna nazwa pola BILL_INFO.

Cel rozwiązania Bramka umożliwia automatyzację wymiany obustronnej SMS pomiędzy Partnerem a Ebill/SmsBulk. Poniższa specyfikacja nie jest wiążąca, mogą pojawiać się nowe opcjonalne elementy w dokumentach XML, należy mieć to na uwadze przy projektowaniu i wdrażaniu usługi. Specyfikacja zakłada wykorzystanie zarówno protokołu HTTP jak i HTTPS przy wymianie infromacji. Komunikacja może być zabezpieczona zarówno poprzez dane autoryzacyjne jak i poprzez dostęp tylko z określonej podsieci IP zarówno u Partnera jak i Ebill/SmsBulk.

1. Komunikacja Ebill/SmsBulk Partner Partner udostępnia URL na który Ebill/SmsBulk przesyła dokument XML w parametrze xml metody POST. Schemat dokumentu XML: <?xml version="1.0" encoding="utf-8"?> <MESSAGES> <MESSAGE_ID>1345</MESSAGE_ID> <TYPE_ID>1</TYPE_ID> <MSISDN>48502123456</MSISDN> <LA>7666</LA> <INFO><![CDATA[ffff]]></INFO> <DATE_INFO>14324352</DATE_INFO> <BILL_COUNT>1</BILL_COUNT> <SERVICE_ID>2634564</SERVICE_ID> <OPER>I</OPER> <MESSAGE_ID>1223</MESSAGE_ID> <TYPE_ID>1</TYPE_ID> <MSISDN>48602111111</MSISDN> <LA>7777</LA> <INFO><![CDATA[ffff]]></INFO> <DATE_INFO>14324352</DATE_INFO> <OPER>E</OPER> </MESSAGES> Dokument rozpoczyna się instrukcją sterującą, która zawiera informacje o wersji standardu XML, z jakim jest zgodny, oraz o sposobie kodowania znaków. Element może być pominięty. W razie braku którejś z danych przyjmuje się wartość domyślną, jakimi są wersja 1.0 oraz standard kodowania UTF-8. Elementy MESSAGE mogą pojawiać się wielokrotnie zależnie od ruchu SMS i/lub braku komunikacji z Partnerem lub Ebill/SmsBulk nalezy dążyć do grupowania wiadomości w pojedynczym dokumencie w zapytaniu HTTP przyśpieszy to przetwarzanie większej liczby wiadomości.

Objaśnienia pól elementu MESSAGE: MESSAGE_ID TYPE_ID typ: ENUM {1} MSISDN LA typ: integer INFO typ: text DATE_INFO typ: unix timestamp OPER typ: char ID wiadomości SMS w bazie Ebill/SmsBulk. W przypadku odpowiedzi na SMS należy podać wartośc tego pola. Rodzaj wiadomości SMS: 1 - SMS tekstowy Numer telefonu abonenta w notacji międzynarodowej wiodące 48 dla Polski. Numer SMS Premium ( Large Account) W Polsce numery 4 i 5 cyfrowe 7xxxx oraz 9xxxx Treść komunikatu SMS w zależności od potrzeby może być ujęta w sekcję CDATA ( m.in dla znaków < / & itp.) Data wpłynięcia wiadomości SMS do systemu Ebill/SmsBulk zapisana w postaci znacznika czasu unix ( ilość sekund od 1970-01-01 ) Skrót operatora. Możliwe wartości: E ERA GSM I ORANGE P PLUS GSM 4 - PLAY U - NIEZNANY T NUMER TESTOWY V NUMER WIRTUALNY TESTOWY SMSy z wartością T są wysyłane przez obsługę techniczą Ebill/SmsBulk poprzez telefony GSM. Wartość V wskazuje na automat testowy po stronie bazy Ebill/SmsBulk ( jest to numer msisdn: 48 100 000 000 ) SMSy takie należy traktować jak każdy inny SMS, nie zostaną one jednak naliczone jako przychód Partnera. BILL_COUNT typ: int (opcjonalny) SERVICE_ID (opcjonalny) Ilość SMS rozliczeniowych przypadających na aktualną wiadomość. Jeśli abonent wysłał SMS ponad 160 znaków ( 80 jeśli użyto znaków spoza ASCII ) to przychodzący SMS składa się de facto z kilku oddzielnych SMS, które są składane w jedną całość. Pole to zawiera informację z ilu części złożono docelowy SMS liczba części określa krotność opłaty jaka została pobrana od abonenta dla danej taryfy. Wewnętrzne ID serwisu po stronie Ebill/SmsBulk może być przydatne w celu odróżnienia kilku serwisów na tym samym LA przy odsyłaniu wiadomości zwrotnych.

Partner po otrzymaniu dokumentu XML od Ebill/SmsBulk MUSI potwierdzić jego otrzymanie poprzez wyświetlenie w odpowiedzi poniższego dokumentu XML Schemat odpowiedzi XML: <?xml version="1.0" encoding="utf-8"?> <RESPONSE> <MESSAGE_ID>1345</MESSAGE_ID> <STATUS>OK</STATUS> <MESSAGE_ID>1223</MESSAGE_ID> <STATUS>ERROR</STATUS> </RESPONSE> Objaśnienia pól elementu MESSAGE : MESSAGE_ID STATUS typ: text ID wiadomości SMS w bazie Ebill/SmsBulk. Status przetworzenia wiadomości SMS. Możliwe statusy: OK - wiadomość odebrana przez Partnera ERROR wiadomośc nieodebrana, ponów wysyłkę. Ebill/SmsBulk będzie ponawiał wysyłkę danego SMS do momentu kiedy nie otrzyma w STATUS wiadomości OK. WAŻNE! W PRZYPADKU KIEDY NASTĘPUJE POWTÓRZENIE id wiadomości (MESSAGE_ID) PARTNER MUSI ODPOWIEDZIEĆ OK W STATUSIE WIADOMOŚCI, JEDNOCZEŚNIE ZAPRZESTAJĄC DALSZEGO PRZETWARZANIA TEJ WIADOMOŚCI.ZAPOBIEGA TO POWTÓRZENIOM ZWIĄZANYM Z TIMEOUTAMI SPOWODOWANYMI BŁĘDAMI SIECI.

2. Komunikacja Partner Ebill/SmsBulk Partner wysyła na URL : https://smsgw.ebill.pl/xml/in.php dokument XML w parametrze xml metody POST. W celu autoryzacji wymagane są 2 parametry : login oraz password w metodzie GET. Dodatkowo przy uruchamianiu usługi można podać dozwoloną klasę adresową IP Partnera, z której będzie wywoływany URL po stronie Ebill/SmsBulk. Schemat dokumentu XML: <?xml version="1.0" encoding="utf-8"?> <MESSAGES> <MESSAGE_ID>1345</MESSAGE_ID> <TYPE_ID>1</TYPE_ID> <MSISDN>48502123456</MSISDN> <LA>7666</LA> <INFO><![CDATA[ffff]]></INFO> <DATE_INFO>14324352</DATE_INFO> <INCOMING_ID>321412</INCOMING_ID> <MESSAGE_ID>1223</MESSAGE_ID> <TYPE_ID>2</TYPE_ID> <MSISDN>48602111111</MSISDN> <LA>7777</LA> <INFO><![CDATA[http://onet.pl/l,NAZWA]]></INFO> <DATE_INFO>14324352</DATE_INFO> <INCOMING_ID>321412</INCOMING_ID> </MESSAGES> Dokument rozpoczyna się instrukcją sterującą, która zawiera informacje o wersji standardu XML, z jakim jest zgodny, oraz o sposobie kodowania znaków. Element może być pominięty. W razie braku którejś z danych przyjmuje się wartość domyślną, jakimi są wersja 1.0 oraz standard kodowania UTF-8. Elementy MESSAGE mogą pojawiać się wielokrotnie zależnie od ruchu SMS i/lub braku komunikacji z Partnerem lub Ebill/SmsBulk nalezy dążyć do grupowania wiadomości w pojedynczym dokumencie w zapytaniu HTTP przyśpieszy to przetwarzanie większej liczby wiadomości.

Objaśnienia pól elementu MESSAGE: MESSAGE_ID TYPE_ID typ: ENUM {1,2} MSISDN LA typ: integer ID wiadomości SMS w bazie Partnera. Rodzaj wiadomości SMS: 1 - SMS tekstowy 2 - Wap push Numer telefonu abonenta w notacji międzynarodowej wiodące 48 dla Polski. Numer SMS Premium ( Large Account) W Polsce numery 4 i 5 cyfrowe 7xxxx oraz 9xxxx Jeżeli wysyłka następuje poprzez system SMSBULK pole to może zawierać znaki alfanumeryczne do 11 znaków. INFO typ: text Dla TYPE_ID=1 (TEXT SMS) : Treść komunikatu SMS w zależności od potrzeby może być ujęta w sekcję CDATA ( m.in dla znaków < / & itp.) Długość ciągu znaków nie może przekroczyć 160 znaków. Dla TYPE_ID=2 (WAP PUSH): Należy podać URL do obiektu oraz jego nazwę w formacie URL,nazwa. URL nie może zawierać przecinków (,) Długość takiego ciągu nie może przekroczyć 120 znaków. DATE_INFO typ: unix timestamp INCOMING_ID Data wysłania wiadomości SMS przez Ebill/SmsBulk zapisana w postaci znacznika czasu unix ( ilość sekund od 1970-01-01 ). Jeżeli czas zostanie podany w przyszłości SMS zostanie zakolejkowany do wysyłki w podanym terminie. ID wiadomości na którą dany SMS jest odpowiedzią zwrotną w ramach limitu SMS zwrotnych. Jeżeli dany SMS nie jest odpowiedzią lub jest wiadomością wysyłaną poprzez system SMSBULK w pole to należy wstawić wartość : -1.

Ebill/SmsBulk po otrzymaniu dokumentu XML od Partnera potwierdza jego otrzymanie poprzez wyświetlenie w odpowiedzi poniższego dokumentu XML. W przypadku błędów po stronie baz danych Ebill/SmsBulk może zostać wygenerowany status 500 HTTP. Schemat odpowiedzi XML: <?xml version="1.0" encoding="utf-8"?> <RESPONSE> <MESSAGE_ID>1345</MESSAGE_ID> <STATUS>OK</STATUS> <MESSAGE_ID>1223</MESSAGE_ID> <STATUS>ERROR</STATUS> <ERROR>NO SUCH INCOMING ID</ERROR> </RESPONSE> Objaśnienia pól elementu MESSAGE : MESSAGE_ID STATUS typ: text ERROR typ: text ID wiadomości SMS Partnera. Status przetworzenia wiadomości SMS. Możliwe statusy: OK - wiadomość odebrana przez Ebill/SmsBulk ERROR wiadomośc nieodebrana, ponów wysyłkę. Pole opcjonalne zawierające opis błędu jeśli w STATUS jest ERROR, jedyny wyjątek to powtórzenie wiadomości M.in. : ILLEGAL CHAR FOUND REPLY LIMIT EXCEEDED BAD MSISDN BAD LA MESSAGE TOO LONG REPLY ( mimo, że STATUS=OK ) NO SUCH INCOMING ID BAD SERVICE ID Partner będzie ponawiał wysyłkę danego SMS do momentu kiedy nie otrzyma w STATUS wiadomości OK.

WAŻNE! W PRZYPADKU KIEDY NASTĘPUJE POWTÓRZENIE ID wiadomości (MESSAGE_ID) Ebill/SmsBulk ODPOWIADA OK W STATUSIE WIADOMOŚCI, JEDNOCZEŚNIE ZAPRZESTAJĄC DALSZEGO PRZETWARZANIA TEJ WIADOMOŚCI. ZAPOBIEGA TO POWTÓRZENIOM ZWIĄZANYM Z TIMEOUTAMI SPOWODOWANYMI BŁĘDAMI SIECI.

3. Raporty doręczeń Partner wysyła na URL : https://smsgw.ebill.pl/xml/dlr.php dokument XML w parametrze xml metody POST. W celu autoryzacji wymagane są 2 parametry : login oraz password w metodzie GET. Są one identyczne jak dla punktu 2 ( komunikacja Partner-Ebill/SmsBulk) Schemat dokumentu XML: <?xml version="1.0" encoding="utf-8"?> <REQUEST> <MESSAGE_ID_FROM>1234345</MESSAGE_ID_FROM> <MESSAGE_ID_TO>1234349</MESSAGE_ID_TO> <DT_FROM>1432234349</DT_FROM> <DT_TO>1432234349</DT_TO> </REQUEST> Dokument rozpoczyna się instrukcją sterującą, która zawiera informacje o wersji standardu XML, z jakim jest zgodny, oraz o sposobie kodowania znaków. Element może być pominięty. W razie braku którejś z danych przyjmuje się wartość domyślną, jakimi są wersja 1.0 oraz standard kodowania UTF-8. Objaśnienia pól elementu REQUEST: MESSAGE_ID_FROM MESSAGE_ID_TO DT_FROM typ: unix timestamp DT_TO typ: unix timestamp Początkowe ID wiadomości SMS w bazie Partnera. Końcowe ID wiadomości SMS w bazie Partnera. Początkowa data pomyślnego przesłania wiadomości SMS przez Partnera do Ebill/SmsBulk zapisana w postaci znacznika czasu unix ( ilość sekund od 1970-01-01 ). Końcowa data pomyślnego przesłania wiadomości SMS przez Partnera do Ebill/SmsBulk zapisana w postaci znacznika czasu unix ( ilość sekund od 1970-01-01 )

Wymagana jest jedna para parametrów ( MESSAGE_ID_FROM, MESSAGE_ID_TO lub DT_FROM, DT_TO ). W przypadku podania zarówno ID wiadomości jak i czasu będą brane pod uwagę obydwa pasujące warunki ( zależność czasowa jak i id wiadomosci ). Ebill/SmsBulk po otrzymaniu dokumentu XML od Partnera potwierdza jego otrzymanie poprzez wyświetlenie w odpowiedzi poniższego dokumentu XML. W przypadku błędów po stronie baz danych Ebill/SmsBulk może zostać wygenerowany status 500 HTTP. Schemat odpowiedzi XML: <?xml version="1.0" encoding="utf-8"?> <DELIVERY> <MESSAGE_ID>1345</MESSAGE_ID> <STATE_ID>1</STATE_ID> <STATUS>Wiadomosc wyslana</status> <DT_STATE>134534758</DT_STATE> <ERROR>Komunikat</ERROR> </DELIVERY> Objaśnienia pól elementu MESSAGE : MESSAGE_ID ID wiadomości SMS Partnera. STATE_ID typ: int STATUS typ: text DT_STATE typ: unix timestamp ERROR typ: text Status numeryczny wiadomości: 0 - Wiadomość nieprzetworzona 1 - Wiadomość wysłana do SMSC 2 - Wiadomość dostarczona 3 - Upłynął termin ważności SMS 4 - Błąd podczas wysyłki do SMSC. 5 - Nieprawidłowy numer telefonu Status tekstowy wiadomości: Wiadomosc nieprzetworzona Wiadomosc wyslana do SMSC Wiadomosc dostarczona Uplynal termin waznosci SMS Blad podczas wysyłki do SMSC. Nieprawidlowy numer telefonu Data zmiany statusu na obecny tylko dla STATE_ID : 1 i 2 Pole występujące w przypadku wystąpienia wyjątku np.: SERVICE EXPIRED

ERROR IN PARSING INPUT XML

Dozwolone znaki w treściach SMS litery : A-Z ( kody ASCII: 65-90 ) a-z ( kody ASCII: 97-122 ) cyfry: 0-9 ( kody ASCII: 48-57 ) znaki specjalne: Kod ASCII Znaczenie 32 Space (odstęp) 33! 34 " 35 # 36 $ 37 % 38 & 40 ( 41 ) 42 * 43 + 44, 45-46. 47 / 58 : 59 ; 60 < 61 = 62 > 63? 64 @ 95 _

Przykładowy kod formularza w języku PHP: <?php if ( isset($_post['form_submit']) ) { echo "WYSYLANIE SMS"; $message_id=time();//moze to być jakikolwiek unikalny identyfikator $xml = array ( 'xml' => ' <MESSAGES> <MESSAGE_ID>'.$message_id.'</MESSAGE_ID> <TYPE_ID>1</TYPE_ID> <MSISDN>48'.(int) $_POST['phone'].'</MSISDN> <LA>NADAWCA</LA> <INFO><![CDATA['.$_POST['message'].']]></INFO> <DATE_INFO>'. time().'</date_info> <INCOMING_ID>-1</INCOMING_ID> </MESSAGES> ' ); $ch=curl_init(); $service_id="login"; $password="haslo"; curl_setopt($ch,curlopt_url,"https://smsgw.ebill.pl/xml/in.php? service_id={$service_id}&password={$password}"); curl_setopt($ch,curlopt_header,true); curl_setopt($ch,curlopt_postfields,$xml); curl_setopt($ch,curlopt_returntransfer,1); $result=curl_exec($ch); curl_close($ch); } else {?> <form action="" method="post"> Telefon: +48 <input type="text" name="phone"/> <br/> Tresc: <input type="text" name="message"/> <br/> <input type="submit" name="form_submit" value="wyslij"/> </form> <? }?>