1. Wprowadzenie

Platforma SMSAPI została skierowana do użytkowników chcących rozbudować swoje aplikacje o system wysyłania i odbierania SMS-ów oraz MMS-ów oraz wysyłki wiadomości głosowych VMS. Aplikacja ta w prosty sposób umożliwia integrację dowolnego serwisu z bramką SMS, MMS i/lub VMS. Głównymi atutami naszego serwisu oprócz prostej implementacji jest możliwość nadawania wiadomości z własnej nazwy (maksymalnie 11 znaków). Każdy wysłany SMS, MMS oraz VMS za pośrednictwem systemu posiada unikalny numer identyfikacyjny pozwalając na sprawdzenie raportu doręczenia wiadomości.

Rozpoczęcie współpracy

W celu rozpoczęcia współpracy należy utworzyć konto w serwisie SMSAPI . Utworzone konto jest gotowe do użytku, jednak zalecamy ustawienie własnego pola nadawcy. Jako domyślne ustawione jest pole nadawcy „Info”. Dodanie pola nadawcy jest usługą całkowicie darmową.

Filtr IP dla interfejsu API

W celu dodatkowego zabezpieczenie interfejsu API w Filtr adresów IP ustawić można adresy IP z których możliwa będzie wysyłka wiadomości (w przypadku próby dokonania wysyłki z innego IP system zwróci błąd: ERROR:105 ). Adresy należy oddzielić przecinkami.

Autoryzacja

Przykład:

POST /sms.do HTTP/1.1
Host: api.smsapi.pl
Authorization: Bearer <access_token>

Rekomendujemy autoryzację OAuth 2.0. Genrowanie tokenu z dostępem do wybranych stref można zrealizować w naszym panelu klienta Tokeny API .

W odwołaniu do API wymagany jest dodatkowy nagłówek autoryzacyjny.

Jeżeli wykorzystywane środowisko nie pozwala na modyfikację nagłówków opcjonalnie można dodać parametr access_token w którym zostanie przekazany token. Jest to jednak rozwiązanie nierekomendowane oraz obniżające poziom bezpieczeństwa.

Adresy URL

Adresy URL do połączenia z aplikacją - zwane dalej "Adresem połączenia":

https://api.smsapi.pl/ - dla połączeń szyfrowanych SSL
https://api2.smsapi.pl/ - backup dla połączeń szyfrowanych SSL

Biblioteki

Wykorzystanie gotowych bibliotek SMSAPI pozawala na przyśpieszenie oraz uproszczenie prac związanych z integracją z naszą platformą. Wszystkie dostępne biblioteki są dostępne na GitHub.

Język programowania	Github link:
PHP	Biblioteka PHP
C# .net	Biblioteka C#
Bash	Biblioteka Bash
Python	Biblioteka Python
JavaScript (node.js)	Biblioteka JavaScript (node.js)
Java	Biblioteka Java

2. Pojedynczy SMS

curl -H "Authorization Bearer access_token" \
"https://api.smsapi.pl/sms.do?\
from=pole_nadawcy&\
to=48500000000&\
message=treść_wiadomości&\
format=json"

<?php

function sms_send($params, $token, $backup = false)
{

    static $content;

    if ($backup == true) {
        $url = 'https://api2.smsapi.pl/sms.do';
    } else {
        $url = 'https://api.smsapi.pl/sms.do';
    }

    $c = curl_init();
    curl_setopt($c, CURLOPT_URL, $url);
    curl_setopt($c, CURLOPT_POST, true);
    curl_setopt($c, CURLOPT_POSTFIELDS, $params);
    curl_setopt($c, CURLOPT_RETURNTRANSFER, true);
    curl_setopt($c, CURLOPT_HTTPHEADER, array(
        "Authorization: Bearer $token"
    ));

    $content = curl_exec($c);
    $http_status = curl_getinfo($c, CURLINFO_HTTP_CODE);

    if ($http_status != 200 && $backup == false) {
        $backup = true;
        sms_send($params, $token, $backup);
    }

    curl_close($c);
    return $content;
}

$token = "wygenerowany_token"; //https://ssl.smsapi.com/webapp#/oauth/manage

$params = array(
    'to' => '500000000', //numery odbiorców rozdzielone przecinkami
    'from' => 'Info', //pole nadawcy
    'message' => "Hello world!" //treść wiadomości
);

echo sms_send($params, $token);

?>

I. Przykład odpowiedzi kiedy &format = json jest użyty:

a) W przypadku sukcesu:


{
    "count":1,
    "list": [
    {
        "id":"1460969715572091219",       //id wiadomości
        "points":0.16,                    //cena wiadomości
        "number":"44123456789",           //numer odbiorczy z prefixem
        "date_sent":1460969712,           //data wysyłki
        "submitted_number":"44123456789", //numer odbiorczy podany w zapytaniu
        "status":"QUEUE"                  //status wiadomości
    }
  ]
}

b) w przypadku niepowodzenia:


 {
"invalid_numbers":[
    {
    "number":"44123456789",             //numer odbiorczy z prefixem
    "submitted_number":"44123456789",   //numer odbiorczy podany w zapytaniu
    "message":"Invalid phone number"    //opis błędu
    }
  ],
  "error":13,                           //kod błędu
  "message":"No correct phone numbers"  //opis błędu
    }
}

II. Przykład odpowiedzi bez parametru &format :

a) W przypadku sukcesu:

OK:<ID>:<POINTS>
OK:1460969715572091219:0.16

b) w przypadku niepowodzenia:

ERROR:<ERR>
ERROR:13

Wysyłanie SMS-ów odbywa się przez wysłanie metodą GET lub POST danych do adresu połączenia:

Parametr	Opis
access_token	OAuth token wygenerowany w Panelu SMSAPI
to	Numer odbiorcy wiadomości w formacie 48xxxxxxxxx lub xxxxxxxxx. Np. 48505602702 lub 505602702.
group	Nazwa grupy kontaktów z książki telefonicznej, do których ma zostać wysłana wiadomość
message	Treść wiadomości. Standardowo do 160 znaków lub 70 znaków w przypadku wystąpienia chociaż jednego znaku specjalnego (polskie znaki uważane są za specjalne). Maksymalna długość wiadomości wynosi 918 znaków (lub 402 ze znakami specjalnymi) i jest wysyłana/ jako 6 połączonych SMS-ów, obciążając konto zgodnie z aktualnym
from	Parametr from definiuje rodzaj wysłanej wiadomości (Pro / Eco / 2way) jednocześnie dla wiadomości Pro określając Pole Nadawcy z jakim wiadomość ma być wysłana: &from=Nazwa – spowoduje wysłanie wiadomości Pro z polem nadawcy „Nazwa” &from=2way – spowoduje wysłanie wiadomości 2WAY - &from=Eco – spowoduje wysłanie wiadomości ECO. Pozostawienie pola pustego powoduje wysłanie domyślnego rodzaju wiadomości z domyślnym polem nadawcy. Przyjmowane są tylko nazwy zweryfikowane. (&from=aktywna_nazwa). Pole nadawcy należy dodać po zalogowaniu na stronie SMSAPI, Pola Nadawcy .
encoding	Parametr określa kodowanie polskich znaków w SMS-ie. Domyślne kodowanie jest windows-1250. Jeżeli występuje konieczność zmiany kodowania, należy użyć parametru encoding z danymi: Interfejs HTTP/S API - wersja 2.34-dla iso-8859-2 (latin2) – należy podać wartość „iso-8859-2”,-dla utf-8 – należy podać wartość „utf-8”.
flash	Wysyłanie wiadomości trybem „flash”, odbywa się poprzez podanie parametru flash o wartości „1”. SMS-y flash są automatycznie wyświetlane na ekranie głównym telefonu komórkowego i nie są przechowywane w skrzynce odbiorczej (jeśli nie zostaną zapisane).
test	Wiadomość nie jest wysyłana, wyświetlana jest jedynie odpowiedź (w celach testowych). (&test=1)
details	W odpowiedzi zawarte jest więcej szczegółów. (Treść wiadomości, długość wiadomość, ilość części z jakich składa się wiadomość). (&details=1)
date	Data w formacie unixtime (&date=1287734110) lub ISO 8601 (&date=2012-05-10T08:40:27+00:00). Określa kiedy wiadomość ma być wysłana. W przypadku wstawieniadaty przeszłej wiadomość zostanie wysłana od razu. Wiadomość można zaplanować na maksymalnie 3 miesiące do przodu.
date_validate	Ustawienie „1” sprawdza poprawność formatu podanej daty. W przypadku wystąpienia błędnej daty zwrócony zostanie błąd `ERROR:54`
datacoding	Parametr pozwalający na wysyłanie wiadomości binarnych. (&datacoding=bin) Parametry udh oraz message muszą być wysyłane w postaci ciągu HEX (np. message=616263 dla treści abc)
udh	Nagłówek UDH wiadomości SMS wymagany podczas korzystania z parametru &datacoding=bin (np. &udh=0605040b8423f0 dla WAP PUSH)
skip_foreign	Ustawienie tego parametru (&skip_foreign=1) powoduje pominięcie numerów nie-polskich jeżeli takie pojawią się w odwołaniu
allow_duplicates	Pozwala na wysłanie wiadomości na numery zduplikowane w danym odwołaniu (przydatne np. przy wykorzystywaniu sparametryzowanych treści)
idx	Opcjonalny parametr użytkownika wysyłany z wiadomością a następnie zwracany przy wywołaniu zwrotnym CALLBACK. Parametr idx może mieć maksymalnie 255 znaków dopuszczalne są cyfry 0 - 9 oraz litery a – z (wielkość liter nie jest rozróżniana). (&idx=123)
check_idx	Pozwala zabezpieczyć przed wysłanie dwóch wiadomości z identyczną wartością parametru idx w trakcie ostatnich 24h. W przypadku ustawienia parametru (&check_idx=1)system sprawdza czy wiadomość z podanym idx nie została wysłana w ostatnich czterechdniach lub czy nie jest zaplanowana do wysłania w przyszłości, jeżeli jest zwracany jest błąd 53.
nounicode	Ustawienie 1 zabezpiecza przed wysłaniem wiadomości ze znakami specjalnymi (w tym polskimi) (`ERROR:11`).
normalize	Opcja spowoduje zastąpienie w wiadomości SMS znaków specjalnych na ich odpowiedniki (np. ą-a, ć-c, ę-e...). (&normalize=1)
fast	Ustawienie 1 spowoduje wysłanie wiadomości przy wykorzystaniu osobnego kanału zapewniającego szybkie doręczenie wiadomości Fast. Z parametru korzystać można podczas wysyłania wiadomości Pro oraz Eco, Ilość punktów za wysyłkę pomnożona będzie przez 1.5 Uwaga! Dla tego parametru zabronione jest prowadzenie wysyłek masowych i marketingowych.
partner_id	Kod partnerski, który otrzymać można po podpisaniu umowy partnerskiej. Kod nie będzie brany pod uwagę jeżeli użytkownik wysyłający polecony jest przez innego klienta lub podaje swój kod.
max_parts	Parametr określa maksymalną ilość części z jakich może składać się wiadomość. Maksymalna wartość to 6. W przypadku gdy wiadomość składa się z większej ilości części zwrócony zostanie błąd `ERROR:12` Domyślna ilość części ustawiana jest w panelu klienta.
expiration_date	Różnica pomiędzy datą wysyłki a datą wygaśnięcia musi być większa niż 15 minut i mniejsza niż 72 godzin (zaleca się aby było to minimum 1 godzina i maksymalnie 12 godzin).Data może zostać podana w formacie unixtime (&date=1287734110) lub ISO 8601 (&date=2012-05-10T08:40:27+00:00).
discount_group	Nazwa grupy kodów rabatowych do załączenia w wysyłce. Grupy można dodawać oraz edytować w panelu klienta.
notify_url	Parametr pozwalający na ustawienie adresu URL do skryptu callback odbierającego raporty doręczenia dla danej wiadomości. Adres ten jest brany w pierwszej kolejności (przed globalnym adresem ustawionym na koncie).
format	Dla &format=json powoduje, że zwrotka z API wysyłana jest w formacie JSON.

Wiadomość FAST

https://api.smsapi.pl/sms.do - dla połączeń szyfrowanych SSL


curl -H "Authorization: Bearer access_token" \
"https://api.smsapi.pl/sms.do?\
from=pole_nadawcy&\
to=44123456789&\
message=tresc_wiadomosci&\
fast=1&\
format=json"

<?php

$params = array(
    'access_token'  => 'token SMSAPI'               //token SMSAPI
    'to'            => '48500000000',               //numer odbiorczy  
    'from'          => 'SMSAPI',                    //pole nadawcy  
    'message'       => 'treść wiadomości',           //treść wiadomości
    'fast'          => '1',                         
);

?>

Przykład odpowiedzi :

a) W przypadku sukcesu:

OK:<ID>:<POINTS>
OK:17101000090360359:0.16

b) w przypadku niepowodzenia:

ERROR:<ERR>
ERROR:13


ID	Unikalne ID wiadomości
POINTS	Ilośc punktów wykorzystanych do wysyłki
ERR	Kod błędu (sprawdź kody błędów)

Ustawienie parametru fast=1 spowoduje wysłanie wiadomości przy wykorzystaniu osobnego kanału zapewniającego najwyższy priorytet wysyłki. Z parametru korzystać można podczas wysyłania wiadomości Pro oraz Eco, Ilość punktów za wysyłkę pomnożona będzie przez 1.5

W razie problemów podczas odwoływania się do podstawowego adresu URL można wykorzystać adres URL backup https://api2.smsapi.pl/

Planowanie SMS

https://api.smsapi.pl/sms.do - dla połączeń szyfrowanych SSL


<?php

$params = array(
    'access_token'  => 'token SMSAPI'               //token SMSAPI
    'to'            => '48500000000',               //numer odbiorczy  
    'from'          => 'SMSAPI',                            //pole nadawcy  
    'message'       => 'treść wiadomości',           //treść wiadomości
    'date'          => '1577878200',                //data wysyłki UNIXTIME / ISO 8601
);

?>


curl -H "Authorization: Bearer access_token" \
"https://api.smsapi.pl/sms.do?\
from=pole_nadawcy&\
to=44123456789&\
message=tresc_wiadomosci&\
date=1577878200&\
format=json"

W celu wysłania wiadomości o określonej godzinie/dacie musi zostać użyty parametr date, dopuszczalne formaty daty to unixtime i ISO 8601.

