FreecoNet API URLver.3.05.00

Autorzy: M.Szymański, Ł.Umbras-Nichnerowicz, M.Rutkowski Data: 2010-11-24

Strona 1 z 59

SPIS TREŚCI

1 HISTORIA ZMIAN .................................................................................. 4

2 WSTĘP ....................................................................................................... 6

3 OPIS UŻYCIA API ................................................................................... 6 3.1 SKŁADNIA WYWOŁANIA FUNKCJI Z API ......................................................................................................................................... 7 3.2 UWIERZYTELNIANIE ................................................................................................................................................................... 7

3.2.1 Metoda oparta o token ................................................................................................................................................. 8 3.2.2 Metoda oparta o szyfrowanie parametrów żądania ................................................................................................... 10

3.2.2.1 Przykład użycia szyfrowania ................................................................................................................................................ 10 3.2.2.2 Generowanie wartości do pola encData ................................................................................................................................ 14

3.2.3 Porównanie metod autoryzacji ................................................................................................................................... 17 3.2.3.1 Metoda oparta o token .......................................................................................................................................................... 17 3.2.3.2 Metoda oparta o szyfrowanie parametrów żądania ............................................................................................................... 18

3.3 OBSŁUGA BŁĘDÓW ................................................................................................................................................................... 18

4 OPIS FUNKCJI API ................................................................................. 20 4.1 FUNKCJE WSPÓLNE DLA API USER, API PARTNER, API CRM ..................................................................................................... 20

4.1.1 getToken ...................................................................................................................................................................... 20 4.1.2 checkToken .................................................................................................................................................................. 21 4.1.3 encryptPGP ............................................................................................................................................................... 21 4.1.4 invalidateToken ........................................................................................................................................................... 22 4.1.5 getVersion ................................................................................................................................................................. 23 4.1.6 uploadFile ................................................................................................................................................................ 23 4.1.7 deleteFile .................................................................................................................................................................. 24

4.2 FUNKCJE MODUŁU API USER ................................................................................................................................................... 25 4.2.1 getGroupFinAccountInfo ............................................................................................................................................ 25 4.2.2 makeCall ..................................................................................................................................................................... 26 4.2.3 getBilling ................................................................................................................................................................... 28 4.2.4 sendFax ...................................................................................................................................................................... 31 4.2.5 getFaxSent .................................................................................................................................................................. 32 4.2.6 deleteFaxSent ............................................................................................................................................................. 33 4.2.7 restartFaxSent ........................................................................................................................................................... 34 4.2.8 getFaxCampaignFinished .......................................................................................................................................... 35 4.2.9 deleteFaxCampaignFinished ...................................................................................................................................... 36 4.2.10 getFaxReceived ....................................................................................................................................................... 37 4.2.11 getFaxCurrent ......................................................................................................................................................... 39 4.2.12 cancelFaxCurrent .................................................................................................................................................... 40 4.2.13 getFaxCampaignCurrent ......................................................................................................................................... 41 4.2.14 cancelFaxCampaignCurrent ................................................................................................................................... 42 4.2.15 setFaxCampaignCurrentName ................................................................................................................................. 43 4.2.16 setFaxCampaignCurrentTimeMask ......................................................................................................................... 44 4.2.17 startMassDial .......................................................................................................................................................... 44 4.2.18 getMassDialCurrent ................................................................................................................................................ 45 4.2.19 getMassDialCampaignCurrent ............................................................................................................................... 47 4.2.20 cancelMassDialCurrent ........................................................................................................................................... 49 4.2.21 cancelMassDialCampaignCurrent .......................................................................................................................... 50 4.2.22 getMassDialCalled .................................................................................................................................................. 50 4.2.23 getMassDialCampaignFinished .............................................................................................................................. 52 4.2.24 deleteMassDialCalled ............................................................................................................................................. 54 4.2.25 deleteMassDialCampaignFinished ......................................................................................................................... 54 4.2.26 restartMassDialCalled ............................................................................................................................................ 55 4.2.27 setMassDialCampaignCurrentName ........................................................................................................................ 56 4.2.28 setMassDialCampaignCurrentTimeMask ............................................................................................................... 56 4.2.29 getRegistrationStatus ................................................................................................................................................ 57

5 OPŁATY .................................................................................................... 58

Strona 2 z 59

6 ANEKS A .................................................................................................... 58 6.1 STRONICOWANIE DANYCH BEZ WYKORZYSTANIA FUNKCJI ZLICZAJĄCYCH LICZBĘ WSZYSTKICH WIERSZY .................................................. 58

Strona 3 z 59

1 Historia zmianData Wersja

dokumentuOpis

2008-11-07 1.00.00 Pierwsza oficjalna wersja dokumentu2008-11-18 1.01.00 Dodanie funkcji invalidToken2008-11-22 1.01.01 Drobne poprawki treści2008-12-10 1.01.02 Dodanie informacji, że checkToken nie zmniejsza licznika użyć

tokena.2008-12-10 1.01.03 Dodanie funkcji getVersion. Zmiana numeracji wersji API z wersji

platformy na wersje API2008-12-19 1.01.04 Drobne poprawki w opisie szyfrowania2009-02-24 2.00.00 • Wartości w odpowiedzi umieszczane są w elementach a nie

atrybutach XML• Wprowadzenie w wiadomości zwrotnej (XML) sekcji nazwy

funkcji. Sekcja może znajdować się w sekcji 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 2009-06-22 2.01.00 Dodanie możliwości pobrania kolumny z identyfikatorem kampanii

MassDial (batchId) dla funkcji getMassDialCurrent oraz getMassDialCalled

2009-06-23 2.02.00 Dodanie do funkcji startMassDial kodu błędu invalidPresentationNum

2009-06-23 2.03.00 Dodanie do funkcji sendFax / startMassDial parametru campaignName

2009-07-02 2.03.01 Poprawienie w dokumentacji opisu parametrów TRUE/FALSE. Zamiana na true/false.

2009-07-08 2.04.00 Dodanie błędu functionCallLimitsExceeded, dodanie możliwości pobrania kolumny z identyfikatorem kampanii wysyłki faksu (batchId) dla funkcji getFaxCurrent oraz getFaxSent

2009-07-22 2.04.01 Poprawka parametru authSystem dla wszystkich funkcji faksowych, usunięcie parametru fromNum z funkcji getFaxSent oraz getFaxCurrent, aktualizacja parametrów orderBy w funkcji getFaxReceived

2009-08-03 2.05.00 • Dodanie nowego systemu uwierzytelniania – AMCL, realizacja funkcji makeCall z wykorzystaniem tego systemu uwierzytelniania

• Dodanie parametru presentationNum do usługi makeCall2009-09-30 3.00.00 • Utworzenie nowej wersji FreecoNet API opartej o protokół

XML RPC opisanej w innym dokumencie• Wyświetlanie bardziej szczegółowych błędów gdy nie

powiedzie się wysyłka faksów lub start zadań massDial• Dodanie nowych funkcji:

◦ getFaxCampaignCurrentCount◦ getFaxCampaignFinishedCount◦ getFaxCampaignFinished◦ deleteFaxCampaignFinished◦ getFaxCampaignCurrent◦ cancelFaxCampaignCurrent◦ setFaxCampaignCurrentName◦ setFaxCampaignCurrentTimeMask

