Aanleverspecificaties. voor Producten. Versie 1.0

bouwmaterialenvergelijk.nl

Aanleverspecificaties voor Producten

Versie 1.0

Datum uitgifte: 18-05-2015

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

Aanleverspecificaties

voor producten

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 e-mailadres [email protected] of telefonsich via 040-8429280.


voor producten

3

Terminologie

BMV

Verwijzing naar bouwmaterialenvergelijk.nl.

Alfanumeriek

Decimaal

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.

EAN

De Europese artikelnummering.

Numeriek

Reeks alleen bestaande uit cijfers.

PIM

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.

CSV

Productenbestand

Product feed

Productvelden UPC XML

4

Extensible Markup Language (XML) is een standaard opmaak voor gestructureerde gegevens.


voor producten

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 Omschrijving en uitleg

Type

Aantal tekens

Verplicht

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.


voor producten

5

Kolomnaam Omschrijving en uitleg

Type

Aantal tekens

Verplicht

Stock

Numeriek

Tussen 0 en 500.000

Nee

Numeriek

Tussen 0 en 60

Nee

Tussen 0 en 5.000.000

Ja

Aantal stuks op voorraad.

DeliveryPeriod

Levertijd in dagen. 0 is direct leverbaar.

Price

Decimaal

Verkoopprijs in euro’s exclusief btw. Deze wordt weergegeven op de website. Maximaal 2 decimalen.

PriceSingle

Numeriek

Tussen 0 en 5.000.000

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 per Pak”. 2

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

Gram

Min 1, max 5.000.000

Nee

Min 3, max 1000

Nee

Merk van het product.

ShippingWeight

Verzendgewicht van product.

Property

Tekst

Extra eigenschappen van het product.

* Zie per aanleverformaat de voorwaarden voor het gebruik van GTIN en MPN

6


voor producten

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 10001. 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 9090. 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.


voor producten

7

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-110323.jpg“. Dan zal de afbeelding ook binnen het verzamelbestand in de map “producten/gereedschap“ moeten staan en als bestandsnaam “steeksleutel-110323.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 e-mailadres [email protected] of telefonsich via 040-8429280.

8


voor producten

Aanleveren als CSV bestand Het aanleveren van een productenbestand in CSV formaat raden wij aan voor lijsten met 50 tot 10.000 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


voor producten

9

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 e-mailadres [email protected] of telefonsich via 040-8429280.

10


voor producten

Aanleveren als XML (Product feed) Het aanleveren van een productenbestand in XML formaat raden wij aan voor lijsten met 50 tot 100.000 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 . 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>....

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 name=”Eigenschap naam 2”>Eigenschap waarde 2 .....


voor producten

11

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. <products> <product> 68463684 Gipsplaat A-plaat 12,5x1200x2400mm <description>Beplating op een onderconstructie ... <productcategory>Afbouw > Platen > Gipskartonplaten GPAK00001.jpg 1 <stock>1000 <shippingtime>0 <price>10 <pricesingle>10 <mpn>EN 520 – A Knauf <properties> <property name=”Dikte”>12,5 mm <property name=”Breedte”>1200mm <property name=”Lengte”>2400mm <product> .... ... <products>


12


voor producten

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.


voor producten

13

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


voor producten

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: <products> <product> 68463684 1 <stock>1000 <product> 4846411 <price>10,50 <pricesingle>10,50 <product> 1515556 <stock>5 <product> .... ... <products>



voor producten

15

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


voor producten


voor producten

17

bouwmaterialenvergelijk.nl

Aanleverspecificaties voor Producten

18


voor producten

Aanleverspecificaties. voor Producten. Versie 1.0

Recommend Documents