Usuwanie zaplanowanej wiadomości :

<?php

$params = array(
    'access_token'  => 'token SMSAPI'               //token SMSAPI
    'sch_del'       => '9040616088106874',          //id wysyłki

);

?>


curl -H "Authorization: Bearer access_token" \
"https://api.smsapi.pl/sms.do?\
sch_del=09040616088106874&\
format=json"

3. Masowe wysyłanie SMSów

https://api.smsapi.pl/sms.do - dla połączeń szyfrowanych SSL

curl -H "Authorization: Bearer access_token" \
"https://api.smsapi.pl/sms.do?\
from=pole_nadawcy&\
to=48500500500,48501501501,48502502502&\
message=tresc_wiadomosci&\
format=json"


<?php

$params = array(
    'access_token'  => 'token SMSAPI'                                   //token SMSAPI
    'to'            => '48500500500,48501501501,48502502502',                           //numery odbiorcze  
    'from'          => 'SMSAPI',                                //pole nadawcy  
    'message'       => 'content of message',                            //treść wiadomości
);

?>

I. Przykład odpowiedzi kiedy użyto parametru &format=json :

a) W przypadku sukcesu:

    {
        "count": 3,
        "list": [
            {
                "id":"1460978572913968440",
                "points":0.16,
                "number":"48500500500",
                "date_sent":1460978579,
                "submitted_number":"48500500500",
                "status":"QUEUE"
            },
            {
                "id":"1460978572913968450",
                "points":0.16,
                "number":"48501501501",
                "date_sent":1460978579,
                "submitted_number":"48501501501",
                "status":"QUEUE"
            },
            {
                "id":"1460978572913968460",
                "points":0.16,
                "number":"48502502502",
                "date_sent":1460978579,
                "submitted_number":"48502502502",
                "status":"QUEUE"
            }

        ]
    }

b) w przypadku niepowodzenia:

    {
        "invalid_numbers": [
            {
                "number":"456456456",
                "submitted_number":"456456456",
                "message":"Invalid phone number"
            },
            {
                "number":"321321321",
                "submitted_number":"321321321",
                "message":"Invalid phone number"
            }
        ],
        "error":13,
        "message":"No correct phone numbers"
    }

Przykład odpowiedzi bez parametru format :

a) W przypadku sukcesu:

OK:<ID>:<POINTS>
OK:1460978572913968440:0.16:500500500;OK:1460978572913968450:0.16:501500501;OK:1460978572913968460:0.16:501500502

b) w przypadku niepowodzenia:

ERROR:<ERR>
ERROR:13

Wysyłanie SMS-ów do grupy odbiorców odbywa się tak jak do pojedynczego odbiorcy (opis w punkcie 2) lecz z podaniem wielu numerów telefonów w parametrze to. Dodatkowo cała wysyłka powinna odbywać się metodą POST do adresu połączenia. W przypadku wysyłki metodą GET przy większej ilości numerów, część parametrów może zostać ucięta i w efekcie niedostarczona w całości doserwisu SMSAPI.

Jeżeli cena za wysłanie wszystkich SMS-ów jest większa od ilości punktów dostępnych w serwisie, zostanie zwrócony komunikat o błędzie (103) i SMS-y nie zostaną wysłane. Jeżeli zostały podane błędne numery (nierozpoznane przez serwis SMSAPI ze względu na błędny prefiks), wszystkie SMS-y zostaną wysłane z pominięciem tych numerów, wówczas ilość otrzymanych raportów będzie różnić się od ilości wysłanych SMS-ów. Sytuacja ta nie dotyczy numerów z poprawnym prefiksem (np. 500000000), gdzie SMS zostanie wysłany, a następnie odrzucony gdyż numer nie istnieje (punkty za wysłanie SMS-a zostaną pobrane). Numery, które się powtarzają zostaną wysłane tylko 1 raz.

Warto zauważyć, że przy wysyłce SMS-ów do grupy odbiorców dodatkowo zwracany jest numer telefonu oraz każdy SMS jest zakończany średnikiem (oprócz ostatniego. Nie dotyczy wysyłki z parametrem &format=json).

Zalecana maksymalna ilość jednorazowej wysyłki (jedno wywołanie) wynosi 10 000 wiadomości metodą POST oraz do 200 wiadomości metodą GET.

W razie problemów podczas odwoływania się do podstawowego adresu URL można wykorzystać adres URL backup https://api2.smsapi.pl/

SMS do grupy z bazy kontaktów

https://api.smsapi.pl/sms.do - dla połączeń szyfrowanych SSL

curl -H "Authorization: Bearer access_token" \
"https://api.smsapi.pl/sms.do?\
from=pole_nadawcy&\
group=grupa_testowa&\
message=treść z parametrami [%imie%]&\
format=json"

<?php

$params = array(
    'access_token'  => 'token SMSAPI'                                       //token SMSAPI
    'group'         => 'grupa_testowa',                                     //grupa odbiorców  
    'from'          => 'SMSAPI',                                            //pole nadawcy  
    'message'       => 'treść z parametrami [%imie%]',                        //treść wiadomości
);

?>

Przykład odpowiedzi:

OK:<ID>:<POINTS>:<PHONE>;...;...;... 

OK:17101000090567759:0.14:500500500;OK:171010000903455357:0.14:501500501;OK:17101000096577326:0.14:502502502;

W celu wysłania wiadomości do określonej grupy należy w pierwszej kolejności stworzyć ją w panelu WWW Grupy.

Istnieje możliwość wstawienia pola własnego do treści wiadomości. Pola własne mogą być definiowane w panelu WWW Pola własne. Aby wstawić pole, w treści wiadomości należy wpisać [%kontakt.nazwa pola%]. Podczas wysyłki pole zostanie zastąpione odpowiednią wartością przypisaną do danego kontaktu. Istnieje także możliwość użycia standardowych pól, takich jak:

Parametr	Opis
[%imie%]	Imię przypisane do kontaktu
[%imie_w%]	Wołacz imienia przypisanego do kontaktu
[%nazwisko%]	Nazwisko przypisane do kontaktu
[%kontakt.kraj%]	Kraj
[%kontakt.opis%]	Opis kontaktu
[%kontakt.email%]	Email
[%kontakt.urzadzenie%]	Urządzenie użytkownika (przypisywany automatycznie w przypadku kliknięcia odbiorcy w skrócony link)
[%kontakt.miejscowosc%]	Miejscowość
[%kontakt.przegladarka%]	Przeglądarka (przypisywana automatycznie w przypadku kliknięcia odbiorcy w skrócony link)
[%kontakt.system operacyjny%]	System operacyjny użytkownika (przypisywany automatycznie w przypadku kliknięcia odbiorcy w skrócony link)
[%kontakt.nazwa_pola%]	Niestandardowe pole własne

Wykorzystanie parametrów

https://api.smsapi.pl/sms.do - dla połączeń szyfrowanych SSL

curl -H "Authorization: Bearer access_token" \
"https://api.smsapi.pl/sms.do?\
from=pole_nadawcy&\
to=48600111222,48500111222&\
message=test wiadomości, parametr1:[%1%] parametr2:[%2%]&\
param1=Jan|Ania&\
param2=30|40&\
format=json"

<?php

$params = array(
    'access_token'  => 'token SMSAPI'                                                           //token SMSAPI
    'to'            => '8600111222,48500111222',                                                //numery odbiorców
    'from'          => 'SMSAPI',                                                                //pole nadawcy  
    'message'       => 'test wiadomości, parametr1:[%1%] parametr2:[%2%]',                     //treść wiadomości
    'param1'        => 'Jan|Ania',
    'param2'        => '30|40'
);

?>

Wiadomości będą miały następującą treść:

Wiadomość 1: Test wiadomosci, parametr1: Jan parametr2: 30
Wiadomość 2: Test wiadomosci, parametr1: Ania parametr2: 40

Istnieje możliwość wysłania do 100 spersonalizowanych wiadomości przy pomocy jednego wywołania wykorzystując parametry. W razie potrzeby wysłania większej ilości wiadomości można wywołać równolegle kilka odwołań.Parametry powinny być zdefiniowane w wywołaniu jako param1, param2, param3, param4, które zastępowały będą [%1%], [%2%], [%3%] oraz [%4%] w treści wiadomości. Wartości parametrów muszą być oddzielone znakiem pipe „|” według wzoru:

param1=Ania|Michal|Andrzej&param2=Nowak|Kowalski|Nowakowski

Liczba parametrów musi być identyczna z liczbą numerów do których wysłane mają być wiadomości w innym przypadku zwrócony będzie błąd: ERROR:18 i wiadomość nie zostanie wysłana.

Jeżeli jeden z numerów będzie błędny zostanie on pominięty i wiadomości zostaną wysłane z pominięciem tego numeru.

Parametry

Parametry wykorzystane mogą być po zdefiniowaniu ich miejsca w wiadomości:

Parametr	Opis
[%1%]	Tekst parametru 1 (param1)
[%2%]	Tekst parametru 2 (param2)
[%3%]	Tekst parametru 3 (param3)
[%4%]	Tekst parametru 4 (param4)

Parametry IDX

Istnieje możliwość wysyłania masowych wiadomości z parametrem użytkownika IDX różnym dla każdej wiadomości. Parametr ten zwracany jest w wywołaniu zwrotnym CALLBACK z raportem doręczenia. Parametr IDX może mieć dowolną wartość, może on być wykorzystywany np. jako flaga użytkownika lub wewnętrzne ID z systemu klienckiego. Dodatkowo przy użyciu parametru IDX możliwe jest użycie parametry check_idx (&check_idx=1), użycie tego parametru nie pozwoli na wysłanie więcej niż jednej wiadomości z tym samym parametrem IDX w trakcie ostatnich 24h. W przypadku próby wysłania wiadomości z wartością parametru IDX która już pojawiła się dla danego użytkownika zostanie zwrócony błąd ERROR: 53. W celu przypisania różnych parametrów rożnym wiadomością należy oddzielić je znakiem “pipe” co przedstawia poniższy przykład:

idx=idx1|idx2|idx3|idx4

Liczba parametrów IDX musi być identyczna z liczbą wysyłanych wiadomości

Kody rabatowe

https://api.smsapi.pl/sms.do - dla połączeń szyfrowanych SSL

curl -H "Authorization: Bearer access_token" \
"https://api.smsapi.pl/sms.do?\
from=pole_nadawcy&\
to=48600111222,48500111222&\
discount_group=kody&\
message=Test wiadomości z kodem rabatowym [%kod%]&\
format=json"

<?php

    $params = array(
        'access_token'  => 'token SMSAPI'                                           //token SMSAPI
        'discount_group'=> 'kody',                                                  //grupa kodów
        'to'            => '8500500500,48501501501,48502502502',                    //grupa odbiorców  
        'from'          => 'SMSAPI',                                                //pole nadawcy  
        'message'       => 'treść z kodem rabatowym [%kod%]',                     //treść wiadomości
    );

?>

SMSAPI umożliwia wysyłanie wiadomości z kodami rabatowymi. Aby wysyłać takie wiadomości trzeba najpierw przygotować listę kodów rabatowych w panelu klienta Kody rabatowe. Kody rabatowe mogą być wczytane z uprzednio przygotowanego pliku csv lub skorzystać z wbudowanego generatora kodów.

Podczas wysyłki system pobiera kody z podanej listy jednocześnie oznaczając je jako wykorzystane (jeden kod może być wykorzystany tylko raz). Aby móc wykorzystać grupę kodów do wysyłki musi być ona aktywna (data ważności nie minęła) oraz zawierać odpowiednią liczbę kodów

Wiadomości z idz.do

https://api.smsapi.pl/sms.do - dla połączeń szyfrowanych SSL

curl -H "Authorization: Bearer access_token" \
"https://api.smsapi.pl/sms.do?\
from=pole_nadawcy&\
to=48600111222&\
message=test wiadomości z skróconym linkiem [%idzdo:www.smsapi.pl%] &\
format=json"

<?php

$params = array(
    'access_token'  => 'token SMSAPI'                                                       //token SMSAPI  
    'to'            => '48500500500',                                                       //grupa odbiorców  
    'from'          => 'SMSAPI',                                                            //pole nadawcy  
    'message'       => 'test wiadomości z skróconym linkiem [%idzdo:www.smsapi.pl%]',     //treść wiadomości
    );

?>

W celu wysłania wiadomości zawierającej skrócony link, SMSAPI udostępnia „skracacz” idz.do. Linki wygenerowane przy pomocy skracacza mają format http://idz.do/ABCD. Aby w treści wiadomości umieścić skrócony link należy w parametrze message dodać [%idzdo:adres_url%]. Każdy kolejny numer w wysyłce otrzyma unikalny link na podstawie którego możliwe jest śledzenie kliknięć oraz informacji m.in. o czasie wywołania linku, typie urządzenia, systemie operacyjnym.

4. Wykorzystanie szablonów

https://api.smsapi.pl/sms.do - dla połączeń szyfrowanych SSL >Przykład


Nazwa Szablonu:         Powiadomienie
Treść Szablonu:       Witaj [%1%], Twoje zamówienie zostało wysłane.

curl -H "Authorization: Bearer access_token" \
"https://api.smsapi.pl/sms.do?\
from=pole_nadawcy&\
to=48500500500&\
template=Powiadomienie&\
param1=Marek&\
format=json"

<?php

$params = array(
    'access_token'  => 'token_smsapi',          //token sms api
    'to'       => '48500500500'                 //numer odbiorczy
    'from'     => 'SMSAPI',                     //pole nadawcy
    'template' => 'Powiadomienie'               //nazwa szablonu
    'param1'   => 'Marek'
    );

?>

Treść wysłanej wiadomości:
Witaj Marek, Twoje zamówienie zostało wysłane.

Przy wykorzystaniu szablonów w bardzo prosty sposób zmienić można treść SMS-ów powiadamiających (w sklepach, serwisach internetowych, klinikach itp.) bez ingerencji w kod skryptu odpowiedzialnego za wysyłanie wiadomości SMS.

W celu skorzystania z szablonów należy :

Po zalogowaniu na stronie http://www.smsapi.pl dodać szablon w menu Wiadomości Szablony.
W miejsce, w którym ma występować parametr należy wpisać [%N%] gdzie N to liczba od 1 do 4.
W celu wykorzystania szablonu w interfejsie API należy wybrać jeden z szablonów poprzez wpisanie parametru &template=nazwa_szablonu
Prócz podstawowych parametrów w trakcie używania szablonów dostępne są parametry

