Aanleverspecificaties. voor Producten. Versie 1.0

Transcriptie

1 b o u w m a t e r i a l e n v e r g e l i j k. n l Aanleverspecificaties voor Producten Versie 1.0 Datum uitgifte:

2 Inhoudsopgave Terminologie 4 Productvelden specificatie 5 Identificatie producten 7 Product matching 7 Afbeeldingen 7 Productcategorie 8 Aanleveren als CSV bestand 9 CSV opmaak 9 Kolommen 9 Eigenschap (Property) kolommen in een CSV bestand 9 CSV Bestandscontrole 10 Voorbeeldbestand 10 Aanleveren als XML (Product feed) 11 Bestaande product feeds 11 XML opbouw 11 Eigenschappen (Property) 11 Voorbeeld XML 12 Maatwerk bij complexe of 13 grote databestanden 13 Diverse oplossingen 13 Producten beheren via Productenbeheer 14 Productenbeheer 14 Kleine productenlijsten 14 Prijs- en voorraadinformatie 15 Aanlevermethodes 16 Productenbestand uploaden 16 Product feed 16 Manueel aanleveren 16 2 A a n l e v e r s p e c i f i c a t i e s v o o r p r o d u c t e n

3 Introductie Dit document bevat alle technische informatie die nodig is voor het maken van een productenbestand voor bouwmaterialenvergelijk.nl. Datakwaliteit Bij bouwmaterialenvergelijk.nl streven wij naar een zo hoog mogelijke datakwaliteit. Dit verbeterd de vindbaarheid van de producten voor de gebruikers. Ons technisch team staat je graag bij in het aanleveren van de juiste productinformatie. Geen tijd? Heb je zelf te weinig tijd om het productenbestand in orde te maken. Dan kun je ook je onbewerkte data aanleveren. Deze zal dan door ons kostenloos worden verwerkt tot een importeerbaar bestand. Contact Voor vragen of opmerkingen kun je contact opnemen met de Service Desk via adres of telefonsich via A a n l e v e r s p e c i f i c a t i e s v o o r p r o d u c t e n 3

4 Terminologie BMV Alfanumeriek CSV Decimaal EAN Numeriek PIM Productenbestand Product feed Productvelden UPC XML Verwijzing naar bouwmaterialenvergelijk.nl. Verzamelnaam voor de letters van het alfabet en de cijfers 0 tot en met 9. Een komma gescheiden bestand, of CSV-bestand, in het Engels Comma Separated Values, is een specificatie voor tabelbestanden. Een getal met cijfers achter de komma. De Europese artikelnummering. Reeks alleen bestaande uit cijfers. Product Informatie Management. Systeem waarmee product informate beheert kan worden. Bestand dat alle productinformatie bevat. Dit bestand wordt door de groothandels opgemaakt en aangeboden aan bouwmaterialenvergelijk.nl. Idem als Productenbestand. Echter in dit document refereren we specifiek naar de methode om de data in een XML opgebouwd bestand aan te leveren. Elk productenbestand is opgebouwd uit productvelden. Deze velden definiëren een separaat product. Universal Product Code of UPC is een streepjescode. Extensible Markup Language (XML) is een standaard opmaak voor gestructureerde gegevens. 4 A a n l e v e r s p e c i f i c a t i e s v o o r p r o d u c t e n

