Dokumentacja zawiera listę funkcji związanych z działaniem usługi SMS na link.
Domyślną opcją ustawioną dla każdego Partnera jest obsługa SMSów (przychodzących jak i wychodzących) przez Panel Partnera, do którego przyznawany jest dostęp po zamówieniu i uruchomieniu usługi. Obsługa SMSów przez Panel Partnera odbywa się lajv. To znaczy, że gdy klient wysyła SMS’a natychmiast, bez odświeżania strony wpada on do Panelu.
Partner po zalogowaniu się do Panelu Partnera, ma możliwość w zakładce API -> SMS ustawić link, pod który Numery-Premium.pl ma przekazać otrzymanego przez użytkownika SMS’a. Nieuzupełniony adres linku jednoznaczny będzie z obsługą SMSów z poziomu Panelu Partnera.
Partner ma możliwość wysyłki odpowiedzi na otrzymanego sms pod wskazany adres linku. W tym wypadku wymaganym parametrem jest adres IP (IPv4) w formacie string uzupełniony w zakładce API -> SMS. SMS wysłąne z innego adresu IP nie będą przyjmowane.
Numery-Premium.PL kontaktuje się z Partnerami z adresu IP: 77.237.17.9/32, 77.237.17.10/32 oraz 86.106.91.171/32. Sugerujemy ograniczyć dostęp do skryptu odbierającego SMSy innym adresom IP w celu wyeliminowania nadużyć.
API Numery-Premium.PL po wykonaniu każdej opcji zwraca odpowiedni komunikat.
KOD | Status | Info |
---|---|---|
200 | OK | Zapytanie zostało odebrane prawidłowo i wykonane poprawnie |
201 | CREATED | Zapytanie utworzyło nowy element. |
202 | ACCEPTED | Zapytanie zostało prawidłowo zaakceptowane i wstawione do kolejki. |
204 | NO CONTENT | Zwracany przy prawidłowym usunięciu elementu. |
KOD | Status | Info |
---|---|---|
400 | BAD REQUEST | Brak wymaganego parametru lub przyjął on nieodpowiednią wartość. |
401 | UNAUTHORIZED | Brak prawidłowej autoryzacji, lub odpowiednich uprawnień do wykonania akcji. |
403 | FORBIDDEN | Brak uprawnień do danego zasobu. |
404 | NOT FOUND | Nie znaleziono zasobu. |
422 | UNPROCESSABLE ENTITY | Zwracany wraz z informacją o błędach w zasobie. |
We większość komunikatów błędów pojawia się wyjaśnienie co poszło nie tak.
Bez względu na funkcję, której chcemy użyć każde zapytanie musi zawierać parametr w formacie:
Wymagany Parametr – Typ Danych – Wyjaśnienie.
Parametr | Typ Danych | Wyjaśnienie |
---|---|---|
apikey | string | znajdziesz go po zalogowaniu w lewym menu zakładka API -> SMS |
Niezależnie od formy otrzymywania SMS (przez Panel Partnera lub SMS wysyłany przez LINK). Użytkownik musi wysłać prawidłowy prefix pod prawidłowy numer premium. Nieprawidłowy prefix, lub SMS wysłany pod niewłaściwy numer nie będą przekazywane do Partnerów poza poniższym wyjątkiem:
System Numery-Premium.PL po wysłaniu SMS przez użytkownika na prawidłowy numer telefonu loguje dany msisdn na okres około 2 godzin. Oznacza to, że użytkownik w pierwszym SMS bezwzględnie musi podać prefix i wysłać wiadomość pod prawidłowy numer premium (wykupiony przez Partnera). Po prawidłowej wysyłce dany msisdn jest logowany w systemie Partnera na okres około 2 godzin, co oznacza, że od momentu wysłania pierwszego SMS’a w kolejnych SMS’ach już użytkownik nie musi podawać prefixu (zalecamy jednak przyzwyczajanie klientów do każdorazowego podawania prefixu tj. pierwszego słowa w treści sms) przez okres 2 godzin.
System komunikuje się Partnerem przez protokół HTTP metodą POST
System komunikuje się z Partnerem w momencie nadejścia SMS’a. Oczekujemy kodu odpowiedzi 201. Jeśli kod odpowiedzi jest inny niż 201 ewentualnie 200 system będzie ponawiał próbę wysyłki co 60 minut aż 20 razy. Zalecamy zapis SMS w Partnera bazie metodą edytuj lub zapisz na podstawie unikalnego id, wysyłanego przez Numery-Premium.PL. Po 20 próbach doręczenia danego SMS'a nie będzie on dalej dostarczany, pozostanie jednak widoczny w Panelu Zarządzania Usługą, oraz w billingu usług.
Parametr | Typ Danych | Wyjaśnienie |
---|---|---|
id | string | unikalne id SMS’a, po którym można znaleźć SMS w systemie Numery-Premium.PL; |
msisdn | string | numer telefonu użytkownika; |
la | string | numer premium pod który użytkownik wysłał SMS; |
msg | text | wiadomość wysłana przez użytkownika, wraz z prefixem; |
time | datetime | czas nadejścia SMS do systemu Numery-Premium.PL. |
Proces wysyłki / odpowiedzi na SMS’a / Wysyłki Sms / Masowej wysyłki.
Wysyłka SMS nie jest przeznaczona do wysyłki masowej. Każdorazowa akcja wysyłki masowej (komunikaty (w tym reklamowe) o tej samej, bądź podobnej (zbliżonej) treści, do różnych msisdn w okresie 1 tygodnia, ilości powyżej 70 sztuk) zakończy się nałożeniem kary przez Numery-Premium.PL w stosunku do Partnera w wysokości 20 000 zł (dwadzieścia tysięcy złotych) z możliwością dochodzenia dalszych roszczeń prawnych przez okres 10 lat od momentu wysyłki.
Jeśli potrzebujesz masowej wysyłki SMS, najpierw należy napisać e-mail z proponowaną treścią komunikatu, ilością msisdn, pełnymi danymi administratora bazy, daty rozpoczęcia wysyłki i daty zakończenia wysyłki. Numery-Premium.PL mogą wyrazić zgodę na wskazaną wysyłkę lub jej odmówić nie podając przyczyn. Numery-Premium.PL wydają zezwolenie, bądź odmowę na takie zgłoszenie w terminie maksymalnym 7 dni roboczych (co należy uwzględnić w dacie rozpoczęcia wysyłki). Nie udzielenie odpowiedzi jest równe nie udzieleniu pozwolenia. Jednorazowo można wysłać maksymalnie 100 smsów (przez jedno zgłoszenie do API).
Informujemy, że pobieramy opłatę od każdego SMS’a w wysyłce masowej, nawet jeśli nie dotrze on do odbiorcy. SMS’y masowe nie docierają wyłącznie do odbiorców, którzy u swojego operatora zablokowali komunikaty reklamowe. Odpowiedzi na SMS’y i wysyłka SMSów realizowane są bez tej opcji. Proszę zwrócić uwagę na fakt, że celowa i nachalna wysyłka treści reklamowych przez odpowiedź na SMS, lub standardową wysyłkę SMS może stanowić naruszenie zasad współpracy i spowodować nałożenie kary przez UKE i/lub Numery-Premium.PL na Partnera.
Poniżej znajdziesz listę wymaganych parametrów do obsługi wysyłki odpowiedzi na SMS w formacie:
Wymagany Parametr – Typ Danych – Wyjaśnienie.
Adres: https://numery-premium.pl/api/partner/replyToSms/
Metoda: POST
Parametr | Typ Danych | Wyjaśnienie |
---|---|---|
spam | string | 0 |
prefix | string | prefix uruchomiony przez partnera; |
id | string | id SMS’a otrzymane od Numery-Premium.PL poczas wysyłki SMS; |
msisdn | string | odpowiedź na SMS można wysłać tylko na numer telefonu, z którego przyszedł SMS; |
la | string | numer premium uruchomiony przez partnera do obsługi SMS; |
rely | text | odpowiedź, która ma być wysłana do klienta. |
Oczekiwany kod odpowiedzi 202 oznaczający prawidłowe wysłanie odpowiedzi na SMS do użytkownika.
W przypadku kodu 200 zapytanie zostało poprawnie wykonane, jednak wystąpił problem z wysyłką SMS’a do klienta po stronie operatora użytkownika. Należy ponowić próbę wysyłki SMS’a za kilka minut.
$client = new \GuzzleHttp\Client();
$client->request('POST','https://numery-premium.pl/api/partner/replyToSms/',[
'form_params' => [
'apikey' => 'apikey otrzymany od Numery-Premium.PL',
'spam' => 0,
'prefix' => 'prefix uruchomiony przez partnera',
'id' => 'id SMS’a otrzymane od Numery-Premium.PL poczas wysyłki SMS',
'msisdn' => 'odpowiedź na SMS można wysłać tylko na numer telefonu, z którego przyszedł SMS',
'la' => 'numer premium uruchomiony przez partnera do obsługi SMS', na którego użytkownik wysłał SMS, na którego odpowiadamy,
'reply' => 'odpowiedź, która ma być wysłana do klienta'
]
]);
Dokładną informację wraz z konkretnym opisem błędu znajdziesz po wysłaniu zapytania
HTTP response code | Odpowiedź serwisu | Wyjaśnienie |
---|---|---|
500 | internal server error | Zapytanie jest nieodpowiednio sformułowane |
422 | Problem z prefixem lub msisdn | Sprawdź czy msisdn zawiera dokładnie 9 cyfr, lub czy użyłeś właściwego prefixu |
404 | Not Found | Niewłaściwa metoda. Przyjmujemy zapytania metodą POST |
403 | Forbidden | Wysyłka SMS pod inny msisdn niż ten, z którego przyszedł SMS |
401 | UNAUTHORIZED | Błędna autoryzacja, niewłaściwy apikey, i/lub adres IP |
400 | Brak wymaganych parametrów | Sprawdź niezbędne parametry |
202 | ACCEPTED | SMS Wysłany prawidłowo |
200 | OK | Zapytanie poprawne, operator nie dostarczył SMS. Spróbuj ponownie za kilka minut |
Wysyłka SMS zgodna z cennikiem Numery-Premium.PL
Poniżej znajdziesz listę wymaganych parametrów do obsługi wysyłki odpowiedzi na SMS w formacie:
Wymagany Parametr – Typ Danych – Wyjaśnienie.
Adres: https://numery-premium.pl/api/partner/sendSms/
Metoda: POST
Parametr | Typ Danych | Wyjaśnienie |
---|---|---|
spam | string | 0 jeśli wysyłka nie zawiera jakiegokolwiek lokowania produktu lub usługi. 1 jeśli wysyłka reklamowa, bądź zawiera jakiekolwiek lokowanie czegokolwiek (nie prawidłowe oznaczenie może spowodować nałożenie kary przez UKE na Partnera); |
msisdn[] | array | jeśli 'spam' == 1 Numer telefonu do wysłania SMS. Maksymalna ilość msisdn = 100. |
msisdn | string | jeśli 'spam' == 0 Numer telefonu do wysłania SMS. |
la | string | jeden z uruchomionych numerów premium przez partnera do obsługi SMS, wybrany dobrowolnie przez Partnera; |
msg | text | Treść SMS, która ma być dostarczona do klienta. |
Proszę zwrócić uwagę na fakt, że tylko jeden msisdn wysyłamy w zależności od parametru spam
Oczekiwany kod odpowiedzi 202 oznaczający prawidłowe wysłanie odpowiedzi na SMS do użytkownika.
W przypadku kodu 200 zapytanie zostało poprawnie wykonane, jednak wystąpił problem z wysyłką SMS’a do klienta po stronie operatora użytkownika. Należy ponowić próbę wysyłki SMS’a za kilka minut.
$client = new \GuzzleHttp\Client();
$client->request('POST','https://numery-premium.pl/api/partner/sendSms/',[
'form_params' => [
'apikey' => 'apikey otrzymany od Numery-Premium.PL',
'spam' => 0,
'msisdn' => 'Numer telefonu do wysłania SMS',
'la' => 'jeden z uruchomionych numerów premium przez partnera do obsługi SMS, wybrany dobrowolnie przez Partnera',
'msg' => 'Treść SMS, która ma być dostarczona do klienta'
]
]);
Dokładną informację wraz z konkretnym opisem błędu znajdziesz po wysłaniu zapytania
HTTP response code | Odpowiedź serwisu | Wyjaśnienie |
---|---|---|
500 | internal server error | Zapytanie jest nieodpowiednio sformułowane |
422 | Problem z msisdn | MSISDN musi zawierać 9 cyfr lub być array |
404 | Not Found | Niewłaściwa metoda. Przyjmujemy zapytania metodą POST |
403 | Problem z la | Brak praw do używania wskazanego numeru la. Jesli nie masz usługi wyślij z la 7043 |
401 | UNAUTHORIZED | Błędna autoryzacja, niewłaściwy apikey |
400 | Brak wymaganych parametrów lub ich zła wartość | Sprawdź czy wysłano wszystkie prawidłowo uzupełnione dane. Szczegóły znajdziesz w odpowiedzi. |
202 | ACCEPTED | SMS('y') Wysłan(y:o) prawidłowo |
200 | OK | Zapytanie poprawne, operator docelowy nie dostarczył SMS(a:ów). Spróbuj ponownie za kilka minut |