• Dodano nowe parametry przy wywołaniu funkcji getBillingCount i getBilling

• Dodano pole faxStatus dla funkcji getFaxReceivedCount i getFaxReceived

• Dla funkcji getFaxReceived dodano możliwość zwrócenia rozmiaru pliku w postaci kolumny faxSize

2009-10-29 3.01.00 • Dodanie funkcji:◦ cancelMassDialCampaignCurrent◦ deleteMassDialCampaignFinished◦ getMassDialCampaignCurrentCount◦ getMassDialCampaignCurrent◦ getMassDialCampaignFinishedCount◦ getMassDialCampaignFinished◦ setMassDialCampaignCurrentName◦ setMassDialCampaignCurrentTimeMask

2009-12-07 3.02.00 • Usunięcie funkcji *Count• Zmiana w dopuszczalnych wartościach dla pole orderBy w

funkcji getBilling (startDate, endDate)2010-02-19 3.03.00 • Usunięcie z funkcji getBilling parametru orderBy

• Dodanie do funkcji getBilling kolumny endDate2010-03-18 3.04.00 • Dodanie do funkcji getGroupFinAccountInfo pól

creditToday, creditLimit

2010-11-24 3.05.00 • Dodanie do funkcji getBilling kolumny callId

2 WstępPrzedstawione 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 FreecoNet URL API ver.3.x oparte o wymianę parametrów poprzez popularny mechanizm bazujący na żądaniach HTTPS GET/POST. Użycie URL API 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 FreecoNet

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 APIJak już zostało wspomniane we wstępie komunikacja między klientem a platformą FreecoNet oparta jest 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 /URL/V3/execute? fun=getGroupFinAccountInfo&tokenStr=815aa4d11b51ffc09b251da76a7bac81283a002442ac64efc03162922838fb51&sig=86cee83a1d14bf7eb8c7b5f6e94a7dd4

W odpowiedzi klient otrzymuje XML w postaci:

0 0 0

6 z 59

https://apiuser.freeconet.pl/RestAPI/V2/execute?fun=getGroupFinAccountInfo&tokenStr=815aa4d11b51ffc09b251da76a7bac81283a002442ac64efc03162922838fb51&sig=86cee83a1d14bf7eb8c7b5f6e94a7dd4https://apiuser.freeconet.pl/RestAPI/V2/execute?fun=getGroupFinAccountInfo&tokenStr=815aa4d11b51ffc09b251da76a7bac81283a002442ac64efc03162922838fb51&sig=86cee83a1d14bf7eb8c7b5f6e94a7dd4https://apiuser.freeconet.pl/RestAPI/V2/execute?fun=getGroupFinAccountInfo&tokenStr=815aa4d11b51ffc09b251da76a7bac81283a002442ac64efc03162922838fb51&sig=86cee83a1d14bf7eb8c7b5f6e94a7dd4https://apiuser.freeconet.pl/RestAPI/V2/execute?fun=getGroupFinAccountInfo&tokenStr=815aa4d11b51ffc09b251da76a7bac81283a002442ac64efc03162922838fb51&sig=86cee83a1d14bf7eb8c7b5f6e94a7dd4https://apiuser.freeconet.pl/RestAPI/V2/execute?fun=getGroupFinAccountInfo&tokenStr=815aa4d11b51ffc09b251da76a7bac81283a002442ac64efc03162922838fb51&sig=86cee83a1d14bf7eb8c7b5f6e94a7dd4http://techblog.freeconet.pl/http://techblog.freeconet.pl/http://techblog.freeconet.pl/

Analizując XML widzimy, że stan konta, kwota należności i limit dla grupy to 0 PLN. Kwota inna niż 0 PLN dla należności i limitu występują tylko dla grup, które rozliczają się z FreecoNet w oparciu o postaid. Jako, że w odpowiedzi nie wystąpił tag oznacza, że operacja przebiegła pomyślnie.

Jak widać wywołanie funkcjonalności z FreecoNet URL 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 APIW celu wywołania funkcji z API należy stworzyć URL składający się z paru obowiązkowych części.

Gdzie:1 - komunikacja odbywa się po szyfrowanym protokole HTTPS2 –część URL, adres pod którym umieszczone jest API. 3 - część URL, pod którą umieszczone są zasoby FreecoNet URL. Dla wszystkich funkcji zaprezentowanych w tym dokumencie ta część przyjmuje wartość URL4 – 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 paneluhttps://apipartner. freeconet.pl - dla modułu partnerahttps://apicrm. freeconet.pl - dla modułu CRM

3.2 UwierzytelnianieW 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• AMCL – użytkownik usługi Zestaw połączenie

7 z 59

https://apiuser.freeconet.pl/URL/V3/execute?encData=23ffsdf..

1 2 3 4 5

https://apicrm/https://apicrm/https://apipartner/https://apipartner/https://apiuser/https://apiuser/https://wizard.freeconet.pl/https://wizard.freeconet.pl/

Jeśli parametr nie jest podany w żądaniu, domyślnie przyjmowana jest wartość USER.

3.2.1 Metoda oparta o tokenW 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.

https://apiuser. freeconet.pl /URL/V3/execute? fun=getToken&userName=apidemo&password=apidemo&authSystem=USER&validPeriod=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)

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, AMCL – użytkownik usługi Zestaw połączenie (Api Make Call). 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, Faks i Zestaw połączenie należy odpowiednio rejestrować się na system MASD, FAXV i AMCL, 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

815aa4d11b51ffc09b251da76a7bac81283a002442ac64efc03162922838fb51

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.

8 z 59

https://apiuser.freeconet.pl/RestAPI/V2/execute?fun=getToken&userName=apidemo&password=apidemo&authSystem=USER&validPeriod=10000https://apiuser.freeconet.pl/RestAPI/V2/execute?fun=getToken&userName=apidemo&password=apidemo&authSystem=USER&validPeriod=10000https://apiuser.freeconet.pl/RestAPI/V2/execute?fun=getToken&userName=apidemo&password=apidemo&authSystem=USER&validPeriod=10000https://apiuser.freeconet.pl/RestAPI/V2/execute?fun=getToken&userName=apidemo&password=apidemo&authSystem=USER&validPeriod=10000https://apiuser.freeconet.pl/RestAPI/V2/execute?fun=getToken&userName=apidemo&password=apidemo&authSystem=USER&validPeriod=10000

Jeśli operacja nie przebiegnie pomyślnie np. źle podane hasło w sekcji pojawi się sekcja (dokładny opis zwracanych wartości umieszczony jest w rozdziale - 3.3 Obsługabłędów) np.

invalidToken Token expired or is invalid

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. https://apiuser. freeconet.pl /URL/V3/execute? fun=getGroupFinAccountInfo&tokenStr=815aa4d11b51ffc09b251da76a7bac81283a002442ac64efc03162922838fb51&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(‘fungetGroupFinAccountInfotokenStr815aa4d11b51ffc09b251da76a7bac81283a002442ac64efc03162922838fb51953a3220084d73ea9948e3046c3c242d’)= 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.

9 z 59

