Теме: Web развој

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

Скраћена веза: http://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 (486)


Поделите овај чланак са пријатељима


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

  • Videh danas kad si pitao za pomoć na twitteru. Mi smo na faksu pre par godina baš radili soap na primeru NBS web-servisa, i baš smo nusoap koristili. Htedoh da ti pošaljem te primere, ali izgleda da više nemam pristup našem eLearning sistemu :/

    Interesantno je to kako gotovo nigde nisam naišao (osim u NBS) da se koristi soap, svuda koriste API-je zasnovane na REST web-servisima (pa i na FB-u i na twitteru)… (iako načelno ni jedan od njih nije bolji od onog drugog, samo imaju drugačiji pristup problemu). A opet, kao za inat, kod nas (barem na mom faksu) je iz više predmeta obrađivan soap, a o rest-u niko ni reč da bekne. Kod nas večito sve napako xD

  • Нашао сам пар примера од раније али је НБС променила API за свој SOAP тако да они више не радe.

    С обзиром колико има сајтова који приказују курснелисте које преузимају од НБС, јасно једа су то људи решили, али да нико није преман да другима покаже како, а ако се неко није овим бавио раније, прилично му је тешко да провали све детаље.

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

  • SOAP je starija i ozbiljnija tehnologija, za ralziku od REST-a poznaje strogo tipizirane podatke. Amazon i eBay su dugo koristili SOAP, mislim da ga još uvek podržavaju. Zgodno je što postoji WSDL, u to vreme očekivalo se da će postojati automatski alati koji generišu klijente zavisno od WSDL opisa servisa.

  • A zašto SOAP, verovatno NBS koristi neki IBM softver koji ume podrazumevano da priča SOAP pa im je to bilo najlakše da ponude i objedine sve veb servise u isti interfejs.

  • Ja nisam uspeo nikada da se registrujem kod njih.
    Dobijam runtime error?
    Mozda zato sto koristim linuks???

    Ranije mi je radilo sa test nalogom, sada mi je potrebna registracija, ali nece…

  • Бацио сам поглед, на брзину, али нисам видео индикативни курс… има ли и њега у понуди?

    Иначе, ја за @kurs на твитеру парсујем HTML страницу.

  • Pedja R.

    Hvala za skriptu,uspeo sam da se konektujem i izvucem povratan odgovor i zamolio bih Vas za neki tip kako da iz dobijenog niza izvucem samo vrednost evra.Hvala

  • Као резултат добијаш XML, испарсирај и узми шта ти треба.

  • Pedja R.

    Kad imam xml fajl onda se snalazim sa parsovanjem,ali ovde me buni sto (ako sam dobro ukapirao)xml se nalazi u okviru varijable $m_output…ili sam ja malo vise zalutao???
    Hvala

  • Свеједно је да ли је XML у датотеци или променљивој. Парсирање је исто.

  • Pedja R.

    Reseno,Hvala ti sto si ovo podelio sa nama.
    Pozdrav

  • Alex

    Hvala Vam MNOGO na svemu, gotovo sigurno nikada ne bih uspeo da niste pomogli.
    Imam samo jedan problem.
    Koristim „GetCurrentExchangeRate“ a ne „GetExchangeRateByDate“.
    Kada pustim stranicu, ne prijavljuje ni jednu grešku ali mi ne čita kao da je XML, tačnije ovako izgleda:
    http://img220.imageshack.us/img220/6507/blia.jpg
    (Na sliku je stavljen BLUR efekat)
    Sada ne znam da li tako i treba da izgleda i da li će tako čitati ili ne? Kada odem na CTRL+U (na toj stranici) sve izgleda lepo.
    I da li možda znate neki gotov ili polu gotov PHP kod gde bih mogao da namestim koje valute da se prikazuje i to sve lepo složeno u neku tabelu ili ću morati da se namučim da to napravim sam?

    • Дао сам решење за главни део посла.

      Ако нећеш сам да се помучиш, увек можеш да поручиш од некога да ти направи то што ти треба, на пример од мене.

  • Alex

    Ok, naravno. Kontaktiraj me na email, da se dogovorimo.

  • JP

    vidim da je tema odavno, ali meni je sad aktuelna…moje pitanje je sta ako ne zelim da prosledim drugi parametar (Identifikator kursne liste), u opisu stoji da je samo datum obavezan, medjutim ako drugi parametar postavim na null dobijam
    Error:

    Array
    (
    [faultcode] => soap:Client
    [faultstring] => Server was unable to read request. —> There is an error in XML document (5, 171). —> Input string was not in a correct format.
    [detail] =>
    )

    unapred hvala na odgovoru 🙂

    • Мислим да је грешка у документацији да је само date параметар наведен као обавезан, пошто нема логике да није обавезан и параметар за тип листе.

      Пробај да уместо null пошаљеш празан стринг.

  • JP

    Probala, ponovo javlja gresku 🙁
    Ja u stvari pokusavam da pozovem metodu
    GetDebtor servisa DebtorXmlService (registar duznika u prinudnoj naplati), za koju ni jedan parametar nije obavezan, ali ako bilo koji postavim na null ili prazan string dobijem gresku Input string was not in a correct format
    U ovom slucaju zaista ima smisla da parametri nisu obavezni, htela sam pretragu samo po maticnom broju, ali nikako ne uspevam da to izvedem 🙁
    Svaka sugestija je dobrodosla 🙂

    • То се и мени дешавало са неким другим функцијама и после много порведених сати, само сам могао да признам капитујацију и одустанем.

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

      Чак су одбили да и овај мој чланак ставе на сајт као упутство за своје кориснике. Може им се, на државним су јаслама.

  • JP

    ako si ti odustao ja mogu samo da sednem i placem :((
    Hvala u svakom slucaju, malo mi je lakse kad vidim da nisam jedina koja ne ume da resi ovo
    Pozdrav 🙂

  • Miroslav

    Svaka cast na olaksavanju kolegama na predlozenoj nuSoap biblioteci i konkretnom primeru.
    Samo bih da dodam, da ko se igra kuci sa ovim servisom, neka na (konkretno ja koristim) WAMP-u ukljuci na dva mesta biblioteku za cURL
    http://www.phpmind.com/blog/2011/02/how-to-enable-curl-in-wamp/

    Pozdrav

  • Nikol

    Hvala bogu pa sam i ja dobio ovaj zadatak, i to u javi, mogu slobodno da se ubijem…

Leave a Reply

 

 

 

You can use these HTML tags

<a href="" title=""> <abbr title=""> <acronym title=""> <b> <blockquote cite=""> <cite> <code> <del datetime=""> <em> <i> <q cite=""> <s> <strike> <strong>

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