Parametr	Opis
template	Nazwa szablonu
paramN	Parametr wstawiany w miejsce [%N%] w szablonie gdzie N to liczba od 1 do 4
single	Jeżeli wiadomość będzie składała się z więcej niż 160 znaków nie zostanie wysłana i zwrócony zostanie `ERROR:12` (&single=1)

W razie problemów podczas odwoływania się do podstawowego adresu URL można wykorzystać adres URL backup https://api2.smsapi.pl/

5. mail2SMS

Aby wysłać SMS-a za pomocą maila należy wysłać maila według schematu:


ADRES:	sms.do@smsapi.pl
TEMAT:	login@haslo_32znaki_w_md5
TREŚĆ:	from=nadawca&to=numer&message=tresc wiadomosci


ADRES:	sms.do@smsapi.pl
TEMAT:	login@8456fkty567gb3bg37b357b3457b3457
TREŚĆ:	from=nadawca&to=numer&message=tresc wiadomosci

Dodanie parametru raport=1 spowoduje odsyłanie maila z raportem (potwierdzenie wysłania wiadomości lub błąd – jest to przydatne w trakcie testowania usługi):


ADRES:	sms.do@smsapi.pl
TEMAT:	login@8456fkty567gb3bg37b357b3457b3457
TREŚĆ:	from=nadawca&to=numer&raport=1&message=tresc wiadomosci

Wiadomości mogą być wysyłane w kodowaniu plain / quotedprintable / base64. Oprócz parametrów wymienionych w powyższych przykładach w mail2sms dostępne są wszystkie parametry wymienione w Punkcie 2. Wysyłanie pojedynczych SMS'ów. W celu wysłania wiadomości Eco przez mail2SMS podać jako wartość parametru from ustawić Eco (from=Eco). W celu wysłania wiadomości 2way przez mail2SMS podać jako wartość parametru from ustawić 2way (from=2way). Nazwa nadawcy (zmienna &from=) musi być aktywna.

6. Sprawdzenie ilości punktów

https://api.smsapi.pl/user.do - dla połączeń szyfrowanych SSL

Przykład:


curl -H "Authorization: Bearer access_token" \
"https://api.smsapi.pl/user.do?\
credits=1\
format=json"

I. Przykład odpowiedzi kiedy parametr &format=json został użyty:

w przypadku powodzenia:


{
    "points":100.00, // Ilość punktów dostępnych na koncie SMSAPI
}

II. Przykład odpowiedzi bez użycia parametru &format:

a) w przypadku powodzenia:

Response :   Credits: <CREDITS>

b) w przypadku niepowodzenia:

Response :  ERROR: <ERR>

<CREDITS>   Liczba punktów 

Example :   Credits: 100.000

Poniżej przedstawiona jest funkcja dodatkowa służąca do sprawdzenia stanu środków pozostałych na koncie klienta.

Parametr	Opis
access_token	token przypisany do konta w serwisie SMSAPI
credits	Należy podać wartość „1”
details	Dodatkowo wyświetlana jest ilość wiadomości Pro oraz Eco
format	Dla &format=json powoduje, że zwrotka z API wysyłana jest w formacie JSON

W razie problemów podczas odwoływania się do podstawowego adresu URL można wykorzystać adres URL backup https://api2.smsapi.pl/

7. Wiadomości MMS

https://api.smsapi.pl/mms.do - dla połączeń szyfrowanych SSL

curl -H "Authorization Bearer access_token" \
"https://api.smsapi.pl/mms.do?\
to=48500000000&\
subject=Testowy_MMS&\
smil=[smil]&\
format=json"

<?php

$params = array(
    'acces_token' => 'smsapi_token',    //token SMSAPI
    'to'          => '48500000000',     //numer odbiorcy  
    'subject'     => 'Testowy_MMS',         //pole nadawcy  
    'smil'        => 'smil',            //treść wiadomości
    );

?>

Przykładowa wiadomość MMS w formacie SMIL z wykorzystaniem kodowania BASE64


<smil>
    <head>
        <layout>
            <root-layoutbackgroundColor="#FFFFFF"height="100%"width="100%"/>
            <region id="Text"top="50%"height="50%"left="0"width="100%" fit="scroll"/>
        </layout>
    </head>
<body>
   <par>
      <img
      src="data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAKgAAAAbCAYAAADoFcRvAAAAAXNSR0IArs4c6QAAA
AZiS0dEAP8A/wD/oL2nkwAACw9JREFUeNrtW2tQVdcVBr0gIATkeamKr1SjJGYiaLDUkvJQBNKmEgyOptWpGqQRbHwQg
xFUFBSMo8ZXIqDMVJzqWIyKigqSijyMT0bUYidjUILlJQgir7v7bXJh9tn33Mu5L+EHa+abPXPPOnvvs/d31tprrXNNT
AZkQAZkQAbEQEIIcQT+DlwEfgRqDYgKYAQ33gxOpwxwfQXP6QU8ZcbNUqNnCgQBh4BSoNrAaxKj77P86qvrHwO1DObo2
V8A15+
+eAIUAAnA62rGzGD0H6rbtLCOjg66aUaR1tZWxfbt273YMffv37+C12tsbDxpZHLaNDc3/8SOeevWrRoRPRfge2JEycr
KuqQnmSa5Jhe9QEu6IU+88hStzi+5bVjsOrY/Q8I15VoTJSo/pmNUegUz/06xTZsBcrYTI8u2bdu82XF37ty5So3qCmM
R9MWLFwf5wYqLi+t5y9nS0pJv7PU4ceJEgR7kHCRPyMsTI4J8y/dHdSbonJg4YxGUwUJ2TIe/fVvZM/eEPIXKpB4/fpz
LL97hw4dJVFQUiYiIIMuWLdMbixcvJoGBgZPYcXft2rVSbONevnzZgsbbCNbzz2LjlZSU1LF67e3tvrzOjRs3yOrVq7v
Ww1BrEhoamq7rs7imlCzWYKkUurp6nqCw0MR65hJiNT2UWP3mQ+lQ6r/2/gpYxX8L55dU0IB2GEPQJxoJWltb28JuxqZ
Nmwh+PgxEARHAMgNgMWAthaBUmpqaqBu2NiA5J8N6Nkgh6O3btzPZ6w8ePCByufwOLq1Wroeh1sRTR+v5Bjb5GbvpTqu
OCq3o5vzHaG31JujWq0TmMnabDs/crZ9i5R32kn+JHD5N/a1kgtbX13eyGzJ37tzUVxGUaSIoFRAqzUDkNGtoaPhB3Tg
8QfPz80s5V9xIj0r9JZiVb74scO1On/2DDB4mv+cce5K3VBmGIKjd/E1e+szXfOyUL1y3FQrmhrPufMkEraurU7Absnv
37kV9QdDOzk4x/oTqOw5c9la+U4VCoZag58+fL2d1L1y48GN/ISc2cYnAUiZdIbLhE8roJct3ZlVRl9xDru0/UFfvry9
BbUKi/PSZs83sSC/ezb/2x88WaePiFZzFWNsXBM3IyFDAvQqI1NbW9hLNaD2s50wEgALmp6amkufPn6sl6MmTJ+9xUX5
VPyGnKwgpcO02s5a24dJEpcqf7BYkdHJRPXX1Zn1K0JDlXpi3QmeCFhYWCiJ4RLD1aJYCE4CRgJuWoPfYa0vQgwcP3vb
393/IW1KcR4vRWOhATlscE/7H9nXs2DEyffr04yCtWoKuX7/+EnsPdOkL/A3goeN6jALkgKU+Gw2XfVFwjos8QEwGDV7
P6uC8eMJl/VkuaCr5uk8JGhjxLl4UoQX9YJV0giI6LRfzrSBKG9AENGsJek8NDX4BGnAslELQs2fPFuJn740bNyr4ueC
l2awlOWmq6DTbR3l5OXFzc/sO+dggTS5+woQJEVVVVUTNmuiyHhQNwH/pY9I4FBiupfVcwG6wy4YLxGzEG8W4NIhTHYk
Iuk4kuveRRNAP18ZzGQFE4tH+
+hAUL1Io7Udg+UOi/iKZoA4ODpF79uwxetoPsNJEULjWG/T3YcOGbTlz5gzhrBg1q5LfZOiv4AoFJCQk5AkuOaFAMEcT
QSF2wcHBdQisjLYYOBfTytpsieR0w9myhd1gu/C4F9YBS2jVZxLgDozs1jc1s/ir3UdxxCnmOHFac6yrddmQUwKdXr2a
TfDyL1y+PEOcvzz9C9b+ix4j3mPmIgPeVo6rCROByfTFQl72oYD0CJgsPYNnSyYohLrPPTQ3l52dTZ4+NU5BCRWcRCkE
hVjCil2qqanhq0yPpFge6LiDAG3svXDbHbgUQK8nJyeH90JQKjO9vLya0tPTyd27d2lu1hjrQc20Yy/kNJVvyc9WyXUm
F7UjCKLo6EJKSRV+d+r29ECayWDZfRwBymg7yNr+kvk4D3lva2dqbulnOsSqAu1PXRhi9dDUwnpsD4FnLbVwiT9/BmMp
esYWRzt0OsXytLZzv6R7MVwbgnYLzVtlOzo6Vk+ZMoX4+vrqhKCgIBITE0PKysr4gIeedUdJIGiXqwoLC2sUyY/mUPet
gZz22Pi7XBROhg4dGt+tk5KS8pEEglKZBqSbmZmVjR8/vtXHx0en9fDz8yMLFy4kR44cIezZlwqMwYZeEvLzpVZokH7a
z91upiQrbWli3FyCwR6szFcPZcAeI2Qy59En8NLoVEWy/
+RrAsKncZUkyQTtuQeYAvjqiCAgBm7yEU+wgoKCRRIJ2hWVHjhwQMXyYJOXq5s43PI+VhcpNOLp6XmV3RwtCMpu9HjAR
8f1oEcTeg4/grKq4HyNAPWaBus5ynVr4XMu4Omq7rgmF6si5Rq1WO9yfVCXbA4MAayVMNVksWnUz0Amoj8CyfcWafX3E
uKy8SJxWnmEWPstIrDmObjfSl+CGkRgAechiiZcimezFgQ1MTc3/7a0tFSsFOouYj3/oJJEDQ19zqRhdCWowQQ51lp2f
jTnqiEhn8VutuPyNCJz/XWnzGVMO6L1DhW4vt4xxP13gYI+EnLd4W4fAOVABUDTThvVWuzkYh/o3APKlO1NRPKjVM8Cp
hFmIyYSMzd3DXiTyOTjOk2tbKtxx01grdKim/QLgiYkJHjBJQsIs3fv3q3aEJQ+0NSpU8tR7eLPb/fRmDPkHIPfBCklB
EO0ZPsB32FfEhRVqifsHM+dO/cfNZbsE+GZs5huON3kycoXbpII3gKc2X4G2Ti4281PeMafX9HOEBvXbt6Gz1XOjKGfi
2UATJWl2mkaQK35m4C9Ul/cXfchQachIS5wafv27UvSkqBUJkdGRjaLRMKHuhUwjuDTuDt37hBLS8tvxDrrS4Lm5eX1S
tBfXPvVRpYkQ30WdCoJqK3IEOik8WVQVHYeUfetmgddE6+SBw3+1N+Ya9JnBIU79wGJeAuqC0GpLKVJdhF5H1jD1fCJt
7d3ubqgoC8JWlRU9DM715ycHBUXjwDklMC1Rx8icKkr9RjWwmKy78/UCnNWOfFVJOr7JUFpOqiysjKTZ9MaiI4EpQn00
/fv3+czA83t3FsQGxtLy38e6vrpC4LSKhIQ8uzZs1Z2rsePHy/jrOfHPEHMR79dqslFSpRgu/D4Ts7Vt6F9q98TFOv0H
t0n+u2uAVAEXEekXc+T8/Lly8TJyclbV4LS6DEgIOCRppwktbLKw7iJrgTFTzLgqAHXpFhZReKPKCQ8PPyfDDldeNduE
7isHZfeMQQRBjuOzHRed5r/4ukBWst+TVBsaryxy0g0yEEN/JoyZdMl+GpK8EX9qVOnbkp4nhlIuot+/V9RUUHGjRt3q
rcOUOoMZ+
+7fv16PXfdsrq6utnYa7Jjxw56rvRWvhRmIEuO8JvJg/Rl22BALsiRHqpRyZ8mXenJEduGro3j00T6ljp7E8flqZXM2V
ghZlGS8EUTMRaQ+yMeHh6Nygi0R/AXkBWsXmZm5jUpD0ST7rTixd4LQpF58+bR/xb1+n+cxMTEMFql6r43NzdX8J+kuL
g4K1jVVmOtB/7BQKKjoyn5vmLytyEgSrt8Uy6hoB98oPJz0wh86CqDdo/ThaQrzSBH18fT+MpoHXvNJf4crHjE741JUP
sluyq6x3OO/a5T9HwC1BoRxWrc1AxOT+oHITT4yebupbk2qd+O0nNXDXNvlkhi/qoR1+MxEM2NSfOXDZyOp5E4kSaydt
1jBXDXKoExRj6iZzDjPTQZkAEZkAEZED3l/yw2+Xsa+AiKAAAAAElFTkSuQmCC"></img>
        </par>
     </body>
</smil>

Poniższa tabela przedstawia parametry niezbędne do wysłania wiadomości MMS.