http://pl.wikipedia.org/wiki/MD5https://apiuser.freeconet.pl/RestAPI/V2/execute?fun=getGroupFinAccountInfo&tokenStr=815aa4d11b51ffc09b251da76a7bac81283a002442ac64efc03162922838fb51&sig=86cee83a1d14bf7eb8c7b5f6e94a7dd4https://apiuser.freeconet.pl/RestAPI/V2/execute?fun=getGroupFinAccountInfo&tokenStr=815aa4d11b51ffc09b251da76a7bac81283a002442ac64efc03162922838fb51&sig=86cee83a1d14bf7eb8c7b5f6e94a7dd4https://apiuser.freeconet.pl/RestAPI/V2/execute?fun=getGroupFinAccountInfo&tokenStr=815aa4d11b51ffc09b251da76a7bac81283a002442ac64efc03162922838fb51&sig=86cee83a1d14bf7eb8c7b5f6e94a7dd4https://apiuser.freeconet.pl/RestAPI/V2/execute?fun=getGroupFinAccountInfo&tokenStr=815aa4d11b51ffc09b251da76a7bac81283a002442ac64efc03162922838fb51&sig=86cee83a1d14bf7eb8c7b5f6e94a7dd4https://apiuser.freeconet.pl/RestAPI/V2/execute?fun=getGroupFinAccountInfo&tokenStr=815aa4d11b51ffc09b251da76a7bac81283a002442ac64efc03162922838fb51&sig=86cee83a1d14bf7eb8c7b5f6e94a7dd4

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 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:

0 0 0

W wyniku tej operacji ważność tokena ustawiana jest na kolejne 10000 sekund.

3.2.2 Metoda oparta o szyfrowanie parametrów żądaniaW 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 szyfrowaniaZałóż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 (‘KonfiguracjaUsługiDodaj nową usługę’ i wybrać usługę ‘Zestaw połączenie’) i ustawić jak na poniższym ekranie:

10 z 59

11 z 59

Samo zainicjowanie połączenia następuje po wysłaniu do serwera następujące żądania1

Gdzie: 1 – standardowy adres API User2 – 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 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 KonfiguracjaUsługi i wybieramy zdefiniowaną usługę ‘Zestaw połączenie’ i przechodzimy do zakładki ‘kontrolka’. Wpisujemy ustawienia jak na ekranie poniżej:

1 Ze względu, że na koncie testowym jest zerowy stan konta można jedynie podać numer z FreecoNet.12 z 59

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

1 2

3

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, 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 Wartość Zaszyfrowane Uwagi

Funkcja (fun) makeCall TAKNazwa konta (userName) 60 TAK W przypadku usług nazwa konta to

13 z 59

identyfikator usługiHasło (password) apidemo TAK Należy wpisać hasło dla podanego

wyżej użytkownika. W przypadku należy podać hasło wprowadzone podczas konfiguracji usługi

System autoryzacji (authSystem)

AMCL TAK Moduł autoryzacji. Jeśli ten parametr nie zostanie podany przyjmowana jest wartość USER

Numer do (to) 0587311999 TAK Numer BOK na który dzwonimyTyp strony Do (toType) N TAK Podany może być jedynie numerTyp strony Od (fromType)

N TAK Podany może być jedynie numer

Interesujący nas URL jest w postaci:

https://apiuser.freeconet.pl/URL/V3/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=

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://apiuser.freeconet.pl/URL/V3/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

Dla typowej sytuacji możemy skorzystać z całego kodu kontrolki wygenerowanego na stronie.

