SOAP API

Wstecz

Poniższa dokumentacja odnosi się do SOAP API w wersji 3.1. 

Jeżeli Twoje konto rozliczane jest w systemie złotówkowym, a nie punktowym, korzystasz z SOAP API w wersji 2.0.

Poniższe przykłady działają w oparciu o stworzoną przez nas, a dla Państwa wygody, gotową bibliotekę, którą można pobrać tutaj.

Wprowadzenie

SOAP API dostępne jest pod adresem https://promosms.com/api/soap/v3.1

Ponadto, aby zwiększyć poziom bezpieczeństwa systemu, udostępniamy zapasowe API dostępne pod adresem: https://backup2.promosms.com/api/soap/v3.1

Pierwszym parametrem wywołania każdej metody jest obiekt klasy Authentication, zawierający dane uwierzytelniające.

 

Definicja klasy Authentication
PoleTypWymagane
login string tak
password string tak

 

login - identyfikator użytkownika, czyli adres email

password - hasło dostępu do API (w postaci jawnej)

 

Kody odpowiedzi:

Statusy wykonania metody są indywidualne dla każdej metody (dotyczy kodów 1-399)

  • 0 - operacja przebiegła pomyślnie
  • 00 00012 (110) - 11 11112 (6310) - wykonano z ostrzeżeniami. Ostrzeżenia zapisywane są na pojedynczych bitach i jednocześnie może wystąpić więcej niż jedno
  • 100-199 - wystąpił błąd - nie przekazano wszystkich wymaganych danych
  • 200-299 - wystąpił błąd - wartości przekazanych danych są niepoprawne
  • 300-399 - wystąpił błąd - konfiguracja konta lub systemu nie pozwala na wykonanie operacji
  • 400 - błąd uwierzytelniania (którego przyczyną może być: niepoprawna para login / hasło, IP nie znajduje się na liście autoryzowanych adresów, przekroczono limit prób logowania)
  • 401 - 403 - nieoczekiwany błąd

Wysyłanie wiadomości SMS

 

Przykładowy kod PHP

View source
 
 
 
<?php 
require_once('Client.php');
 
 
$promoSms = new \PromoSms\Soap\Client();
$auth = new \PromoSms\Soap\Authentication('login@example.com';, 'secretPassword');
 
 
$response = $promoSms->sendSms(
 $auth,
 new \PromoSms\Soap\SendSmsRequest(
 array(
 new \PromoSms\Soap\Message(
 'Wiadomość testowa', // text
 1, // type
 array('504304204') // recipients
 )
 )
 )
);
if ($response->status < 100) {
 echo 'Wiadomość została wysłana. Kosz wysyłki: ' . $response->points . PHP_EOL;
} else {
 echo 'Wystąpił błąd: ' . $response->status . PHP_EOL;
}
 
 

 

Definicja metody

View source
SendSmsResponse sendSms (
 Authentication authentication, 
 SendSmsRequest request 
 )

 

Definicja klasy SendSmsRequest
PoleTypWymagane
messages Vector tak
returnRecipientResults boolean nie (domyślnie false)

 

  • messages - tablica/wektor obiektór typu Message
  • returnRecipientResults - flaga określająca, czy w obiekcie odpowiedzi mają się znajdować szczegóły dotyczące każdego adresata

 