Parametr	Opis
access_token	token przypisany do konta w serwisie SMSAPI
to	Numer odbiorcy wiadomości w formacie 48xxxxxxxxx lub xxxxxxxxx.
group	Nazwa grupy kontaktów z książki telefonicznej, do których ma zostać wysłana wiadomość
subject	Temat wiadomości MMS. Temat może zawierać maksymalnie 30 znaków, w przypadku przekroczenia limitu wiadomość jest odrzucana i zwracany jest błąd 26.
date	Data w formacie unixtime (&date=1287734110) lub ISO 8601 (&date=2012-05-10T08:40:27+00:00) kiedy wiadomość ma być wysłana
date_validate	Ustawienie „1” sprawdza poprawność formatu podanej daty. W przypadku wystąpienia błędnej daty zwrócony zostanie błąd `ERROR:54`
smil	Wiadomość MMS w formacie SMIL 1.0
idx	Opcjonalny parametr użytkownika wysyłany z wiadomością a następnie zwracany przy wywołaniu zwrotnym CALLBACK. Parametr idx może mieć maksymalnie 255 znaków dopuszczalne są cyfry 0 - 9 oraz litery a – z (wielkość liter nie jest rozróżniana). (&idx=123)
check_idx	Pozwala zabezpieczyć przed wysłanie dwóch wiadomości z identyczną wartością parametru idx. W przypadku ustawienia parametru (&check_idx=1) system sprawdza czy wiadomość z takim idx już została przyjęta, jeśli tak zwracany jest błąd 53.
notify_url	Parametr do podawania URL do skryptu callback do odbierania raportów doręczeń. Jeżeli na koncie nie ma ustawionego stałego adresu callback dlr lub jeżeli dla tej wiadomości adres ten ma być inny niż stały można go podać w parametrze &notify_url.
test	Wiadomość nie jest wysyłana, wyświetlana jest jedynie odpowiedź (w celach testowych). (&test=1)
format	Dla &format=json powoduje, że zwrotka z API wysyłana jest w formacie JSON

W razie problemów podczas odwoływania się do podstawowego adresu URL można wykorzystać adres URL backup https://api2.smsapi.pl/

8. Wiadomości VMS

https://api.smsapi.pl/vms.do - dla połączeń szyfrowanych SSL

curl -H "Authorization: Bearer access_token" \
"https://api.smsapi.pl/vms.do?\
to=48500000000&\
tts=treść_Wiadomości"

<?php

$params = array(
    'acces_token' => 'smsapi_token',        //token SMSAPI
    'to'          => '48500000000',         //numer odbiorcy  
    'tts'         => 'Treść_Wiadomości', //pole nadawcy  
    );

?>

Lub :

curl -H "Authorization: Bearer access_token" \
"https://api.smsapi.pl/vms.do?\
to=48500000000&\
file=http://hiper.lacze.do/pliku.wav"

<?php

$params = array(
    'acces_token' => 'smsapi_token',                    //token SMSAPI
    'to'          => '48500000000',                     //numer odbiorcy  
    'file'        => 'http://hiper.lacze.do/pliku.wav', //pole nadawcy  
    );

?>

Poniższa tabela przedstawia parametry niezbędne do wysłania wiadomości VMS:

Parametr	Opis
access_token	token przypisany do konta w serwisie SMSAPI
to	Numer odbiorcy wiadomości w formacie 48xxxxxxxxx lub xxxxxxxxx.
group	Nazwa grupy kontaktów z książki telefonicznej, do których ma zostać wysłana wiadomość
tts	Treść wiadomości głosowej w postaci tekstu. Tekst powinien być podawany w kodowaniu UTF-8, w przeciwny razie zostanie zwrócony błąd `Error:11`.
file	Treść wiadomości w postaci pliku wave, akceptowalny link do pliku umieszczonego w sieci lub plik wysłany postem metodą multipart form-data
date	Data w formacie unixtime (&date=1287734110) lub ISO 8601 (&date=2012-05-10T08:40:27+00:00) kiedy wiadomość ma być wysłana
date_validate	Ustawienie „1” sprawdza poprawność formatu podanej daty. W przypadku wystąpienia błędnej daty zwrócony zostanie błąd `ERROR:54`
try	Ilość prób połączenia (dopuszczalne wartości od 1 do 6)
interval	Czas w sekundach po jakim powtórzone ma być połączenie w przypadku jego nieodebrania lub odrzucenia (dopuszczalne wartości od 300 do 7200s)
skip_gsm	Ustawienie tego parametru (&skip_gsm=1) spowoduje pominięcie telefonów komórkowych podczas wysyłki i wysłanie wiadomości tylko do numerów stacjonarnych
check_idx	Pozwala zabezpieczyć przed wysłanie dwóch wiadomości z identyczną wartością parametru idx. W przypadku ustawienia parametru (&check_idx=1) system sprawdza czy wiadomość z takim idx już została przyjęta, jeśli tak zwracany jest błąd 53.
notify_url	Parametr do podawania URL do skryptu callback do odbierania raportów doręczeń. Jeżeli na koncie nie ma ustawionego stałego adresu callback dlr lub jeżeli dla tej wiadomości adres ten ma być inny niż stały można go podać w parametrze &notify_url.
test	Wiadomość nie jest wysyłana, wyświetlana jest jedynie odpowiedź (w celach testowych). (&test=1)
format	Dla &format=json powoduje, że zwrotka z API wysyłana jest w formacie JSON

W razie problemów podczas odwoływania się do podstawowego adresu URL można wykorzystać adres URL backup https://api2.smsapi.pl/

9. Raporty Callback

Usługa callback pozwala na otrzymywanie aktualizacji statusów wysyłek (raportów doręczeń), odebranych wiadomości SMS/MMS, kliknięć w skrócone linki (idz.do) lub sprawdzeń numerów w bazie HLR do enpointa skonfigurowanego po stronie użytkownika SMSAPI. Adres URL endpointa wprowadzany jest w panelu klienta SMSAPI. Po wystąpieniu nowego zdarzenia, SMSAPI generuje odwołanie POST lub GET z zestawem danych do endpointa użytkownika SMSAPI.

Odwołania mogą wystąpić z podanych poniżej adresów IP: 85.194.241.82,89.174.81.103,89.174.81.98,89.174.81.102,91.185.184.29,91.185.185.2,185.36.169.252 .

Raporty SMS


