API endpoint: https://voorraad.grsservices.nl/api/
API Token: doorgegeven door GRS, of op te halen via https://voorraad.grsservices.nl/tokens
Via deze API kunnen voorraad gegevens van retailers opgehaald worden. De standaardmethode hiervoor is een server-to-server koppeling. Hierbij kan de volledige database gesynchroniseerd worden, maar is het ook mogelijk om voorraadgegevens per product op te halen.
Leveranciers hebben alleen toegang tot de voorraadgegevens van producten die door GRS aan de leverancier zijn gekoppeld.
Toegang tot de API is alleen mogelijk met een geldige token. Deze token wordt over het algemeen niet gewijzigd en wordt direct in de requests meegestuurd.
De token wordt meegestuurd in een "Authorization" header:
GET /api/product/1234567890123 HTTP/1.1 Host: voorraad.grsservices.nl Authorization: Bearer TOKEN
Het is ook mogelijk om voor testdoeleinden de token als GET parameter mee te sturen:
https://voorraad.grsservices.nl/api/product/1234567890123?token=TOKEN
Om te voorkomen dat derden de API token kunnen gebruiken, kan deze voor de javascript requests aangepast worden. Dit kan bijvoorbeeld door een timestamp, id en hash te gebruiken. Bijvoorbeeld:
$token = 'abcdef'; $timestamp = time(); $uid = 123; $js_token = $uid . '-' . $timestamp . '-' . md5($token . $timestamp);
Hiermee is het mogelijk om een token met beperkte houdbaarheid te genereren.
Deze methode wordt gebruikt om een lokale kopie van de volledige database bij te houden.
Bij elke request wordt een sync_id meegegeven, wanneer deze niet in de request staat wordt het begin van de lijst getoond. In elke response van de server staat een next_sync_id, deze moet bij de volgende request meegestuurd worden, maar alleen als alle gegevens succesvol verwerkt zijn.
De volledige synchronisatie is te bereiken op "/sync", eventueel kan een "limit" als GET parameter meegestuurd worden (default is 100):
https://voorraad.grsservices.nl/api/sync/SYNC_ID
Er komt een antwoord in het volgende formaat terug:
{
"success": true,
"eol": true,
"next_sync_id": "6672616948607483907",
"result": [
{
"barcode": "8711904154370",
"data": {
"barcode": "8711904154370",
"name": "elho barcelona balkonbak schotel 90cm wit",
"stock": [
{
"retailer": 1,
"stock": 7,
"google_place_id": "ChIJVzL1y9jjxUcR5paDeZvVacw"
}
]
}
},
{
"barcode": "8711904154371",
"data": null
}
]
}
Het is mogelijk dat er resultaten tussen staan zonder voorraadgegevens. Dit zijn producten die wel aan de leverancier gekoppeld zijn, maar waarbij de retailers geen voorraad hebben doorgegeven. Deze staan over het algemeen aan het begin van de synchronisatielijst.
| Veld | Uitleg |
|---|---|
| success | Geeft aan of de invoer correct is, wanneer deze waarde anders dan true is kan de respons niet verwerkt worden. In dat geval staat er doorgaans ook een error veld in de respons met aanvullende informatie over het probleem. |
| eol | Geeft aan of het einde van de lijst bereikt is. Wanneer de waarde op false staat zijn er direct meer gegevens beschikbaar en kan er direct een nieuw request gedaan worden. Wanneer de waarde true is moet er met een volgende request gewacht worden. |
| next_sync_id | De sync id die bij de volgende request gebruikt moet worden. Gebruik deze alleen als alle gegevens op de juiste manier verwerkt zijn. |
| result | Lijst met product objecten. |
| result/barcode | Unieke id van het product, in dit geval de barcode die ook in de data staat. |
| result/data | Gegevens van het product. Wanneer deze waarde null is, is het product verwijderd. |
| result/data/stock | Voorraadgegevens met een retailer-id en voorraadwaarde. De gegevens van de retailers worden via de "/retailers" API opgehaald. Wanneer de stock "0" is, is het product niet op voorraad Wanneer de stock "null" is, wordt het product door de retailer verkocht maar is de voorraad niet bekend |
De gegevens kunnen ook real-time uit de API gehaald worden, bijvoorbeeld bij het tonen van een productpagina of overzicht. Het voordeel hiervan is dat er geen lokale database met voorraadgegevens nodig is, het nadeel is een grotere hoeveelheid requests naar de API en extra laadtijd.
Losse producten kunnen via de "/product" API opgehaald worden, meerdere worden via "/products" opgehaald. Het product-object is hetzelfde als bij de synchronisatie API.
https://voorraad.grsservices.nl/api/product/8711904154370
Het is ook toegestaan om de barcode als GET of POST parameter mee te geven. Er komt een antwoord in het volgende formaat terug:
{
"success": true,
"data": {
"barcode": "8711904154370",
"name": "elho barcelona balkonbak schotel 90cm wit",
"stock": [
{
"retailer": 1,
"stock": 7,
"google_place_id": "ChIJVzL1y9jjxUcR5paDeZvVacw"
}
]
}
}
Meerdere producten in één request worden als volgt opgehaald:
https://voorraad.grsservices.nl/api/products?barcodes=8711904154370,8711904154371
Het is ook toegestaan om de barcodes met een POST request door te sturen. Er komt een antwoord in het volgende formaat terug:
{
"success": true,
"data": [
{
"barcode": "8711904154370",
"success": true,
"data": {
"barcode": "8711904154370",
"name": "elho barcelona balkonbak schotel 90cm wit",
"stock": [
{
"retailer": 1,
"stock": 7,
"google_place_id": "ChIJVzL1y9jjxUcR5paDeZvVacw"
}
]
}
},
{
"barcode": "8711904154371",
"success": false,
"error": "No product found for barcode"
}
]
}
De lijst met actieve retailers kan via "/retailers" opgehaald worden:
https://voorraad.grsservices.nl/api/retailers
De respons bevat een lijst met retailers en bijbehorende gegevens:
{
"success": true,
"data": [
{
"id": 1,
"google_place_id": "ChIJVzL1y9jjxUcR5paDeZvVacw",
"name": "Tuincentrum Osdorp",
"address": "Osdorperweg 247",
"zipcode": "1069 LL",
"city": "Amsterdam-Osdorp",
"website": "https://www.osdorp.nl/",
"product_url": "https://www.osdorp.nl/zoeken?q={barcode}&search-submit=Zoeken",
"image": "https://voorraad.grsservices.nl/images/retailer/osdorp.png",
"location": [
52.35162,
4.79046
]
},
{
"id": 2,
"google_place_id": "ChIJd8zuZdCsyEcRSUzJRwf5-FU",
"name": "Tuincentrum de Boet",
"address": "Oosterboekelweg 2-A",
"zipcode": "1718 LN",
"city": "Hoogwoud",
"website": "http://www.webshopdeboet.nl/",
"product_url": null,
"image": "https://voorraad.grsservices.nl/images/retailer/de_boet.png",
"location": [
52.71978,
4.94292
]
}
]
}