3.2.2.2 Generowanie wartości do pola encDataW 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 URL używana jest metody szyfrowania DSA/Elgamal z 1024 bitowym kluczem publicznym (więcej o DSA/Elgamal i o asymetrycznym szyfrowaniu na stronie

14 z 59

http://pl.wikipedia.org/wiki/Kryptografia_asymetryczna ).

Poniżej klucz publiczny dla URL API podany w formacie programu GnuPg (http://www.gnupg.org/) :-----BEGIN PGP PUBLIC KEY BLOCK-----Version: GnuPG v1.4.9 (MingW32)

mQGiBEiN2BARBACiu8YcoZ0fg1/twKRSifKAii0jAPyCKWBCKlTa3F+HAVe4jUHm8/ZdPauS7a0+AkN/YqiALwM3wJyyCGwWKJPkdGtrjPnWsVIO4jRS0OGDjkHEFUIj0+TeZk1sU6Hj/HhFtTkapObbUx1P6+8pYEWQoAiZHXv+5f9x1+GMppoeEwCghctllkN+mgrj02fpIdLj6JMbl2EEAJAQLc9wlAic6sN5ibhqEtF03hAQRRUuvEiklwKqanwxfxwEGOBee7vEaxA6B6bDZsTPzkZbKBfBbvd+KH/6j1alltFSL7HjNILEFqsh9rZxUyFT1GmEdjA0NsQgW3CppEv43crWEK4NibxfLrbkNKwms442zUT3mdL5KUnR7wfbA/9i7rFPNDcsWi7O+KlNhiIK6X44ogRXkvtKvsHiqTbyhUG8uoyWXG3Y+teDDSg6RBit/RnLUbO0p0l7shWOv8SZx8Z4xuw5sQVsXFyXPiliYm93WJgpnqHe/jtpmOyTzMLZk8IeTRxfIAkvBv9O8SvxGTk1Gy7nwxXemgiMV/efjrRJRnJlZWNvbmV0IFJlc3RBUEkgKEZyZWVjb25ldCBSZXN0QVBJIERFUy9FbGdhbWFsIGtleXMpIDxhcGlAZnJlZWNvbmV0LnBsPohgBBMRAgAgBQJIjdgQAhsDBgsJCAcDAgQVAggDBBYCAwECHgECF4AACgkQIix00gUvRyi53QCcD+2vbU9wSTmLSK3IAmt/tEoB/OcAn0FZzuoaD8XyNYgbgr51ULE7tXYiuQENBEiN2BAQBACa6OT1G/UNiK4v2eyWqDNG/lSU3+2wwvUSYKQ6dXYPxc87BZDuLiJjjgkSU7ovqu+Hz/xdAluxhZ8A44/lnhdniyE0x8aHWXOvBfAnEDEjoYP5xU8i30ohs5cymr3l+FS4PPongyVoSN134cBMpYZW8fynXjdvyVFoZ3QCnx1gpwADBQP9FAJgDhgOSs4W/3XV463epf+eiruv5L8qqn1S4CQwCi49U3ce9KmNk+NjKVFDD0WLsDYN4+2wKviSGl/bbMmhZOpH/h2dLqhaWYDcX+jVsh3rYuHb5Oc1gdSrNgTfGGGBZX5/lzDq3kdBc3uWL6V0vf4mIzNoQdBt63fwwsa8RtSISQQYEQIACQUCSI3YEAIbDAAKCRAiLHTSBS9HKEp7AJ9RidMYO4WJ43N2RMP2iVtrKXVqdQCeJpf+bNYSFLxZD8AmZ0La+1iCvcw==mDNs-----END PGP PUBLIC KEY BLOCK-----

Klucz ten można również pobrać ze strony :https://apiuser.freeconet.pl/certificates/URLAPI_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 URL_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 URL_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=60&password=apidemo&authSystem=AMCL&to=0587311999&toType=N&fromType=N

15 z 59

http://www.gnupg.org/http://www.gnupg.org/http://pl.wikipedia.org/wiki/Kryptografia_asymetryczna

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=60&password=apidemo&authSystem=AMCL&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.txtYou did not specify a user ID. (you may use "-r")

Current recipients:

Enter the user ID. End with an empty line: api@freeconet.plgpg: 7C50D2BB: There is no assurance this key belongs to the named user

pub 1024g/7C50D2BB 2008-07-28 FreecoNet URL (FreecoNet URL DES/Elgamalkeys) 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 namedin 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 URL (FreecoNet URL DES/Elgamal keys) "

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/RkeYDuYSeANStQi0MadQo5EHkPVNS7uADXkLTYde4Uug7uV6NEzNsnTOboRQx+48e2lsa4qltYd+RPtfI9TW/JOEhYENwuz1zBTvOw1uX9gUN5gs2yMrOn9anB31wi8i4I0TUnwfmSczTatc7PTuHUjnH99Zssqcll7NC55LMWkD/0rFdb34/XwoHG20+YDJ9EJ2UDcKiJ1e6I5JNmcd3YEElp9xhiS7bV6iYnXpDKi5l7KJKUcTMboGsY7Nvn172/9t88ksb2PyM7JPwa9VQUO6H9Ptn22VctkBym272lvRDF3nX8BSC8+b5PFlWUKirwYgI+DgTyB1B8Gjsksp4D460pIBQymN5RF8dZp0

16 z 59

http://www.faqs.org/rfcs/rfc1738http://www.albionresearch.com/misc/urlencode.phphttp://www.albionresearch.com/misc/

8kdozH9izVc98ZRuLFBrS6TtaM5gEj+SritQe3W+2EX7TnwhfrWd68EvQUjFR8XdecpyN/il7ykQOY0VXI5nXHqbBxFSLdU/JPYFDTcZiE0FfHpa6bh5ZWQjvSOwFrAIwocOMDcPsMVZOJTKqlha2Xaenzw5a3hejcdK7dDWZ97CZJ+/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+UnwfmSczTatc7PTuHUjnH99Zssqcll7NC55LMWkD%2F0rFdb34%2FXwoHG20%2BYDJ9EJ2UDcKiJ1e6I5J+Nmcd3YEElp9xhiS7bV6iYnXpDKi5l7KJKUcTMboGsY7Nvn172%2F9t88ksb2PyM7JPwa9VQUO6H9Pt+n22VctkBym272lvRDF3nX8BSC8%2Bb5PFlWUKirwYgI%2BDgTyB1B8Gjsksp4D460pIBQymN5RF8dZp0+8kdozH9izVc98ZRuLFBrS6TtaM5gEj%2BSritQe3W%2B2EX7TnwhfrWd68EvQUjFR8XdecpyN%2Fil7ykQ+OY0VXI5nXHqbBxFSLdU%2FJPYFDTcZiE0FfHpa6bh5ZWQjvSOwFrAIwocOMDcPsMVZOJTKqlha2Xae+nzw5a3hejcdK7dDWZ97CZJ%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.

https://apiuser.freeconet.pl/URL/V3/execute?encData=wcBOA%2F%2FH0yB8UNK7EAP%2FRkeYDuYSeANStQi0MadQo5EHkPVNS7uADXkLTYde4Uug7uV6NEzNsnTO+boRQx%2B48e2lsa4qltYd%2BRPtfI9TW%2FJOEhYENwuz1zBTvOw1uX9gUN5gs2yMrOn9anB31wi8i4I0T+UnwfmSczTatc7PTuHUjnH99Zssqcll7NC55LMWkD%2F0rFdb34%2FXwoHG20%2BYDJ9EJ2UDcKiJ1e6I5J+Nmcd3YEElp9xhiS7bV6iYnXpDKi5l7KJKUcTMboGsY7Nvn172%2F9t88ksb2PyM7JPwa9VQUO6H9Pt+n22VctkBym272lvRDF3nX8BSC8%2Bb5PFlWUKirwYgI%2BDgTyB1B8Gjsksp4D460pIBQymN5RF8dZp0+8kdozH9izVc98ZRuLFBrS6TtaM5gEj%2BSritQe3W%2B2EX7TnwhfrWd68EvQUjFR8XdecpyN%2Fil7ykQ+OY0VXI5nXHqbBxFSLdU%2FJPYFDTcZiE0FfHpa6bh5ZWQjvSOwFrAIwocOMDcPsMVZOJTKqlha2Xae+nzw5a3hejcdK7dDWZ97CZJ%2B%2FPoFO3w%3D%3D+%3Dbumf&from=0895277082

3.2.3 Porównanie metod autoryzacjiPoniż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 tokenZalety

• 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

17 z 59

http://www.w3schools.com/TAGS/ref_urlencode.asp

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 żądaniaZalety

• 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.

Należy zaznaczyć, że obie metody mogą być używane równocześnie w obrębie jednej aplikacji..

3.3 Obsługa błędówW przypadkach gdy wystąpi błąd przy realizacji wywoływanej funkcji zwracany jest sekcja (w sekcji nazwy funkcji) składająca się z elementów które opisują z jakim błędem albo błędami mamy do czynienia.

Przykładowa odpowiedź, z informacją o błędzie.

18 z 59

http://en.wikipedia.org/wiki/Single_sign-on

invalidCredentials Invalid userName, password or authSystem

Przy opisie każdej funkcji zostały wymienione możliwe wartości .

Jeśli pojawi się błąd, który nie można powiązać z wywołaniem funkcji sekcja funkcji w może nie istnieć np.

indvalidSignature Invalid signature

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 żą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

api@freeconet.pl• functionCallLimitsExceeded – pojawiło się za dużo zapytań do API o daną funkcję.

Należy ponowić próbę w późniejszym czasie.• 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 )

19 z 59

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 password3) 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 getTokenNazwa funkcji

getToken

Opis 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.

Wejście W celu autoryzacji żądania podajemy: • userName – login użytkownika / identyfikator usługi • password – hasło użytkownika / usługi

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 USERWyjście Zwracane wartości:

- stworzony token

20 z 59

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 APIPrzykład użycia

Wywołanie:https://apiuser. freeconet.pl /URL/V3/execute? fun=getToken&userName=apidemo&password=apidemo

Przykładowa odpowiedź:

0bfcca72fbad31da6b9087337b468ffb670868a6c45969512df8fc7a9cd05d50

4.1.2 checkTokenNazwa 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.

Wejście • tokenStr – token który zostaje sprawdzonyWyjście Zwracane znaczniki elementu :

• - login użytkownika• - system w którym przebiegło uwierzytelnianie

Błędy • invalidCredentials – podany token nie istniejePrzykład użycia

Wywołanie:https://apiuser. freeconet.pl /URL/V3/execute?fun=checkToken& tokenStr=815aa4d11b51ffc09b251da76a7bac81283a002442ac64efc03162922838fb51

Odpowiedź:

apidemo USER

4.1.3 encryptPGP Nazwa funkcji

encryptPGP