<?php

    if($_GET['MsgId'] && $_GET['status'] ) {
        mysqli_select_db('database_name',mysqli_connect('localhost','login','password'));
        $arIds = explode(',',$_GET['MsgId']);
        $arStatus = explode(',',$_GET['status']);
        $arIdx = explode(',',$_GET['idx']);
        if($arIds){ 
            foreach($arIds as $k => $v){
                mysqli_query("UPDATE sms SET sms_status = '".mysqli_real_escape_string($arStatus[$k])."', 
    sms_index = '".mysqli_real_escape_string($arIdx[$k])."' WHERE sms_id ='".mysqli_real_escape_string($v)."' LIMIT 1");
       }
        mysqli_close();
        echo"OK";
    }

?>

W celu sprawdzenia statusu wiadomości należy w panelu klienta Adresy Callback ustawić adres do skryptu do którego przekazywany będzie raport doręczenia wiadomości. Aby móc wprowadzić adres callback, skrypt musi być umieszczony w podanej lokalizacji.

Przykład: http://www.moja_strona.pl/status_update.php

Ważne, aby podany adres był poprawny, tzn. aby wskazany skrypt istniał na serwerze. W momencie dodawania adresu do skryptu callback w panelu SMSAPI, weryfikowany jest on poprzez odwołanie się do niego z pustą tablicą GET. Do skryptu wysyłane będą status wiadomości (od 1 do 5 w zależności od tego dla ilu wiadomości zmienił się status). Parametry będą podane metodą GET i będą oddzielone przecinkami.

Parametr	Opis
MsgId	ID wysłanej wiadomości.Parametr MsgId jest parametrem o zmiennej długości, ale nie większej niż 32 znaki.
status	Kod statusu doręczenia.
status_name	Nazwa statusu doręczenia.
idx	Opcjonalny parametr użytkownika wysłany z SMS'em
donedate	Czas dostarczenia wiadomości w formacie unixtime
username	Nazwa użytkownika wysyłającego wiadomość
points	Ilość punktów pobranych za wysyłkę wiadomości
from	Pole nadawcy z którym została wysłana wiadomość
to	Numer na jaki wysyłana była wiadomość
mcc	Kod Mobile Country Code identyfikujący jednoznacznie kraj przynależności numeru
mnc	Kod Mobile Network Code identyfikujący jednoznacznie sieć w ramach kraju (MCC) do której numer należy.

Skrypt powinien zwracać OK, w innym przypadku nastąpią ponowne odwołania.

Raporty MMS

W celu sprawdzenia statusu wiadomości należy w panelu klienta Adresy Callback ustawić adres do skryptu do którego przekazywany będzie raport doręczenia wiadomości.

Przykład: http://www.moja_strona.pl/status_update.php

Poniższa tabela przedstawia wysyłane parametry:

Parametr	Opis
MsgId	ID wysłanej wiadomości. Parametr MsgId jest parametrem o zmiennej długości, ale nie większej niż 32 znaki.
status	Kod doręczenia wiadomości
to	Numer na jaki wysyłana była wiadomość
idx	Opcjonalny parametr użytkownika wysłany z MMS'em
donedate	Czas dostarczenia wiadomości w formacie unixtime
username	Nazwa użytkownika z którego została wysłana wiadomość

Skrypt powinien zwracać OK, w innym przypadku nastąpią ponowne odwołania.

Raport VMS

W celu sprawdzenia statusu wiadomości należy w panelu klienta Adresy Callback ustawić adres do skryptu do którego przekazywany będzie raport doręczenia wiadomości.

Przykład: http://www.moja_strona.pl/status_update.php

Poniższa tabela przedstawia wysyłane parametry:

Parametr	Opis
MsgId	ID wysłanej wiadomości. Parametr MsgId jest parametrem o zmiennej długości, ale nie większej niż 32 znaki.
status	Kod doręczenia wiadomości
to	Numer na jaki wysyłana była wiadomość
idx	Opcjonalny parametr użytkownika wysłany z MMS'em
donedate	Czas dostarczenia wiadomości w formacie unixtime
username	Nazwa użytkownika z którego została wysłana wiadomość
pressed	Klawisz wybrany przez odbiorcę wiadomości podczas jej odsłuchiwania
hangup_time	Czas trwania połączenia

Skrypt powinien zwracać OK, w innym przypadku nastąpią ponowne odwołania.

Wysyłki masowe

Do skryptu CALLBACK dla wysyłek masowych wysyłane jest odwołanie w momencie rozpoczęcia wysyłania danej wysyłki. Odwołanie zawiera parametry przedstawione w tabeli poniżej. W celu włączenia CALLBACK'a dla wysyłek masowych należy w panelu klienta Adresy Callback ustawić adres do skryptu do którego przekazywane będą statusy wysyłek masowych

Przykład: http://www.moja_strona.pl/bulk_callback.php

Poniższa tabela przedstawia wysyłane parametry:

Parametr	Opis
type	Typ wiadomości SMS/MMS/VMS
all	Liczba wiadomości (numerów) w wysyłce.
points	Liczba pobranych punktów za wysyłkę.
to	Określa gdzie (za pomocą której zakładki bramki SMS) została wysłana wysyłka csv, csv_and_text lub phonebook.
info	W przypadku wysyłki to numerów z Bazy lista grup do których zostały wysłane wiadomości.
text	Tekst wysłanej wiadomości.

Skrypt powinien zwracać OK, w innym przypadku nastąpią ponowne odwołania.

Kliknięcia idz.do

W celu sprawdzenia kliknięć w link idz.do należy w panelu klienta Adresy Callback ustawić adres do skryptu do którego przekazywany będzie raport kliknięć idz.do.

Przykład: http://www.moja_strona.pl/idzdo_callback.php

Poniższa tabela przedstawia wysyłane parametry:

Parametr	Opis
MsgId	ID wysłanej wiadomości. Parametr MsgId jest parametrem o zmiennej długości, ale nie większej niż 32 znaki.
to	Numer na jaki wysyłana była wiadomość
click_date	Czas pierwszego otwarcia odnośnika w formacie unixtime
device	Typ urządzenia
operating_system	System operacyjny
browser	Rodzaj przeglądarki
username	Nazwa użytkownika z którego została wysłana wiadomość
ip	Adres IP z którego nastąpiło kliknięcie w skrócony link
sufix	Sufiks skróconego adresu, np. Hq9Y(dla http://idz.do/Hq9Y)

Skrypt powinien zwracać OK, w innym przypadku nastąpią ponowne odwołania.

11. Odbiory Wiadomości

Serwis SMSAPI oferuje również odbiór wiadomości SMS oraz MMS. Odbierać można wiadomości SMS i/lub MMS wysłane na wykupiony numer dedykowany lub odpowiedzi na wysłane wiadomości 2way.

Czas oczekiwania na wiadomość zwrotną od adresata w systemie 2Way wynosi 24h. Po tym czasie wiadomość nie zostanie przypisana do konta klienta

Odbiór SMS


<?php

    function messageReceive()
    {
        $received   = $_POST;
        $content = print_r($received, true);
        $sms_from   = $received['sms_from'];
        $sms_to     = $received['sms_to'];
        $sms_date   = $received['sms_date'];
        $sms_text   = $received['sms_text'];
        $username   = $received['username'];

        $filename = "sms.log";

        file_put_contents($filename, $content);

        if (is_file($filename)) {
            return true;
            } else {
            return false;
            }
    }

    if ($_POST) {
        if (messageReceive() === true) {
            echo "OK";
        }
    }

?>

Odbiór wiadomości odbywać się będzie za pomocą skryptu, do którego adres należy ustawić w Adresy Callback.

Działanie skryptu opisane jest poniżej:

Po odebraniu wiadomości odwoływać będziemy się do skryptu stworzonego przez Państwa, który powinien obsługiwać następujące parametry z tablicy POST:

Parametr	Opis
sms_to	numer telefonu odbiorcy
sms_from	numer telefonu nadawcy
sms_text	treść wiadomości
sms_date	czas w postaci unixtime pobrany z SMS'a
username	nazwa użytkownika (login) do którego wiadomość została przydzielona
MsgId	id wiadomości 2way na którą jest to odpowiedź, dla odpowiedzi na numer dedykowany pole to będzie puste. Parametr MsgId jest parametrem o zmiennej długości, ale nie większej niż 32 znaki.

Dane wysyłane są w kodowaniu UTF8.

Skrypt powinien zwracać OK, w innym przypadku nastąpią ponowne odwołania.

W momencie dodawania adresu do skryptu callback w panelu SMSAPI, weryfikowany jest on poprzez odwołanie się do niego z pustą tablicą GET.

Odbiór MMS


<?php

    function receiveMms()
    {
        $received = false;

        foreach ($_FILES as $plik) 
        {
            if (is_uploaded_file($plik['tmp_name']))
            {
                if (move_uploaded_file($plik['tmp_name'],'mms/'.$plik['name'])) {
                    $received = true;
                }
            }
        }
        return $received;
    }


    if ($_FILES) {
        if (receiveMms() === true) {
            echo "OK";
        }
    }

?>

Odbiór wiadomości odbywać się będzie za pomocą skryptu, do którego adres należy ustawić w Adresy Callback. Działanie skryptu opisane jest poniżej:Po odebraniu wiadomości odwoływać będziemy się do skryptu stworzonego przez Państwa, który powinien obsługiwać parametry z tablicy POST oraz FILES podane poniżej:

Tablica POST:

Parametr	Opis
mms_to	numer telefonu odbiorcy
mms_from	numer telefonu nadawcy
mms_subject	temat wiadomości
mms_date	czas w postaci unixtime pobrany z MMS'a

Tablica FILES:

Parametr	Opis
name	oryginalna nazwa wysyłanego pliku
type	typ MIME wysyłanego pliku (JPEG, GIF, ...)
tmp_name	tymczasowa nazwa pliku, który został wysłany na serwer
error	numer błędu (0 oznacza prawidłowe wysłanie)
size	rozmiar wysyłanego pliku (w bajtach)

Dane wysyłane są w kodowaniu UTF8.

Skrypt powinien zwracać OK (np. echo 'OK';), w innym przypadku nastąpią ponowne odwołania.

12. HLR

curl -H "Authorization: Bearer access_token" \
"https://api.smsapi.pl/hlr.do?\
number=48500000000&\
format=json"

<?php
$params = array(
    'access_token'    => 'smsapi_token',            //token SMSAPI
    'number'          => '48500000000',             //numer do sprawdzenia

);
if ($params['access_token']&&$params['number']) {
    $date = '?'.http_build_query($params);
    $file = fopen('https://api.smsapi.pl/hlr.do'.$date,'r');
    $result = fread($file,1024);
    fclose($file);
    echo $result;
}
?>

HLR (ang. Home Location Register) – Rejestr Abonentów Macierzystych – element infrastruktury telekomunikacyjnej zawierający informacje o każdym aktywnym numerze GSM. W celu skorzystania z tej opcji należy wysłać żądanie pod adres: https://api.smsapi.pl/hlr.do z parametrami opisanymi w tabeli poniżej. Informacje o numerach będą wysłane do skryptu do którego adres należy podać w panelu klienta na stronie https://api.smsapi.pl w menu Adresy Callback w polu „Adres callback - odwołania HLR”.

Ważne aby wprowadzony adres URL prowadził do istniejącego, działającego skryptu. Po sprawdzeniu numeru w systemie HLR informacja o nim zostanie przesłana do podanego adresu URL w postaci tablicy POST. W jednym odwołaniu może znajdować się do 20 numerów.

Poniższa tabela przedstawia parametry odwołania HLR:

Parametr	Opis
access_token	token przypisany do konta w serwisie SMSAPI
number	Numer/y, które mają być sprawdzone w HLR.
idx	Opcjonalny parametr użytkownika wysyłany z odwołaniem, a następnie zwracany przy wywołaniu zwrotnym CALLBACK. Parametr idx może mieć maksymalnie 255 znaków dopuszczalne są cyfry 0- 9 oraz litery a – z (wielkość liter nie jest rozróżniana). (&idx=123)
format	Dla &format=json powoduje, że zwrotka z API wysyłana jest w formacie JSON.

Poniższa tabela przedstawia parametry wysyłane do skryptu:

Parametr	Opis
id	id zwrócony podczas sprawdzania numeru
number	sprawdzany numer
mcc	numer identyfikujący kraj (ang. Mobile Country Code)
mnc	numer sieci w danym kraju (ang. Mobile Network Code)
info	nazwa sieci, do której należy numer, lub opis błędu
status	OK kiedy numer jest poprawny, FAIL kiedy numer jest błędny (np. wyłączony, nieaktywny itp.)
date	Data w formacie UNIX timestamp, kiedy numer był sprawdzany
ported	0 jeżeli numer jest nieprzeniesiony, 1 jeżeli numer jest przeniesiony
ported_from	null kiedy numer jest nieprzeniesiony lub nazwa sieci z której numer został przeniesiony
idx	Opcjonalny parametr użytkownika wysłany z zapytaniem HLR

13. Konto użytkownika

Dodawanie użytkownika

Przykład:


curl -H "Authorization: Bearer access_token" \
"https://api.smsapi.pl/user.do?\
password=&\
add_user=subuser&\
pass=subuser_md5_password\
format=json"

Przykład odpowiedzi:


OK:<SUB_NAME>
ERROR:<ERR>

Przykład odpowiedzi gdy &format = :




{
    "username":"subuser",
    "limit":0, 
    "month_limit":0,    // miesięczny limit odnawialny
    "senders":0,        // dostęp do pól nadawcy konta głównego
    "phonebook":0,      // dostęp do bazy kontaktów konta głównego
    "active":false, 
    "info":"unknown" 
}

Gdy wystąpi błąd:




{
    "error": 123,
    "message": "error message"
}

W celu dodania nowego konta użytkownika należy w odwołaniu umieścić parametr &add_user=poduzytkownik oraz parametry określające właściwości dodawanego konta.

Zarządzanie kontem odbywa się przez wysłanie metodą GET lub POST danych do adresu połączenia odpowiednich parametrów:

Parametr	Opis
access_token	Token przypisany do konta w serwisie SMSAPI
add_user	Nazwa dodawanego użytkownika
pass	Hasło do panelu klienta SMSAPI dodawanego
pass_api	Hasło do interfejsu API dla użytkownika brak tego parametru spowoduje ustawienie jako hasła do API kopii hasła do panelu klient
limit	Limit punktów przydzielony użytkownikowi
month_limit	Ilość punktów która będzie przypisana do konta użytkownika każdego pierwszego dnia
senders	Udostępnienie pól nadawców konta głównego (dostępne wartości: 1 – udostępniaj, 0 – nie udostępniaj, domyślnie wartość równa 0)
phonebook	Udostępnienie grup książki telefonicznej konta głównego (dostępne wartości: 1 – udostępniaj, 0 – nie udostępniaj, domyślnie wartość równa 0). Po udostępnieniu książki użytkownik będzie mógł wysyłać do grup wiadomości nie będzie jednak widział poszczególnych kontaktów w książce telefonicznej.
active	Aktywowanie konta użytkownika (dostępne wartości: 1 – aktywne, 0 – nieaktywne, domyślnie wartość równa 0)
info	Dodatkowy opis użytkownika
format	Dla &format=json powoduje, że zwrotka z API wysyłana jest w formacie JSON, w zwrotce oprócz potwierdzenia , zawierająca następujące parametry: limit, limit_month, senders, phonebook, active, info.
without_prefix	Ustawienie tego parametru pozwala na dodanie użytkownika bez prefixu użytkownika głównego (poduzytkownik zamiast uzytkownik_poduzutkownik)

Edycja użytkownika

curl -H "Authorization: Bearer access_token" \
"https://api.smsapi.pl/user.do?\
set_user=subuser&\
pass=new_subuser_password_in_md5&\
active=1&\
format=json"

Przykład odpowiedzi:


OK:<SUB_NAME>
ERROR:<ERR>

Przykład odpowiedzi kiedy &format = json :





{
    "username":"subuser",
    "limit":0, 
    "month_limit":0, 
    "senders":0, 
    "phonebook":0, 
    "active":false, 
    "info":"unknown"
}

W przypadku wystąpienia błędu:


{
    "error": 123,
    "message": "error message"
}

W celu edycji parametrów istniejącego konta użytkownika należy w odwołaniu umieścić parametr &set_user=uzytkownik oraz parametr odpowiadający właściwości, która ma zostać zmieniona.

Zarządzanie kontem odbywa się przez wysłanie metodą GET lub POST danych do adresu połączenia:

Parametr	Opis
access_token	Token przypisany do konta w serwisie SMSAPI
set_user	Nazwa edytowanego użytkownika bez prefiksu użytkownika głównego
pass	Hasło do panelu klienta SMSAPI dodawanego użytkownika
pass_api	Hasło do interfejsu API dla użytkownika, brak tego parametru spowoduje ustawienie jako hasła do API kopii hasła do panelu klient
limit	Limit punktów przydzielony użytkownikowi
month_limit	Ilość punktów która będzie przypisana do konta użytkownika każdego pierwszego dnia
senders	Udostępnienie pól nadawców konta głównego (dostępne wartości: 1 – udostępniaj, 0 – nie udostępniaj, domyślnie wartość równa 0)
phonebook	Udostępnienie grup książki telefonicznej konta głównego (dostępne wartości: 1 – udostępniaj, 0 – nie udostępniaj, domyślnie wartość równa 0). Po udostępnieniu książki użytkownik będzie mógł wysyłać do grup wiadomości nie będzie jednak widział poszczególnych kontaktów w książce telefonicznej.
active	Aktywowanie konta użytkownika (dostępne wartości: 1 – aktywne, 0 – nieaktywne, domyślnie wartość równa 0)
info	Dodatkowy opis użytkownika
format	Dla &format=json powoduje, że zwrotka z API wysyłana jest w formacie JSON, w zwrotce oprócz potwierdzenia , zawierająca następujące parametry: limit, limit_month, senders, phonebook, active, info.
without_prefix	Ustawienie tego parametru pozwala na dodanie użytkownika bez prefixu użytkownika głównego (poduzytkownik zamiast uzytkownik_poduzutkownik)

Dane użytkownika

curl -H "Authorization: Bearer access_token" \
"https://api.smsapi.pl/user.do?\
get_user=sub_user\
format=json"

Przykład odpowiedzi:


OK:<LIMIT>:<MONTH_LIMIT>:<SENDERS>:<PHONEBOOK>:<ACTIVE>:<INFO>
ERROR:<ERR>

Przykład odpowiedzi kiedy &format = json:


{
    "username":"user_subuser", 
    "limit":"10.000", 
    "month_limit":"0.000", 
    "senders":0, 
    "phonebook":0,
    "active":"1", 
    "info":"unknown"
}

W przypadku wystąpienia błędu:


{
    "error": 123,
    "message": "error message"
}

W celu pobrania informacji dotyczących istniejącego konta użytkownika należy w odwołaniu umieścić parametr &get_user=1.

Zarządzanie kontem odbywa się przez wysłanie metodą GET lub POST danych do adresu połączenia:

Parametr	Opis
access_token	Token przypisany do konta w serwisie SMSAPI
get_user	Nazwa użytkownika bez prefiksu użytkownika głównego
format	Dla &format=json powoduje, że zwrotka z API wysyłana jest w formacie JSON, w zwrotce oprócz potwierdzenia , zawierająca następujące parametry: limit, limit_month, senders, phonebook, active, info.
without_prefix	Ustawienie tego parametru pozwala na dodanie użytkownika bez prefixu użytkownika głównego (poduzytkownik zamiast uzytkownik_poduzutkownik)

Liczba punktów

curl -H "Authorization: Bearer access_token" \
"https://api.smsapi.pl/user.do?\
credits=1\
format=json"

Przykład odpowiedzi:


Points: <POINTS>
ERROR:<ERR>

Przykład odpowiedzi kiedy &format = json:


{
    "points":6225.4875, 
    "proCount":"41503", 
    "
}

W przypadku wystąpienia błędu:


{
    "error": 123,
    "message": "error message"
}

W celu sprawdzenia ilości środków pozostałych na koncie dla istniejącego użytkownika należy w odwołaniu umieścić parametr &credits=1. Dodatkowo umieszczenie w odwołaniu parametru &details=1 powoduje oprócz ilości środków na koncie również zwrócenie ilości wiadomości dostępnych do wysłania.

Zarządzanie kontem odbywa się przez wysłanie metodą GET lub POST danych do adresu połączenia:

Parametr	Opis
access_token	Token przypisany do konta w serwisie SMSAPI
credits	&credits=1
details	&details=1 powoduje dodatkowo zwrócenie ilości SMS, MMS, VMS (PRO, ECO, MMS, VMS_gsm, VMS_land)
format	Dla &format=json powoduje, że zwrotka z API wysyłana jest w formacie JSON, w zwrotce oprócz potwierdzenia , zawierająca następujące parametry: limit, limit_month, senders, phonebook, active, info.
without_prefix	Ustawienie tego parametru pozwala na dodanie użytkownika bez prefixu użytkownika głównego (poduzytkownik zamiast uzytkownik_poduzutkownik)

Lista użytkowników

curl -H "Authorization: Bearer access_token" \
"https://api.smsapi.pl/user.do?\
list=1\
format=json"

Przykład odpowiedzi:


OK: subuser1:subuser2
ERROR:<ERR>

Przykład odpowiedzi kiedy &format = json:

[{
    "username":"subuser1", 
    "limit":"10.0000", 
    "month_limit":"0.0000", /
    "senders":"0", 
    "phonebook":"0", 
    "active":"1", 
    "info":"unknown"
},
    "username":"subuser2", 
    "limit":"0.0000", 
    "month_limit":"0.0000", /
    "senders":"0", 
    "phonebook":"0", 
    "active":"0", 
    "info":"unknown"
}]

W przypadku wystąpienia błedu:


{
    "error": 123,
    "message": "error message"
}

W celu pobrania listy użytkowników należy w odwołaniu umieścić parametr &list=1. Dodatkowo po dodaniu parametru &format=json w odpowiedzi zwracana jest tablica obiektów w formacie JSON zawierająca dane o kontach użytkowników jak dla parametru &get_user=1.

Zarządzanie kontem odbywa się przez wysłanie metodą GET lub POST danych do adresu połączenia:

Parametr	Opis
access_token	Token przypisany do konta w serwisie SMSAPI
list	&list=1 zwraca listę użytkowników dla danego konta głównego
format	Dla &format=json powoduje, że zwrotka z API wysyłana jest w formacie JSON, w zwrotce oprócz potwierdzenia , zawierająca następujące parametry: limit, limit_month, senders, phonebook, active, info.

14. Pola nadawcy

Dodawanie pola nadawcy

Funkcja dodawania pól nadawcy wymaga dodatkowej aktywacji. Aby aktywować funkcję prosimy o kontakt z Biurem Obsługi Klienta.

Status pola nadawcy

curl -H "Authorization: Bearer access_token" \
"https://api.smsapi.pl/sender.do?\
status=sender\
format=json"

Przykład odpowiedzi:


OK:<STATUS>
ERROR:<ERR>

Przykład odpowiedzi kiedy &format = json :

{
    "name":"SMSAPI",  
    "status":"ACTIVE"  
    "default":true     
}

W przypadku wystąpienia błedu:


{
    "error": 123,
    "message": "error message"
}

Zarządzanie polami nadawcy odbywa się przez wysłanie metodą GET lub POST danych do adresu połączenia:

Parametr	Opis
access_token	Token przypisany do konta w serwisie SMSAPI
status	Nazwa pola nadawcy, którego status ma być sprawdzony
format	&format=json powoduje zwrócenie wyniku obiektu w formacie JSON zawierającego następujące parametry: nazwa_nadawcy, status oraz informację czy nazwa jest nazwą domyślną.

Listy pól nadawcy

curl -H "Authorization: Bearer access_token" \
"https://api.smsapi.pl/sender.do?\
list=1\
format=json"

Przykład odpowiedzi:


OK:<SENDER_1>,<STATUS_1>:<SENDER_2>:<STATUS_2>...,...:...,...:...,...
ERROR:<ERR>

Przykład odpowiedzi kiedy &format = json:

[{
    "sender":"SMSAPI", 
    "status":"ACTIVE", 
    "default":true
},
{
    "sender":"SMSAPI.pl", /
    "status":"INACTIVE", 
    "default":false
 },
 {
    "sender":"SMS", 
    "status":"ACTIVE", 
    "default":false
}]

W przypadku wystąpienia błedu:


{
    "error": 123,
    "message": "error message"
}

W celu sprawdzenia listy dostępnych pól nadawcy, wraz z ich statusami, należy w odwołaniu umieścić parametr &list=1

Zarządzanie polami nadawcy odbywa się przez wysłanie metodą GET lub POST danych do adresu połączenia:

Parametr	Opis
access_token	Token przypisany do konta w serwisie SMSAPI
format	&format=json powoduje zwrócenie w wyniku tablicy obiektów w formacie JSON zawierającego następujące parametry: nazwa_nadawcy, status oraz informację czy dana nazwa jest nazwą domyślną
with_nat_names	Ustawienie tego parametru (&with_nat_names=1) powoduje wyświetlenie na liście również nazw udostępnionych przez użytkownika głównego (dla użytkowników)

Domyślne pole nadawcy

curl -H "Authorization: Bearer access_token" \
"https://api.smsapi.pl/sender.do?\
default=default_name\
format=json"

Przykład odpowiedzi:


OK
ERROR:<ERR>

Przykład odpowiedzi kiedy &format = json:

{
    "count": 1
}

W przypadku wystąpienia błędu:


{
    "error": 123,
    "message": "error message"
}

Domyślne pole nadawcy jest to nazwa, z która zostanie wysłana wiadomość w przypadku przesłania parametru &from lub gdy parametr ten jest pusty. Pole nadawcy ustawiane jako domyślne musi być aktywne. W przypadku braku domyślnego pola nadawcy wiadomości takie wysyłane są z nazwą SMSAPI.

W celu ustawienia nazwy jako domyślne pole nadawcy należy umieścić parametr &default=nazwa, gdzie nazwa jest nazwą pola nadawcy, które ma być domyślnym.

Zarządzanie polami nadawcy odbywa się przez wysłanie metodą GET lub POST danych do adresu połączenia:

Parametr	Opis
access_token	Token przypisany do konta w serwisie SMSAPI
default	Nazwa, która ma być ustawiona jako domyślna
format	Dla &format=json powoduje, że zwrotka z API wysyłana jest w formacie JSON

15. SMS Authenticator

SMS Authenticator jest implementacją jendek składnika, który może być częścią uwierzytelniania wieloskładnikowego (multi-factor authentication, MFA). Pozwala na uproszczenie operacji autoryzacji użytkownika/klienta. Realizowana jest w dwóch etapach. Pierwszy polega na wysłaniu automatycznie wygenerowanego kodu autoryzacyjnego w wiadomości SMS. W drugim etapie następuje weryfikacja czy kod podany przez odbiorce jest prawidłowy.

Wysyłka kodu


<?php
$url = 'https://api.smsapi.pl/mfa/codes';
$ch = curl_init($url);
$params = array(
    'phone_number' => '48500500500'     //numer telefonu do wysyłki kodu
);
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_POSTFIELDS, $params);
curl_setopt($ch, CURLOPT_HTTPHEADER, array('Authorization: Bearer access_token'));
$result = curl_exec($ch);
?>


curl -H "Authorization Bearer access_token"\
"Content-Type: application/json" -X POST -d\ 
'{"phone_number":"48500500500"}'\
https://api.smsapi.pl/mfa/codes

Przykład odpowiedzi :


{"id":"5ADEF4DC3738305BEED02B0C","code":"123456","phone_number":"48500500500"}

https://api.smsapi.pl/mfa/codes - dla połączeń szyfrowanych SSL

Wysyłka kodu autoryzacyjnego polega na wygenerowaniu requestu POST do API z numerem telefonu odbiorcy.

Parametr	Opis
access_token	OAuth token wygenerowany w Panelu SMSAPI
phone_number	Numer telefonu odbiocy SMS autoryzacyjnego

W odpowiedzi zwracany jest json z następującymi parametrami:

Parametr	Opis
id	ID zdarzenia
code	Kod autoryzacyjny wysłany do odbiorcy
phone_number	Numer telefonu odbiocy SMS autoryzacyjnego

Sprawdzenie poprawności kodu


<?php
$url = 'https://api.smsapi.pl/mfa/codes/verifications';
$ch = curl_init($url);
$params = array(
    'phone_number' => '48500500500',    // numer telefonu podającego kod
    'code'         => '123456'          // kod do sprawdzenia 
);
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_HEADER, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, $params);
curl_setopt($ch, CURLOPT_HTTPHEADER, array('Authorization: Bearer access_token'));
$result = curl_exec($ch);
?>


