De Marie NV Platform - De Marie NV Platform

API Documentatie GET /companies/:machineName/articles

Toon alle artikelen voor een leverancier.

Toon een lijst van alle artikelen voor een specifieke leverancier.

Resource URL

GET https://nvdemarie.ib.nl/api/bulk/v1/companies/:machineName/articles

Placeholder	Formaat	Omschrijving
:machineName	string [\w_]+	De identifier van het bedrijf dat het artikel levert. Zie /companies voor het verkrijgen van de beschikbare machine names.

Query parameters

Naam	Verplicht	Formaat	Standaard	Omschrijving
offset		int	0	Gebruik deze query-parameter voor paginatie. Vul een geheel getal in en krijg de volgende artikelen vanaf dat aantal artikelen.
offset-id		string		Gebruik deze query-parameter voor paginatie. Per resultatenset wordt de huidige en volgende offsetId getoond. Als men de de volgende offsetId hier invuld krijgt men de volgende set artikelen. Deze manier van door de verschillende pagina's heen navigeren werkt sneller dan als men gebruik maakt van de offset.
limit		int	25	Deze query-parameter beperkt het aantal resultaten per response. Let op: De maximale waarde is 100.
expand		bool	false	Zet deze op true om de meest volledige artikelinformatie te krijgen. Gebruikt u de extra informatie niet? Dat kunt u deze boolean beter op false laten staan om zo de snelheid van de API te vergroten en bandbreedte te besparen.
modified		date	false	Indien u hier een datum opgeeft worden enkel de artikelen getoond waarvan de artikelgegevens sinds deze datum zijn gewijzigd. Het formaat kan gegeven worden als "YYYY-MM-DD" of als datum/tijd in het ISO 8601 formaat.
availability		[85E, 91E, 92E]		Indien u hier een beschikbaarheidscode opgeeft worden enkel de artikelen getoond waarvan de beschikbaarheid gelijk is aan de opgegeven beschikbaarheidscode. De mogelijke waarden zijn 85E (actueel: leverbare artikelen), 91E (uitlopend: artikelen die binnenkort uit het assortiment gehaald gaan worden en wellicht slechts beperkt leverbaar zijn) en 92E (vervallen: deze artikelen zijn niet meer leverbaar).
filter-matchcode		bool	false	Indien u deze filter aan zet (op true) worden enkel de artikelen getoond waarvan de matchcode gevuld is. Standaard staat deze filter uit en worden ook artikelen getoond zonder matchcode.
ean		EAN-13		Indien u hier een EAN opgeeft wordt enkel het artikel getoond met deze specifieke EAN. Dit is een EAN-13/GTIN-13 nummer conform de GS1 standaard.
allow-count		bool	true	In de resultatenset is het totaal aantal artikelen voor dit assortiment opgenomen. Bij assortimenten met veel artikelen kan het de snelheid tengoede komen om deze optie uit te zetten (op false).

Resultaat

Bij een 200 OK HTTP-status bevat de response body het volgende JSON object:

Veld	Datatype	Omschrijving
offset	int 0<=n	Deze hoeveelheid aan resultaten zijn vanaf het begin overgeslagen. Indien er een offset query parameter is opgegeven zal deze waarde gelijk zijn aan de opgegeven waarde. De waarde kan echter niet negatief zijn.
offsetId	string|null	De identifier van de huidige resultatenset, deze zal alleen gevuld zijn als in de request gekozen is voor het ophalen van de artikelen op basis van een offsetId.
nextOffsetId	string	De identifier van de volgende resultatenset. Deze kan men gebruiken in de query-parameter offset-id om de volgende set aan artikelen op te halen.
limit	int 1<=n<=100	Geeft aan hoeveel resultaten er maximaal worden getoond. Indien er een limit query parameter is opgegeven zal deze waarde gelijk zijn aan de opgegeven waarde. De waarde is echter minimaal 1 en maximaal 100.
count	int 0<=n	Het aantal items dat in totaal beschikbaar is over alle paginas.
expanded	bool true|false	Boolean waarde. Als deze false is worden enkel de basisvelden weergegeven, bij true wordt de volledige informatie getoond.
changesSince	date	Geeft de datum weer die is opgegeven in de query-parameter modified, als deze niet is ingevuld zal dit veld null tonen.
items	array	Json-array van Article objecten. Afhankelijk van de waarde van expand worden hierin enkel de basisvelden of alle velden getoond.
href	url	De URL naar de huidige pagina in de paginering.
next	url	De volledige URL naar de volgende pagina in de paginering of null als dit de laatste pagina is.
previous	url	De volledige URL naar de vorige pagina in de paginering of null als dit de eerste pagina is.

Article

