HTTPS API v2 / Wprowadzenie

SerwerSMS.pl umożliwia wysyłanie wiadomości przy pomocy Panelu Klienta oraz dostępnych tam funkcji jak również przy pomocy tzw. zdalnej obsługi. Dzięki drugiej z wymienionych metod możliwe jest wysyłanie oraz sprawdzanie poprawności wysłanych wiadomości jak również dostęp do innych funkcji bez konieczności logowania się do Panelu Klienta.

Komunikacja z SerwerSMS.pl odbywa się poprzez wywołanie adresu URL metodą POST z odpowiednimi parametrami. Zalecane jest połączenie szyfrowane SSL (https). Jako odpowiedź zwracany jest dokument w formacie JSON lub XML informujący o wyniku wywołanej akcji. 

Maksymalna wielkość pojedynczego zgłoszenia do wysyłki wiadomości to 100 000 numerów. Zalecane jest przesyłanie mniejszych porcji danych np. 50-200 numerów w jednym zgłoszeniu. W przypadku gdy w pojedynczym zgłoszeniu zostanie przesłanych więcej numerów (powyżej 100 000) lub wiadomości spersonalizowanych (numer oraz wiadomość, powyżej 10 000) wygenerowany zostanie błąd ogólny, a wiadomości nie zostaną wysłane.

Usługa zdalnej obsługi przez HTTPS API umożliwia również wysyłanie informacji o raportach doręczeń oraz odpowiedziach SMS wprost na wskazany adres URL Abonenta. Aby SerwerSMS.pl wysłał automatycznie informacje o raportach doręczeń do Abonenta, należy w Panelu Klienta ustawić odpowiednie opcje w zakładce Ustawienia interfejsów (HTTPS XML API lub ustawienia w odpowiedniej sekcji np. ND/NDI). Więcej informacji na ten temat znajduje się w dalszej części dokumentacji.

Należy również pamiętać o formacie podawanych numerów telefonów. Każdy numer powinien być w formacie międzynarodowym np. w przypadku numerów polskich sieci komórkowych jest to +48500600700. Analogicznie jeśli numer jest z sieci innego kraju należy poprzedzić go numerem kierunkowym. Numery Polskie nie posiadające prefiksu +48, w miarę możliwości będą automatycznie korygowane do wymaganego formatu np:

500 600 700 -> +48500600700
48500600700 -> +48500600700
0048.500600700 -> +48500600700

Numery zagraniczne muszą posiadać pełny prefiks międzynarodowy poprzedzony znakiem „+” (plus). Ponadto należy zwrócić uwagę na długość adresu przesyłanego metodą GET gdyż w przypadku przesyłania większej ilości danych może nastąpić przekroczenie dozwolonych 255 znaków. W takim przypadku prosimy o przesyłanie danych metodą POST.

Adres, na który należy wysyłać zapytania do HTTPS API to:

https://api2.serwersms.pl/

Domyślnym formatem zwracanych danych jest JSON. W celu wywołania wysyłki wiadomości należy użyć konstrukcji:

https://api2.serwersms.pl/messages/send_sms

lub:

https://api2.serwersms.pl/messages/send_sms.json

W przypadku zmiany formatu danych na XML, w adresie URL należy użyć rozszerzenia .xml:

https://api2.serwersms.pl/messages/send_sms.xml

Alternatywny adres (HTTP lub HTTPS) to:

https://s1api2.serwersms.pl/

Wychodząc naprzeciw oczekiwaniom naszych obecnych oraz przyszłych Klientów, udostępniamy możliwość sprawdzania i testowania usługi zdalnej obsługi przez HTTPS API dla osób nie posiadających jeszcze kont w SerwerSMS.pl. Aby skorzystać z konta testowego należy logować się na następujące dane:

Login: demo
Hasło: demo

Zapytania które w przypadku normalnego konta wysyłają wiadomości, w tym przypadku jedynie generują zwrot w postaci dokumentu JSON/XML (identycznie jak w przypadku parametru „test=1”). Informacje zwrotne są identyczne jak w przypadku standardowego wysyłania wiadomości . Aby dokładnie sprawdzić raporty doręczenia oraz odczytywanie wiadomości zwrotnych wysłane zostały dwa SMS-y oraz jedna odpowiedź SMS. W zwrocie otrzymano następujące dokumenty JSON:

Wysłany SMS 1:

{
   "success":true,
   "queued":1,
   "unsent":0,
   "items":[{
        "id":"c2451e1302",
        "phone":"+48500600700",
        "status":"queued",
        "queued":"2014-10-16 16:49:05",
        "parts":1,
        "text":"To jest wiadomosc testowa z SerwerSMS.pl"
   }]
}

Wysłany SMS 2 (zwrot w postaci dokumentu XML):

<result>
   <success>1</success>
   <queued>1</queued>
   <unsent>0</unsent>
   <items>
      <item>
         <id>c2451e1302</id>
         <phone>+48783820099</phone>
         <status>queued</status>
         <queued>2014-10-17 16:00:15</queued>
         <parts>1</parts>
         <text>I jeszcze jedna wiadomosc testowa z SerwerSMS.pl</text>
      </item>
   </items>
</result>

Odpowiedź na SMS ECO+:

{
    "items":[{
         "id":2469266,
         "type":"eco",
         "phone":"+48783820099",
         "recived":"2014-10-16 16:52:03",
         "message_id":"c2451e1302",
         "blacklist":false,
         "text":"Dziekuje za ta informacje. Pozdrawiam"
    }]
}

Na podstawie powyższych informacji można z powodzeniem przetestować oraz wdrożyć zdalną obsługę do własnego oprogramowania przez co sam proces integracji po skorzystaniu z oferty SerwerSMS.pl będzie krótszy i pewniejszy.

Oferujemy również gotowe biblioteki do wykorzystania implementujące HTTPS API w poniższych językach programowania:

Wszystkie akcje opisane w dokumentacji testować można przy pomocy konsoli API dostępnej pod adresem: http://apiconsole.serwersms.pl