Dokumentacja SMS API

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ć.

DEFINICJE

  1. Partner – Osoba, która podpisała z Numery-Premium.pl umowę o współpracy w zakresie usług premium;
  2. Użytkownik – Klient Partnera (Osoba dzwoniąca pod uruchomiony przez partnera numer premium, lub wysyłająca sms’a pod uruchomiony przez Partnera numer premium);
  3. Numery-Premium.PL (pisane niezależnie od wielkości liter) – firma Oskar Rybczyński, NIP: 5611550703; REGON: 368710883;
  4. UKE – Urząd Komunikacji Elektronicznej.

Kody odpowiedzi HTTP

API Numery-Premium.PL po wykonaniu każdej opcji zwraca odpowiedni komunikat.

Poprawne kody odpowiedzi

Poprawne kody odpowiedzi API
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.

Błędne kody odpowiedzi

Błędne kody odpowiedzi API
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.

Ważne informacje (logowanie do API):

Bez względu na funkcję, której chcemy użyć każde zapytanie musi zawierać parametr w formacie:
Wymagany Parametr – Typ Danych – Wyjaśnienie.

Logowanie do API wymagane w każdym wysyłanym elemencie.
Parametr Typ Danych Wyjaśnienie
apikey string znajdziesz go po zalogowaniu w lewym menu zakładka API -> SMS

Numery-Premium.PL -> Partner

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.

FORM_PARAMS POST

FORM_PARAMS POST API
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.

Partner -> 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.

Wysyłka odpowiedzi na otrzymanego SMS

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

Wymagane Parametry

Wymagane Parametry do wysłania odpowiedzi na SMS - wszystkie obowiązkowe
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.

Przykład wysyłki odpowiedzi na SMS

$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'
 ]
]);

Możliwe odpowiedzi przy wysyłce odpowiedzi na SMS

Dokładną informację wraz z konkretnym opisem błędu znajdziesz po wysłaniu zapytania

Możliwe odpowiedzi serwera przy wysyłce odpowiedzi na SMS
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

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

Wymagane Parametry

Wymagane Parametry do wysyłki SMS - wszystkie obowiązkowe, tylko jedno msisdn w zależności od parametru spam
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.

Przykład wysyłki SMS bez lokowania produktu/usługi

$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'
 ]
]);

Możliwe odpowiedzi przy wysyłce SMS

Dokładną informację wraz z konkretnym opisem błędu znajdziesz po wysłaniu zapytania

Możliwe odpowiedzi serwera przy wysyłce SMS
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

Wersja API

  1. v1.0 - Utworzenie API