21 z 59

https://apiuser.freeconet.pl/RestAPI/V2/execute?fun=checkToken&%20tokenStr=815aa4d11b51ffc09b251da76a7bac81283a002442ac64efc03162922838fb51https://apiuser.freeconet.pl/RestAPI/V2/execute?fun=checkToken&%20tokenStr=815aa4d11b51ffc09b251da76a7bac81283a002442ac64efc03162922838fb51https://apiuser.freeconet.pl/RestAPI/V2/execute?fun=checkToken&%20tokenStr=815aa4d11b51ffc09b251da76a7bac81283a002442ac64efc03162922838fb51https://apiuser.freeconet.pl/RestAPI/V2/execute?fun=checkToken&%20tokenStr=815aa4d11b51ffc09b251da76a7bac81283a002442ac64efc03162922838fb51https://apiuser.freeconet.pl/RestAPI/V2/execute?fun=getToken&userName=apidemo&password=apidemohttps://apiuser.freeconet.pl/RestAPI/V2/execute?fun=getToken&userName=apidemo&password=apidemohttps://apiuser.freeconet.pl/RestAPI/V2/execute?fun=getToken&userName=apidemo&password=apidemohttps://apiuser.freeconet.pl/RestAPI/V2/execute?fun=getToken&userName=apidemo&password=apidemo

Opis 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 :

- stworzony token Błędy Możliwe komunikaty błędów:

• invalidData – nie udało się wykonać szyfrowania danych, zapewne złe dane wejściowe.

Przykład użycia

Wywołanie:https://apiuser. freeconet.pl /URL/V3/execute?fun=encryptPGP&inputText=fun %3DmakeCall%26userName%3Dapidemo%26password%3Dapidemo%26idService%3D543452%26to%3D0587311999%26toType%3DN%26fromType%3DN

Odpowiedź:

wcBOA%2F%2FH0yB8UNK7EAQAibQEBMsX8aCXP%2Bh3M%2BdQEWgNRLIstz%2F9EKY6Auox0q66z4scOwoUxnae%0ArrKYU8U5L3j8rpKK1Xv%2BXP5dQ%2FhOqeQnl7UHPYRRzJDKXJRmgSMZwdAOujfXVmXiKNUsjDX2wpoz%0ArZsI%2Bd0NNfUZ2TUVbQjP458vXFvKq%2FBaCGQtWr8D%2FidMTSwSfYCbu0jHxOwbDgr8h9O9TNw4uKlT%0AND%2ByWTC0FDgQfIODlhj1jH6BNtHh9CWHMPPfcS4b%2Ft7ccYsPF2L0YzHISY1PjDXGbHcAAFPrgGmw%0A0WbEW8Gos7VnBCdXz1I0DJvQ3v6WVQEl7UVfI2Q2y3k0WnYevZPfLU735pGg0pIBr0J3tPULxPdy%0ARgIyy9iJ3GEe2vHqIVXliGec1JIonVLDuDwuRuC9IYx44%2F9jHTxlnqpgpH6TNEiNh01eoxVExlGN%0Ath5TmevPLgRQUQp49eodO4LyN7%2F5UGXREX05PFlQRUY9GF9QKG%2FteFgT4B%2BpKt8tnLe990MWe%2BSn%0A4mVpu63SePClkh%2FPGmqtzVx9DLSAPw%3D%3D%0A%3DRPDf

4.1.4 invalidateTokenNazwa 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. W przypadku tej komendy nie jest wymagane podpisanie komunikatu (czyli nie trzeba dołączać pola sig).

Wejście • tokenStr – token, który chcemy unieważnićWyjście Zwracane znaczniki sekcji :

- w przypadku udanej operacji w tym parametrze zwracana jest wartość tokena podanego w parametrach wejściowych

Błędy Możliwe komunikaty błędów:

22 z 59

https://apiuser.freeconet.pl/RestAPI/V2/execute?fun=encryptPGP&inputText=fun=makeCall&userName=apidemo&password=apidemo&idService=543452&to=0587311999&toType=N&fromType=Nhttps://apiuser.freeconet.pl/RestAPI/V2/execute?fun=encryptPGP&inputText=fun=makeCall&userName=apidemo&password=apidemo&idService=543452&to=0587311999&toType=N&fromType=Nhttps://apiuser.freeconet.pl/RestAPI/V2/execute?fun=encryptPGP&inputText=fun=makeCall&userName=apidemo&password=apidemo&idService=543452&to=0587311999&toType=N&fromType=Nhttps://apiuser.freeconet.pl/RestAPI/V2/execute?fun=encryptPGP&inputText=fun=makeCall&userName=apidemo&password=apidemo&idService=543452&to=0587311999&toType=N&fromType=Nhttps://apiuser.freeconet.pl/RestAPI/V2/execute?fun=encryptPGP&inputText=fun=makeCall&userName=apidemo&password=apidemo&idService=543452&to=0587311999&toType=N&fromType=Nhttp://sunsite.icm.edu.pl/gnupg/rfc2440-6.html

• invalidCredentials – token nie został znalezionyPrzykład użycia

Wywołanie:https://apiuser. freeconet.pl /URL/V3/execute? fun=invalidateToken&tokenStr=9358dae31aa89c05dc31171ecebf309ce3dba0b9ea9daeb5702091dda4c65908&sig=b802ed9a60fabe9d88b29911b72e943b

Odpowiedź:

9358dae31aa89c05dc31171ecebf309ce3dba0b9ea9daeb5702091dda4c65908

4.1.5 getVersion Nazwa funkcji

getVersion

Opis 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 , np. 2.01. Funkcja nie wymaga dołączania pola sig.

Wejście BrakWyjście Zwracane znaczniki sekcji :

• - wersja główna (ang. major version)• - wersja mniej ważna (ang. minor version)• - numer kompilacji systemu (ang. build version)

Błędy BrakPrzykład użycia

Wywołanie:https://apiuser. freeconet.pl /URL/V3/execute?fun=getVersion

Odpowiedź:

2 0 0

4.1.6 uploadFile Nazwa funkcji

uploadFile

23 z 59

https://apiuser.freeconet.pl/RestAPI/V2/execute?fun=getVersionhttps://apiuser.freeconet.pl/RestAPI/V2/execute?fun=getVersionhttps://apiuser.freeconet.pl/RestAPI/V2/execute?fun=getVersionhttps://apiuser.freeconet.pl/RestAPI/V2/execute?fun=invalidateToken&tokenStr=9358dae31aa89c05dc31171ecebf309ce3dba0b9ea9daeb5702091dda4c65908&sig=b802ed9a60fabe9d88b29911b72e943bhttps://apiuser.freeconet.pl/RestAPI/V2/execute?fun=invalidateToken&tokenStr=9358dae31aa89c05dc31171ecebf309ce3dba0b9ea9daeb5702091dda4c65908&sig=b802ed9a60fabe9d88b29911b72e943bhttps://apiuser.freeconet.pl/RestAPI/V2/execute?fun=invalidateToken&tokenStr=9358dae31aa89c05dc31171ecebf309ce3dba0b9ea9daeb5702091dda4c65908&sig=b802ed9a60fabe9d88b29911b72e943bhttps://apiuser.freeconet.pl/RestAPI/V2/execute?fun=invalidateToken&tokenStr=9358dae31aa89c05dc31171ecebf309ce3dba0b9ea9daeb5702091dda4c65908&sig=b802ed9a60fabe9d88b29911b72e943bhttps://apiuser.freeconet.pl/RestAPI/V2/execute?fun=invalidateToken&tokenStr=9358dae31aa89c05dc31171ecebf309ce3dba0b9ea9daeb5702091dda4c65908&sig=b802ed9a60fabe9d88b29911b72e943b