Veld	Zichtbaar indien niet expanded	Datatype	Omschrijving
ibCode		long	De door IB gehanteerde identifier voor dit specifieke artikel. Let op: Afhankelijk van uw overeenkomst met IB is dit veld wel of niet zichtbaar.
matchCode		string|null	Uw eigen unieke artikelcode voor dit artikel. Indien onbekend is deze null.
parentIbCode		long	In geval van een handelsartikel staat hier de IB code van het artikel in het assortiment van de fabrikant. Let op: Afhankelijk van uw overeenkomst met IB is dit veld wel of niet zichtbaar.
productIbCode		long	In geval dat dit artikel onderdeel is van een product staat hier de IB code van dat product.
articleId		string	Het door de leverancier gehanteerde artikelnummer voor dit artikel.
description		string	De omschrijving van dit artikel.
extendedInfo		string	Uitgebreide artikelomschrijving. Deze kan meerdere regels omvatten.
availability		string	Beschikbaarheidscode van het artikel. De volgende codes kunnen voorkomen: 85E (Actueel) Dit artikel is leverbaar. 91E (Uitlopend) Dit artikel wordt binnenkort uit het assortiment verwijderd. 92E (Vervallen) Dit artikel is in dit assortiment niet meer beschikbaar.
modified		datum	Datum van de meest recente wijziging in de gegevens van dit artikel. Let op: Wijzigingen kunnen zich ook voordoen in een deel van de gegevens die niet via de API inzichtelijk zijn. Een update in de wijzigingsdatum betekend dus niet per definitie dat er voor u gegevens zijn gewijzigd. Andersom kunt u er wel vanuit gaan dat er geen wijzigingen zijn zolang deze datum niet is bijgewerkt.
supplier		Company	Json-object met leveranciersgegevens.
manufacturer		Company	Json-object met fabrikantsgegevens.
units		array	Json-array van TradeUnit objecten. Bevat een opsomming van beschikbare verpakkingen en/of handelseenheden voor dit artikel. Verpakkingen worden altijd in een veelvoud van een kleinere verpekking omschreven.
unitRoles		array	Json-array van TradeUnit objecten. Bevat een opsomming van beschikbare verpakkingen en/of handelseenheden voor dit artikel. Verpakkingen worden altijd in een veelvoud van een kleinere verpekking omschreven.
images		array	Json-array van Image objecten. Bevat een opsomming van beschikbare afbeeldingen bij dit artikel.
documents		array	Json-array van Document objecten. Bevat een opsomming van beschikbare downloadbare documenten bij dit artikel.
properties		object	Bevat een opsomming van artikeleigenschappen in de vorm van een json-object met Property objecten gekeyed op naam.
availability_label		string	Beschikbaarheid van het artikel.
prices		array	Json-array van Price objecten. Bevat een lijst van beschikbare prijzen voor het artikel.
classification		array	Json-array van de classificatie van dit artikel. Bevat de classificatiecodes van verschillende classificatiebomen waartoe dit artikel behoort.
id		string	Unieke sleutel waarmee u in de API gegevens voor dit artikel kunt ophalen.
siteLink		url	URL naar de bijbehorende webpagina met artikelgegevens.
href		url	URL naar de API resource met de volledige informatie voor dit artikel.
parent

TradeUnit

Veld	Datatype	Omschrijving
unitLabel	string	Samenvoeging van aantal en eenheid waaruit de handelseenheid bestaat. (In geval van een doos van 50 stuks is deze waarde "50 st")
eanCode	string|null	Door GS1 uitgegeven EAN code. Dit kan een code volgens het EAN-12, EAN-13 of EAN-14 formaat zijn.
unitAmount	decimal	Aantal deeleenheden in de handelseenheid. (In geval van een doos van 50 stuks is deze waarde "50")
packageName	string	Naam van de handelseenheid. (In geval van een doos van 50 stuks is deze waarde "doos")
unitName	string	Verwijzing naar een kleinere eenheid waaruit deze handelseenheid is opgebouwd. (In geval van een doos van 50 stuks is deze waarde "st")
orderable	bool	Geeft aan of deze eenheid als verpakking bestelbaar is. Niet bestelbare eenheden kunnen enkel als rekeneenheid voor prijzen en/of calculaties worden gebruikt.

Image

Veld	Datatype	Omschrijving
fileName	string	Originele bestandsnaam.
mimeType	string	Bestandsformaat aanduiding volgens het MIME formaat van de Internet Assigned Numbers Authority.
fileSize	int	Bestandsgrootte in bytes.
width	int	Breedte van de afbeelding in pixels.
height	int	Hoogte van de afbeelding in pixels.
download	url	Locatie waarop gemachtigde gebruikers de afbeelding kunnen downloaden.
thumb	url	Locatie van een thumbnail van de afbeelding. Deze heeft een resolutie van 100 x 100 pixels.
summary	string|null	Omschrijving van de afbeelding.

Document

