REST API

Wstecz

Poniższa dokumentacja odnosi się do REST API w wersji 3.0. 

Jeżeli Twoje konto rozliczane jest w systemie złotówkowym, a nie punktowym, korzystasz z HTTPS API w wersji 2.0.

Wprowadzenie

 

REST API dostępne jest pod adresem https://promosms.com/api/rest/

Ponadto, aby zwiększyć poziom bezpieczeństwa systemu, udostępniamy zapasowe API dostępne pod adresem https://backup2.promosms.com/api/rest/

Każde żądanie składa się z adresu API, nazwy akcji oraz zakodowanego w base64 loginu i hasła, oddzielonych znakiem dwukropka. Opcjonalnie można wskazać w jakim formacie ma zostać zwrócona odpowiedź. Ponadto większość akcji wymaga dodatkowych parametrów, przekazywanych w adresie URL (metoda GET) lub w nagłówku żądania (metoda POST).

Kodowania loginu i hasła do postaci base64 można dokonać na przykład w języku PHP przy użyciu poniższej konstrukcji:

 

 

base64_encode($login . ':' . $password)

 

Składnia żądań REST API

View source
api_url/action_name/login_password[/format][?parameters]

 

Przykładowe wywoływanie metody send

View source
https://promosms.com/api/rest/send-sms/bG9naW46cGFzc3dvcmQ=/json?text=Test%20message&type=3&recipients[]=500000001&recipients[]=500000002&sender=InfoSMS&special-chars=1&long-sms=1&date=1451602800&delivery-url=http%3A%2F%2Fexample.com%2Fsmsid%3D%25smsID%26report%3D%25report&user-index[]=testmsg1&user-index[]=testmsg2

W powyższym przykładzie dla czytelności oddzielono parametry znakiem nowej linii. Nie należy ich jednak stosować przy wywoływaniu żądań REST

 

https://promosms.com/api/rest/send/bG9naW46cGFzc3dvcmQ= - adres REST API

https://promosms.com/api/rest/send/bG9naW46cGFzc3dvcmQ= - funkcja

https://promosms.com/api/rest/send/bG9naW46cGFzc3dvcmQ= - zakodowane w base64 login i hasło (oddzielone dwukropkiem)



Opcjonalnie można także dodać parametr formatu odpowiedzi (domyślnie text):
https://promosms.com/api/rest/send/bG9naW46cGFzc3dvcmQ=/json

 

Kody odpowiedzi:

 

Statusy wykonania metody są indywidualne dla każdej metody (dotyczy kodów 1-399)

  • 0 - operacja przebiegła pomyślnie
  • 00 00012 (110) - 11 11112 (6310) - wykonano z ostrzeżeniami. Ostrzeżenia zapisywane są na pojedynczych bitach i jednocześnie może wystąpić więcej niż jedno
  • 100-199 - wystąpił błąd - nie przekazano wszystkich wymaganych danych
  • 200-299 - wystąpił błąd - wartości przekazanych danych są niepoprawne
  • 300-399 - wystąpił błąd - konfiguracja konta lub systemu nie pozwala na wykonanie operacji
  • 400 - błąd uwierzytelniania, którego przyczyną może być:
    • niepoprawna para login / hasło
    • IP nie znajduje się na liście autoryzowanych adresów
    • przekroczono limit prób logowania (5 prób na 15 minut)
  • 401 - 403 - nieoczekiwany błąd

 

Wysyłanie wiadomości SMS

 

Wysyłka wiadomości SMS odbywa się przy użyciu funkcji send-sms

 

https://promosms.com/api/rest/send-sms

 

Dostępne metody wywołania: POST, GET