Opis 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).

Wejście Dane powinny być przesyłane zgodnie z metodą POST. (patrz Przykład użycia). Parametr w metodzie POST wskazujący plik powinien nazywać się:

Wyjście Zwracane tagi XML: - identyfikator dokumentu pliku dodanego przez klienta (string)

Błędy Możliwe komunikaty błędów:• fileSizeExceeded – przekroczono dozwolony rozmiar pliku • fileLimitExceeded – przekroczono dozwoloną ilość plików • fileTransmissionError – błąd transmisji pliku

Przykład użycia

Wywołanie:

Poniżej przykładowy kod źródłowy w języku HTML pokazujący użycie funkcji uploadFile

Odpowiedź:

plik_1234.txt

4.1.7 deleteFile Nazwa funkcji

deleteFile

Opis Funkcja umożliwia usunięcie wcześniej przesłanego plikuWejście - identyfikator dokumentu pliku, który ma zostać skasowanyWyjście Zwracane tagi XML:

- identyfikator dokumentu pliku skasowanegoBłędy Możliwe komunikaty błędów:

• invalidFileDocumentId – nie znaleziono pliku o podanym identyfikatorzePrzykład Wywołanie:

24 z 59

użyciahttps://apiuser. freeconet.pl /URL/V3/execute? fun=deleteFile&fileDocumentId=plik_1234.txt&tokenStr=815aa4d11b51ffc09b251da76a7bac81283a002442ac64efc03162922838fb51&sig=767848d05b5fbc9c39806586fbcb8a28

Odpowiedź:

plik_1234.txt

4.2 Funkcje modułu API User

4.2.1 getGroupFinAccountInfoNazwa funkcji

getGroupFinAccountInfo

Opis Funkcja pobiera informacje o saldzie konta dla grupyWejście Brak parametrówWyjście Zwracane znaczniki sekcji :

• - stan środków łącznie w PLN• - stan środków dostępnych dzisiaj w PLN• - dzienny limit środków w PLN• - stan zobowiązań (tylko dla grup rozliczanych w postpaid)• - limit kredytu (tylko dla grup rozliczanych w postpaid)• - 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 użycia

Wywołanie dla konta apidemo:https://apiuser. freeconet.pl /URL/V3/execute? fun=getGroupFinAccountInfo&tokenStr=815aa4d11b51ffc09b251da76a7bac81283a002442ac64efc03162922838fb51&sig=86cee83a1d14bf7eb8c7b5f6e94a7dd4

Odpowiedź:

0 0 10000 0 0

25 z 59

https://apiuser.freeconet.pl/RestAPI/V2/execute?fun=getGroupFinAccountInfo&tokenStr=815aa4d11b51ffc09b251da76a7bac81283a002442ac64efc03162922838fb51&sig=86cee83a1d14bf7eb8c7b5f6e94a7dd4https://apiuser.freeconet.pl/RestAPI/V2/execute?fun=getGroupFinAccountInfo&tokenStr=815aa4d11b51ffc09b251da76a7bac81283a002442ac64efc03162922838fb51&sig=86cee83a1d14bf7eb8c7b5f6e94a7dd4https://apiuser.freeconet.pl/RestAPI/V2/execute?fun=getGroupFinAccountInfo&tokenStr=815aa4d11b51ffc09b251da76a7bac81283a002442ac64efc03162922838fb51&sig=86cee83a1d14bf7eb8c7b5f6e94a7dd4https://apiuser.freeconet.pl/RestAPI/V2/execute?fun=getGroupFinAccountInfo&tokenStr=815aa4d11b51ffc09b251da76a7bac81283a002442ac64efc03162922838fb51&sig=86cee83a1d14bf7eb8c7b5f6e94a7dd4https://apiuser.freeconet.pl/RestAPI/V2/execute?fun=getGroupFinAccountInfo&tokenStr=815aa4d11b51ffc09b251da76a7bac81283a002442ac64efc03162922838fb51&sig=86cee83a1d14bf7eb8c7b5f6e94a7dd4https://apiuser.freeconet.pl/RestAPI/V2/execute?fun=deleteFile&fileDocumentId=plik_1234.txt&tokenStr=815aa4d11b51ffc09b251da76a7bac81283a002442ac64efc03162922838fb51&sig=767848d05b5fbc9c39806586fbcb8a28https://apiuser.freeconet.pl/RestAPI/V2/execute?fun=deleteFile&fileDocumentId=plik_1234.txt&tokenStr=815aa4d11b51ffc09b251da76a7bac81283a002442ac64efc03162922838fb51&sig=767848d05b5fbc9c39806586fbcb8a28https://apiuser.freeconet.pl/RestAPI/V2/execute?fun=deleteFile&fileDocumentId=plik_1234.txt&tokenStr=815aa4d11b51ffc09b251da76a7bac81283a002442ac64efc03162922838fb51&sig=767848d05b5fbc9c39806586fbcb8a28https://apiuser.freeconet.pl/RestAPI/V2/execute?fun=deleteFile&fileDocumentId=plik_1234.txt&tokenStr=815aa4d11b51ffc09b251da76a7bac81283a002442ac64efc03162922838fb51&sig=767848d05b5fbc9c39806586fbcb8a28https://apiuser.freeconet.pl/RestAPI/V2/execute?fun=deleteFile&fileDocumentId=plik_1234.txt&tokenStr=815aa4d11b51ffc09b251da76a7bac81283a002442ac64efc03162922838fb51&sig=767848d05b5fbc9c39806586fbcb8a28

4.2.2 makeCallNazwa funkcji

makeCall

Uwaga!W przypadku wersji 2 parametrowej autoryzacja odbywa się z loginem i hasłem użytkownika FreecoNet.

W przypadku wersji z większą ilością parametrów autoryzacja odbywa się loginem (identyfikator usługi np. '999' ) oraz hasłem z usługi Zestaw Połączenie zamiast loginem i hasłem użytkownika panelu, autoryzować należy się na system authSystem=AMCL. Identyfikator usługi wyświetlany jest na ekranie konfiguracji usługi

Opis 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 ifrom, fromType, to, toType. Wywołanie wymaga zdefiniowania 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. Uwierzytelnianie odbywa się na podany w konfiguracji identyfikator usługi, zdefiniowane przez użytkownika hasło i authSystem=AMCL.

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.

Wejście Należ wybrać metodę połączenia do abonenta from:• from – numer telefoniczny/ id usługi / nazwa konta • fromType

o S - podany jest identyfikator usługi (np. SID999)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 identyfikator usługi (np. SID999)o A – podana jest nazwa konta (userName)o N – podany jest numer telefoniczny

Parametr opcjonalny:• presentationNum – numer, którym będzie się prezentować usługa

