Изборник Затворити

PHP, nusoap и веб сервис за курсну листу НБС

Скраћена веза: https://pedja.supurovic.net/veza/4685

Пре неколико дана сам кренуо да урадим рутину за преузимање курсне листе са сајта Народне Банке Србије. На први поглед, с обзиром да су понудили јавни веб сервис у SOAP технологији, изгледало је да ће ствар бити урађена рутински. Нажалост није. Поштено сам се намучио да све наместим.

Документација која је понуђена на сајту НБС је прилично штура и није баш од велике помоћи, нарочито некоме ко се први пут упушта у овакву ствар. И Гугл о целој овој ствари мало зна, те углавном приказује линкове на поменуту документацију али и на неколико сајтова где људи траже помоћ покушавајући да се изборе са коришћењем сервиса и без видних решења.

Стога, с обзиром да ми је најзад успело да изведем повезивање, ево упутства како се из PHP-а користи веб сервис НБС за приступ курсним листама.

Како почети

Најпре, да бисте користили веб сервисе НБС морате бити регистровани корисник. Детаљно објашњење како се то чини имате на сајту НБС , а укратко, треба да пошаљете попуњен и оверен захтев за учлањење у систем веб-сервиса НБС. Процедура је једноставна и завршава се за неколико дана, с обзиром да захтев морате, поред имејла, послати и обичном поштом, одштампан.

Када постанете члан, добићете шифру лиценце која вам је неопходна да бисте сервис могли користити. Поред ове шифре, потребни су вам и корисничко име и лозинка а њих сами одређујете и наводите у захтеву за учлањење.

Након што постанете члан моћи ћете одмах користити све бесплатне веб сервисе НБС. Међу њима је и сервис за приступ курсним листама који нас интересује. Ако вас интеренсују сервиси који се наплаћују њих посебно морате активирати.

Шта је SOAP?

За детаљан одговор на ово питање послаћу вас на Гугл. Ствар је сувише сложена да нема сврхе да вам препричавам обиље документације која је доступна. Дачу вам врло кратко и уопштено објашњење.

Интернет је омогућио да се функционалност апликација прошири ван једног рачунара и ван локалне мреже – на цео Интернет. То значи да је могуће на једном рачунару покренути апликацију, а она ће користити податке са неке друге локације која може бити било где, само је важно да сервер са подацима буде доступан преко Интернета. Нешто сложенији приступ омогућава да се и сама апликација налази на Интернету, а да корисник има само једноставан клијент на свом рачунару.

Најочигледнији пример таквог приступа је веб читач којим управо читате овај чланак. То је једноставна апликација која, сама за себе нема неку сврху, али када отворите неки сајт ви у ствари учитавате програм који веб читачу даје функционалност. За неке друге намене користе се другачији клијенти и другачији сервери који омогућују и веома сложене апликације.

Са тим, појавила се и неизбежна потреба да сеомогући да разнородни рачунари, оперативни системи и програми могу међусобно не само да комуницирају него и да извршавају апликације. Појавили су се протоколи који су управо то омогућили. Они омогућују да са клијента извршите програмске процедуре на серверу. Те процедуре могу једноставно да вам дају тражене податке али могу и да изврше обраду података на серверу. SOAP (Simple Object Access Protocol) је један од таквих протокола.

Погодност SOAP-а је у томе што је он универзалан и превазилази разлике између хардвера, оперативних система, програмских језика као и самих апликација. SOAP апликација може да се извршава на било чему, почев од обичног рачунара, преко ПДА, мобилног телефона као и на сваком другом уређају који може да са SOAP сервером комуницира преко Интернета.

Наравно, не извршава се стварно се SOAP апликација на свим овим уређајима већ они могу, коришћењем SOAP протокола, да покрећу процедуре које се извршавају на серверу и да добију од њега податке које даље могу да користе.

Тако широка компатибилност SOAP протокола се заснива на томе што он сву комуникацију између клијената и сервера заснива на XML порукама. SOAP поруке су, у ствари, само XML поруке са унапред јасно дефинисаном структуром.

Није зато изненађујуће зашто се Народна банка Србије одлучила да овај протокол користи за обезбеђење свог јавног веб сервиса: тиме су омогућили да податке са њиховог сервера можете добити на било ком уређају и из било ког окружења које има приступ Интернету.

Како функционише веб севис НБС

Да бисте могли да добијете неку информацију од веб сервиса НБС потребни су вам следећи подаци:

– корисничко име (UserName)

– лозинка за приступ (Password)

– шифра лиценце (LicenceID)

– локација WSDL дефинције сервиса

– назив именског простора (NameSpace)

– назив метода (програмске функције) сервиса

– параметри који се прослеђују изабраној методи

