Functioneel Ontwerp: WebServices bevragingen Version., 22 mei 204 Huis ter Heideweg 46 3705 LZ Zeist The Netherlands Tel: +3 (0)30 697 32 88 Fax: +3 (0)30 697 32 89 E-mail: info@onetrail.com
Inleiding Dit document beschrijft het functionele ontwerp van de artikel- en product informatie webservices en dient als input voor het technisch ontwerp van de webservices. Een functionele beschrijving van een webservice bestaat uit: Beschrijving van de toepassing van de service, waarvoor wordt deze gebruikt; De definitie van het verzoek; De definitie van het antwoord; Mogelijke functionele fout situaties (bijv. artikel niet gevonden); Dit document is tot stand gekomen in samenwerking met: Rien Wabeke Sales in de Bouw Ron Kessels Saint Gobain Arian Haeser 2BA Eddy Geurts Oosterberg Cor Zijlstra Onetrail Uitgangspunten. Hoofdstuk 6: Functionaliteit Webservices uit het concept advies d.d.29--203 van Peter Zwakhals dient als uitgangspunt voor de beoogde functionaliteit. 2. De services voor de artikel informatie zijn al geïmplementeerd bij een aantal partijen in de branche en is beschreven op de UDDI van ETIM: StockAvailability. Het streven is om deze met minimale wijzigingen over te nemen in dit ontwerp. 3. In het ontwerp van het verzoek en antwoord wordt zoveel mogelijk gebruikt gemaakt van de bericht-, attribuut- en entiteit definities uit de INSBOU003 standaard. Voor de attribuut-type en lengte wordt verwezen naar deze lijsten. 4. Authenticatie en sessiemanagement en versionering gelijk aan de MessagingWebService. 5. Mogelijkheid voor REST services open houden. 6. Versiebeheer in endpoint regelen. Artikel informatie Prijs en voorraad Toepassing De Prijs en Voorraad webservice heeft primair ten doel de nettoprijs en voorraadinformatie te verstrekken. Dit is sterk vergelijkbaar met de prijs en voorraadinformatie zoals getoond op een webwinkel. Page 2 of 5
Het is mogelijk om voor meerdere artikelen de informatie op te vragen. In het verzoek wordt optioneel het gewenste aantal afname eenheden vermeld. In het antwoord wordt indien en gevraagd aantal ingestuurd is maximaal het gevraagde aantal vermeld anders geeft de leverancier terug hoeveel er daadwerkelijk beschikbaar zijn. De prijs is de nettoprijs incl. kortingen (bijv. staffel). Uitganspunt is dat artikelbericht gegevens bekend zijn in systeem van de afnemer. Page 3 of 5
Verzoek. Leverancier/GLN 2. Afnemer/GLN 3. Vraag Soort Prijs / Voorraad / Beide 4. Artikelen -00 4. GTIN artikel Global Trade Item Number, wereldwijd uniek nummer ter identificatie van het artikel 4.2 Artikelcode leverancier Kenmerk, uniek binnen het systeem van de leverancier, ter identificatie van het artikel. 4.3 Aantal Aantal afname eenheden gelijk aan aantal besteld op de order 0- (verplicht indien artikelcode leverancier leeg) 0- (verplicht indien GTIN leeg) 0- Antwoord. Resultaatcode 0=Ok (webservice is correct uitgevoerd, een van de regels kan nog wel een fout bevatten) =Error (webservice is niet correct uitgevoerd).. Artikelen Lijst met gevraagde artikelen -00. Resultaatcode 0=Ok =Artikel niet gevonden 2=Artikel niet meer leverbaar.2 GTIN Global Trade Item Number, wereldwijd uniek nummer ter identificatie van het artikel.3 Artikelcode leverancier Kenmerk, uniek binnen het systeem van de leverancier, ter identificatie van het artikel. 0- (verplicht indien artikelcode leverancier leeg) (ook vermelden in resultaatcode <>0) (ook vermelden in resultaatcode <>0) Page 4 of 5
.4 GTIN opvolger 00% alternatief icm met resultaatcode 2 0-.5 Artikelcode leverancier opvolger 00% alternatief icm met resultaatcode 2 0-.6 Indicatie prijs op aanvraag Code die aangeeft dat de prijs moet worden aangevraagd bij de leverancier. 0-.7 Bruto prijs Bedrag dat wordt gevraagd voor de levering van een product of dienst, exclusief kortingen en toeslagen en exclusief BTW. 0-.8 Beschikbaarheid regels 0-n (verplicht indien statuscode=0).8. Aantal Aantal afname eenheden Maximaal het gevraagde aantal. 0- (verplicht bij vraagsoort voorraad / beide).8.2 Datum Datum waarop het vermelde aantal beschikbaar is bij de leverancier voor verzending / afhalen. 0-.9 Kortingen 0-999.9. Ingangsdatum korting 0-.9.2 Soort korting.9.3 Kortingsbedrag 0-.9.4 Volgnummer 0-.9.5 Omschrijving korting 0-.9.6 Kortingspercentage 0-.0 Staffel 0-.0. Ondergrens staffel. Toeslagen 0-999 Page 5 of 5
.. Ingangsdatum toeslag Datum vanaf wanneer de toeslag geldt...2 Soort toeslag Code waarmee het type toeslag wordt gespecificeerd..3 Toeslagbedrag Het bedrag dat extra in rekening wordt gebracht...4 Volgnummer Nummer ter identificatie en volgordebepaling van een regeltoeslag...5 Omschrijving toeslag Tekstveld met een omschrijving of nadere specificatie van het soort toeslag..6 Toeslagpercentage Getal waarmee de hoogte van de regeltoeslag wordt gespecificeerd in procenten van het totale regelbedrag of de totale regelhoeveelheid. 0-0- 0-0- 0- Page 6 of 5
Foutsituaties 0=Ok =Artikel niet gevonden 2=Artikel vervallen / niet meer leverbaar Stuklijst (basket) Toepassing Om een aantal redenen kan het handig zijn om een selectie van artikelen samen te stellen op de webshop/website van een leverancier: Men wil de artikelgegevens van de betreffende leverancier niet opnemen in het eigen ERP systeem omdat bijv. het assortiment te groot is, de bestelfrequentie te laag is, etc. Het samenstellen van de artikelen is gebonden aan business rules, die niet door de eigen ERP ondersteund worden (bijv. product configurator) De leverancier maakt bestellijsten aan voor de afnemer Etc. In deze gevallen kan de gebruiker, of de leverancier, op de webshop/website van de leverancier een stuklijst aanleggen. Deze kan de afnemer vervolgens overnemen in zijn eigen ERP om de gegevens daar verder te gebruiken in bijv. een calculatiemodule, offerte of inkooporder. De webservice voorziet in de data overdracht van de al samengestelde stuklijst van de website/webshop naar het eigen ERP systeem, alsmede in het opvragen van een overzicht en het verwijderen van de aanwezige stuklijsten. Verzoek overzicht stuklijsten (basket)(optioneel). Leverancier-GLN 2. Afnemer-GLN 3. Taalcode Code van de taal waarin de teksten in het bericht zijn opgesteld. Default NL indien niet meegegeven. ISO 639 taalcode. 0- Page 7 of 5
Antwoord overzicht stuklijsten (basket). Resultaatcode 0=Ok =Geen Stuklijsten gevonden 2. Lijst met stuklijsten -N 2. ID Uniek nummer van de stuklijst gegeneerd door het systeem 2.2 Referentie Referentie welke de gebruiker heeft opgegeven bij het aanmaken van de winkelwagen / bestellijst 2.3 Omschrijving Omschrijving welke de gebruiker heeft opgegeven bij het aanmaken van de winkelwagen / bestellijst 2.4 Gebruikersnaam Naam van de gebruiker die de Stuklijst heeft aangemaakt 2.5 Aantal artikelen Aantal artikelen in de stuklijst Foutsituaties 0=Ok = Geen Stuklijsten gevonden Verzoek opvragen Stuklijst (basket). Leverancier/GLN 2. Afnemer/GLN 3. Stuklijst ID Uniek nummer van de Stuklijst gegeneerd door het systeem. Indien leeg, dan wordt de default bestellijst/winkelwagen opgevraagd 4. Taalcode Code van de taal waarin de teksten in het bericht zijn opgesteld. Default NL indien niet meegegeven. ISO 639 taalcode. 0-0- Page 8 of 5
Antwoord Het antwoord bevat de statuscode en een INSBOUW003 artikelbericht met daarin de geselecteerde / samengestelde producten uit de Stuklijst. Uitganspunt is dat het antwoord voldoende gegevens bevat om een orderregel aan te kunnen maken in het ontvangende systeem en de benodigde artikelstamgegevens.. Resultaatcode 0=Ok =ID niet gevonden 3. Referentie Referentie welke de gebruiker heeft opgegeven bij het aanmaken van de Stuklijst 4. Omschrijving / Aanvullende Informatie 5. Gebruikersnaam / Afnemer contactpersoon Omschrijving welke de gebruiker heeft opgegeven bij het aanmaken van de Stuklijst Naam van de gebruiker die de Stuklijst heeft aangemaakt 6. Artikelen Lijst met artikelen welke in de Stuklijst zijn opgenomen -N 6. Aantal Aantal afname eenheden 6.2 Lange omschrijving (bij nieuwe versie PRICAT komt deze te vervallen) 0-6.3 Artikelregel Artikelbericht (PRICAT) Niveau in het bericht waar artikelen worden gespecificeerd. Foutsituaties 0=Ok =ID niet gevonden Page 9 of 5
Verwijderen Stuklijsten. Leverancier-GLN 2. Afnemer-GLN 3. Stuklijst ID Uniek nummer van de Stuklijst gegeneerd door het systeem. Indien leeg, dan wordt de default bestellijst/winkelwagen verwijderd. 0- Antwoord verwijderen Stuklijsten Het antwoord geeft aan of het verwijderen is geslaagd.. Resultaatcode 0=Ok (winkelwagen is verwijderd) =Geen Stuklijsten gevonden Foutsituaties 0=Ok = Geen Stuklijsten gevonden Page 0 of 5
Product informatie Productgevevens Toepassing De webservice voor het opvragen van productgegevens heeft als doel om op adhoc basis productinformatie te verwerven van een leverancier. Het artikelnummer en de leverancier dienen reeds bekend te zijn bij de gebruiker. In het verzoek kan artikelnummer worden opgenomen. In het verzoek wordt de taalcode opgegeven waaraan het antwoord moet voldoen. Het antwoord bevat volledige ProductData (prodat) conform de INSBOUW003 definitie. Verzoek. Leverancier/GLN 2. Afnemer/GLN 3. Producten 3. GTIN Global Trade Item Number, wereldwijd uniek nummer ter identificatie van het product 3.2 Productcode leverancier Kenmerk, uniek binnen het systeem van de leverancier, ter identificatie van het product. 3.3 Taalcode Code van de taal waarin de teksten in het bericht zijn opgesteld. Default NL indien niet meegegeven. ISO 639 taalcode. 0-00 (verplicht indien artikelcode leverancier leeg) 0-00 (verplicht indien GTIN leeg) 0-00 Antwoord Het antwoord bevat de volledige Product Data (prodat) zonder wijzigingen, m.u.v. van toevoeging van de resultaatcode aan het begin van het schema. # Attribuut Toelichting. Resultaatcode 0=Ok =Product niet gevonden -00 2. Productbericht regel INSBOU003 productbericht regel (PRODAT). -00 Page of 5
Foutsituaties 0=Ok =GTIN niet gevonden Product bijlagen Toepassing De webservice voor het opvragen van productbijlagen heeft als doel om op adhoc basis productbijlagen te verwerven van een leverancier. Het artikelnummer en de leverancier dienen reeds bekend te zijn bij de gebruiker. In het verzoek kan artikelnummer worden opgenomen. Het antwoord bevat alle beschikbare bijlagen met metadata die de bijlage beschrijft en een URL. Verzoek. Leverancier/GLN 2. Afnemer/GLN 3. GTIN Global Trade Item Number, wereldwijd uniek nummer ter identificatie van het product 4. Productcode leverancier Kenmerk, uniek binnen het systeem van de leverancier, ter identificatie van het product. 0-00 (verplicht indien artikelcode leverancier leeg) 0-00 (verplicht indien GTIN leeg) 4. Taalcode ISO 639 taalcode 5. Type bijlage Zie tabel- bijlage typen Page 2 of 5
Antwoord. Resultaatcode 0=Ok =Product niet gevonden 2. Regels -n 2. URL URL 2.2 Mime-type RFC2046 2.3 Type Zie tabel- bijlage typen 2.4 Titel Onderschrift bij bijlage 2.5 Volgorde Om de volgorde van belangrijkheid van de bijlage aan te geven. =Hoogste prioriteit oplopend naar laagste prioriteit 2.6 Bijlage attributen -n 2.6. Naam Selectie uit tabel-2 attributen 2.6.2 Waarde Waarde van het attribuut Foutsituaties 0=Ok =GTIN niet gevonden 2=Artikel vervallen / niet meer leverbaar 3=Gevraagde taalcode niet beschikbaar 4=Bijlage van dit type niet aanwezig Page 3 of 5
Tabel-: Bijlage typen (Bron: 2BA) THN Thumbnail Ext: jpg; gif; png Color: RGB Max. 200x200px PPI PHI PVI Afbeelding van bijv. het product met als doel weergave op internet of in applicatie Highres afbeelding met als doel drukwerk Presentatie video / filmpje Ext: jpg; gif; png Color: RGB Max. 2000x2000px Ext: tiff; eps; jpg; ai; pdf Color: CMYK Min. 300 DPI (indien afmeting gespecifieerd) PRT Presentatie document / presentatiebestand MAN Handleiding Voorkeur ext: pdf, mp3 of link naar bijv. YouTube CHR Sheet met karakteristieken Voorkeur: pdf; xls SOF Software Voorkeur: gecomprimeerd STR CAD COL SCH LOG OTV Standards & regulation, certificaten etc. CAD object of symbool via attributen meer details Overige documenten naast de handleiding Schema Logo (bijv. merklogo) Overig visueel element OTD Overig document Voorkeur ext: pdf OTA Overig niet gecategoriseerde bijlage Page 4 of 5
Tabel-2: Attributen (Bron: 2BA) PrintWidth Centimeter (integer) PrintWidth=5 PrintHeight Centimeter (integer) PrintHeight=22 Width Pixels (integer) Width=280 Height Pixels (integer) Height=024 Latitude Graden (decimaal) Longtitude Graden (decimaal) Altitude Meter (decimaal) (Absolute altitude) Hoogte boven maaiveld Altitude=30 NAP Meter (decimaal) Hoogte boven NAP NAP=20 Dimensions (decimaal) Aantal dimensies (bijv. bij CAD) 2; 2.5 of 3 zijn standaardwaardes Dimensions=3 Face Front, Left, Back, Right, Top, Bottom Primair van toepassing op visuele, 2D elementen Face=Bottom CreateDate (date) Datum volgens het ISO 860 formaat: YYYY-MM- DDThh:mm:ss. Bijv. de datum waarop de foto gemaakt is CreateDate=20-03-04T4:52:56 Author (string) Author=2BA Duration Seconden (decimaal) Bijv. van toepassing bij een video of audio Duration=3600 FileSize Bytes (integer) De bestandsgrootte FileSize=5202 Page 5 of 5