curl -H "Authorization Bearer access_token"\
"Content-Type: application/json" -X POST -i -d\
'{"phone_number":"48500500500","code":"123456"}'\
https://api.smsapi.pl/mfa/codes/verifications

Przykład odpowiedzi :


HTTP/1.1 204

https://api.smsapi.pl/mfa/codes/verifications - dla połączeń szyfrowanych SSL

Sprawdzenie poprawności kodu autoryzacyjnego jest realizowane przez podanie dwóch parametrów w requescie POST do API, numeru telefonu odbiorcy oraz kodu autoryzacyjnego wprowadzonego przez użytkownika.

Parametr	Opis
access_token	OAuth token wygenerowany w Panelu SMSAPI
code	Kod autoryzacyjny wprowadzony przez odbiorcę SMS autoryzacyjnego
phone_number	Numer telefonu odbiocy SMS autoryzacyjnego

W odpowiedzi zwracany jest HTTP CODE obsługujący 3 zdarzenia:

Status	Opis
204	Poprawny kod
404	Błędny kod
408	Przedawniony kod

16. Interfejs SMPP

Protokół SMPP

SMPP (Short Message Peer-to-Peer) jest otwartym, ustandaryzowanym protokołem zaprojektowanym do bezpośredniej komunikacji pomiędzy systemami teleinformatycznymi, takimi jak operatorskie Centrum SMS (SMSC) oraz Systemy przesyłania wiadomości SMS (SME/ESME) w celu przesyłu krótkich wiadomości tekstowych SMS. Protokół SMPP wykorzystywany jest w SMSAPI głównie do komunikacji z polskimi sieciami komórkowymi oraz agregatorami SMS dla wysyłek zagranicznych (połączenia ESME <-> SMSC). Dla serwisów posiadających własny rozbudowany system obsługi klientów szukających dostawcy usługi wysyłki wiadomości SMS platforma SMSAPI w razie potrzeby może udostępnić połączenie do własnego SMSC za pomocą interfejsu SMPP.

Protokół SMPP oparty jest na binarnie zakodowanych parach pakietów zapytań/odpowiedzi (request/response PDUs) przesyłanych za pomocą warstwy transportowej modelu OSI. Dane pomiędzy peer'ami wymieniane mogą być synchronicznie, gdzie po każdym wysłanym pakiecie oczekiwana jest odpowiedź przed wysłaniem kolejnego, oraz asynchroniczne gdzie dozwolone jest wysyłanie większej liczby pakietów bez odpowiedzi potwierdzającej ich odebranie. Dozwolona liczba zapytań bez odpowiedzi, nazywana oknem, powinna być identyczna dla obu stron komunikacji dla zapewnienia najwyższej jakości usługi.

Sposób komunikacji wykorzystywany w protokole SMPP sprawia, że dla poprawnego wysłania wiadomości SMS nie jest konieczne wykorzystywanie telefonów komórkowych, modemów GSM czy kart SIM. Dodatkowo udostępnia on wiele funkcjonalności niedostępnych przy użyciu standardowych urządzeń komunikacji GSM jak np. przesyłanie wiadomości z alfanumerycznym polem nadawcy zamiast standardowego numeru telefonu.

Szczegółowe informacje oraz dostęp do połączenia SMPP można uzyskać w Biurze Obsługi Klienta - kontakt

17. Lista statusów doręczenia

Kod	Status ANG	Status	Opis
401	NOT_FOUND	Nieznaleziona	Błędny numer ID lub raport wygasł
402	EXPIRED	Przedawniona	Wiadomość niedostarczona z powodu zbyt długiego czasu niedostępność numeru
403	SENT	Wysłana	Wiadomość została wysłana ale operator nie zwrócił jeszcze raportu doręczenia
404	DELIVERED	Dostarczona	Wiadomość dotarła do odbiorcy
405	UNDELIVERED	Niedostarczona	Wiadomość niedostarczona (np.: błędny numer, numer niedostępny)
406	FAILED	Nieudana	Błąd podczas wysyłki wiadomości - prosimy zgłosić
407	REJECTED	Odrzucona	Wiadomość niedostarczona (np.: błędny numer, numer niedostępny)
408	UNKNOWN	Nieznany	Brak raportu doręczenia dla wiadomości (wiadomość doręczona lub brak możliwości doręczenia)
409	QUEUE	Kolejka	Wiadomość czeka w kolejce na wysyłkę
410	ACCEPTED	Zaakceptowana	Wiadomość przyjęta przez operatora
411	RENEWAL	Ponawianie	Wykonana była próba połączenia która nie została odebrana, połączenie zostanie ponowione.
412	STOP	Zatrzymanie	Zatrzymanie

18. Kody błędów

ERROR	Opis
8	Błąd w odwołaniu (Prosimy zgłosić)
11	Zbyt długa lub brak wiadomości lub ustawiono parametr nounicode i pojawiły się znaki specjalne w wiadomości. Dla wysyłki VMS błąd oznacz brak pliku WAV lub błąd tekstu TTS (brak tekstu lub inne niż UTF-8 kodowanie).
12	Wiadomość składa się z większej ilości części niż określono w parametrze &max_parts
13	Brak prawidłowych numerów telefonów (numer błędny, stacjonarny (w przypadku wysyłki SMS) lub znajdujący się na czarnej liście)
14	Nieprawidłowe pole nadawcy
17	Nie można wysłać FLASH ze znakami specjalnymi
18	Nieprawidłowa liczba parametrów
19	Za dużo wiadomości w jednym odwołaniu
20	Nieprawidłowa liczba parametrów IDX
21	Wiadomość MMS ma za duży rozmiar (maksymalnie 300kB)
22	Błędny format SMIL
23	Błąd pobierania pliku dla wiadomości MMS lub VMS
24	Błędny format pobieranego pliku
25	Parametry &normalize oraz &datacoding nie mogą być używane jednocześnie.
26	Za długi temat wiadomości. Temat może zawierać maksymalnie 30 znaków.
27	Parametr IDX za długi. Maksymalnie 255 znaków
28	Błędna wartość parametru time_restriction. Dostępne wartości to FOLLOW, IGNORE lub NEAREST_AVAILABLE.
30	Brak parametru UDH jak podany jest datacoding=bin
31	Błąd konwersji TTS
32	Nie można wysyłać wiadomości Eco, MMS i VMS na zagraniczne numery lub wysyłka na zagranicę wyłączona na koncie.
33	Brak poprawnych numerów
35	Błędna wartość parametru tts_lector. Dostępne wartości: agnieszka, ewa, jacek, jan, maja
36	Nie można wysyłać wiadomości binarnych z ustawioną stopką.
40	Brak grupy o podanej nazwie
41	Wybrana grupa jest pusta (brak kontaktów w grupie)
50	Nie można zaplanować wysyłki na więcej niż 3 miesiące w przyszłość
51	Ustawiono błędną godzinę wysyłki, wiadomość VMS mogą być wysyłane tylko pomiędzy godzinami 8 a 22 lub ustawiono kombinację parametrów try i interval powodującą możliwość próby połączenia po godzinie 22.
52	Za dużo prób wysyłki wiadomości do jednego numeru (maksymalnie 10 prób w przeciągu 60sek do jednego numeru)
53	Nieunikalny parametr idx. Wiadomość o podanym idx została wysłana w ostatnich czterech dniach lub jest zaplanowana do wysyłki w przyszłości przy wykorzystaniu parametru &check_idx=1.
54	Błędny format daty. Ustawiono sprawdzanie poprawności daty &date_validate=1
55	Brak numerów stacjonarnych w wysyłce i ustawiony parametr skip_gsm
56	Różnica pomiędzy datą wysyłki, a datą wygaśnięcia nie może być mniejsza niż 15 minut i większa niż 72 godzin
57	Numer znajduje się na czarnej liście dla danego użytkownika.
60	Grupa kodów o podanej nazwie nie istnieje.
61	Data ważności grupy kodów minęła.
62	Brak wolnych kodów w podanej grupie (wszystkie kody zostały już wykorzystane).
65	Brak wystarczającej liczby kodów rabatowych dla wysyłki. Liczba niewykorzystanych kodów w grupie musi być co najmniej równa liczbie numerów w wysyłce.
66	W treści wiadomości brak jest znacznika [%kod%] dla wysyłki z parametrem &discount_group (znacznik taki jest wymagany).
70	Błędny adres CALLBACK w parametrze notify_url.
74	Data wysyłki nie spełnia ograniczeń czasowych ustawionych na koncie
101	Niepoprawne lub brak danych autoryzacji
102	Nieprawidłowy login lub hasło
103	Brak punków dla tego użytkownika
104	Brak szablonu
105	Błędny adres IP (włączony filtr IP dla interfejsu API)
110	Usługa (SMS, MMS, VMS lub HLR) nie jest dostępna na danym koncie.
200	Nieudana próba wysłania wiadomości, prosimy ponowić odwołanie
201	Wewnętrzny błąd systemu (prosimy zgłosić)
202	Zbyt duża ilość jednoczesnych odwołań do serwisu, wiadomość nie została wysłana (prosimy odwołać się ponownie)
203	Zbyt wiele odwołań do serwisu. Spróbuj ponownie później.
300	Nieprawidłowa wartość pola points (przy użyciu pola points jest wymagana wartość 1)
301	Wiadomość o podanym ID nie istnieje lub jest zaplanowana do wysłania w przeciągu najbliższych 60 sekund (nie można usunąć takiej wiadomości).
400	Nieprawidłowy ID statusu wiadomości.
999	Wewnętrzny błąd systemu (prosimy zgłosić)
1000	Akcja dostępna tylko dla użytkownika głównego
1001	Nieprawidłowa akcja (oczekiwane jedna z add_user, set_user, get_user, credits)
1010	Błąd dodawania użytkownika
1020	Błąd edycji konta użytkownika
1021	Brak danych do edycji, przynajmniej jeden parametr musi być edytowany
1030	Błąd pobierania danych użytkownika
1032	Nie istnieje użytkownik o podanej nazwie dla danego użytkownika głównego
1100	Błąd danych użytkownika
1110	Błędna nazwa tworzonego użytkownika
1111	Nie podano nazwy tworzonego konta użytkownika
1112	Nazwa konta użytkownika za krótka (minimum 3 znaki)
1113	Nazwa konta użytkownika za długa, łączna długość nazwy użytkownika wraz z prefiksem użytkownika głównego może mieć maksymalnie 32 znaki
1114	W nazwie użytkownika pojawiły się nidozwolone znaki, dozwolone są litery [A – Z], cyfry [0 – 9] oraz znaki @, -, _ i
1115	Istnieje już użytkownik o podanej nazwie
1120	Błąd hasła dla tworzonego konta użytkownika
1121	Hasło dla tworzonego konta użytkownika za krótkie
1122	Hasło dla tworzonego konta użytkownika za długie
1123	Hasło powinno być zakodowane w MD5
1130	Błąd limitu punktów przydzielanego użytkownikowi
1131	Parametr limit powinno zawierać wartość numeryczną
1140	Błąd limitu miesięcznego punktów przydzielanego użytkownikowi
1141	Parametr month_limit powinno zawierać wartość numeryczną
1150	Błędna wartość parametru senders, dopuszczalne wartości dla tego parametru to 0 lub 1
1160	Błędna wartość parametru phonebook, dopuszczalne wartości dla tego parametru to 0 lub 1
1170	Błędna wartość parametru active, dopuszczalne wartości dla tego parametru to 0 lub 1
1180	Błąd parametru info
1183	Zawartość parametru info jest za długa
1190	Błąd hasła do interfejsu API dla konta użytkownika
1192	Błędna długość hasła do interfejsu API dla konta użytkownika (hasło zakodowane w md5 powinno mieć 32 znaki)
1193	Hasło do interfejsu powinno zostać podane w formie zakodowanej w md5
2001	Nieprawidłowa akcja (oczekiwane jedna z add, status, delete, list)
2010	Błąd dodawania pola nadawcy
2030	Błąd sprawdzania statusu pola nadawcy
2031	Nie istnieje pole nadawcy o podanej nazwie
2060	Błąd dodawania domyślnego pola nadawcy
2061	Pole nadawcy musi być aktywne, żeby ustawić je jako domyślne
2062	Pole nadawcy już jest ustawione jako domyślne
2100	Błąd przesyłanych danych
2110	Błąd nazwy pola nadawcy
2111	Brak nazwy dodawanego pola nadawcy (parametr &add jest pusty)
2112	Niepoprawna nazwa pola nadawcy (np. numer telefonu, zawierająca polskie i/lub specjalne znaki lub za długie), pole nadawcy może mieć maksymalnie 11 znaków, dopuszczalne znaki: a-z A-Z 0-9 - . [spacja]
2115	Pole o podanej nazwie już istnieje