Није неопходно да ручно креирате XML поруке да бисте користли веб сервис. Постоје готове библиотеке које то могу урадити уместо вас, на основу параметара које им проследите.

Приликом успостављања конекције са веб сервисом неопходно је да се идентификујете. За то служи заглавље за аутентификацију (AuthenticationHeader) које се шаље приликом успостављања конекције. Оно је специфично за веб сервис НБС тако да га морате припремити ручно. Заглавље за аутентификацију се умеће у заглавље SOAP поруке и треба да изгледа овако:

<AuthenticationHeader  xmlns="http://communicationoffice.nbs.rs">
<UserName>korsinicko_ime</UserName>
<Password>lozinka</Password>
<LicenceID>sifra_licence</LicenceID>
</AuthenticationHeader>

Веб сервис НБС користи неколико WSDL сервиса, па тако морате изабрати одговарајућу дефиницију зависно опд тога какве податке желите. Потпун списак свих сервиса наћи ћете на сајту НБС. Нас, за преузимање курсне листе интересује Сервис за приступ курсним листама .

За сваки сервис НБС постоје два типа: један враћа податке у XML облику а други као DataSet. Користићемо XML, тако да је локација WSDL дефинције сервиса који ћемо користити https://webservices.nbs.rs/CommunicationOfficeService1_0/ExchangeRateXmlService.asmx?WSDL.

Именски простор (NameSpace) за све веб сервисе НБС је исти: http://communicationoffice.nbs.rs.

Списку метода веб сервиса ExchangeRateXmlService је подугачак, а нас интересује метод GetExchangeRateByDate , који даје податке о курсној листи на задати дан. Овај метод има два параметра: date датумског типа и exchangeRateListTypeID који је нумерички идентификатор курсне листе.

Датумски подаци се прослеђују као текстуални у формату ГГГГММДД (година са четири цифре, месец са две цифре и дан са две цифре, све спојено).

Идентификатор курсне листе је број. Може имати три вредности: 1 – за девизе, 2 – за ефективу и 3 – средњи курс. Ми ћемо тражити средњи курс.

То су сви подаци потребни да можемо да преузмемо податке од веб сервиса НБС.

Како користити SOAP у PHP-у

Иако у принципу SOAP упите можемо да извршавамо ручно, јер се у суштини ради о слању XML порука, ипак је много боље то радити неком наменском библиотеком која садржи потпуну имплементацију SOAP протокола. Ја сaм изабрао библиотеку nusoap . Она има сву потребну функционалниост и врло се једноставно користи.

Инсталација библиотеке је једноставна: преузмете архиву и распакујете је је у директоријуму где ће се налазити PHP програм који треба да је користи. Добићете два нова поддиректоријума: lib и samples. Први садржи библиотеку, а други можете и да обришете јер садржи примере коришћења библиотеке. Ако вам је потребно, а требало би да јесте, са сајта библиотеке можете посебно преузети архиву са документацијом.

Библиотеку у свој код укључујете командом

require_once('lib/nusoap.php');

SOAP конекцију подешавате креирањем објекта из класе nusoap_client, на пример командом:

$soap_client = new nusoap_client($soap_wsdl, true);

У било ком тренутку можете проверити стање објекта клијента увидом у бројне методе и својства класе nusoap_client. Све одједном их можете погледати командом:

print_r ($soap_client);

То ће вам свакако требати ако будете наишли на проблеме. Нарочито обратите пажњу на метод $soap_client->getError(). Ако ова функција врати било какву вредност, то значи да је дошло до неке грешке. Ако је грешкауследила након позива неког метода, онда ће та метода да вам уместо тражених података врати низ који описује грешку коју је пријавио SOAP сервер.

Ако имате проблема са позивом неког SOAP метода, доброје да проверите како изгледа SOAP порука која је послата серверу. Она се налази у својству $soap_client->request.

За остало, проучите документацију библиотеке nusoap.

А сад на посао

После мало дужег увода можемо да кренемо са комуникацијом са SOAP сервером НБС. Показаћу једноставан пример који преузима курсну листу на задати датум по средњем курсу.

На почетку, морамо укључити nusoap библиотеку

<?php
require_once('lib/nusoap.php');

а затим подесити параметре жељене курсне листе

$m_date = '20100811'; // zeljeni datum kursne liste u formatu YYYYMMDD
$m_list_type = 3;     // zelimo kursnu listu posrednjem kursu

Сада подешавамо податке везане за регистрацију на веб сервису. Овде морате уписати своје податке.

$login_username = 'USERNAME'';
$login_password = 'PASSWORD'';
$login_licenceid = 'LICENCEID';

И преостало нам је још да подесимо локацију WDSL и NameSpace сервиса:

