FreecoNet API 2.0

Transkrypt

FreecoNet API 2.0

FreecoNet RestAPI
ver.2.04.01
Autorzy:
M.Szymański, M.Rutkowski, Ł.Umbras-Nichnerowicz
Data: 2009-7-22
Strona 1 z 47
SPIS TREŚCI
1 HISTORIA ZMIAN..................................................................................3
2 WSTĘP.......................................................................................................5
3 OPIS UŻYCIA API...................................................................................5
3.1 SKŁADNIA WYWOŁANIA FUNKCJI Z API.........................................................................................................................................6
3.2 UWIERZYTELNIANIE...................................................................................................................................................................6
3.2.1 Metoda oparta o token.................................................................................................................................................7
3.2.2 Metoda oparta o szyfrowanie parametrów żądania.....................................................................................................9
3.2.2.1 Przykład użycia szyfrowania..................................................................................................................................................9
3.2.2.2 Generowanie wartości do pola encData................................................................................................................................13
3.2.3 Porównanie metod autoryzacji...................................................................................................................................16
3.2.3.1 Metoda oparta o token..........................................................................................................................................................16
3.2.3.2 Metoda oparta o szyfrowanie parametrów żądania...............................................................................................................16
3.3 OBSŁUGA BŁĘDÓW...................................................................................................................................................................17
4 OPIS FUNKCJI API.................................................................................18
4.1 FUNKCJE WSPÓLNE DLA API USER, API PARTNER, API CRM.....................................................................................................18
4.1.1 getToken......................................................................................................................................................................18
4.1.2 checkToken..................................................................................................................................................................19
4.1.3 encryptPGP ...............................................................................................................................................................20
4.1.4 invalidateToken...........................................................................................................................................................20
4.1.5 getVersion .................................................................................................................................................................21
4.1.6 uploadFile ................................................................................................................................................................22
4.1.7 deleteFile ..................................................................................................................................................................22
4.2 FUNKCJE MODUŁU API USER...................................................................................................................................................23
4.2.1 getGroupFinAccountInfo............................................................................................................................................23
4.2.2 makeCall.....................................................................................................................................................................24
4.2.3 getBillingCount ..........................................................................................................................................................25
4.2.4 getBilling ...................................................................................................................................................................27
4.2.5 sendFax......................................................................................................................................................................30
4.2.6 getFaxCurrentCount...................................................................................................................................................30
4.2.7 getFaxSentCount........................................................................................................................................................31
4.2.8 getFaxReceivedCount.................................................................................................................................................32
4.2.9 getFaxSent..................................................................................................................................................................33
4.2.10 getFaxReceived .......................................................................................................................................................35
4.2.11 getFaxCurrent .........................................................................................................................................................36
4.2.12 StartMassDial..........................................................................................................................................................38
4.2.13 getMassDialCurrentCount......................................................................................................................................39
4.2.14 getMassDialCalledCount........................................................................................................................................40
4.2.15 getMassDialCurrent................................................................................................................................................41
4.2.16 cancelMassDialCurrent...........................................................................................................................................42
4.2.17 getMassDialCalled..................................................................................................................................................43
4.2.18 deleteMassDialCalled.............................................................................................................................................45
4.2.19 restartMassDialCalled............................................................................................................................................46
4.2.20 getRegistrationStatus................................................................................................................................................47
5 OPŁATY....................................................................................................47
Strona 2 z 47
1 Historia zmian
Data
2008-11-07
2008-11-18
2008-11-22
2008-12-10
Wersja
dokumentu
1.00.00
1.01.00
1.01.01
1.01.02
2008-12-10
1.01.03
2008-12-19
2009-02-24
1.01.04
2.00.00
2009-06-22
2.01.00
2009-06-23
2.02.00
2009-06-23
2.03.00
2009-07-02
2.03.01
2009-07-08
2.04.00
2009-07-22
2.04.01
Opis
Pierwsza oficjalna wersja dokumentu
Dodanie funkcji invalidToken
Drobne poprawki treści
Dodanie informacji, że checkToken nie zmniejsza licznika użyć
tokena.
Dodanie funkcji getVersion. Zmiana numeracji wersji API z wersji
platformy na wersje API
Drobne poprawki w opisie szyfrowania
• Wartości w odpowiedzi umieszczane są w elementach a nie
atrybutach XML
• Wprowadzenie w wiadomości zwrotnej (XML) sekcji
nazwy funkcji. Sekcja <errors> może znajdować się w
sekcji <nazwa funkcji> albo poza tą sekcją.
• Rozdział API na moduł Partner/User/CRM
• funkcja makeCall umożliwia zestawienie połączenia
między dwoma numerami bez używania usługi 'Zestaw
połączenie'. Uproszczone wywołanie usługi nie pozwala na
używanie zaawansowanych funkcjonalności usługi 'Zestaw
połączenie' takich jak białe/czarne list numerów czy maski
czasowe.
• Funkcje do obsługi wirtualnego faksu
• Funkcje obsługi MassDial
• getVersion - zmiana nazwy parametrów wejściowych
• authSystem – nowe pole określające na jaki system
przebiega uwierzytelnianie.
• Usunięcie parametru userDomain z żądań. Parametr ten
jest ustawiany automatycznie na podstawie adresu URL
• Funkcja getToken zwraca błąd invalidCredentialsw
przypadku błędnych danych uwierzytelniających
Dodanie możliwości pobrania kolumny z identyfikatorem kampanii
MassDial (batchId) dla funkcji getMassDialCurrent oraz
getMassDialCalled
Dodanie do funkcji startMassDial kodu błędu
invalidPresentationNum
Dodanie do funkcji sendFax / startMassDial parametru
campaignName
Poprawienie w dokumentacji opisu parametrów TRUE/FALSE.
Zamiana na true/false.
Dodanie błędu functionCallLimitsExceeded, dodanie możliwości
pobrania kolumny z identyfikatorem kampanii wysyłki faksu
(batchId) dla funkcji getFaxCurrent oraz getFaxSent
Poprawka parametru authSystem dla wszystkich funkcji
faksowych, usunięcie parametru fromNum z funkcji getFaxSent
oraz getFaxCurrent, aktualizacja parametrów orderBy w funkcji
getFaxReceived
2 Wstęp
Przedstawione w poniższym dokumencie API pozwala na integrację zewnętrznych systemów
informatycznych z platformą FreecoNet. Możliwości użycia API są nieograniczone, przykładem
może być wbudowanie funkcjonalności nawiązywania połączeń telefonicznych na stronach systemu
CRM, czy też w portalach społecznościowych, możliwość wyświetlenia stanu konta w aplikacji
standalone czy toolbarze w przeglądarce, czy też pobranie spisu połączeń do systemu kontroli
połączeń.
Aktualna wersja dokumentu opisuje wyłącznie FreecoNet RestAPI ver.2.x oparte o wymianę
parametrów poprzez popularny mechanizm REST (Representional State Transfer http://en.wikipedia.org/wiki/Representational_State_Transfer) bazujący na żądaniach HTTPS
GET/POST. Użycie REST pozwala użyć API z każdego języka programowania, który posiada
obsługę HTTPS między innymi PHP, Java, JavaScript czy ActionScript jak również z każdego
systemu operacyjnego.
API zostało podzielone na trzy moduły:
•
moduł partnerski (API Partner) – udostępniający funkcjonalność panelu partnerskiego
•
moduł użytkownika (API User) – udostępniający funkcjonalność panelu użytkownika,
•
moduł CRM (API CRM) – udostępniający funkcjonalność panelu CRM platformy
Należy zaznaczyć, że obecna wersja API ulega ciągłej rozbudowie, osoby chcące skorzystać z API
modułu partnerskiego i użytkownika w systemach produkcyjnych proszone są o zapoznanie się z
najnowszą dokumentacją dostępną pod adresem http://techblog.freeconet.pl/. Dokumentacja funkcji
modułu CRM dostępna jest wyłącznie dla firm używających systemu Carrier-eX .
3 Opis użycia API
Jak już zostało wspomniane we wstępie komunikacja między klientem a platformą FreecoNet
oparta jest o REST, czyli o standardowy mechanizm żądań HTTP. W zależności od potrzeby można
użyć metodę GET albo POST obie metody są obsługiwane po stronie serwera w ten sam sposób i
zapewniają taki sam stopień bezpieczeństwa przesyłania danych.
Poniżej przykład, który pozwoli na szybkie zaznajomienie się z metodą korzystania z API.
Jednym z prostszych przykładów użycia API modułu użytkownika jest wywołanie funkcji
pobierającej stan konta. Poniżej przykład takiego wywołania w oparciu o żądanie GET
wywoływany dla konta demonstracyjnego o loginie apidemo.
https://apiuser.freeconet.pl/RestAPI/V2/execute?
fun=getGroupFinAccountInfo&tokenStr=815aa4d11b51ffc09b251da76a7bac81283a002442
ac64efc03162922838fb51&sig=86cee83a1d14bf7eb8c7b5f6e94a7dd4
W odpowiedzi klient otrzymuje XML w postaci:
<?xml version=”1.0”?>
<response>
<getGroupFinAccount>
<credit>0</credit>
<debit>0</debit>
<creditLimit>0</creditLimit>
<minusCreditDate></minusCreditDate>
</getGroupFinAccount>
</response>
5 z 47
Analizując XML widzimy, że stan konta, kwota należności i limit dla grupy to 0zł. Kwota inna niż
0 złotych dla należności i limitu występują tylko dla grup, które rozliczają się z FreecoNet w
oparciu o postpaid. Jako, że w odpowiedzi nie wystąpił tag <errors> oznacza, że operacja
przebiegła pomyślnie.
Jak widać wywołanie funkcjonalności z FreecoNet RestAPI jak również interpretacja wyników nie
jest skomplikowane i nie sprawia problemu osobie z podstawową znajomością zagadnień
technologii internetowych.
Wymagania
Jedynym wymogiem jest to żeby wybrany język umożliwiał generacje żądań GET albo POST po
protokole HTTPS.
API uwierzytelnia żądania korzystając z kont użytkownika systemu FreecoNet, tak więc należy
posiadać przynajmniej jedno konto w serwisie FreecoNet, osoby które takiego konta nie posiadają
mogą go założyć poprzez stronę https://wizard.freeconet.pl.
3.1 Składnia wywołania funkcji z API
W celu wywołania funkcji z API należy stworzyć URL składający się z paru obowiązkowych
części.
https://apiuser.freeconet.pl/RestAPI/V2/execute?encData=23ffsdf..
1
2
3
4
5
Gdzie:
1 - komunikacja odbywa się po szyfrowanym protokole HTTPS
2 –część URL, adres pod którym umieszczone jest API.
3 - część URL, pod którą umieszczone są zasoby FreecoNet RestAPI. Dla wszystkich funkcji
zaprezentowanych w tym dokumencie ta część przyjmuje wartość RestAPI
4 – część definiująca wersję API, z której chcemy skorzystać
5 – parametry wywoływanej funkcji
Adresy dla modułów są następujące:
https://apiuser.freeconet.pl - dla modułu użytkowania panelu
https://apipartner.freeconet.pl - dla modułu partnera
https://apicrm.freeconet.pl - dla modułu CRM
3.2 Uwierzytelnianie
W celu upewnienia się, że funkcje serwisu będą wywoływane przez uprawnione osoby/systemy,
zostały wprowadzone dwie metody uwierzytelniania, pierwsza oparta o token wystawiany przez
system i podpis, druga oparta o zaszyfrowanie wybranych parametrów żądania. Przy
uwierzytelnianiu w module użytkownika (API User) należy podać system w którym chcemy się
uwierzytelnić , podajemy to w parametrze authSystem.
Do wyboru mamy systemy:
• USER – użytkownik panelu FreecoNet
• FAXV – użytkownik panelu faksów
• MASD – użytkownik panelu MassDial
Jeśli parametr nie jest podany w żądaniu, domyślnie przyjmowana jest wartość USER.
6 z 47
3.2.1 Metoda oparta o token
W tej metodzie uwierzytelniania przed wykonaniem właściwej operacji system kliencki musi
pobrać token. Czas ważności tokenu ustalany jest poprzez podanie wartości w parametrze
validPeriod. Każdorazowe użycie tokena w wywoływanych funkcjach przedłuża ważność
tokena o początkowo podaną wartość.
Pobranie tokena realizowane jest za pomocą funkcji getToken. Poniżej przykład pobrania tokena
dla konta apidemo dla którego ustawione jest hasło apidemo.
fun=getToken&userName=apidemo&password=apidemo&authSystem=USER&validPeriod=100
00
Gdzie:
fun – wywołujemy funkcje pobierającą token
userName – to login konta przez które się logujemy do systemu (poprzez te konto będą
realizowane wszystkie operacje np. dzwonienie)
password – hasło dla konta. Jest to te samo hasło które użytkownik używa do logowania się do
panelu
authSystem – identyfikator systemu w którym chcemy się uwierzytelnić. Dopuszczalne wartości
dla modułu użytkownika (API User) to USER (użytkownika panelu FreecoNet), FAXV –
użytkownik panelu faksów, MASD – użytkownik panelu MassDial. Jeśli parametr nie jest podany w
żądaniu, domyślnie przyjmowana jest wartość USER. Dla modułu partnerskiego i CRM parametru
authSystem nie trzeba ustawiać – domyślnie przybiera wartość PARTNER i CRM. Dla systemów
MassDial i Faks należy odpowiednio rejestrować się na system MASD oraz FAXV, w przeciwnym
przypadku użytkownik otrzyma komunikat błędu.
validPeriod – czas ważności tokenu w sekundach, wartość domyślna to 10s
W przypadku udanego uwierzytelniania otrzymujemy XML w postaci
<response>
<getToken>
<tokenStr>815aa4d11b51ffc09b251da76a7bac81283a002442ac64efc03162922838fb51
</tokenStr>
</getToken>
</response>
Oczywiście wartość pola tokenStr będzie inna przy każdym wywołaniu funkcji getToken. Dla
celów demonstracyjnych przedstawiono token, który będzie używany w dalszej części dokumentu i
którego ważność nie wygasa, tak więc każdy użytkownik może go użyć we własnych testach.
Jeśli operacja nie przebiegnie pomyślnie np. źle podane hasło w sekcji <response> pojawi się
sekcja <errors> (dokładny opis zwracanych wartości umieszczony jest w rozdziale - 3.3 Obsługa
błędów ) np.
<response>
<getGroupFinAccountInfo>
<errors>
<error>
7 z 47
<code>invalidToken</code>
<msg>Token expired or is invalid</msg>
</error>
</errors>
</getGroupFinAccountInfo>
</response>
Mając token możemy stworzyć URL wywołujący określoną funkcjonalność systemu. Załóżmy, że
chcemy pobrać stan konta dla grupy do której należy konto apidemo . W tym celu tworzymy URL.
ac64efc03162922838fb51&sig=86cee83a1d14bf7eb8c7b5f6e94a7dd4
Należy zwrócić uwagę na ostatnią część w URL:
sig=86cee83a1d14bf7eb8c7b5f6e94a7dd4
Jest to podpis przesyłanej wiadomości, który zabezpiecza przed nieautoryzowaną zmianą wartości
żądania.
Podpis
ten
tworzymy
poprzez
policzenie
funkcji
skrótu
MD5
(http://pl.wikipedia.org/wiki/MD5) z ciągu znaków utworzonego z nazwy wywoływanej funkcji,
nazw atrybutów, wartości atrybutów (nie enkodowanych) oraz wartości MD5 z hasła dla konta
(podawane jest MD5 z hasła a nie samo hasło ponieważ w systemie FreecoNet przechowywane jest
hasło w postaci skrótu MD5). MD5 z hasła musi być dodane do końca ciągu dla którego obliczamy
MD5. Kolejność atrybutów/wartości musi być taka sama jak w przesyłanym URL. Przy liczeniu
MD5 nie bierzemy po uwagę atrybutu sig. W naszym przypadku obliczanie podpis będzie
wyglądało następująco (oryginalna wartość hasła to ‘apidemo’):
MD5(‘fungetGroupFinAccountInfotokenStr815aa4d11b51ffc09b251da76a7bac81283a0024
42ac64efc03162922838fb51953a3220084d73ea9948e3046c3c242d’)=
86cee83a1d14bf7eb8c7b5f6e94a7dd4
Pogrubioną czcionką zaznaczone MD5 hasła:
MD5(‘apidemo’)="953a3220084d73ea9948e3046c3c242d"
Uwaga w przypadku przesyłania danych za pomocą GET i równocześnie w POST, do obliczenia
MD5 w tworzonym ciągu podajemy najpierw parametry GET a później z POST.
Podpis ten zabezpiecza nas przed nieautoryzowaną modyfikacją przesyłanych parametrów. Ma to
szczególne znaczenie gdy tworzony URL jest dostępny na stronie WWW wyświetlanej
użytkownikowi końcowemu. Jeśli użytkownik dokona zmian w URL taka zmiana zostanie wykryta
przez funkcje serwisu i operacja nie zostanie wykonana.
UWAGA
Jeśli nazwa atrybutu w przesyłanym żądaniu rozpoczyna się od NS oznacza to, że dany atrybut
jak też jego wartość nie jest brana pod uwagę przy liczeniu podpisu. Jeśli w żądaniu pojawi się
ten sam parametr z i bez NS funkcja zwróci błąd a pole <error> <code> przyjmie wartość
DuplicatedParams . Użycie przedrostku NS pozwala na ustawianie wybranych parametrów
bez obliczania MD5 co ma znaczenie np. w przypadku tworzenia URL po stronie klienta..
W wyniku prawidłowego działania funkcji dostaniemy XML w postaci:
8 z 47
<response>
<credit>0</credit>
<debit>0</debit>
</response>
W wyniku tej operacji ważność tokena ustawiana jest na kolejne 10000 sekund.
3.2.2 Metoda oparta o szyfrowanie parametrów żądania
W tej metodzie nie ma oddzielnego etapu autoryzacji użytkownika, co implikuje że po stronie
serwera nie ma sesji i nie ma możliwości przechowywania wartości w sesji, tak więc przy każdym
wywołaniu musimy przesłać informacje niezbędne do autoryzacji czyli nazwę użytkownika, hasło
dodatkowo ze względów bezpieczeństwa musi być zaszyfrowany identyfikator wywoływanej
funkcji. Wywołanie określonej funkcji z API w najprostszym scenariuszu wymaga jedynie
wywołania URL który jest niezmienny w czasie (oczywiście o ile nie ulegnie zmianie hasło konta),
tak więc można np. taki URL umieścić w emailu albo na statycznej stronie HTML. W przypadku tej
metody nie używamy pola sig czyli podpisywania żądania.
Użycie tej metody najlepiej zaprezentować na przykładzie użycia usługi ’Zestaw Połączenie’.
Usługa ta pozwala na zainicjowanie połączenia między dwoma stronami (np. numerami) poprzez
wysłanie żądania do systemu FreecoNet.
3.2.2.1 Przykład użycia szyfrowania
Załóżmy, że mamy stronę WWW Biura Obsługi Klienta na której jest pole ‘Mój numer’, w którym
można wpisać własny numer i obok pola jest przycisk ‘Rozmowa z konsultantem’. Wpisanie
numeru a później naciśnięcie na przycisk ma spowodować zestawienie połączenia miedzy
telefonem którego numer wpisaliśmy a numerem BOK. Załóżmy, że numer biura obsługi to
0587311999 (w systemie FreecoNet jest to numer demonstrujący działanie usług IVR) a wpisany
numer to 0895277082 (dla testów proponujemy podać swój numer FreecoNet), połączenie ma
zostać zestawione przez konto apidemo , dla którego hasło jest apidemo.
W celu zestawienia takiego połączenia należy w pierwszej kolejności załączyć usługę w panelu
użytkownika (‘KonfiguracjaUsługiDodaj nową usługę’ i wybrać usługę ‘Zestaw połączenie’) i
ustawić jak na poniższym ekranie:
9 z 47
Samo zainicjowanie połączenia następuje po wysłaniu do serwera następujące żądania1
1
2
https://apiuser.freeconet.pl/RestAPI/V2/execute?encData=wcBOA%2F%2FH0yB8UNK7EAP
%2BJtHxfQRr5CYUnCIk4ce4%2FvS%2BVGy6TIucIECuANCV6Z0VfHe%2FSmX%2BJXxx
%0AH504CscfT6SzJVsZmqHVjujsTBl8vZlUc%2F4J1gX6CSSsli67hEFeEOtpYKDbvcI9h5S4uFAppHSS
%0AR0aQkU3QDBNu1dcI49KwUdYse1XDsTwioU6prqQEAIbFfwmh6rxlupMRdtWnsih94N987AbQvhti
%0AoBUk212NHQvdLUa6em2dmd%2BE5S0j5lfFv5WWepJkueG5yoUpi
%2Bg0E9hMck235fJvP755oe7sjzN6%0AA6zv%2BSvipADULgKh7fAjUCwTX6Xoz%2BkHVEiarctV
%2BVKuuE5oO3HABRpTpIrL0pIBA6%2BqotlrXmY%2F%0ANzeRRTgHQGm0oy2Yl%2BW3Mzql7jIJyjj
%2Fs9DIKFVKDZfttoR03lFvQTDTXe0nvbdw4Ohi5uQChVma%0AyNjJCK3zP7nvC9I2sG5vmrsATgb
%2Ff2DJKhcrfPXJt9GBPoSPqPP6v4x0v7YazQKQP%2Fiznm90PQzU%0A%2BgmUpmXltDDSg3%2BmfaSa1N
%2BOdof3BQ%3D%3D%0A%3DPeia&from=0895277082
3
Gdzie:
1 – standardowy adres API User
2 – zaszyfrowany login, hasło konta, które zostanie obciążone kosztami rozmowy i z którego
1
Ze względu, że na koncie testowym jest zerowy stan konta można jedynie podać numer z FreecoNet.
10 z 47
zostanie zestawione połączenie, id serwisu, typ strony Od i ‘numer Do’
3 - numer telefonu wpisany na stronie
Dla uproszenia generacji URL dla tej metody autoryzacji korzystamy z pomocniczego ekranu do
generacji kontrolki usługi ‘Zestaw połączenie’. W tym celu wybieramy w panelu użytkownika
ekran KonfiguracjaUsługi i wybieramy zdefiniowaną usługę ‘Zestaw połączenie’ i przechodzimy
do zakładki ‘kontrolka’. Wpisujemy ustawienia jak na ekranie poniżej:
Po wprowadzeniu danych naciskamy przycisk ‘Generuj’. W wygenerowanym kodzie HTML
11 z 47
odszukujemy sekcje zaczynającą się od https, na zamieszczonym powyżej ekranie zaznaczono na
czerwono interesującą nas sekcje.
Ze względów bezpieczeństwa należy szyfrować te dane które nie mogą się pojawić jawnym tekstem
w żądaniu oraz które nie powinny być zmienione przez użytkownika, parametry takie jak nazwa
konta, domena, hasło i funkcja muszą zawsze być podawane w części szyfrowanej .
Dla naszego przykładu link zawiera następujące dane:
Nazwa pola
Funkcja (fun)
Nazwa konta (userName)
Hasło (password)
Wartość
makeCall
apidemo
apidemo
Zaszyfrowane
TAK
TAK
TAK
System autoryzacji
(authSystem)
USER
TAK
Id usługi (idService)
543452
TAK
Numer do (to)
Typ strony Do (toType)
Typ strony Od
(fromType)
0587311999
N
N
TAK
TAK
TAK
Uwagi
Należy wpisać hasło dla podanego
wyżej użytkownika
Moduł autoryzacji. Jeśli ten
parametr nie zostanie podany
przyjmowana jest wartość USER
Id usługi. Wyświetlane w zakładce
‘konfiguruj’ poniżej nazwy usługi.
Numer BOK na który dzwonimy
Podany może być jedynie numer
Podany może być jedynie numer
Interesujący nas URL jest w postaci:
https://apiuser.freeconet.pl/RestAPI/V2/execute?encData=wcBOA%2F
%2FH0yB8UNK7EAP%2BJtHxfQRr5CYUnCIk4ce4%2FvS%2BVGy6TIucIECuANCV6Z0VfHe%2FSmX
%2BJXxx%0AH504CscfT6SzJVsZmqHVjujsTBl8vZlUc
%2F4J1gX6CSSsli67hEFeEOtpYKDbvcI9h5S4uFAppHSS
%0AR0aQkU3QDBNu1dcI49KwUdYse1XDsTwioU6prqQEAIbFfwmh6rxlupMRdtWnsih94N987AbQvht
i%0AoBUk212NHQvdLUa6em2dmd%2BE5S0j5lfFv5WWepJkueG5yoUpi
%2Ff2DJKhcrfPXJt9GBPoSPqPP6v4x0v7YazQKQP%2Fiznm90PQzU%0A
%2BgmUpmXltDDSg3%2BmfaSa1N%2BOdof3BQ%3D%3D%0A%3DPeia&from=
Tak wygenerowany URL możemy wkleić bezpośrednio do pola adresu w przeglądarce jedynie co
należy zrobić to dodać do URL’a cześć w której definiujemy numer Od. Cały URL z dodaną częścią
będzie wyglądał następująco (dodana część została oznaczona na czerwono)
%2FH0yB8UNK7EAP%2BJtHxfQRr5CYUnCIk4ce4%2FvS%2BVGy6TIucIECuANCV6Z0VfHe%2FSmX
%2BJXxx%0AH504CscfT6SzJVsZmqHVjujsTBl8vZlUc
%2F4J1gX6CSSsli67hEFeEOtpYKDbvcI9h5S4uFAppHSS
%0AR0aQkU3QDBNu1dcI49KwUdYse1XDsTwioU6prqQEAIbFfwmh6rxlupMRdtWnsih94N987AbQvht
i%0AoBUk212NHQvdLUa6em2dmd%2BE5S0j5lfFv5WWepJkueG5yoUpi
%2Ff2DJKhcrfPXJt9GBPoSPqPP6v4x0v7YazQKQP%2Fiznm90PQzU%0A
%2BgmUpmXltDDSg3%2BmfaSa1N%2BOdof3BQ%3D%3D%0A%3DPeia&from=0895277082
Dla typowej sytuacji możemy skorzystać z całego kodu kontrolki wygenerowanego na stronie.
12 z 47
3.2.2.2 Generowanie wartości do pola encData
W poprzednim rozdziale została przedstawiona metoda generowania zaszyfrowanego linku z
użyciem strony do generacji kontrolek dla usługi ‘Zestaw połączenie’. Poniżej zostanie
zaprezentowany opis jak samodzielnie przygotować zawartość pola encData.
Przy przygotowaniu wartości pola encData skorzystaliśmy z popularnego programu do
szyfrowania GnuPg ale oczywiście można użyć ogólnie dostępne biblioteki szyrowania PGP. Warto
zaznaczyć, że do szyfrowania można użyć również funkcji encryptPGP dostępnej w Rest API –
rozdział 4.1.3.
W RestAPI używana jest metody szyfrowania DSA/Elgamal z 1024 bitowym kluczem publicznym
(więcej o DSA/Elgamal i o asymetrycznym szyfrowaniu na stronie
http://pl.wikipedia.org/wiki/Kryptografia_asymetryczna ).
Poniżej klucz publiczny dla Rest API podany w formacie programu GnuPg (http://www.gnupg.org/)
:
-----BEGIN PGP PUBLIC KEY BLOCK----Version: GnuPG v1.4.9 (MingW32)
mQGiBEiN2BARBACiu8YcoZ0fg1/twKRSifKAii0jAPyCKWBCKlTa3F+HAVe4jUHm
8/ZdPauS7a0+AkN/YqiALwM3wJyyCGwWKJPkdGtrjPnWsVIO4jRS0OGDjkHEFUIj
0+TeZk1sU6Hj/HhFtTkapObbUx1P6+8pYEWQoAiZHXv+5f9x1+GMppoeEwCghctl
lkN+mgrj02fpIdLj6JMbl2EEAJAQLc9wlAic6sN5ibhqEtF03hAQRRUuvEiklwKq
anwxfxwEGOBee7vEaxA6B6bDZsTPzkZbKBfBbvd+KH/6j1alltFSL7HjNILEFqsh
9rZxUyFT1GmEdjA0NsQgW3CppEv43crWEK4NibxfLrbkNKwms442zUT3mdL5KUnR
7wfbA/9i7rFPNDcsWi7O+KlNhiIK6X44ogRXkvtKvsHiqTbyhUG8uoyWXG3Y+teD
DSg6RBit/RnLUbO0p0l7shWOv8SZx8Z4xuw5sQVsXFyXPiliYm93WJgpnqHe/jtp
mOyTzMLZk8IeTRxfIAkvBv9O8SvxGTk1Gy7nwxXemgiMV/efjrRJRnJlZWNvbmV0
IFJlc3RBUEkgKEZyZWVjb25ldCBSZXN0QVBJIERFUy9FbGdhbWFsIGtleXMpIDxh
cGlAZnJlZWNvbmV0LnBsPohgBBMRAgAgBQJIjdgQAhsDBgsJCAcDAgQVAggDBBYC
AwECHgECF4AACgkQIix00gUvRyi53QCcD+2vbU9wSTmLSK3IAmt/tEoB/OcAn0FZ
zuoaD8XyNYgbgr51ULE7tXYiuQENBEiN2BAQBACa6OT1G/UNiK4v2eyWqDNG/lSU
3+2wwvUSYKQ6dXYPxc87BZDuLiJjjgkSU7ovqu+Hz/xdAluxhZ8A44/lnhdniyE0
x8aHWXOvBfAnEDEjoYP5xU8i30ohs5cymr3l+FS4PPongyVoSN134cBMpYZW8fyn
XjdvyVFoZ3QCnx1gpwADBQP9FAJgDhgOSs4W/3XV463epf+eiruv5L8qqn1S4CQw
Ci49U3ce9KmNk+NjKVFDD0WLsDYN4+2wKviSGl/bbMmhZOpH/h2dLqhaWYDcX+jV
sh3rYuHb5Oc1gdSrNgTfGGGBZX5/lzDq3kdBc3uWL6V0vf4mIzNoQdBt63fwwsa8
RtSISQQYEQIACQUCSI3YEAIbDAAKCRAiLHTSBS9HKEp7AJ9RidMYO4WJ43N2RMP2
iVtrKXVqdQCeJpf+bNYSFLxZD8AmZ0La+1iCvcw=
=mDNs
-----END PGP PUBLIC KEY BLOCK-----
Klucz ten można również pobrać ze strony :
https://apiuser.freeconet.pl/certificates/RestAPI_public_key_api.gpg
W celu przygotowania pełnego URL’a z wywołaniem należy:
•
pobrać i zainstalować program GnuPg (http://www.gnupg.org/).
•
•
Utworzyć plik RestAPI_public_key_api.gpg i wkleić podany powyżej klucz publiczny.
Dodać klucz publiczny do repozytorium kluczy (tzw.keyring). Pobranie i dodanie klucza
wykonujemy tylko raz po zainstalowaniu GnuPg.
13 z 47
gpg –-import RestAPI_public_key_api.gpg
•
Utworzyć ciąg tekstowy który chcemy zaszyfrować w postaci:
nazwa parametru =warto ść parametru&nazwa parametru=warto ść ...
w naszym przypadku:
fun=makeCall&userName=apidemo&password=apidemo&idService=543452&to=0587311999&
toType=N&fromType=N
Uwaga!!!
Należy zwrócić uwagę, że znaki specjalne dla wartości parametrów muszą być enkodowane tak
jak
to
się
dzieje
gdy
są
zamieszczane
w
URL
(http://www.albionresearch.com/misc/urlencode.php). W poniższych przykładach zastosowano
kodowanie zgodne z RFC1738 (http://www.faqs.org/rfcs/rfc1738) z tą różnicą, że znaki spacji są
kodowane jako znak plusa (+). Inne wartości poza wartościami nie powinny być enkodowane.
W naszym przypadku wartości po enkodowaniu wartości z URLa wyglądają tak samo:
fun=makeCall&userName=apidemo&password=apidemo&idService=543452&to=0587311999&
toType=N&fromType=N
•
Uzyskany tekst zapisujemy w pliku makecall_test.txt i dokonujemy szyfrowania:
gpg –a –-encrypt makecall_test.txt
Poniżej zapis sesji szyfrowania:
C:\Program Files\GNU\GnuPG>gpg -a -e makecall_test.txt
You did not specify a user ID. (you may use "-r")
Current recipients:
Enter the user ID. End with an empty line: [email protected]
gpg: 7C50D2BB: There is no assurance this key belongs to the named user
pub 1024g/7C50D2BB 2008-07-28 FreecoNet RestAPI (FreecoNet RestAPI
DES/Elgamal
keys) <[email protected]>
Primary key fingerprint: 00EF A738 7244 3D7C DE6C 7EAF 222C 74D2 052F 4728
Subkey fingerprint: 63B6 4527 79D2 C479 10E0 32B0 FFC7 D320 7C50 D2BB
It is NOT certain that the key belongs to the person named
in the user ID. If you *really* know what you are doing,
you may answer the next question with yes.
Use this key anyway? (y/N) y
Current recipients:
1024g/7C50D2BB 2008-07-28 "FreecoNet RestAPI (FreecoNet RestAPI DES/Elgamal
keys
) <[email protected]>"
14 z 47
Enter the user ID.
End with an empty line:
C:\Program Files\GNU\GnuPG>
Wynik szyfrowania znajdziemy w pliku makeCall_test.txt.asc:
-----BEGIN PGP MESSAGE----Version: GnuPG v1.4.9 (MingW32)
wcBOA//H0yB8UNK7EAP/RkeYDuYSeANStQi0MadQo5EHkPVNS7uADXkLTYde4Uug7uV6NEzNsnTO
boRQx+48e2lsa4qltYd+RPtfI9TW/JOEhYENwuz1zBTvOw1uX9gUN5gs2yMrOn9anB31wi8i4I0T
UnwfmSczTatc7PTuHUjnH99Zssqcll7NC55LMWkD/0rFdb34/XwoHG20+YDJ9EJ2UDcKiJ1e6I5J
Nmcd3YEElp9xhiS7bV6iYnXpDKi5l7KJKUcTMboGsY7Nvn172/9t88ksb2PyM7JPwa9VQUO6H9Pt
n22VctkBym272lvRDF3nX8BSC8+b5PFlWUKirwYgI+DgTyB1B8Gjsksp4D460pIBQymN5RF8dZp0
8kdozH9izVc98ZRuLFBrS6TtaM5gEj+SritQe3W+2EX7TnwhfrWd68EvQUjFR8XdecpyN/il7ykQ
OY0VXI5nXHqbBxFSLdU/JPYFDTcZiE0FfHpa6bh5ZWQjvSOwFrAIwocOMDcPsMVZOJTKqlha2Xae
nzw5a3hejcdK7dDWZ97CZJ+/PoFO3w==
=bumf
-----END PGP MESSAGE-----
Należy zaznaczyć, że każde wywołanie szyfrowania wygeneruje inną zawartość pliku
makeCall_test.txt.asc co jest sytuacją normalną i wynika ze specyfiki działania
szyfrowania PGP.
•
Z wiadomości wycinamy trzy pierwsze linie jak również ostatnią linie.
•
Następnie należy wykonać URL Encoding (do testów można skorzystać ze strony
http://www.w3schools.com/TAGS/ref_urlencode.asp) na całej zaszyfrowanej wiadomości
Po enkodowaniu dostajemy ciąg:
wcBOA%2F%2FH0yB8UNK7EAP
%2FRkeYDuYSeANStQi0MadQo5EHkPVNS7uADXkLTYde4Uug7uV6NEzNsnTO+boRQx
%2B48e2lsa4qltYd%2BRPtfI9TW
%2FJOEhYENwuz1zBTvOw1uX9gUN5gs2yMrOn9anB31wi8i4I0T+UnwfmSczTatc7PTuHUjnH99Zssq
cll7NC55LMWkD
%2F0rFdb34%2FXwoHG20%2BYDJ9EJ2UDcKiJ1e6I5J+Nmcd3YEElp9xhiS7bV6iYnXpDKi5l7KJKUc
TMboGsY7Nvn172%2F9t88ksb2PyM7JPwa9VQUO6H9Pt+n22VctkBym272lvRDF3nX8BSC8%2Bb5PFl
WUKirwYgI%2BDgTyB1B8Gjsksp4D460pIBQymN5RF8dZp0+8kdozH9izVc98ZRuLFBrS6TtaM5gEj
%2BSritQe3W%2B2EX7TnwhfrWd68EvQUjFR8XdecpyN%2Fil7ykQ+OY0VXI5nXHqbBxFSLdU
%2FJPYFDTcZiE0FfHpa6bh5ZWQjvSOwFrAIwocOMDcPsMVZOJTKqlha2Xae+nzw5a3hejcdK7dDWZ9
7CZJ%2B%2FPoFO3w%3D%3D+%3Dbumf
•
Ostatnim krokiem jest stworzenie pełnego URL’. W naszym przypadku dodajemy jeszcze adres
API oraz parametr, który będzie zmienny czyli from.
%2FH0yB8UNK7EAP
%2FRkeYDuYSeANStQi0MadQo5EHkPVNS7uADXkLTYde4Uug7uV6NEzNsnTO+boRQx
%2B48e2lsa4qltYd%2BRPtfI9TW
%2FJOEhYENwuz1zBTvOw1uX9gUN5gs2yMrOn9anB31wi8i4I0T+UnwfmSczTatc7PTuHUjnH99Zssq
cll7NC55LMWkD
%2F0rFdb34%2FXwoHG20%2BYDJ9EJ2UDcKiJ1e6I5J+Nmcd3YEElp9xhiS7bV6iYnXpDKi5l7KJKUc
TMboGsY7Nvn172%2F9t88ksb2PyM7JPwa9VQUO6H9Pt+n22VctkBym272lvRDF3nX8BSC8%2Bb5PFl
WUKirwYgI%2BDgTyB1B8Gjsksp4D460pIBQymN5RF8dZp0+8kdozH9izVc98ZRuLFBrS6TtaM5gEj
%2BSritQe3W%2B2EX7TnwhfrWd68EvQUjFR8XdecpyN%2Fil7ykQ+OY0VXI5nXHqbBxFSLdU
%2FJPYFDTcZiE0FfHpa6bh5ZWQjvSOwFrAIwocOMDcPsMVZOJTKqlha2Xae+nzw5a3hejcdK7dDWZ9
7CZJ%2B%2FPoFO3w%3D%3D+%3Dbumf&from=0895277082
15 z 47
3.2.3 Porównanie metod autoryzacji
Poniżej zestawienie zalet i wad dwóch wymienionych wyżej metod. Zestawienie pomoże wybrać
najlepsze rozwiązanie dla konkretnego rozwiązania.
3.2.3.1 Metoda oparta o token
•
•
•
•
•
Zalety
Nie trzeba przesyłać loginu i hasła przy każdym wywołaniu funkcji. W przypadku generacji
HTML użytkownik nie widzi identyfikatorów w URL
Duża szybkość tworzenia żądań, jak również duża szybkość obsługi tych żądań po stronie
systemu FreecoNet. Tworzenie wywołań wymaga obliczania funkcji skrótu MD5 dla
wygenerowanego żądania. Obliczanie jest zaimplementowana w większości języków
programowania i wykonywane jest bardzo szybko.
Możliwość użycia tokena w systemach z logowaniem SSO (Single Sign-on
http://en.wikipedia.org/wiki/Single_sign-on ), czyli token może być przekazywany między
różnymi luźno powiązanymi systemami klienta.
Dołączany podpis zabezpiecza przed nieautoryzowaną modyfikacją wywołania
Dynamiczne wygenerowanie żądań np. sprawdzenie stanu kont dla różnych grup wymaga
jedynie użycia funkcji haszującej MD5 przez co jest łatwe do implementacji.
Wady
• Przed wywołaniem funkcji z API trzeba wykonać uwierzytelnianie użytkownika – pobranie
tokena. Przy pobraniu tokena należy podać login i hasło użytkownika.
• Wygenerowany token przy braku aktywności ważny jest określoną ilość sekund, co w
przypadkach długich przerw w interakcji użytkownika z systemem komplikuje obsługę API.
• Brak możliwości ‘osadzania’ wywołań na statycznych stronach HTML.
3.2.3.2 Metoda oparta o szyfrowanie parametrów żądania
•
•
•
•
Zalety
Możliwość osadzenia wywołania funkcji na statycznej stronie HTML, w mailu czy też w
banerze reklamowym.
Nie istnieje problem wygasania ważności tokena.
Możliwość umieszczenia w części zaszyfrowanej parametrów, które nie powinny być
widoczne przez użytkownika. Do szyfrowania parametrów używane jest szyfrowaniem PGP,
które lepiej zabezpiecza niż podpis MD5 jak to ma miejsce w metodzie opartej o token.
W panelu użytkownika istnieje kreator do tworzenia żądań do API dla usługi ‘Zestaw
połączenie’.
Wady
• Zmiana hasła / loginu / funkcji (czy też dołączanie nowych parametrów do części
zaszyfrowanej) w żądaniu wymaga ponownie zaszyfrowania tych parametrów za pomocą
klucza publicznego. Zastosowane w API szyfrowanie PGP jest zdecydowanie bardziej
złożone obliczeniowo niż obliczanie MD5, przez co przygotowanie żądania jak również
wykonanie po stronie serwera jest wolniejsze niż analogiczne wywołanie w metodzie z
tokenem.
• Przy każdym wywołaniu musimy podawać login, hasło i nazwę funkcji (przez podany login
będą wykonywane wywołania).
• Nie dla wszystkich języków programowania istnieją biblioteki szyfrowania PGP.
• URL jest dłuższy niż dla metody opartej o token.
16 z 47
Należy zaznaczyć, że obie metody mogą być używane równocześnie w obrębie jednej aplikacji..
3.3 Obsługa błędów
W przypadkach gdy wystąpi błąd przy realizacji wywoływanej funkcji zwracany jest sekcja
<errors> (w sekcji nazwy funkcji) składająca się z elementów <error> które opisują z jakim
błędem albo błędami mamy do czynienia.
Przykładowa odpowiedź, z informacją o błędzie.
<response>
<getToken>
<errors>
<error>
<code>invalidCredentials</code>
<msg>Invalid userName, password or authSystem</msg>
</error>
</errors>
</getToken>
</response>
Przy opisie każdej funkcji zostały wymienione możliwe wartości <code>.
Jeśli pojawi się błąd, który nie można powiązać z wywołaniem funkcji sekcja funkcji w
<response> może nie istnieć np.
<response>
<errors>
<error>
<code>indvalidSignature</code>
<msg>Invalid signature</msg>
</error>
</errors>
</response>
Możliwe wartości błędów które mogą się pojawić przy wszystkich wywołaniach funkcji:
•
•
•
•
•
•
•
•
•
•
•
•
duplicatedParams – pojawiły się duplikaty parametrów w żądaniu
invalidToken – token wygasł lub jest błędny
invalidSignature – podpis w komunikacie nie jest zgodny z podpisem obliczonym w
systemie FreecoNet
invalidEncParams – zły format ciągu tekstowego w zaszyfrowanej części
invalidEnc – wystąpił błąd w trakcie deszyfrowanie części encData
invalidEncEncoding – błędne enkodowanie w odszyfrowanym ciągu encData
NSInsideEncData – pojawił się parametr z prefiksem NS w polu encData
noFunInRequest – brak pola Fun w w żądaniu.
invalidAuthType – w parametrach żądaniu użyto jednocześnie pól token oraz
userName lub/i password
valuesToLong – wartości parametrów są za długie
internalServerError – pojawił się błąd operacji. Proszę zgłosić ten błąd do
[email protected]
functionCallLimitsExceeded – pojawiło się za dużo zapytań do API o daną funkcję.
Należy ponowić próbę w późniejszym czasie.
17 z 47
•
•
invalidCredentials – zła kombinacja userName, authSystem, password albo
użytkownik nie ma praw do wykonywania funkcji API
invalidRequest – pozostałe błędy związane z niewłaściwym wywołaniem funkcji
(np.nie podano parametrów wymaganych albo podano za dużo parametrów. Bardziej
szczegółowe wyjaśnienie błędu w <msg>)
4 Opis funkcji API
Uwaga!!!
1) Jeśli w wyniku działania funkcji zwracana jest wartość liczbowa to znakiem oddzielającym
część całkowitą od części dziesiętnej jest znak kropki.
2) Dla wszystkich funkcji w przypadku metody z szyfrowaniem pól trzeba podać parametry
userName, fun i password
3) Wszystkie daty zwracane są w formacie unix'owego znacznika czasu (timestamp), tj. liczba
sekund od 00:00:00 1 stycznia 1970 roku.
4) Wszystkie ciągi tekstowe należy kodować w UTF-8
4.1 Funkcje wspólne dla API User, API Partner, API CRM
4.1.1 getToken
Nazwa
funkcji
Opis
Wejście
getToken
Funkcja autoryzuje użytkownika panelu albo użytkownika usługi i pobiera token z
systemu. W przypadku tej komendy nie jest wymagane podpisanie komunikatu (czyli
nie trzeba dołączać pola sig). Token autoryzacji pobrany w jednym systemie nie
może zostać użyty w innym.
W celu autoryzacji żądania podajemy:
• userName – login użytkownika / serwisu
• password – hasło użytkownika / serwisu
albo poprzedni token
• tokenStr – wcześniej otrzymany token. Użycie tego parametru powoduje
zmniejszenie ilości dopuszczalnych sprawdzeń tokenu dla ‘starego’ tokenu.
Jeśli w tej metodzie uwierzytelniania użyjemy przy wywołaniu funkcji
getToken parametry validPeriod i noAttempts, parametry
noAttempts i validPeriod nie mogą przyjąć wartości większych niż
były podane w 'starym' tokenie.
opcjonalnie
• validPeriod – czas ważności tokena w sekundach (możliwe wartości od
1-86400 [s]). Parametr opcjonalny, w przypadku gdy nie zostanie ustawiony
zostaje użyta wartość domyślna 10 [s]
• noAttempts – dopuszczalna ilość sprawdzeń tokenu. Jeśli -1 to nie ma
limitu na ilość sprawdzeń. Wartość domyślna parametru to 1.
• authSystem – autoryzacja na wybrany system – domyślnie USER
18 z 47
Wyjście
Zwracane wartości:
<tokenStr> - stworzony token
Błędy
Możliwe komunikaty błędów:
• invalidValidPeriod – zła wartość validPeriod. Musi się zawierać
między 1 a 86400 [s ]
• invalidCredentials – zła kombinacja userName, password,
authSystem albo użytkownik nie ma praw do wykonywania funkcji API
Przykład Wywołanie:
użycia
fun=getToken&userName=apidemo&password=apidemo
Przykładowa odpowiedź:
<response>
<getToken>
<tokenStr>
0bfcca72fbad31da6b9087337b468ffb670868a6c45969512df8fc7a9cd05d50
</tokenStr>
</getToken>
</response>
4.1.2 checkToken
Nazwa
funkcji
Opis
checkToken
Funkcja sprawdza ważność tokenu. W przypadku tej komendy nie jest wymagane
podpisanie komunikatu (czyli nie trzeba dołączać pola sig). Funkcja nie zmniejsza
licznika użyć dla tokena.
Wejście
• tokenStr – token który zostaje sprawdzony
Wyjście Zwracane znaczniki elementu <checkToken>:
• <userName> - login użytkownika
• <authSystem> - system w którym przebiegło uwierzytelnianie
Błędy
• invalidCredentials – podany token nie istnieje
użycia
https://apiuser.freeconet.pl/RestAPI/V2/execute?fun=checkToken&
tokenStr=815aa4d11b51ffc09b251da76a7bac81283a002442ac64efc03162922838fb51
Odpowiedź:
<response>
<checkToken>
<userName>apidemo</userName>
<authSystem>USER</authSystem>
<checkToken>
</response>
19 z 47
4.1.3 encryptPGP
Nazwa
funkcji
Opis
encryptPGP
Funkcja szyfruje podany ciąg tekstowy i zwraca wynik w postaci zgodnej z tym co
powinno znajdować się w polu encData (jest to format zgodny z RFC2440
http://sunsite.icm.edu.pl/gnupg/rfc2440-6.html dodatkowo bez nagłówku i stopki ,
tworzony w jednej linii oraz skonwertowane do URL Encoding). Uwaga! Funkcja
encryptPGP nie wymaga podawania userName/userDomain/password jak
również nie istnieje potrzeba generowania podpisu.
Wejście
• inputText – tekst do szyfrowania (tekst musi być w postaci URL Encoding)
Wyjście Zwracane znaczniki sekcji <encryptPGP>:
<outputStr> - stworzony token
Błędy
• invalidData – nie udało się wykonać szyfrowania danych, zapewne złe
dane wejściowe.
użycia
https://apiuser.freeconet.pl/RestAPI/V2/execute?fun=encryptPGP&inputText=fun
%3DmakeCall%26userName%3Dapidemo%26password%3Dapidemo%26idService
%3D543452%26to%3D0587311999%26toType%3DN%26fromType%3DN
Odpowiedź:
<response>
<encryptPGP>
<outputStr>
wcBOA%2F%2FH0yB8UNK7EAQAibQEBMsX8aCXP%2Bh3M%2BdQEWgNRLIstz
%2F9EKY6Auox0q66z4scOwoUxnae%0ArrKYU8U5L3j8rpKK1Xv%2BXP5dQ
%2FhOqeQnl7UHPYRRzJDKXJRmgSMZwdAOujfXVmXiKNUsjDX2wpoz%0ArZsI
%2Bd0NNfUZ2TUVbQjP458vXFvKq%2FBaCGQtWr8D
%2FidMTSwSfYCbu0jHxOwbDgr8h9O9TNw4uKlT%0AND
%2ByWTC0FDgQfIODlhj1jH6BNtHh9CWHMPPfcS4b
%2Ft7ccYsPF2L0YzHISY1PjDXGbHcAAFPrgGmw
%0A0WbEW8Gos7VnBCdXz1I0DJvQ3v6WVQEl7UVfI2Q2y3k0WnYevZPfLU735pGg0pIBr0
J3tPULxPdy
%0ARgIyy9iJ3GEe2vHqIVXliGec1JIonVLDuDwuRuC9IYx44%2F9jHTxlnqpgpH6TNEiN
h01eoxVExlGN%0Ath5TmevPLgRQUQp49eodO4LyN7%2F5UGXREX05PFlQRUY9GF9QKG
%2FteFgT4B%2BpKt8tnLe990MWe%2BSn%0A4mVpu63SePClkh%2FPGmqtzVx9DLSAPw
%3D%3D%0A%3DRPDf</outputStr>
</encryptPGP>
</response>
4.1.4 invalidateToken
Nazwa
funkcji
Opis
Wejście
Wyjście
invalidateToken
Funkcja unieważnia wystawiony token. Token po takiej operacji przestaje być
aktywny i nie jest możliwe wykonywanie operacji z użyciem tego tokena. W
przypadku tej komendy nie jest wymagane podpisanie komunikatu (czyli nie trzeba
dołączać pola sig).
• tokenStr – token, który chcemy unieważnić
Zwracane znaczniki sekcji <invalidateToken>:
20 z 47
<tokenStr> - w przypadku udanej operacji w tym parametrze zwracana jest wartość
tokena podanego w parametrach wejściowych
• invalidCredentials – token nie został znaleziony
użycia
fun=invalidateToken&tokenStr=9358dae31aa89c05dc31171ecebf309ce3dba0b9ea9da
eb5702091dda4c65908&sig=b802ed9a60fabe9d88b29911b72e943b
Błędy
Odpowiedź:
<response>
<invalidateToken>
<tokenStr>9358dae31aa89c05dc31171ecebf309ce3dba0b9ea9daeb5702091dda
4c65908</invalidateToken>
</invalidateToken>
</response>
4.1.5 getVersion
Nazwa
funkcji
Opis
getVersion
Pobranie numeru wersji API – wersja składa się z trzech pól majorVer,
minorVer, buildVer jednoznacznie określających wersje API. W specyfikacji są
odnośniki do wersji w postaci <majorVer>,<minorVer> np. 2.01. Funkcja nie
wymaga dołączania pola sig.
Wejście Brak
Wyjście Zwracane znaczniki sekcji <getVersion>:
• <majorVer> - wersja główna (ang. major version)
• <minorVer> - wersja mniej ważna (ang. minor version)
• <buildVer> - numer kompilacji systemu (ang. build version)
Błędy
Brak
użycia
https://apiuser.freeconet.pl/RestAPI/V2/execute?fun=getVersion
Odpowiedź:
<response>
<getVersion>
<majorVer>2</majorVer>
<minorVer>0</minorVer>
<buildVer>0</buildVer>
</getVersion>
</response>
21 z 47
4.1.6 uploadFile
Nazwa
funkcji
Opis
Wejście
uploadFile
Funkcja umożliwia przesyłanie pliku do systemu, takie pliki mogą być np. używane
do wysyłki faksów. Dokumenty powinny mieć rozmiar nie większy niż 3MB. Pliki
trafiają do specjalnie wydzielonej przestrzeni dyskowej klienta, z której są
automatycznie usuwane po okresie jednego dnia od daty dodania. Nie można mieć
więcej jak 20 takich plików. W przypadku tej komendy nie jest wymagane podpisanie
komunikatu (czyli nie trzeba dołączać pola sig).
Dane powinny być przesyłane zgodnie z metodą POST. (patrz Przykład użycia).
Parametr w metodzie POST wskazujący plik powinien nazywać się:
<fileDocument>
Wyjście
Zwracane tagi XML:
<fileDocumentId> - identyfikator dokumentu pliku dodanego przez klienta (string)
Błędy
• fileSizeExceeded – przekroczono dozwolony rozmiar pliku
• fileLimitExceeded – przekroczono dozwoloną ilość plików
• fileTransmissionError – błąd transmisji pliku
użycia
Poniżej przykładowy kod źródłowy w języku HTML pokazujący użycie funkcji
uploadFile
<html>
<body>
<form method="post" enctype="multipart/form-data"
action="https://apiuser.freeconet.pl/RestAPI/V2/execute?
fun=uploadFile&tokenStr=815aa4d11b51ffc09b251da76a7bac81283a002442ac6
4efc03162922838fb51">
<input type="file" name="fileDocument">
<button type="submit">
</form>
</body>
</html>
Odpowiedź:
<response>
<uploadFile>
<fileDocumentId>plik_1234.txt</fileDocumentId>
</uploadFile>
</response>
4.1.7 deleteFile
Nazwa
funkcji
Opis
Wejście
Wyjście
deleteFile
Funkcja umożliwia usunięcie wcześniej przesłanego pliku
<fileDocumentId> - identyfikator dokumentu pliku, który ma zostać skasowany
Zwracane tagi XML:
<fileDocumentId> - identyfikator dokumentu pliku skasowanego
22 z 47
Błędy
• invalidFileDocumentId – nie znaleziono pliku o podanym identyfikatorze
użycia
fun=deleteFile&fileDocumentId=plik_1234.txt&tokenStr=815aa4d11b51ffc09b251da
76a7bac81283a002442ac64efc03162922838fb51&sig=767848d05b5fbc9c39806586f
bcb8a28
Odpowiedź:
<response>
<deleteFile>
<fileDocumentId>plik_1234.txt</fileDocumentId>
</deleteFile>
</response>
4.2 Funkcje modułu API User
4.2.1 getGroupFinAccountInfo
Nazwa
funkcji
Opis
Wejście
Wyjście
getGroupFinAccountInfo
Funkcja pobiera informacje o saldzie konta dla grupy
Brak parametrów
Zwracane znaczniki sekcji <getGroupFinAccountInfo>:
• <credit> - stan konta w PLN
• <debit> - stan zobowiązań (tylko dla grup rozliczanych w postpaid)
• <creditLimit> - limit kredytu (tylko dla grup rozliczanych w postpaid)
• <minusCreditDate> - data kiedy stan konta spadł poniżej 0 PLN. Jeśli stan
jest powyżej zera to pole jest puste. Data jest podana w formacie Unixowego
czasu (ilość sekund od 1 stycznia 1970)
Przykład Wywołanie dla konta apidemo:
użycia
02442ac64efc03162922838fb51&sig=86cee83a1d14bf7eb8c7b5f6e94a7dd4
Odpowiedź:
<response>
<credit>0</credit>
<debit>0</debit>
</response>
23 z 47
4.2.2 makeCall
Nazwa
funkcji
Opis
Wejście
makeCall
Funkcja zestawia połączenia między dwoma podanymi stronami. Funkcja można
wywołać na dwa sposoby:
• podajemy tylko parametry from i to. W takim przypadku do zestawienia
połączenia nie jest wymagane stworzenia instancji usługi 'Zestaw Połączenie' a
co za tym idzie koszt użytkowania tej funkcji sprowadza się jedynie do
kosztu zestawienia połączenia. W parametrze from oraz to można podawać
numer telefonu (np. '+48221234567') lub login konta SIP (np. 'jan_kowalski').
Dodatkowo nie można skorzystać z ustawień usługi 'Zestaw połączenie' np.
czarnej/białej listy.
• podane są pola idService, from, fromType, to, toType. Wywołanie
wymaga zdefiniowanie usługi 'Zestaw połączenie' w systemie FreecoNet. Po
stronie panelu usługa posiada możliwość konfiguracji, między innymi można
zdefiniować czarną listę dla numeru A czy też B.
W obu przypadkach wywołania funkcji w pierwszej kolejności zestawiane jest
połączenie z from a jak zostanie podniesiona słuchawka to z to.
• idService – identyfikator usługi przez który zostanie zrealizowane
połączenie. Ten parametr w przypadku użycia metody autoryzacji opartej o
szyfrowanie pól musi zostać umieszczony w części zaszyfrowanej.
Należ wybrać metodę połączenia do abonenta from:
• from – numer telefoniczny/ id usługi / nazwa konta
• fromType
o S - podany jest id usługi
o A – podana jest nazwa konta (userName)
o N – podany jest numer telefoniczny
oraz metodę połączenia do abonenta to:
• to – numer telefoniczny / id usługi / nazwa konta
• toType
o S - podany jest id usługi
o A – podana jest nazwa konta (userName)
o N – podany jest numer telefoniczny
Wyjście
Błędy
Uwaga. Podanie równocześnie toType oraz fromType na ‘A’ spowoduje
zwrócenie wartości loopDetected
Zwracane znaczniki sekcji <makeCall>:
• <callId> - unikalny identyfikator rozmowy w systemie FreecoNet.
Zwracane błędy:
• loopDetected – wykryto możliwość zapętlenia np. podano równocześnie
w param. wejściowych toType oraz fromType na ‘A’
• fromBlackListRej – numer A został odrzucony na podstawie czarnej listy
• fromWhiteListRej – numer A został odrzucony na podstawie białej listy
(numer niedopuszczony)
• toBlackListRej – numer B został odrzucony na podstawie czarnej listy
24 z 47
•
toWhiteListRej – numer B został odrzucony na podstawie białej listy
(numer nie dopuszczony)
• timeMaskRej – połączenie odrzucone ze względu na maskę czasową
• fromServiceNotEnabled – strona A nie może być usługą
• fromAccountNotEnabled – strona A nie może być użytkownikiem
• toServiceNotEnabled – strona B nie może być usługą
• toAccountNotEnabled – strona B nie może być użytkownikiem
• serviceDisabled – usługa wyłączona
• wrongFromNumber – błędny format numeru A
• wrongToNumber – błędny format numeru B
Przykład Wywołanie :
https://apiuser.freeconet.pl/RestAPI/V2/execute?encData=wcBOA
użycia
%2F%2FH0yB8UNK7EAP
%2FRkeYDuYSeANStQi0MadQo5EHkPVNS7uADXkLTYde4Uug7uV6NEzNsnTO+boR
Qx%2B48e2lsa4qltYd%2BRPtfI9TW
%2FJOEhYENwuz1zBTvOw1uX9gUN5gs2yMrOn9anB31wi8i4I0T+UnwfmSczTatc
7PTuHUjnH99Zssqcll7NC55LMWkD
%2F0rFdb34%2FXwoHG20%2BYDJ9EJ2UDcKiJ1e6I5J+Nmcd3YEElp9xhiS7bV6i
YnXpDKi5l7KJKUcTMboGsY7Nvn172%2F9t88ksb2PyM7JPwa9VQUO6H9Pt+n22V
ctkBym272lvRDF3nX8BSC8%2Bb5PFlWUKirwYgI
%2BDgTyB1B8Gjsksp4D460pIBQymN5RF8dZp0+8kdozH9izVc98ZRuLFBrS6Tta
M5gEj%2BSritQe3W%2B2EX7TnwhfrWd68EvQUjFR8XdecpyN
%2Fil7ykQ+OY0VXI5nXHqbBxFSLdU
%2FJPYFDTcZiE0FfHpa6bh5ZWQjvSOwFrAIwocOMDcPsMVZOJTKqlha2Xae+nzw
5a3hejcdK7dDWZ97CZJ%2B%2FPoFO3w%3D%3D+%3Dbumf&from=0895277082
W polu encData są zaszyfrowane następujące dane:
fun=makeCall&userName=apidemo&password=apidemo&idService=543452
&to=0587311999&toType=N&fromType=N
Odpowiedź:
<response>
<makeCall>
<callId>fsdfs23423423432234324</callId>
</makeCall>
</response>
4.2.3 getBillingCount
Nazwa
funkcji
Opis
Wejście
getBillingCount
Funkcja zlicza ilość wierszy zwracanych w raporcie połączeń dla zadanych kryteriów
wyszukiwania.
Poniżej lista pól definiujących kryterium wyszukiwania
• callDir
o OUT – rozmowy wychodzące
o IN – rozmowy przychodzące
• fromAccount (opcjonalne) - nazwa użytkownika z którego wychodzą
rozmowy.
25 z 47
•
•
Wyjście
Błędy
Przykład
użycia
toAccount (opcjonalne) – nazwa użytkownika do którego przychodzą
rozmowy
callType (opcjonalne) – typ rozmowy
o CHFR– rozmowy w obrębie platformy
o LOCC– rozmowy PSTN (np. TPSA)
o CALL,<id peera> - rozmowy realizowane przez zewnętrznego
operatora VoIP. Jeśli <id operatora> jest puste wyszukiwane są
rozmowy realizowane przez wszystkich operatorów zewnętrznych.
o LCR,<id peera LCR> - rozmowy przychodzące realizowane przez
operatora LCR. Jeśli <id peera LCR> jest puste wyszukiwane są
rozmowy przychodzące przez wszystkich operatorów LCR.
• isMissed – false są znajdowane rozmowy zrealizowane, true niezrealizowane
• fromDate - data od której wyszukiwane są rozmowy. Data podawana jest w
sekundach które upłynęły od 1 stycznia 1970 (Unix timestamp).
• toDate - data do której wyszukiwane są rozmowy. Data podawana jest w
• calleXFid – identyfikator użytkownika w systemie Call-eX
Zwracane znaczniki XML:
• <noOfRows> - ilość wyszukanych wierszy
Możliwe kody błędów:
• <invalidCallDir> - podano nieprawidłową wartość callDir
• <invalidCallType> - podano nieprawidłową wartość callType
• <invalidToAcc> i <invalidFromAcc>- nie znaleziono podanego konta, w
grupie na która przeprowadzony uwierzytelnianie
• <invalidIsMissed> - podano nieprawidłową wartość isMissed
• <invalidDate> - któraś z podanych dat jest nieprawidłowa
Chcemy sprawdzić ilość połączeń dla następujących kryteriów:
• Rozmowy wychodzące
• Rozmowy wychodzące z kont apidemo
• Rozmowy LCR (bez podania id peera)
• Tylko rozmowy zrealizowane
• Połączeni między 2008-01-01 13:00 a 2008-02-01 14:00
Wywołanie:
fun=getBillingCount&callDir=OUT&fromAccount=apidemo&callType=LCR&isMis
sed=false&fromDate=343434&toDate=354543543534&tokenStr=815aa4d11b51ffc0
9b251da76a7bac81283a002442ac64efc03162922838fb51&sig=0f838ca00d3fb8c72f9
3e833eb96a0fc
Odpowiedź:
<response>
<getBillingCount>
<noOfRows>1234</noOfRows>
</getBillingCount>
</response>
26 z 47
4.2.4 getBilling
Nazwa
funkcji
Opis
Wejście
getBilling
Funkcja pobiera listę połączeń dla zadanych kryteriów wyszukiwania. Jednym
wywołaniem można pobrać 200 wierszy, jeśli w wyniku otrzymujemy więcej niż 200
wierszy należy parokrotnie wywołać funkcje zmieniając offRow czyli numer wiersza
od którego pobieramy dane.
Poniżej lista pól definiujących kryterium wyszukiwania
• callDir
o OUT – rozmowy wychodzące
o IN – rozmowy przychodzące
• fromAccount (opcjonalne) – nazwa użytkownika z którego wychodzą
rozmowy.
• toAccount (opcjonalne) – nazwa użytkownika do którego przychodzą
rozmowy
• callType (opcjonalne) – typ rozmowy
o CHFR– rozmowy w obrębie platformy
o LOCC – rozmowy PSTN (np. TPSA)
o CALL,<id peera sip> - rozmowy realizowane przez zewnętrznego
operatora VoIP. Jeśli <id peera sip> jest puste wyszukiwane są
rozmowy realizowane poprzez wszystkie peery dla operatorów
zewnętrznych.
o LCR,<id peera LCR> - rozmowy przychodzące realizowane przez
peera LCR. Jeśli <id peera LCR> jest puste wyszukiwane są
rozmowy przychodzące przez wszystkie peery LCR.
• isMissed – false są brane rozmowy zrealizowane, true – niezrealizowane
• fromDate – data od której wyszukiwane są rozmowy. Data podawana jest w
• toDate – data do której wyszukiwane są rozmowy. Data podawana jest w
• calleXFid – identyfikator użytkownika w systemie Call-eX
• orderBy (opcjonalne) – określa po którym polu dokonywane jest sortowanie
o fromAccount – konto Od
o toAccount – konto Do
o fromNumber – numer Od
o toNumber – numer Do
o startDate – czas nawiązania połączenia
o callDuration – czas trwania połączenia
o callCost – koszt połączenia
o peerName – nazwa operatora
• orderDesc – kolejność sortowania. false – rosnąco, true– malejąco
• noOfRows – ilość wierszy do pobrania, maksymalna wartość 200
• offRow – od którego wiersza mają być pobrane dane
• columnList – lista kolumn poprzedzielane znakiem przecinka, które można
27 z 47
Wyjście
Błędy
pobrać poprzez wywołanie funkcji
o callType - typ rozmowy, możliwe wartości takie jak dla parametru
wejściowego
o fromAccount – nazwa konto Od
o toAccount – nazwa konto Do
o fromNumber – numer Od
o contactFNF – imię skojarzone w oparciu o książkę kontaktową dla
numeru Od
o contactLNF- nazwisko skojarzone w oparciu o książkę kontaktową
dla numeru Od
o toNumber – numer Do
o contactFNT – imię skojarzone w oparciu o książkę kontaktową dla
numeru Do
o contactLNT- nazwisko skojarzone w oparciu o książkę kontaktową
dla numeru Do
o startDate – czas rozpoczęcia rozmowy. Czas podawany jest w
formacie timestamp’u Unixowego. Czyli ilości sekund od 1970-01-01
00:00:00
o callDuration – czas trwania rozmowy podany w sekundach
o callRate – stawka podana w postaci czwórki x0,y0,x1,y1. X0 – czas
trwania pierwszego impulsu, Y0 – koszt pierwszego impulsu [PLN],
X1 – okres naliczania w [s], Y1 – stawka za 1 min połączenia.
Przykładowe wartości callRate:
 x0=0;y0=10;x1=0;y1=0 - opłata 10 zł. Tylko za
połączenie
 x0=0;y0=10;x1=1;y1=60 - opłata 10 zł. Za połączenie a
dodatkowo 1zł za każdą rozpoczętą sekundę
 x0=1;y0=36;x1=1;y1=36 - opłata 0.6 zł. Za każdą
rozpoczętą sekundę
 x0=10;y0=0.60;x1=1;y1=0.60 - pierwsze 10s za 0.1 zł.
Później 0.01 zł za każdą rozpoczętą sekundę
o callCost – koszt rozmowy
o peerName – nazwa operatora przez którego została zrealizowana
rozmowa
o calleXFid – aktualnie nie wypełniane
W parametrze <columnList> umieszczona jest lista kolumn (przedzielona
przecinkami) dla danych, które wystąpią w <billingData>. W <billingData>
będzie przesyłany spis połączeń w postaci rekordów rozdzielonych znakami LF (\n).
Każdy rekord będzie zawierał pola rozdzielone znakami ‘|’ (ang. pipe). Lista pól i ich
kolejność jest zdefiniowany przez <columnList>. W polu noOfRowsReq
zwracana jest ilość wierszy w danym żądaniu.
Lista kolumn które mogą się pojawić w odpowiedzi została opisane w sekcji
getBillingWejściecolumnList.
• <invalidCallDir> - podano nieprawidłową wartość callDir
• <invalidCallType> - podano nieprawidłową wartość callType
• <invalidToAccount> i <invalidFromAccount>- nie znaleziono
28 z 47
•
•
•
•
•
•
•
podanego konta, w grupie na która przeprowadzony uwierzytelnianie
<invalidIsMissed> - podano nieprawidłową wartość isMissed
<invalidDate> - któraś z podanych dat jest nieprawidłowa
<invalidDate> - jedna z podanych dat jest nieprawidłowa
<invalidColumnList> - wprowadzono niedozwoloną wartość w polu
columnList
<invalidOrderBy> - wprowadzono niedozwoloną wartość w polu orderBy
<invalidOrderDesc> - wprowadzono niedozwoloną wartość w polu
orderDesc
<invalidNoOfRows> - wprowadzono niedozwoloną wartość w polu
noOfRows (maksymalna wartość to 200)
<invalidOffRow> - wprowadzono niedozwoloną wartość w polu offRow
•
Przykład Chcemy pobrać ilość połączeń dla następujących kryterium:
użycia
• Rozmowy wychodzące
• Rozmowy wychodzące z konta apidemo
• Rozmowy LCR (bez podania peera LCR)
• Tylko rozmowy zrealizowane
• Połączenia między 2008-01-01 13:00 (czas Unix 1199192400) a 2008-02-01
14:00 (cza Unix 1201874400)
Lista powinna być posortowana rosnąco po koszcie połączenia i pobieramy 2 wierszy
od 100 wiersza. W rezultacie chcielibyśmy dostać następujące kolumny:
• numer Od
• numer Do
• czas trwania połączenia
• koszt połączenia
• data rozpoczęcia połączenia
• pobierane jest 100 pierwszych wierszy
Wywołanie:
fun=getBilling&callDir=OUT&fromAccount=apidemo&callType=LCR&isMissed=fa
lse&fromDate=1199192400&toDate=1201874400&orderBy=callCost&orderDesc=fal
se&noOfRows=100&offRow=1&columnList=fromNumber,toNumber,callDuration,ca
llCost,startDate&tokenStr=815aa4d11b51ffc09b251da76a7bac81283a002442ac64efc0
3162922838fb51&sig=b79072e81e70be8ce31c41abfc181750
Odpowiedź:
<response>
<getBilling>
<noOfRowsReq>2</noOfRowsReq>
<columnList>fromNumber,toNumber,callDuration,callCost,startDate</
columnList>
<billingData>
<![CDATA[
0895257406|48895257306|233|0.22|1210774923
0893444433|48344444444|33|2.2|1210773923
]]>
</billingData>
</getBilling>
</response>
29 z 47
4.2.5 sendFax
Nazwa
funkcji
Opis
sendFax
Funkcja umożliwia wysłanie pliku faksem.
Uwaga!
Autoryzacja odbywa się loginem oraz hasłem z usługi Wirtualny Faks zamiast
loginem i hasłem użytkownika panelu, autoryzować należy się na system
authSystem=FAXV.
Wejście
• campaignName – nazwa kampanii
• fileDocumentId – identyfikator pliku do wysłania
• timeMask – maska czasowa w formacie UNIX POSIX. Domyślnie przyjmuje
wartość * * * * *
• numberList - lista numerów rozdzielonych przecinkami, na które zostanie
wysłany dokument faksu. Numery należy podawać w takim samym formacie
jak w telefonie np. 0221234567 lub +48221234567, 0049123456789 (Niemcy)
• toDelete - wskazuje czy plik wysyłany powinien być skasowany (wartość
true) po użyciu czy nie (wartość false). Jeśli parametr nie jest podany
domyślnie ustawiony jest na true.
Wyjście Zwracane znaczniki XML:
• <batchId> - unikalny numer zlecenia faksowego
Błędy
• <invalidFileDocumentId> - nie znaleziono pliku o podanym
identyfikatorze
• <invalidNumList> - podana lista numerów jest w błędna
użycia
fun=sendFax&fileDocumentID=plik_1234.txt&timeMask=* * * *
*&numberList=0581234567,0587654321,0581111111&tokenStr=7b4f24d8b17b1502
4426c3a5125577942f876ccb2c132c9f273296220899835e&sig=41b97e4da175a684e5
7adf080d1be605
Odpowiedź:
<response>
<sendFax>
<batchId>12344</batchId>
</sendFax>
</response>
4.2.6 getFaxCurrentCount
Nazwa
funkcji
Opis
getFaxCurrentCount
Funkcja zwraca ilość wierszy w spisie faksów aktualnie wysyłanych spełniających
określone kryteria.
30 z 47
Uwaga!
authSystem=FAXV.
Wejście Parametry wywołania:
• faxStatus – status dokumentu faksu. Dopuszczalne parametry to:
o WAITING, STARTED, CANCELED, ALL
Wyjście Zwracane tagi XML:
Błędy
• <invalidFaxStatus> - podano błędny status dokumentu faksu
Przykład Chcemy sprawdzić ilość faksów dla następującego kryterium:
użycia
• Faksy oczekujące
Wywołanie:
fun=getFaxCurrentCount&faxStatus=WAITING&tokenStr=7b4f24d8b17b15024426c
3a5125577942f876ccb2c132c9f273296220899835e&sig=165887a64ea6baa990f65abf
c64b45a3
Odpowiedź:
<response>
<getFaxCurrentCount>
</getFaxCurrentCount>
</response>
4.2.7 getFaxSentCount
Nazwa
funkcji
Opis
Wejście
Wyjście
Błędy
getFaxSentCount
Funkcja zwraca ilość wierszy w spisie faksów wysłanych spełniających określone
kryteria.
Uwaga!
authSystem=FAXV .
Parametry wywołania:
• fromDate - data od której wyszukiwane są faksy. Data podawana jest w
• toDate - data do której wyszukiwane są faksy. Data podawana jest w
• faxStatus – status wysyłki dokumentu faksu. Dopuszczalne parametry to:
o ENDED, ERROR, CANCELED, ALL
Zwracane tagi XML:
31 z 47
• <invalidDate> - jedna z podanych dat jest nieprawidłowa
użycia
• Faksy wysłane
• Tylko faksy wysłane prawidłowo
Wywołanie:
fun=getFaxSentCount&faxStatus=ENDED&fromDate=343434555&toDate=3545435
43534&tokenStr=7b4f24d8b17b15024426c3a5125577942f876ccb2c132c9f27329622
0899835e&sig=81d6da206e6f47a670f7df685c23ffc0
Odpowiedź:
<response>
<getFaxSentCount>
</getFaxSentCount>
</response>
4.2.8 getFaxReceivedCount
Nazwa
funkcji
Opis
getFaxReceivedCount
Funkcja zwraca ilość wierszy w spisie faksów odebranych spełniających określone
kryteria.
Uwaga!
authSystem=FAXV .
Błędy
użycia
• Faksy odebrane
Wywołanie:
fun=getFaxReceivedCount&fromDate=343434555&toDate=354543543534&tokenStr
=7b4f24d8b17b15024426c3a5125577942f876ccb2c132c9f273296220899835e&sig=f
96602d87edd7deede2e8ae9e9190e26
32 z 47
Odpowiedź:
<response>
<getFaxReceivedCount>
</getFaxReceivedCount>
</response>
4.2.9 getFaxSent
Nazwa
funkcji
Opis
Wejście
Wyjście
getFaxSent
Funkcja umożliwia pobranie listy wysłanych faksów dla danej konsoli faksowej.
Uwaga!
authSystem=FAXV .
• faxStatus – status dokumentu faksu
• orderBy – pole decydujące po jakim polu odbywa się sortowanie. Lista
możliwych wartości – batchId, toNumber, sentDate
• orderDesc - kolejność sortowania. false – rosnąco, true – malejąco
• noOfRows - ilość wierszy do pobrania, maksymalna wartość 200
• offRow - od którego wiersza mają być pobrane dane
o batchId – identyfikator kampanii wysyłki faksu
o itemId – identyfikator elementu wysyłki faksu
o toNumber – numer odbiorcy
o faxStatus – status wysyłki dokumentu
o faxStatusDetails – szczegółowy status wysyłki faksu
o noAttempt – aktualna próba
o maxNoAttempts – maksymalna liczba prób
o sentDate – data wysłania dokumentu (Unix timestamp)
o noPages – liczba wysłanych stron
o sentCost – koszt wysłania faksu
o fileUrl – adres URL dokumentu faksu
o fileName – nazwa pliku dokumentu faksu
W parametrze <columnList> umieszczona jest przedzielona przecinkami lista
kolumn, które wystąpią w odpowiedzi – sekcja <faxData>. W <faxData> będzie
przesyłany spis połączeń w postaci rekordów rozdzielonych znakami LF (\n). Każdy
rekord będzie zawierał pola rozdzielone znakami ‘|’ (ang. pipe). Lista pól i ich
33 z 47
kolejność jest zdefiniowany przez <columnList>.W polu noOfRowsReq zwracana
jest ilość wierszy zwracanych w danym żądaniu.
Błędy
getFaxSentWejściecolumnList.
• <invalidColumnList> - wprowadzono niedozwoloną wartość w polu
•
•
•
columnList
orderDesc
•
Przykład Chcemy pobrać faxy dla następujących kryterium:
użycia
• Faksy wysłane
• Tylko faksy wysłane prawidłowo
• Interesują nas kolumny toNumber, faxStatus, noAttempt
Chcemy w rezultacie otrzymać następujące pola:
• numer Od
• status wysłania faksu
• ilość prób
Wywołanie:
fun=getFaxSent&faxStatus=ENDED&fromDate=343434&toDate=354543543534&c
olumnList=toNumber,faxStatus,noAttempt&tokenStr=7b4f24d8b17b15024426c3a512
5577942f876ccb2c132c9f273296220899835e&orderBy=sentDate&orderDesc=true&
noOfRows=100&offRow=1&sig=f16e1963cad368d85e42a63bd82ad52f
Odpowiedź:
<response>
<getFaxSent>
<columnList>toNumber,faxStatus,noAttempt</columnList>
<faxData>
<![CDATA[
0895257406|ENDED|1
0893444433|ENDED|2
]]>
</faxData>
</getFaxSent>
</response>
34 z 47
4.2.10 getFaxReceived
Nazwa
funkcji
Opis
Wejście
Wyjście
Błędy
getFaxReceived
Funkcja umożliwia pobranie listy odebranych faksów dla danej konsoli faksowej.
Uwaga!
authSystem=FAXV.
możliwych pól – toNumber, receivedDate, fromNumber
o fromNumber – numer telefonu ‘Od’
o toNumber –numer telefonu ‘Do’
o receivedDate – data otrzymania faksu
o itemId – identyfikator odebranego faksu
o fileUrl – link do pliku z faksem odebranym
rekord będzie zawierał pola rozdzielone znakami ‘|’ (ang.pipe). Lista pól i ich
getFaxRecvWejściecolumnList.
•
•
•
•
columnList
orderDesc
<invalidoffRow> - wprowadzono niedozwoloną wartość w polu offRow
35 z 47
Przykład Chcemy pobrać faksy dla następujących kryterium:
użycia
• Faksy odebrane
• Interesują nas kolumny toNumber
• numer Od
Wywołanie:
fun=getFaxReceived&fromDate=343434&toDate=354543543534&columnList=toNu
mber&tokenStr=7b4f24d8b17b15024426c3a5125577942f876ccb2c132c9f273296220
899835e&orderBy=receivedDate&orderDesc=true&noOfRows=100&offRow=1&sig
=7e4a60a5b92f0b39ed51538d9d7358d2
Odpowiedź:
<response>
<getFaxReceived>
<columnList>toNumber</columnList>
<faxData>
<![CDATA[
0895257406
0893444433
]]>
</faxData>
</getFaxReceived>
</response>
4.2.11 getFaxCurrent
Nazwa
funkcji
Opis
Wejście
getFaxCurrent
Funkcja umożliwia pobranie listy aktualnie wysyłanych faksów dla danej konsoli
faksowej.
Uwaga!
authSystem=FAXV.
• faxStatus – status dokumentu faksu
możliwych pól – batchId, toNumber, creationDate
36 z 47
Wyjście
Błędy
o batchId – identyfikator kampanii wysyłki faksu
o itemId – identyfikator elementu wysyłki faksu
o toNumber -docelowy numer telefonu
o faxStatus – status dokumentu faksu
o noAttempt - ilość wykonanych prób
o creationDate – data utworzenia dokumentu
o fileUrl – adres URL dokumentu faksu
o fileName – nazwa pliku dokumentu faksu
rekord będzie zawierał pola rozdzielone znakami ‘|’ (ang.pipe). Lista pól i ich
getFaxCurrWejściecolumnList.
•
•
•
columnList
orderDesc
•
Przykład Chcemy pobrać faxy dla następujących kryterium:
użycia
• Faxs w trakcie wysyłki oczekujący na wysyłkę
• Interesują nas kolumny toNumber, faxStatus, noAttempt
• numer Od
• status wysłania faksu
• ilość prób
Wywołanie:
fun=getFaxCurrent&faxStatus=WAITING&columnList=toNumber,faxStatus,noAttem
pt&tokenStr=7b4f24d8b17b15024426c3a5125577942f876ccb2c132c9f273296220899
835e&orderBy=creationDate&orderDesc=true&noOfRows=100&offRow=1&sig=96
b0a13a89ce2959025d479a0775e784
Odpowiedź:
<response>
37 z 47
<getFaxCurrent>
<columnList>toNumber,faxStatus,noAttempt</columnList>
<faxData>
<![CDATA[
0895257406|WAITING|1
0893444433|WAITING|2
]]>
</faxData>
</getFaxCurrent>
</response>
4.2.12 StartMassDial
Nazwa
funkcji
Opis
Wejście
Wyjście
Błędy
startMassDial
Funkcja umożliwia rozpoczęcie kampanii MassDial.
Uwaga!
Autoryzacja odbywa się loginem oraz hasłem z usługi MassDial zamiast loginem i
hasłem użytkownika panelu, autoryzować należy się na system authSystem=MASD.
• campaignName – nazwa kampanii
• fileDocumentId – identyfikator pliku dźwiękowego. Parametr opcjonalny.
• timeMask – maska czasowa w formacie UNIX POSIX. Domyślnie przyjmuje
wartość * * * * *
• playingMode – tryb odtwarzania. Opcja dostępna jest tylko gdy podana jest
wartość fileDocumentId. Możliwe wartości:
o playFileFirst – odtwarza nagranie z pliku przed komunikatem
o playFileLast – odtwarza nagranie z pliku po komunikacie
• taskList – lista docelowych numerów i przypisanych im komunikatów do
odtworzenia (format: numer;komunikat|numer;komunikat).
• toDelete - wskazuje czy plik powinien być skasowany (wartość true) po
użyciu czy nie (wartość false). Jeśli parametr nie jest podany domyślnie
ustawiony jest na true.
• presentationNum – numer, którym będzie się prezentować kampania
MassDial. Numer jest odpowiednikiem prezentacji w konfiguracji konta w
panelu. Gdy ten numer nie jest podany ustawienia prezentacji będą takie jakie
są ustawienia dla konta. Numer należy podawać w formacie +48221234567.
Funkcja presentationNum działa tylko w przypadku, gdy konto przez które
realizowane jest połączenie, ma ustawioną prezentację 'użyj z bramki'.
Zwracane znaczniki XML:
• <batchId> - unikalny identyfikator kampanii
• invalidFileDocumentId – podano nieprawidłowy identyfikator dokumentu
• invalidPlayingMode – podany tryb odtwarzania jest nieprawidłowy
• invalidTaskList – podana lista komunikatów jest nieprawidłowa
• invalidTimeMask – podana maska czasowa ma błędny format
• invalidPresentationNum – podany numer prezentacji jest nieprawidłowy
(zły format, nie znaleziono podanego numeru)
38 z 47
użycia
fun=startMassDial&fileDocumentID=plik_1234.mp3&timeMask=* * * *
*&tokenStr=cae54dc195caaba426cbe9dbda2d97c345b9507cb7b304392bc7da4bf1095
72b&campaignName=Moja_Kampania_01&taskList=123456789;Komunikat1|
123456790;Komunikat2&playingMode=playFileLast&sig=9036d5d902b25443af96cd
4f57f16575
Odpowiedź:
<response>
<startMassDial>
</startMassDial>
</response>
4.2.13 getMassDialCurrentCount
Nazwa
funkcji
Opis
getMassDialCurrentCount
Funkcja zwraca ilość wierszy w spisie połączeń MassDial aktualnie przetwarzanych
spełniających określone kryteria.
Uwaga!
• massDialStatus – status połączenia MassDial. Dopuszczalne parametry to:
Błędy
• <invalidMassDialStatus> - podano błędny status kampanii
Przykład Chcemy sprawdzić ilość połączeń dla następującego kryterium:
użycia
• Połączenia oczekujące
Wywołanie:
fun=getMassDialCurrentCount&massDialStatus=WAITING&tokenStr=cae54dc195ca
aba426cbe9dbda2d97c345b9507cb7b304392bc7da4bf109572b&sig=e63999ad9b7dbb
c8e1c092d42139852b
Odpowiedź:
<response>
<getMassDialCurrentCount>
</getMassDialCurrentCount>
</response>
39 z 47
4.2.14 getMassDialCalledCount
Nazwa
funkcji
Opis
getMassDialCalledCount
Funkcja zwraca ilość wierszy w spisie połączeń zakończonych spełniających
określone kryteria.
Uwaga!
• fromDate - data od której wyszukiwane są połączenia. Data podawana jest w
• toDate - data do której wyszukiwane są połączenia. Data podawana jest w
• massDialStatus – status połączenia MassDial. Dopuszczalne parametry to:
• massDialStatusDetails – opcja dostępna tylko przy wyborze
massDialStatus na ENDED. Dopuszczalne wartości to:
o SUCCESSFUL – zakończone powodzeniem
o PARTIAL – częściowo zrealizowane
o SWITCHED – zakończone powodzeniem, następnie przełączone na
wyjście z usługi
Błędy
• <invalidMassDialStatus> - podano błędny status połączenia MassDial
Przykład Chcemy sprawdzić ilość połączeń MassDial dla następującego kryterium:
użycia
• połączenia zakończone sukcesem
Wywołanie:
fun=getMassDialCalledCount&massDialStatus=ENDED&massDialStatusDetails=SU
CCESSFUL&fromDate=343434555&toDate=354543543534&tokenStr=cae54dc195c
aaba426cbe9dbda2d97c345b9507cb7b304392bc7da4bf109572b&sig=b486e56f2644e
d7741317f99ef73253c
Odpowiedź:
<response>
<getMassDialCalledCount>
</getMassDialCalledCount>
</response>
40 z 47
4.2.15 getMassDialCurrent
Nazwa
funkcji
Opis
Wejście
Wyjście
getMassDialCurrent
Funkcja umożliwia pobranie listy aktualnie realizowanych połączeń dla konsoli
MassDial
Uwaga!
• massDialStatus – status połączenia
o WAITING,STARTED,CANCELED,ALL
możliwych pól – batchId, toNumber, creationDate
o batchId – identyfikator kampanii MassDial
o itemId – identyfikator połączenia MassDial
o announcement – komunikat jaki zostanie przeczytany po odebraniu
połączenia
o toNumber - docelowy numer telefonu
o massDialStatus – status połączenia MassDial
o noAttempt - ilość wykonanych prób
o creationDate – data utworzenia dokumentu
o fileUrl – adres URL pliku do odtwarzania
o fileName – nazwa pliku pliku do odtwarzania
o playingMode – tryb odtwarzania. Możliwe wartości:
o playFileFirst – odtwarza nagranie z pliku przed
komunikatem
kolumn, które wystąpią w odpowiedzi – sekcja <massDialData>. W
<massDialData> będzie przesyłany spis połączeń w postaci rekordów
rozdzielonych znakami LF (\n). Każdy rekord będzie zawierał pola rozdzielone
znakami ‘|’ (ang.pipe). Lista pól i ich kolejność jest zdefiniowany przez
<columnList>.W polu noOfRowsReq zwracana jest ilość wierszy zwracanych w
danym żądaniu.
getMassDialCurrWejściecolumnList.
41 z 47
Błędy
columnList
• <invalidOrderBy> - wprowadzono niedozwoloną wartość w polu orderBy
• <invalidOrderDesc> - wprowadzono niedozwoloną wartość w polu
orderDesc
• <invalidNoOfRows> - wprowadzono niedozwoloną wartość w polu
• <invalidOffRow> - wprowadzono niedozwoloną wartość w polu offRow
Przykład Chcemy pobrać połączenia MassDial dla następujących kryterium:
użycia
• połączenia bieżące, oczekujące
• Interesują nas kolumny toNumber, massDialStatus, noAttempt
• numer Od
• status połączenia
• ilość prób
Wywołanie:
fun=getMassDialCurrent&massDialStatus=WAITING&columnList=toNumber,massD
ialStatus,noAttempt&orderBy=creationDate&orderDesc=true&noOfRows=100&offR
ow=1&tokenStr=cae54dc195caaba426cbe9dbda2d97c345b9507cb7b304392bc7da4bf
109572b&sig=950fdf242ed647337ef3e2ca28e5314e
Odpowiedź:
<response>
<getMassDialCurrent>
<columnList>toNumber,massDialStatus,noAttempt</columnList>
<massDialData>
<![CDATA[
0895257406|WAITING|1
0893444433|WAITING|2
]]>
</massDialData>
</getMassDialCurrent>
</response>
4.2.16 cancelMassDialCurrent
Nazwa
funkcji
Opis
cancelMassDialCurrent
Funkcja umożliwia anulowanie listy zadań z listy aktualnie realizowanych połączeń
MassDial
Uwaga!
42 z 47
Wejście
• itemList – lista identyfikatorów połączeń MassDial, które mają zostać
anulowane
Wyjście
<status> - jeżeli udało się anulować połączenia MassDial pole to przyjmie wartość
CANCELED
Błędy
• <invalidItemList> - podano nieprawidłową listę identyfikatorów połączeń
MassDial lub połączenia są w trakcie realizacji i nie można ich już anulować
użycia
fun=cancelMassDialCurrent&itemList=123,456,234&tokenStr=cae54dc195caaba426
cbe9dbda2d97c345b9507cb7b304392bc7da4bf109572b&sig=8a69e8f6cddfef4cd2b9a
f9c03c94df7
Odpowiedź:
<response>
<cancelMassDialCurrent>
<status>CANCELED</status>
</cancelMassDialCurrent>
</response>
4.2.17 getMassDialCalled
Nazwa
funkcji
Opis
Wejście
getMassDialCalled
Funkcja umożliwia pobranie listy zakończonych połączeń dla konsoli MassDial.
Uwaga!
• fromDate -data od której wyszukiwane są połączenia. Data podawana jest w
• toDate -data do której wyszukiwane są połączenia. Data podawana jest w
• massDialStatus – status zadania
• massDialStatusDetails – opcja dostępna tylko przy wyborze
massDialStatus na ENDED. Dopuszczalne wartości to:
o SUCCESSFUL – zakończone powodzeniem
o PARTIAL – częściowo zrealizowane
o SWITCHED – zakończone powodzeniem, następnie przełączone na
wyjście z usługi
możliwych pól – batchId, toNumber, callDate
43 z 47
•
•
Wyjście
Błędy
offRow - od którego wiersza mają być pobrane dane
columnList – lista kolumn poprzedzielane znakiem przecinka, które można
o batchId – identyfikator kampanii MassDial
o itemId – identyfikator elementu kampanii MassDial (połączenia)
o announcement – komunikat odtwarzany po odebraniu połączenia
o toNumber – docelowy numer telefonu
o massDialStatus – status połączenia
o massDialStatusDetails – szczegółowy status połączenia
o noAttempt – aktualna próba
o callDuration – czas połączenia
o callDate – data zakończenia połączenia
o callCost – koszt połączenia
o fileUrl – adres URL pliku do odtwarzania
o fileName – nazwa pliku do odtwarzania
o playingMode – tryb odtwarzania. Możliwe wartości:
o playFileFirst – odtwarza nagranie z pliku przed
komunikatem
o contactName – imię i nazwisko jeżeli numer docelowy znajduje się
na liście kontaktów zdefiniowanych w panelu
kolumn, które wystąpią w odpowiedzi – sekcja <massDialData>. W
<massDialData> będzie przesyłany spis połączeń w postaci rekordów
rozdzielonych znakami LF (\n). Każdy rekord będzie zawierał pola rozdzielone
znakami ‘|’ (ang.pipe). Lista pól i ich kolejność jest zdefiniowany przez
<columnList>.W polu noOfRowsReq zwracana jest ilość wierszy zwracanych w
danym żądaniu.
getMassDialCalledWejściecolumnList.
•
•
•
columnList
orderDesc
•
Przykład Chcemy pobrać połączenia dla następujących kryterium:
użycia
• Połączenia zakończone
• Połączenia zakończone prawidłowo
• Połączenia między 2008-01-01 13:00 a 2008-02-01 14:00
• Interesują nas kolumny toNumber, massDialStatus, noAttempts
44 z 47
• numer Od
• status połączenia
• ilość prób
Wywołanie:
fun=getMassDialCalled&massDialStatus=ENDED&fromDate=343434&toDate=3545
43543534&columnList=toNumber,massDialStatus,noAttempt&orderBy=callDate&or
derDesc=true&noOfRows=100&offRow=1&tokenStr=cae54dc195caaba426cbe9dbda
2d97c345b9507cb7b304392bc7da4bf109572b&sig=76b91e608090cafc035c63ea3465
eb46
Odpowiedź:
<response>
<getMassDialCalled>
<columnList>toNumber,massDialStatus,noAttempts</columnList>
<massDialData>
<![CDATA[
0895257406|ENDED|1
0893444433|ENDED|2
]]>
</massDialData>
</getMassDialCalled>
</response>
4.2.18 deleteMassDialCalled
Nazwa
funkcji
Opis
Wejście
Wyjście
Błędy
deleteMassDialCalled
Funkcja umożliwia usunięcie listy zadań z listy zakończonych połączeń MassDial
Uwaga!
usunięte
<status> - jeżeli udało się anulować połączenia MassDial pole to przyjmie wartość
DELETED
MassDial
użycia
fun=deleteMassDialCalled&itemList=123,456,234&tokenStr=cae54dc195caaba426cb
45 z 47
e9dbda2d97c345b9507cb7b304392bc7da4bf109572b&sig=f391c5e5d3dea09d58000b
fdb504deb0
Odpowiedź:
<response>
<deleteMassDialCalled>
<status>DELETED</status>
</deleteMassDialCalled>
</response>
4.2.19 restartMassDialCalled
Nazwa
funkcji
Opis
Wejście
Wyjście
restartMassDialCalled
Funkcja umożliwia ponowną realizację listy zadań z listy zakończonych połączeń
MassDial
Uwaga!
ponownie zrealizowane
<batchId> - każdy element batchId wskazuje na nowo utworzone zadanie
MassDial. Jeżeli podane identyfikatory połączeń wskazują na realizację połączeń w
tym samym zadaniu zostaną one również zrealizowane w jednym zadaniu
Błędy
MassDial
użycia
fun=restartMassDialCalled&itemList=123,456,234&tokenStr=cae54dc195caaba426c
be9dbda2d97c345b9507cb7b304392bc7da4bf109572b&sig=a00b685831ca950796a4
5996667663b3
Odpowiedź:
<response>
<restartMassDialCalled>
</restartMassDialCalled>
</response>
46 z 47
4.2.20getRegistrationStatus
Nazwa
funkcji
Opis
getRegistrationStatus
Funkcja umożliwia pobranie statusu rejestracji kont zdefiniowanych w obrębie
grupy. Gdzie przez rejestracje konta rozumiemy – rejestracje terminala na to konto.
Wejście
• accountList – lista kont przedzielonych przecinkami dla których chcemy
pobrać statusy. Jednorazowo można podać listę 20 kont.
Wyjście Zwracana jest informacja ze statusem dla poszczególnych kont w sekcji
<registerStatusList>. Informacje o pojedynczym koncie zwracana jest w sekcji
<registerStatus> i zawiera następujące elementy:
• <userName> – nazwa konta
• <status> – status rejestracji
o REGISTERED – przynajmniej jeden terminal jest zarejestrowany na
koncie.
o UNREGISTERED – nie było próby rejestracji na koncie
o TRYING – była nieudana próba rejestracji
• <noRegistered> – ilość zalogowanych bramek na danym koncie
Błędy
• <invalidAccountList> - podano więcej niż 20 numerów lub nie znaleziono
któregoś z podanych kont
użycia
fun=getRegistrationStatus&accountList=apidemo&tokenStr=815aa4d11b51ffc09b251
da76a7bac81283a002442ac64efc03162922838fb51&sig=cd9303672e2754e8d043849
25fce73c1
Odpowiedź:
<response>
<getRegistrationStatus>
<registerStatusList>
<registerStatus>
<userName>test</userName>
<status>REGISTERED</status>
<noRegistered>1</noRegistered>
</registerStatus>
<registerStatus>
<userName>test1</userName>
<status>REGISTERED</status>
<noRegistered>2</noRegistered>
</registerStatus>
</registerStatusList>
</getRegistrationStatus>
</response>
5 Opłaty
RestAPI 2.x jest usługą bezpłatną.
47 z 47

FreecoNet API 2.0

Transkrypt

Podobne dokumenty

Podłączenie i konfiguracja telefonu VoIP Gigaset A580IP

Nie wszystko można zmienid, telefon tak!

PODŁĄCZENIE ROUTERA VOIP LINKSYS WRTP54G-EU

Yealink SIP-T28P

UMOWA NR O ŚWIADCZENIE

Mobile + Kontekst Otoczenia