5 Productvelden specificatie Bijna elk type formaat van het productenbestand is opgebouwd uit een productenlijst. Deze lijst bevat product specifieke informatie welke wordt gebruikt in de BMV website. Om de verwerking van deze data zo nauwkeurig mogelijk te laten verlopen en om het BMV systeem de data te laten begrijpen maken we gebruik van voorgedefinieerde productvelden. Zo kan er per product via separate productvelden worden aangegeven wat de eigenschappen zijn. De gevulde waardes van de productvelden dienen te voldoen aan voorwaarden zoals type en lengte. De specifieke voorwaarden per veld kun je vinden in onderstaande lijst. Kolomnaam Type Aantal tekens Verplicht Omschrijving en uitleg ID Alfanumeriek Min 1, max 50 Ja Eigen artikelnummer. Dient uniek te zijn binnen je productenreeks. Name Tekst Min 5, max 150 Ja Productnaam. Mag omschrijvend zijn. Geen promotietekst. Geen Merk. Description Tekst Max 5000 Ja Omschrijving van het product. Enkel regeleinde. Geen opmaak. Geen HTML code. ProductCategory Tekst Min 5, max 150 Ja De productcategorie waarbinnen het betreffende product is ingedeeld. Zie paragraaf Productcategorie. Image URL of bestandslocatie Max 250 Nee Webadres of bestandslocatie van afbeelding. Als er een bestandslocatie wordt opgegeven dient er een aparte verzamelbestand (bijv. een ZIP bestand) mee te worden geleverd. Zie paragraaf Afbeeldingen. Availability BMV Voorraadtype 1 Ja De volgende numerieke waardes kunnen worden gebruikt: 1 (op voorraad), 2 (niet op voorraad), 3 (vooraf bestellen). Gebruik alleen het nummer. A a n l e v e r s p e c i f i c a t i e s v o o r p r o d u c t e n 5

6 Kolomnaam Type Aantal tekens Verplicht Omschrijving en uitleg Stock Numeriek Tussen 0 en Nee Aantal stuks op voorraad. DeliveryPeriod Numeriek Tussen 0 en 60 Nee Levertijd in dagen. 0 is direct leverbaar. Price Decimaal Tussen 0 en Ja Verkoopprijs in euro s exclusief btw. Deze wordt weergegeven op de website. Maximaal 2 decimalen. PriceSingle Numeriek Tussen 0 en Ja Prijs per stuk. Kan afwijken als het bijvoorbeeld een verzamelverpakking betreft. Maximaal 6 decimalen. PricingUnit Tekst Max 50 Nee Omschrijving van het volume. Bijvoorbeeld: 200gr, 10 Stuks of 2 m 2 per Pak. GTIN GTIN Code Min 12, max 13 Nee* Product identificatie nummer: UPC (12 tekens) of EAN (13 tekens) MPN Alfanumeriek Min 1, max 100 Nee* Manufacturer Part Number. Fabrikant artikelnummer. Als het een eigen product betreft, gebruik dan artikelnummer. Brand Tekst Min 2, max 100 Ja Merk van het product. ShippingWeight Gram Min 1, max Nee Verzendgewicht van product. Property Tekst Min 3, max 1000 Nee Extra eigenschappen van het product. * Zie per aanleverformaat de voorwaarden voor het gebruik van GTIN en MPN 6 A a n l e v e r s p e c i f i c a t i e s v o o r p r o d u c t e n