$soap_wsdl = "https://webservices.nbs.rs/
CommunicationOfficeService1_0/ExchangeRateXmlService.asmx?WSDL";
$soap_namespace = "http://communicationoffice.nbs.rs";

Крећемо на посао. Прво креирамо објекат SOAP клијента

$soap_client = new nusoap_client($soap_wsdl, true);

и одмах искључимо декодирање utf8 знакова, јер веб сервиси НБС враћају податке у utf8 формату а такви нам и требају. Ако ово не искључимо сва ћирилична и наша латинична слова би била уништена.

$soap_client->decode_utf8 = 0;

Припремићемо заглавље за аутентификацију, као што је раније објашњено. То заглавље умећемо у заглавље SOAP поруке.

$m_header =
'<AuthenticationHeader xmlns="' . $soap_namespace . '">
<UserName>' . $login_username . '</UserName>
<Password>' . $login_password . '</Password>
<LicenceID>' . $login_licenceid . '</LicenceID>
</AuthenticationHeader>';

$soap_client->setHeaders($m_header);

Припремићемо и параметре које ћемо проследити приликом позива SOAP метода. Параметри се прослеђују у облику асоцијативног низа.

$p_parameters = array('date'=>$m_date,
                      'exchangeRateListTypeID' => $m_list_type);

Све је спремно и можемо извршити SOAP метод GetExchangeRateByDate са припремљеним параметрима.

$m_soap_result = $soap_client->call ('GetExchangeRateByDate',
                                      $p_parameters);

Након извршеног метода, у $m_soap_result ће се налазити или подаци које смо тражили (у XML облику) или порука о грешци коју је вратио SOAP сервер. Да ли је дошло до грешке проверичемо позивом метода getError().

Ако нема грешке, подаци се налазе у променљивој  $m_soap_result која је у ствари низ са једним елементом под именом GetExchangeRateByDateResult.

$m_error = $soap_client->getError();
if ($m_error) {
   //doslo je do greske, ispisacemo dostupne podatke o tome
   echo '<h1>Error:</h1>';
   echo '<pre>';
   print_r ($m_soap_result);
   print_r ($soap_client);
   echo '</pre>';
} else {
   //nema greske, prikazacemo podatke koje smo dobili
   $m_output = $m_soap_result;
   print_r ($m_output);
}
?>

И ту је крај

Претпостављам да сте до овог мог чланка дошли након што сте и сами наишли на проблем и да вам се сада чини да је ово све веома једноставно. Верујем да се тако чинило и људима у НБС па нису сматрали за сходно да напишу мало јаснију документацију. Надам се да сам на овај начин употпунио празан простор који је постојао те да ће другима сада битилакше да у своје програме уграде подршку за веб севисе Народне банке Србије.

Ови сервиси нуде још много података. Уколико су вам неки од њих потребни, проучите документацију SOAP метода који даје то што вам треба и употребите га на сличан начин као у овом примеру.

На крају, ево и датотеке са кодом који је коришћен у чланку: kursna-lista-nbs-nusoap.zip (5093 downloads )

31 Comments

  1. Knez

    Ovo je super radilo sve do skoro. Poslao sam mejl sa tekstom greske u attachmentu ovima u NBS ali se ne javljaju. Pedja da li tebi ovo jos uvek funkcionise ?

    • Пеђа

      Нисам одавно користио тај код. Не чуди ме ако су у међувремену нешто променили а да нису документовали.

    • Пеђа

      Малопре сам пробао сервис и ради ми пример који сам направио приликом писања овог чланка без икаквих измена.

      НБС је променила адресе страница са документаицјом, па сам ажурирао чланак и ставио нове адресе.

  2. Mlisac

    Python3 resenje ako nekog zanima…

    from suds.client import Client
    from xml_to_dict import XMLtoDict

    WSDL_URL = 'https://webservices.nbs.rs/CommunicationOfficeService1_0/CurrentExchangeRateXmlService.asmx?WSDL'
    uname = 'xxxxxxxxxxxxx'
    passwd = 'xxxxx-xxxx-xxx-xxx-xx'
    lic_id = 'xxxxxxx-xxxxx-xxxxxxx'

    client = Client(WSDL_URL, faults=False, cachingpolicy=1)

    authHead = client.factory.create('AuthenticationHeader')
    authHead.Password = passwd
    authHead.UserName = uname
    authHead.LicenceID = lic_id

    client.set_options(soapheaders=authHead)

    parser = XMLtoDict()

    status, resp = client.service.GetCurrentExchangeRate(1)
    print(status, parser.parse(resp))

Оставите одговор на SadClown Одустани од одговора

Ваша адреса е-поште неће бити објављена. Неопходна поља су означена *

Попуните израз тако да буде тачан: *

Ово веб место користи Акисмет како би смањило непожељне. Сазнајте како се ваши коментари обрађују.