Freeconet RestAPI ver.1.01

Transkrypt

Freeconet RestAPI
ver.1.01
Autor: Michał Szymański
http:://techblog.freeconet.pl
Data: 2009-5-19
Strona 1 z 25
SPIS TREŚCI
1 HISTORIA ZMIAN................................................................................3
2 WSTĘP.....................................................................................................4
3 OPIS UŻYCIA API.................................................................................4
3.1 SKŁADNIA WYWOŁANIA FUNKCJI Z API..............................................................................................................................5
3.2 UWIERZYTELNIANIE........................................................................................................................................................5
3.2.1 Metoda oparta o token.......................................................................................................................................5
3.2.2 Metoda oparta o szyfrowanie parametrów żądania..........................................................................................7
3.2.2.1 Przykład użycia szyfrowania......................................................................................................................................7
3.2.2.2 Generowanie wartości do pola encData....................................................................................................................10
3.2.3 Porównanie metod autoryzacji........................................................................................................................13
3.2.3.1 Metoda oparta o token..............................................................................................................................................13
3.2.3.2 Metoda oparta o szyfrowanie parametrów żądania...................................................................................................14
3.3 OBSŁUGA BŁĘDÓW........................................................................................................................................................14
4 OPIS FUNKCJI API.............................................................................15
4.1 GETTOKEN...................................................................................................................................................................15
4.2 CHECKTOKEN...............................................................................................................................................................16
4.3 GETFINACCOUNTINFO...................................................................................................................................................17
4.4 MAKECALL..................................................................................................................................................................17
4.5 GETBILLINGCOUNT (OD WERSJI API 1.02)......................................................................................................................19
4.6 GETBILLING (OD WERSJI API 1.02)................................................................................................................................20
4.7 ENCRYPTPGP .............................................................................................................................................................23
4.8 INVALIDATETOKEN (OD WERSJI API 1.01).......................................................................................................................24
4.9 GETVERSION (OD WERSJI API 1.01)..............................................................................................................................24
5 OPŁATY................................................................................................25
Strona 2 z 25
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
1.01.04
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
Freeconetu na wersje API
Drobne poprawki w opisie szyfrowania
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.1.01 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.
Należy zaznaczyć, że obecna wersja API ulega ciągłej rozbudowie, osoby chcące skorzystać z API
w systemach produkcyjnych proszone są o zapoznianie się z najnowszą dokumentacją dostępną pod
adresem http://techblog.freeconet.pl/.
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 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 api_demo.
https://api.freeconet.pl/RestAPI/V1/execute?
fun=getGroupFinAccountInfo&tokenStr=815aa4d11b51ffc09b251da76a7bac81283a002442
ac64efc03162922838fb51&sig=86cee83a1d14bf7eb8c7b5f6e94a7dd4
W odpowiedzi klient otrzymuje XML w postaci:
<?xml version=”1.0”?>
<response>
<function>getGroupFinAccount</function>
<params>
<param name=”credit”
value=”0”/>
<param name=”debit”
value=”0”/>
<param name=”creditLimit”
value=”0”/>
<param name=”emptyAccountDate” value=””/>
</params>
</response>
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 żadania 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:// api.freeconet.pl /RestAPI/V1/execute?encData=wcBOA%2F%2FH0yB8UNK7EAQAm...
1
2
3
4
5
Gdzie:
1 - komunikacja odbywa się po szyfrowanym protokole HTTPS
2 –część URL, pod którą są umieszczone wszystkie API oferowane przez system FreecoNet
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ć, aktualnie istnieje tylko wersja 1.x tak
więc zawsze podajemy V1
5 – parametry wywoływanej funkcji
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.
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 które ma hasło apidemo :
fun=getToken&userName=apidemo&userDomain=sip.freeconet.pl&password=apidemo&val
idPeriod=10000
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)
userDomain – domena w której zarejestrowany jest użytkownik (dla użytkownika założonego ze
strony www.freeconet.pl pole przyjmuje wartość ‘sip.freeconet.pl’)
password – hasło dla konta. Jest to te samo hasło które użytkownik używa do logowania się do
panelu
validPeriod – czas ważności tokenu w sekundach, wartość domyślna to 10s
W przypadku udanego uwierzytelniania otrzymujemy XML w postaci
<response>
<function>getToken</function>
<params>
<param name=”tokenStr”
value=”815aa4d11b51ffc09b251da76a7bac81283a002442ac64efc03162922838fb51”/>
</params>
</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>
<function>getGroupFinAccountInfo</function>
<errors>
<error>
<code>invalidToken</code>
<msg>Token expired or is invalid</msg>
</error>
</errors>
</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.
fun=getGroupFinAccountInfo&tokenStr=815aa4d11b51ffc09b251da76a7bac81283a002442
ac64efc03162922838fb51&sig=86cee83a1d14bf7eb8c7b5f6e94a7dd4
Należy zwrócić uwagę na ostatnią część w URL:
sig=86cee83a1d14bf7eb8c7b5f6e94a7dd4
Jest to podpis przesyłanej wiadomości. 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 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 uwage 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:
<response>
<params>
value=”0”/>
value=”0”/>
value=”0”/>
</params>
</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,
nazwę domeny oraz 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:
Samo zainicjowanie połączenia następuje po wysłaniu do serwera następujące żądania1
1
2
https://api.freeconet.pl/RestAPI/V1/execute?encData=wcBOA%2F%2FH0yB8UNK7EAP%2BJhVN29
4Ema9E4eiPFFcVb%2B9wwsqK2yw2szJKLc5tDgmtaBil48qRK%2Ftq%0AtG8EkNItTx8MkXPqq3AASFGTmeUSia4T6iy
yEv02C3rrMzVaFfincZTYZzjKmkzsOCIXGC%2FnbFlM%0AJIT0%2BpOxYtTfBbJvVIMx2HCqjpUEL7%2FqPoie3NAEAID
%2FtQKdjhfvfTdeGqFU7vscMJ5udqD9Gcec%0AcvpsZYRw%2FJFEe%2BHQh5%2FmHujdQP5grc1g1EqB3t2f1VPty3sq
hY8hpLLtyW4UOmFhQ%2BWK4TfAdjH3%0AJnkHq8fvZWzfcWFLchWsWSz7J8yKPy7KDaaGqlZCBqftQ%2B1ZZbI0fZl
1cspy0q4BZOpgCPm1ALa1%0AqBnfI2I1K6OuN1q8vPl82UJBIAY8SryBy8pCDAZ9BxyKvg7Vbmzm8CGVeUNku%2FMg
JkAeQ8bLgef4%0AahBesQ16O1pAzBhv3p2A51xxbnEJAjbXAoApC8hf5rqBKX4DbJl3tZQJMVotAVhWFHg%2Bxr9f3fRy
%0AXhfaXYyT8WWHTmov71SkmPcDqI1YmTfnwpRUg%2BFekP2d8UtxsMLR5eFdRbnil8EBBn4%3D%0A%3DNM74
&from=0895277082
3
1
Ze względu, że na koncie testowym jest zerowy stan konta można jedynie podać numer z Freeconetu.
Gdzie:
1–
standardowy adres API
2–
zaszyfrowany login, hasło konta, które zostanie obciążone kosztami rozmowy i z którego
zostanie zestawione połączenie, id serwisu, typ strony Od i ‘numer Od’
3numer 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
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, paremetry 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)
Domena konta
(userDomain)
Hasło (password)
Wartość
makeCall
apidemo
sip.freeconet.pl
apidemo
Zaszyfrowane
TAK
TAK
TAK
TAK
Uwagi
Należy wpisać hasło dla podanego
Id Serwisu (idservice)
543452
TAK
Numer do (to)
Typ strony Do (toType)
Typ strony Od (fromType)
0587311999
N
N
TAK
TAK
TAK
wyżej użytkownika
Id serwisu. Wyświetlane w zakładce
‘konfiguruj’ poniżej nazwy serwisu.
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://api.freeconet.pl/RestAPI/V1/execute?encData=wcBOA%2F%2FH0yB8UNK7EAP
%2BJhVN294Ema9E4eiPFFcVb%2B9wwsqK2yw2szJKLc5tDgmtaBil48qRK%2Ftq
%0AtG8EkNItTx8MkXPqq3AASFGTmeUSia4T6iyyEv02C3rrMzVaFfincZTYZzjKmkzsOCIXGC
%2FnbFlM%0AJIT0%2BpOxYtTfBbJvVIMx2HCqjpUEL7%2FqPoie3NAEAID
%2FtQKdjhfvfTdeGqFU7vscMJ5udqD9Gcec%0AcvpsZYRw%2FJFEe
%2BHQh5%2FmHujdQP5grc1g1EqB3t2f1VPty3sqhY8hpLLtyW4UOmFhQ
%2BWK4TfAdjH3%0AJnkHq8fvZWzfcWFLchWsWSz7J8yKPy7KDaaGqlZCBqftQ
%2B1ZZbI0fZl1cspy0q4BZOpgCPm1ALa1%0AqBnfI2I1K6OuN1q8vPl82UJBIAY8SryBy8pCDAZ9Bx
yKvg7Vbmzm8CGVeUNku
%2FMgJkAeQ8bLgef4%0AahBesQ16O1pAzBhv3p2A51xxbnEJAjbXAoApC8hf5rqBKX4DbJl3tZQJMV
otAVhWFHg%2Bxr9f3fRy%0AXhfaXYyT8WWHTmov71SkmPcDqI1YmTfnwpRUg
%2BFekP2d8UtxsMLR5eFdRbnil8EBBn4%3D%0A%3DNM74&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)
https://api.freeconet.pl/RestAPI/V1/execute?encData=wcBOA%2F%2FH0yB8UNK7EAP
%2BJhVN294Ema9E4eiPFFcVb%2B9wwsqK2yw2szJKLc5tDgmtaBil48qRK%2Ftq
%2B1ZZbI0fZl1cspy0q4BZOpgCPm1ALa1%0AqBnfI2I1K6OuN1q8vPl82UJBIAY8SryBy8pCDAZ9Bx
yKvg7Vbmzm8CGVeUNku
%2FMgJkAeQ8bLgef4%0AahBesQ16O1pAzBhv3p2A51xxbnEJAjbXAoApC8hf5rqBKX4DbJl3tZQJMV
otAVhWFHg%2Bxr9f3fRy%0AXhfaXYyT8WWHTmov71SkmPcDqI1YmTfnwpRUg
%2BFekP2d8UtxsMLR5eFdRbnil8EBBn4%3D%0A%3DNM74&from=0895277082
Dla typowej sytuacji możemy skorzystać z całego kodu kontrolki wygenerowanego na stronie.
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. Warto zaznaczyć, że do szyfrowania można użyć również funkcji encryptPGP
dostępnej w Rest API – rozdział 4.7.4.7
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://api.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.
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&userDomain=sip.freeconet.pl&password=apidemo&idS
ervice=543452&to=0587311999&toType=N&fromType=N
Należy zwrócić uwage, ż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&userDomain=sip.freeconet.pl&password=apidemo&idS
ervice=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]>"
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)
hQEOA//H0yB8UNK7EAP+MTzQ/32VBdsC+VaEi3zMfm7YVzNeMc7N1r+vYHdEKQLM
2XI430dxAV8OzcZKe1j+89CvjD6UgMLXtUjUDOWUlP1qtJZ0aPGO3vMfH7j62ZP/
Gvkkhj73wazdSYvhX8OJcidlE1QV2kgylcguRJjbOOdpPHpiX1G+elOmqrdQt7ED
/11DByTL6XZ+YZsgILKpNiXvnhEx/+qOcziE9ZhJUUsqarALQRymIrljjgNxM09c
shIpt3xfsueQ1ks2UFAvx1jSx36RZiT+FrSauyUZvnfczMmEzTKw7GelhZ/dqC/M
yc+BiY+ydzQT5lApeXVjXjtDRQAA2x7nET/0EorbpFNM0rYBdyONk9B2u0lujgb1
aUgfuZ5DwRIGPmbv0xhZa93QOY/apCeYKoSOY4weskpexlpVKFVv5szp55os8YPb
x2md//82kEaV5j0gMLH+WBjWgLMjGqgTVQszYKTdr+jb+MZDq+meJ/cnG2S1uBQp
2DeAdDNtnIJtbaQSy5/NzJBJ1eARZGgd/opYAGV/YoIvZfa6amdRELzrjys1qkdY
nTuDxoqBAxEvC6mpk4kKat8UmAAxzMTSlQ==
=nrXZ
-----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:
hQEOA%2F%2FH0yB8UNK7EAP%2BMTzQ%2F32VBdsC%2BVaEi3zMfm7YVzNeMc7N1r
%2BvYHdEKQLM+2XI430dxAV8OzcZKe1j%2B89CvjD6UgMLXtUjUDOWUlP1qtJZ0aPGO3vMfH7j62ZP
%2F+Gvkkhj73wazdSYvhX8OJcidlE1QV2kgylcguRJjbOOdpPHpiX1G%2BelOmqrdQt7ED+
%2F11DByTL6XZ%2BYZsgILKpNiXvnhEx%2F
%2BqOcziE9ZhJUUsqarALQRymIrljjgNxM09c+shIpt3xfsueQ1ks2UFAvx1jSx36RZiT
%2BFrSauyUZvnfczMmEzTKw7GelhZ%2FdqC%2FM+yc%2BBiY%2BydzQT5lApeXVjXjtDRQAA2x7nET
%2F0EorbpFNM0rYBdyONk9B2u0lujgb1+aUgfuZ5DwRIGPmbv0xhZa93QOY
%2FapCeYKoSOY4weskpexlpVKFVv5szp55os8YPb+x2md%2F%2F82kEaV5j0gMLH
%2BWBjWgLMjGqgTVQszYKTdr%2Bjb%2BMZDq%2BmeJ
%2FcnG2S1uBQp+2DeAdDNtnIJtbaQSy5%2FNzJBJ1eARZGgd%2FopYAGV
%2FYoIvZfa6amdRELzrjys1qkdY+nTuDxoqBAxEvC6mpk4kKat8UmAAxzMTSlQ%3D%3D+%3DnrXZ
•
Ostatnim krokiem jest stworzenie pełnego URL’. W naszym przypadku dodajemy jeszcze adres
API oraz paremetr, który będzie zmienny czyli from.
https://api.freeconet.pl/RestAPI/V1/execute?encData=hQEOA%2F%2FH0yB8UNK7EAP
%2BMTzQ%2F32VBdsC%2BVaEi3zMfm7YVzNeMc7N1r%2BvYHdEKQLM+2XI430dxAV8OzcZKe1j
%2B89CvjD6UgMLXtUjUDOWUlP1qtJZ0aPGO3vMfH7j62ZP
%2F+Gvkkhj73wazdSYvhX8OJcidlE1QV2kgylcguRJjbOOdpPHpiX1G%2BelOmqrdQt7ED+
%2F11DByTL6XZ%2BYZsgILKpNiXvnhEx%2F
%2BqOcziE9ZhJUUsqarALQRymIrljjgNxM09c+shIpt3xfsueQ1ks2UFAvx1jSx36RZiT
%2BFrSauyUZvnfczMmEzTKw7GelhZ%2FdqC%2FM+yc%2BBiY%2BydzQT5lApeXVjXjtDRQAA2x7nET
%2F0EorbpFNM0rYBdyONk9B2u0lujgb1+aUgfuZ5DwRIGPmbv0xhZa93QOY
%2FapCeYKoSOY4weskpexlpVKFVv5szp55os8YPb+x2md%2F%2F82kEaV5j0gMLH
%2BWBjWgLMjGqgTVQszYKTdr%2Bjb%2BMZDq%2BmeJ
%2FcnG2S1uBQp+2DeAdDNtnIJtbaQSy5%2FNzJBJ1eARZGgd%2FopYAGV
%2FYoIvZfa6amdRELzrjys1qkdY+nTuDxoqBAxEvC6mpk4kKat8UmAAxzMTSlQ%3D%3D+
%3DnrXZ&from=0587834934
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 szyfrowanien 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 / domeny / 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, domenę 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.
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 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>
<errors>
<error>
<code>invalidCredential</code>
<msg>Invalid userName/password/domain</msg>
</error>
</errors>
</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 pola w sekcji <response>
mogą być puste np
<response>
<function> </function>
<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]
invalidCredential – zła kombinacja userName/userDomain/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
UWAGI OGÓLNE:
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, userDomain, fun i password
3) Wszystkie daty zwracane są w formacie unixsowego znacznika czasu (timestamp), tj. liczba
sekund od 00:00:00 1 stycznia 1970 roku.
4) Wszystkie ciągi tekstowe powinny być zakodowane w UTF-8.
4.1 getToken
Nazwa
funkcji
getToken
Opis
Funkcja autoryzuje użytkownika i pobiera token z systemu. W przypadku tej komendy nie
jest wymagane podpisanie komunikatu (czyli nie trzeba dołączać pola sig)
W celu autoryzacji żadania podajemy:
• userName – login użytkownika, przez którego będą wykonywane operacje
• userDomain – domena użytkownika (zwykle sip.freeconet.pl)
• password – hasło użytkownika (takie samo jak dla panelu)
albo 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
Wejście
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 186400s). Parametr opcjonalny, w przypadku gdy nie zostanie ustawiony zostaje
użyta wartość domyślna 10s
• noAttempts – dopuszczalna ilość sprawdzeń tokenu. Jeśli -1 to nie ma limitu na
ilość sprawdzeń. Wartość domyślna parametru to 1.
Wyjście Zwracane atrybuty sekcji <params>:
• <tokenStr> - stworzony token
Błędy
Możliwe komunikaty błędów:
• invalidValidPeriod – zła wartość validPeriod. Musi się zawierać między 1 a
86400s
• invalidAuthData – zła kombinacja userName/userDomain/password albo
użytkownik nie ma praw do wykonywania funkcji API
Przykład Wywołanie:
użycia
fun=getToken&userName=apidemo&userDomain=sip.freeconet.pl&pass
word=apidemo
Przykładowa odpowiedź:
<response>
<params>
<param name=”tokenStr”
value=”0bfcca72fbad31da6b9087337b468ffb670868a6c45969512df8fc7a9cd05d50”/>
</params>
</response>
4.2 checkToken
Nazwa
funkcji
checkToken
Opis
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.
• tokenStr – token który zostaje sprawdzony
Wejście
Wyjście
Błedy
Zwracane atrybuty sekcji <params>:
• <userName> - login użytkownika
• <userDomain> - domena użytkownika
• invalidCredential – podany token nie istnieje
https://api.freeconet.pl/RestAPI/V1/execute?fun=checkToken&
użycia
tokenStr=815aa4d11b51ffc09b251da76a7bac81283a002442ac64efc031
62922838fb51
Odpowiedź:
<response>
<function>checkToken</function>
<params>
<param name=”userName” value=”apidemo”/>
<param name=”userDomain” value=”sip.freeconet.pl”/>
</params>
</response>
4.3 getFinAccountInfo
Nazwa
funkcji
getGroupFinAccountInfo
Opis
Funkcja pobiera informacje o stanie konta dla grupy
Wejście
Brak parametrów
Wyjście
• <credit> - stan konta
• <debit> - stan należności (tylko dla grup rozliczanych w postpaid)
• <creditLimit> - limit kredytu (tylko dla grup rozliczanych w postpaid)
• <emptyAccountDate> - data kiedy stan konta spadł poniżej 0zł. Jeśli stan jest
powyżej 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
fun=getGroupFinAccountInfo&tokenStr=815aa4d11b51ffc09b251da76a
7bac81283a002442ac64efc03162922838fb51&sig=86cee83a1d14bf7eb8c
7b5f6e94a7dd4
Odpowiedź:
<response>
<params>
value=”0”/>
value=”0”/>
value=”0”/>
</params>
</response>
4.4 makeCall
Nazwa
funkcji
makeCall
Opis
Funkcja zestawia połączenia między dwoma podanymi stronami. W pierwszej kolejności
zestawiane jest połączenie z From a jak zostanie podniesiona słuchawka to z To. Po
stronie panelu usługa posiada możliwość konfiguracji, między innymi można zdefiniować
czarną liste dla numeru A czy też B.
• idService – identyfikator serwisu 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:
Wejście
• from – numer telefoniczny/ id serwisu / nazwa konta
• fromType –
o S - podany jest id serwsiu
o A – podana jest nazwa konta (userName)
o N – podany jest numer telefoniczny
oraz metodę połączenia do abonenta to:
• to – numer telefoniczny / id serwisu / nazwa konta
• toType –
o S - podany jest id serwsiu
o A – podana jest nazwa konta (userName)
o N – podany jest numer telefoniczny
Uwaga. Podnie równocześnie toType oraz fromType na ‘A’ spowoduje zwrócenie
wartości loopDetected
• <callId> - unikalny identyfikator rozmowy w systemie Freeconet.
Błędy
Zwracane błędy:
o loopDetected – wykryto możliwość zapętlenia np. podano równocześnie
w param. wejściowych accFrom oraz accTo
o fromBlackListRej – numer A został odrzucony na podstawie czarnej
listy
o fromWhiteListRej – numer A został odrzucony na podstawie białej listy
(numer niedopuszczony)
o toBlackListRej – numer B został odrzucony na podstawie czarnej listy
o toWhiteListRej – numer B został odrzucony na podstawie białej listy
(numer nie dopuszczony)
o timeMaskRej – połączenie odrzucone ze względu na maskę czasową
o fromServiceNotEnabled – strona A nie może być usługą
o fromAccountNotEnabled – strona A nie może być użytkownikiem
o toServiceNotEnabled – strona B nie może być usługą
o toAccountNotEnabled – strona B nie może być użytkownikiem
o serviceDisabled – usluga wylaczona
o wrongFromNumber – błędny format numeru A
o wrongToNumber – błędny format numeru B
Przykład Wywołanie :
https://api.freeconet.pl/RestAPI/V1/execute?encData=wcBOA%2F
użycia
%2FH0yB8UNK7EAP%2BJhVN294Ema9E4eiPFFcVb%2B9wwsqK2yw2szJKLc5tDgmtaBil48qRK
%2Ftq
%2B1ZZbI0fZl1cspy0q4BZOpgCPm1ALa1%0AqBnfI2I1K6OuN1q8vPl82UJBIAY8SryBy8pCDA
Z9BxyKvg7Vbmzm8CGVeUNku
%2FMgJkAeQ8bLgef4%0AahBesQ16O1pAzBhv3p2A51xxbnEJAjbXAoApC8hf5rqBKX4DbJl3tZ
QJMVotAVhWFHg%2Bxr9f3fRy%0AXhfaXYyT8WWHTmov71SkmPcDqI1YmTfnwpRUg
%2BFekP2d8UtxsMLR5eFdRbnil8EBBn4%3D%0A%3DNM74&from=0895277082
W polu encData są zaszyfrowane następujące dane:
fun=makeCall&userName=apidemo&userDomain=sip.freeconet.pl&password=apidemo
&idService=543452&to=0587311999&toType=N&fromType=N
Odpowiedź:
<response>
<function>makeCall</function>
<params>
<param name=”callId” value=”fsdfs23423423432234324”/>
</params>
</response>
4.5 getBillingCount (od wersji API 1.02)
Nazwa
funkcji
getBillingCount
Opis
Funkcja zlicza ilość wierszy zwracanych w raporcie połączeń dla zadanych kryteriów
wyszukiwania.
Poniżej lista pól definiujących kryterium wyszukiwania
Wejście
• callDir
o out – rozmowy wychodzące
o in – rozmowy przychodzące
• accFrom (opcjonalne) - nazwa użytkownika z którego wychodzą rozmowy.
• accTo (opcjonalne) – nazwa użytkownika do którego przychodzą rozmowy
• callType (opcjonalne) – typ rozmowy
o CHFR– rozmowy w obrębie Freeconet
o LOCC– rozmowy PSTN (np. TPSA)
o CALL,<id operatora> - rozmowy realizowane przez zewnętrznego
operatora VoIP. Jeśli <id operatora> jest puste wyszukiwane są
rozmowy realizowane przez wszystkich operatorów zewnętrznych. W
wersji API 1.0 <id operatora> powinno być puste.
o TELA,<id operatora tela.> - rozmowy przychodzące realizowane
przez operatora Telarenowego Jeśli <id operatora tela.> jest puste
wyszukiwane są rozmowy przychodzące przez wszystkich operatorów
telarenowych. W wersji API 1.0 <id operatora tela.> powinno być
puste.
• isMissed – FALSE są znajdowane rozmowy zrealizowane, TRUE niezrealizowane
• fromDate - data od której wyszukiwane są rozmowy. Data podawana jest w
sekundach które upłyneły od 1 stycznia 1970 (Unix timpestamp).
• toDate - data do której wyszukiwane są rozmowy. Data podawana jest w
Wyjście Zwracane tagi XML:
• <noOfRows> - ilość wyszukanych wierszy
Przykład Chcemy sprawdzić ilość połączeń dla następujących kryterium:
użycia
• Rozmowy wychodząca
• Rozmowy wychodzące z kont apidemo
• Rozmowy telrenowy (bez podani operatora)
• Tylko rozmowe zrealizowane
• Połączeni między 2008-01-01 13:00 a 2008-02-01 14:00
Wywołanie:
https://api.freeconet.pl/RestAPI/V1/execute?fun=getBillingCount&callDir=out
&accFrom=apidemo&callType=TELA&isMissed=false
&fromDate=343434&toDate=354543543534
&tokenStr=0bfcca72fbad31da6b9087337b468ffb670868a6c45969512df8fc7a9cd05d50
&sig=0a6c24a178ed112303e0edbca9040afe
Odpowiedź:
<response>
<function>getBillingCount</function>
<params>
<param name=”noOfRows” value=”1234”/>
</params>
</response>
4.6 getBilling (od wersji API 1.02)
Nazwa
funkcji
getBilling
Opis
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 offsetRow czyli numer wiersza
od którego pobieramy dane. Dodatkowym ograniczeniem jest to, że ilość wybranych
wierszy w systemie (nie koniecznie pobranych) nie może być większa niż 2000 tysiące –
jeśli ten limit zostanie przekroczony zwracany jest błąd maxSelNoRowsExceeded, w
takim wypadku należy zawęzić kryterium wyszukiwania.
Wejście
Poniżej lista pól definiujących kryterium wyszukiwania
• callDir
o out – rozmowy wychodzące
o in – rozmowy przychodzące
• accFrom (opcjonalne) – nazwa użytkownika z którego wychodzą
rozmowy.
• accTo (opcjonalne) – nazwa użytkownika do którego przychodzą rozmowy
• callType (opcjonalne) – typ rozmowy
o CHFR– rozmowy w obrębie Freeconet
o LOCC – rozmowy PSTN (np. TPSA)
o CALL,<id operatora> - rozmowy realizowane przez zewnętrznego
operatora VoIP. Jeśli <id operatora zewn.> jest puste wyszukiwane
są rozmowy realizowane przez wszystkich operatorów zewnętrznych. W
wersji API 1.0 <id operatora zewn.> powinno być puste.
o TELA,<id operatora tela.> - rozmowy przychodzące realizowane
przez operatora Telarenowego. Jeśli <id operatora tela.> jest
puste wyszukiwane są rozmowy przychodzące przez wszystkich
operatorów telarenowych. W wersji API 1.0 <id operatora tela.>
powinno być puste.
• isMissed – FALSE są brane rozmowy niezralizowane, 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
• orderBy – określa po którym polu dokonywane jest sortowanie
o accFrom –konto Od
o accTo –konto Do
o numFrom – numer Od
o numTo – numer Do
o stTime – czas nawiązania połączenia
o callDur – czas trwania połączenia
o callCost – koszt połączenia
o opName – nazwa operatora
o sipRespC – kod odpowiedzi SIP
• orderDesc – kolejność sortowania. False – rosnąco, true – malejąco
• numberOfRows – ilość wierszy do pobrania, maksymalna wartość 200
• offsetRow – od którego wiersza mają byc pobrane dane
• columnList – lista kolumn poprzedzielane znakiem przecinka, które można
pobrać poprzez wywołanie funkcji
o callType - typ rozmowy, możliwe wartości takie jak dla parametru
wejsciowego cType
o accFrom – nazwa konto Od
o accTo – nazwa konto Do
o numFrom – 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 numTo – 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 stTime – czas rozpoczęcia rozmowy. Czas podawany jest w formacie
timpestamp’u Unixowego. Czyli ilości sekund od 1970-01-01 00:00:00
o callDur – czas trwania rozmowy podany sekundach
o callRate – stawka podana w postaci czwórki x0,y0,x1,y1.
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 zl. 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.01zl za każdą rozpoczętą sekundę
o callCost – koszt rozmowy
o opName – nazwa operatora przez którego została zrealizowana rozmowa
o callexFid – aktualnie nie wypełniane
o sipRespC – kod sipowy zakończenia rozmowy
Wyjście
W parametrze <cdrHeader> umieszczona jest lista kolumn (przedzielona przecinkami)
dla danych, które wystąpią w <cdrList>. W <cdrList> będzie przesyłany spis połączeń
w postaci rekordów rozdzielonych znakami CRLF. Każdy rekord będzie zawierał pola
rozdzielone znakami ‘|’ (ang.pipe). Lista pól i ich kolejność jest zdefiniowany przez
<cdrHeader>
Lista kolumn które mogą się pojawić w odpowiedzi została opisane w sekcji
getBillingWejsciecolumnList.
Błędy
Możliwe kody błędów:
• maxSelNoRowsExceeded – przekroczono dopuszczalną liczbę wybranych wierszy
(max.2000).
• maxFetchedNoRoweExceeded – próbowano pobrać więcej niż 200 wierszy w
jednym wywołaniu
Przykład Chcemy pobrać ilość połączeń dla następujących kryterium:
użycia
• Rozmowy wychodząca
• Rozmowy wychodzące z kont apidemo
• Rozmowy telrenowy (bez podania operatora)
• Tylko rozmowę zrealizowane
• Połączeni 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:
https://api.freeconet.pl/RestAPI/V1/execute?fun=getBilling&callDir=out
&accFrom=apidemo&callType=TELA,1&isMissed=false&fromDate=1199192400
&toDate=1201874400&orderBy=callCost&orderDesc=false&numberOfRows=2
&offsetRow=100&columnList=numFrom%2CnumTo%2CcallDur%2CcallCost%2CstTime
&numOfRows=100
&tokenStr=0bfcca72fbad31da6b9087337b468ffb670868a6c45969512df8fc7a9cd05d50
&sig=e3eab6b7e9970324113cf2369a36b025
Odpowiedź:
<response>
<function>getBilling</function>
<params>
<param name=”cdrHeader”
value=”numFrom,numTo,callDur,CallCost,stTime”/>
<param>
<name> cdrData </name>
<value>
<![CDATA[
0895257406|48895257306|233|0.22|1210774923
0893444433|48344444444|33|2.2|1210773923
]]>
</value>
</param>
</params>
</response>
4.7 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 lini oraz skonwertowane do URL Encoding). Uwaga! Funkcja
encryptPGP nie wymaga podawania userName/hasła jak również nie istnieje potrzeba
generowania podpisu.
Wejście
• inputText – tekst do szyfrowania (tekst musi być w postaci URL Encoding)
• userDomain – domena w której zarejestrowany jest użytkownik (dla
użytkownika założonego ze strony www.freeconet.pl pole przyjmuje wartość
‘sip.freeconet.pl’)
• <outputStr> - stworzony token
Błędy
• invalidData – nie udało się wykonać szyfrowania danych, zapewne złe dane
wejściowe.
użycia
fun=encryptPGP&inputText=fun%3DmakeCall%26userName%3Dapidemo
%26userDomain%3Dsip.freeconet.pl%26password%3Dapidemo
%26idService%3D543452%26to%3D0587311999%26toType%3DN
%26fromType%3DN&userDomain=sip.freeconet.pl
Odpowiedź:
<response>
<function>encryptPGP</function>
<params>
<param name=”outputStr”
value=”
wcBOA%2F
%2FH0yB8UNK7EAQAi8PbkTWblkYTGnzEmjtKFnMjIIWJJFcn9VT0Xxcr1pRiK2Pf69rUO9lp
%0A5p8GIHZ%2BhsLsQ2LXll6NO26mqCNEh9IrxOCu0j8NK6PhMB5SSYGPCA3EKYMfoKsm
%2BmSNJXcOCwVr%0AUMvOlg9ydnbmsl2kR4WmEvBnzLj05Jcuxq7%2FfaED%2FA5XId
%2F46OWhTtDWnl%2B0%2BWeZ3%2FrYq7SGmNDw
%0Adb8zr8gA97qt21U9betZOzmCpqs6SgahKrYbyfdpCRMkBpKRhb02FOscu
%2FIuuYqxh6c7E54gXgu%2F
%0A7hy8qiQLTrKZg0E4M1791ldLQZz0Bvh6Sot453enkQVoX1hjObr47r
%2FnnSXx0sAKAasC1W6EZ3KR%0ANoPJgFM6BsMo5ahG2qSKVwVmg8h84bRo
%2FQQcwECFFiWhuvZ1rXhJuEAUPQpdewCsYnZ8ttZa3SIr%0Ahxmrq0ISk
%2BnXO27scgXzv59kila5Xs%2BNOvxPPIXU8ASH17t3lXAn3V%2BULwxl5VlDbi18dZIN6H
%2BH%0A4rps30U%2BZVo7t8FM7tDBLOx2rCdel6T1FslSqZnG
%2BcRVcknrB1NHsY90czdjeZpVRnTGQ4Uz7vG%2F%0AlP9HAL6qOLVoROTQcz
%2F6Z0iVEocHlg%3D%3D%0A%3DFtlO”/>
</params>
</response>
4.8 invalidateToken (od wersji API 1.01)
Nazwa
funkcji
invalidateToken
Opis
Funkcja unieważnia wystawiony token. Token po takiej operacji przestaje być aktywny i
nie jest możliwe wykonywanie operacji z użyciem tego tokena.
• tokenStr – token, który chcemy unieważnić
Wejście
Wyjście
• <tokenStr> - w przypadku udanej operacji w tym parametrze zwracany jest
wartość tokena podanego w parametrach wejściowych
Błędy
• invalidCredential – token nie został znaleziony
użycia
fun=invalidateToken&tokenStr=9358dae31aa89c05dc31171ecebf309ce3dba0b9ea9d
aeb5702091dda4c65908&sig=b802ed9a60fabe9d88b29911b72e943b
Odpowiedź:
<response>
<function>invalidateToken</function>
<params>
<param name="tokenStr"
value="9358dae31aa89c05dc31171ecebf309ce3dba0b9ea9daeb5702091dda4c65908"/
>
</params>
</response>
4.9 getVersion (od wersji API 1.01)
Nazwa
funkcji
getVersion
Opis
Pobranie numeru wersji API – wersja składa się z trzech pól major_ver,
minor_version, build_ver jednoznacznie określających wersje API. W specyfikacji
są odnośniki do wersji w postaci <major_ver>,<minor_version> np. 1.01. Funkcja
nie wymaga dołączania pola sig.
Brak
Wejście
Wyjście
Błędy
• <major_ver> - wersja główna (ang.major version)
• <minor_ver> - wersja mniej ważna (ang.minor version)
• <build ver> - numer kompilacji systemu (ang. build version)
Brak
https://api.freeconet.pl/RestAPI/V1/execute?fun=getVersion
użycia
Odpowiedź:
<response>
<function>getVersion</function>
<params>
<param name="major_ver" value="1"/>
<param name="minor_ver" value="1"/>
<param name="build_ver" value="233"/>
</params>
</response>
5 Opłaty
RestAPI 1.x jest usługą bezpłatną.

Freeconet RestAPI ver.1.01

Transkrypt

Podobne dokumenty

Mobile + Kontekst Otoczenia

1. Zasady korzystania z Usługi Airly API stanowią załącznik do

Instrukcja integracji HP Wall Art ze stroną www

Pobierz zasób - Dane Publiczne