Definicja klasy Message
PoleTypWymagane
text string tak
type integer tak
recipients Vector tak
sender string tak - dla MaxSMS i FasterSMS
specialChars boolean nie (domyślnie false)
longSms boolean nie (domyślnie false)
date integer nie
binarySms boolean nie (domyślnie false)
udh string tak jeżeli binarySms = true
deliveryUrl string nie
userIndexes Vector nie
shortLinkEnabled bool nie (domyślnie false)

 

  • text - treść wysyłanej wiadomości
  • type - typ wysyłanego SMSa. Dozwolone typy to:
    • 0 - FlashSMS
    • 1 - EkoSMS
    • 3 - MaxSMS
    • 4 - FasterSMS
  • recipients - tablica/wektor odbiorców wiadomości. W tablicy stringów mają znajdować się więc numery telefonów odbiorców wiadomości (każdy element tablicy to kolejny odbiorca)
  • sender - nazwa nadawcy SMSa (wyświetlana zamiast numeru telefonu). Aby korzystać z własnej nazwy nadawcy należy ją wcześniej zarejestrować. W przypadku EkoSMS/FlashSMS parametr ten jest opcjonalny
  • specialChars - ustawienie tej wartości na true spowoduje, że znaki specjalne nie będą zamieniane na odpowiadające im znaki standardowe, lecz wiadomość zostanie wysłana w postaci przekazanej do systemu. Warto jednak pamiętać, że przekazywanie w treści SMSa znaków specjalnych powoduje, że długość SMS’a zmniejsza się ze standardowych 160 znaków do 70. Jeżeli zatem chcemy, aby platforma PromoSMS usuwała wszelkie niestandardowe znaki (znaki specjalne), należy podać wartość tej zmiennej ustawioną na false
  • longSms - ustawienie tej wartości na true powoduje, że przez platformę są przyjmowane do wysyłki także wiadomości dłuższe niż 160 znaków (lub 70 w przypadku zmiennej specialChars ustawionej na true). Takie wiadomości będą dostarczone jako jedna całość (potocznie: jako jeden SMS), ale należy liczyć się z wyższym kosztem wysyłki (uzależniony od liczby wiadomości składowych)
  • date - znacznik czasowy określający moment kiedy wiadomość ma zostać wysłana (unixowy znacznik czasowy wyrażony w sekundach)
  • binarySms - parametr opcjonalny. Ustawienie tej wartości na true spowoduje, że zostanie wysłany SMS binarny. W takim wypadku obowiązkowe jest zdefiniowanie wartości parametru udh
  • udh - wartość nagłówka UDH wiadomości binarnej
  • deliveryUrl - adres URL serwera użytkownika, na który mają być przekazywane raporty dostarczenia wiadomości. W adresie URL mogą być podane następujące zmienne specjalne, które zostaną zastąpione odpowiednią wartością przez system podczas przesyłania raportu na serwer klienta:
    • %smsID - ID wysłanej wiadomości
    • %timestamp - data raportu w postaci unixowego znacznika czasu
    • %number - numer na jaki została wysłana wiadomość
    • %report - ID raportu (1 oznacza dostarczone)
    • %ownID - identyfikator własny użytkownika
  • userIndexes - parametr pozwala użytkownikowi zdefiniować własne identyfikatory wiadomości. Liczba elementów tablicy/wektora musi być równa liczbie zdefiniowanych odbiorców wiadomości. Wówczas każdej wiadomości, będzie przyporządkowany kolejny element z tej tablicy. Możliwe jest również zdefiniowanie jednego elementu dla tej tablicy/wektora, aby wszystkim wysłanym wiadomościom był przypisany ten sam identyfikator
  • shortLinkEnabled - stawienie tej wartości powoduje, że odpowiednio przygotowane linki, znajdujące się w treści wiadomości, zostaną zamienione na krótki link. Żeby link został poprawnie zinterpretowany, musi mieć postać: <<url:http://www.example.com/test>>

 

Definicja klasy SendSmsResponse
PoleTyp
status integer
points float
sentSmsCount integer
contentIds Vector
recipientsResults Vector

 

  • status - kod odpowiedzi
  • points - koszt zrealizowanej wysyłki (wyrażony w punktach)
  • sentSmsCount - liczba pomyślnie wysłanych wiadomości
  • contentIds - wektor identyfikatorów treści wysyłki
  • recipientsResults - wektor obiektów typu RecipientResult (lub null jeżeli nie ustawiono parametru wejściowego returnRecipientResults na true)

 

Kody odpowiedzi metody SendSms:

KodOpis
012 (110) Wiadomość została przekazana do późniejszej wysyłki
102 (210) Część podanych numerów telefonów jest niepoprawna
100 Nie podano adresatów wysyłki
101 Nie podano treści
102 Nie podano pola nadawcy
103 Nie podano pola UDH
104 Nie podano ani jednego obiektu Message
200 Wszystkie podane numery telefonów są niepoprawne
201 Nazwa nadawcy jest za długa
202 Nie można wysłać wiadomości w przeszłość
203 Liczba własnych identyfikatorów jest niezgodna z liczbą odbiorców
204 Wiadomość jest dłuższa niż 1 sms
205 Wiadomość jest dłuższa niż 4 sms’y (maksimum)
206 Podano więcej niż jednego adresata wysyłki FasterSMS
207 Treść zawiera znaki spoza zbioru Unicode
208 Jedna wysyłka zawiera adresatów z różnych krajów
209 Niepoprawny typ wiadomości
300 Stan konta nie pozwala na zrealizowanie wysyłki
301 Nazwa nadawcy nie została zarejestrowana
302 Nie można wysłać tego typu wiadomości do wybranego kraju
303 Konto nie zostało przystosowane do korzystania z tej wersji API

 

Definicja klasy RecipientResult
PoleTyp
recipient string
contentId integer
smsId string
ownId string
status integer

 

  • recipient - numer telefonu adresata
  • contentId - identyfikator treści (wiadomości o tej samej treści wysyłane jednocześnie, mają jednakową wartość tego parametry)
  • smsId - indywidualny identifykator wiadomości
  • ownId - identyfikator nadany przez użytkownika
  • status - status przekazania wiadomości
    • 0 - przekazano
    • 210 - numer niepoprawny

Raporty dostarczenia

 

Przykładowy kod PHP

View source
<?php
 require_once('Client.php');
 
 $promoSms = new \PromoSms\Soap\Client();
 $auth = new \PromoSms\Soap\Authentication('login@example.com', 'secretPassword');
 
 $response = $promoSms->sendSms(
 $auth,
 new PromoSms\Soap\GetReportsRequest(
 array('098f6bcd4621d373cade4e832627b4f6'), // indexes
 null, // fromTime
 null, // toTime
 0 // indexType
 )
 )
 if ($response->status < 100) {
 var_dump($response->reports);
 } else {
 echo 'Wystąpił błąd: ' . $response->status . PHP_EOL;
 }

 