Parametry wejściowe:

  • text - string - treść wysyłanej wiadomości
  • type - integer - typ wysyłanego SMSa. Dozwolone typy to:
    • 0 - FlashSMS
    • 1 - EkoSMS
    • 3 - MaxSMS
    • 4 - FasterSMS
  • recipients[] - string[] - tablica odbiorców wiadomości. W tablicy stringów mają znajdować się więc numery telefonów odbiorców wiadomości (każdy element tablicy to kolejny odbiorca)
  • sender - string (opcjonalny) - nazwa nadawcy SMSa (wyświetlana zamiast numeru telefonu). Aby korzystać z własnej nazwy nadawcy należy ją wcześniej zarejestrować. W przypadku EkoSMS/FlashSMS parametr ten jest opcjonalny
  • special-chars - boolean (opcjonalny) - ustawienie tej wartości na 1 spowoduje, że znaki specjalne nie będą zamieniane na odpowiadające im znaki standardowe, lecz wiadomość zostanie wysłana w postaci przekazanej do systemu. Warto jednak pamiętać, że przekazywanie w treści SMSa znaków specjalnych powoduje, że długość SMS’a zmniejsza się ze standardowych 160 znaków do 70. Jeżeli zatem chcemy, aby platforma PromoSMS usuwała wszelkie niestandardowe znaki (znaki specjalne), należy podać wartość tej zmiennej ustawioną na 0
  • long-sms - boolean (opcjonalny) - ustawienie tej wartości na 1 powoduje, że przez platformę są przyjmowane do wysyłki także wiadomości dłuższe niż 160 znaków (lub 70 w przypadku zmiennej special-chars ustawionej na 1). Takie wiadomości będą dostarczone jako jedna całość (potocznie: jako jeden SMS), ale należy liczyć się z wyższym kosztem wysyłki (uzależniony od liczby wiadomości składowych)
  • date - integer (opcjonalny) - znacznik czasowy określający moment kiedy wiadomość ma zostać wysłana (unixowy znacznik czasowy wyrażony w sekundach)
  • delivery-url - string (opcjonalny) - adres URL serwera użytkownika, na który mają być przekazywane raporty dostarczenia wiadomości. W adresie URL mogą być podane następujące zmienne specjalne, które zostaną zastąpione odpowiednią wartością przez system podczas przesyłania raportu na serwer klienta:
    • %smsID - ID wysłanej wiadomości
    • %timestamp - data raportu w postaci unixowego znacznika czasu
    • %number - numer na jaki została wysłana wiadomość
    • %report - ID raportu (1 oznacza dostarczone)
    • %ownID - identyfikator własny użytkownika
  • user-indexes[] - string[] (opcjonalny) - parametr pozwala użytkownikowi zdefiniować własne identyfikatory wiadomości. Liczba elementów tablicy/wektora musi być równa liczbie zdefiniowanych odbiorców wiadomości. Wówczas każdej wiadomości, będzie przyporządkowany kolejny element z tej tablicy. Możliwe jest również zdefiniowanie jednego elementu dla tej tablicy/wektora, aby wszystkim wysłanym wiadomościom był przypisany ten sam identyfikator
  • return-send-recipients - boolean (opcjonalny) - flaga określająca, czy w odpowiedzi mają zostać zwrócone szczegóły dotyczące każdego adresata

 

Odpowiedź:

 

W przypadku wybrania formatu odpowiedzi XML lub JSON, wynik jest zgodny z poniższym schematem:

  • status (integer)
  • points (integer)
  • sent-sms-count (integer)
  • content-id (integer)
  • recipients-results
    • recipient-result[]
      • recipient (string)
      • sms-id (string)
      • own-id (string)
      • status (integer)

 

Ponadto dokument XML jest zgodny z poniższą definicją XSD:

https://promosms.com/api/rest/send-sms.xsd

 

  • status - kod odpowiedzi
  • points - koszt zrealizowanej wysyłki (wyrażony w punktach)
  • sent-sms-count - liczba pomyślnie wysłanych wiadomości
  • content-id - identyfikator treści wysyłki
  • recipients-results[] - szczegółowe informacje o wysyłce (jeżeli ustawiono parametr wejściowy return-recipient-results na 1)
    • recipient - numer telefonu adresata
    • sms-id - indywidualny identifykator wiadomości
    • own-id - identyfikator nadany przez użytkownika
    • status - status przekazania wiadomości (0 - przekazano, 210 - niepoprawny numer)

 

Statusy końcowe funkcji send-sms:

 