7 Identificatie producten Bij het importeren van de aangeleverde gegevens zal er een nieuw product worden aangemaakt dan wel een update worden uitgevoerd afhankelijk van het opgegeven ID. Bestaat een product ID al binnen je account dan zal de informatie van het betreffende product worden overschreven met de nieuw aangeleverde informatie. Twee voorbeelden: 1. Een product heeft ID waarde Deze is in ons systeem nog niet bekend binnen je account. Omdat deze nog niet bekend is wordt er een nieuw product aangemaakt. 2. Een product heeft ID waarde Deze is binnen ons systeem reeds bekend onder jouw account als Gipsschroef. Omdat deze al bekend is zal er geen nieuw product worden aangemaakt maar zal het huidige product met ID 9090 worden vervangen door het nieuwe product met ID 9090 dat in het nieuwe productenbestand staat. Product matching Het belangrijkste onderdeel van het systeem is de mogelijkheid om te vergelijken. Om een vergelijking te kunnen maken zal er op basis van de productklasse een productenreeks worden getoond. Binnen deze reeks is het mogelijk om per product de lijst met leveranciers weer te geven. Deze lijst wordt ook gebruikt bij de vergelijking binnen een projectenlijst. De match tussen een product en leveranciers wordt gedaan op basis van de combinatie merk en MPN of op basis van de GTIN code (EAN of UPC). Bij het aanleveren van het productenbestand is het dus belangrijk dat de GTIN of MPN code wordt meegegeven. Wordt deze niet of niet nauwkeurig meegegeven dan kan het zijn dat het product niet zal verschijnen in de zoek- of vergelijkingsresultaten. Afbeeldingen Afbeeldingen kunnen op twee manieren worden aangeleverd. In het productenbestand kan het webadres van de afbeeldingen worden opgegeven of enkel de bestandslocatie. Het BMV systeem zal bij beide opties de afbeelding eenmalig downloaden en verwerken voor weergave op de website. Momenteel is het alleen mogelijk om afbeeldingen in JPG / JPEG formaat aan te leveren. Bij het opgeven van een webadres van de afbeelding dient de webadres toegankelijk te zijn zonder authenticatie. Het bestand kan dus niet worden gedownload van een website met een gebruikersnaam en wachtwoord beveiliging. A a n l e v e r s p e c i f i c a t i e s v o o r p r o d u c t e n 7

8 Een bestandslocatie opgeven is enkel mogelijk als de afbeeldingen in een grote batch worden geleverd. Bijvoorbeeld in een ZIP or RAR bestand. Hierbij dient de bestandslocatie relatief te zijn opgegeven met betrekking tot het verzamelbestand. Een voorbeeld: Het Image veld heeft als waarde: producten/gereedschap/steeksleutel jpg. Dan zal de afbeelding ook binnen het verzamelbestand in de map producten/gereedschap moeten staan en als bestandsnaam steeksleutel jpg moeten hebben. Productcategorie In het veld ProductCategory dient de categorie te komen waarbinnen het betreffende product is ingedeeld. Belangrijk: Dit dient de categorie te zijn van jouw systeem en niet de categorie van BMV. Hier zijn twee redenen voor: 1. Wij willen het beheer zo makkelijk mogelijk houden voor groothandels. De categoriestructuur zoals je die al kent zal ook bij ons zijn in het beheer systeem bestaan. Dit vergemakkelijkt bijvoorbeeld de koppeling tussen je bestaande klanten en bestaande prijsafspraken op bepaalde productenreeks. 2. BMV werkt met een flexibel categorieseringssysteem. Dat wil zeggen dat het product niet in een vaste categorie is ingedeeld maar binnen meerdere categorieën kan vallen. De notering van de productcategorie dient als volgt te worden opgebouwd: Hoofdcategorie > sub categorie > sub categorie > eind categorie Het is belangrijk dat de categoriestructuur wordt opgedeeld in separate categorieën en dat deze gescheiden worden door een > teken. Het teken dient aan beide kanten een spatie te hebben. Hulp nodig? In de volgende hoofdstukken zullen wij enkele voorbeelden geven van een productenbestand. Heb je zelf te weinig tijd om het productenbestand in orde te maken. Dan kun je ook je onbewerkte data aanleveren. Neem hiervoor contact op met de Service Desk via adres of telefonsich via A a n l e v e r s p e c i f i c a t i e s v o o r p r o d u c t e n