Uwaga. Podanie równocześnie toType oraz fromType na ‘A’ spowoduje

26 z 59

zwrócenie wartości loopDetectedWyjście Zwracane znaczniki sekcji :

• - unikalny identyfikator rozmowy w systemie FreecoNet. Błędy 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• 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 użycia

Wywołanie :https://apiuser.freeconet.pl/URL/V3/execute?encData=wcBOA%2F%2FH0yB8UNK7EAP%2FRkeYDuYSeANStQi0MadQo5EHkPVNS7uADXkLTYde4Uug7uV6NEzNsnTO+boRQx%2B48e2lsa4qltYd%2BRPtfI9TW%2FJOEhYENwuz1zBTvOw1uX9gUN5gs2yMrOn9anB31wi8i4I0T+UnwfmSczTatc7PTuHUjnH99Zssqcll7NC55LMWkD%2F0rFdb34%2FXwoHG20%2BYDJ9EJ2UDcKiJ1e6I5J+Nmcd3YEElp9xhiS7bV6iYnXpDKi5l7KJKUcTMboGsY7Nvn172%2F9t88ksb2PyM7JPwa9VQUO6H9Pt+n22VctkBym272lvRDF3nX8BSC8%2Bb5PFlWUKirwYgI%2BDgTyB1B8Gjsksp4D460pIBQymN5RF8dZp0+8kdozH9izVc98ZRuLFBrS6TtaM5gEj%2BSritQe3W%2B2EX7TnwhfrWd68EvQUjFR8XdecpyN%2Fil7ykQ+OY0VXI5nXHqbBxFSLdU%2FJPYFDTcZiE0FfHpa6bh5ZWQjvSOwFrAIwocOMDcPsMVZOJTKqlha2Xae+nzw5a3hejcdK7dDWZ97CZJ%2B%2FPoFO3w%3D%3D+%3Dbumf&from=0895277082

W polu encData są zaszyfrowane następujące dane:fun=makeCall&userName=543452&password=apidemo&authSystem=AMCL&to=0587311999&toType=N&fromType=N

Odpowiedź:

fsdfs23423423432234324

27 z 59

4.2.3 getBilling 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 offRow czyli numer wiersza od którego pobieramy dane.

Wejście Poniżej lista pól definiujących kryterium wyszukiwania• callDir

o OUT – rozmowy wychodząceo IN – rozmowy przychodzące

• fromAccount (opcjonalne) – nazwa użytkownika z którego wychodzą rozmowy.

• toAccount (opcjonalne) – nazwa użytkownika do którego przychodzą rozmowy

• fromService (opcjonalne) – login usługi, z której wychodzą połączenia (np. SID22)

• toService (opcjonalne) – login usługi, do której przychodzą połączenia (np. SID22)

• fromNumber (opcjonalne) – numer, z którego wychodzą połączenia• toNumber (opcjonalne) – numer, na który przychodzą połączenia• callType (opcjonalne) – typ rozmowy

o CHFR– rozmowy w obrębie platformyo LOCC – rozmowy PSTN (np. TPSA)o CALL, - rozmowy realizowane przez zewnętrznego

operatora VoIP. Jeśli jest puste wyszukiwane są rozmowy realizowane poprzez wszystkie peery dla operatorów zewnętrznych.

o LCR, - rozmowy przychodzące realizowane przez peera LCR. Jeśli jest puste wyszukiwane są rozmowy przychodzące przez wszystkie peery LCR.

• isMissed (opcjonalne) – false są brane 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 sekundach które upłynęły od 1 stycznia 1970 (Unix timestamp).

• 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

pobrać poprzez wywołanie funkcjio callType - typ rozmowy, możliwe wartości takie jak dla parametru

wejściowegoo fromAccount – nazwa konto Odo fromNumber – numer Odo contactFNF – imię skojarzone w oparciu o książkę kontaktową dla

28 z 59

numeru Odo contactLNF- nazwisko skojarzone w oparciu o książkę kontaktową

dla numeru Odo fromServiceType – typ usługi odo fromServiceName – nazwa usługi odo fromType – typ połączenia Od. Możliwe wartości to:

o account – połączenie z kontao service – połączenie z usługio PSTN – połączenie PSTNo VoIP – połączenie VoIP

o toAccount – nazwa konto Doo toNumber – numer Doo contactFNT – imię skojarzone w oparciu o książkę kontaktową dla

numeru Doo contactLNT- nazwisko skojarzone w oparciu o książkę kontaktową

dla numeru Doo toServiceType – typ usługi doo toServiceName – nazwa usługi doo toType – typ połączenia Do. Możliwe wartości to:

o account – połączenie na kontoo service – połączenie na usługęo PSTN – połączenie PSTNo VoIP – połączenie VoIP

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 endDate – czas zakończenia 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 sekundacho 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 callId – unikalny identyfikator pozwalający powiązać ze sobą kilka

przekierowanych połączeńo peerName – nazwa operatora przez którego została zrealizowana

rozmowaWyjście W parametrze umieszczona jest lista kolumn (przedzielona

29 z 59

przecinkami) dla danych, które wystąpią w . W 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 . W polu noOfRowsReq zwracana jest ilość wierszy w danym żądaniu.

Lista kolumn które mogą się pojawić w odpowiedzi została opisane w sekcji getBillingWejściecolumnList.

Błędy Możliwe kody błędów:• - podano nieprawidłową wartość callDir• - podano nieprawidłową wartość callType• , ,

, - nie znaleziono podanego konta/usługi, w grupie na którą przeprowadzono uwierzytelnianie

• - podano nieprawidłową wartość isMissed• - któraś z podanych dat jest nieprawidłowa• - wprowadzono niedozwoloną wartość w polu

columnList

• - wprowadzono niedozwoloną wartość w polu orderBy• - wprowadzono niedozwoloną wartość w polu

orderDesc

• - wprowadzono niedozwoloną wartość w polu noOfRows (maksymalna wartość to 200)

• - wprowadzono niedozwoloną wartość w polu offRowPrzykład użycia

Chcemy pobrać ilość połączeń dla następujących kryterium:• Rozmowy wychodzące• Rozmowy wychodzące z konta apidemo• Rozmowy LCR (bez podania peera LCR)• Tylko rozmowy zrealizowane• Połączenia między 2009-08-01 13:00 (czas Unix 1249128780) a 2009-08-31

14:00 (cza Unix 1251720840)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://apiuser. freeconet.pl /URL/V3/execute? fun=getBilling&tokenStr=815aa4d11b51ffc09b251da76a7bac81283a002442ac64efc03162922838fb51&callDir=OUT&isMissed=false&fromDate=1249128780&toDate=1251720840&callType=LCR&columnList=fromNumber,toNumber,callDuration,callCost,startDate&orderBy=callCost&orderDesc=false&offRow=1&noOfRows=100&sig=96e387810792996a79bfd239f44e6249

30 z 59