Tabela błędów systemu HLR:

Błąd	Opis
UNKNOWN_SUBSCRIBER	Błędny, nieaktywny numer. Błąd mający charakter stały.
ABSENT_SUBSCRIBER	Numer wyłączony lub poza zasięgiem przez dłuższy czas. Numer uznany jest jako nieaktywny (podobnie jak w przypadku UNKNOWN) jednak ma charakter tymczasowy, jeżeli numer pojawi się w zasięgu stanie się na nowo aktywny.
TELESERVICE_NOT_PROVISIONED	Numer ma zablokowaną opcję odbierania wiadomości SMS. Błąd ma charakter stały.
SYSTEM_FAILURE	Błąd systemu sieci macierzystej podczas sprawdzania numeru, ma charakter tymczasowy.
HLR_LOCAL_CANCEL / HLR_ABORT	Błąd sytemu HLR dla danego numeru, ma charakter tymczasowy.
CALL_BARRED	Zablokowane połączenia przychodzące dla danego numeru. Błąd ma charakter stały

19. Alfabet 7bit GSM

Tutaj przedstawiony jest podstawowy alfabet '7bit' zgodny ze specyfikacją GSM 03.38.

Wszystkie znaki poza tym spisem, są uznawane za znaki specjalne oraz skracają wiadomość ze 160 znaków na 70. Użycie znaków z tej listy nie skróci wiadomości.

Zauważ, że znaki ^ { } [ ] \ ~ | [enter] € są liczone podwójnie, kiedy wysyłana jest wiadomość bez znaków specjalnych z powodu wymagań specyfikacji GSM.

Znak	Nazwa Znaku	HEX	DEC
@	COMMERCIAL AT	0x00	0
£	POUND SIGN	0x01	1
$	DOLLAR SIGN	0x02	2
¥	YEN SIGN	0x03	3
è	LATIN SMALL LETTER E WITH GRAVE	0x04	4
é	LATIN SMALL LETTER E WITH ACUTE	0x05	5
ù	LATIN SMALL LETTER U WITH GRAVE	0x06	6
ì	LATIN SMALL LETTER I WITH GRAVE	0x07	7
ò	LATIN SMALL LETTER O WITH GRAVE	0x08	8
Ç	LATIN CAPITAL LETTER C WITH CEDILLA	0x09	9
	LINE FEED	0x0A	10
Ø	LATIN CAPITAL LETTER O WITH STROKE	0x0B	11
ø	LATIN SMALL LETTER O WITH STROKE	0x0C	12
	CARRIAGE RETURN	0x0D	13
Å	LATIN CAPITAL LETTER A WITH RING ABOVE	0x0E	14
å	LATIN SMALL LETTER A WITH RING ABOVE	0x0F	15
Δ	GREEK CAPITAL LETTER DELTA	0x10	16
_	LOW LINE	0x11	17
Φ	GREEK CAPITAL LETTER PHI	0x12	18
Γ	GREEK CAPITAL LETTER GAMMA	0x13	19
Λ	GREEK CAPITAL LETTER LAMBDA	0x14	20
Ω	GREEK CAPITAL LETTER OMEGA	0x15	21
Π	GREEK CAPITAL LETTER PI	0x16	22
Ψ	GREEK CAPITAL LETTER PSI	0x17	23
Σ	GREEK CAPITAL LETTER SIGMA	0x18	24
Θ	GREEK CAPITAL LETTER THETA	0x19	25
Ξ	GREEK CAPITAL LETTER XI	0x1A	26
	ESCAPE TO EXTENSION TABLE	0x1B	27
	FORM FEED	0x1B0A	27 10
^	CIRCUMFLEX ACCENT	0x1B14	27 20
{	LEFT CURLY BRACKET	0x1B28	27 40
}	RIGHT CURLY BRACKET	0x1B29	27 41
'\'	REVERSE SOLIDUS (BACKSLASH)	0x1B2F	27 47
[	LEFT SQUARE BRACKET	0x1B3C	27 60
~	TILDE	0x1B3D	27 61
]	RIGHT SQUARE BRACKET	0x1B3E	27 62
	VERTICAL BAR	0x1B40	27 64
€	EURO SIGN	0x1B65	27 101
Æ	LATIN CAPITAL LETTER AE	0x1C	28
æ	LATIN SMALL LETTER AE	0x1D	29
ß	LATIN SMALL LETTER SHARP S (German)	0x1E	30
É	LATIN CAPITAL LETTER E WITH ACUTE	0x1F	31
	SPACE	0x20	32
!	EXCLAMATION MARK	0x21	33
\"	QUOTATION MARK	0x22	34
#	NUMBER SIGN	0x23	35
¤	CURRENCY SIGN	0x24	36
%	PERCENT SIGN	0x25	37
&	AMPERSAND	0x26	38
'	APOSTROPHE	0x27	39
(	LEFT PARENTHESIS	0x28	40
)	RIGHT PARENTHESIS	0x29	41
*	ASTERISK	0x2A	42
+	PLUS SIGN	0x2B	43
,	COMMA	0x2C	44
-	HYPHEN-MINUS	0x2D	45
.	FULL STOP	0x2E	46
/	SOLIDUS (SLASH)	0x2F	47
0	DIGIT ZERO	0x30	48
1	DIGIT ONE	0x31	49
2	DIGIT TWO	0x32	50
3	DIGIT THREE	0x33	51
4	DIGIT FOUR	0x34	52
5	DIGIT FIVE	0x35	53
6	DIGIT SIX	0x36	54
7	DIGIT SEVEN	0x37	55
8	DIGIT EIGHT	0x38	56
9	DIGIT NINE	0x39	57
:	COLON	0x3A	58
;	SEMICOLON	0x3B	59
<	LESS-THAN SIGN	0x3C	60
=	EQUALS SIGN	0x3D	61
>	GREATER-THAN SIGN	0x3E	62
?	QUESTION MARK	0x3F	63
¡	INVERTED EXCLAMATION MARK	0x40	64
A	LATIN CAPITAL LETTER A	0x41	65
B	LATIN CAPITAL LETTER B	0x42	66
C	LATIN CAPITAL LETTER C	0x43	67
D	LATIN CAPITAL LETTER D	0x44	68
E	LATIN CAPITAL LETTER E	0x45	69
F	LATIN CAPITAL LETTER F	0x46	70
G	LATIN CAPITAL LETTER G	0x47	71
H	LATIN CAPITAL LETTER H	0x48	72
I	LATIN CAPITAL LETTER I	0x49	73
J	LATIN CAPITAL LETTER J	0x4A	74
K	LATIN CAPITAL LETTER K	0x4B	75
L	LATIN CAPITAL LETTER L	0x4C	76
M	LATIN CAPITAL LETTER M	0x4D	77
N	LATIN CAPITAL LETTER N	0x4E	78
O	LATIN CAPITAL LETTER O	0x4F	79
P	LATIN CAPITAL LETTER P	0x50	80
Q	LATIN CAPITAL LETTER Q	0x51	81
R	LATIN CAPITAL LETTER R	0x52	82
S	LATIN CAPITAL LETTER S	0x53	83
T	LATIN CAPITAL LETTER T	0x54	84
U	LATIN CAPITAL LETTER U	0x55	85
V	LATIN CAPITAL LETTER V	0x56	86
W	LATIN CAPITAL LETTER W	0x57	87
X	LATIN CAPITAL LETTER X	0x58	88
Y	LATIN CAPITAL LETTER Y	0x59	89
Z	LATIN CAPITAL LETTER Z	0x5A	90
Ä	LATIN CAPITAL LETTER A WITH DIAERESIS	0x5B	91
Ö	LATIN CAPITAL LETTER O WITH DIAERESIS	0x5C	92
Ñ	LATIN CAPITAL LETTER N WITH TILDE	0x5D	93
Ü	LATIN CAPITAL LETTER U WITH DIAERESIS	0x5E	94
§	SECTION SIGN	0x5F	95
¿	INVERTED QUESTION MARK	0x60	96
a	LATIN SMALL LETTER A	0x61	97
b	LATIN SMALL LETTER B	0x62	98
c	LATIN SMALL LETTER C	0x63	99
d	LATIN SMALL LETTER D	0x64	100
e	LATIN SMALL LETTER E	0x65	101
f	LATIN SMALL LETTER F	0x66	102
g	LATIN SMALL LETTER G	0x67	103
h	LATIN SMALL LETTER H	0x68	104
i	LATIN SMALL LETTER I	0x69	105
j	LATIN SMALL LETTER J	0x6A	106
k	LATIN SMALL LETTER K	0x6B	107
l	LATIN SMALL LETTER L	0x6C	108
m	LATIN SMALL LETTER M	0x6D	109
n	LATIN SMALL LETTER N	0x6E	110
o	LATIN SMALL LETTER O	0x6F	111
p	LATIN SMALL LETTER P	0x70	112
q	LATIN SMALL LETTER Q	0x71	113
r	LATIN SMALL LETTER R	0x72	114
s	LATIN SMALL LETTER S	0x73	115
t	LATIN SMALL LETTER T	0x74	116
u	LATIN SMALL LETTER U	0x75	117
v	LATIN SMALL LETTER V	0x76	118
w	LATIN SMALL LETTER W	0x77	119
x	LATIN SMALL LETTER X	0x78	120
y	LATIN SMALL LETTER Y	0x79	121
z	LATIN SMALL LETTER Z	0x7A	122
ä	LATIN SMALL LETTER A WITH DIAERESIS	0x7B	123
ö	LATIN SMALL LETTER O WITH DIAERESIS	0x7C	124
ñ	LATIN SMALL LETTER N WITH TILDE	0x7D	125
ü	LATIN SMALL LETTER U WITH DIAERESIS	0x7E	126
à	LATIN SMALL LETTER A WITH GRAVE	0x7F	127

20. Kodowanie

Domyślnie kodowanie znaków ustawione jest na windows-1250. Jednak do wysyłania wiadomości można użyć jednego z poniżej przedstawionych rodzajów kodowania. W tym celu wykorzystać należy parametr &encoding.

iso-8859-1
iso-8859-2
iso-8859-3
iso-8859-4
iso-8859-5
iso-8859-7
windows-1250
windows-1251
utf-8

21. Integracje

Branża e-commerce coraz częściej i chętniej korzysta z potencjału mobilnej komunikacji, tym bardziej, że przekłada się ona zarówno na wprowadzenie oszczędności, jak i wsparcie sprzedaży.