Definicja metody

View source
GetReportsResponse getReports (
     Authentication authentication,
    GetReportsRequest request
 )

 

Definicja klasy GetReportsRequest
PoleTypWymagane
indexes Vector nie
fromTime integer nie
toTime integer nie
indexType integer tak, jeżeli użyto pola indexes
limit integer nie
offset integer nie

 

  • indexes - tablica lub wektor identyfikatorów wiadomości. W zależności od wartości pola indexType, są to identyfikatory smsId, własne identyfikatory użytkownika (userIndex) lub identyfikatory treści (contentId)
  • fromTime - czas (w postaci uniksowego znacznika czasu), od którego momentu chcemy pobrać informację o statusach wysłanych wiadomości
  • toTime - czas (w postaci uniksowego znacznika czasu), do którego momentu chcemy pobrać informację o statusach wysłanych wiadomości
  • indexType - rodzaj identyfikatora
    • 0 - smsId
    • 1 - userIndex
    • 2 - contentId
  • limit - opcja przydatna w przypadku, kiedy trzeba pobrać dużą liczbę statusów (np. kilkadziesiąt tysięcy). Wówczas możemy ograniczyć liczbę zwracanych elementów w tablicy/wektorze
  • offset - pole to określa, od jakiego momentu ma być zwracana tablica/wektor. Wartość tego pola brana jest pod uwagę tylko w momencie zastosowania parametru limit

 

Definicja klasy GetReportsResponse
PoleTyp
status integer
reports Vector

 

  • status - kod odpowiedzi
  • reports - tablica/wektor raportów

 

KodOpis
012 (110) Część identyfikatorów wiadomości jest niepoprawna
100 Nie określono typu identyfikatora
101 Nie podano identyfikatorów wiadomości
200 Wszystkie podane identyfikatory są niepoprawne
201 Niepoprawny znacznik czasowy
202 Niepoprawny typ identyfikatora
203 Niepoprawna wartość parametru limit
204 Niepoprawna wartość parametru offset

 

Definicja klasy Report
PoleTyp
recipient string
smsId string
ownId string
contentId integer
status integer
lastUpdateTime integer

 

  • recipient - numer telefonu adresata wiadomości
  • smsId - unikalny identyfikator wiadomości
  • ownId - identyfikator nadany przez użytkownika
  • contentId - identyfikator treści
  • status - stan wysyłki
    • 0 - wiadomość oczekuje na wysłanie
    • 4, 8 - wiadomość została wysłana
    • 1 - wiadomość została dostarczona do odbiorcy
    • 2, 16 - wiadomość nie została dostarczona - najczęstsze przyczyny tego statusu to niepoprawny numer telefonu lub brak aktywności telefonu adresata przez zbyt długi okres czasu
  • lastUpdateTime - czas ostatniej aktualizacji statusu

Odbieranie odpowiedzi

 

W przypadku realizacji wysyłki EkoSMS bądź MaxSMS za pomoca zakupionego numeru telefonu, istnieje możliwość, aby odbiorca wiadomości odpowiedział na nią. Odpowiedzi takie dostępne są zarówno przez Panel SMS jak i poprzez SOAP API.

 

Odbiór wiadomości odbywa się poprzez wywołanie metody getInbox

 

Przykładowy kod PHP

View source
<?php require_once('Client.php');
 
 $promoSms = new \PromoSms\Soap\Client();
 $auth = new \PromoSms\Soap\Authentication('login@example.com', 'secretPassword');
 
 $response = $promoSms->getInbox(
 $auth,
 new \PromoSms\Soap\GetInboxRequest(
 null, // lastMessageId
 strtotime('2015-08-01 00:00:00'), // fromTime
 null, // contentId
 null, // smsId
 null // ownId
 )
 );
 if ($response->status < 100) {
 var_dump($response->inboxMessages);
 } else {
 echo 'Wystąpił błąd: ' . $response->status . PHP_EOL;
 }

 

Definicja metody

View source
GetInboxResponse getInbox (
 Authentication authentication, 
 GetInboxRequest request 
 )

 

Definicja klasy GetInboxRequest
PoleTypWymagane
lastMessageId integer nie
fromTime integer nie
contentId integer nie
smsId string nie
ownId string nie

 

  • lastMessageId - każda odebrana wiadomość SMS ma swój unikalny identyfikator w postaci liczby. Jeżeli chcemy odbierać wiadomość tylko od danej wiadomości o znanym nam identyfikatorze - należy go tutaj podać. Jeżeli więc wcześniej przy odbiorze wiadomości ostatnia odczytana wiadomość miała numer 359 i teraz chcemy, aby funkcja zwróciła tylko nowsze wiadomości - to jako wartość tego parametru należy podać 359.
  • fromTime - jeżeli zamiast podawania identyfikatora wiadomości chcemy pobrać wszystkie wiadomości od danego momentu to należy go tutaj podać w postaci uniksowego znacznika czasu.
  • contentId - jeżeli ten parametr jest ustawiony, zwracane są odpowiedzi jedynie na wiadomości o podanym identyfikatorze treści
  • smsId - unikalny identyfikator wiadomości
  • ownId - identyfikator wiadomości nadany przez użytkownika

 