Veld	Datatype	Omschrijving
fileName	string	Originele bestandsnaam.
mimeType	string	Bestandsformaat aanduiding volgens het MIME formaat van de Internet Assigned Numbers Authority.
fileSize	int	Bestandsgrootte in bytes.
download	url	Locatie waarop gemachtigde gebruikers het document kunnen downloaden.
summary	string|null	Omschrijving van het document.

Property

Veld	Datatype	Omschrijving
label	string	De leesbare naam van de eigenschap, bijv. "Kleur".
name	string [\w_]+	Een identifier voor de eigenschap bestaande uit kleine letters en underscores.
value	string	De waarde van de eigenschap. Bij de eigenschap "Kleur" zou deze waarde bijv. "Blauw" kunnen zijn. Indien een eigenschap meerdere waarden bevat worden deze met een "|"-symbool (pipe) gescheiden.

Price

Veld	Datatype	Omschrijving
priceUnitQuantity	decimal	Aantal eenheden in een prijseenheid. (Bij € 1,00 per 5 m2 is deze waarde "5").
priceUnitDescription	string	Naam van de prijseenheid. (Bij € 1,00 per 5 m2 is deze waarde "m2").
priceUnitLabel	string	Vervallen: Gebruik priceUnitDescription in plaats van dit gegeven. Dit veld komt per 1-1-2018 te vervallen.
price	decimal	De prijs per prijseenheid in euros. (Bij € 1,00 per 5 m2 is deze waarde "1").
startDate	datum|null	Ingangsdatum voor deze prijs indien beschikbaar.
endDate	datum|null	Einddatum voor deze prijs indien beschikbaar.
moq	decimal|null	Aantal in de staffelondergrens. (Bij € 1,00 per 5 m2 vanaf 2 pallets is deze waarde "2")
moqUnit	string|null	Staffeleenheid (Bij € 1,00 per 5 m2 vanaf 2 pallets is deze waarde "pallet")
label	string	Naam van het prijstype. Bijvoorbeeld Brutoprijs of Consumentenadviesprijs.
reference	string|null	Uw referentie bij de prijs. Bijvoorbeeld het contractnummer waar de prijs van afkomstig is.
type	string	Sleutel van het prijstype.
companySpecific	bool	Boolean waarde die aangeeft of deze prijs gebonden is aan de afnemer.
active	bool	Boolean waarde die aangeeft of de huidige datum tussen de start en de einddatum valt.
summary	string	Leesbare tekst waarin de bovenstaande gegevens samengevoegd worden weergegeven.

Moderated sets

In sommige situaties wilt u wellicht uitproberen wat een data-update voor gevolgen in uw systeem heeft. Indien u hiervoor een aparte acceptatieomgeving van uw systeem ingericht heeft kunt u gebruik maken van de moderated sets. Artikelupdates komen dan eerst in uw acceptatie omgeving door, en pas nadat u uw goedkeuring heeft gegeven stellen wij de gegevens aan uw productie-omgeving ter beschikking. Eventuele vervolgupdates zullen altijd weer eerst in uw acceptatieomgeving terecht komen.

Om gebruik te maken van de moderated sets geeft u bij uw request een extra HTTP-header met de naam X-Moderation mee. Deze kan de waardes unmoderated, moderated of both bevatten. Dit heeft het volgende effect:

• unmoderated: De API geeft alleen artikelen terug die sinds de laatste goedkeuringsdatum van een specifiek assortiment zijn gewijzigd. Voordat u voor het eerst de wijzigingen in een assortiment (d.w.z. alle artikelen van één leverancier) heeft goedgekeurd zal de API bij deze header-waarde alle artikelen teruggeven. Geef deze waarde mee bij synchronsatie van uw acceptatie-omgeving.
• moderated: De API geeft alleen artikelen terug die voorafgaand aan de laatste goedkeuringsdatum van een specifiek assortiment zijn gewijzigd. Voordat u voor het eerst de wijzigingen in een assortiment heeft goedgekeurd zal de API bij deze header-waarde geen artikelen teruggeven. Geef deze waarde mee bij synchronsatie van uw productie-omgeving.
• both: De API geeft alle artikelen terug ongeacht wijzigings- of goedkeuringsdatum. Dit is tevens het standaard gedrag indien de X-Moderation-header niet wordt meegegeven. Geef deze waarde mee, of laat de header achterwege indien u geen gebruik wenst te maken van moderated sets.

De API geeft tevens de response header X-Moderation-Date terug. De waarde van deze header geeft aan welke bepekerking er op de resultaatset wordt toegepast.

Let op: Middels de X-Environment header bieden wij een acceptatieomgeving van onze API aan. Deze omgeving dient echter als staging-omgeving voor nieuwe functionaliteiten, niet voor data updates. Wij raden u aan enkel in overleg met onze IT-medewerkers gebruik te maken van onze acceptatie-omgeving.