9 Aanleveren als CSV bestand Het aanleveren van een productenbestand in CSV formaat raden wij aan voor lijsten met 50 tot producten. Voor kleinere aantallen kunnen de producten het beste beheert worden via Productenbeheer op de BMV beheer website voor Groothandels. Voor grotere aantallen is een maatwerk oplossing meestal beter geschikt. CSV opmaak Gebruik een ; als scheidingsteken en plaats teksten tussen aanhalingstekens. Excel van Microsoft kan CSV bestanden openen, bewerken en opslaan. Tevens kunnen veel PIM of voorraadbeheer systemen een export maken naar CSV. Kolommen De kolomnamen dienen in de eerste rij van het CSV bestand te worden aangegeven. Hierbij kun je de velden zoals aangegeven in het hoofdstuk Productvelden specificatie als richtlijn gebruiken. De volgorde van kolommen is hierbij niet van belang. De verplichte velden dienen wel aanwezig te zijn. Eigenschap (Property) kolommen in een CSV bestand Hoe meer de productinformatie specifiek gescheiden wordt des te beter deze in de zoekopdrachten naar voren zal komen. Hiervoor bestaat er naast de standaard veld-kolommen het Property kolom. Een CSV productenbestand kan tot 10 Property kolommen bevatten. Deze hoeft niet verplicht gevuld te zijn per product. Pas als er een waarde wordt gegeven zal deze worden meegenomen. De waarde van een Property kolom dient als volgt te worden genoteerd: Attribuutnaam : Attribuut waarde. Bijvoorbeeld voor een balk kan de waarde zijn: Lengte : 100cm. Deze waarde wordt dan als eigenschap van het product verwerkt. De eigenschap van de balk is dat deze een Lengte van 100cm heeft. Deze kan worden gebruikt in de filter* voor het verfijnen van het zoekresultaten. * Meer informatie over de werking van filters m.b.t. aangeleverde attribuut data komt later ter beschikking A a n l e v e r s p e c i f i c a t i e s v o o r p r o d u c t e n 9

10 CSV Bestandscontrole Een CSV bestand is niet makkelijk leesbaar (zie afbeelding I). Vooral bij grotere bestanden zal het vrijwel onmogelijk zijn om het bestand te controleren op eventuele fouten. Bij de eerste versie van de BMV beheer website voor groothandels zal er tussen het uploaden en het importeren automatisch een controle plaatsvinden. Hiermee wordt het gemakkelijk om de bestanden te controleren en de data te bekijken. afbeelding I Voorbeeldbestand Bij dit document is ook een CSV en Excel voorbeeldbestand geleverd. Deze staan in dezelfde map als waar je het gecomprimeerde bestand hebt uitgepakt. De bestandsnaam is Aanleverbestand voorbeeld.csv en Aanleverbestand voorbeeld.xlsx. Deze kun je gebruiken als voorbeeld of je kunt de data verwijderen en deze vervangen met je eigen productenlijst. Hulp nodig? Heb je zelf te weinig tijd om het productenbestand in orde te maken. Dan kun je ook je onbewerkte data aanleveren. Neem hiervoor contact op met de Service Desk via adres servicedesk@bouwmaterialenvergelijk.nl of telefonsich via A a n l e v e r s p e c i f i c a t i e s v o o r p r o d u c t e n

11 Aanleveren als XML (Product feed) Het aanleveren van een productenbestand in XML formaat raden wij aan voor lijsten met 50 tot producten. Voor kleinere aantallen kunnen de producten het beste beheert worden via Productenbeheer op de BMV beheer website voor groothandels. Voor grotere aantallen is een maatwerk oplossing vaker beter geschikt. Bestaande product feeds Bestaat er al een product feed van je producten? Neem dan contact met ons op. Het is goed mogelijk dat deze product feed als maatwerk oplossing kan worden ingezet. XML opbouw De opmaak van het XML is vrij eenvoudig gehouden. Als top node wordt het products element gebruikt. Daarbinnen worden alle producten als product element gedefinieerd. Binnen het product element dienen alle velden zoals aangegeven in het hoofdstuk Productvelden specificatie als element te worden gedefinieerd. Houd er rekening mee bij het opmaken dat XML hoofdlettergevoelig is. Gebruik dus <products> in plaats van <Products>. Alle elementen dienen te worden geschreven in kleine letters. Dit geldt ook voor de productveld elementen. Bijvoorbeeld het productveld DeliveryPeriod dient te worden geschreven als <deliveryperiod>...</deliveryperiod>. Eigenschappen (Property) Een uitzondering in de opmaak van de XML met betrekking tot de productveld specificatie richtlijnen is het gebruik van het Property productveld. Deze dient als volgt te worden gebruikt binnen een product element: <properties> <property name= Eigenschap naam 1 >Eigenschap waarde 1</property> <property name= Eigenschap naam 2 >Eigenschap waarde 2</property>... </properties> A a n l e v e r s p e c i f i c a t i e s v o o r p r o d u c t e n 11