Definicja klasy GetInboxResponse
PoleTyp
status integer
inboxMessages Vector

 

  • status - kod odpowiedzi
  • inboxMessages - tablica/wektor odpowiedzi

 

KodOpis
012 (110) Brak nowych odpowiedzi
200 Niepoprawny identyfikator odpowiedzi
201 Niepoprawny znacznik czasowy
202 Niepoprawny identyfikator treści

 

Definicja klasy InboxMessage
PoleTyp
messageId integer
sender string
message string
originalMessage string
receiveTime integer

 

  • messageId - identyfikator odpowiedzi
  • sender - numer telefonu osoby przesyłającej odpowiedź
  • message - treść odpowiedzi
  • originalMessage - treść wiadomości, której dotyczy odpowiedź
  • receiveTime - czas otrzymania wiadomości (w postaci uniksowego znacznika czasowego)

 

Sprawdzanie stanu konta

 

Sprawdzanie stanu konta odbywa się poprzez wywołanie metody getBalance

 

Przykładowy kod PHP

View source
<?php
 require_once('Client.php');
 
 $promoSms = new \PromoSms\Soap\Client();
 $auth = new \PromoSms\Soap\Authentication('login@example.com', 'secretPassword');
 
 $response = $promoSms->getBalance($auth); if ($response->status < 100) {
 echo 'Stan konta: ' . $response->pointsAvailable . PHP_EOL;
 } else {
 echo 'Wystąpił błąd: ' . $response->status . PHP_EOL;
 }

 

Definicja metody

View source
GetBalanceResponse getBalance (
 Authentication authentication 
 )

 

Definicja klasy GetInboxResponse
PoleTyp
status integer
pointsAvailable integer
pointsBlocked integer
pointsCredit integer

 

  • status - kod odpowiedzi
  • pointsAvailable - liczba dostępnych do wykorzystania punktów
  • pointsBlocked - liczba zablokowanych punktów (w wyniku zaplanowania wysyłki)

 

KodOpis
300 Konto nie jest przystosowane do korzystania z tej wersji API

Konwertowanie wiadomości

 

Wiadomość przy wysyłce jest konwertowana do standardu GSM, a następnie obliczana jest liczba wiadomości składowych oraz koszt realizacji takiej wysyłki. Konwersja taka odbywa się poprzez wywołanie metody convertMessage

 

Przykładowy kod PHP

View source
<?php
 require_once('Client.php');
 
 $promoSms = new \PromoSms\Soap\Client();
 $auth = new \PromoSms\Soap\Authentication('login@example.com', 'secretPassword');
 
 $response = $client->convertMessage(
 $auth,
 new PromoSms\Soap\ConvertMessageRequest(
 'W Mińsku lżą naftę Jóź. Gość brzydł. Pech!', // text
 false, // specialChars
 true, //longSms
 1, //smsType
 'PL', // countryCode
 null, //countryPrefix
 null //countryName
 )
 );
 
 if ($response->status < 100) {
 echo 'Wiadomość po konwersji: ' . $response->text . PHP_EOL 'Liczba znaków: ' . $response->charsNumber . PHP_EOL 'Liczba wiadomości składowych: ' . $response->smsParts . PHP_EOL 'Koszt wysyłki: ' . $response->points . PHP_EOL ; } else {
 echo 'Wystąpił błąd: ' . $response->status . PHP_EOL;
 }

 

Definicja metody

View source
ConvertMessageResponse convertMessage (
 Authentication authentication, 
 ConvertMessageRequest request 
 )

 

Definicja klasy ConvertMessageRequest
PoleTypWymagane
text string tak
specialChars boolean tak
longSms boolean nie (domyślnie true)
smsType integer nie
countryCode string nie
countryPrefix string nie
countryName string nie

 

  • text - treść wiadomości, na podstawie której ma być obliczona liczba znaków oraz liczba SMSów składowych
  • specialChars - jeżeli parametr przyjmie wartość true, wówczas znaki specjalne są dozwolone w wiadomości i nie zostaną zastąpione odpowiednikami w znakach standardowych. Jeżeli natomiast zostanie ustawiona wartość false, wówczas wszelkie znaki specjalne zostaną przekonwertowane i dopiero wówczas zostanie obliczona długość wiadomości i liczba SMSów składowych.
  • longSms - jeżeli pole to przyjmie wartość true, wiadomość zostanie przycięta do długości jednej wiadomości sms.
  • smsType - rodzaj wiadomości SMS. Jeżeli pole to, wraz z jednym z pól countryCode / countryPrefix / countryName nie są puste, w odpowiedzi zostanie zawarty koszt wysłania tej wiadomości do pojedynczego adresata
    • 0 - FlashSMS
    • 1 - EkoSMS
    • 3 - MaxSMS
    • 4 - FastSMS
  • countryCode - kod kraju odbiorcy w postaci dwóch liter
  • countryPrefix - prefiks kraju odbiorcy
  • countryName - nazwa kraju odbiorcy

 

