Dokumentacja SMS API - 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 „Test”. 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 token_api_oauth
Rekomendujemy autoryzację OAuth 2.0. Generowanie 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 SSLhttps://api2.smsapi.pl/- backup dla połączeń szyfrowanych SSL
Biblioteki
Wykorzystanie gotowych bibliotek SMSAPI pozwala 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 |
| Go | Biblioteka Go |
Dokumentacja openAPI
Poza endpointami wspomnianymi w tej dokumentacji, SMSAPI udostępnia też inne zasoby API do realizacji wielu zadań związanych z kontem. Są one udokumentowane w oparciu o standard openAPI tutaj oraz na bieżąco rozwijane i aktualizowane.
2. Pojedynczy SMS
curl -X POST -H "Authorization: Bearer token_api_oauth" \
"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 = "token_api_oauth"; //https://ssl.smsapi.pl/react/oauth/manage
$params = array(
'to' => '500000000', //numery odbiorców rozdzielone przecinkami
'from' => 'Test', //pole nadawcy stworzone w https://ssl.smsapi.pl/sms_settings/sendernames
'message' => "Hello world!", //treść wiadomości
'format' => 'json'
);
echo sms_send($params, $token);
?>
<?php
declare(strict_types=1);
require_once 'vendor/autoload.php';
use Smsapi\Client\Feature\Sms\Bag\SendSmsBag;
use Smsapi\Client\Feature\Sms\Data\Sms;
use Smsapi\Client\Curl\SmsapiHttpClient;
/** @var Sms $sms */
$sms = (new SmsapiHttpClient())
->smsapiPlService('token_api_oauth')
->smsFeature()
->sendSms(SendSmsBag::withMessage('48500000000', 'Hello world!'));
var_dump($sms);
from smsapi.client import Client
client = Client("https://api.smsapi.pl", access_token="%SMSAPI_ACCESS_TOKEN%")
send_results = client.sms.send(to="48500000000", message="treść wiadomości", from_="Pole Nadawcy")
for result in send_results:
print(result.id, result.points, result.error)
Przykładowa odpowiedź (format JSON):
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
}
Przykładowa odpowiedź (tekst):
a) w przypadku sukcesu:
OK:<ID>:<POINTS>
OK:1460969715572091219:0.16
b) w przypadku niepowodzenia:
ERROR:<ERR>
ERROR:13
-
POST https://api.smsapi.pl/sms.do– dla połączeń szyfrowanych SSL
| Parametr | Opis |
|---|---|
| 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 1530 znaków (lub 670 ze znakami specjalnymi) i jest wysyłana/ jako 10 połączonych SMS-ów, obciążając konto zgodnie z aktualnym cennikiem |
| from | Parametr from definiuje rodzaj wysłanej wiadomości (Pro / 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 typu 2way. 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 wstawienia daty 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 |
| time_restriction | Ustala zachowanie podczas próby wysyłki w godzinach/datach nie odpowiadających ustawieniom na koncie. Dostępne wartości to follow- działaj według ustawień, ignore - ignoruj ustawienia oraz nearest_available- zaplanuj wysyłkę w najbliższym dozwolonym czasie. |
| 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łaniem 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 24h 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, 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 10. 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). |
| fallback | Opcjonalny parametr pozwalający na zastąpienie SMS-a wysyłką VMS w przypadku wysyłki na numer stacjonarny. Należy podać go w postaci jednoelementowej tablicy "type":"vms". Parametr jest dostępny tylko dla pojedynczej wysyłki. |
| format | Dla &format=json powoduje, że zwrotka z API wysyłana jest w formacie JSON. |
Odpowiedź w przypadku powodzenia:
| Odpowiedź OK | Opis |
|---|---|
| id | ID wiadomości w serwisie SMSAPI |
| points | Ilość punktów pobrana za wysyłkę wiadomości SMS konta SMSAPI |
| number | Numer telefonu na który została zlecona wysyłka wiadomości SMS w formacie kod_kraju+numer, np. 48500000000 |
| date_sent | Data wysyłki wiadomości SMS |
| submitted_number | Numer telefonu w formacie przekazanym w odwołaniu do API, np. +48500000000,0048500000000 |
| status | Status doręczenia wiadomości SMS. Pełna lista obsługiwanych statusów |
Odpowiedź w przypadku niepowodzenia:
| Odpowiedź ERROR | Opis |
|---|---|
| ERROR | Kod Błędu |
Wiadomość FAST
POST https://api.smsapi.pl/sms.do- dla połączeń szyfrowanych SSL
curl -X POST -H "Authorization: Bearer token_api_oauth" \
"https://api.smsapi.pl/sms.do?\
from=pole_nadawcy&\
to=44123456789&\
message=tresc_wiadomosci&\
fast=1&\
format=json"
<?php
$params = array(
'to' => '48500000000', //numer odbiorczy
'from' => 'Test', //pole nadawcy stworzone w https://ssl.smsapi.pl/sms_settings/sendernames
'message' => 'treść wiadomości', //treść wiadomości
'fast' => '1',
'format' => 'json'
);
?>
<?php
declare(strict_types=1);
require_once 'vendor/autoload.php';
use Smsapi\Client\Feature\Sms\Bag\SendSmsBag;
use Smsapi\Client\Feature\Sms\Data\Sms;
use Smsapi\Client\Curl\SmsapiHttpClient;
$sendSmsBag = SendSmsBag::withMessage('48500000000', 'Hello world!');
$sendSmsBag->fast = true;
/** @var Sms $sms */
$sms = (new SmsapiHttpClient())
->smsapiPlService('token_api_oauth')
->smsFeature()
->sendSms($sendSmsBag);
var_dump($sms);
from smsapi.client import Client
client = Client("https://api.smsapi.pl", access_token="%SMSAPI_ACCESS_TOKEN%")
send_results = client.sms.send_fast(to="48500000000", message="treść wiadomości", from_="Pole nadawcy")
for result in send_results:
print(result.id, result.points, result.error)
Przykładowa odpowiedź (format JSON):
a) w przypadku sukcesu:
{
"count":1,
"list": [
{
"id":"1460969715572091219", //id wiadomości
"points":0.70, //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
}
Przykładowa odpowiedź (tekst):
a) w przypadku sukcesu:
OK:<ID>:<POINTS>
OK:17101000090360359:0.70
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, 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
POST https://api.smsapi.pl/sms.do- dla połączeń szyfrowanych SSL
curl -X POST -H "Authorization: Bearer token_api_oauth" \
"https://api.smsapi.pl/sms.do?\
from=pole_nadawcy&\
to=44123456789&\
message=tresc_wiadomosci&\
date=1577878200&\
format=json"
<?php
$params = array(
'to' => '48500000000', //numer odbiorczy
'from' => 'Test', //pole nadawcy stworzone w https://ssl.smsapi.pl/sms_settings/sendernames
'message' => 'treść wiadomości', //treść wiadomości
'date' => '1577878200', //data wysyłki UNIXTIME / ISO 8601
'format' => 'json'
);
?>
<?php
declare(strict_types=1);
require_once 'vendor/autoload.php';
use Smsapi\Client\Feature\Sms\Bag\ScheduleSmsBag;
use Smsapi\Client\Feature\Sms\Data\Sms;
use Smsapi\Client\Curl\SmsapiHttpClient;
/** @var Sms $sms */
$sms = (new SmsapiHttpClient())
->smsapiPlService('token_api_oauth')
->smsFeature()
->scheduleSms(ScheduleSmsBag::withMessage(new DateTime(), '48500000000', 'Hello world!'));
var_dump($sms);
from smsapi.client import Client
client = Client("https://api.smsapi.pl", access_token="%SMSAPI_ACCESS_TOKEN%")
send_results = client.sms.send(to="48500000000", message="treść wiadomości", date="1577878200", from_="Pole nadawcy")
for result in send_results:
print(result.id, result.points, result.error)
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:
W celu usunięcia zaplanowanej wiadomości należy w parametrze sch_del podać id wysyłki która ma zostać usunięta. Aby usunąć więcej niż jedną wysyłkę należy podać ID rozdzielone przecinkami.
curl -X POST -H "Authorization: Bearer token_api_oauth" \
"https://api.smsapi.pl/sms.do?\
sch_del=09040616088106874&\
format=json"
<?php
$params = array(
'sch_del' => '9040616088106874', //id wysyłki
'format' => 'json'
);
?>
<?php
declare(strict_types=1);
require_once 'vendor/autoload.php';
use Smsapi\Client\Feature\Sms\Bag\ScheduleSmsBag;
use Smsapi\Client\Feature\Sms\Data\Sms;
use Smsapi\Client\Curl\SmsapiHttpClient;
/** @var Sms $sms */
$sms = (new SmsapiHttpClient())
->smsapiPlService('token_api_oauth')
->smsFeature()
->deleteScheduledSms(new DeleteScheduledSmssBag(['id1', 'id2']));
var_dump($sms);
from smsapi.client import Client
client = Client("https://api.smsapi.pl", access_token="%SMSAPI_ACCESS_TOKEN%")
send_results = client.sms.remove_scheduled(id='ID_zaplanowanej_wiadomości')
for result in send_results:
print(result.id, result.points, result.error)
3. Masowe wysyłanie SMSów
POST https://api.smsapi.pl/sms.do- dla połączeń szyfrowanych SSL
curl -X POST -H "Authorization: Bearer token_api_oauth" \
"https://api.smsapi.pl/sms.do?\
from=pole_nadawcy&\
to=48500500500,48501501501,48502502502&\
message=tresc_wiadomosci&\
format=json"
<?php
$params = array(
'to' => '48500500500,48501501501,48502502502', //numery odbiorcze
'from' => 'Test', //pole nadawcy stworzone w https://ssl.smsapi.pl/sms_settings/sendernames
'message' => 'treść wiadomości', //treść wiadomości
'format' => 'json'
);
?>
<?php
declare(strict_types=1);
require_once 'vendor/autoload.php';
use Smsapi\Client\Feature\Sms\Bag\SendSmssBag;
use Smsapi\Client\Feature\Sms\Data\Sms;
use Smsapi\Client\Curl\SmsapiHttpClient;
/** @var Sms[] $smss */
$smss = (new SmsapiHttpClient())
->smsapiPlService('token_api_oauth')
->smsFeature()
->sendSmss(SendSmssBag::withMessage(['48500000000', '48500000001'], 'Hello world!'));
var_dump($smss);
from smsapi.client import Client
client = Client("https://api.smsapi.pl", access_token="%SMSAPI_ACCESS_TOKEN%")
send_results = client.sms.send(to="48500000000,48500000001,48500000002", message="treść wiadomości", from_="Pole nadawcy")
for result in send_results:
print(result.id, result.points, result.error)
Przykładowa odpowiedź (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ładowa odpowiedź (tekst):
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.
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.
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
POST https://api.smsapi.pl/sms.do- dla połączeń szyfrowanych SSL
curl -X POST -H "Authorization: Bearer token_api_oauth" \
"https://api.smsapi.pl/sms.do?\
from=pole_nadawcy&\
group=grupa_testowa&\
message=treść_z_parametrami_[%imie%]&\
format=json"
<?php
$params = array(
'group' => 'grupa_testowa', //grupa odbiorców
'from' => 'Test', //pole nadawcy stworzone w https://ssl.smsapi.pl/sms_settings/sendernames
'message' => 'treść z parametrami [%imie%]', //treść wiadomości
'format' => 'json'
);
?>
<?php
declare(strict_types=1);
require_once 'vendor/autoload.php';
use Smsapi\Client\Feature\Sms\Bag\SendSmsToGroupBag;
use Smsapi\Client\Feature\Sms\Data\Sms;
use Smsapi\Client\Curl\SmsapiHttpClient;
/** @var Sms[] $smss */
$smss = (new SmsapiHttpClient())
->smsapiPlService('token_api_oauth')
->smsFeature()
->sendSmsToGroup(SendSmsToGroupBag::withMessage('Contacts group name', 'Hello [%imie_w%]!'));
var_dump($smss);
from smsapi.client import Client
client = Client("https://api.smsapi.pl", access_token="%SMSAPI_ACCESS_TOKEN%")
send_results = client.sms.send_to_group(group="Nazwa Grupy", message="treść wiadomości", from_="Pole nadawcy")
for result in send_results:
print(result.id, result.points, result.error)
Przykładowa odpowiedź (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ładowa odpowiedź (tekst):
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
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.informacja%] | Opis kontaktu |
| [%kontakt.email%] | |
| [%kontakt.urzadzenie%] | Urządzenie użytkownika (przypisywany automatycznie w przypadku kliknięcia odbiorcy w skrócony link) |
| [%kontakt.miasto%] | 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
POST https://api.smsapi.pl/sms.do- dla połączeń szyfrowanych SSL
curl -X POST -H "Authorization: Bearer token_api_oauth" \
"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(
'to' => '8600111222,48500111222', //numery odbiorców
'from' => 'Test', //pole nadawcy stworzone w https://ssl.smsapi.pl/sms_settings/sendernames
'message' => 'test wiadomości, parametr1:[%1%] parametr2:[%2%]', //treść wiadomości
'param1' => 'Jan|Ania',
'param2' => '30|40',
'format' => 'json'
);
?>
<?php
declare(strict_types=1);
require_once 'vendor/autoload.php';
use Smsapi\Client\Feature\Sms\Bag\SendSmssBag;
use Smsapi\Client\Feature\Sms\Data\Sms;
use Smsapi\Client\Curl\SmsapiHttpClient;
$sendSmssBag = SendSmssBag::withMessage(['48500000000', '48500000000'], '[%1%] [%2%]!')
->setParams([1 => ['Hello', 'Witaj'], 2 => ['world', 'świecie']]);
/** @var Sms $sms */
$sms = (new SmsapiHttpClient())
->smsapiPlService('token_api_oauth')
->smsFeature()
->sendSmss($sendSmssBag);
var_dump($sms);
from smsapi.client import Client
client = Client("https://api.smsapi.pl", access_token="%SMSAPI_ACCESS_TOKEN%")
send_results = client.sms.send(to=['48500000000', '48500000001'], message='test wiadomości, parametr1:[%1%] parametr2:[%2%]', param1=['Jan', 'Ania'], param2=['30', '40'], from_="Pole nadawcy")
for result in send_results:
print(result.id, result.points, result.error)
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¶m2=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
<?php
declare(strict_types=1);
require_once 'vendor/autoload.php';
use Smsapi\Client\Feature\Sms\Bag\SendSmssBag;
use Smsapi\Client\Feature\Sms\Data\Sms;
use Smsapi\Client\Curl\SmsapiHttpClient;
$sendSmssBag = SendSmssBag::withMessage(['48500000000', '48500000001'], 'Hello world!');
$sendSmssBag->idx = ['id-1', 'id-2'];
/** @var Sms[] $smss */
$smss = (new SmsapiHttpClient())
->smsapiPlService('token_api_oauth')
->smsFeature()
->sendSmss($sendSmssBag);
var_dump($smss);
from smsapi.client import Client
client = Client("https://api.smsapi.pl", access_token="%SMSAPI_ACCESS_TOKEN%")
send_results = client.sms.send(to=['48500000000', '48500000001'], message='treść wiadomości', idx=['idx1', 'idx2'], from_="Pole nadawcy")
for result in send_results:
print(result.id, result.points, result.error)
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
POST https://api.smsapi.pl/sms.do- dla połączeń szyfrowanych SSL
curl -X POST -H "Authorization: Bearer token_api_oauth" \
"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(
'discount_group' => 'kody', //grupa kodów
'to' => '48500500500,48501501501,48502502502', //grupa odbiorców
'from' => 'Test', //pole nadawcy stworzone w https://ssl.smsapi.pl/sms_settings/sendernames
'message' => 'treść z kodem rabatowym [%kod%]', //treść wiadomości
'format' => 'json'
);
?>
<?php
declare(strict_types=1);
require_once 'vendor/autoload.php';
use Smsapi\Client\Feature\Sms\Bag\SendSmssBag;
use Smsapi\Client\Feature\Sms\Data\Sms;
use Smsapi\Client\Curl\SmsapiHttpClient;
/** @var Sms[] $smss */
$smss = (new SmsapiHttpClient())
->smsapiPlService('token_api_oauth')
->smsFeature()
->sendSmss(SendSmssBag::withMessage(['48500000000', '48500000001'], 'Hello world! Discount code: [%kod%]'));
var_dump($smss);
from smsapi.client import Client
client = Client("https://api.smsapi.pl", access_token="%SMSAPI_ACCESS_TOKEN%")
send_results = client.sms.send(to="48500000000,48500000001,48500000002", message="treść wiadomości kod rabatowy: [%kod%]", from_="Pole nadawcy")
for result in send_results:
print(result.id, result.points, result.error)
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
POST https://api.smsapi.pl/sms.do- dla połączeń szyfrowanych SSL
curl -X POST -H "Authorization: Bearer token_api_oauth" \
"https://api.smsapi.pl/sms.do?\
from=pole_nadawcy&\
to=48500000000,48500000001&\
message=test_wiadomości_ze_skróconym_linkiem_[%idzdo:www.smsapi.pl%]&\
format=json"
<?php
$params = array(
'to' => '48500500500,48500000001', //grupa odbiorców
'from' => 'Test', //pole nadawcy stworzone w https://ssl.smsapi.pl/sms_settings/sendernames
'message' => 'test wiadomości ze skróconym linkiem [%idzdo:www.smsapi.pl%]', //treść wiadomości
'format' => 'json'
);
?>
<?php
declare(strict_types=1);
require_once 'vendor/autoload.php';
use Smsapi\Client\Feature\Sms\Bag\SendSmssBag;
use Smsapi\Client\Feature\Sms\Data\Sms;
use Smsapi\Client\Curl\SmsapiHttpClient;
/** @var Sms[] $smss */
$smss = (new SmsapiHttpClient())
->smsapiPlService('token_api_oauth')
->smsFeature()
->sendSmss(SendSmssBag::withMessage(['48500000000', '48500000001'], 'Hello world! Go: [%idzdo:www.smsapi.pl%]'));
var_dump($smss);
from smsapi.client import Client
client = Client("https://api.smsapi.pl", access_token="%SMSAPI_ACCESS_TOKEN%")
send_results = client.sms.send(to="48500000000,48500000001,48500000002", message="treść wiadomości link: [%idzdo:www.smsapi.pl%]", from_="Pole nadawcy")
for result in send_results:
print(result.id, result.points, result.error)
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. Możliwe jest dodanie do 100 numerów w odwołaniu, gdy użyty jest skrócony link.
Linki indywidualne są ważne przez 30 dni, a linki identyczne dla każdego odbiorcy przez 10 lat.
Wiadomości z linkiem Opt-out
POST https://api.smsapi.pl/sms.do- dla połączeń szyfrowanych SSL
curl -X POST -H "Authorization: Bearer token_api_oauth" \
"https://api.smsapi.pl/sms.do?\
from=pole_nadawcy&\
to=48500000000,48500000001&\
message=test wiadomości_z_linkiem_Opt-out_[%opt_out_link%]&\
format=json"
<?php
$params = array(
'to' => '48500500500,48500000001', //grupa odbiorców
'from' => 'Test', //pole nadawcy stworzone w https://ssl.smsapi.pl/sms_settings/sendernames
'message' => 'test wiadomości z linkiem Opt-out [%opt_out_link%]', //treść wiadomości
'format' => 'json'
);
?>
<?php
declare(strict_types=1);
require_once 'vendor/autoload.php';
use Smsapi\Client\Feature\Sms\Bag\SendSmssBag;
use Smsapi\Client\Feature\Sms\Data\Sms;
use Smsapi\Client\Curl\SmsapiHttpClient;
/** @var Sms[] $smss */
$smss = (new SmsapiHttpClient())
->smsapiPlService('token_api_oauth')
->smsFeature()
->sendSmss(SendSmssBag::withMessage(['48500000000', '48500000001'], 'test wiadomości z linkiem Opt-out [%opt_out_link%]'));
var_dump($smss);
from smsapi.client import Client
client = Client("https://api.smsapi.pl", access_token="%SMSAPI_ACCESS_TOKEN%")
send_results = client.sms.send(to="48500000000,48500000001,48500000002", message="test wiadomości z linkiem Opt-out [%opt_out_link%]", from_="Pole nadawcy")
for result in send_results:
print(result.id, result.points, result.error)
Funkcja Opt-out SMS umożliwia wklejenie w treści wiadomości SMS linka prowadzącego do automatycznego wypisania się z grupy odbiorców na danym koncie w panelu klienta SMS. Aby w treści wiadomości umieścić link OptOut należy w parametrze message dodać [%opt_out_link%]. Wypisane z grupy kontakty znajdą się na liście Wypisani oraz będą wykluczane z przyszłych kampanii.
Linki Opt-out wygasają po 14 dniach.
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 o numerze [%2%] zostało wysłane.
curl -H "Authorization: Bearer token_api_oauth" \
"https://api.smsapi.pl/sms.do?\
from=pole_nadawcy&\
to=48500500500&\
template=Powiadomienie&\
param1=Marek&\
param2=BG12344423&\
format=json"
<?php
$params = array(
'to' => '48500500500', //numer odbiorczy
'from' => 'Test', //pole nadawcy stworzone w https://ssl.smsapi.pl/sms_settings/sendernames
'template' => 'Powiadomienie', //nazwa szablonu
'param1' => 'Marek',
'param2' => 'BG12344423',
'format' => 'json'
);
?>
<?php
declare(strict_types=1);
require_once 'vendor/autoload.php';
use Smsapi\Client\Feature\Sms\Bag\SendSmsBag;
use Smsapi\Client\Feature\Sms\Data\Sms;
use Smsapi\Client\Curl\SmsapiHttpClient;
$sendSmsBag = SendSmsBag::withTemplateName('48500000000', 'Powiadomienie');
$sendSmsBag->setParams([1 => 'Marek', 2 => 'BG12344423']);
/** @var Sms $sms */
$sms = (new SmsapiHttpClient())
->smsapiPlService('token_api_oauth')
->smsFeature()
->sendSms($sendSmsBag);
var_dump($sms);
Treść wysłanej wiadomości:
Witaj Marek, Twoje zamówienie o numerze BG12344423 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 https://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 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
GET https://api.smsapi.pl/profile- dla połączeń szyfrowanych SSL
curl -X GET -H "Authorization: Bearer token_api_oauth" \
"https://api.smsapi.pl/profile"
<?php
function getPoints($token)
{
static $content;
$url = 'https://api.smsapi.pl/profile';
$c = curl_init();
curl_setopt($c, CURLOPT_URL, $url);
curl_setopt($c, CURLOPT_RETURNTRANSFER, true);
curl_setopt($c, CURLOPT_HTTPHEADER, array(
"Authorization: Bearer $token"
));
$content = curl_exec($c);
curl_close($c);
return $content;
}
$token = "token_api_oauth"; //https://ssl.smsapi.pl/react/oauth/manage
echo getPoints($token);
?>
<?php
declare(strict_types=1);
require_once 'vendor/autoload.php';
use Smsapi\Client\Feature\Profile\Data\Profile;
use Smsapi\Client\Curl\SmsapiHttpClient;
/** @var Profile $profile */
$profile = (new SmsapiHttpClient())
->smsapiPlService('token_api_oauth')
->profileFeature()
->findProfile();
var_dump($profile->points);
from smsapi.client import Client
client = Client("https://api.smsapi.pl", access_token="%SMSAPI_ACCESS_TOKEN%")
def get_account_balance():
r = client.account.balance()
print(r.points, r.pro_count, r.eco_count, r.mms_count, r.vms_gsm_count, r.vms_land_count)
Przykładowa odpowiedź:
a) w przypadku sukcesu:
{
"name": "string",
"email": "string",
"username": "string",
"phone_number": "string",
"payment_type": "prepaid",
"user_type": "native",
"points": 0 // Ilość punktów dostępnych na koncie SMSAPI
}
b) w przypadku niepowodzenia:
{
"message":"Authorization failed",
"error":"authorization_failed",
"developer_description":null,
"errors":null
}
Endpoint profile pozwala na sprawdzenie stanu konta, typu płatności oraz danych przypisanych do konta SMSAPI.
W przypadku powodzenia odwołania:
| Opowiedź | Opis |
|---|---|
| points | Punkty dostępne na platformie SMSAPI |
| name | Nazwa firmy |
| Kontaktowy email | |
| username | Nazwa użytkownika SMSAPI |
| phone_number | Kontaktowy numer telefonu |
| payment_type | Typ płatności, prepaid lub postpaid |
| user_type | Typ konta na platformie SMSAPI, native lub subuser |
W przypadku niepowodzenia odwołania:
| Opowiedź | Opis |
|---|---|
| message | Opis błędu |
| error | Typ błędu |
| developer_description | Rozszerzona informacja dla developera |
| errors | Tablica błędów |
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
POST https://api.smsapi.pl/mms.do- dla połączeń szyfrowanych SSL
curl -X POST -H "Authorization: Bearer token_api_oauth" \
"https://api.smsapi.pl/mms.do?\
to=48500000000&\
subject=Testowy_MMS&\
smil=[smil]&\
format=json"
<?php
function mms_send($params, $token)
{
static $content;
$url = 'https://api.smsapi.pl/mms.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);
curl_close($c);
return $content;
}
$token = "token_api_oauth"; //https://ssl.smsapi.pl/react/oauth/manage
$params = array(
'to' => '48500000000', //numer odbiorcy
'subject' => 'Testowy_MMS', //pole nadawcy
'smil' => 'smil', //treść wiadomości w formacie SMIL (przykład poniżej)
'format' => 'json'
);
echo mms_send($params, $token);
?>
<?php
declare(strict_types=1);
require_once 'vendor/autoload.php';
use Smsapi\Client\Feature\Mms\Bag\SendMmsBag;
use Smsapi\Client\Feature\Mms\Data\Mms;
use Smsapi\Client\Curl\SmsapiHttpClient;
$smil = '<smil>
<head>
<layout>
<root-layout backgroundColor="#FFFFFF" background-color="#FFFFFF" height="100%" width="100%"/>
<region id="Image" top="0" left="0" height="50%" width="100%" fit="meet"/>
<region id="Text" top="50%" left="0" height="50%" width="100%" fit="scroll"/>
</layout>
</head>
<body>
<par dur="5000ms">
<img src="http://example.com/image.png" region="Image"/>
</par>
<par dur="5000ms">
<text src="http://example.com/plaintext.txt" region="Text"/>
</par>
</body>
</smil>';
/** @var Mms $mms */
$mms = (new SmsapiHttpClient())
->smsapiPlService('token_api_oauth')
->mmsFeature()
->sendMms(new SendMmsBag('48500000000', 'Hello world!', $smil));
var_dump($mms);
from smsapi.client import Client
client = Client("https://api.smsapi.pl", access_token="%SMSAPI_ACCESS_TOKEN%")
def basic_send_mms():
client.mms.send(to='48500000000', subject='Temat Wiadomości', \
smil='<smil>
<head>
<layout>
<root-layout backgroundColor="#FFFFFF" background-color="#FFFFFF" height="100%" width="100%"/>
<region id="Image" top="0" left="0" height="50%" width="100%" fit="meet"/>
<region id="Text" top="50%" left="0" height="50%" width="100%" fit="scroll"/>
</layout>
</head>
<body>
<par dur="5000ms">
<img src="http://example.com/image.png" region="Image"/>
</par>
<par dur="5000ms">
<text src="http://example.com/plaintext.txt" region="Text"/>
</par>
</body>
</smil>')
Przykładowa wiadomość MMS w formacie SMIL:
<smil>
<head>
<layout>
<root-layout backgroundColor="#FFFFFF" background-color="#FFFFFF" height="100%" width="100%"/>
<region id="Image" top="0" left="0" height="50%" width="100%" fit="meet"/>
<region id="Text" top="50%" left="0" height="50%" width="100%" fit="scroll"/>
</layout>
</head>
<body>
<par dur="5000ms">
<img src="http://hiper.lacze.do/pliku.jpg" region="Image"/>
</par>
<par dur="5000ms">
<text src="http://hiper.lacze.do/pliku.txt" region="Text"/>
</par>
</body>
</smil>
Przykładowa odpowiedź (format JSON):
a) w przypadku sukcesu:
{
"count":1,
"list":[
{
"id":"0025459515532275190",
"points":1,
"number":"48500000000",
"date_sent":1535100254,
"submitted_number":"48500000000",
"status":"QUEUE",
"error":null,
"idx":null
}
]
}
b) w przypadku niepowodzenia:
{
"error":11,
"message":"Set Content requires parametter smil!"
}
Poniższa tabela przedstawia parametry niezbędne do wysłania wiadomości MMS.
| Parametr | Opis |
|---|---|
| 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 ¬ify_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
POST https://api.smsapi.pl/vms.do- dla połączeń szyfrowanych SSL
curl -X POST -H "Authorization: Bearer token_api_oauth" \
"https://api.smsapi.pl/vms.do?\
to=48500000000&\
tts=treść_Wiadomości&\
format=json"
<?php
function vms_send($params, $token)
{
static $content;
$url = 'https://api.smsapi.pl/vms.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);
curl_close($c);
return $content;
}
$token = "token_api_oauth"; //https://ssl.smsapi.pl/react/oauth/manage
$params = array(
'to' => '48500000000', //numer odbiorcy
'file' => 'http://hiper.lacze.do/pliku.wav', //ścieżka do pliku audio
//'tts' => 'Treść_Wiadomości', //zamiennie z file
//'tts_lector'=> 'Maja', //zamiennie z file: Ewa, Jan, Maja, Jacek
'format' => 'json'
);
echo vms_send($params, $token);
?>
<?php
declare(strict_types=1);
require_once 'vendor/autoload.php';
use Smsapi\Client\Feature\Vms\Bag\SendVmsBag;
use Smsapi\Client\Feature\Vms\Data\Vms;
use Smsapi\Client\Curl\SmsapiHttpClient;
/** @var Vms $vms */
$vms = (new SmsapiHttpClient())
->smsapiPlService('token_api_oauth')
->vmsFeature()
->sendVms(new SendVmsBag('48500000000', 'Hello world!'));
var_dump($vms);
from smsapi.client import Client
client = Client("https://api.smsapi.pl", access_token="%SMSAPI_ACCESS_TOKEN%")
def basic_send_vms():
client.vms.send(to='48500000000', tts='treść wiadomości VMS')
Lub:
curl -X POST -H "Authorization: Bearer token_api_oauth" \
"https://api.smsapi.pl/vms.do?\
to=48500000000&\
file=http://hiper.lacze.do/pliku.wav&\
format=json"
from smsapi.client import Client
client = Client("https://api.smsapi.pl", access_token="%SMSAPI_ACCESS_TOKEN%")
def send_vms_from_file():
client.vms.send_flash(to='some-number', file='/path/to/vms/file')
Przykładowa odpowiedź (format JSON):
a) w przypadku sukcesu:
{
"count":1,
"list":[
{
"id":"0006759312242528650",
"points":1,
"number":"48500000000",
"date_sent":1535100067,
"submitted_number":"48500000000",
"status":"QUEUE",
"error":null,
"idx":null
}
]
}
b) w przypadku niepowodzenia:
{
"error":23,
"message":"Remote get error: http:\/\/hiper.lacze.do\/pliku.wav"
}
Poniższa tabela przedstawia parametry do wysłania wiadomości VMS:
| Parametr | Opis |
|---|---|
| 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ść |
| from | Własny numer dzwoniący dodany w panelu klienta |
| 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. |
| tts_lector | Określa nazwę lektora czytającego wpisany tekst wiadomości VMS. Dostępne wartości: ewa, jacek, jan, maja. Domyślna wartość to ewa. W przypadku podania błędnej wartości pojawi się błąd ERROR:35 |
| 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 ¬ify_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 endpointa 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: 206.189.63.71, 3.123.166.170, 91.185.184.29, 89.174.81.98, 91.185.187.219, 213.189.53.211
Żądania na adres wywołania zwrotnego są ponawiane cyklicznie aż do ich odbioru bądź archiwizacji powiązanej wiadomości. Wysyłanie żądań na adres wywołania zwrotnego może zostać zablokowane w przypadku wykrycia zbyt dużej ilość błędów podczas transmisji po stronie klienta.
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";
}
?>
Przykład odpowiedzi:
a) W przypadku pojedynczej wartości:
https://example.com/?MsgId=613F1B14346335B944450980&donedate=1631525653&from=Test&idx=1&mcc=260&mnc=3&points=0.0&sent_at=1631525653&status=403&status_name=SENT&to=48500500500&username=smsapi.user
b) W przypadku większej ilości wartości:
https://example.com/?MsgId=613F14C4346335AE0B1DBA31%2C613F14C4346335AE0B1DBA2E%2C613F14C4346335AE0B1DBA30%2C613F14C4346335AE0B1DBA2F%2C613F14C4346335AE0B1DBA2D&donedate=1631525676%2C1631525676%2C1631525676%2C1631525676%2C1631525676&from=Test%2CTest%2CTest%2CTest%2CTest&idx=%2C%2C%2C%2C&mcc=260%2C260%2C260%2C260%2C260&mnc=3%2C3%2C3%2C3%2C3&points=0.16%2C0.16%2C0.16%2C0.16%2C0.16&sent_at=1631525676%2C1631525676%2C1631525676%2C1631525676%2C1631525676&status=403%2C403%2C403%2C403%2C403&status_name=SENT%2CSENT%2CSENT%2CSENT%2CSENT&to=48500500500%2C48500500500%2C48500500500%2C48500500500%2C48500500500&username=smsapi.user%2Csmsapi.user%2Csmsapi.user%2Cmsmsapi.user%2Csmsapi.user
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
Do skryptu wysyłane są parametry za pomocą metody GET. Każdy parametr może posiadać do 5 wartości w zależności od ilości wiadomości w raporcie. Ilość wartości jest taka sama dla każdego parametru.
| 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. Lista statusów |
| status_name | Nazwa statusu doręczenia. Lista statusów |
| idx | Opcjonalny parametr użytkownika wysłany z SMS'em |
| sent_at | Czas podany w formacie unixtime reprezentujący datę wysłania wiadomośći |
| 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. |
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 (string, nie sam status HTTP), 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 (string, nie sam status HTTP), 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 (string, nie sam status HTTP), 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. |
| MsgIdx | Opcjonalny parametr wysyłany z wiadomością (idx) |
| suffix | Sufiks skróconego adresu, np. Hq9Y(dla http://idz.do/Hq9Y) |
| 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 |
Skrypt powinien zwracać OK (string, nie sam status HTTP), w innym przypadku nastąpią ponowne odwołania.
10. 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.
Jeśli odpowiedź na wiadomość 2way zostanie wysłana po upływie 24 godzin, nie gwarantujemy jej przypisania 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 (string, nie sam status HTTP), w innym przypadku nastąpią ponowne odwołania.
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 (string, nie sam status HTTP), w innym przypadku nastąpią ponowne odwołania.
11. HLR
Przykład odwołania:
curl -H "Authorization: Bearer token_api_oauth" \
"https://api.smsapi.pl/hlr.do?\
number=48500000000&\
format=json"
<?php
$params = array(
'access_token' => 'token_api_oauth', //token SMSAPI
'number' => '48500000000', //numer do sprawdzenia
'format' => 'json'
);
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;
}
?>
<?php
declare(strict_types=1);
require_once 'vendor/autoload.php';
use Smsapi\Client\Feature\Hlr\Bag\SendHlrBag;
use Smsapi\Client\Feature\Hlr\Data\Hlr;
use Smsapi\Client\Curl\SmsapiHttpClient;
/** @var Hlr $hlr */
$hlr = (new SmsapiHttpClient())
->smsapiPlService('token_api_oauth')
->hlrFeature()
->sendHlr(new SendHlrBag('48500000000'));
var_dump($hlr);
from smsapi.client import Client
client = Client("https://api.smsapi.pl", access_token="%SMSAPI_ACCESS_TOKEN%")
def check_number():
r = client.hlr.check_number(number='48500000000')
print(r.status, r.number, r.id, r.price)
Przykładowa odpowiedź (format JSON):
a) w przypadku sukcesu:
{
"status": "OK",
"number": "48100200300",
"id": "46567088",
"price": "0.0500"
}
b) w przypadku niepowodzenia:
{
"status":"ERROR",
"number":"481002003001", // nieprawidłowy numer telefonu
"error":13 // kod błędu
}
Przykładowa odpowiedź (tekst):
a) w przypadku sukcesu:
OK:<NUMBER>:<ID>:<POINTS>;OK:<NUMBER>:<ID>:<POINTS>;...;...
OK:44123123123:80625:0.006;OK:44234234234:80627:0.006;
b) w przypadku niepowodzenia:
ERROR:<NUMBER>:<ERR>;ERROR:<NUMBER>:<ERR>;...;...
OK:44123123123:80625:0.006;ERROR:4433412333:13;
gdzie:
<NUMBER> Sprawdzany numer telefonu
<ID> Unikalne ID
<POINTS> Liczba wykorzystanych punktow
<ERR> Kod błędu
Przykład danych wysyłanych do skryptu callback (przesłana do podanego adresu URL w postaci tablicy POST):
Array
(
[0] => Array
(
[id] => 80625
[number] => 48600600600
[mcc] => 260
[mnc] => 2
[info] => T-Mobile
[status] => OK
[date] => 1302703609
[ported] => 0
[ported_from] => null
)
[1] => Array
(
[id] => 80627
[number] => 48500600700
[mcc] => 260
[mnc] => 2
[info] => ABSENT_SUBSCRIBER
[status] => FAIL
[date] => 1302703609
[ported] => 0
[ported_from] => null
)
)
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– dla połączeń zabezpieczonych SSL
z parametrami opisanymi w tabeli poniżej. W jednym odwołaniu może znajdować się do 20 numerów. Informacje o numerach będą wysłane do skryptu do którego adres należy podać w panelu klienta na stronie 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.
Tabelę błędów systemu HLR sprawdzić można w zakładce Kody błędów.
Poniższa tabela przedstawia parametry odwołania HLR:
| Parametr | Opis |
|---|---|
| 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 |
Skrypt powinien zwracać OK, w innym przypadku nastąpią ponowne odwołania.
12. Baza Kontaktów
GET https://api.smsapi.pl/contacts- dla połączeń szyfrowanych SSL
Endpoint contacts pozwala na przeprowadzanie operacji na kontaktach.
Wyświetlanie kontaktów
GET https://api.smsapi.pl/contacts
curl -X GET -H "Authorization: Bearer token_api_oauth" https://api.smsapi.pl/contacts?\
birthday_date=between%281997-02-24%2C%202002-02-24%29
<?php
function getContact($params, $token)
{
$c = curl_init();
curl_setopt($c, CURLOPT_URL, 'https://api.smsapi.pl/contacts?'.$params);
curl_setopt($c, CURLOPT_RETURNTRANSFER, true);
curl_setopt($c, CURLOPT_HTTPHEADER, array(
"Authorization: Bearer $token"
));
$content = curl_exec($c);
curl_close($c);
return $content;
}
$token = "token_api_oauth"; //https://ssl.smsapi.pl/react/oauth/manage
$params = 'phone_number=48500500500'; //parametr = wyszukiwane
//lub w przypadku operatorów:
// $params = 'Pole_dodatkowe=9 -- Zwróci kontakty dla których pole dodatkowe jest równe 9, 90, 99 itd.
// $params = 'Pole_dodatkowe=between(9,11) -- Zwróci kontakty dla których pole dodatkowe jest równe np. 10.
echo getContact($params, $token);
?>
<?php
declare(strict_types=1);
require_once 'vendor/autoload.php';
use Smsapi\Client\Feature\Contacts\Bag\FindContactsBag;
use Smsapi\Client\Feature\Contacts\Data\Contact;
use Smsapi\Client\Curl\SmsapiHttpClient;
$findContactsBag = new FindContactsBag();
$findContactsBag->phoneNumber = 48500000000;
/** @var Contact[] $contacts */
$contacts = (new SmsapiHttpClient())
->smsapiPlService('token_api_oauth')
->contactsFeature()
->findContacts($findContactsBag);
var_dump($contacts);
from smsapi.client import Client
client = Client("https://api.smsapi.pl", access_token="%SMSAPI_ACCESS_TOKEN%")
def get_all_contacts():
l = client.contacts.list_contacts()
for c in l:
print(c.id, c.first_name, c.last_name, c.phone_number)
Przykładowa odpowiedź:
a) w przypadku sukcesu:
{
"size":1,
"collection":[
{
"id":"5b83ba81a788494a0469490f",
"first_name":"Imię",
"last_name":"Nazwisko",
"birthday_date": "1998-03-09",
"phone_number":"48500000000",
"email":"bok@smsapi.pl",
"gender":"male",
"city":"Miasto",
"country":"Poland",
"source":"source",
"date_created":"2018-08-27T10:46:57+02:00",
"date_updated":"2018-08-27T10:46:57+02:00",
"groups":[
{
"id":"59a3ca1fa78849062837cd0c",
"name":"default",
"date_created":"2017-08-28T09:45:35+02:00",
"date_updated":"2017-08-28T09:45:35+02:00",
"description":"",
"created_by":"login",
"idx":null,
"contact_expire_after":null,
"contacts_count":null
}
]
}
]
}
b) w przypadku niepowodzenia:
{
"message":"Authorization failed",
"error":"authorization_failed",
"errors":null
}
Poniższe parametry pozwalają w tej funkcji na filtrowanie listy kontaktów. Szukanie odbywa się case-insensitive.
Istnieje także możliwość filtrowania po polach własnych. Można je dodać w Panelu Klienta Pola własne.
| Parametr | Opis |
|---|---|
| q | Parametr pozwala wyszukać kontakty zawierające podany ciąg znaków w ramach podstawowych pól w bazie kontaktów tj. imię, nazwisko, numer telefonu, email, miejscowość. |
| offset | Listowanie kontaktu od podanej pozycji. |
| limit | Limit klientów którzy mają zostać wylistowani. |
| sort | Parametr określa pole w bazie kontaktów po którym zostanie wykonane sortowanie danych. Kierunek rosnący to np. sort=last_name natomiast kierunek malejący to np. sort=-last_name. |
| phone_number | Listowanie kontaktu o podanym numerze telefonu. |
| Listowanie kontaktu o podanym adresie email. | |
| first_name | Listowanie kontaktów o podanym imieniu. |
| last_name | Listowanie kontaktów o podanym nazwisku. |
| group_id | Listowanie kontaktów należących do określnej grupy (należy podać groupID). |
| gender | Listowanie kontaktów o podanej płci, male lub female. |
| birthday_date | Listowanie kontaktów o podanej dacie urodzin. Data podawana jest w formacie RRRR-MM-DD. |
Do wyszukiwania można także użyć poniższych operatorów. Mogą one nie działać ze wszystkimi typami parametrów.
| Operator | Opis |
|---|---|
| gt | Operator "większe niż" zwraca kontakty gdzie dana wartość jest większa niż podana w parametrze. |
| lt | Operator "mniejsze niż" zwraca kontakty gdzie dana wartość jest mniejsza niż podana w parametrze. |
| gte | Operator "większe lub równe" zwraca kontakty gdzie dana wartość jest większa lub równa podanej w parametrze. |
| lte | Operator "mniejsze lub równe" zwraca kontakty gdzie dana wartość jest mniejsza lub równa podanej w parametrze. |
| eq | Operator "równy" zwraca kontakty gdzie dana wartość jest równa tej podanej w parametrze. |
| = | Operator "like" zwraca kontakty w których dana część wartości zgadza się z podanym parametrem. |
| between | Zwraca kontakty których wartość znajduje się pomiędzy dwoma wartościami podanymi w parametrze. |
Dodawanie kontaktów
POST https://api.smsapi.pl/contacts
curl -X POST "https://api.smsapi.pl/contacts" -H "Authorization: Bearer token_api_oauth" -d\
"phone_number=48500000000&email=bok@smsapi.pl&first_name=imie&last_name=nazwisko&gender=płeć\
&description=opis&city=miasto&groups=default"
<?php
function contactsCreate($params, $token)
{
static $content;
$url = 'https://api.smsapi.pl/contacts';
$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);
curl_close($c);
return $content;
}
$token = "token_api_oauth"; //https://ssl.smsapi.pl/react/oauth/manage
$params = http_build_query(array(
'phone_number' => '500000000', //numer telefonu
'email' => 'bok@smsapi.pl', //adres email
'first_name' => "Imię",
'last_name' => "Nazwisko",
'gender' => "Płeć", // male (mężczyzna) lub female (kobieta)
'birthday_date' => "Data urodzenia", // RRRR-MM-DD
'city' => "Miasto",
'source' => "source",
));
echo contactsCreate($params, $token);
?>
<?php
declare(strict_types=1);
require_once 'vendor/autoload.php';
use Smsapi\Client\Feature\Contacts\Bag\CreateContactBag;
use Smsapi\Client\Feature\Contacts\Data\Contact;
use Smsapi\Client\Curl\SmsapiHttpClient;
/** @var Contact $contact */
$contact = (new SmsapiHttpClient())
->smsapiPlService('token_api_oauth')
->contactsFeature()
->createContact(CreateContactBag::withEmail('example@example.com'));
var_dump($contact);
from smsapi.client import Client
client = Client("https://api.smsapi.pl", access_token="%SMSAPI_ACCESS_TOKEN%")
def create_contact():
c = client.contacts.create_contact(
first_name='imie',
last_name='nazwisko',
phone_number=48500000000,
email='adres email',
birthday_date='1970-01-01',
gender='{male|female|undefined}',
city='Miasto',
description='opis')
Przykładowa odpowiedź:
a) w przypadku sukcesu:
{
"id":"5b802315a788494a04690d1d",
"first_name":"string",
"last_name":"string",
"phone_number":"48500000000",
"email":"bok@smsapi.pl",
"gender":"płeć",
"city":"miasto",
"date_created":"2018-08-24T17:24:05+02:00",
"date_updated":"2018-08-24T17:24:05+02:00",
"description":"opis",
"groups":
[
{
"id":"59a3ca1fa78849062837cd0c",
"name":"default",
"date_created":"2017-08-28T09:45:35+02:00",
"date_updated":"2017-08-28T09:45:35+02:00",
"description":"",
"created_by":"username",
"idx":null,
"contact_expire_after":null,
"contacts_count":null
}
]
}
b) w przypadku niepowodzenia:
{
"message":"Contact already exists",
"error":"contact_conflict",
"code":409,
"errors":[],
"developer_description":null
}
| Parametr | Opis |
|---|---|
| phone_number | Numer telefonu kontaktu. |
| Adres email kontaktu. | |
| first_name | Imię kontaktu. |
| last_name | Nazwisko kontaktu. |
| gender | Płeć kontaktu, male lub female. |
| birthday_date | Data urodzenia kontaktu podana w formacie RRRR-MM-DD |
| city | Miejscowość przypisana do kontaktu. |
| description | Opis kontaktu w bazie klienta. Może zawierać dowolny ciąg znaków. |
W przypadku powodzenia odwołania:
| Opowiedź | Opis |
|---|---|
| id | ID kontaktu |
| first_name | Imię kontaktu zapisane w bazie kontaktów. |
| last_name | Nazwisko kontaktu zapisane w bazie kontaktów. |
| phone_number | Numer telefonu kontaktu zapisany w bazie kontaktów. |
| Adres email kontaktu zapisany w bazie kontaktów. | |
| gender | Płeć kontaktu zapisana w bazie kontaktów |
| city | Miejscowość przypisana do kontaktu, zapisana w bazie kontaktów |
| date_created | Data stworzenia kontaktu w bazie |
| date_updated | Data ostatniej aktualizacji kontaktu w bazie |
| description | Opis kontaktu w bazie kontaktów |
| groups | Grupy do jakich należy kontakt |
W przypadku niepowodzenia odwołania:
| Opowiedź | Opis |
|---|---|
| message | Opis błędu. |
| error | Typ błędu. |
| errors | Tablica błędów. |
Edycja kontaktów
Funkcja pozwala na edycję kontaktu na podstawie jego ID.
PUT https://api.smsapi.pl/contacts/{contactId}
curl -X PUT -H "Content-Type: application/json" -H "Authorization: Bearer token_api_oauth" -d 'email=tech@smsapi.pl\
&phone_number=500000003&email=tech@smsapi.pl&first_name=Imię&last_name=Nazwisko&gender=Płeć' https://api.smsapi.pl/contacts/Id_kontaktu
<?php
function putContact($id,$params,$token)
{
static $content;
$c = curl_init();
curl_setopt($c, CURLOPT_URL, 'https://api.smsapi.pl/contacts/'.$id);
curl_setopt($c, CURLOPT_POSTFIELDS, http_build_query($params));
curl_setopt($c, CURLOPT_RETURNTRANSFER, true);
curl_setopt($c, CURLOPT_CUSTOMREQUEST, "PUT");
curl_setopt($c, CURLOPT_HTTPHEADER, array(
"Authorization: Bearer $token"
));
$content = curl_exec($c);
curl_close($c);
return $content;
}
$params = (array(
'phone_number' => '4850000003',
'email' => 'tech@smsapi.pl',
'first_name' => "Imię",
'last_name' => "Nazwisko",
'gender' => "Płeć", // male,female lub mężczyzna,kobieta
'birthday_date' => "Data Urodzenia", // RRRR-MM-DD
'city' => "Miasto"
));
$token = "token_api_oauth"; //https://ssl.smsapi.pl/react/oauth/manage
$id = "id_kontaktu"; //ID Kontaktu
echo putContact($id, $params, $token);
?>
<?php
declare(strict_types=1);
require_once 'vendor/autoload.php';
use Smsapi\Client\Feature\Contacts\Bag\UpdateContactBag;
use Smsapi\Client\Feature\Contacts\Data\Contact;
use Smsapi\Client\Curl\SmsapiHttpClient;
$update = new UpdateContactBag('contact_id');
/** @var Contact $contact */
$contact = (new SmsapiHttpClient())
->smsapiPlService('token_api_oauth')
->contactsFeature()
->updateContact($update->setName('Imię', 'Nazwisko'));
var_dump($contact);
from smsapi.client import Client
client = Client("https://api.smsapi.pl", access_token="%SMSAPI_ACCESS_TOKEN%")
def update_contacts():
c = client.contacts.update_contact(contact_id=1, description='nowy opis', email='nowy adres email')
print(c.id, c.first_name, c.last_name, c.phone_number)
Przykładowa odpowiedź:
a) w przypadku sukcesu:
{
"id":"5b83ba81a788494a0469490f",
"first_name":"Imię",
"last_name":"Nazwisko",
"phone_number":"48500000001",
"email":"tech@smsapi.pl",
"gender":"undefined",
"city":"Miasto",
"country":"Poland",
"source":"source",
"date_created":"2018-08-27T10:46:57+02:00",
"date_updated":"2018-08-27T14:17:20+02:00",
"groups":[
{
"id":"59a3ca1fa78849062837cd0c",
"name":"default",
"date_created":"2017-08-28T09:45:35+02:00",
"date_updated":"2017-08-28T09:45:35+02:00",
"description":"",
"created_by":"username",
"idx":null,
"contact_expire_after":null,
"contacts_count":null
}
]
}
b) w przypadku niepowodzenia:
{
"message":"Authorization failed",
"error":"authorization_failed",
"errors":null
}
| Parametr | Opis |
|---|---|
| id | ID kontaktu |
| first_name | Imię |
| last_name | Nazwisko |
| phone_number | Numer telefonu |
| Kontaktowy email | |
| gender | Płeć |
| city | Miasto |
| date_created | Data stworzenia |
| date_updated | Data ostatniej aktualizacji |
| description | Opis |
W przypadku powodzenia odwołania:
| Opowiedź | Opis |
|---|---|
| id | ID kontaktu |
| first_name | Imię |
| last_name | Nazwisko |
| phone_number | Numer telefonu |
| Kontaktowy email | |
| gender | Płeć |
| city | Miasto |
| date_created | Data stworzenia |
| date_updated | Data ostatniej aktualizacji |
| description | Opis |
| groups | Grupy do jakich należy kontakt |
W przypadku niepowodzenia odwołania:
| Opowiedź | Opis |
|---|---|
| message | Opis błędu |
| error | Typ błędu |
| errors | Tablica błędów |
Przypisywanie kontaktu do grupy
curl -X PUT -H "Authorization: Bearer token_api_oauth"
'https://api.smsapi.pl/contacts/{contactId}/groups/{groupId}'
<?php
function putContact($contactId, $groupId, $token)
{
static $content;
$c = curl_init();
curl_setopt($c, CURLOPT_URL, 'https://api.smsapi.pl/contacts/'.$contactId.'/groups/'.$groupId);
curl_setopt($c, CURLOPT_RETURNTRANSFER, true);
curl_setopt($c, CURLOPT_CUSTOMREQUEST, "PUT");
curl_setopt($c, CURLOPT_HTTPHEADER, array(
"Authorization: Bearer $token"
));
$content = curl_exec($c);
curl_close($c);
return $content;
}
$token = "token_api_oauth"; //https://ssl.smsapi.pl/react/oauth/manage
$contactId = "id_kontaktu";
$groupId = "id_grupy";
echo putContact($contactId, $groupId, $token);
?>
<?php
declare(strict_types=1);
require_once 'vendor/autoload.php';
use Smsapi\Client\Feature\Contacts\Groups\Bag\AssignContactToGroupBag;
use Smsapi\Client\Feature\Contacts\Data\Contact;
use Smsapi\Client\Curl\SmsapiHttpClient;
/** @var Contact $contact */
$contact = (new SmsapiHttpClient())
->smsapiPlService('token_api_oauth')
->contactsFeature()
->groupsFeature()
->assignContactToGroup(new AssignContactToGroupBag('contact_id', 'group_id'));
var_dump($contact);
Przykładowa odpowiedź:
a) w przypadku sukcesu:
{
"size":1,
"collection":[
{
"id":"1238f47da26ee45dc41fb987",
"name":"Grupa testowa",
"date_created":"2022-04-01T12:00:00+02:00",
"date_updated":"2022-04-01T12:00:00+02:00",
"description":"",
"created_by":"smsapi_user",
"idx":"",
"contact_expire_after":null,
"contacts_count":1,
"permissions":[
{
"username":"smsapi_user",
"group_id":"1238f47da26ee45dc41fb987",
"write":true,
"read":true,
"send":true
}
]
}
]
}
b) w przypadku niepowodzenia:
{
"message":"Authorization failed",
"error":"authorization_failed",
"errors":null
}
Funkcja pozwala na przypisanie kontaktu do wybranej grupy na podstawie jego ID.
PUT https://api.smsapi.pl/contacts/{contactId}/groups/{groupId}
| Parametr | Opis |
|---|---|
| contactId | ID kontaktu |
| groupId | ID grupy |
Aby usunąć kontakt z wybranej grupy, należy wysłać odwołanie typu DELETE zamiast PUT z takimi samymi parametrami.
DELETE https://api.smsapi.pl/contacts/{contactId}/groups/{groupId}
Usuwanie kontaktów
Funkcja pozwala na usunięcie kontaktu na podstawie jego ID.
DELETE https://api.smsapi.pl/contacts/{contactId}
curl -X "DELETE" -H "Authorization: Bearer token_api_oauth" \
https://api.smsapi.pl/contacts/Id_kontaktu
<?php
function deleteContact($contactID,$token)
{
$url = "https://api.smsapi.pl/contacts/".$contactID;
$c = curl_init();
curl_setopt($c, CURLOPT_URL, $url);
curl_setopt($c, CURLOPT_CUSTOMREQUEST, "DELETE");
curl_setopt($c, CURLOPT_HTTPHEADER, array(
"Authorization: Bearer $token"
));
$content = curl_exec($c);
curl_close($c);
return $content;
}
$contactID = "id_kontaktu"; //Id kontaktu który ma zostać usunięty
$token = "token_api_oauth"; //https://ssl.smsapi.pl/react/oauth/manage
echo deleteContact($contactID,$token);
?>
<?php
declare(strict_types=1);
require_once 'vendor/autoload.php';
use Smsapi\Client\Feature\Contacts\Bag\DeleteContactBag;
use Smsapi\Client\Curl\SmsapiHttpClient;
(new SmsapiHttpClient())
->smsapiPlService('token_api_oauth')
->contactsFeature()
->deleteContact(new DeleteContactBag('000000000000000000000000'));
from smsapi.client import Client
client = Client("https://api.smsapi.pl", access_token="%SMSAPI_ACCESS_TOKEN%")
def remove_contact():
client.contacts.delete_contact(contact_id=1)
13. Czarna Lista
Czarna lista pozwala na dodanie numerów telefonów do których blokowane będą wysyłki wiadomości SMS, MMS oraz VMS z danego konta. Data ważności określa do kiedy mają być blokowane wysyłki na dany numer.
Wyświetlanie Czarnej listy
Funkcja pozwala na wyświetlenie czarnej listy.
GET https://api.smsapi.pl/blacklist/phone_numbers
curl -H "Authorization: Bearer token_api_oauth" -H \
"Content-Type: application/json" -X GET https://api.smsapi.pl/blacklist/phone_numbers
<?php
function getBlacklist($token)
{
static $content;
$c = curl_init();
curl_setopt($c, CURLOPT_URL, 'https://api.smsapi.pl/blacklist/phone_numbers');
curl_setopt($c, CURLOPT_RETURNTRANSFER, true);
curl_setopt($c, CURLOPT_HTTPHEADER, array(
"Authorization: Bearer $token"
));
$content = curl_exec($c);
curl_close($c);
return $content;
}
$token = "token_api_oauth"; //https://ssl.smsapi.pl/react/oauth/manage
echo getBlacklist($token);
?>
<?php
declare(strict_types=1);
require_once 'vendor/autoload.php';
use Smsapi\Client\Feature\Blacklist\Bag\FindBlacklistedPhoneNumbersBag;
use Smsapi\Client\Feature\Blacklist\Data\BlacklistedPhoneNumberFactory;
use Smsapi\Client\Curl\SmsapiHttpClient;
/** @var Blacklist $blacklist */
$blacklist = (new SmsapiHttpClient())
->smsapiPlService('token_api_oauth')
->blacklistFeature()
->findBlacklistedPhoneNumbers(new FindBlacklistedPhoneNumbersBag());
var_dump($blacklist);
Przykładowa odpowiedź:
a) w przypadku sukcesu:
[{
"id":"ID_wpisu",
"phone_number":"48500000000",
"created_at":"2018-11-08T09:36:53+01:00",
"expire_at":"2021-03-16"
},
{
"id":"ID_wpisu",
"phone_number":"48500000001",
"created_at":"2018-11-08T09:36:53+01:00",
"expire_at":null
}]
b) w przypadku niepowodzenia:
{
"error": 101,
"message": "authorization_failed"
}
| Parametr | Opis |
|---|---|
| id | Id wpisu |
| phone_number | Numer telefonu znajdującego się na czarnej liście |
| created_at | Data dodania numeru na czarną liste |
| expire_at | Data ważności wpisu na czarnej liście (jeżeli ma wartość "null" nigdy nie wygasa) |
Dodawanie numeru do Czarnej listy
Funkcja pozwala na dodanie numeru do czarnej listy.
POST https://api.smsapi.pl/blacklist/phone_numbers
curl -i -H "Authorization: Bearer token_api_oauth" -H "Content-Type: application/json" -X POST -d \
'{"phone_number":"48500000000","expire_at":"2021-03-16"}' https://api.smsapi.pl/blacklist/phone_numbers
<?php
function addNumbertoblacklist($params, $token)
{
static $content;
$url = 'https://api.smsapi.pl/blacklist/phone_numbers';
$c = curl_init();
curl_setopt($c, CURLOPT_URL, $url);
curl_setopt($c, CURLOPT_POST, true);
curl_setopt($c, CURLOPT_POSTFIELDS, http_build_query($params));
curl_setopt($c, CURLOPT_RETURNTRANSFER, true);
curl_setopt($c, CURLOPT_HTTPHEADER, array(
"Authorization: Bearer $token"
));
$content = curl_exec($c);
curl_close($c);
return $content;
}
$token = "token_api_oauth"; //https://ssl.smsapi.pl/react/oauth/manage
$params = array(
'phone_number' => '48500000000',
'expire_at' => '2021-03-16'
);
echo addNumbertoblacklist($params, $token);
?>
<?php
declare(strict_types=1);
require_once 'vendor/autoload.php';
use Smsapi\Client\Feature\Blacklist\Bag\CreateBlacklistedPhoneNumberBag;
use Smsapi\Client\Feature\Blacklist\Data\BlacklistedPhoneNumberFactory;
use Smsapi\Client\Curl\SmsapiHttpClient;
/** @var Blacklist $blacklist */
$blacklist = (new SmsapiHttpClient())
->smsapiPlService('token_api_oauth')
->blacklistFeature()
->createBlacklistedPhoneNumber(new CreateBlacklistedPhoneNumberBag('48500000000'));
var_dump($blacklist);
Przykładowa odpowiedź:
a) w przypadku sukcesu:
{
"id":"ID_wpisu",
"phone_number":"48500000000",
"created_at":"2018-11-08T09:36:53+01:00",
"expire_at":"2021-03-16"
}
b) w przypadku niepowodzenia:
{
"error": 101,
"message": "authorization_failed"
}
| Parametr | Opis |
|---|---|
| id | Id wpisu |
| phone_number | Numer telefonu znajdującego się na czarnej liście |
| created_at | Data dodania numeru na czarną liste |
| expire_at | Data ważności wpisu na czarnej liście (jeżeli ma wartość "null" nigdy nie wygasa) |
Usuwanie numeru z czarnej listy
Funkcja pozwala na usunięcie numeru z czarnej listy.
DELETE https://api.smsapi.pl/blacklist/phone_numbers/{Id_wpisu}
curl -X "DELETE" -H "Authorization: Bearer token_api_oauth" \
https://api.smsapi.pl/blacklist/phone_numbers/Id_wpisu
<?php
function deleteNumberfromblacklist($token,$Id)
{
$url = "https://api.smsapi.pl/blacklist/phone_numbers/".$Id;
$c = curl_init();
curl_setopt($c, CURLOPT_URL, $url);
curl_setopt($c, CURLOPT_CUSTOMREQUEST, "DELETE");
curl_setopt($c, CURLOPT_HTTPHEADER, array(
"Authorization: Bearer $token"
));
$content = curl_exec($c);
curl_close($c);
return $content;
};
$Id = '5BE3F5A53738306F740DB6DB'; //Id wpisu który ma zostać usunięty
$token = "token_api_oauth"; //https://ssl.smsapi.pl/react/oauth/manage
echo deleteNumberfromblacklist($token,$Id);
?>
<?php
declare(strict_types=1);
require_once 'vendor/autoload.php';
use Smsapi\Client\Feature\Blacklist\Bag\DeleteBlacklistedPhoneNumberBag;
use Smsapi\Client\Feature\Blacklist\Data\BlacklistedPhoneNumberFactory;
use Smsapi\Client\Curl\SmsapiHttpClient;
/** @var Blacklist $blacklist */
$blacklist = (new SmsapiHttpClient())
->smsapiPlService('token_api_oauth')
->blacklistFeature()
->deleteBlacklistedPhoneNumber(new DeleteBlacklistedPhoneNumberBag('record_id'));
Wyczyszczenie czarnej listy
Funkcja pozwala na usunięcie wszystkich numerów z czarnej listy.
DELETE https://api.smsapi.pl/blacklist/phone_numbers
curl -X "DELETE" -H "Authorization: Bearer token_api_oauth" \
https://api.smsapi.pl/blacklist/phone_numbers
<?php
function deleteAllNumbersFromBlacklist($token)
{
$url = "https://api.smsapi.pl/blacklist/phone_numbers";
$c = curl_init();
curl_setopt($c, CURLOPT_URL, $url);
curl_setopt($c, CURLOPT_CUSTOMREQUEST, "DELETE");
curl_setopt($c, CURLOPT_HTTPHEADER, array(
"Authorization: Bearer $token"
));
$content = curl_exec($c);
curl_close($c);
return $content;
};
$token = "token_api_oauth"; //https://ssl.smsapi.pl/react/oauth/manage
echo deleteAllNumbersFromBlacklist($token);
?>
<?php
declare(strict_types=1);
require_once 'vendor/autoload.php';
use Smsapi\Client\Curl\SmsapiHttpClient;
/** @var Blacklist $blacklist */
$blacklist = (new SmsapiHttpClient())
->smsapiPlService('token_api_oauth')
->blacklistFeature()
->deleteBlacklistedPhoneNumbers();
14. Konto użytkownika
Listowanie użytkowników
Funkcja pozwala na wyświetlenie listy użytkowników.
GET https://api.smsapi.pl/subusers
curl -i -H "Authorization: Bearer token_api_oauth"\
-H "Content-Type: application/json" -X GET https://api.smsapi.pl/subusers
<?php
function getSubusers($token)
{
static $content;
$c = curl_init();
curl_setopt($c, CURLOPT_URL, 'https://api.smsapi.pl/subusers');
curl_setopt($c, CURLOPT_RETURNTRANSFER, true);
curl_setopt($c, CURLOPT_HTTPHEADER, array(
"Authorization: Bearer $token"
));
$content = curl_exec($c);
curl_close($c);
return $content;
}
$token = "token_api_oauth"; //https://ssl.smsapi.pl/react/oauth/manage
echo getSubusers($token);
?>
<?php
declare(strict_types=1);
require_once 'vendor/autoload.php';
use Smsapi\Client\Feature\Subusers\Data\Subuser;
use Smsapi\Client\Curl\SmsapiHttpClient;
/** @var Subuser[] $subusers */
$subusers = (new SmsapiHttpClient())
->smsapiPlService('token_api_oauth')
->subusersFeature()
->findSubusers();
var_dump($subusers);
Przykładowa odpowiedź:
a) w przypadku sukcesu:
[{
"id":"5A5359173738303F2F95B7E2",
"username":"subuser1",
"active":true,
"description":null,
"points":{
"from_account":10.0,
"per_month":0.0
}
},
{
"id":"5A5359173738303F2F95B7E2",
"username":"subuser2",
"active":true,
"description":null,
"points":{
"from_account":10.0,
"per_month":0.0
}
}]
b) w przypadku niepowodzenia:
{
"error": 123,
"message": "error message"
}
| Parametr | Opis |
|---|---|
| id | Id użytkownika |
| username | Nazwa użytkownika |
| active | "true" - aktywny, "false" - nieaktywny |
| description | Opis |
| from_account | Punkty udostępnione przez głównego użytkownika |
| per_month | Miesięczy odnawialny limit punktów |
Dodawanie użytkownika
Funkcja pozwala na dodanie użytkownika.
POST https://api.smsapi.pl/subusers
Przykład:
curl -i -H "Authorization: Bearer token_api_oauth"\
-H "Content-Type: application/json" -X POST -d \
'{"credentials":{"username":"Nazwa_uzytkownika","password":"Hasło_do_Panelu","api_password":"Hasło_do_API"},\
"active":"1","description":"Opis","points":{"from_account":"2","per_month":"2"}}'\
https://api.smsapi.pl/subusers
<?php
function subuserCreate($params, $token)
{
static $content;
$url = 'https://api.smsapi.pl/subusers';
$c = curl_init();
curl_setopt($c, CURLOPT_URL, $url);
curl_setopt($c, CURLOPT_POST, true);
curl_setopt($c, CURLOPT_POSTFIELDS, http_build_query($params));
curl_setopt($c, CURLOPT_RETURNTRANSFER, true);
curl_setopt($c, CURLOPT_HTTPHEADER, array(
"Authorization: Bearer $token"
));
$content = curl_exec($c);
curl_close($c);
return $content;
}
$token = "token_api_oauth"; //https://ssl.smsapi.pl/react/oauth/manage
$params = array(
'credentials' => array(
'username' => 'nazwa_Subużytkownika',
'password' => 'hasło do Panelu Klienta',
'api_password' => 'hasło do API'
),
'active' => true,
'description' => "opis",
'points' => array(
'from_account' => 2, //Ilość punktów udostępnionych dla Subkonta
'per_month' => 2 //Limit odnawialny dla Subkonta
)
);
echo subuserCreate($params, $token);
?>
<?php
declare(strict_types=1);
require_once 'vendor/autoload.php';
use Smsapi\Client\Feature\Subusers\Bag\CreateSubuserBag;
use Smsapi\Client\Feature\Subusers\Data\Subuser;
use Smsapi\Client\Curl\SmsapiHttpClient;
/** @var Subuser $subuser */
$subuser = (new SmsapiHttpClient())
->smsapiPlService('token_api_oauth')
->subusersFeature()
->createSubuser(new CreateSubuserBag('username', 'password'));
var_dump($subuser);
Przykładowa odpowiedź:
a) w przypadku sukcesu:
{
"id":"ABCD1234EFGH9876ABCD1234",
"username":"subuser123",
"active":true,
"description":"new subuser for tests",
"points":
{
"from_account":2.0, //Punkty udostępnione przez głównego użytkownika
"per_month":2.0 //Miesięczny odnawialny limit punktów
}
}
b) w przypadku niepowodzenia:
{
"message":"Username already exists",
"error":"invalid_domain_logic",
"errors":[
{
"error":"invalid_domain_logic",
"message":"Username already exists"
}]
}
| Parametr | Opis |
|---|---|
| username | Nazwa dodawanego użytkownika |
| password | Hasło do panelu klienta SMSAPI dodawanego subkonta |
| api_password | Hasło do interfejsu API dla użytkownika |
| from_account | Limit punktów przydzielony użytkownikowi |
| per_month | Ilość punktów która będzie przypisana do konta użytkownika każdego pierwszego dnia |
| active | Aktywowanie konta użytkownika (dostępne wartości: 1/true – aktywne, 0/false – nieaktywne, domyślnie wartość równa 0) |
| description | Dodatkowy opis użytkownika |
Usuwanie użytkownika
Funkcja pozwala na usunięcie użytkownika na podstawie jego ID.
DELETE https://api.smsapi.pl/subusers/{subuser_id}
curl -X "DELETE" -H "Authorization: Bearer token_api_oauth" \
https://api.smsapi.pl/subusers/{subuser_id}
<?php
function deleteSubuser($token,$userID)
{
$url = "https://api.smsapi.pl/subusers/".$userID;
$c = curl_init();
curl_setopt($c, CURLOPT_URL, $url);
curl_setopt($c, CURLOPT_CUSTOMREQUEST, "DELETE");
curl_setopt($c, CURLOPT_HTTPHEADER, array(
"Authorization: Bearer $token"));
$content = curl_exec($c);
curl_close($c);
return $content;
}
$userID = "subuser_id"; //Id użytkownika który ma zostać usunięty
$token = "token_api_oauth"; //https://ssl.smsapi.pl/react/oauth/manage
echo deleteSubuser($token,$userID);
?>
<?php
declare(strict_types=1);
require_once 'vendor/autoload.php';
use Smsapi\Client\Feature\Subusers\Bag\DeleteSubuserBag;
use Smsapi\Client\Feature\Subusers\Data\SubuserFactory;
use Smsapi\Client\Curl\SmsapiHttpClient;
/** @var Subusers $subusers */
$subusers = (new SmsapiHttpClient())
->smsapiPlService('token_api_oauth')
->subusersFeature()
->deleteSubuser(new DeleteSubuserBag('subuser_id'));
| Parametr | Opis |
|---|---|
| subuser_id | Id użytkownika (subkonta) |
Edycja użytkownika
curl -X PUT -H "Content-Type: application/json" \
-H "Authorization: Bearer token_api_oauth" -d\
'{"credentials":{"password":"Hasło_do_Panelu","api_password":"Hasło_do_API"}, \
"active":"1","description":"Opis","points":{"from_account":"2","per_month":"2"}}'
'https://api.smsapi.pl/subusers/{subuser_id}'
<?php
function putSubuser($id,$params,$token)
{
static $content;
$c = curl_init();
curl_setopt($c, CURLOPT_URL, 'https://api.smsapi.pl/subusers/'.$id);
curl_setopt($c, CURLOPT_POSTFIELDS, http_build_query($params));
curl_setopt($c, CURLOPT_RETURNTRANSFER, true);
curl_setopt($c, CURLOPT_CUSTOMREQUEST, "PUT");
curl_setopt($c, CURLOPT_HTTPHEADER, array(
"Authorization: Bearer $token"
));
$content = curl_exec($c);
curl_close($c);
return $content;
}
$params = array(
'credentials' => array(
'password' => 'hasło do Panelu Klienta',
'api_password' => 'hasło do API'
),
'active' => true,
'description' => "opis",
'points' => array(
'from_account' => 2, //Ilość punktów udostępnionych dla Subkonta
'per_month' => 2 //Limit odnawialny dla Subkonta
)
);
$token = "token_api_oauth"; //https://ssl.smsapi.pl/react/oauth/manage
$id = "subuser_id"; //ID Subkonta
echo putSubuser($id, $params, $token);
?>
<?php
declare(strict_types=1);
require_once 'vendor/autoload.php';
use Smsapi\Client\Feature\Subusers\Bag\UpdateSubuserBag;
use Smsapi\Client\Feature\Subusers\Data\Subuser;
use Smsapi\Client\Curl\SmsapiHttpClient;
/** @var Subuser $subuser */
$updateSubuserBag = new UpdateSubuserBag('000000000000000000000000');
$updateSubuserBag->active = true;
$subuser = (new SmsapiHttpClient())
->smsapiPlService('token_api_oauth')
->subusersFeature()
->updateSubuser($updateSubuserBag);
var_dump($subuser);
Przykładowa odpowiedź:
a) w przypadku sukcesu:
{
"id":"5A8D6E6F373830607C87B277",
"username":"Subuser name",
"active":true,
"description":"Opis",
"points":{
"from_account":2,
"per_month":2
}
}
b) w przypadku niepowodzenia:
{
"error": 123,
"message": "error message"
}
Zarządzanie kontem odbywa się przez wysłanie metodą GET lub POST danych do adresu połączenia.
GET https://api.smsapi.pl/subusers/{subuser_id}POST https://api.smsapi.pl/subusers/{subuser_id}
| Parametr | Opis |
|---|---|
| subuser_id | Id użytkownika (subkonta) |
| token_api_oauth | Token przypisany do konta w serwisie SMSAPI |
| username | Nazwa edytowanego użytkownika bez prefiksu użytkownika głównego |
| password | Hasło do panelu klienta SMSAPI dodawanego użytkownika |
| api_password | Hasło do interfejsu API dla użytkownika. |
| from_account | Limit punktów przydzielony użytkownikowi |
| per_month | Ilość punktów która będzie przypisana do konta użytkownika każdego pierwszego dnia |
| active | Aktywowanie konta użytkownika (dostępne wartości: 1 – aktywne, 0 – nieaktywne, domyślnie wartość równa 0) |
| description | Dodatkowy opis użytkownika |
Udostępnianie pól nadawcy
curl -X PUT -H "Content-Type: application/json" \
-H "Authorization: Bearer token_api_oauth" \
-d '{"access":"selected","senders":["pole_nadawcy1","pole_nadawcy3"]}' \
'https://api.smsapi.pl/subusers/{subuser_id}/shares/sendernames'
<?php
function putAccess($id,$params,$token)
{
$c = curl_init();
curl_setopt($c, CURLOPT_URL, 'https://api.smsapi.pl/subusers/'.$id.'/shares/sendernames');
curl_setopt($c, CURLOPT_POSTFIELDS, http_build_query($params));
curl_setopt($c, CURLOPT_RETURNTRANSFER, true);
curl_setopt($c, CURLOPT_CUSTOMREQUEST, "PUT");
curl_setopt($c, CURLOPT_HTTPHEADER, array(
"Authorization: Bearer $token"
));
$content = curl_exec($c);
curl_close($c);
return $content;
}
$token = "token_api_oauth"; //https://ssl.smsapi.pl/react/oauth/manage
$id = "subuser_id"; //Id użytkownika (subkonta) któremu modyfikujemy dostęp do pól nadawcy
$params = array(
'access' => "selected", //none | selected | all
'senders' => ["pole_nadawcy1","pole_nadawcy3"]
);
echo putAccess($id,$params,$token);
?>
Funkcja pozwala na zarządzanie udostępnianymi polami nadawcy użytkowników (subkont).
PUT https://api.smsapi.pl/subusers/{subuser_id}/shares/sendernames
| Parametr | Opis |
|---|---|
| subuser_id | Id użytkownika (subkonta) |
| access | Typ dostępu do pól nadawcy konta głównego ("none" - żadne, "selected" - wybrane, "all" - wszystkie) |
| senders | Tablica z listą pól nadawcy, które mają być udostępnione dla subkonta. Parametr ustawiany w przypadku gdy parametr access = 'selected' |
15. Pola nadawcy
Sekcja poświęcona zarządzaniu polami nadawcy konta. Zarządzanie udostępnianymi polami nadawcy z konta głównego dla użytkowników (subkont) została opisana w zakładce Konto użytkownika -> Udostępnianie pól nadawcy.
Dodawanie pola nadawcy
curl -X POST "https://api.smsapi.pl/sms/sendernames" \
-H "Authorization: Bearer token_api_oauth" -d "sender=nowe_pole_nadawcy"
<?php
function add_sendername($token, $params)
{
static $content;
$url = 'https://api.smsapi.pl/sms/sendernames';
$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);
curl_close($c);
return $content;
}
$token = "token_api_oauth"; //https://ssl.smsapi.pl/react/oauth/manage
$params = array(
'sender' => 'nowe_pole_nadawcy',
);
echo add_sendername($token, $params);
?>
Przykładowa odpowiedź:
a) w przypadku sukcesu:
{
"sender":"nowe_pole_nadawcy",
"is_default":false,
"status":"INACTIVE",
"created_at":"2020-01-01T00:00:00+02:00"
}
Zwracany jest również kod HTTP201
b) w przypadku niepowodzenia:
{
"message":"Sendername is not valid",
"error":"invalid_sender",
"errors":[
{
"error":"invalid_sender",
"message":"Sendername is not valid"
}]
}
Funkcja dodawania pól nadawcy wymaga dodatkowej aktywacji. Aby aktywować funkcję prosimy o kontakt z Biurem Obsługi Klienta.
POST https://api.smsapi.pl/sms/sendernames
Dodanie nowego pola nadawcy odbywa się przez wysłanie zapytania metodą POST.
| Parametr | Opis |
|---|---|
| sender | Nazwa pola nadawcy, która ma zostać dodana |
Status pola nadawcy
Funkcja pozwala na wyświetlenie statusu pola nadawcy.
GET https://api.smsapi.pl/sms/sendernames/{sender}
curl -H "Authorization: Bearer token_api_oauth" \
"https://api.smsapi.pl/sms/sendernames/{sender}"
<?php
function getSender($sender, $token)
{
$c = curl_init();
curl_setopt($c, CURLOPT_URL, 'https://api.smsapi.pl/sms/sendernames/'.$sender);
curl_setopt($c, CURLOPT_RETURNTRANSFER, true);
curl_setopt($c, CURLOPT_HTTPHEADER, array(
"Authorization: Bearer $token"
));
$content = curl_exec($c);
curl_close($c);
return $content;
}
$token = "token_api_oauth"; //hhttps://ssl.smsapi.pl/react/oauth/manage
$sender = "sender_name";
echo getSender($sender, $token);
?>
Przykładowa odpowiedź:
a) w przypadku sukcesu:
{
"sender":"pole_nadawcy",
"is_default":false,
"status":"ACTIVE",
"created_at":"2020-01-01T00:00:00+02:00"
}
b) w przypadku niepowodzenia:
{
"message":"Sendername not exists",
"error":"not_found_sendername",
"errors":[
{
"error":"not_found_sendername",
"message":"Sendername not exists"
}]
}
Sprawdzanie statusu pola nadawcy odbywa się przez wysłanie metodą GET danych do adresu połączenia:
| Parametr | Opis |
|---|---|
| {sender} | Nazwa pola nadawcy, którego status ma być sprawdzony |
Listy pól nadawcy
Funkcja pozwala na wyświetlenie listy pól nadawcy.
GET https://api.smsapi.pl/sms/sendernames
curl -H "Authorization: Bearer token_api_oauth" \
"https://api.smsapi.pl/sms/sendernames"
<?php
function getSenderlist($token)
{
static $content;
$c = curl_init();
curl_setopt($c, CURLOPT_URL, 'https://api.smsapi.pl/sms/sendernames');
curl_setopt($c, CURLOPT_RETURNTRANSFER, true);
curl_setopt($c, CURLOPT_HTTPHEADER, array(
"Authorization: Bearer $token"
));
$content = curl_exec($c);
curl_close($c);
return $content;
}
$token = "token_api_oauth"; //https://ssl.smsapi.pl/react/oauth/manage
echo getSenderlist($token);
?>
Przykładowa odpowiedź:
a) w przypadku sukcesu:
{
"collection":[
{
"sender":"pole_nadawcy1",
"is_default":false,
"status":"ACTIVE",
"created_at":"2018-09-23T12:00:00+02:00"
},
{
"sender":"pole_nadawcy2",
"is_default":true,
"status":"ACTIVE",
"created_at":"2019-05-19T16:00:00+02:00"
},
{
"sender":"pole_nadawcy3",
"is_default":false,
"status":"INACTIVE",
"created_at":"2020-01-01T00:30:00+02:00"
}
],
"size":3
}
b) w przypadku niepowodzenia:
{
"message":"Authorization failed",
"error":"authorization_failed",
"developer_description":null,
"errors":null
}
Domyślne pole nadawcy
Funkcja pozwala na ustawienie domyślnego pola nadawcy.
POST https://api.smsapi.pl/sms/sendernames/{sender}/commands/make_default
curl -H "Authorization: Bearer token_api_oauth" \
-X POST "https://api.smsapi.pl/sms/sendernames/{sender}/commands\
/make_default"
<?php
function DefaultSendername($token,$sender)
{
static $content;
$url = 'https://api.smsapi.pl/sms/sendernames/'.$sender.'/commands/make_default';
$c = curl_init();
curl_setopt($c, CURLOPT_URL, $url);
curl_setopt($c, CURLOPT_POST, true);
curl_setopt($c, CURLOPT_RETURNTRANSFER, true);
curl_setopt($c, CURLOPT_HTTPHEADER, array(
"Authorization: Bearer $token"
));
$content = curl_exec($c);
curl_close($c);
return $content;
}
$token = "token_api_oauth"; //https://ssl.smsapi.pl/react/oauth/manage
$sender = "sender_name";
echo DefaultSendername($token,$sender);
?>
Przykładowa odpowiedź:
a) w przypadku sukcesu:
Zwracany jest tylko kod HTTP204
b) w przypadku niepowodzenia:
{
"message":"Sendername not exists",
"error":"not_found_sendername",
"errors":[
{
"error":"not_found_sendername",
"message":"Sendername not exists"
}
]
}
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.
| Parametr | Opis |
|---|---|
| {sender} | Nazwa, która ma być ustawiona jako domyślna |
16. SMS Authenticator
SMS Authenticator jest implementacją 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łany kod autoryzacyjny jest ważny 180 sekund.
Wiadomości wysyłane za pomocą SMS Authenticatora domyślnie są wiadomościami typu FAST co wiąże się z kosztami wysyłki x1.5. Jeżeli wiadomości mają być wysyłane bez opcji FAST należy w zapytaniu dodać parametr fast=0.
Wysyłka kodu
curl -H "Authorization: Bearer token_api_oauth"\
-H "Content-Type: application/json" -X POST -d\
'{"phone_number":"48500500500","from":"Test","content":"Twój kod: [%code%]","fast":"1"}'\
https://api.smsapi.pl/mfa/codes
<?php
$url = 'https://api.smsapi.pl/mfa/codes';
$ch = curl_init($url);
$params = array(
'phone_number' => '48500500500', //numer telefonu do wysyłki kodu
'from' => 'Test', //pole nadawcy stworzone w https://ssl.smsapi.pl/sms_settings/sendernames
'content' => 'Twój kod: [%code%]', //treść wiadomości z polem [%code%] (parametr opcjonalny)
'fast' => '1' //typ wiadomości (domyślnie fast=1)
);
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_POSTFIELDS, $params);
curl_setopt($ch, CURLOPT_HTTPHEADER, array('Authorization: Bearer token_api_oauth'));
$result = curl_exec($ch);
?>
<?php
declare(strict_types=1);
require_once 'vendor/autoload.php';
use Smsapi\Client\Feature\Mfa;
use Smsapi\Client\Feature\Mfa\Bag\CreateMfaBag;
use Smsapi\Client\Curl\SmsapiHttpClient;
$createMfaBag = new CreateMfaBag('48500500500');
$createMfaBag->from = 'Test';
$createMfaBag->content = 'Twój kod: [%code%]';
/** @var Mfa $mfa */
$mfa = (new SmsapiHttpClient())
->smsapiPlService('token_api_oauth')
->mfaFeature()
->generateMfa($createMfaBag);
var_dump($mfa);
Przykładowa odpowiedź:
{
"id":"5ADEF4DC3738305BEED02B0C",
"code":"123456",
"phone_number":"48500500500",
"from":"Test"
}
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 |
|---|---|
| phone_number | Numer telefonu odbiocy SMS autoryzacyjnego |
| from | Pole nadawcy z jakiego wysłany będzie SMS autoryzacyjny. W przypadku braku parametru from, wiadomość zostanie wysłana z domyślnym polem nadawcy dla danego konta |
| content | Spersonalizowana treść wiadomości autoryzacyjnej z polem [%code%]. W przypadku braku parametru content, wiadomość zostanie wysłana z domyślną treścią |
| fast | Ustawienie priorytetu wysyłanej wiadomości, domyślnie fast=1 z szybszym doręczeniem wiadomości, opłata x1.5 zwykłej wiadomości |
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 (z dodanym prefiksem kraju) |
| from | Pole nadawcy z jakiego wysłany został SMS autoryzacyjny |
Sprawdzenie poprawności kodu
curl -H "Authorization: Bearer token_api_oauth"\
-H "Content-Type: application/json" -X POST -i -d\
'{"phone_number":"48500500500","code":"123456"}'\
https://api.smsapi.pl/mfa/codes/verifications
<?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 token_api_oauth'));
$result = curl_exec($ch);
?>
<?php
declare(strict_types=1);
require_once 'vendor/autoload.php';
use Smsapi\Client\Feature\Mfa;
use Smsapi\Client\Feature\Mfa\Bag\VerificationMfaBag;
use Smsapi\Client\Curl\SmsapiHttpClient;
/** @var Mfa $mfa */
$mfa = (new SmsapiHttpClient())
->smsapiPlService('token_api_oauth')
->mfaFeature()
->verifyMfa(new VerificationMfaBag('123456', '48500500500'));
var_dump($mfa);
Przykładowa odpowiedź:
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 |
|---|---|
| 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 (czas powyżej 180 sekund) |
17. 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
18. 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 |
19. Kody błędów
| ERROR | Opis |
|---|---|
| 7 | Skrócone linki są wyłączone na koncie |
| 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 (zbyt duża liczba odbiorców, w przypadku użycia skróconego linku, limit wynosi 100) |
| 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 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ą. |
| 37 | Wiadomość TTS jest zbyt długa |
| 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. |
| 59 | Numer znajduje się na liście "Wypisani" |
| 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 |
| 76 | Nieprawidłowe znaki w parametrach żądania |
| 94 | Wysyłka wiadomości z linkiem jest zablokowana |
| 96 | Limit wysyłek na koncie dla kraju został osiągnięty |
| 98 | Twoje konto jest ograniczone. Możesz wysyłać wiadomości tylko na numer użyty podczas rejestracji. |
| 101 | Niepoprawne lub brak danych autoryzacji |
| 102 | Nieprawidłowy login lub hasło |
| 103 | Brak punktów dla tego użytkownika |
| 104 | Brak szablonu |
| 105 | Błędny adres IP (włączony filtr IP dla interfejsu API) |
| 106 | Błędny adres URL do skrócenia w parametrze [%idzdo:adres_URL%] |
| 110 | Usługa (SMS, MMS, VMS lub HLR) nie jest dostępna na danym koncie. |
| 112 | Wysyłka wiadomości na numery telefonów w tym kraju jest zablokowana na 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. Dotyczy endpointu https://api.smsapi.pl/subusers |
| 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. |
| 401 | Token nie ma uprawnień do wykonywanej akcji. |
| 409 | Podana wartość już istnieje. |
| 997 | Żądania HTTP zostały wyłączone na Twoim koncie, prosimy o używanie bezpiecznego połączenia (HTTPS) |
| 998 | Usługa idz.do nie jest dostępna |
| 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 |
Kody błędów HLR
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 |
20. 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 ^ { } [ ] \ ~ | € 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 |
Dopuszczalna liczba znaków w wiadomościach:
| Liczba części | Bez znaków specjalnych | Ze znakami specjalnymi |
|---|---|---|
| 1 część | 160 znaków | 70 znaków |
| 2 części | 306 znaków | 134 znaków |
| 3 części | 459 znaków | 201 znaków |
| 4 części | 612 znaków | 268 znaków |
| 5 części | 765 znaków | 335 znaków |
| 6 części | 918 znaków | 402 znaków |
| 7 części | 1071 znaków | 469 znaków |
| 8 części | 1224 znaków | 536 znaków |
| 9 części | 1377 znaków | 603 znaków |
| 10 części | 1530 znaków | 670 znaków |
21. Kodowanie
Przykład:
curl -H "Authorization: Bearer token_api_oauth" \
"https://api.smsapi.pl/sms.do?\
from=pole_nadawcy&\
to=48500000000&\
encoding=utf-8&\
message=treść_wiadomości"
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
22. 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ń
W ustawieniach należy przejść do zakładki „Filtry”, a następnie wybrać opcję „utwórz nowy filtr”
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ą.
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ą
Gmail konfiguracja skryptu
function SMSapi() {
// Konfiguracja
/*******************************************************/
var MAIL_LABEL = 'SMSAPI'; // etykieta (w Gmail) dla której zostanie zrealizowana wysyłka powiadomień SMS
var SMSAPI_TOKEN = 'token_api_oauth';
var SMSAPI_SENDERNAME = 'Test'; // pole nadawcy stworzone w https://ssl.smsapi.pl/sms_settings/sendernames
var SMSAPI_RECIVER = 'tel_number'; // odbiorca wiadomości SMS
var MESSAGE = 'New email from: :SENDER, topic: :TITLE'; // treść wiadomości SMS z dodatkowymi parametrami :SENDER, :TITLE
/*******************************************************/
var threads = GmailApp.getUserLabelByName(MAIL_LABEL).getThreads();
for(i in threads)
UrlFetchApp.fetch('https://api.smsapi.pl/sms.do?encoding=utf-8&access_token='+SMSAPI_TOKEN+'&from='+SMSAPI_SENDERNAME+'&to='+encodeURIComponent(SMSAPI_RECIVER)+"&message="+encodeURIComponent(MESSAGE.replace(':SENDER',threads[i].getMessages()[0].getFrom()).replace(':TITLE', threads[i].getMessages()[0].getSubject())));
GmailApp.getUserLabelByName(MAIL_LABEL).removeFromThreads(threads);
}
Wymagane zmienne wraz z opisem:
* MAIL_LABEL – nazwa etykiety po której następuje filtrowanie wiadomości email do powiadomień SMS
* SMSAPI_TOKEN – token w serwisie SMSAPI
* SMSAPI_SENDERNAME – pole nadawcy stworzone w https://ssl.smsapi.pl/sms_settings/sendernames
* SMSAPI_RECIVER – numer telefonu odbiorcy
* MESSAGE – treść wiadomości
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
W nowo otwartym oknie usuwamy przykład rozpoczętego skryptu oraz wklejamy skrypt dostępny w naszej dokumentacji.
W celu ustawienia częstotliwości wykonywania skryptu należy wybrać 
(wyzwalacze bieżącego projektu) a następnie dodać nowy wyzwalacz i wybrać częstotliwość wyzwalania
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
Google Calendar
function SmsApiCalendar()
{
/* Configuration */
var SMSAPI_TOKEN = 'token';
var SMSAPI_RECEIVER = '48XXXXXXXXX'; // Numer odbiorcy
var SMSAPI_SENDERNAME = 'Test'; //pole nadawcy stworzone w https://ssl.smsapi.pl/sms_settings/sendernames
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(); // dla domyślnego kalendarza na koncie
// lub
// var calendar = CalendarApp.getCAlendarsByName('nazwa_kalendarza') dla określonego kalendarza
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');
}
}
Wymagane zmienne wraz z opisem:
* 'SMSAPI_TOKEN' - token smsAPI
* 'SMSAPI_RECIVER' - numer odbiorczy
* 'SMSAPI_SENDERNAME' - pole nadawcy stworzone w https://ssl.smsapi.pl/sms_settings/sendernames
* '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
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” , następnie „No triggers set up. Click here to add one now” oraz zmienić ustawienia na „Minutes timer” i „Every minute”.
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.
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
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
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.
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.
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. 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
Opcja przedstawiona poniżej pozwala na aktywacje wysyłki oraz konfigurację treści powiadomienia SMS o nowym zamówieniu.
Opcja przedstawiona poniżej pozwala na aktywacje wysyłki oraz konfigurację treści powiadomień SMS o zmianie statusu zamówienia w sklepie IAI-SHOP.
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.
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=Test&message=@@Text@@
Następnie należy wybrać przycisk Zapisz
W kolejnym kroku należy wybrać z listy wyboru przed chwilą utworzoną konfigurację - SMSAPI.pl
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
W kolejnym kroku należy wybrać kraj oraz numery telefonów (maksymalnie dwa) na jakie mają być wysyłane powiadomienia o błędach.
Autoryzacja OAuth2 Webflow
OAuth - metoda autoryzacji umożliwiająca integrację aplikacji zewnętrznych z SMSAPI. Przed rozpoczęciem procesu integracji prosimy o kontakt na adres e-mail tech@smsapi.pl w celu przydzielenia client_id i client_secret.
GET https://ssl.smsapi.pl/oauth/access/
Przykład pierwszego kroku autoryzacji (użytkownik jest przekierowywany do SMSAPI, gdzie musi się zalogować i zatwierdzić integrację):
https://ssl.smsapi.pl/oauth/access?client_id=123456&redirect_uri=https://www.sample.pl/&scope=sms mms hlr
Przykładowa odpowiedź:
https://www.sample.pl/?code=11112222
W pierwszym kroku autoryzacji użytkownik jest przekierowywany do panelu SMSAPI, gdzie musi się zalogować i zatwierdzić integrację. Po otrzymaniu pozytywnej weryfikacji użytkownik zostaje przekierowany na stronę podaną w parametrze redirect_uri i otrzymuje swój code, który należy podać w drugim kroku.
Wymagane parametry:
| Parametr | Opis |
|---|---|
| client_id | Unikalne ID dla aplikacji |
| redirect_uri | Adres URL, na który zostanie przekierowany użytkownik po autoryzacji |
| scope | Zdefiniowane uprawnienia do funkcjonalności |
| state | Opcjonalny parametr - token CSRF |
Dostępne parametry scope:
| Parametr | Opis |
|---|---|
| sms | Dostęp do wysyłki SMS |
| mms | Dostęp do wysyłki MMS |
| vms | Dostęp do wysyłki VMS |
| sms_sender | Dostęp do zarządzania polami nadawcy SMS |
| hlr | Dostęp do odwołań HLR |
| contacts | Dostęp do bazy kontaktów |
| subuser | Dostęp do zarządzania użytkownikami |
| blacklist | Dostęp do zarządzania czarną listą |
| mfa | Dostęp do MFA |
| callback | Dostęp do zarządzania callbackami |
| short_url | Dostęp do zarządzania skróconymi linkami |
| profile | Dostęp do zarządzania profilem użytkownika |
-
POST https://api.smsapi.pl/oauth/token"
W drugim kroku należy przesłać client_secret, code oraz parametry z pierwszego kroku za pomocą metody POST, aby zakończyć proces autoryzacji. Otrzymany access_token można wykorzystać do autoryzacji zapytań do SMSAPI.
Przykład drugiego kroku:
curl -X POST "https://api.smsapi.pl/oauth/token" -d "client_id=1112223334444\
&client_secret=111222333444&code=11112222&grant_type=authorization_code\
&redirect_uri=https://www.sample.pl/"
Przykładowa odpowiedź:
{
"access_token":"A1b***x2Z",
"token_type":"Bearer",
"expires":1577836800,
"expires_in":604800,
"refresh_token":"c3D*************************4eF"
}
* access_token – token pozwalający na dostep do zasobów za pośrednictwem API
* token_type – typ tokena (w przypadku SMSAPI zawsze "Bearer")
* expires – data wygaśnięcia tokena w formacie unixstamp
* expires_in – czas ważności tokena (dni, godziny i minuty)
* refresh_token – refresh token, który pozwala na przedłużenie ważności autoryzacji
Wymagane parametry:
| Parametr | Opis |
|---|---|
| client_id | Unikalne ID dla aplikacji |
| client_secret | Prywatna wartość unikalna dla Twojej aplikacji |
| code | Kod autoryzacyjny zwracany po pierwszym zapytaniu |
| grant_type | Typ autoryzacji, powinien mieć wartość "authorization_code" |
| redirect_uri | Adres URL na który zostanie skierowana odpowiedź dla autoryzacji |
-
POST https://api.smsapi.pl/oauth/token
Aby utrzymać połączenie należy wysłać zapytanie zawierające refresh_token, który jest otrzymywany w drugim odwołaniu. W kolejnych odwołaniach należy zastąpić access_token i refresh_token nowymi, otrzymanymi w tym zapytaniu.
Przykład odwołania z refresh_token:
curl -X POST "https://api.smsapi.pl/oauth/token" -d "client_id=123456\
&client_secret=111222333444&refresh_token=AaaaaBbbbbCccccDdddd\
&grant_type=refresh_token"
Przykładowa odpowiedź:
{
"access_token":"BD1***p3k",
"token_type":"Bearer",
"expires":1577837800,
"expires_in":604800,
"refresh_token":"yn3*************************z54"
}
Wymagane parametry:
| Parametr | Opis |
|---|---|
| client_id | Unikalne ID dla aplikacji |
| client_secret | Prywatna wartość unikalna dla Twojej aplikacji |
| refresh_token | Token otrzymany w drugim kroku |
| grant_type | Typ autoryzacji, powinien mieć wartość "refresh_token" |
PKCE
SMSAPI obsługuje też autoryzację z wykorzystaniem PKCE (Proof Key for Code Exchange). Od standardowej autoryzacji OAuth różni się tym, że w celu jej przeprowadzenia należy wygenerować losowy ciąg znaków code_verifier. W pierwszym kroku należy podać przekształconą wersję tego ciągu znaków pod nazwą code_challenge, a w drugim kroku przesłać code_verifier. Parametr client_secret przesyłany w drugim kroku jest opcjonalny.
Parametr code_challenge powstaje przez zahashowanie code_verifier metodą SHA256 i zakodowanie hasha za pomocą Base64. Możesz wykonać kodowanie URL Base64, biorąc ciąg zakodowany w Base64 i zmieniając '+' i '/' odpowiednio na '-' i '_', a następnie przycinając końcowe '='.
GET https://ssl.smsapi.pl/oauth/access/
Przykład pierwszego kroku autoryzacji (użytkownik jest przekierowywany do SMSAPI, gdzie musi się zalogować i zatwierdzić integrację):
https://ssl.smsapi.pl/oauth/access?client_id=123456&redirect_uri=https://www.sample.pl/&code_challenge=12345678&code_challenge_method=S256&scope=sms
Przykładowa odpowiedź:
https://www.sample.pl/?code=11112222
Wymagane parametry:
| Parametr | Opis |
|---|---|
| client_id | Unikalne ID dla aplikacji |
| redirect_uri | Adres URL, na który zostanie przekierowany użytkownik po autoryzacji |
| code_challenge | Parametr generowany jak opisano wyżej |
| code_challenge_method | Metoda generowania code_challenge, powinna zawsze mieć wartość S256 |
| scope | Zdefiniowane uprawnienia do funkcjonalności |
| state | Opcjonalny parametr - token CSRF |
-
POST https://api.smsapi.pl/oauth/token
Przykład drugiego kroku:
curl -X POST "https://api.smsapi.pl/oauth/token" -d "client_id=1112223334444\
&code_verifier=111222333444&code=11112222&grant_type=authorization_code\
&redirect_uri=https://www.sample.pl/"
Przykładowa odpowiedź:
{
"access_token":"A1b***x2Z",
"token_type":"Bearer",
"expires":1577836800,
"expires_in":604800,
"refresh_token":"c3D*************************4eF"
}
* access_token – token pozwalający na dostep do zasobów za pośrednictwem API
* token_type – typ tokena (w przypadku SMSAPI zawsze "Bearer")
* expires – data wygaśnięcia tokena w formacie unixstamp
* expires_in – czas ważności tokena (dni, godziny i minuty)
* refresh_token – refresh token, który pozwala na przedłużenie ważności autoryzacji
Po otrzymaniu pozytywnej weryfikacji w pierwszym zapytaniu należy dosłać informacje za pomocą metody POST aby zakończyć proces autoryzacji. Otrzymany access_token można wykorzystać do autoryzacji zapytań do SMSAPI.
Wymagane parametry:
| Parametr | Opis |
|---|---|
| client_id | Unikalne ID dla aplikacji |
| code | Kod autoryzacyjny zwracany po pierwszym zapytaniu |
| grant_type | Typ autoryzacji, powinien mieć wartość "authorization_code" |
| redirect_uri | Adres URL, na który zostanie przekierowany użytkownik po autoryzacji |
| client_secret | Opcjonalny parametr - prywatna wartość unikalna dla Twojej aplikacji |
-
POST https://api.smsapi.pl/oauth/token
Aby utrzymać połączenie należy wysłać zapytanie zawierające refresh_token, który jest otrzymywany w drugim odwołaniu. W kolejnych odwołaniach należy zastąpić access_token i refresh_token nowymi, otrzymanymi w tym zapytaniu.
Przykład odwołania z refresh_token:
curl -X POST "https://api.smsapi.pl/oauth/token" -H "client_id=123456\
&refresh_token=AaaaaBbbbbCccccDdddd&grant_type=refresh_token"
Przykładowa odpowiedź:
{
"access_token":"BD1***p3k",
"token_type":"Bearer",
"expires":1577837800,
"expires_in":604800,
"refresh_token":"yn3*************************z54"
}
Wymagane parametry:
| Parametr | Opis |
|---|---|
| client_id | Unikalne ID dla aplikacji |
| refresh_token | Token otrzymany w drugim kroku |
| grant_type | Typ autoryzacji, powinien mieć wartość "refresh_token" |
Pozostałe Integracje
Pozostałe serwisy i usługi, które można zintegrować z SMSAPI znajdziesz tutaj: Integracje.