KodOpis
012 (110) Wiadomość została przekazana do późniejszej wysyłki
102 (210) Część podanych numerów telefonów jest niepoprawna
100 Nie podano adresatów wysyłki
101 Nie podano treści
102 Nie podano pola nadawcy
103 Nie podano pola UDH
104 Nie podano ani jednego obiektu Message
200 Wszystkie podane numery telefonów są niepoprawne
201 Nazwa nadawcy jest za długa
202 Nie można wysłać wiadomości w przeszłość
203 Liczba własnych identyfikatorów jest niezgodna z liczbą odbiorców
204 Wiadomość jest dłuższa niż 1 sms
205 Wiadomość jest dłuższa niż 4 sms’y (maksimum)
206 Podano więcej niż jednego adresata wysyłki FasterSMS
207 Treść zawiera znaki spoza zbioru Unicode
208 Jedna wysyłka zawiera adresatów z różnych krajów
209 Niepoprawny typ wiadomości
300 Stan konta nie pozwala na zrealizowanie wysyłki
301 Nazwa nadawcy nie została zarejestrowana
302 Nie można wysłać tego typu wiadomości do wybranego kraju
303 Konto nie zostało przystosowane do korzystania z tej wersji API

 

Przykład:

https://promosms.com/api/rest/send-sms/bG9naW46cGFzc3dvcmQ=/xml?text=Lorem+ipsum+dolor+sit+amet&type=1&recipients[]=500000001&recipients[]=500000002

 

Raporty dostarczenia

 

Aby odpytać system o stan wysłanych wiadomości, można użyć funkcji get-reports

 

https://promosms.com/api/rest/get-reports

 

Dostępna metoda wywołania: GET

Parametry wejściowe:

 

  • indexes[] - strong[] (opcjonalny) - tablica identyfikatorów wiadomości. W zależności od wartości pola index-type, są to identyfikatory smsId, własne identyfikatory użytkownika (userIndex) lub identyfikatory treści (contentId)
  • from-time - integer (opcjonalny) - czas (w postaci uniksowego znacznika czasu), od którego momentu chcemy pobrać informację o statusach wysłanych wiadomości
  • to-time - integer (opcjonalny) - czas (w postaci uniksowego znacznika czasu), do którego momentu chcemy pobrać informację o statusach wysłanych wiadomości
  • index-type - integer (opcjonalny) - rodzaj identyfikatora
    • 0 - smsId
    • 1 - userIndex
    • 2 - contentId
  • limit - integer (opcjonalny) - opcja przydatna w przypadku, kiedy trzeba pobrać dużą liczbę statusów (np. kilkadziesiąt tysięcy). Wówczas możemy ograniczyć liczbę zwracanych elementów w tablicy.
  • offset - integer (opcjonalny) - pole to określa, od jakiego momentu ma być zwracana tablica. Wartość tego pola brana jest pod uwagę tylko w momencie zastosowania parametru limit

 

Odpowiedź:

 

W przypadku wybrania formatu odpowiedzi XML lub JSON, wynik jest zgodny z poniższym schematem:

 

  • status (integer)
  • reports
    • report[]
      • recipient (string)
      • sms-id (string)
      • own-id (string)
      • content-id (integer)
      • status (integer)
      • last-update-time (integer)

 

Ponadto dokument XML jest zgodny z poniższą definicją XSD:

 

https://promosms.com/api/rest/get-reports.xsd

 

  • status - kod odpowiedzi
  • reports[] - tablica raportów
    • recipient - numer telefonu adresata wiadomości
    • sms-id - unikalny identyfikator wiadomości
    • own-id - identyfikator nadany przez użytkownika
    • content-id - identyfikator treści
    • status - stan wysyłki
      • 0 - wiadomość oczekuje na wysłanie
      • 4, 8 - wiadomość została wysłana
      • 1 - wiadomość została dostarczona do odbiorcy
      • 2, 16 - wiadomość nie została dostarczona - najczęstsze przyczyny tego statusu to niepoprawny numer telefonu lub brak aktywności telefonu adresata przez zbyt długi okres czasu
    • lastUpdateTime - czas ostatniej aktualizacji statusu

 

Statusy końcowe funkcji get-reports:

 

KodOpis
012 (110) Część identyfikatorów wiadomości jest niepoprawna
100 Nie określono typu identyfikatora
101 Nie podano identyfikatorów wiadomości
200 Wszystkie podane identyfikatory są niepoprawne
201 Niepoprawny znacznik czasowy
202 Niepoprawny typ identyfikatora
203 Niepoprawna wartość parametru “limit”
204 Niepoprawna wartość parametru “offset”

 