Definicja klasy ConvertMessageResponse
PoleTyp
status integer
charsNumber integer
smsParts integer
text string
points float

 

  • status - kod odpowiedzi
  • charsNumber - łączna liczba znaków wiadomości
  • smsParts - liczba SMSów składowych
  • text - treść wiadomości. Jeżeli w parametrach wejściowych bSpecialChars przyjęło wartość false, to wówczas zostanie tutaj zwrócona nie oryginalna treść wiadomości, lecz wiadomość przekonwertowana
  • points - obliczony koszt wysyłki (jeżeli w żądaniu określono typ wiadomości oraz kraj wysyłki)

 

KodOpis
100 Nie podano treści
101 Nie podano typu wiadomości SMS
200 Zbyt długa wiadomość (nie mieści się w ramach 4 wiadomości składowych)
201 Podano różne kraje wysyłki
202 Podany kraj wysyłki nie istnieje
300 Wysyłka tego typu wiadomości do podanego kraju jest niedostępna

Sprawdzanie poprawności numerów

 

Metoda validateNumbers umożliwia sprawdzanie poprawności numeru pod względem składniowym. Sprawdzane jest więc, czy np. numer 531100112 ma poprawną formę i jest możliwym numerem.

 

Przykładowy kod PHP

View source
<?php
 require_once('Client.php');
 
 $promoSms = new \PromoSms\Soap\Client();
 $auth = new \PromoSms\Soap\Authentication('login@example.com', 'secretPassword');
 
 $response = $promoSms->validateNumbers(
 $auth,
 new \PromoSms\Soap\ValidateNumbersRequest(
 '48', // countryPrefix
 array('504304204') // numbers
 )
 );
 if ($response->status < 100) {
 $number = $response->numbers[0]; if ($number->isValid) { echo 'Numer ' . $number->formatted . ' jest poprawny' . PHP_EOL; } else { echo 'Number' . $number->original . ' numer jest niepoprawny' . PHP_EOL; } } else {
 echo 'Wystąpił błąd: ' . $response->status . PHP_EOL;
 }

 

Definicja metody

View source
ValidateNumbersResponse validateNumbers (
 Authentication authentication, 
 ValidateNumbersRequest request 
 )

 

Definicja klasy ValidateNumbersRequest
PoleTypWymagane
countryPrefix string tak
numbers Vector tak

 

  • countryPrefix - prefiks kraju z którego inicjowane jest połączenie. Dla przykładu, jeżeli jest to 48, to następujące numery są traktowane jako numery polskie: 512345678, 48512345678, +48512345678, w dodatku jest to ten sam numer zapisany w różny sposób. Jeżeli natomiast pole to przyjmie wartość 49, to tylko ostatni z przykładów jest potraktowany jako numer polski.
  • numbers - tablica/wektor numerów telefonów. Jeżeli numer posiada inny prefiks kraju niż określony w polu countryPrefix, należy użyć symbolu + (plus)

 

Definicja klasy ValidateNumbersResponse
PoleTyp
status integer
numbers Vector

 

  • status - kod odpowiedzi
  • numbers - tablica/wektor ze szczegółowymi informacjami o numerze telefonu

 

KodOpis
012 (110) Niektóre z podanych numerów są niepoprawne
102 (210) Wszystkie podane numery są niepoprawne
100 Nie podano ani jednego numeru telefonu

 