12 Voorbeeld XML In onderstaande voorbeeld zie je de algemene implementatie van de richtlijnen voor een BMV product feed. Bij dit document is ook een uitgebreider XML voorbeeldbestand geleverd. Deze staat in dezelfde map als waar je het gecomprimeerde bestand hebt uitgepakt. De bestandsnaam is Aanleverbestand voorbeeld.xml. Gebruik bij het opzetten van je product feed de condities van de velden die zijn aangegeven in het hoofdstuk Productvelden specificatie. Dus als een veld verplicht is, dient deze ook aanwezig te zijn binnen de product-node. Is het veld niet verplicht dan hoeft deze ook niet te worden inbegrepen. <?xml version= 1.0 encoding= utf-8?> <products> <product> <id> </id> <name>gipsplaat A-plaat 12,5x1200x2400mm</name> <description>beplating op een onderconstructie...</description> <productcategory>afbouw > Platen > Gipskartonplaten</productcategory> <image>gpak00001.jpg</image> <availability>1</availability> <stock>1000</stock> <shippingtime>0</shippingtime> <price>10</price> <pricesingle>10</pricesingle> <mpn>en 520 A</mpn> <brand>knauf</brand> <properties> <property name= Dikte >12,5 mm</property> <property name= Breedte >1200mm</property> <property name= Lengte >2400mm</property> </properties> </product> <product>... </product>... <products> Hulp nodig? Heb je zelf te weinig tijd om het productenbestand in orde te maken. Dan kun je ook je onbewerkte data aanleveren. Neem hiervoor contact op met de Service Desk via adres of telefonsich via A a n l e v e r s p e c i f i c a t i e s v o o r p r o d u c t e n

13 Maatwerk bij complexe of grote databestanden Het kan voorkomen dat het aanleveren van de productdata in CSV of XML formaat niet toereikend of mogelijk is. Dit kan bijvoorbeeld zijn wanneer het bron systeem, bijvoorbeeld het product informatie of voorraad beheer systeem, geen standaard optie heeft voor de uitvoer van data in deze formaten. Een andere reden kan zijn dat het aantal producten dat moet worden overgezet simpelweg te veel is om dit via een van deze twee opties te doen. In deze en elk ander geval waarbij CSV en XML niet voldoende opties biedt kunnen we een maatwerk oplossing creëren. Diverse oplossingen Als we over maatwerk spreken, dan spreken we over een breed scala aan mogelijkheden. Het hoeft niet altijd een oplossing zijn waarbij er een extra systeem wordt gecreëerd. Een oplossing kan zijn dat BMV de productdata zelf importeert vanuit onbewerkte data. Bijvoorbeeld direct uit een webshop database. Aan de andere kant kan het voorkomen dat er wel wordt gekozen voor een extra systeem die continu de data tussen BMV en het bron systeem synchroniseert. Welke richting er gekozen wordt kan pas worden bepaald aan de hand van een analyse. Dit is afhankelijk van veel factoren. Hier is op voorhand dus geen uitsluitsel over te geven. A a n l e v e r s p e c i f i c a t i e s v o o r p r o d u c t e n 13

