API - informacje ogólne

Wstecz

Słownik pojęć

Aby ułatwić komunikację, przyjęliśmy pewne nazewnictwo. Poniżej przedstawiamy przyjęte założenia:

 

Komunikat

jest to informacja o takiej samej treści wysyłana do jednego lub wielu odbiorców,

 

Wiadomość

jest to treść komunikatu, który trafia do jednego lub wielu odbiorców. Wiadomość może składać się z jednego l\ ub więcej SMSów,

 

SMS

jest to część składowa wiadomości. Wiadomość może składać się zatem z jednego lub więcej SMSów, co jest uzależnione od długości wiadomości. W dalszej części dokumentacji znajduje się tabela określająca z ilu SMSów składowych może składać się wiadomość. Jest to uzależnione bowiem nie tylko od długości wiadomości, lecz także od rodzaju użytych znaków,

 

Znaki standardowe

zbiór symboli standardowych, których użycie w wiadomościach jest traktowane jako wprowadzenie pojedynczego znaku. Są to następujące znaki:

@ £ $ ¥ è é ù ì ò Ç Ø ø Å å Δ _ Φ Γ Λ Ω Π Ψ Σ Θ Ξ Æ æ ß É ! " # ¤ % & ' ( ) * + , - . / 0 1 2 3 4 5 6 7 8 9 : ; < = > ? ¡ A B C D E F G H I J K L M N O P Q R S T U V W X Y Z Ä Ö Ñ Ü § ¿ a b c d e f g h i j k l m n o p q r s t u v w x y z ä ö ñ ü à

W skład znaków standardowych wchodzą również następujące znaki:

^ { } [ ] ~ \ | € oraz , przy czym znaki te w wiadomościach traktowane jest jako dwa znaki. Znaki specjalne wszelkie znaki nie zaliczone do znaków standardowych. Użycie w wiadomości choćby jednego znaku specjalnego oznacza, że każdy znak, w tym również znak standardowy, jest traktowany jako dwa znaki, co powoduje skrócenie długości wiadomości.

 

Znaki specjalne

wszelkie znaki nie zaliczone do znaków standardowych. Użycie w wiadomości choćby jednego znaku specjalnego oznacza, że każdy znak, w tym również znak standardowy, jest traktowany jako dwa znaki, co powoduje skrócenie długości wiadomości.

 

Kodowanie

Wszystkie komunikaty w systemie kodowane są za pomocą kodowania UTF-8. Takie kodowanie jest też wymagane dla wywołań API, aby możliwe było prawidłowe obsługiwanie znaków spoza standardowego zakresu ASCII.

 

Długość wiadomości

W zależności od liczby znaków użytych w wiadomościach oraz rodzaju znaków (znaki standardowe/niestandardowe) uzależnione jest, z ilu SMSów składowych złożona jest dana wiadomość. Co ważne, użycie w wiadomości choćby jednego znaku niestandardowego powoduje, że dana wiadomość może mieć krótszą długość.

 

Długość wiadomości (bez znaków niestandardowych) a liczba SMSów składowych

 

Długość wiadomościLiczba SMSów składowych
od 1 do 160 1
od 161 do 306 2
od 307 do 459 3
od 460 do 612 4

 

Poniższa tabela prezentuje natomiast liczbę SMSów składowych w przypadku, gdy w wysyłanej wiadomości zostanie wprowadzony choćby jeden znak niestandardowy.

 

Długość wiadomości (ze znakami niestandardowymi) a liczba SMSów składowych

 

Długość wiadomościLiczba SMSów składowych
od 1 do 70 1
od 71 do 134 2
od 135 do 201 3
od 202 do 268 4

 

Statusy końcowe operacji

Za każdym razem po wysłaniu wiadomości poprzez HTTP/SOAP SSL API, zwracany jest status wysyłki. Jest on potwierdzeniem, czy wiadomość została wysłana prawidłowo. Poniżej znajduje się lista możliwych zwracanych statusów wraz z opisem.


Status zwracane przy wysyłaniu wiadomości SMS

 