https://apiuser.freeconet.pl/RestAPI/V2/execute?fun=getBilling&callDir=OUT&fromAccount=apidemo&callType=LCR&isMissed=false&fromDate=1199192400&toDate=1201874400&orderBy=callCost&orderDesc=false&noOfRows=100&offRow=1&columnList=fromNumber,toNumber,callDuration,callCost,startDate&tokenStr=815aa4d11b51ffc09b251da76a7bac81283a002442ac64efc03162922838fb51&sig=b79072e81e70be8ce31c41abfc181750https://apiuser.freeconet.pl/RestAPI/V2/execute?fun=getBilling&callDir=OUT&fromAccount=apidemo&callType=LCR&isMissed=false&fromDate=1199192400&toDate=1201874400&orderBy=callCost&orderDesc=false&noOfRows=100&offRow=1&columnList=fromNumber,toNumber,callDuration,callCost,startDate&tokenStr=815aa4d11b51ffc09b251da76a7bac81283a002442ac64efc03162922838fb51&sig=b79072e81e70be8ce31c41abfc181750https://apiuser.freeconet.pl/RestAPI/V2/execute?fun=getBilling&callDir=OUT&fromAccount=apidemo&callType=LCR&isMissed=false&fromDate=1199192400&toDate=1201874400&orderBy=callCost&orderDesc=false&noOfRows=100&offRow=1&columnList=fromNumber,toNumber,callDuration,callCost,startDate&tokenStr=815aa4d11b51ffc09b251da76a7bac81283a002442ac64efc03162922838fb51&sig=b79072e81e70be8ce31c41abfc181750https://apiuser.freeconet.pl/RestAPI/V2/execute?fun=sendFax&fileDocumentID=plik_1234.txt&timeMask=*%20*%20*%20*%20*&numberList=0581234567,0587654321,0581111111&tokenStr=7b4f24d8b17b15024426c3a5125577942f876ccb2c132c9f273296220899835e&sig=41b97e4da175a684e57adf080d1be605https://apiuser.freeconet.pl/RestAPI/V2/execute?fun=sendFax&fileDocumentID=plik_1234.txt&timeMask=*%20*%20*%20*%20*&numberList=0581234567,0587654321,0581111111&tokenStr=7b4f24d8b17b15024426c3a5125577942f876ccb2c132c9f273296220899835e&sig=41b97e4da175a684e57adf080d1be605https://apiuser.freeconet.pl/RestAPI/V2/execute?fun=sendFax&fileDocumentID=plik_1234.txt&timeMask=*%20*%20*%20*%20*&numberList=0581234567,0587654321,0581111111&tokenStr=7b4f24d8b17b15024426c3a5125577942f876ccb2c132c9f273296220899835e&sig=41b97e4da175a684e57adf080d1be605

Odpowiedź:

2 fromNumber,toNumber,callDuration,callCost,startDate

4.2.4 sendFaxNazwa funkcji

sendFax

Opis 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. 221234567 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:• - unikalny numer kampanii faksowej

Błędy Możliwe kody błędów:• - nie znaleziono pliku o podanym

identyfikatorze• - podana lista numerów jest w błędna

Przykład użycia

Wywołanie:

https://apiuser. freeconet.pl /URL/V3/execute? fun=sendFax&fileDocumentID=plik_1234.txt&timeMask=* * * * *&numberList=0581234567,0587654321,0581111111&tokenStr=7b4f24d8b17b15024426c3a5125577942f876ccb2c132c9f273296220899835e&sig=41b97e4da175a684e57adf080d1be605

Odpowiedź:

31 z 59

https://apiuser.freeconet.pl/RestAPI/V2/execute?fun=sendFax&fileDocumentID=plik_1234.txt&timeMask=*%20*%20*%20*%20*&numberList=0581234567,0587654321,0581111111&tokenStr=7b4f24d8b17b15024426c3a5125577942f876ccb2c132c9f273296220899835e&sig=41b97e4da175a684e57adf080d1be605https://apiuser.freeconet.pl/RestAPI/V2/execute?fun=sendFax&fileDocumentID=plik_1234.txt&timeMask=*%20*%20*%20*%20*&numberList=0581234567,0587654321,0581111111&tokenStr=7b4f24d8b17b15024426c3a5125577942f876ccb2c132c9f273296220899835e&sig=41b97e4da175a684e57adf080d1be605https://apiuser.freeconet.pl/RestAPI/V2/execute?fun=sendFax&fileDocumentID=plik_1234.txt&timeMask=*%20*%20*%20*%20*&numberList=0581234567,0587654321,0581111111&tokenStr=7b4f24d8b17b15024426c3a5125577942f876ccb2c132c9f273296220899835e&sig=41b97e4da175a684e57adf080d1be605https://apiuser.freeconet.pl/RestAPI/V2/execute?fun=sendFax&fileDocumentID=plik_1234.txt&timeMask=*%20*%20*%20*%20*&numberList=0581234567,0587654321,0581111111&tokenStr=7b4f24d8b17b15024426c3a5125577942f876ccb2c132c9f273296220899835e&sig=41b97e4da175a684e57adf080d1be605https://apiuser.freeconet.pl/RestAPI/V2/execute?fun=sendFax&fileDocumentID=plik_1234.txt&timeMask=*%20*%20*%20*%20*&numberList=0581234567,0587654321,0581111111&tokenStr=7b4f24d8b17b15024426c3a5125577942f876ccb2c132c9f273296220899835e&sig=41b97e4da175a684e57adf080d1be605

12344

4.2.5 getFaxSentNazwa funkcji

getFaxSent

Opis Funkcja umożliwia pobranie listy wysłanych faksów dla danej konsoli faksowej.

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 Parametry wywołania:• fromDate - data od której wyszukiwane są faksy. Data podawana jest w

sekundach które upłynęły od 1 stycznia 1970 (Unix timestamp).• toDate - data do której wyszukiwane są faksy. Data podawana jest w

sekundach które upłynęły od 1 stycznia 1970 (Unix timestamp).• batchId (opcjonalne) – identyfikator kampanii wysyłki faksu• faxStatus – status dokumentu faksu

o ENDED, ERROR, CANCELED, ALL • 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• columnList – lista kolumn poprzedzielane znakiem przecinka, które można

pobrać poprzez wywołanie funkcjio batchId – identyfikator kampanii wysyłki faksuo itemId – identyfikator faksuo toNumber – numer odbiorcyo faxStatus – status wysyłki dokumentu o faxStatusDetails – szczegółowy status wysyłki faksuo noAttempt – aktualna próbao maxNoAttempts – maksymalna liczba próbo sentDate – data wysłania dokumentu (Unix timestamp)o noPages – liczba wysłanych strono sentCost – koszt wysłania faksuo fileUrl – adres URL dokumentu faksuo fileName – nazwa pliku dokumentu faksu

Wyjście W parametrze umieszczona jest przedzielona przecinkami lista kolumn, które wystąpią w odpowiedzi – sekcja . W 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 .W polu noOfRowsReq zwracana

32 z 59

jest ilość wierszy zwracanych w danym żądaniu.

Lista kolumn które mogą się pojawić w odpowiedzi została opisane w sekcji getFaxSentWejściecolumnList.

Błędy Możliwe kody błędów:• - podano błędny status dokumentu faksu• - jedna z podanych dat jest nieprawidłowa• - wprowadzono niedozwoloną wartość w polu

columnList

• - wprowadzono niedozwoloną wartość w po