GetBasket Beschrijving van de webservices vr het imprteren van bestellijsten van de Galvan website in de lcale klantsftware. Auteur: Rn Kessels Datum: maandag 6 april 2009 Versie: 1.3
1 Functineel Op de Galvan website bieden we klanten de mgelijkheid m eenvudig artikelen te zeken p basis van de classificatie, via een catalgusstructuur enz. Daarnaast helpen we de klant bij het samenstellen van de juiste cmplete cmbinaties e.d. Om deze functinaliteiten k beschikbaar te krijgen in de lkale sftware van de klant is het idee ntstaan m het mgelijk te maken de dr de klant geselecteerde artikelen p de website te te vegen aan een bestellijst (zgenaamde stuklijst). Vervlgens kan vanuit de lkale sftware van de klant de inhud van een bestellijst pgevraagd wrden middels een webservice. De sftware van de klant kan daarmee de specificatie van de bestellijst die p de website is samengesteld vernemen in een fferte/bestelling/factuur. Bij implementatie van deze kppeling is het niet meer ndzakelijk m een artikelbestand beschikbaar te hebben in de lkale sftware van de klant. Samen met de webservice GetArticleInf, waarmee de artikelgegevens bijgewerkt kunnen wrden, is het dan mgelijk m altijd actuele artikelinfrmatie beschikbaar te hebben znder nderliggend artikelbestand. Galvan Grthandel BV Pagina 2 R.M.J. Kessels
2 Uitwerking functinaliteit Om deze functinaliteit in te buwen dienen een aantal zaken geregeld te wrden. Allereerst met het mgelijk zijn m vanuit de lkale sftware van de klant de website van Galvan p te starten. De klant kan vervlgens de artikelen zeken en in een bestellijst plaatsen. Wanneer hij klaar is kan vanuit de sftware van de klant een functie aangerepen wrden waarmee de bestellijst uitgelezen wrdt. Op de website van Galvan is het mgelijk m meerdere bestellijsten aan te maken. Om de imprt van de bestellijst van de website van Galvan te faciliteren in de sftware van de klant zijn de vlgende drie webservices gedefinieert: 1. Webservice vr het pvragen van de actuele bestellijsten van een klant. 2. Webservice vr het pvragen van de inhud (artikelspecificatie) van een bestellijst. 3. Webservice vr het verwijderen van een bestellijst (incl. artikelspecificatie). Deze functies wrden hiernder in detail beschreven. 2.1 Inlggen samenstellen bestellijst Vanuit de sftware van de klant dient de website van Galvan aangerepen te kunnen wrden. Er dient een (geïntegreerde) brwser pgestart te wrden welke de website van Galvan pent. Op de website plaatst de klant de artikelen niet in een rder, maar in een bestellijst, deze bestellijst kan hij vervlgens in zijn eigen sftware imprteren. De website van Galvan kan met de vlgende link gepend wrden: http://prtal.galvan.nl/www/link/prduct.rails?query=&username=[1]&passwrd=[2] Daarbij kunnen de vlgende variabelen meegestuurd wrden: [1] = de gebruikersnaam waarmee de gebruiker inlgt (ptineel) [2] = het wachtwrd (ptineel) 2.2 Webservices Om de bestellijsten p te vragen is een webservice gemaakt. De webservice beschikt ver een drietal methds, deze zijn: 1. getuserbaskets: vr het pvragen van de bestellijsten van een gebruiker 2. getbasketcntent: vr het pvragen van de inhud (artikelspecificatie) van een bestellijst 3. deletebasket: vr het verwijderen van een bestellijst. Bij elke aanrep van de webservice wrden een drietal gegevens verwacht: struserid: de inlgnaam van de gebruiker p de website van Galvan strpasswrd: het wachtwrd behrende bij de inlgnaam strxml[methdname]: de xmlstructuur behrende bij de methd. De xmlstructuur is afhankelijk van de methd, deze verschillende structuren wrden in de vlgende subparagrafen beschreven. Galvan Grthandel BV Pagina 3 R.M.J. Kessels
De xmlstructuur vr de verschillende methds is vastgelegd in een XSD. In de bijlage is een afdruk van deze structuur terug te vinden. 2.2.1 Opvragen bestellijsten (getuserbaskets) Wanneer de klant klaar is met het samenstellen van de bestellijst kan hij deze lijst vernemen in zijn sftware. Daarvr dient in zijn sftwarepakket een functie gemaakt te wrden waarmee de actuele bestellijsten pgevraagd kunnen wrden welke p de website van Galvan aangemaakt zijn. Hiervr wrdt de webservice aangerepen met de methd getuserbaskets. Deze methd kent de vlgende inputvariabelen: - Settings ApplicatinId: (XSD:Integer 4N) Een cde die aangeeft welke sftware de webservice aanrept. VersinId: (XSD:String, 5AN) Versienummer van de sftware welke de webservice aanrept. LanguageCde: (XSD:String, 2AN) Niet verplicht. Taalcde waarin de webservice de gegevens terug wil ntvangen, mgelijke cdes zijn: NL: Nederlands (default, indien niet meegegeven) EN: Engels DE: Duits FR: Frans De webservice returneert alle bestellijsten welke aangemaakt zijn dr de klant. De webservice zal, naast de inputvariabelen de vlgende gegevens returneren: Vr elke bestellijst wrden de vlgende gegevens gereturneerd. BasketId: (XSD: Int) Het unieke vlgnummer van de bestellijst Reference: (XSD:String, 15AN) De naam waarnder de bestellijst pgeslagen is dr de klant Descriptin: (XSD:String, 64AN) Een beschrijving van de bestellijst dr de klant UserName: (XSD: String, 30AN) De vr- en achternaam van de gebruiker die de bestellijst aangemaakt heeft. LineCunt: (XSD: Int) Het aantal artikelregels in de bestellijst 2.2.2 Opvragen inhud bestellijst (getbasketcntent) Als de gebruiker een keuze gemaakt heeft vr een bestellijst kan met deze webserivce, met de methd getbasketcntent, de inhud (artikelspecificatie) van die bestellijst pgevraagd wrden. Deze methd kent de vlgende input variabelen: - Settings ApplicatinId: (XSD:Integer 4N) VersinId: (XSD:String, 5AN) LanguageCde: (XSD:String, 2AN) BasketId: (XSD: Int) Betreft het BasketId van de bestellijst waarvan de regels pgevraagd wrden. Deze is dus eerder pgevraagd via de webservice GetUserBaskets. Galvan Grthandel BV Pagina 4 R.M.J. Kessels
De webservice returneert de kenmerken van de bestellijst én alle artikelen die in de bestllijst zitten. De vlgende gegevens wrden gereturneerd: BasketId: (XSD: Int) Reference: (XSD:String, 15AN) Descriptin: (XSD:String, 64AN) UserName: (XSD: String, 30AN) LineCunt: (XSD: Int) Items Hiernder vlgen de artikelen Item Vr elk artikel uit de bestellijst wrden de vlgende gegevens gereturneerd: ArticleId: (XSD:Integer) Artikelnummer waarnder het artikel besteld kan wrden bij Galvan Quantity: (XSD:Integer) Het aantal stuks van dit artikel uit de bestellijst in besteleenheden. Unit: (XSD:String, 15AN) De besteleenheid waarin quantity uitgedrukt is Cnversinfactr: (XSD:duble) Een mrekenfactr van besteleenheid naar gebruikseenheid. Bevat het aantal gebruikseenheden per besteleenheid (Wanneer er dus 25 Meter (gebruikseenheid) p 1 Rl (besteleenheid) zit, dan is de Cnversinfactr: 25). Om het aantal gebruikseenheden uit te rekenen dien de Cnversinfactr vermenigvuldigd te wrden met de Quantity. UserUnit: (XSD:String, 15AN) De gebruikseenheid ShrtDescriptin: (XSD:String, 100AN) Krte mschrijving van de artikelregel (ptineel) LngDescriptin: (XSD: String, 145AN) Uitgebreide artikelmschrijving van de artikelregel. Deze mschrijving is leidend! Brand: (XSD:String, 25AN) Merknaam van het artikel Serie: (XSD:String, 25AN) Serienaam van het artikel PrductDescriptin: (XSD:String, 50AN) Prductmschrijving van het artikel Clr: (XSD: 25AN) Kleur van het prduct PrductCde: (XSD:String, 20AN) Artikelnummer fabrikant EANcde: (XSD:Int) EAN / GTIN CllectinId : (XSD :Int) Indicatie srt artikel: 0 = Uniek artikelnummer 2 = Verzamelnummer 3 = Semi-verzamelnummer Deze indicatie is vral ndzakelijk vr sftware die maar 1 artikelmschrijving vast kan leggen. Bij cde 2 en 3 gaat het m artikelnummers waarnder meerdere artikelen besteld kunnen wrden (p basis van de mschrijving). Daarm dient hierbij altijd de uitgebreide Galvan Grthandel BV Pagina 5 R.M.J. Kessels
mschrijving vastgelegd te wrden daar anders nit meer achterhaald kan wrden wat het prduct is/was. GrssUnitPrice: (XSD:duble) De brut stukprijs van het artikel per besteleenheid. De prijs per gebruikseenheid kan uitgerekend wrden dr dit veld te delen dr de CnversinFactr. NetUnitPrice: (XSD:duble) De nett stukprijs van het artikel per besteleenheid. NetTtalPrice: (XSD:duble) Dit is de nett ttaalprijs vr het aantal uit het Quantity veld. NetPriceDescriptin: (XSD:String, 50AN) Deze mschrijving geeft aan he de gereturneerde nettprijs berekend is. 2.2.3 Leegmaken bestellijst (deletebasket) Nadat de bestellijst succesvl pgevraagd is vanuit de sftware van de klant kan de bestellijst p de website verwijderd wrden. Hiervr wrdt de methd deletebasket gebruikt. Deze methd kent de vlgende input variabelen. - Settings ApplicatinId: (XSD:Integer 4N) VersinId: (XSD:String, 5AN) LanguageCde: (XSD:String, 2AN) BasketId: (XSD: Int) Betreft het BasketId van de bestellijst die verwijderd dient te wrden. Deze webservice zal een cde true f false teruggeven die aangeeft f de bestellijst succesvl verwijderd is. 2.2.4 Errrafhandeling Indien er een futieve aanrep plaatsvindt, zal er een errrnde teruggestuurd wrden met de vlgende structuur: - Errrbasket Errrid: (XSD:Int) Futcde Descriptin: (XSD:String) Omschrijving van de fut Field: (XSD:String) Veld waarin de fut ptrad We nderkennen de vlgende errrs: ErrrId Descriptin 1 Aanrep mislukt, de service is mmenteel niet beschikbaar, prbeer het later pnieuw 2 Inlggen mislukt, de cmbinatie gebruikersnaam en wachtwrd is njuist 3 Authrisatie mislukt, u heeft niet de juiste bevegdheid f bestellijst niet gevnden 4 Aanrep mislukt, ApplicatinId ngeldig 5 Aanrep mislukt, gelieve een BasketId p te geven 6 Aanrep mislukt, er is een ngedefinieerde fut pgetreden 7 Aanrep mislukt; lijst bevat artikelen die niet (meer) leverbaar zijn, gelieve deze eerst uit de lijst te verwijderen 8 Aanrep mislukt; u kunt vr maximaal 100 artikelen tegelijk infrmatie pvragen Galvan Grthandel BV Pagina 6 R.M.J. Kessels
I. XSD Webservice baskets Galvan Grthandel BV Pagina 7 R.M.J. Kessels