14 Producten beheren via Productenbeheer Binnenkort wordt de BMV beheer website voor groothandels gelanceerd. Naast onder andere statistieken* inzien en orderbeheer* is dit ook de plek waar CSV bestanden kunnen worden geüpload en gecontroleerd. Daarnaast zal het ook mogelijk zijn om product feeds in te stellen en te controleren. Productenbeheer De productdata zal veelal uit externe bronnen komen. Vanuit deze systematiek wordt er ook van uitgegaan dat de externe informatie de waarheid is. Oftewel, alle productinformatie wijzigingen dienen vanuit de bron te worden gemaakt. Deze informatie dient dan te worden gesynchroniseerd met de BMV database. Echter omdat een van de kern onderdelen van het BMV systeem een PIM (Product Informatie Management) systeem is, kan dit wel worden gebruikt om bijvoorbeeld productdata te verrijken. Zo behoudt je de waarheid systematiek maar blijf je wel flexibel genoeg om de data te kunnen verbeteren of aan te passen aan specifieke eisen. Kleine productenlijsten Via de BMV beheer website voor groothandels is het ook mogelijk om helemaal zonder externe bron te werken. Het is mogelijk om producten aan te maken, te bewerken en verwijderen. Dit is alleen aan te raden voor groothandels met een klein assortiment op BMV. * Meer informatie over statistieken en orderbeheer komt later ter beschikking 14 A a n l e v e r s p e c i f i c a t i e s v o o r p r o d u c t e n

15 Prijs- en voorraadinformatie Voor het aanleveren van prijs- en voorraadinformatie kan er gebruikt worden gemaakt van een separaat productenbestand. Dit bestand heeft enkel de functie bestaande producten upte-daten met actuele informatie over de prijs en voorraad. Dit bestand kan dus enkel producten bevatten die al zijn ingevoerd in het BMV systeem onder jouw account. Het bestand select aantal productvelden: ID (Verplicht), Availability, Stock, Price en PriceSingle. Op ID na is geen enkel veld een verplicht veld. Er geldt echter wel een regel voor het aanpassen van de prijs. Deze dient altijd in de combinatie van Price met PriceSingle te worden gedaan. Een voorbeeld: <?xml version= 1.0 encoding= utf-8?> <products> <product> <id> </id> <availability>1</availability> <stock>1000</stock> </product> <product> <id> </id> <price>10,50</price> <pricesingle>10,50</pricesingle> </product> <product> <id> </id> <stock>5</stock> </product> <product>... </product>... <products> Hulp nodig? Heb je zelf te weinig tijd om het productenbestand in orde te maken. Dan kun je ook je onbewerkte data aanleveren. Neem hiervoor contact op met de Service Desk via adres of telefonsich via A a n l e v e r s p e c i f i c a t i e s v o o r p r o d u c t e n 15

16 Aanlevermethodes Het producten updatebestand kan op verschillende manieren worden aangeleverd: Productenbestand uploaden De bestanden kan je uploaden via de BMV beheer website voor groothandels. Hiervoor dien je een beheer account te hebben. (Momenteel is de optie enkel beschikbaar voor personen uit het test-panel) Product feed De bestanden kun je op je eigen website / server beschikbaar stellen. Voor deze optie dien je de adressen op te geven van de bestanden via de BMV beheer website voor groothandels. Het BMV systeem zal het productenbestand eenmalig automatisch downloaden. Daarna dient dit via de beheer website manueel geactiveerd te worden. Het updatebestand wordt 1 maal per dag automatisch gedownload. (Momenteel is de optie enkel beschikbaar voor personen uit het test-panel) Manueel aanleveren De bestanden of locatie van de bestanden kunnen worden gestuurd naar servicedesk@ bouwmaterialenvergelijk.nl. De bestanden zullen dan manueel worden verwerkt door de afdeling Operations van BMV. 16 A a n l e v e r s p e c i f i c a t i e s v o o r p r o d u c t e n

17 A a n l e v e r s p e c i f i c a t i e s v o o r p r o d u c t e n 17

18 b o u w m a t e r i a l e n v e r g e l i j k. n l Aanleverspecificaties voor Producten 18 A a n l e v e r s p e c i f i c a t i e s v o o r p r o d u c t e n