Definicja klasy Number
PoleTyp
originalNumber string
isValid boolean
isValidForRegion boolean
probablyExists boolean
countryPrefix string
countryCode string
formatted string
type integer

 

  • originalNumber - postać w jakiej numer został podany w żądaniu
  • isValid - flaga określająca, czy numer jest poprawny
  • isValidForRegion - flaga określająca, czy numer należy do podanej strefy prefiksowej
  • probablyExists - flaga określająca, czy numer jest prawdopodobnie prawdziwy
  • countryPrefix - prefiks kraju
  • countryCode - kod kraju w postaci dwóch liter
  • formatted - numer telefonu z prefiksem kraju
  • type - typ numeru telefonu:
    • 0 - Numer stacjonarny
    • 1 - Numer komórkowy
    • 2 - Numer stacjonarny lub komórkowy
    • 3 - Darmowy numer (np. numer typu 800...)
    • 4 - Number o podwyższonej płatności
    • 5 - Koszt za połączenie jest współdzielony między odbiorcą i nadawcą (np. numer typu 801...)
    • 6 - Numer VoIP
    • 7 - Numer osobisty, możliwe że jest równocześnie komórkowy jak i stacjonarny (patrz: http://en.wikipedia.org/wiki/Personal_Numbers )
    • 8 - Pager
    • 9 - tzw. Universal Access Numbers lub Company Numbers (Jeden numer firmowy, ale połączenie może być odpowiednio przełączane)
    • 10 lub -1 - Numer niepoprawny lub inny, niezidentyfikowany rodzaj numeru

 

Uwaga! Metoda validateNumbers sprawdza numer pod kątem semantycznym. Nie jest to sprawdzenie numeru u operatora!

 

Dodawanie kontaktów

 

SOAP API umożliwia dodawanie kontaktów do Książki Adresowej za pomocą metody addContacts

 

Przykładowy kod PHP

View source
<?php
 require_once('Client.php');
 
 $promoSms = new \PromoSms\Soap\Client();
 $auth = new \PromoSms\Soap\Authentication('login@example.com', 'secretPassword');
 
 $response = $promoSms->addContacts(
 $auth,
 new \PromoSms\Soap\AddContactsRequest(
 array( new \PromoSms\Soap\Contact( '504304204', // phone 'PromoSMS', // name ) ), array('Grupa testowa'), // groups true // createGroupsIfNotExist )
 );
 if ($response->status < 100) {
 echo 'Dodano następującą liczbę kontaktów: ' . $response->contactsCount . PHP_EOL;
 } else {
 echo 'Wystąpił błąd: ' . $response->status . PHP_EOL;
 }

 

Definicja metody

View source
AddContactsResponse addContacts (
 Authentication authentication, 
 AddContactsRequest request 
 )

 

Definicja klasy AddContactsRequest
PoleTypWymagane
contacts Vector tak
groups Vector nie
createGroupsIfNotExist boolean nie (domyślnie false)

 

  • contacts - tablica/wektor obiektów typu Contact
  • groups - tablica/wektor identyfikatorów grup kontaktów
  • createGroupsIfNotExist - flaga określająca czy utworzyć nową grupę w przypadku gdy podana w polu groups wartość nie istnieje jeszcze w systemie

 

Definicja klasy Contact
PoleTypWymagane
phone string tak
name string nie
firstName string nie
lastName string nie
customField1 string nie
customField2 string nie
customField3 string nie
customField4 string nie
customField5 string nie
customField6 string nie

 

  • phone - numer telefonu
  • name - nazwa kontaktu. Domyślnie przyjmuje tą samą wartość co pole phone
  • firstName - imię
  • lastName - nazwisko
  • customField1 - customField6 - dodatkowe pola, które mogą zostać użyte do wysyłki spersonalizowanej

 

Definicja klasy AddContactsResponse
PoleTyp
status integer
contactsCount integer

 

  • status - kod odpowiedzi
  • contactsCount - liczba dodanych kontaktów

 

KodOpis
100 Nie podano kontaktów
101 Brak numeru telefonu w kontakcie
200 Niepoprawne numery telefonów
300 Konto nie ma ustalonego domyślnego kraju wysyłki


Import kontaktów z pliku CSV


Przesyłanie załączników odbywa się za pomocą metody HTTP Multipart. Używając załączonej biblioteki, można załączyć plik używając metody \PromoSms\Soap\Client::addUploadFile(string $path, string $originalFilename = null) (jak w załączonym przykładzie)

 

Przykładowy kod PHP

View source
<?php 
 
 
require_once('Client.php');
 
 
$promoSms = new \PromoSms\Soap\Client();
$auth = new \PromoSms\Soap\Authentication('login@example.com';, 'secretPassword');
 
 
$promoSms->addUploadFile('./contacts.csv');
 
 
$response = $promoSms->importCsv(
$auth,
new \PromoSms\Soap\ImportCsvRequest(
true, // ignoreFirstRow
array('Nowa grupa'), // groups
true, // createGroupsIfNotExist
false, // createNewGroup
array('number', 'name', 'custom1'), // columns
';', // delimiter
'"', // enclosure
1 // mode
)
);
 
 
if ($response->status < 100) {
echo 'Import kontaktów przebiegł pomyślnie.' . PHP_EOL;
echo 'Liczba dodanych numerów: ' . $response->contactsCount . PHP_EOL;
} else {
echo 'Wystąpił błąd: ' . $response->status . PHP_EOL;
}
 
 

 

Plik contacts.php

View source
"number";"name";"foot size"
"48500000001";"Caroline";38
"48500000002";"Adam";42
"48500000003";"Bill";41

 



Definicja klasy ImportCsvRequest


PoleTypWymagane
ignoreFirstRow boolean nie (domyślnie false)
groups Vector nie
createGroupsIfNotExist boolean nie (domyślnie false)
createNewGroup boolean nie (domyślnie false)
columns Vector nie
delimiter character nie
enclosure character nie
mode int nie


 

  • ignoreFirstRow - parametr określający, czy pierwszy wiersz ma zostać zignorowany (często pierwszy wiersz zawiera tytuły kolumn)
  • groups - nazwy grup, do których mają zostać przypisane kontakty
  • createGroupsIfNotExist - flaga wskazująca na to, czy należy utworzyć grupy, których nazwy zostały wskazane w poprzednim argumencie, a te nie istnieją w systemie
  • createNewGroup - wartość, której ustawienie spowoduje, że zostanie automatycznie utworzona grupa kontaktów na podstawie nazwy pliku oraz znacznika czasowego
  • columns - wektor kolumn - wskazuje na kolejność kolejnych pól w wierszu. Jako elementy zbioru, należy użyć poniższych wartości (pola mogą być wykorzystywane do zlecania spersonalizowanej wysyłki z panelu). Jeśli parametr columns nie jest przekazany, system próbuje sam przypisać odpowiednie kolumny
    • number - numer telefonu
    • name - nazwa kontaktu
    • firstName - imię
    • lastName - nazwisko
    • custom1 - własne pole nr 1
    • custom2 - własne pole nr 2
    • custom3 - własne pole nr 3
    • custom4 - własne pole nr 4
    • custom5 - własne pole nr 5
    • custom6 - własne pole nr 6
    • customContent - treść wiadomości
  • delimiter - znak oddzielający poszczególne pola w pliku (np. przecinek lub średnik)
  • enclosure - ogranicznik pola (np. znak cudzysłowu)
  • mode - tryb działania importera
    • 1 - zapis kontaktów
    • 2 - podgląd działania bez zapisu
    • 3 - zapis kontaktów wraz ze zwróceniem dodanych kontaktów


Definicja klasy ImportCsvResponse


PoleTyp
status integer
contactsCount integer
invalidNumbers integer
columns Vector
csv Vector<Vector>
newGroupName string


  • status - kod odpowiedzi
  • contactsCount - liczba poprawnych numerów
  • invalidNumbers - liczba niepoprawnych numerów
  • columns - wektor wskazujący na kolejność kolumn w wyniku
  • csv - macierz zawierająca kontakty (jeśli wybrano tryb 2 lub 3)
  • newGroupName - nazwa nowo utworzonej grupy (jeśli włączono opcję createNewGroup)


Kody odpowiedzi metody importCsv


KodOpis
100 Brak kontaktów w załączonym pliku
101 Nie znaleziono kolumny z numerem telefonu
102 W co najmniej jednym wierszu brakuje numeru telefonu we wskazanym polu
200 W co najmniej jednym wierszu numer telefonu jest niepoprawny
201 Niepoprawny plik przekazanego pliku (wymagany jest plik csv)
300 Nie ustawiono domyślnego kraju wysyłki


Wysyłanie wiadomości MMS




 

Przykładowy kod PHP

View source
<?php 
 
 
require_once('Client.php');
 
 
$promoSms = new \PromoSms\Soap\Client();
$auth = new \PromoSms\Soap\Authentication('login@example.com';, 'secretPassword');
 
 
 
$promoSms->addUploadFile('./image.jpg');
 
 
$response = $promoSms->sendMms(
 $auth,
 new \PromoSms\Soap\SendMmsRequest(
 array(
 new \PromoSms\Soap\MultimediaMessage(
 'Wiadomość testowa', // subject
 array('504304204') // recipients
 )
 )
 )
);
 
 
if ($response->status < 100) {
 echo 'Wiadomość została wysłana. Kosz wysyłki: ' . $response->points . PHP_EOL;
} else {
 echo 'Wystąpił błąd: ' . $response->status . PHP_EOL;
}
 
 

 

Definicja metody

View source
SendMmsResponse sendMms(
Authentication authentication,
SendMmsRequest request
)

 



Przesyłanie załączników odbywa się za pomocą metody HTTP Multipart. Używając załączonej biblioteki, można załączyć plik używając metody \PromoSms\Soap\Client::addUploadFile(string $path, string $originalFilename = null) (jak w załączonym przykładzie)



Definicja klasy SendMmsRequest


PoleTypWymagane
messages Vector tak
returnRecipientResults boolean nie (domyślnie false)


  • messages - tablica/wektor obiektów typu MultimediaMessage
  • returnRecipientResults - flaga określająca, czy w obiekcie odpowiedzi mają się znajdować szczegóły dotyczące każdego adresata


Definicja klasy MultimediaMessage


PoleTypWymagane
subject string tak
recipients Vector tak
date integer nie
deliveryUrl string nie
userIndexes Vector nie


 

  • subject - temat wiadomości - nie może być dłuższy niż 40 znaków
  • recipients - tablica/wektor odbiorców wiadomości. W tablicy stringów mają znajdować się więc numery telefonów odbiorców wiadomości (każdy element tablicy to kolejny odbiorca)
  • date - znacznik czasowy określający moment kiedy wiadomość ma zostać wysłana (unixowy znacznik czasowy wyrażony w sekundach)
  • deliveryUrl - adres URL serwera użytkownika, na który mają być przekazywane raporty dostarczenia wiadomości. W adresie URL mogą być podane następujące zmienne specjalne, które zostaną zastąpione odpowiednią wartością przez system podczas przesyłania raportu na serwer klienta:
    • %smsID - ID wysłanej wiadomości
    • %timestamp - data raportu w postaci unixowego znacznika czasu
    • %number - numer na jaki została wysłana wiadomość
    • %report - ID raportu (1 oznacza dostarczone)
    • %ownID - identyfikator własny użytkownika
  • userIndexes - parametr pozwala użytkownikowi zdefiniować własne identyfikatory wiadomości. Liczba elementów tablicy/wektora musi być równa liczbie zdefiniowanych odbiorców wiadomości. Wówczas każdej wiadomości, będzie przyporządkowany kolejny element z tej tablicy. Możliwe jest również zdefiniowanie jednego elementu dla tej tablicy/wektora, aby wszystkim wysłanym wiadomościom był przypisany ten sam identyfikator


Definicja klasy SendMmsResponse


PoleTyp
status integer
points float
sentMmsCount integer
contentIds Vector
recipientResults Vector


 

  • status - kod odpowiedzi
  • points - koszt zrealizowanej wysyłki (wyrażony w punktach)
  • sentMmsCount - liczba pomyślnie wysłanych wiadomości
  • contentIds - wektor identyfikatorów treści wysyłki
  • recipientsResults - wektor obiektów typu RecipientResult (lub null jeżeli nie ustawiono parametru wejściowego returnRecipientResults na true)


Definicja klasy RecipientResult jest taka sama jak dla metody sendSms.



Kody odpowiedzi metody sendMms


KodOpis
100 Nie podano adresatów wysyłki
101 Nie podano pola nadawcy
102 Nie podano załączników
200 Wszystkie podane numery telefonów są niepoprawne
201 Nazwa nadawcy jest za długa
202 Nie można wysłać wiadomości w przeszłość
203 Liczba własnych identyfikatorów jest niezgodna z liczbą odbiorców
204 Temat wiadomości jest zbyt długi
205 Przekroczono maksymalny rozmiar
206 Jedna wysyłka zawiera adresatów z różnych krajów
300 Stan konta nie pozwala na zrealizowanie wysyłki
301 Nazwa nadawcy nie została zarejestrowana
302 Nie można wysłać tego typu wiadomości do wybranego kraju
303 Konto nie zostało przystosowane do korzystania z tej wersji API


Sprawdzanie HLR

 


 

Przykładowy kod PHP

View source
<?php 
 
 
require_once('Client.php');
 
 
$promoSms = new \PromoSms\Soap\Client();
$auth = new \PromoSms\Soap\Authentication('login@example.com';, 'secretPassword');
 
 
$response = $promoSms->hlr(
 $auth,
 new \PromoSms\Soap\HlrRequest(
 array('48500000001', '48500000002'), // numbers
 'http://example.com?hlr-callback.php' // callbackUrl
 )
);
 
 
if ($response->status < 100) {
 echo 'Pomyślnie zlecono sprawdzenie operatorów.' . PHP_EOL;
} else {
 echo 'Wystąpił błąd: ' . $response->status . PHP_EOL;
}
 
 

 

hlr-callback.php

View source
 <?php
 
 
 
$post = $_POST;
 
$out = ‘’;
 
 
 
foreach ($post as $number) {
 
    if ($number[‘status’] === ‘OK’) {
 
        $out .= ‘Numer:. $number[‘number’]
 
            . ‘ należy do sieci:. $number[‘mcc’] ./. $number[‘mnc’] . PHP_EOL
 
        ;
 
    }
 
}
 
 
file_put_contents(‘hlr-checks.txt’, $out);

 



Definicja klasy HlrRequest


PoleTypWymagane
numbers Vector tak
callbackUrl string tak


 

  • numbers - wektor numerów telefonów do sprawdzenia
  • callbackUrl - adres, na który zostaną przekazane wyniki sprawdzenia


Definicja klasy HlrResponse


PoleTyp
status integer
numbers Vector


 

  • status - kod operacji
  • numbers - tablica obiektów zawierających informację o statusie przekazania do sprawdzenia


Definicja klasy HlrNumber


PoleTyp
id integer
number string
status integer


 

  • id - identyfikator sprawdzenia numeru
  • number - numer telefonu, którego dotyczy sprawdzenie
  • status - kod przekazania do sprawdzenia
    • 0 - poprawnie przekazano
    • 200 - numer jest niepoprawny pod względem składniowym
    • 201 - nie udało się przekazań numeru do sprawdzenia


Kody odpowiedzi metody hlr


KodOpis
100 Nie podano żadnego numeru
200 Wszystkie podane numery są niepoprawne
300 Brak wystarczających środków na zrealizowanie sprawdzenia


Callback url:

Po sprawdzeniu numerów, następuje przekazanie wyników na wskazany adres metodą POST. Przekazane wyniki mają postać tablicy, której każdy element jest tablicą zawierającą poniższe indeksy:

 

  • id - identyfikator sprawdzenia numeru
  • number - numer poddany sprawdzeniu
  • mcc - identyfikator kraju
  • mnc - identyfikator operatora
  • info - nazwa operatora
  • status - status sprawdzenia
  • date - data dokonania sprawdzenia
  • belongs_to_network_since - czas od kiedy numer należy do sieci
  • ported - czy numer został przeniesiony
  • ported_from - z jakiej sieci nastąpiło przeniesienie