Przykład:

 

https://promosms.com/api/rest/get-reports/bG9naW46cGFzc3dvcmQ=/xml?from-time=1433109600&to-time=1435701600

 

Odbieranie odpowiedzi

 

W przypadku realizacji wysyłki EkoSMS, istnieje możliwość, aby odbiorca wiadomości odpowiedział na nią. Odpowiedzi takie dostępne są zarówno przez Panel SMS jak i poprzez REST API.

 

Odbiór wiadomości odbywa się poprzez wywołanie metody get-inbox

 

https://promosms.com/api/rest/get-inbox

 

Dostępna metoda wywołania: GET

 

Parametry wejściowe:

 

  • last-message-id - integer (opcjonalny) - każda odebrana wiadomość SMS ma swój unikalny identyfikator w postaci liczby. Jeżeli chcemy odbierać wiadomość tylko od danej wiadomości o znanym nam identyfikatorze - należy go tutaj podać. Jeżeli więc wcześniej przy odbiorze wiadomości ostatnia odczytana wiadomość miała numer 359 i teraz chcemy, aby funkcja zwróciła tylko nowsze wiadomości - to jako wartość tego parametru należy podać 359.
  • from-time - integer (opcjonalny) - jeżeli zamiast podawania identyfikatora wiadomości chcemy pobrać wszystkie wiadomości od danego momentu to należy go tutaj podać w postaci uniksowego znacznika czasu.
  • content-id - integer (opcjonalny) - jeżeli ten parametr jest ustawiony, zwracane są odpowiedzi jedynie na wiadomości o podanym identyfikatorze treści
  • sms-id - string (opcjonalny) - unikalny identyfikator wiadomości
  • own-id - string (opcjonalny) - identyfikator wiadomości nadany przez użytkownika

 

Odpowiedź:

 

W przypadku wybrania formatu odpowiedzi XML lub JSON, wynik jest zgodny z poniższym schematem:

 

  • status (integer)
  • inbox-messages
    • inbox-message[]
      • message-id (integer)
      • sender (string)
      • message (string)
      • original-message (string)
      • receive-time (integer)

 

Ponadto dokument XML jest zgodny z poniższą definicją XSD:

 

https://promosms.com/api/rest/get-inbox.xsd

 

  • status - kod odpowiedzi
  • inbox-messages[] - tablica odpowiedzi
    • message-id - identyfikator odpowiedzi
    • sender - numer telefonu osoby przesyłającej odpowiedź
    • message - treść odpowiedzi
    • original-message - treść wiadomości, której dotyczy odpowiedź
    • receive-time - czas otrzymania wiadomości (w postaci uniksowego znacznika czasowego)

 

Statusy końcowe funkcji get-inbox:

 

KodOpis
012 (110) Brak nowych odpowiedzi
200 Niepoprawny identyfikator odpowiedzi
201 Niepoprawny znacznik czasowy
202 Niepoprawny identyfikator treści

 

Przykład:

 

https://promosms.com/api/rest/get-inbox/bG9naW46cGFzc3dvcmQ=/xml?from-time=1433109600

 

Sprawdzanie stanu konta

 

Sprawdzanie stanu konta odbywa się poprzez wywołanie metody get-balance

 

https://promosms.com/api/rest/get-balance

 

Dostępna metoda wywołania: GET

 

Funkcja nie przyjmuje dodatkowych parametrów wejściowych.

 

Odpowiedź:

 

W przypadku wybrania formatu odpowiedzi XML lub JSON, wynik jest zgodny z poniższym schematem:

 

  • status (integer)
  • points-available (integer)
  • points-blocked (integer)
  • points-credit (integer)

 

Ponadto dokument XML jest zgodny z poniższą definicją XSD:

 

https://promosms.com/api/rest/get-balance.xsd

 

  • status - kod odpowiedzi
  • points-available - liczba dostępnych do wykorzystania punktów
  • points-blocked - liczba zablokowanych punktów (w wyniku zaplanowania wysyłki)
  • points-credit - liczba przyznanych punktów kredytowych

 