StatusOpis statusu
001 Wysłano prawidłowo
002 Wiadomość prawidłowo przekazana do wysyłki, jednak z przyczyn technicznych zostanie wysłana w późniejszym czasie (dotyczy FasterSMS)
011 Nie przekazano potrzebnych parametrów - brak danych GET/POST
021 Zły login lub hasło
022 Brak wystarczających środków na koncie do realizacji tego typu wysyłki
023 Problem z wyslaniem wiadomości. Skontaktuj się z BOK.
031 Pole nadawcy jest zbyt długie (maksymalnie 16 znaków przy nadawcy numerycznym i 11 znaków przy nadawcy alfanumerycznym)
032 Nie podałeś/-aś ani jednego adresata wiadomości lub podany adresat jest nieprawidłowy (nieprawidłowy/nieistniejący numer komórkowy lub numer stacjonarny)
033 Nie podałeś/-aś treści wiadomości
034 Podano czas z przeszłości jako preferowany czas wysyłki
035 Liczba identyfikatorów własnych jest różna od liczby odbiorców wysyłanej wiadomości
036 Został wybrany typ wiadomości MaxSMS, ale nie został określony nadawca wiadomości (maksymalnie 11 znaków alfanumerycznych)
037 Zezwalasz tylko na wysyłanie wiadomości składających się z jednego SMSa, a Twoja wiadomość jest dłuższa
038 Treść wiadomości przekracza maksymalną dozwoloną pod względem technicznym długość (więcej niż 4 SMSy składowe na wiadomość)i
039 Wybrałeś wysyłkę typu FasterSMS i równocześnie próbujesz wysłać wiadomość do więcej niż jednego adresata, co jest niedozwolone (FasterSMS służy do wysyłania pojedynczych wiadomości SMS, np. z hasłem jednorazowym)
040 Nazwa nadawcy wiadomości nie została zarejestrowana. Skontaktuj się z BOK.
080 Adres IP, z którego przyszło wywołanie API nie znajduje się na liście adresów uprawnionych do korzystania z API. Zaloguj się do Panelu SMS, aby skonfigurować ustawienia API.
041 Wiadomość zawiera znaki spoza dozwolonego zakresu znaków UTF-8.
091 Błąd połączenia z bazą. Skontaktuj się z firmą PromoSMS
092 Błąd podczas wysyłki wiadomości. Skontaktuj się z firmą PromoSMS

 

Raporty doręczenia wiadomości


Każda wiadomość może mieć przypisany jeden z czterech rodzajów statusu. Ich pełny opis znajduje się w poniższej tabeli.

 

Rodzaje statusów

 

StatusOpis statusu
0 Wiadomość nie została jeszcze przekazana do wysyłki. Taki stan możliwy jest zaraz po zleceniu wysyłki (wiadomości są przekazywane do operatora średnio co 15 sekund) lub w przypadku wiadomości, które mają być wysłane w przyszłości (parametr time przy wysyłce)
4 lub 8 Wiadomość została przekazana do operatora. W tym momencie platforma PromoSMS czeka na realizację zlecenia przez operatora. Stan nr 8 można porównać do wysłania SMS z telefonu, kiedy telefon komórkowy wysłał wiadomość, lecz nie otrzymaliśmy jeszcze potwierdzenia dostarczenia/niedostarczenia od operatora. Ponadto, jeżeli odbiorca ma na przykład wyłączony telefon, a operator próbował dostarczyć prawidłowo tę wiadomość, to także należy spodziewać się takiego stanu wiadomości
1 Status o numerze jeden oznacza, że wiadomość została dostarczona na telefon komórkowy odbiorcy
2 lub 16 Wiadomość nie została dostarczona. Przyczyn może być kilka. Najbardziej prawdopodobne to: numer odbiorcy jest nieprawidłowy telefon odbiorcy jest wyłączony przez długi czas i wiadomość wygasła

 

Typy numerów komórkowych


W tabeli poniżej znajduje się lista typów numerów rozpoznawanych przez system.

 

Opis typów numerów

 

Typ numeruOpis typu
1 Numer stacjonarny
2 Numer komórkowy
3 W niektórych krajach możliwe jest, że dany numer jest równocześnie numerem komórkowym/stacjonarnym
4 Darmowy numer
5 Number o podwyższonej płatności
6 Koszt za połączenie jest współdzielony między odbiorcą i nadawcą (np. numer typu 801..)
7 Numer VoIP
8 Numer osobisty, możliwe że jest równocześnie komórkowy jak i stacjonarny (patrz tutaj: http://en.wikipedia.org/wiki/Personal_Numbers )
9 Pager
10 tzw. Universal Access Numbers lub Company Numbers (Jeden numer firmowy, ale połączenie może być odpowiednio przełączane)
10 lub -1 Numer niepoprawny lub inny, niezidentyfikowany rodzaj numeru