Poniższa dokumentacja odnosi się do najnowszego API REST w wersji 3.2 dla nowego panelu klienta.
Wprowadzenie
Każde żądanie musi zawierać następujący nagłówek autoryzacyjny: Authorization: Basic < credentials > gdzie credentials to zakodowany w base64 adres email oraz hasło oddzielone dwukropkiem (hasło dla API należy ustawić w panelu klienta: Ustawienia interfejsów - HTTP API - Użytkownicy API). Można użyć nagłówka Accept w celu wskazania formatu odpowiedzi, np. Accept: text/json.
Kodowania loginu i hasła do postaci base64 można dokonać na przykład w języku PHP przy użyciu poniższej konstrukcji:
$authHeader = 'Authorization: Basic ' . base64_encode($login . ':' . $password);
Kody odpowiedzi:
Statusy wykonania metody są indywidualne dla każdej metody (dotyczy kodów 1-399)
- 0 - operacja przebiegła pomyślnie
- 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ę poprzez żądaniePOST na adres:
https://promosms.com/api/rest/v3_2/sms
Dostępne metody wywołania: POST
Parametry wejściowe podawane w BODY jako FormData:
- text - string - treść wysyłanej wiadomości
- type - integer - typ wysyłanego SMSa. Dozwolone typy to:
- 0 - SMS Flash(tylko wysyłka krajowa do polskich operatorów)
- 1 - SMS ECO (tylko wysyłka krajowa do polskich operatorów)
- 3 - SMS FULL
- 4 - SMS SPEED
- 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). Numery krajowe do polskich operatorów można podać w formacie 9 cyfrowym. Numery należące do zagranicznych operatorów muszą posiadać prefiks kraju wysyłki.
- 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 SMS ECO/SMS Flash 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 dla pojedynczej wiadomości SMS. Jeżeli zatem chcemy, aby platforma PromoSMS usuwała wszelkie niestandardowe znaki (znaki specjalne), należy podać wartość tej zmiennej ustawioną na 0. Funkcja dostępna tylko dla SMS FULL.
- 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). Naliczanie zgodne z tabelą znaków
- 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. Identyfikator może mieć minimalnie 3 znaki i maksymalnie 50 znaków alfanumerycznych (a-z, A-Z, 0-9)
- 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 JSON lub XML, wynik jest zgodny z poniższym schematem:
- status (integer)
- sentSmsCount (integer)
- recipientsResults
- recipientResult[]
- recipient (string)
- sms-id (string)
- own-id (string)
- status (integer)
- recipientResult[]
- status - kod odpowiedzi
- sentSmsCount - liczba pomyślnie wysłanych wiadomości
- recipientsResults[] - 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:
| Kod | Opis |
|---|---|
| 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 SMS SPEED |
| 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 w PHP:
$ch = curl_init('https://promosms.com/api/rest/v3_2/sms');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, array(
'Authorization: Basic '
.base64_encode('john.doe@example.com:s3cr3tp4ssw0rd'),
'Accept: text/json'
));
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, http_build_query(array(
'text' => 'Test SMS Content',
'type' => 1,
'recipients' => array ('504304204','123456789','987654321'),
)));
$result = json_decode(curl_exec($ch));
Raporty dostarczenia
Aby otrzymać raporty wysłanych wiadomości zalecanym sposobem jest podanie adresu URL serwera użytkownika, na który mają być przekazywane. Ustawienie to znajduje się w panelu klienta: Ustawienia - Ustawienia zaawansowane - Raport doręczeń. 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 - jeżeli używasz własnych identyfikatorów, możesz użyć również tej opcji
Podany adres powinien mieć więc na przykład następującą formę:
https://twojserwer.pl/odbior-raportow.php?identyfikator=%smsID&czas_dostarczenia=%timestamp&na_numer=%number
Aby samodzielnie odpytać system o stan wysłanych wiadomości, można użyć funkcji get-reports
https://promosms.com/api/rest/v3_2/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)
- 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
- 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 JSON lub XML, wynik jest zgodny z poniższym schematem:
- status (integer)
- reports
- report[]
- recipient (string)
- smsId (string)
- ownId (string)
- status (integer)
- lastUpdateTime (integer)
- report[]
- status - kod odpowiedzi
- reports[] - tablica raportów
- recipient - numer telefonu adresata wiadomości
- smsId - unikalny identyfikator wiadomości
- ownId - identyfikator nadany przez użytkownika
- 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:
| Kod | Opis |
|---|---|
| 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 w PHP:
$ch = curl_init('https://promosms.com/api/rest/v3_2/reports?' . http_build_query(array(
'from-time' => 1433109600,
'to-time' => 1435701600,
)));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, array(
'Authorization: Basic '
.base64_encode('john.doe@example.com:s3cr3tp4ssw0rd'),
'Accept: text/json'
));
$result = json_decode(curl_exec($ch));
Odbieranie odpowiedzi
W przypadku realizacji wysyłki SMS ECO, 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/v3_2/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.
- 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 JSON lub XML, wynik jest zgodny z poniższym schematem:
- status (integer)
- inboxMessages
- inboxMessage[]
- messageId (integer)
- sender (string)
- message (string)
- originalMessage (string)
- receiveTime (integer)
- inboxMessage[]
- status - kod odpowiedzi
- inbox-messages[] - tablica odpowiedzi
- messageId - identyfikator odpowiedzi
- sender - numer telefonu osoby przesyłającej odpowiedź
- message - treść odpowiedzi
- originalMessage - treść wiadomości, której dotyczy odpowiedź
- receiveTime - czas otrzymania wiadomości (w postaci uniksowego znacznika czasowego)
Statusy końcowe funkcji get-inbox:
| Kod | Opis |
|---|---|
| 200 | Niepoprawny identyfikator odpowiedzi |
| 201 | Niepoprawny znacznik czasowy |
| 202 | Niepoprawny identyfikator treści |
Przykład w PHP:
$ch = curl_init('https://promosms.com/api/rest/v3_2/inbox?' . http_build_query(array(
'from-time' => 1433109600,
)));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, array(
'Authorization: Basic '
.base64_encode('john.doe@example.com:s3cr3tp4ssw0rd'),
'Accept: text/json'
));
$result = json_decode(curl_exec($ch));
Sprawdzanie stanu konta
Sprawdzanie stanu konta odbywa się poprzez wywołanie metody get-balance
https://promosms.com/api/rest/v3_2/balance
Dostępna metoda wywołania: GET
Funkcja nie przyjmuje dodatkowych parametrów wejściowych.
Odpowiedź:
W przypadku wybrania formatu odpowiedzi JSON lub XML, wynik jest zgodny z poniższym schematem:
- status (integer)
- balanceAvailable (integer)
- status - kod odpowiedzi
- balanceAvailable - liczba dostępnych do wykorzystania środków podanych w groszach
Statusy końcowe funkcji get-balance:
| Kod | Opis |
|---|---|
| 300 | Konto nie jest przystosowane do korzystania z tej wersji API |
Przykład w PHP:
$ch = curl_init('https://promosms.com/api/rest/v3_2/balance');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, array(
'Authorization: Basic '
.base64_encode('john.doe@example.com:s3cr3tp4ssw0rd'),
'Accept: text/json'
));
$result = json_decode(curl_exec($ch));
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/v3_2/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. Funkcja dostępna tylko dla SMS FULL.
- 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 - SMS Flash
- 1 - SMS ECO
- 3 - SMS FULL
- 4 - SMS SPEED
- 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 JSON lub XML, wynik jest zgodny z poniższym schematem:
- status (integer)
- charsNumber (integer)
- smsParts (integer)
- text (string)
- status - kod odpowiedzi
- charsNumber - łączna liczba znaków wiadomości
- smsParts - 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
Statusy końcowe funkcji convert-message:
| Kod | Opis |
|---|---|
| 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 w PHP:
$ch = curl_init('https://promosms.com/api/rest/v3_2/convert-message?' . http_build_query(array(
'text' => 'Puść mą dłoń! Gnij schab, frytkę! Zwóź żel!',
'special-chars' => 0,
)));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, array(
'Authorization: Basic '
.base64_encode('john.doe@example.com:s3cr3tp4ssw0rd'),
'Accept: text/json'
));
$result = json_decode(curl_exec($ch));
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/v3_2/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). W przypadku numerów poprzedzonych znakiem "+" jest ignorowany parametr country-prefix.
Odpowiedź:
W przypadku wybrania formatu odpowiedzi JSON lub XML, wynik jest zgodny z poniższym schematem:
- status (integer)
- numbers
- number[]
- originalNumber (string)
- isValid (boolean)
- countryPrefix (string)
- formatted (string)
- number[]
- status - kod odpowiedzi
- numbers[] - tablica ze szczegółowymi informacjami o numerze telefonu
- originalNumber - postać w jakiej numer został podany w żądaniu
- isValid - flaga określająca, czy numer jest poprawny
- countryPrefix - prefiks kraju
- formatted - numer telefonu z prefiksem kraju
Statusy końcowe funkcji validate-numbers:
| Kod | Opis |
|---|---|
| 100 | Nie podano ani jednego numeru telefonu |
Przykład w PHP:
$ch = curl_init('https://promosms.com/api/rest/v3_2/validate-numbers?' . http_build_query(array(
'country-prefix' => '48',
'numbers' => array ('500001002', '500001003'),
)));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, array(
'Authorization: Basic '
.base64_encode('john.doe@example.com:s3cr3tp4ssw0rd'),
'Accept: text/json'
));
$result = json_decode(curl_exec($ch));
Dodawanie kontaktów
REST API umożliwia dodawanie kontaktów do Książki Adresowej za pomocą funkcji add-contacts
https://promosms.com/api/rest/v3_2/contacts
Dostępna metoda wywołania: POST
Parametry wejściowe podawane w BODY jako FormData:
- 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 JSON lub XML, wynik jest zgodny z poniższym schematem:
- status (integer)
- contactsCount (integer)
- status - kod odpowiedzi
- contactsCount - liczba dodanych kontaktów
Statusy końcowe funkcji add-contacts
| Kod | Opis |
|---|---|
| 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 w PHP:
$ch = curl_init('https://promosms.com/api/rest/v3_2/contacts');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, array(
'Authorization: Basic '
.base64_encode('john.doe@example.com:s3cr3tp4ssw0rd'),
'Accept: text/json'
));
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, http_build_query(array(
'contacts' => array(
array(
'phone' => '+48504304204',
'name' => 'PromoSMS',
'first-name' => 'John',
'last-name' => 'Doe',
),
'groups' => array('awesome'),
'create-groups-if-not-exist' => 1,
)));
$result = json_decode(curl_exec($ch));