Statusy końcowe funkcji get-balance:

 

KodOpis
300 Konto nie jest przystosowane do korzystania z tej wersji API

 

Przykład:

 

https://promosms.com/api/rest/get-balance/bG9naW46cGFzc3dvcmQ=/xml

 

Konwertowanie wiadomości

 

Wiadomość przy wysyłce jest konwertowana do standardu GSM, a następnie obliczana jest liczba wiadomości składowych oraz koszt realizacji takiej wysyłki. Konwersja taka odbywa się poprzez wywołanie funkcji convert-message.

 

https://promosms.com/api/rest/convert-message

 

Dostępna metoda wywołania: GET

 

Parametry wejściowe:

 

  • text - string - treść wiadomości, na podstawie której ma być obliczona liczba znaków oraz liczba SMSów składowych
  • special-chars - boolean - jeżeli parametr przyjmie wartość true, wówczas znaki specjalne są dozwolone w wiadomości i nie zostaną zastąpione odpowiednikami w znakach standardowych. Jeżeli natomiast zostanie ustawiona wartość false, wówczas wszelkie znaki specjalne zostaną przekonwertowane i dopiero wówczas zostanie obliczona długość wiadomości i liczba SMSów składowych.
  • long-sms - boolean (opcjonalny) - jeżeli pole to przyjmie wartość false, wiadomość zostanie przycięta do długości jednej wiadomości sms.
  • sms-type - integer (opcjonalny) - rodzaj wiadomości SMS. Jeżeli pole to, wraz z jednym z pól country-code / country-prefix / country-name nie są puste, w odpowiedzi zostanie zawarty koszt wysłania tej wiadomości do pojedynczego adresata
    • 0 - FlashSMS
    • 1 - EkoSMS
    • 3 - MaxSMS
    • 4 - FastSMS
  • country-code - string (opcjonalny) - kod kraju odbiorcy w postaci dwóch liter
  • country-prefix - string (opcjonalny) - prefiks kraju odbiorcy
  • country-name - string (opcjonalny) - nazwa kraju odbiorcy

 

Odpowiedź:

 

W przypadku wybrania formatu odpowiedzi XML lub JSON, wynik jest zgodny z poniższym schematem:

 

  • status (integer)
  • chars-number (integer)
  • sms-parts (integer)
  • text (string)
  • points (float)

 

Ponadto dokument XML jest zgodny z poniższą definicją XSD:

 

https://promosms.com/api/rest/convert-message.xsd

 

  • status - kod odpowiedzi
  • chars-number - łączna liczba znaków wiadomości
  • sms-parts - liczba SMSów składowych
  • text - treść wiadomości. Jeżeli w parametrach wejściowych bSpecialChars przyjęło wartość false, to wówczas zostanie tutaj zwrócona nie oryginalna treść wiadomości, lecz wiadomość przekonwertowana
  • points - obliczony koszt wysyłki (jeżeli w żądaniu określono typ wiadomości oraz kraj wysyłki)

 

Statusy końcowe funkcji convert-message:

 

KodOpis
100 Nie podano treści
101 Nie podano typu wiadomości SMS
200 Zbyt długa wiadomość (nie mieści się w ramach 4 wiadomości składowych)
201 Podano różne kraje wysyłki
202 Podany kraj wysyłki nie istnieje
300 Wysyłka tego typu wiadomości do podanego kraju jest niedostępna

 

Przykład:

 

https://promosms.com/api/rest/convert-message/bG9naW46cGFzc3dvcmQ=/xml?text=Puść+mą+dłoń!+Gnij+schab,+frytkę!+Zwóź+żel!&special-chars=0

 

Sprawdzanie poprawności numerów

 

Funkcja validate-numbers umożliwia sprawdzanie poprawności numeru pod względem składniowym. Sprawdzane jest więc, czy np. numer 504304204 ma poprawną formę i jest możliwym numerem.

 

https://promosms.com/api/rest/validate-numbers

 

Dostępna metoda wywołania: GET

 