Z SMSAPI zintegrowanych jest już kilkadziesiąt platform tworzących oprogramowania e-sklepów, CRM oraz wielu innych. Ich pełną listę znajdziesz tutaj.

Gmail

Skrypt monitoruje wiadomości na podstawie etykiet. Aby ustawić automatyczne przypisywanie etykiety od zdefiniowanego odbiorcy, należy zalogować się na pocztę Gmail, następnie kliknąć w ikonę koła zębatego znajdującą się w prawym górnym rogu strony i przejść do ustawień

alternate text

W ustawieniach należy przejść do zakładki „Filtry”, a następnie wybrać opcję „utwórz nowy filtr”

alternate text

W następnym kroku należy określić parametry, dla których danej wiadomości zostanie przypisana odpowiednia etykieta. W tym przypadku powiadomienia będą wysyłane na odebrane wiadomości z adresu bok@smsapi.pl Oznacza to, że wszystkie wiadomości od zdefiniowanego odbiorcy będą automatycznie zapisywane z wybraną etykietą.

alternate text

Aby przejść dalej, należy kliknąć w link „Utwórz filtr na podstawie tych kryteriów wyszukiwania”

Należy zaznaczyć opcję „zastosuj etykietę”, a następnie stworzyć nową, lub wybrać wcześniej utworzoną

alternate text

Aby dokonać konfiguracji usługi SMSAPI w Google Mail należy upewnić się czy jesteśmy zalogowani na odpowiednim koncie w usłudze Google a następnie przejść pod adres https://script.google.com

alternate text

W nowo otwartym oknie usuwamy przykład rozpoczętego skryptu oraz wklejamy skrypt dostępny pod adresem http://www.smsapi.pl/integracje/poczta-google

W celu ustawienia częstotliwości wykonywania skryptu należy wybrać alternate text (wyzwalacze bieżącego projektu) a następnie dodać nowy wyzwalacz i wybrać częstotliwość wyzwalania

alternate text

Do poprawnego uruchomienia skryptu wymagane jest nadanie mu uprawnień. Skrypt pobiera informacje o adresach e-mail nadawców wiadomości oraz ich tematach dla zdefiniowanej w ustawieniach poczty Gmail etykiety. Następnie wykonywane są odpowiednio przygotowane odwołania do naszego API które skutkują wysłaniem powiadomienia SMS

alternate text

Google Calendar

function SmsApiCalendar()
{
  /* Configuration */

  var SMSAPI_TOKEN   = 'token';

  var SMSAPI_RECEIVER   = '48XXXXXXXXX'; // Numer odbiorcy
  var SMSAPI_SENDERNAME = 'Info'; // Pole nadawcy

  var SMSAPI_URL     = 'https://api.smsapi.pl/sms.do?';

  var HOURS = 0;
  var MINUTES  = 30;
  var MESSAGE = 'GOOGLE Calendar: Coming events: :TITLE that begin :TIME';
  /****************/

  SMSAPI_URL += 'access_token='+SMSAPI_TOKEN;
  SMSAPI_URL += '&from='+SMSAPI_SENDERNAME;
  SMSAPI_URL += '&to='+encodeURIComponent(SMSAPI_RECEIVER);

  var period = (HOURS * 3600000) + (MINUTES * 60000);
  var now = new Date();
  var periodFromNow = new Date(now.getTime() + period);

  var calendar = CalendarApp.getDefaultCalendar();
  var events = calendar.getEvents(now, periodFromNow);

  for (var i in events) {
    var event = events[i];

    var has_smsapi_status = false;
    var tag_keys = event.getAllTagKeys();
    for (var k = 0; k < tag_keys.length; ++k) {
      if (tag_keys[k] === 'smsapi_status') {
        has_smsapi_status = true;
        break;
      }
    }

    if (has_smsapi_status) {
      if (event.getTag('smsapi_status') === 'ok') {
        continue;
      }
    }
    var idx = event.getId();
    var message = MESSAGE.replace(':TITLE', event.getTitle()).replace(':TIME', event.getStartTime());
    var url = SMSAPI_URL+"&encoding=utf8&message="+encodeURIComponent(message)+"&check_idx=1&idx="+encodeURIComponent(idx);
    UrlFetchApp.fetch(url);
    event.setTag('smsapi_status', 'ok');
  }
}


    * 'SMSAPI_TOKEN', Token smsAPI
    * 'SMSAPI_RECIVER', Numer odbiorczy
    * 'SMSAPI_SENDERNAME', Pole nadawcy
    * 'HOURS', Ustawienie ile godzin przed wydarzeniem ma zostać wysłana wiadomość
    * 'MINUTES', Ustawienie ile minut przed wydarzeniem ma zostać wysłana wiadomość
    * 'MESSAGE', Treść wiadomości SMS, ':TITLE' tytuł wydarzenia ':TIME' czas wydarzenia.

Integracja pozwala na konfigurację automatycznych powiadomień SMS o nadchodzących wydarzeniach w Kalendarzu Google. W celu rozpoczęcia współpracy należy utworzyć konto w serwisie SMSAPI. Utworzone konto jest gotowe do użytku, jednak zalecamy ustawienie własnego pola nadawcy. Jako domyślne ustawione jest pole nadawcy „Info”. Dodanie pola nadawcy jest usługą całkowicie darmową.

Aby dokonać konfiguracji usługi SMSAPI w Kalendarzu Google należy upewnić się czy jesteśmy zalogowani na odpowiednim koncie w usłudze Google. Następnie przejść na stronę Google Script

alternate text

Zmień nazwę z 'Code.gs' na 'SmsApiCalendar.gs'.

W nowo otwartym oknie usuwamy przykład rozpoczętego skryptu oraz wklejamy skrypt dostępny po prawej ->

Aby ustawić częstotliwość wykonywania skryptu należy wybrać „Current project's triggers” alternate text , następnie „No triggers set up. Click here to add one now” oraz zmienić ustawienia na „Minutes timer” i „Every minute”.

alternate text

Do poprawnego uruchomienia skryptu wymagane jest nadanie mu uprawnień. Skrypt pobiera informacje o datach oraz nazwach wydarzeń w Kalendarzu Google. Następnie wykonywane są odpowiednio przygotowane odwołania do naszego API które skutkują wysłaniem powiadomienia SMS.

Opencart

Aby dokonać konfiguracji usługi SMSAPI w Opencart w pierwszej kolejności należy pobrać pliki modułu pod adresem SMSAPI-Opencart oraz skopiować je do katalogu, w którym zainstalowany jest Opencart. Po udanym skopiowaniu plików na serwer w panelu administratora Opencart w zakładce Moduły pojawi się możliwość instalacji modułu SMSAPI – Powiadomienia SMS

alternate text

Po wprowadzenia danych autoryzacyjnych, loginu w SMSAPI i hasła do API zakodowanego w MD5 oraz zatwierdzeniu operacji uzyskujemy dostęp do konfiguracji modułu.

W zakładce „Ustawienia” można wybrać aktywne na koncie w SMSAPI pole nadawcy dla powiadomień SMS, sprecyzować dodatkowe parametry dla wysyłki powiadomień SMS, ustawić możliwość odbierania powiadomień SMS o zarejestrowaniu nowego zamówienia w sklepie, ustawić oraz spersonalizować powiadomienia SMS dla konkretnych statusów zamówień.

alternate text

W zakładce Wyślij SMS można skorzystać z „Szybkiej bramki” aby wysłać dowolne powiadomienie SMS do odbiorcy zapisanego w bazie sklepu Opencart lub wprowadzonego ręcznie. W zakładce Historia dostępna jest historia wysłanych powiadomień SMS o zmianie statusów zamówień. W zakładce Stan konta dostępna jest informacja o aktualnym stanie konta w SMSAPI.

alternate text

Moduł SMSAPI wyposażony jest również w tłumaczenie dla polskiej wersji językowej. Przyjęte zostało założenie że polska wersja językowa Opencart zostanie umieszczona w katalogu admin/language/polish .

Shoper

W zakładce „Aplikacje” odnajdujemy „SMSAPI – powiadomienia SMS” oraz wybieramy „Zainstaluj”. Kolejny etap to akceptacja regulaminu sklepu Shoper oraz wybranie akcji „Instaluj”. Po udanej instalacji konfiguracja modułu SMSAPI dostępna jest w zakładce Konfiguracja – Moje aplikacje – SMSAPI

alternate text

Podajemy login w SMSAPI („Login”), hasło do API w MD5 („Hasło API”) oraz zatwierdzamy wybierając „Zapisz”. Hasło można wygenerować w panelu klienta pod linkiem SMSAPI

„Pokaż hasło do API w MD5”.

alternate text

Na liście „Pole nadawcy” można dokonać wyboru pola nadawcy wiadomości SMS spośród dostępnych oraz aktywnych w serwisie SMSAPI. Pole nadawcy „ECO”odpowiada usłudze Eco. Pozostałe pola nadawcy dotyczą usługi Pro. W zakładce „Szablony” można dokonać personalizacji wiadomości dla wybranych statusów zamówień w sklepie Shoper. Aby wiadomość SMS została wysłana dla wybranego statusu zamówienia w polu „Wyślij” należy wybrać „Tak” a następnie „Zapisz”. Lista dostępnych zmiennych które można wykorzystać w treści wiadomości SMS dostępna jest na końcu strony konfiguracyjnej modułu.

IAI Shop

Integracja SMSAPI z IAI-SHOP pozwala na wysyłkę powiadomień SMS podczas zmiany statusu zamówienia w sklepie IAI-SHOP oraz powiadomienie właściciela sklepu o nowym zamówieniu. W ramach jednego użytkownika IAI-SHOP można skonfigurować usługę powiadomień SMS dla kilku sklepów.

Konfiguracja integracji dostępna jest pod adresem iaishop.smsapi.pl Aby uruchomić usługę należy wypełnić formularz pod adresem iaishop.smsapi.pl Rejestracja

alternate text

Podajemy nazwę użytkownika w SMSAPI („SMSAPI UŻYTKOWNIK”), hasło do API („SMSAPI hasło do API w MD5”).Hasło można wygenerować w panelu klienta pod linkiem SMSAPI

Podajemy nazwę sklepu IAI-SHOP („IAI-SHOP nazwa sklepu”), nazwę użytkownika IAI-Shop („IAI-SHOP użytkownik”) oraz hasło użytkownika IAI-Shop („IAI-SHOP hasło”).

Wprowadzone ustawienia należy potwierdzić naciskając „Utwórz konto”.

Pod adresem iaishop.smsapi.pl Logowanie dostępne jest logowanie do nowo utworzonej integracji z IAI-SHOP

alternate text

W integracji dostępne są 3 zakładki :

„Zarządzaj sklepem”, pozwala na konfigurację treści wysyłanym wiadomości SMS podczas zmiany statusu w sklepie IAI-SHOP oraz konfigurację powiadomień o nowym zamówieniu dla właściciela sklepu.

„Ustawienia SMSAPI”, pozwala na zmianę konta w SMSAPI z którym powiązana jest integracja.

„Stan konta”, pozwala na sprawdzenie ilości dostępnych punktów na platformie SMSAPI.

alternate text

Szczegółowa konfiguracja integracji IAI-SHOP

W zakładce „Zarządzaj sklepem” można wybrać sklep IAI-SHOP dla którego chcemy przeprowadzić konfigurację.

Na liście „Nadawca wiadomości” można dokonać wyboru pola nadawcy wiadomości SMS spośród dostępnych oraz aktywnych w serwisie SMSAPI. Pole nadawcy „ECO” odpowiada usłudze Eco. Pozostałe pola nadawcy dotyczą usługi Pro

Opcja „Zastąp znaki specjalne” pozwala na automatyczną zmianę wszystkich znaków specjalnych ( w tym polskich diakrytycznych) w treści wysyłanych powiadomień SMS na odpowiedniki np. ą na a.

Opcja „Wyślij fast” pozwala na nadanie wysyłanym wiadomością najwyższego priorytetu zgodnie z wykorzystywanym kanałem PRO/ECO. Opcja wiąże się z podwyższonymi opłatami – 1,5x stawki standardowej wiadomości danego typu.

Opcja „Numer właściciela sklepu” pozwala na konfigurację numeru/ów na które zostaną wysłane powiadomienia SMS o nowym zamówieniu

alternate text

Opcja przedstawiona poniżej pozwala na aktywacje wysyłki oraz konfigurację treści powiadomienia SMS o nowym zamówieniu.

alternate text

Opcja przedstawiona poniżej pozwala na aktywacje wysyłki oraz konfigurację treści powiadomień SMS o zmianie statusu zamówienia w sklepie IAI-SHOP.

alternate text

Tabela dostępnych parametrów w treści powiadomień SMS dla integracji z IAI-SHOP:

Parametr	Opis
{customer}	Imię i nazwisko klienta
{number}	Numer zamówienia
{phone}	Numer telefonu klienta
{status}	Status zamówienia klienta
{total_price}	Całkowita wartość zamówienia

QNAP

Aby skonfigurować serwer QNAP do wysyłania powiadomień, należy przejść do zakładki Ustawienia systemowe → Powiadomienia →Serwer SMSC.

alternate text

W polu Usługodawca SMS należy wybrać opcję Dodaj usługodawcę SMS.

Do pola poniżej należy wpisać swoją nazwę – np. SMSAPI.pl

Do pola Szablon tekstowy URL należy wkleić poniższe wyrażenie:

https://api.smsapi.pl/sms.do?username=@@UserName@@&password=@@Password@@&to=@@PhoneNumber@@&from=SMSAPI&message=@@Text@@

Następnie należy wybrać przycisk Zapisz

W kolejnym kroku należy wybrać z listy wyboru przed chwilą utworzoną konfigurację - SMSAPI.pl

alternate text

W polu Nazwa użytkownika serwera SMS powinien się znaleźć Państwa login z serwisu SMSAPI

Do pola Hasło użytkownika serwera SMS należy wpisać zakodowane hasło w md5.

W zakładce Ustawienia systemowe → Powiadomienia → Powiadomienia o alertach należy zaznaczyć opcję SMS

alternate text

W kolejnym kroku należy wybrać kraj oraz numery telefonów (maksymalnie dwa) na jakie mają być wysyłane powiadomienia o błędach.

alternate text

Pozostałe Integracje

Pozostałe serwisy i usługi, które można zintegrować z SMSAPI znajdziesz tutaj: Integracje.