Parametry wejściowe:

 

  • country-prefix - prefiks kraju z którego inicjowane jest połączenie. Dla przykładu, jeżeli jest to “48”, to następujące numery są traktowane jako numery polskie: “512345678”, “48512345678”, “+48512345678”, w dodatku jest to ten sam numer zapisany w różny sposób. Jeżeli natomiast pole to przyjmie wartość “49”, to tylko ostatni z przykładów jest potraktowany jako numer polski.
  • numbers[] - tablica numerów telefonów. Jeżeli numer posiada inny prefiks kraju niż określony w polu country-prefix, należy użyć symbolu “+” (plus)

 

Odpowiedź:

 

W przypadku wybrania formatu odpowiedzi XML lub JSON, wynik jest zgodny z poniższym schematem:

 

  • status (integer)
  • numbers
    • number[]
      • original-number (string)
      • is-valid (boolean)
      • is-valid-for-region (boolean)
      • probably-exists (boolean)
      • country-prefix (string)
      • country-code (string)
      • formatted (string)
      • type (integer)

 

Ponadto dokument XML jest zgodny z poniższą definicją XSD:

 

https://promosms.com/api/rest/validate-numbers.xsd

 

  • status - kod odpowiedzi
  • numbers[] - tablica ze szczegółowymi informacjami o numerze telefonu
    • original-number - postać w jakiej numer został podany w żądaniu
    • is-valid - flaga określająca, czy numer jest poprawny
    • is-valid-for-region - flaga określająca, czy numer należy do podanej strefy prefiksowej
    • probably-exists - flaga określająca, czy numer jest prawdopodobnie prawdziwy
    • country-prefix - prefiks kraju
    • country-code - kod kraju w postaci dwóch liter
    • formatted - numer telefonu z prefiksem kraju
    • type - typ numeru telefonu:
      • 0 - Numer stacjonarny
      • 1 - Numer komórkowy
      • 2 - Numer stacjonarny lub komórkowy
      • 3 - Darmowy numer (np. numer typu 800...)
      • 4 - Number o podwyższonej płatności
      • 5 - Koszt za połączenie jest współdzielony między odbiorcą i nadawcą (np. numer typu 801...)
      • 6 - Numer VoIP
      • 7 - Numer osobisty, możliwe że jest równocześnie komórkowy jak i stacjonarny (patrz: http://en.wikipedia.org/wiki/Personal_Numbers )
      • 8 - Pager
      • 9 - 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

 

Statusy końcowe funkcji validate-numbers:

 

KodOpis
012 (110) Niektóre z podanych numerów są niepoprawne
102 (210) Wszystkie podane numery są niepoprawne
100 Nie podano ani jednego numeru telefonu

 

Przykład:

 

https://promosms.com/api/rest/validate-numbers/bG9naW46cGFzc3dvcmQ=/xml?country-prefix=48&numbers[]=504304204

 

Dodawanie kontaktów

 

REST API umożliwia dodawanie kontaktów do Książki Adresowej za pomocą funkcji add-contacts

 

https://promosms.com/api/rest/add-contacts

 

Dostępna metoda wywołania: POST

 

Parametry wejściowe:

 

  • contacts[] - string[] - tablica numerów telefonów
  • groups[] - string[] - tablica identyfikatorów grup kontaktów
  • create-groups-if-not-exist - boolean - flaga określająca czy utworzyć nową grupę w przypadku gdy podana w polu “groups” wartość nie istnieje jeszcze w systemie

 

Odpowiedź:

 

W przypadku wybrania formatu odpowiedzi XML lub JSON, wynik jest zgodny z poniższym schematem:

 

  • status (integer)
  • contacts-count (integer)

 

Ponadto dokument XML jest zgodny z poniższą definicją XSD:

 

https://promosms.com/api/rest/add-contacts.xsd

 

  • status - kod odpowiedzi
  • contacts-count - liczba dodanych kontaktów

 

Statusy końcowe funkcji add-contacts

 

KodOpis
100 Nie podano kontaktów
101 Brak numeru telefonu w kontakcie
200 Niepoprawne numery telefonów
300 Konto nie ma ustalonego domyślnego kraju wysyłki

 

Przykład:

 

https://promosms.com/api/rest/validate-numbers/bG9naW46cGFzc3dvcmQ=/xml?contacts[]=504304204&groups[]=klienci