Inleiding
Dit document omschrijft de API koppeling voor Menuez om vanaf een externe website een bestelling te kunnen plaatsen. De API heeft de volgende basis kenmerken:
- Beschikbaar via HTTPS met basic authenticatie
- Request body en Reponse body als JSON (indien van toepassing)
URL en Authenticatie
curl "https://menuez.nl/api/v2/..."
-u "email:password"
Elk request wordt geauthenticeerd middels HTTP Basic authenticatie. U ontvangt van Menuez een gebruikersnaam en wachtwoord, en een URL voor de staging- en productieomgeving om toegang tot de API te krijgen.
De staging omgeving kunt u gebruiken om testorders aan te bieden. Dit is een afgesloten omgeving waaruit geen actie wordt ondernomen en geen mails naar klanten worden gestuurd.
Paginering
Opgevraagde lijsten zijn gepagineerd. Ten behoeve van deze paginering worden een aantal aanvullende headers teruggegeven en zijn er parameters beschikbaar.
Request parameters
| Naam | Type | Omschrijving |
|---|---|---|
| page | Integer | Paginanummer (beginnend bij 1) |
| per_page | Integer | Aantal per pagina (standaard: 20, maximaal: 100) |
Response headers
| Naam | Type | Omschrijving |
|---|---|---|
| X-Total | Integer | Totaal aantal records beschikbaar |
| X-Per-Page | Integer | Aantal geretourneerde records per pagina |
| X-Page | Integer | Paginanummer (beginnend bij 1) |
| X-Total-Pages | Integer | Totaal aantal pagina's |
| X-Next-Page | Integer | Volgend paginanummer (als beschikbaar) |
| X-Prev-Page | Integer | Vorig paginanummer (als beschikbaar) |
Algemeen proces
Om een order te plaatsen, is de volgende informatie noodzakelijk:
- voor welk(e) product(en) een bestelling geplaatst wordt
- voor welke productformaten een bestelling wordt geplaatst en met welke aantallen
- indien het product personaliseerbaar is: hoe dit product opgemaakt dient te worden
Wij hebben een aantal gangbare use cases beschreven voor onze API koppeling. Bekijk hieronder welke use case bij u van toepassing is.
Terminologie
Product
Een product of artikel. Hierin wordt generieke informatie voor dit product opgeslagen, zoals de naam van het product en indien het een personaliseerbaar product is, de variabele waardes voor die personalisatie.
Productformaat
Het formaat waarin het product geleverd kan worden. Een product kan meerdere productformaten hebben. Zo kan een Combideal geleverd worden in bijvoorbeeld A2, A4 en A5 formaten (fysieke formaten), maar bijvoorbeeld ook via PNG formaat aangeleverd worden via de email.
Product Productformaat
De relatie tussen het product en het productformaat met een uniek id.
Productpersonalisatie
Sommige producten zijn personaliseerbaar. Dit betekent dat er teksten en/of afbeeldingen veranderd kunenn worden naar wens van de klant. De specifieke personalisatiegegevens van de klant slaan wij op in een productpersonalisatie.
Productcategorie
Producten kunnen worden geplaatst in een productcategorie. Een productcategorie kan dus een of meerdere producten bevatten. Het categoriseren van producten maakt het makkelijker voor klanten om gerelateerde producten te vinden.
Editor
Personalisaties worden gepersonaliseerd in een editor. Dit kan de editor van Menuez zijn maar ook een Editor die u zelf opzet. Onze API kan voorzien in relevante informatie, voor het zelf opzetten van een editor.
Beeldbank/Image Library
Een beeldbank is een verzameling beelden. Een beeldbank vind je in de JSON response met sleutel: image_libraries. De namen van de beeldbanken zijn de sleutels die als kind onder dit object hangen.
Image Placeholder
Een voorgedefinieerd gebied in een Product voor beelden die
op het eindproduct geplaatst worden. Te vinden in de JSON met
sleutel: image_placeholders.
Beeld
Hiermee doelen we op een beelden uit een beeldbank.
Beelden worden gebruikt als vulling voor een image_placeholder.
Sommige image_placeholders kunnen meerdere beelden bevatten.
De naam van een beeld is een pad naar het grafisch bestand bestemd voor
de productie van het gepersonaliseerd product. Wanneer de gebruiker een beeld kiest,
Wordt de naam als value aan de input van de image_placeholder.
Beelden hebben een preview. Deze komt als image_preview of video_preview
image_preview, in de vorm van een simpele illustratie, *.png *.jpg *.svg *.gif, etc.video_preview, een video bestand.
Productstijl
Stijl die een gebruiker wenst toe te passen op alle image_placeholders voor deze
personalisatie. Te vinden in de JSON als product_styles. Het kiezen van een stijl
beïnvloed uit welke submap de illustraties gehaald worden uit de beeldbank.
wanneer de image placeholder een style_prefix met waarde true heeft.
Denk aan de volgende concepten:
- Huisstijlen
- visitekaartjes
- A4
- enveloppe's
- Weergave van drankverpakkingen op poster
- blik 0.2L
- blik 0.33L
- horecafles
- petfles
- Weergave van ijs op poster
- hoorn
- bak
- Algemene stijl of thema toegepast
- krijtbord
- verguld
- sepia
- full colour
- zwart/wit
- feestelijk
- ambachtelijk
- zakelijk
Use cases
1. Aanbieden van gepersonaliseerd materiaal waarbij winkelmandje en betaling op eigen website plaatsvinden
Dit is een sequence diagram van welke calls er nodig zijn zodat een gebruiker:
- kan zien welke producten staan op uw website of app
- naar een "product aanpassen" pagina kan gaan om zijn nieuwe product te personaliseren (in de editor van Menuez)
- een order kan plaatsen via uw website of app
Relevante calls
- Opvragen van lijst met productcategorieën
- Opvragen lijst van producten binnen een productcategorie
- Maak nieuw product op
- Plaats order met bestaande productpersonalisatie (met als
product_personalization_idhet id dat u terug krijgt in de callback van stap Maak nieuw product op)
(met als product_personalization_id het id dat u terug krijgt in de callback
van stap Maak nieuw product op)
2. Aanbieden van gepersonaliseerd materiaal, zonder gebruik van de Menuez personalisatie editor
Het is ook mogelijk om een order te plaatsen bij Menuez, zonder dat de gebruiker wordt doorverwezen naar de Menuez personalisatie editor. Dit kan door de personalisatie gegevens in een JSON body te verpakken en de body te POST-en naar de Menuez API.
We beschrijven eerst hoe u kan achterhalen welke variabelen er voor een product zijn. Daarna heeft u genoeg informatie om een personalisatie via de API op te kunnen stellen.
Ophalen van variabelen
Dit gaat alleen over het proces van ophalen van variabelen. Voor een verdiepende uitleg over de betekenis van complexere objecten verwijzen we je door naar:
Om een goede body op te kunnen stellen, moeten eerst de variabelen van een product opgehaald worden. Zolang het product niet verandert, hoeft dit maar eenmaal per product gedaan worden. Een product categorie kan meerdere variabelen bevatten die gevuld moeten worden met tekst of met plaatjes.
{
"id": 1,
"product_category_id": 1,
"name": "Menu Deal",
"description": "",
"thumbnail_url": "/images/mijn_bedrijfsnaam/product/thumbnail/1/file.jpg",
"video_thumbnail_url": null,
"editor_type": "generic",
"customizable": false,
"text_variables": {
"1:1:Kop:1:text_13:Koptekst": {
"default_value": "Combideal",
"input_type": "text_13",
"input_order": "1",
"group_title": "Kop",
"group_order": "1",
"display_name": "Koptekst"
},
"1:2:Aanbieding:1:text_32:Regel 1": {
"default_value": "Pistolet gezond",
"input_type": "text_32",
"input_order": "1",
"group_title": "Aanbieding",
"group_order": "2",
"display_name": "Regel 1"
},
"1:2:Aanbieding:2:text_32:Regel 2": {
"default_value": "+ 0,5L frisdrank",
"input_type": "text_32",
"input_order": "2",
"group_title": "Aanbieding",
"group_order": "2",
"display_name": "Regel 2"
},
"1:3:Prijs:1:text_2:Prijs in Euro's": {
"default_value": "4",
"input_type": "text_2",
"input_order": "1",
"group_title": "Prijs",
"group_order": "3",
"display_name": "Prijs in Euro's"
},
"1:3:Prijs:2:text_2:Prijs in Eurocenten": {
"default_value": "50",
"input_type": "text_2",
"input_order": "2",
"group_title": "Prijs",
"group_order": "3",
"display_name": "Prijs in Eurocenten"
}
},
"image_placeholders": [
"product_original_default.psd",
"Logo_Placeholder.eps"
],
"product_product_formats": [
{
"id": 1337,
"product_id": 1,
"product_format_id": 666
},
{
"id": 1336,
"product_id": 1,
"product_format_id": 665
}
],
"image_libraries": {
"Eten": [
{
"name": "Aziatisch overige",
"directory": true,
"children": [
{
"name": "Eten/Aziatisch overige/Schaaltje_sushi_temaki_.psd",
"human_name": "Schaaltje sushi temaki ",
"image_library_text_variable_replacements": {},
"image_preview": {
"path": "/image_libraries/tenant/Eten/Aziatisch overige/Schaaltje_sushi_temaki_.png",
"filename": "Schaaltje_sushi_temaki_.png"
}
},
{
"name": "Eten/Aziatisch overige/Loempia_vier_stuks.psd",
"human_name": "Loempia vier stuks",
"image_library_text_variable_replacements": {},
"image_preview": {
"path": "/image_libraries/tenant/Eten/Aziatisch overige/Loempia_vier_stuks.png",
"filename": "Loempia_vier_stuks.png"
}
}
]
}
]
},
"product_styles": {
"4": {
"name": "Full-Colour",
"thumbnails": {
"image": "/images/tenant/product_style/thumbnail/4/image_file.png",
"thumb": "/images/tenant/product_style/thumbnail/4/thumb_file.png",
"large": "/images/tenant/product_style/thumbnail/4/large_file.png",
"mini": "/images/tenant/product_style/thumbnail/4/mini_file.png",
"promo": "/images/tenant/product_style/thumbnail/4/promo_file.png",
"promo_large": "/images/tenant/product_style/thumbnail/4/promo_large_file.png",
"tile": "/images/tenant/product_style/thumbnail/4/tile_file.png",
"video_thumb": "/images/tenant/product_style/thumbnail/4/video_thumb_file.png",
"small_thumb": "/images/tenant/product_style/thumbnail/4/small_thumb_file.png"
}
},
"2": {
"name": "Zwart wit",
"thumbnails": {
"image": "/images/tenant/product_style/thumbnail/2/image_file.png",
"thumb": "/images/tenant/product_style/thumbnail/2/thumb_file.png",
"large": "/images/tenant/product_style/thumbnail/2/large_file.png",
"mini": "/images/tenant/product_style/thumbnail/2/mini_file.png",
"promo": "/images/tenant/product_style/thumbnail/2/promo_file.png",
"promo_large": "/images/tenant/product_style/thumbnail/2/promo_large_file.png",
"tile": "/images/tenant/product_style/thumbnail/2/tile_file.png",
"video_thumb": "/images/tenant/product_style/thumbnail/2/video_thumb_file.png",
"small_thumb": "/images/tenant/product_style/thumbnail/2/small_thumb_file.png"
}
}
},
"product_formats": [
{
"id": 666,
"name": "A2 poster verticaal eenzijdig",
"shipment_type": "postal",
"stock_keeping_unit_id": null,
"num_in_stock": null,
"out_of_stock_prompt": null
},
{
"id": 665,
"name": "A3 poster verticaal enkelzijdig",
"shipment_type": "postal",
"stock_keeping_unit_id": null,
"num_in_stock": null,
"out_of_stock_prompt": null
}
]
}
Hiernaast ziet u een voorbeeld JSON response. ➡
Response gegevens
| Naam | Type | Omschrijving |
|---|---|---|
| id | Integer | Unieke referentie van het product |
| product_category_id | String | Unieke referentie naar de product_categorie |
| name | String | Naam van het product |
| description | String | Beschrijving van het product |
| thumbnail_url | String | Pad naar de thumbnail van het product |
| video_thumbnail_url | String | Pad naar de video thumbnail van het product |
| customizeable | Boolean | Boolean die bepaald of het product bewerkt kan worden |
| editor_type | String | Wat voor type editor gebruikt wordt |
| text_variables | Object | Het veld text_variables retourneert een JSON object met alle text variabelen die op dit product van toepassing zijn |
| text_variables > {naam} | String | Unieke Key van text variabele |
| text_variables > {naam} > default_value | String | Standaard waarde van de input |
| text_variables > {naam} > input_type | String | Duidt aan wat voor type input het is |
| text_variables > {naam} > input_order | String | Volgorde waarin inputs gepresenteerd moeten worden binnen hun groep |
| text_variables > {naam} > group_title | String | Titel van de groep waar dit input veld onderdeel van uitmaakt |
| text_variables > {naam} > group_order | String | Volgorde van de groepen binnen de editor |
| text_variables > {naam} > display_name | String | Waarde voor het label van de input |
| image_placeholders | Object | Object van meerdere image_placeholders |
| image_placeholders > {naam} | String | Wordt gebruikt als key van image_placeholders, dit is de naam van een image_placeholder. |
| image_placeholders > {naam} > default_image | String | Standaard waarde van de input |
| image_placeholders > {naam} > text_variable_group | String | De value in deze key geeft aan bij welke groep de input hoort. |
| image_placeholders > {naam} > allow_upload | Boolean | Bepaalt of een gebruiker beelden mag oploaden |
| image_placeholders > {naam} > image_library_id | String | Het id van de beeldbank waaruit beelden geselecteerd mogen worden |
| image_placeholders > {naam} > image_library_text_variable_replacements | Object | Object met standaardwaardes die overgenomen worden wanneer een beeld gekozen wordt |
| image_placeholders > {naam} > range_select | Boolean | Of er sprake is van een reeks afbeeldingen binnen een beelbank. |
| image_placeholders > {naam} > range_limit | Boolean/Integer | false of een integer 1, 2, dicteert de limiet aan gekozen beelden voor deze placeholder, wanneer range_select true is. |
| image_placeholders > {naam} > range_required | Array | Welke beelden vereist zijn binnen de range |
| image_placeholders > {naam} > images_show | Array | Welke beelden voor de betreffende image_placeholder, beschikbaar zijn als keuze voor de gebruiker |
| image_placeholders > {naam} > image_hidden | String | Welke beelden voor de betreffende image_placeholder, niet beschikbaar zijn als keuze voor de gebruiker |
| image_placeholders > {naam} > style_prefix | Boolean | Of beelden uit een submap in de image library gezocht moeten worden? |
| image_libraries | Object | Object van meerdere image_libraries |
| image_libraries > {naam} | Object | Wordt gebruikt als key van image_libraries, dit is de naam van een image_library. |
| image_libraries > {naam} > {map/beeld} | Array | Array van JSON objecten die een map of beeld representeren in een mappenstructuur |
| image_libraries > {naam} > {map} > name | String | Naam van map in image_library |
| image_libraries > {naam} > {map} > directory | Boolean | Is dit een map? Ja/nee |
| image_libraries > {naam} > {map} > children | Array | Array van bestanden/mappen in map of image_library |
| image_libraries > {naam} > {beeld} > name | String | Pad als naam van beeld in image_library |
| image_libraries > {naam} > {beeld} > human_name | String | Weer te geven naam aan gebruiker |
| image_libraries > {naam} > {beeld} > image_library_text_variable_replacements | Object | Over te nemen waardes wanneer dit beeld gekozen wordt. |
| image_libraries > {naam} > {beeld} > image_preview | Object | Object waarin informatie over de preview staat |
| image_libraries > {naam} > {beeld} > image_preview > path | String | Pad naar een preview van het beeld |
| image_libraries > {naam} > {beeld} > image_preview > filename | String | Bestandsnaam van een beeld preview |
| image_libraries > {naam} > {beeld} > video_preview > path | String | Pad naar een preview van de video |
| image_libraries > {naam} > {beeld} > video_preview > filename | String | Bestandsnaam van een video preview |
| product_styles | Array | Array van product_styles |
| product_styles > id | Integer | Unieke referentie naar product_style |
| product_styles > name | String | Naam van de productstijl |
| product_styles > thumbnails | Object | Object met paden naar previews het effect op een gekozen stijl |
| product_styles > thumbnails > * | Object | Key met naam van een preset van een illustratie, de values zijn een pad van een preview plaatje, beschikbaar in diverse grootte's. |
| product_product_formats | Array | Array van product_product_format objecten |
| product_product_formats > id | Integer | Unieke referentie van product_product_format |
| product_product_formats > product_id | Integer | Unieke referentie naar product |
| product_product_formats > product_format_id | Integer | Unieke referentie naar product_format |
| product_formats | Array | Array van product_format objecten |
| product_formats > id | Integer | Unieke referentie van het product_format |
| product_formats > name | String | Naam van product_format |
| product_formats > shipment_type | String | Manier waarop order verscheept wordt |
| product_formats > stock_keeping_unit_id | Integer | Referentie naar Stock Keeping Units |
| product_formats > num_in_stock | Integer | Hoeveelheid op voorraad |
| product_formats > out_of_stock_prompt | String | Weer te geven boodschap aangaande voorraad |
Relevante calls
Of
{
"shipment": {
"name": "Joost", // adres waar het product naar toe moet
"company_name": "MyCompany b.v.",
"address_street": "Voorbeeldstraat",
"address_street_number": "1",
"address_street_number_suffix": "B",
"address_zip_code": "1234 AB",
"address_city": "Amsterdam",
"address_country": "NL",
"email_address": "info@example.com"
},
"product_personalizations": [ // hier gaan we de waardes voor deze specifieke producten invullen
{
"reference": "mijneerstepersonalisatie", //naam van de personalisatie om later naar te refereren.
"product_id": 1, //welk product
"text_variables": {
"1:1:Keuze 1 | Menu titel text:Naam": "Pata Pata Snack",
"1:1:Keuze 1 | Menu prijs:2:text_7:Prijs": "€4,50",
"1:2:Keuze 2 | Super deal menu prijs:2:text_7:Prijs": "€5,00",
"1:3:Keuze 3 | Beste deal prijs:2:text_7:Prijs": "€5,25"
},
"image_placeholders": {
"product_original_default.psd": {
"file": "data:image/png;base64,XXX" //base64 encoded png bestand
},
"Logo_Placeholder.eps": { "file": "data:image/png;base64,YYY"}
}
}
],
"products": [
{
"product_id": 1,
"product_format_id": 1, // Bijv. een A1
"quantity": 1,
"product_personalization_reference": "mijneerstepersonalisatie"
}, {
"product_id": 1,
"product_format_id": 2, // Bijv. een A4
"quantity": 1,
"product_personalization_reference": "mijneerstepersonalisatie"
}, {
"product_id": 1,
"product_format_id": 3, // Bijv. een digitaal bestand
"quantity": 1,
"product_personalization_reference": "mijneerstepersonalisatie"
}
]
}
Order plaatsen
Als u de variabelen voor een product weet, kunt u op uw eigen website de klant een gepersonaliseerd product laten maken. Als de klant klaar is, kunt u de gegevens POST-en naar de API. Hiernaast kunt u een voorbeeld body zien die u moet meegeven wanneer u een order plaatst. ➡
POST /api/v2/orders
<input type="text" name="{{key van instantie uit text_variables}}" />
customizable
Dit attribuut beantwoord met true of false de vraag: Is het product
aan te passen?
editor_type
Menuez heeft vele editor_type, middels de api is enkel generic
beschikbaar. In deze documentatie vind je de uitleg van het type generic.
Wanneer de editor niet van dit type is. Verwijs dan door naar de editor van
Menuez voor dit product.
Mocht je graag willen dat via de API een andere editor_type beschikbaar wordt neem dan contact met ons op.
Uitleg Text Variables
Het veld text_variables retourneert een JSON object met alle text
variabelen die op dit product van toepassing zijn.
text_variables>name
De keys van de JSON object zijn de namen van de input-velden die we terug verwachten bij het aanmaken van een order of personalisatie. ➡
<input value={{default_value}}/>
default_value
Dit is de standaard innerText waarde van het input veld. ➡
input_type
Het input_type bepaalt wat voor soort input aan de gebruiker gepresenteerd
moet worden.
<input type="text"/>
text
Dit wordt een input type text. ➡
<input ... maxlength=10 />
text_\d
Wanneer het input_type begint met text_ en wordt gevolgd door een getal,
dan wordt verwacht dat het getal wordt gebruikt als maxlength-attribuut op het
input-veld.
Voorbeeld bij text_10 ➡
<input type="textarea" />
textarea
Dit wordt een input type textarea.
voorbeeld ➡
<input ... rows=5 />
textarea_\d
Wanneer het textarea begint met textarea_ en wordt gevolgd door een getal,
dan wordt verwacht dat het getal wordt gebruikt als het rows-attribuut.
Voorbeeld bij textarea_5 ➡
date_dd-mm-yyyy
We verwachten een string van de datum, in het volgende formaat dd-mm-yyyy
<input type='text' value={{company_name}} />
<input type='text' value={{company_name}} maxlength=100 />
Vooraf ingevulde type's
Bovenstaand dient gevuld te worden met een initiele waarde. Verder fungeert het gelijk aan het tekst veld ook text_\d) een maximale lengte kan hebben. Kunnen al deze types ook een maximale lengte hebben.
company_namecontactaddress_addressaddress_zip_codeaddress_citytelephone_numbermobile_numberfax_numberemail_addresswebsite_urlfacebook_urlopening_hours_mondayopening_hours_tuesdayopening_hours_wednesdayopening_hours_thursdayopening_hours_fridayopening_hours_saturdayopening_hours_sunday
Voorbeeld bij company_name en company_name_100 ➡
<input type='text' />
ongedefineerd
Wanneer het input_type deze "" is. Dient het als een tekst
behandeld te worden. Deze velden hebben geen maximale lengte.
Voorbeeld ➡
input_order
De volgorde waarin de inputs gepresenteerd moeten worden binnen hun groep.
group_title
De titel van de groep waar de input in valt.
group_order
De volgorde van de groepen binnen de editor.
<label>{{display_name}}</label>
display_name
De waarde voor het label element van de betreffende input.
Uitleg Image Placeholders
Hieronder vind je een uitleg van alle attributen die een element uit image_placeholders bevat.
image_placeholders
Hierin vind je objecten die een image_placeholder representeren.
{
"image_placeholders": {
"ImagePlaceholderNaam": {
// Attributen...
}
}
}
image_placeholder>name
De key van een image placeholder representeert de naam van de placeholder.
image_name
De naam die gebruikt wordt als label voor de input voor het selecteren van een plaatje.
default_image
De value in deze key geeft aan welk beeld gekozen wordt wanneer geen beeld aangeleverd wordt.
text_variable_group
De value in deze key geeft aan bij welke groep de input hoort.
allow_upload
Dit veld beantwoordt de vraag: Mag het beeld zelf aangeleverd worden?
Wanneer dit true is mag dit door gebruikers zelf geüploadet worden.
Wanneer dit false is moet het beeld uit de gekoppelde beeldbank gekozen worden.
{
//...
"image_placeholders": {
"Oktoberfest-combideal.psd": {
"default_image": "Bierfestijn.psd",
"text_variable_group": "Bierfeesten",
"allow_upload": false,
"image_library_id": "Bierfeesten_",
"range_select": false,
"range_limit": false,
"range_required": [],
"images_show": [],
"images_hidden": [],
"image_library_text_variable_replacements": {
"exif_1": "1:2:Bierfeesten:1:text_20:Product",
"exif_2": "1:2:Bierfeesten:2:text_30:Beschrijving 1",
"exif_3": "1:2:Bierfeesten:3:text_30:Beschrijving 2"
},
"style_prefix": false
}
},
"image_libraries": {
"Bierfeesten_": [
{
"name": "2020",
"directory": true,
"children": [
{
"name": "Lente_2020",
"directory": true,
"children": [
{
"name": "Bierfeesten_/2020/Lente_2020/Machtige_Reus.psd",
"file_name": "Machtige_Reus.psd",
"human_name": "Machtige Reus",
"image_library_text_variable_replacements": {
"Oktoberfest-combideal.psd": {
"exif_1": "Deal",
"exif_2": "Bij een braadworst naar ",
"exif_3": "keuze een Machtige Reus voor 1,50"
}
},
"image_preview": {
"path": "/image_libraries/tenant/Bierfeesten_/2020/Lente_2020/Machtige_Reus.png",
"filename": "Machtige_Reus.png"
}
},
{
"name": "Bierfeesten_/2020/Lente_2020/Stroperige_Rakker.psd",
"file_name": "Stroperige_Rakker.psd",
"human_name": "Stroperige Rakker",
"image_library_text_variable_replacements": {
"Oktoberfest-combideal.psd": {
"exif_1": "Lentedeal",
"exif_2": "De Stroperige Rakker gaat goed samen met",
"exif_3": "Nacho Chips"
}
},
"image_preview": {
"path": "/image_libraries/tenant/Bierfeesten_/2020/Lente_2020/Stroperige_Rakker.png",
"filename": "Stroperige_Rakker.png"
}
}
]
}
]
}
]
}
}
image_library_id
Het ID van de beeldbank waaruit beelden gekozen kunnen worden.
image_library_text_variable_replacements
Wanneer een beeld voor een image_placeholder gekozen wordt uit een image_library,
is het de bedoeling dat, op de placeholder de gerelateerde image_library_text_variable_replacements
overgenomen worden uit de image library. De gebruiker kan deze waardes in de editor zelf nog overschrijven.
Wanneer er geen image_library_text_variable_replacements zijn wordt dit veld niet meegestuurd.
relevante keys voor dit voorbeeld:
image_libraries -> image_library_text_variable_replacementsimage_placeholders -> image_library_text_variable_replacements
Voorbeeld
response data ➡
Wanneer iemand in dit voorbeeld het beeld Bierfeesten_/2020/Lente_2020/Stroperige_Rakker.png kiest, dan verwachten we dat het volgende gevuld wordt:
"1:2:Bierfeesten:1:text_20:Product": "Lentedeal""1:2:Bierfeesten:2:text_30:Beschrijving 1": "De Stroperige Rakker gaat goed samen met""1:2:Bierfeesten:3:text_30:Beschrijving 2": "Nacho Chips"
{
"image_library_text_variable_replacements": {
"Oktoberfest-combideal.psd": {
"exif_1": "Lentedeal",
"exif_2": "De Stroperige Rakker gaat goed samen met",
"exif_3": "Nacho Chips"
}
}
}
Waarom? Het gekozen beeld bevat ➡
{
"exif_1": "Lentedeal",
"exif_2": "De Stroperige Rakker gaat goed samen met",
"exif_3": "Nacho Chips"
}
De placeholder waar de gebruiker een beeld kiest heet
Oktoberfest-combideal.psd, waardoor het volgende beschikbaar is ➡
{
"exif_1": "1:2:Bierfeesten:1:text_20:Product",
"exif_2": "1:2:Bierfeesten:2:text_30:Beschrijving 1",
"exif_3": "1:2:Bierfeesten:3:text_30:Beschrijving 2"
}
De placeholder beschrijft ➡
We zullen dus de data van "exif_1": "Lentedeal" moeten toepassen op
"1:2:Bierfeesten:1:text_20:Product".
Zoals eerder gemeld kan de gebruiker eventueel Lentedeal ook nog wijzigigen
in de editor naar bijvoorbeeld Skonne Mensendeal!. We zullen dan de data
van "exif_1": "Skonne Mensendeal!" moeten toepassen op
"1:2:Bierfeesten:1:text_20:Product"
range_select
Het range_select attribuut geeft aan of een reeks plaatjes binnen een
beeldbank gekozen worden met true of false.
Wanneer er sprake is van een range worden de volgende attributen ook belangrijk:
range_required
Bepaalt welke beelden uit de beeldbank verplicht gekozen moeten worden.
range_limit
Bepaalt wat de limiet aan gekozen beelden uit de beeldbank is. false
wanneer er geen limiet is.
duplicate_images_forbidden
Beantwoordt de vraag: Staan we het kiezen van hetzelfde beeld voor deze placeholder toe? We controleren niet of bestanden welke door de gebruiker zelf geupload zijn duplicaten hebben. In dit geval kan een beeld dus wel dubbel gebruikt worden.
{
"image_placeholders": {
"BroodjeGezond_LOS.psd": {
"default_image": "Gefrituurde_garnalen_1.psd",
"text_variable_group": "Aanbieding",
"allow_upload": true,
"image_library_id": "Eten",
"range_select": false,
"range_limit": false,
"range_required": [],
"images_show": [],
"images_hidden": [
"Loempia_vier_stuks.png",
"Loempia_2.png"
]
}
},
"image_libraries": {
"Eten": [
{
"name": "Aziatisch overige",
"directory": true,
"children": [
{
"name": "Eten/Aziatisch Overige/Gefrituurde_garnalen_1.psd",
"human_name": "Gefrituurde garnalen 1",
"image_library_text_variable_replacements": {},
"image_preview": {
"path": "/image_libraries/tenant/Eten/Aziatisch Overige/Gefrituurde_garnalen_1.png",
"filename": "Gefrituurde_garnalen_1.png"
}
},
{
"name": "Eten/Aziatisch Overige/Loempia_2.psd",
"human_name": "Loempia 2",
"image_library_text_variable_replacements": {},
"image_preview": {
"path": "/image_libraries/tenant/Eten/Aziatisch Overige/Loempia_2.png",
"filename": "Loempia_2.png"
}
},
{
"name": "Eten/Aziatisch Overige/Loempia_vier_stuks.psd",
"human_name": "Loempia vier stuks",
"image_library_text_variable_replacements": {},
"image_preview": {
"path": "/image_libraries/tenant/Eten/Aziatisch Overige/Loempia_vier_stuks.png",
"filename": "Loempia_vier_stuks.png"
}
}
]
}
]
}
}
images_show images_hidden
Met deze attributen kan de keuzemogelijkheid van beelden voor een image_placeholder beperkt worden.
- De te tonen beelden uit de beeldbank staan in:
images_show - De te verbergen beelden uit de beeldbank staan in:
images_hidden
De values in de array met images_show or images_hidden moeten matchen met
de file_name key van de image_preview. Wanneer dit het geval is, is
respectievelijk het tonen of verbergen van de optie van toepassing.
Voorbeeld 1 ➡
{
"images_hidden": [
"Loempia_vier_stuks.png",
"Loempia_2.png"
]
}
Gegeven bovenstaand, zou alleen Gefrituurde_garnalen_1.png
getoond/beschikbaar worden als keuze in de editor. Dit omdat de andere twee
beelden uit de images_library Eten verborgen worden door ➡
{
"image_placeholders": {
"BroodjeGezond_LOS.psd": {
"default_image": "Gefrituurde_garnalen_1.psd",
"text_variable_group": "Aanbieding",
"allow_upload": true,
"image_library_id": "Eten",
"range_select": false,
"range_limit": false,
"range_required": [],
"images_show": [
"Gefrituurde_garnalen_1.png"
],
"images_hidden": [],
"style_prefix": false
}
},
"image_libraries": {
"Eten": [
{
"name": "Aziatisch overige",
"directory": true,
"children": [
{
"name": "Eten/Aziatisch Overige/Gefrituurde_garnalen_1.psd",
"human_name": "Gefrituurde garnalen 1",
"image_library_text_variable_replacements": {},
"image_preview": {
"path": "/image_libraries/tenant/Eten/Aziatisch Overige/Gefrituurde_garnalen_1.png",
"filename": "Gefrituurde_garnalen_1.png"
}
},
{
"name": "Eten/Aziatisch Overige/Loempia_2.psd",
"human_name": "Loempia 2",
"image_library_text_variable_replacements": {},
"image_preview": {
"path": "/image_libraries/tenant/Eten/Aziatisch Overige/Loempia_2.png",
"filename": "Loempia_2.png"
}
},
{
"name": "Eten/Aziatisch Overige/Loempia_vier_stuks.psd",
"human_name": "Loempia vier stuks",
"image_library_text_variable_replacements": {},
"image_preview": {
"path": "/image_libraries/tenant/Eten/Aziatisch Overige/Loempia_vier_stuks.png",
"filename": "Loempia_vier_stuks.png"
}
}
]
}
]
}
}
Voorbeeld 2 ➡
{
"images_show": ["Gefrituurde_garnalen_1.png"]
}
Gegeven bovenstaand, zou omdat images_show enkel Gefrituurde_garnalen_1.png
bevat. Uit de images_library Eten enkel de beelden uit de array
getoond/beschikbaar moeten zijn:
style_prefix
Deze boolean beantwoordt de vraag:
Moet ik bij het zoeken naar beelden in een image_library, een prefix toevoegen om bij het beeld te komen?
De waarde is true of false.
Zie product_styles voor een nadere uitleg in hoe dit te gebruiken.
Uitleg Product Styles
Wanneer een image_placeholder de waarde "style_prefix": true bevat,
wil dat zeggen dat niet alle beelden uit een image_library geselecteerd
mogen worden. De beelden die beschikbaar blijven, zijn de beelden in de submap
overeenkomstig met het id van de gekozen product_style.
{
"product_styles": [
{
"id": 4,
"name": "Horecafles",
"thumbnails": {
"image": "/images/de-biermagnaat/product_style/thumbnail/4/image_file.png",
"thumb": "/images/de-biermagnaat/product_style/thumbnail/4/thumb_file.png",
"large": "/images/de-biermagnaat/product_style/thumbnail/4/large_file.png",
"mini": "/images/de-biermagnaat/product_style/thumbnail/4/mini_file.png",
"promo": "/images/de-biermagnaat/product_style/thumbnail/4/promo_file.png",
"promo_large": "/images/de-biermagnaat/product_style/thumbnail/4/promo_large_file.png",
"tile": "/images/de-biermagnaat/product_style/thumbnail/4/tile_file.png",
"video_thumb": "/images/de-biermagnaat/product_style/thumbnail/4/video_thumb_file.png",
"small_thumb": "/images/de-biermagnaat/product_style/thumbnail/4/small_thumb_file.png"
}
},
{
"id": 2,
"name": "0,25L Blik",
"thumbnails": {
"image": "/images/de-biermagnaat/product_style/thumbnail/2/image_file.png",
"thumb": "/images/de-biermagnaat/product_style/thumbnail/2/thumb_file.png",
"large": "/images/de-biermagnaat/product_style/thumbnail/2/large_file.png",
"mini": "/images/de-biermagnaat/product_style/thumbnail/2/mini_file.png",
"promo": "/images/de-biermagnaat/product_style/thumbnail/2/promo_file.png",
"promo_large": "/images/de-biermagnaat/product_style/thumbnail/2/promo_large_file.png",
"tile": "/images/de-biermagnaat/product_style/thumbnail/2/tile_file.png",
"video_thumb": "/images/de-biermagnaat/product_style/thumbnail/2/video_thumb_file.png",
"small_thumb": "/images/de-biermagnaat/product_style/thumbnail/2/small_thumb_file.png"
}
},
{
"id": 1,
"name": "0,33L Blik",
"thumbnails": {
"image": "/images/de-biermagnaat/product_style/thumbnail/1/image_file.png",
"thumb": "/images/de-biermagnaat/product_style/thumbnail/1/thumb_file.png",
"large": "/images/de-biermagnaat/product_style/thumbnail/1/large_file.png",
"mini": "/images/de-biermagnaat/product_style/thumbnail/1/mini_file.png",
"promo": "/images/de-biermagnaat/product_style/thumbnail/1/promo_file.png",
"promo_large": "/images/de-biermagnaat/product_style/thumbnail/1/promo_large_file.png",
"tile": "/images/de-biermagnaat/product_style/thumbnail/1/tile_file.png",
"video_thumb": "/images/de-biermagnaat/product_style/thumbnail/1/video_thumb_file.png",
"small_thumb": "/images/de-biermagnaat/product_style/thumbnail/1/small_thumb_file.png"
}
},
{
"id": 3,
"name": "PET-fles",
"thumbnails": {
"image": "/images/de-biermagnaat/product_style/thumbnail/3/image_file.png",
"thumb": "/images/de-biermagnaat/product_style/thumbnail/3/thumb_file.png",
"large": "/images/de-biermagnaat/product_style/thumbnail/3/large_file.png",
"mini": "/images/de-biermagnaat/product_style/thumbnail/3/mini_file.png",
"promo": "/images/de-biermagnaat/product_style/thumbnail/3/promo_file.png",
"promo_large": "/images/de-biermagnaat/product_style/thumbnail/3/promo_large_file.png",
"tile": "/images/de-biermagnaat/product_style/thumbnail/3/tile_file.png",
"video_thumb": "/images/de-biermagnaat/product_style/thumbnail/3/video_thumb_file.png",
"small_thumb": "/images/de-biermagnaat/product_style/thumbnail/3/small_thumb_file.png"
}
}
]
}
Voorbeeld:
De volgende stijlen bestaan:
In dit geval zal de gebruiker om te beginnen moeten kiezen uit één van de
beschikbare stijlen. We gaan in dit voorbeeld er vanuit dat er gekozen wordt
voor "0,33L Blik". In dat geval heeft de id de waarde "1". De gekozen
stijl is dan dus "1".
{
"image_placeholders": {
"SeizoensBiertje.psd": {
"default_image": "SeizoensBiertje.psd",
"text_variable_group": "Aanbieding",
"allow_upload": false,
"image_library_id": "Range",
"range_select": true,
"range_limit": 9,
"range_required": [],
"images_show": [],
"images_hidden": [],
"style_prefix": true
}
}
}
Opvolgend wordt bij een image_placeholder de prefix toegepast als dat nodig
is. Dit wordt aangegeven door de waarde "style_prefix": true; zoals ook
bij placeholder ➡
{
"SeizoensBiertje.psd": {
"image_library_id": "Range",
"style_prefix": true
}
}
Relevante velden ➡
{
"image_libraries": {
"Range": [
{
"name": "1",
"directory": true,
"children": [
{
"name": "Range/1/100.Stroperige_Rakker_can_33cl.psd",
"human_name": "100.CC regular can 33cl",
"image_library_text_variable_replacements": {},
"image_preview": "/image_libraries/tenant/Range/1/100.Stroperige_Rakker_can_33cl.png"
},
{
"name": "Range/1/100.Machtige_Reus_can_33cl.psd",
"human_name": "100.Machtige Reus can 33cl",
"image_library_text_variable_replacements": {},
"image_preview": "/image_libraries/tenant/Range/1/100.Machtige_Reus_can_33cl.png"
}
]
},
{
"name": "2",
"directory": true,
"children": [
{
"name": "Range/2/100.Stroperige_Rakker_can_25cl.psd",
"human_name": "100.Stroperige Rakker can 25cl",
"image_library_text_variable_replacements": {},
"image_preview": "/image_libraries/tenant/Range/2/100.Stroperige_Rakker_can_25cl.png"
},
{
"name": "Range/2/100.Machtige_Reus_can_25cl.psd",
"human_name": "100.Machtige Reus can 25cl",
"image_library_text_variable_replacements": {},
"image_preview": "/image_libraries/tenant/Range/2/100.Machtige_Reus_can_25cl.png"
}
]
},
{
"name": "3",
"directory": true,
"children": [
{
"name": "Range/3/100.Stroperige_Rakker_pet_50cl.psd",
"human_name": "100.Stroperige Rakker pet 50cl",
"image_library_text_variable_replacements": {},
"image_preview": "/image_libraries/tenant/Range/3/100.Stroperige_Rakker_pet_50cl.png"
},
{
"name": "Range/3/100.Machtige_Reus_pet_50cl.psd",
"human_name": "100.Machtige Reus pet 50cl",
"image_library_text_variable_replacements": {},
"image_preview": "/image_libraries/tenant/Range/3/100.Machtige_Reus_pet_50cl.png"
}
]
},
{
"name": "4",
"directory": true,
"children": [
{
"name": "Range/4/100.Stroperige_Rakker_horeca_fles_20cl.psd",
"human_name": "100.Stroperige Rakker horeca fles 20cl",
"image_library_text_variable_replacements": {},
"image_preview": "/image_libraries/tenant/Range/4/100.Stroperige_Rakker_horeca_fles_20cl.png"
},
{
"name": "Range/4/100.Machtige_Reus_horeca_fles_20cl.psd",
"human_name": "100.Machtige Reus horeca fles 20cl",
"image_library_text_variable_replacements": {},
"image_preview": "/image_libraries/tenant/Range/4/100.Machtige_Reus_horeca_fles_20cl.png"
}
]
}
]
}
}
We weten dat er een image library genaamd Range moet zijn.
Te vinden in het image_libraries attribuut.
{
"image_libraries": {
"Range": [
{
"name": "1",
"directory": true,
"children": [
{
"name": "Range/1/100.Stroperige_Rakker_can_33cl.psd",
"human_name": "100.CC regular can 33cl",
"image_library_text_variable_replacements": {},
"image_preview": "/image_libraries/tenant/Range/1/100.Stroperige_Rakker_can_33cl.png"
},
{
"name": "Range/1/100.Machtige_Reus_can_33cl.psd",
"human_name": "100.Machtige Reus can 33cl",
"image_library_text_variable_replacements": {},
"image_preview": "/image_libraries/tenant/Range/1/100.Machtige_Reus_can_33cl.png"
}
]
}
]
}
}
De gebruiker heeft gekozen voor een productstijl met id 1 en naam:
0,33L Blik. We moeten nu door de directories van de image_library heen om de
subfolder te vinden waarin de beschikbare beelden zitten.
In dit voorbeeld mag de gebruiker dus enkel uit deze twee beelden kiezen:
Range/1/100.Stroperige_Rakker_can_33cl.psdRange/1/100.Machtige_Reus_can_33cl.psd
We verwachten als value van de input, het name (Range/1/100.Stroperige_Rakker_can_33cl.psd) attribuut van het beeld.
Let op: Het zou voor kunnen komen dat een bepaalde image_placeholder
geen beelden heeft voor de gekozen product_style.
Let op: Het filteren van de beschikbare beelden met images_show/images_hidden zou van toepassing kunnen zijn.
Uitleg Image Libraries
Image libraries zijn een boomstructuur van beschikbare bestanden voor het
vullen van image_placeholders. Ze bestaan uit mappen en beelden. Waarbij
beelden een preview en het origineel bestand hebben. Gebruikers kiezen
beelden, de editor submit de name van de beelden als value van de
input. De keuzes worden aan gebruikers gepresenteerd door de afbeeldingen
uit thumbnails te gebruiken.
{
"name": "Mapnaam",
"directory": true,
"children": [
// ...
]
}
Een map ziet er als volgt uit:
Beelden komen in twee smaken, video's en plaatjes.
Het verschil tussen een video en een plaatje zit in de extensie van het bestand
en de key van de preview; (image_preview/video_preview).
Previews zijn de thumbnails welke aan de gebruiker gepresenteerd worden, niet de beelden welke meegestuurd moeten worden bij submitten.
{
"name": "Mapnaam1/Mapnaam2/bestandsnaam.extensie",
"file_name": "bestandsnaam.extensie",
"human_name": "Bestandsnaam",
"image_library_text_variable_replacements": {
"exif_1": "Variabele 1",
"exif_2": "Variabele 2",
"exif_3": "Variabele 3"
},
"image_preview": {
"path": "/image_libraries/tenant/Mapnaam1/Mapnaam2/bestandsnaam.extensie",
"filename": "bestandsnaam.extensie"
}
}
Een beeld als plaatje ziet er als volgt uit ➡
{
"name": "Mapnaam1/Mapnaam2/bestandsnaam.extensie",
"file_name": "bestandsnaam.extensie",
"human_name": "Bestandsnaam",
"image_library_text_variable_replacements": {
"exif_1": "Variabele 1",
"exif_2": "Variabele 2",
"exif_3": "Variabele 3"
},
"video_preview": {
"path": "/image_libraries/tenant/Mapnaam1/Mapnaam2/bestandsnaam.extensie",
"filename": "bestandsnaam.extensie"
}
}
Een beeld als video ziet er als volgt uit ➡
beeld>name
De naam van een beeld of directory. Deze komen in twee smaken, directories of bestanden.
Mappen gebruik je om door te navigeren naar beelden.
Beelden worden gebruikt om de waardes van velden in placeholders te bepalen en te achterhalen waar illustraties te vinden die als preview dienen voor de gebruiker.
directory
Beantwoordt de vraag: Is dit een directory?
children
Een array met kinderen van de map, dit kunnen beelden of mappen zijn.
human_name
Leesbare naam bedoeld om te presenteren aan de gebruiker.
file_name
Bestandsnaam voor het vergelijken van de waardes uit:
image_library>image_library_text_variable_replacements
De sleutels en waarden die door keuze van dit beeld vervangen moeten worden in de placeholder.
image_preview/video_preview
De thumbnail van het plaatje/de video, welke als keuze aan de gebruiker van de editor gepresenteerd kan worden. Dit dient enkel als voorbeeld.
De value voor de input zou uit name van het beeld gehaald moeten
worden, niet hieruit.
Productcategorieën
Opvragen lijst van productcategorieën
Geeft een recursieve lijst terug van alle productcategorieën. Een productcategorie is een container en bevat een verzameling producten.
HTTP Request
GET https://menuez.nl/api/v2/product_categories
curl "https://menuez.nl/api/v2/product_categories"
-u "email:password"
Response
[
{
"id": 1,
"name": "Lorem ipsum dolor sit amet.",
"description": "Lorem ipsum dolor sit amet, consectetur adipiscing elit. Ut suscipit urna ut.",
"thumbnail_url": "https://...",
"children": [
{
"id": 3,
"name": "Lorem ipsum dolor sit amet.",
"description": "Lorem ipsum dolor sit amet, consectetur adipiscing elit. Ut suscipit urna ut.",
"thumbnail_url": "https://...",
"children": []
},
{
"id": 4,
"name": "Lorem ipsum dolor sit amet.",
"description": "Lorem ipsum dolor sit amet, consectetur adipiscing elit. Ut suscipit urna ut.",
"thumbnail_url": null,
"children": []
}
]
},
{
"id": 2,
"name": "Lorem ipsum dolor sit amet.",
"description": "Lorem ipsum dolor sit amet, consectetur adipiscing elit. Ut suscipit urna ut.",
"thumbnail_url": "https://...",
"children": []
}
]
Request parameters
Response gegevens
| Naam | Type | Omschrijving |
|---|---|---|
| id | Integer | Unieke referentie naar productformaat |
| name | String | Naam |
| shipment_type | String | Distributiemethode van het formaat. Deze method heeft invloed op de gegevens die nodig zijn bij het plaatsen van een bestelling. ([postal, email, spotta]) |
| num_in_stock | Integer | Optioneel aantal in voorraad; 'null' wanneer het geen voorraad-product betreft |
| out_of_stock_prompt | String | Tekst weer te geven bij te lage voorraad |
Opvragen lijst van producten binnen een productcategorie
Geeft een lijst terug van alle producten die in de opgegeven productcategorie zitten.
HTTP Request
GET https://menuez.nl/api/v2/product_categories/:id/products
curl "https://menuez.nl/api/v2/product_categories/1/products"
-u "email:password"
Response
Zie Opvragen lijst van producten voor details over de response
Request parameters
Geen.
Productpersonalisaties
Vraag details van personalisatie op
Geeft details van de personalisatie terug
HTTP Request
GET https://menuez.nl/api/v2/product_personalizations/:id
curl "https://menuez.nl/api/v2/products/1/product_personalizations/1"
-u "email:password"
Response
{
"id": 1,
"product_id": 1,
"edit_url": "https://...",
"preview_url": "https://..."
}
Request parameters
| Naam | Type | Omschrijving |
|---|---|---|
| callback_url | String | URL wat moet worden aangeroepen wanneer de klant klaar is met personalizeren |
| preview_product_format_id | Integer | ID van het product_formaat dat geselecteerd moet zijn tijdens het openen van de personalisatie. |
Response
| Naam | Type | Omschrijving |
|---|---|---|
| id | Integer | Unieke referentie naar productpersonalisatie |
| product_id | Integer | Unieke referentie naar product |
| edit_url | String | URL waar gebruiker naartoe gestuurd kan worden om personalisatie te muteren |
| preview_url | String/Null | URL van preview |
Genereer een voorbeeld van de data van een personalisatie
Genereer een voorbeeld van een personalisatie op basis van de aangeleverde data. Dit betreft een zelfde set data als uiteindelijk gebruikt bij het plaatsen van een order met nieuwe productpersonalisatie
HTTP Request
POST https://menuez.nl/api/v2/product_personalizations/:preview
curl "https://menuez.nl/api/v2/product_personalizations/preview"
-u "email:password"
-H "Content-Type: application/json"
POST -d "{
\"product_id\": 752,
\"preview_product_format_id\": 2,
\"text_variables\": {
\"1:1:Kop:1:text_13:Koptekst\": \"Combideal\",
\"1:2:Aanbieding:1:text_32:Regel 1\": \"Pistolet gezond\",
\"1:2:Aanbieding:2:text_32:Regel 2\": \"+ 0,5L frisdrank\",
\"1:3:Prijs:1:text_2:Prijs in Euro's\": \"4\",
\"1:3:Prijs:2:text_2:Prijs in Eurocenten\": \"50\"
},
\"image_placeholders\": {
\"BroodjeGezond_LOS.psd\": \"BroodjeGezond_LOS.psd\",
\"110.CC_zero_sugar_pet_50cl_hand.psd\": \"110.CC_zero_sugar_pet_50cl_hand.psd\",
\"CCR_CCZ.psd\": \"CCR_CCZ.psd\",
\"Logo_Placeholder.eps\": \"data:image/png;base64,XXX\",
\"Blanco_Price_balloon.psd\": \"Blanco_Price_balloon.psd\"
}
}"
HTTP Response
Wanneer alles goed is wordt een afbeelding of PDF aangeboden.
Ongeldige data
Sommige personalisatie-typen hebben verplichtingen. Wanneer relevant zal het antwoord een 422 zijn met JSON bericht failures. Dit zijn tekstuele meldingen die een gebruiker moeten helpen bepaalde aanpassingen te maken.
Denk hierbij vooral aan personalisatie-typen waar producten geselecteerd kunnen worden, zoals een bierkaart.
Het is mogelijk de meldingen in een andere taal op te vragen. Voeg daarvoor de header X-Locale toe.
Ongeldige data
{
"failures": [
"You must select at least 3 beers"
]
}
{
"failures": [
"U dient minimaal 3 bieren te selecteren"
]
}
Request parameters
| Naam | Type | Omschrijving |
|---|---|---|
| product_id | Integer | Het product die u wilt gebruiken |
| preview_product_format_id | Integer | Optioneel het product formaat id waarin je een preview wilt ontvangen |
| text_variables | Object | Lijst van "text_variable_name": "text_variable_value" |
| image_placeholders | Object | Lijst van "image_placeholder_name": "image_placeholder_value". In geval van een upload moet dit een base64 geëncodeerd uri zijn. |
Producten
Opvragen lijst van producten
Geeft een lijst terug van alle producten (gepagineerd)
HTTP Request
GET https://menuez.nl/api/v2/products/
curl "https://menuez.nl/api/v2/products/"
-u "email:password"
response
{
"id": 1,
"product_category_id": 1,
"name": "Lorem ipsum dolor sit amet.",
"description": "Lorem ipsum dolor sit amet.",
"thumbnail_url": "https://example.com",
"video_thumbnail_url": "https://example.com",
"editor_type": "generic",
"customizable": false,
"text_variables": {
"1:1:Keuze 1 | Menu titel text:Naam": "Lorem ipsum dolor sit amet.",
"1:1:Keuze 1 | Menu prijs:2:text_7:Prijs": "€4,50",
"1:2:Keuze 2 | Super deal menu prijs:2:text_7:Prijs": "€5,00",
"1:3:Keuze 3 | Beste deal prijs:2:text_7:Prijs": "€5,25"
},
"image_placeholders": [
"product_original_default.psd",
"Logo_Placeholder.eps"
],
"product_product_formats": [
{
"id": 2,
"product_id": 1,
"product_format_id": 5
}
],
"product_formats": [
{
"id": 5,
"name": "Lorem ipsum dolor sit amet.",
"shipment_type": "Lorem ipsum dolor sit amet.",
"stock_keeping_unit_id": 1,
"num_in_stock": 5000,
"out_of_stock_prompt": ""
}
]
}
Request parameters
geen.
Maak nieuw product op
HTTP Request
POST https://menuez.nl/api/v2/products/:product_id/product_personalizations
curl "https://menuez.nl/api/v2/products/1/product_personalizations"
-u "email:password"
-H "Content-Type: application/json"
POST -d '{"callback_url": "https://myapp.com"}'
Response
{
"id": 1,
"product_id": 1,
"edit_url": "https://...",
"preview_url": "https://..."
}
Request parameters
| Naam | Type | Omschrijving |
|---|---|---|
| callback_url | String | URL waarna de gebruiker teruggestuurd moet worden na muteren van de personalisatie |
Optioneel kan een deel van de personalisatie direct meegestuurd worden:
| Naam | Type | Omschrijving |
|---|---|---|
| logo | File | Inhoud van logo in Base64-encoding (.eps, .ai of .pdf) |
| company_name | String | Bedrijfsnaam |
| email_address | String | E-mailadres |
| phone_number | String | Telefoonnummer |
| mobile_phone_number | String | Mobiel telefoonnummer |
| address_street | String | Straatnaam |
| address_street_number | String | Huisnummer |
| address_street_number_suffix | String | Huisnummertoevoeging |
| address_zip_code | String | Postcode |
| address_city | String | Plaats |
| address_country | String | Land |
| website | String | Websiteadres |
| facebook_url | String | Adres van Facebook-profiel |
Response
Geeft details van de personatie terug:
| Naam | Type | Omschrijving |
|---|---|---|
| id | Integer | Unieke referentie naar productpersonalisatie |
| product_id | Integer | Unieke referentie naar product |
| edit_url | String | URL waar gebruiker naartoe gestuurd kan worden om personalisatie te muteren |
| preview_url | String/Null | URL van preview |
Orders
Opvragen lijst van orders
Geeft een lijst terug van alle orders (gepagineerd)
HTTP Request
GET https://menuez.nl/api/v2/orders
curl "https://menuez.nl/api/v2/orders"
-u "email:password"
Response
Request parameters
| Naam | Type | Omschrijving |
|---|---|---|
| delivered_since | Datum | Filter orders met leverdatum vanaf zoals '2019-05-01' |
| crm_id | String | Filter orders met klant CRM ID |
Prijs berekenen
POST https://menuez.nl/api/v2/orders/price
curl "https://menuez.nl/api/v2/orders/price"
-u "email:password"
-H "Content-Type: application/json"
POST -d '{
"shipment": {
"name": "Lene van Rijsthout",
"company_name": "Lico Innovations",
"address_street": "Geldropseweg",
"address_street_number": "8",
"address_street_number_suffix": "a",
"address_zip_code": "5731 SG",
"address_city": "Mierlo",
"address_country": "NL",
"email_address": "info@lico.nl"
},
"products": [
{
"product_id": 1,
"product_format_id": 1,
"product_personalization_id": 1,
"quantity": 1}
]}'
Request parameters
| Naam | Type | Omschrijving |
|---|---|---|
| shipment | Array | Gegevens over aflevering |
| products | Array | Lijst van te bestellen producten |
Shipment
| Naam | Type | Omschrijving |
|---|---|---|
| company_name | String | Bedrijfsnaam |
| name | String | Contactpersoon |
| address_street | String | Straatnaam |
| address_street_number | String | Huisnummer |
| address_street_number_suffix | String | Huisnummertoevoeging |
| address_zip_code | String | Postcode |
| address_city | String | Plaats |
| address_country | String | Land |
| email_address | String | E-mailadres |
| spotta_week | String | Leverweek Spotta |
| spotta_zip_codes | Array | Postcodes van verspreidgebied |
Let op: Afhankelijk van shipment_type van bestelde producten zijn bepaalde velden verplicht.
Product
| Naam | Type | Omschrijving |
|---|---|---|
| product_id | Integer | Unieke referentie naar |
| product_format_id | Integer | Unieke referentie naar productformaat |
| product_personalisation_id | Integer | Unieke referentie naar productpersonalisatie |
| quantity | Integer | Hoeveelheid van dit product |
Response
| Naam | Type | Omschrijving |
|---|---|---|
| price | Decimal | Prijs excl. BTW |
| product_prices | Array | Lijst van de producten met de prijs per product |
| product_id | Integer | Unieke referentie naar |
| product_format_id | Integer | Unieke referentie naar productformaat |
| quantity | Integer | Hoeveelheid van dit product |
| price | Decimal | Prijs van dit product (totaal van stuksprijs maal aantal) |
| shipment_type | String | Distributiemethode van de zending ([postal, email, spotta]) |
| product_base_prices | Decimal | Totaal van de handlingskosten |
| additional_costs | Decimal | Totaal van additionele kosten die niet onder de overige noemers vallen |
| shipping_costs | Decimal | Totaal van de verzendkosten |
| fixed_range_surtaxes | Decimal | Totaal van extra toeslagen |
| voucher_value | Decimal | Totaal van de eventuele kortingen gegeven via vouchers |
| budget_value | Decimal | Totaal van de eventuele kortingen gegeven via budgetten |
Response
{
"price": "119.5",
"product_prices": [
{
"product_id": 1,
"product_format_id": 1,
"quantity": 5,
"price": "100.0",
"shipment_type": "postal"
}
],
"product_base_prices": "11.0",
"additional_costs": 0,
"shipping_costs": 8.5,
"fixed_range_surtaxes": [],
"voucher_value": "0.0",
"budget_value": 0
}
Plaats order met bestaande productpersonalisatie
HTTP Request
POST https://menuez.nl/api/v2/orders
curl "https://menuez.nl/api/v2/orders"
-u "email:password"
-H "Content-Type: application/json"
POST -d '{
"crm_id": "1234",
"contact_name": "Henk Huppelschoten",
"contact_email_address": "test@example.com",
"contact_telephone_number": "06-12345678",
"customer_share": "0",
"representative": {
"email": "vertegenwoordiger@example.com",
"name": "Vertegenwoordiger",
"language": "nl"
},
"shipment": {
"name": "Lene van Rijsthout",
"company_name": "Lico Innovations",
"address_street": "Geldropseweg",
"address_street_number": "8",
"address_street_number_suffix": "a",
"address_zip_code": "5731 SG",
"address_city": "Mierlo",
"address_country": "NL",
"email_address": "info@lico.nl"
},
"products": [
{
"product_id": 1,
"product_format_id": 1,
"product_personalization_id": 1,
"quantity": 1
}
]}'
Order
| Naam | Type | Omschrijving |
|---|---|---|
| crm_id | String | Unieke referentie in uw systeem. |
| contact_name | String | Naam van contactpersoon |
| contact_email_address | String | Emailadres van contactpersoon |
| contact_telephone_number | String | Telefoonnummer van contactpersoon |
| customer_share | String | Deel van de prijs dat door de klant betaald wordt. (optioneel) (null, "", '50.0') |
Request parameters
| Naam | Type | Omschrijving |
|---|---|---|
| representative | Object | Gegevens van vertegenwoordiger (optioneel) |
| shipment | Object | Gegevens over aflevering |
| products | Array | Lijst van te bestellen producten |
| after_payment_callback_url | String | Optioneel URL waar een gebruiker naartoe gestuurd wordt na het uitvoeren van een betaling (zie Betalen van een order) |
Representative
Wanneer meegegeven is het order gemaakt door de vertegenwoordiger. Anders gaan we er vanuit dat het door de klant zelf
aangemaakt op basis van de attribuuten name en email_adress van shipment.
| Naam | Type | Omschrijving |
|---|---|---|
| name | String | Naam |
| String | E-mailadres | |
| language | String | Taal (zoals 'nl' of 'fr') |
Shipment
| Naam | Type | Omschrijving |
|---|---|---|
| company_name | String | Bedrijfsnaam |
| name | String | Contactpersoon 1 |
| address_street | String | Straatnaam |
| address_street_number | String | Huisnummer |
| address_street_number_suffix | String | Huisnummertoevoeging |
| address_zip_code | String | Postcode |
| address_city | String | Plaats |
| address_country | String | Land |
| email_address | String | E-mailadres 1 |
| spotta_week | String | Leverweek Spotta |
| spotta_zip_codes | Array | Postcodes van verspreidgebied |
Let op: Afhankelijk van shipment_type van bestelde producten zijn bepaalde velden verplicht.
Product
| Naam | Type | Omschrijving |
|---|---|---|
| product_id | Integer | Unieke referentie naar |
| product_format_id | Integer | Unieke referentie naar productformaat |
| product_personalisation_id | Integer | Unieke referentie naar productpersonalisatie |
Customer share
Dit bepaalt wat de klant betaalt. Het verschil tussen "de balans van de order" en het "door de klant te betalen bedrag" wordt in den budgetmutatie verrekend.
Plaats order met nieuwe productpersonalisatie
HTTP Request
POST https://menuez.nl/api/v2/orders
curl "https://menuez.nl/api/v2/orders"
-u "email:password"
-H "Content-Type: application/json"
POST -d '{
"crm_id": "1234",
"contact_name": "Henk Huppelschoten",
"contact_email_address": "test@example.com",
"contact_telephone_number": "06-12345678",
"customer_share": "50.50",
"representative": {
"email": "vertegenwoordiger@example.com",
"name": "Vertegenwoordiger",
"language": "nl"
},
"shipment": {
"name": "Lene van Rijsthout",
"company_name": "Lico Innovations",
"address_street": "Geldropseweg",
"address_street_number": "8",
"address_street_number_suffix": "a",
"address_zip_code": "5731 SG",
"address_city": "Mierlo",
"address_country": "NL",
"email_address": "info@lico.nl"
},
"products": [
{
"product_id": 1,
"product_format_id": 7,
"quantity": 13,
"product_personalization": {
"text_variables": {
"1:1:Product:1:text_24:Regel 1": "Titel",
"1:1:Product:2:text_24:Regel 2": "Aanbieding",
"1:2:Looptijd:1:text_48:Actieperiode": "Periode",
"1:3:NAW:1:text_40:Naam bedrijf": "Naam Bedrijf",
"1:3:NAW:6:text_35:Website": "www.bedrijf.nl"
},
"image_placeholders": {
"3DPrinter.psd": {
"file": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVR42mNk+A8AAQUBAScY42YAAAAASUVORK5CYII="
}
}
}
}
]
}'
Order
| Naam | Type | Omschrijving |
|---|---|---|
| crm_id | String | Unieke referentie in uw systeem. |
| contact_name | String | Naam van contactpersoon |
| contact_email_address | String | Emailadres van contactpersoon |
| contact_telephone_number | String | Telefoonnummer van contactpersoon |
| customer_share | String | Deel van de prijs dat door de klant betaald wordt. (optioneel) (null, "", '50.0') |
Request parameters
| Naam | Type | Omschrijving |
|---|---|---|
| representative | Object | Gegevens van vertegenwoordiger (optioneel) |
| shipment | Object | Gegevens over aflevering |
| products | Array | Lijst van te bestellen producten |
| after_payment_callback_url | String | Optioneel URL waar een gebruiker naartoe gestuurd wordt na het uitvoeren van een betaling (zie Betalen van een order) |
Representative
Wanneer meegegeven gaan we er vanuit dat de order is aangemaakt door een vertegenwoordiger met deze data. Als deze data ontbreekt gaan we er vanuit dat het door de klant zelf
aangemaakt. De gegevens van de gebruiker van de klant baseren we op de attribuuten name en email_adress van shipment.
| Naam | Type | Omschrijving |
|---|---|---|
| name | String | Naam |
| String | E-mailadres | |
| language | String | Taal (zoals 'nl' of 'fr') |
Shipment
| Naam | Type | Omschrijving |
|---|---|---|
| company_name | String | Bedrijfsnaam |
| name | String | Contactpersoon 1 |
| address_street | String | Straatnaam |
| address_street_number | String | Huisnummer |
| address_street_number_suffix | String | Huisnummertoevoeging |
| address_zip_code | String | Postcode |
| address_city | String | Plaats |
| address_country | String | Land |
| email_address | String | E-mailadres 1 |
| spotta_week | String | Leverweek Spotta |
| spotta_zip_codes | Array | Postcodes van verspreidgebied |
Let op: Afhankelijk van shipment_type van bestelde producten zijn bepaalde velden verplicht.
Product
| Naam | Type | Omschrijving |
|---|---|---|
| product_id | Integer | Unieke referentie naar |
| product_format_id | Integer | Unieke referentie naar productformaat |
| product_personalization | Object | Gegevens over productpersonalisatie |
Productpersonalization
| Naam | Type | Omschrijving |
|---|---|---|
| text_variables | Object | Lijst van "text_variable_name": "text_variable_value" |
| image_placeholders | Object | Lijst van "image_placeholder_name": { "file":"image_placeholder_value". Moet een base-64 geëncodeerd uri zijn. |
Plaats order met hetzelfde nieuwe productpersonalisatie voor meerdere producten
HTTP Request
POST https://menuez.nl/api/v2/orders
curl "https://menuez.nl/api/v2/orders"
-u "email:password"
-H "Content-Type: application/json"
POST -d '{
"crm_id": "1234",
"contact_name": "Henk Huppelschoten",
"contact_email_address": "test@example.com",
"contact_telephone_number": "06-12345678",
"customer_share": null,
"representative": {
"email": "vertegenwoordiger@example.com",
"name": "Vertegenwoordiger",
"language": "nl"
},
"shipment": {
"name": "Lene van Rijsthout",
"company_name": "Lico Innovations",
"address_street": "Geldropseweg",
"address_street_number": "8",
"address_street_number_suffix": "a",
"address_zip_code": "5731 SG",
"address_city": "Mierlo",
"address_country": "NL",
"email_address": "info@lico.nl"
},
"product_personalizations": [
{
"reference": "test",
"product_id": 1,
"text_variables": {
"1:1:Product:1:text_24:Regel 1": "Titel",
"1:1:Product:2:text_24:Regel 2": "Aanbieding",
"1:2:Looptijd:1:text_48:Actieperiode": "Periode",
"1:3:NAW:1:text_40:Naam bedrijf": "Naam Bedrijf",
"1:3:NAW:6:text_35:Website": "www.bedrijf.nl"
},
"image_placeholders": {
"3DPrinter.psd": {
"file": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVR42mNk+A8AAQUBAScY42YAAAAASUVORK5CYII="
}
}
}
],
"products": [
{
"product_id": 1,
"product_format_id": 1,
"quantity": 2,
"product_personalization_reference": "test"
},
{
"product_id": 1,
"product_format_id": 2,
"quantity": 4,
"product_personalization_reference": "test"
}
]
}'
Order
| Naam | Type | Omschrijving |
|---|---|---|
| crm_id | String | Unieke referentie in uw systeem. |
| contact_name | String | Naam van contactpersoon |
| contact_email_address | String | Emailadres van contactpersoon |
| contact_telephone_number | String | Telefoonnummer van contactpersoon |
| customer_share | String | Deel van de prijs dat door de klant betaald wordt. (optioneel) (null, "", '50.0') |
Request parameters
| Naam | Type | Omschrijving |
|---|---|---|
| representative | Object | Gegevens van vertegenwoordiger (optioneel) |
| shipment | Object | Gegevens over aflevering |
| products | Array | Lijst van te bestellen producten |
| product_personalizations | Array | Lijst van productpersonalisaties |
| after_payment_callback_url | String | Optioneel URL waar een gebruiker naartoe gestuurd wordt na het uitvoeren van een betaling (zie Betalen van een order) |
Representative
Wanneer meegegeven gaan we er vanuit dat de order is aangemaakt door een vertegenwoordiger met deze data. Als deze data ontbreekt gaan we er vanuit dat het door de klant zelf
aangemaakt. De gegevens van de gebruiker van de klant baseren we op de attribuuten name en email_adress van shipment.
| Naam | Type | Omschrijving |
|---|---|---|
| name | String | Naam |
| String | E-mailadres | |
| language | String | Taal (zoals 'nl' of 'fr') |
Shipment
| Naam | Type | Omschrijving |
|---|---|---|
| company_name | String | Bedrijfsnaam |
| name | String | Contactpersoon 1 |
| address_street | String | Straatnaam |
| address_street_number | String | Huisnummer |
| address_street_number_suffix | String | Huisnummertoevoeging |
| address_zip_code | String | Postcode |
| address_city | String | Plaats |
| address_country | String | Land |
| email_address | String | E-mailadres 1 |
| spotta_week | String | Leverweek Spotta |
| spotta_zip_codes | Array | Postcodes van verspreidgebied |
Let op: Afhankelijk van shipment_type van bestelde producten zijn bepaalde velden verplicht.
Product
| Naam | Type | Omschrijving |
|---|---|---|
| product_id | Integer | Unieke referentie naar |
| product_format_id | Integer | Unieke referentie naar productformaat |
| product_personalization_reference | String | Referentie naar de productpersonalisatie |
Productpersonalization
| Naam | Type | Omschrijving |
|---|---|---|
| product_id | Integer | Het product dat u wilt gebruiken |
| reference | Integer | Referentie naar deze productpersonalisatie (voor producten) |
| text_variables | Object | Lijst van "text_variable_name": "text_variable_value" |
| image_placeholders | Object | Lijst van "image_placeholder_name": { "file":"image_placeholder_value". Moet een base-64 geëncodeerd uri zijn. |
Plaats order en lever direct bestanden aan
HTTP Request
POST https://menuez.nl/api/v2/orders
curl "https://menuez.nl/api/v2/orders"
-u "email:password"
-H "Content-Type: application/json"
POST -d '{
"crm_id": "1234",
"contact_name": "Henk Huppelschoten",
"contact_email_address": "test@example.com",
"contact_telephone_number": "06-12345678",
"customer_share": "50.50",
"representative": {
"email": "vertegenwoordiger@example.com",
"name": "Vertegenwoordiger",
"language": "nl"
},
"shipment": {
"name": "Lene van Rijsthout",
"company_name": "Lico Innovations",
"address_street": "Geldropseweg",
"address_street_number": "8",
"address_street_number_suffix": "a",
"address_zip_code": "5731 SG",
"address_city": "Mierlo",
"address_country": "NL",
"email_address": "info@lico.nl"
},
"products": [
{
"product_id": 1,
"product_format_id": 1,
"certified_url": "https://....",
"preview_url": "https://....",
"quantity": 2
}
]
}'
Gewijzige parameters t.o.v. eerdere verzoeken:
Product
| Naam | Type | Omschrijving |
|---|---|---|
| product_id | Integer | Unieke referentie naar |
| product_format_id | Integer | Unieke referentie naar productformaat |
| certified_url | String | URL waar bestand van gedownload kan worden |
| preview_url | String | URL waar bestand van gedownload kan worden |
Betalen van een order
Wanneer relevant zal het antwoord op het aanmaken van een order informatie bevatten over een betaling in een object 'payment':
Payment
| Naam | Type | Omschrijving |
|---|---|---|
| amount | String | Bedrag te betalen |
| url | String | URL waar een gebruiker naartoe gestuurd kan worden voor het uitvoeren van de betaling |
Na het afronden van de betaling zal de gebruiker eventueel teruggestuurd kunnen worden naar een eerder ingestelde after_payment_callback_url. Gebruik eventueel Wijzig after_payment_callback_url van een order voor het instellen van een callback url na het aanmaken van de order.
Merk op: Bij het terugsturen wordt een query argument 'order_id' en 'payment_status' toegevoegd met één van volgende waarden: 'success', 'pending', 'cancelled', 'error'. Bij het opvragen van de details van een order kan de actuele balans opgevraagd worden.
BTW-nummer
curl "https://menuez.nl/api/v2/orders"
-u "email:password"
-H "Content-Type: application/json"
POST -d '{
"crm_id": "1234",
...
"customer": {
"vat_number": "NL...B01"
}}'
Bij plaatsen van een order (... met bestaande productpersonalisatie, ... met nieuwe productpersonalisatie, ... met hetzelfde nieuwe productpersonalisatie voor meerdere producten, ... en lever direct bestanden aan) is het mogelijk een BTW-nummer mee te geven.
Een BTW-nummer wordt gebruikt om de verleggingsregeling toe te passen. Merk daarbij het volgende op:
- Het BTW-nummer is alleen relevant wanneer de klant de order of een deel van de order niet uit budget kan halen en dus zelf moet betalen
- Het meegeven van het BTW-nummer is optioneel. De klant zal bij betaling gevraagd worden om het in te voeren als deze ontbreekt
- Validatie wordt uitgevoerd bij het Systeem voor de uitwisseling van BTW-informatie (VIES)
Request parameters
Customer
| Naam | Type | Omschrijving |
|---|---|---|
| vat_number | String | BTW-nummer van dde klant |
Wijzig after_payment_callback_url van een order
HTTP Request
POST https://menuez.nl/api/v2/orders/:id
curl "https://menuez.nl/api/v2/orders/1"
-u "email:password"
-H "Content-Type: application/json"
POST -d '{
"after_payment_callback_url": "https://example.com/callback?my-id=123"
}'
Request parameters
| Naam | Type | Omschrijving |
|---|---|---|
| after_payment_callback_url | String | URL waar een gebruiker naartoe gestuurd wordt na het uitvoeren van een betaling |
-
Dit veld wordt gebruikt om een gebruiker met de rol klant aan te maken. Dit is de gebruiker waar het order aan hangt. Gebruik voor een vertegenwoordiger het
representativeobject. ↩
Vraag details van order op
HTTP Request
GET https://menuez.nl/api/v2/orders/:id
curl "https://menuez.nl/api/v2/orders/1"
-u "email:password"
Response
{
"id": 1,
"state": "requested",
"price": "17.0",
"customer_share": "5.0",
"crm_id": "1234",
"contact_name": "Henk Huppelschoten",
"contact_telephone_number": "06-12345678",
"contact_email_address": "test@example.com",
"created_at": "2022-12-08T14:47:32.561+01:00",
"delivered_at": null,
"shipments": [
{
"id": 1,
"shipment_type": "postal",
"name": "Lene van Rijsthout",
"company_name": "Lico Innovations",
"address_street": "Dorpsstraat",
"address_street_number": "1",
"address_street_number_suffix": "a",
"address_zip_code": "1234 AA",
"address_city": "Stad",
"address_country": "NL",
"email_address": "info@example.com",
"spotta_week": null,
"spotta_zip_codes": null
},
{
"id": 2,
"shipment_type": "email",
"name": "Lene van Rijsthout",
"company_name": "Lico Innovations",
"address_street": null,
"address_street_number": null,
"address_street_number_suffix": null,
"address_zip_code": null,
"address_city": null,
"address_country": null,
"email_address": "info@example.com",
"spotta_week": null,
"spotta_zip_codes": null
}
],
"products": [
{
"id": 1,
"state": "delivered",
"shipment_type": "postal",
"product_id": 1,
"product_name": "Lorem ipsum dolor sit amet.",
"product_format_id": 1,
"product_format_name": "Lorem ipsum dolor sit amet.",
"product_personalization_id": 1
},
{
"id": 2,
"state": "delivered",
"shipment_type": "email",
"product_id": 1,
"product_name": "Lorem ipsum dolor sit amet.",
"product_format_id": 4,
"product_format_name": "Lorem ipsum dolor sit amet.",
"product_personalization_id": 1
},
{
"id": 3,
"state": "delivered",
"shipment_type": "email",
"product_id": 2,
"product_name": "Lorem ipsum dolor sit amet.",
"product_format_id": 4,
"product_format_name": "Lorem ipsum dolor sit amet.",
"product_personalization_id": null
}
],
"product_shipments": [
{
"id": 1,
"state": "delivered",
"order_shipment_id": 1,
"order_product_id": 1,
"amount": 25,
"shipment_method": "ups",
"tracking_url": "https://www.ups.com/mobile/track?trackingNumber=1Z9999999999999999"
},
{
"id": 2,
"state": "delivered",
"order_shipment_id": 2,
"order_product_id": 2,
"amount": 1
},
{
"id": 3,
"state": "delivered",
"order_shipment_id": 2,
"order_product_id": 3,
"amount": 1
}
],
"budgets": [
{
"id": 1,
"name": "Budgetnaam",
"number": "12345",
"value": "99.95"
}
],
"invoices": [
{
"year": 2024,
"number": "NL00001",
"date": "2024-04-16",
"sub_total": "0.0",
"vat_value": "0.0",
"total": "0.0",
"company_name": "Lico Innovations",
"crm_id": "1234",
"address_street": "Dorpsstraat",
"address_street_number": "1",
"address_street_number_suffix": "a",
"address_zip_code": "1234 AA",
"address_city": "Stad",
"address_country": "NL",
"iban": null,
"iban_account_holder": null,
"vat_number": "NL1234.56.789.B01"
}
],
"customer": {
"vat_number": "NL1234.56.789.B01"
},
"payment": {
"amount": "15.0",
"url": "https://...."
}
}
Response
| Naam | Type | Omschrijving |
|---|---|---|
| id | id | Unieke referentie naar order |
| crm_id | String | Unieke referentie in uw systeem. |
| status | String | Actuele status |
| price | String | Tekstuele representatie van de prijs van het order |
| customer_share | String | Deel van de prijs dat door de klant betaald wordt. (optioneel) (null, "", '50.0') |
| shipments | Array | Lijst van zendingen |
| products | Array | Lijst van producten |
| product_shipments | Array | Lijst van product-zendingen |
| budgets | Array | Lijst van toegepaste budgetten |
| contact_name | String | Naam van contactpersoon |
| contact_telephone_number | String | Telefoonnummer van contactpersoon |
| contact_email_address | String | Email adres van contactpersoon |
| created_at | Tijd | Moment waarop de order is aangemaakt |
| delivered_at | Tijd | Moment waarop alle individuele product_shipments als geleverd zijn gemarkeerd |
Zendingen
| Naam | Type | Omschrijving |
|---|---|---|
| id | id | Unieke referentie naar zending |
| status | String | Actuele status |
| shipment_type | String | Distributiemethode van de zending ([postal, email, spotta]) |
| name | String | Naam van ontvanger |
| address_street | String | Straatnaam |
| address_street_number | String | Huisnummer |
| address_street_number_suffix | String | Huisnummertoevoeging |
| address_zip_code | String | Postcode |
| address_city | String | Plaats |
| address_country | String | Land |
| email_address | String | E-mailadres |
| spotta_week | String | Leverweek Spotta |
| spotta_zip_codes | Array | Postcodes van verspreidgebied |
Producten
| Naam | Type | Omschrijving |
|---|---|---|
| id | id | Unieke referentie naar product binnen deze order |
| status | String | Actuele status |
| shipment_type | String | Distributiemethode van de zending ([postal, email, spotta]) |
| product_id | Integer | Unieke referentie naar product |
| product_name | String | Naam van product |
| product_format_id | Integer | Unieke referentie naar productformaat |
| product_format_name | String | Naam van productformaat |
| product_personalization_id | Integer | Unieke referentie naar personalisatie |
Product-zendingen
| Naam | Type | Omschrijving |
|---|---|---|
| id | id | Unieke referentie naar product-zending |
| status | String | Actuele status |
| order_shipment_id | String | Unieke referentie naar zending |
| order_product_id | String | Unieke referentie naar product binnen deze order |
| amount | Integer | Aantal |
| shipment_method | String | Zendingmethode ([postnl, ups, b2c]) |
| tracking_url | String | URL om de zending te volgen |
Budgetten
| Naam | Type | Omschrijving |
|---|---|---|
| id | String | Unieke referentie naar het budget |
| name | String | Naam van het budget |
| number | String | Nummer van het budget |
| value | String | Gebruikt bedrag |
Facturen
| Naam | Type | Omschrijving |
|---|---|---|
| year | Integer | Jaar |
| number | String | Factuurnummer |
| date | Date | Factuurdatum |
| sub_total | Decimal | Totaal exclusief BTW |
| vat_value | Decimal | BTW |
| total | Decimal | Totaal inclusief BTW |
| crm_id | String | Unieke referentie in uw systeem |
| company_name | String | Bedrijfsnaam |
| address_street | String | Straatnaam |
| address_street_number | String | Huisnummer |
| address_street_number_suffix | String | Huisnummertoevoeging |
| address_zip_code | String | Postcode |
| address_city | String | Plaats |
| address_country | String | Land |
| iban | String | Rekeningnummer |
| iban_account_holder | String | Rekeninghouder |
| vat_number | String | BTW-nummer (alleen als aanwezig) |
Klant-details (alleen als BTW-nummer aanwezig is)
| Naam | Type | Omschrijving |
|---|---|---|
| vat_number | String | BTW-nummer (alleen als aanwezig) |
Betaling
| Naam | Type | Omschrijving |
|---|---|---|
| amount | String | Bedrag te betalen |
| url | String | URL waar een gebruiker naartoe gestuurd kan worden voor het uitvoeren van de betaling |
Zie ook: Betalen van een order.
Request parameters
Geen.
Spotta
Opvragen beschikbare weken
Geeft een verzameling weeknummers terug die beschikbaar zijn voor Spotta verspreiding. Per weeknummer wordt tevens de eerste dag van die week meegegeven.
HTTP Request
GET https://menuez.nl/api/v2/spotta/available_weeks
curl "https://menuez.nl/api/v2/spotta/available_weeks"
-u "email:password"
Response
{
"available_weeks": [
{
"name": "Week 36",
"value": "04-09-2018"
},
{
"name": "Week 37",
"value": "11-09-2018"
},
{
"name": "Week 38",
"value": "18-09-2018"
},
{
"name": "Week 39",
"value": "25-09-2018"
},
{
"name": "Week 40",
"value": "02-10-2018"
},
{
"name": "Week 41",
"value": "09-10-2018"
},
{
"name": "Week 42",
"value": "16-10-2018"
},
{
"name": "Week 43",
"value": "23-10-2018"
},
{
"name": "Week 44",
"value": "30-10-2018"
},
{
"name": "Week 45",
"value": "06-11-2018"
}
]
}
Request parameters
Geen.
Response gegevens
| Naam | Type | Omschrijving |
|---|---|---|
| name | String | Weeknummer in tekst |
| value | Date | Eerste dag van deze week |
Opvragen postcodereeksen
Geeft een verzameling postcodes terug die in de buurt van de opgegeven postcode liggen:
- binnen 0 tot 5 minuten van de opgegeven postcode
- binnen 5 tot 10 minuten van de opgegeven postcode
- binnen 10 tot 15 minuten van de opgegeven postcode
Tevens wordt per postcode het aantal adressen, waar Spotta flyers bezorgd kunnen worden, weergegeven.
HTTP Request
GET https://menuez.nl/api/v2/spotta/:zip_code/ranges
curl "https://menuez.nl/api/v2/spotta/5731/ranges"
-u "email:password"
Response
{
"0-5": [
{
"zip_code": 5731,
"amount": 3292
}
],
"5-10": [
{
"zip_code": 5666,
"amount": 1277
},
{
"zip_code": 5667,
"amount": 1385
},
{
"zip_code": 5706,
"amount": 4539
},
{
"zip_code": 5707,
"amount": 3314
},
{
"zip_code": 5708,
"amount": 3173
},
{
"zip_code": 5715,
"amount": 525
}
],
"10-15": [
{
"zip_code": 5641,
"amount": 2381
},
{
"zip_code": 5661,
"amount": 356
},
{
"zip_code": 5662,
"amount": 913
},
{
"zip_code": 5663,
"amount": 1883
},
{
"zip_code": 5664,
"amount": 1732
},
{
"zip_code": 5665,
"amount": 1840
},
{
"zip_code": 5672,
"amount": 2431
},
{
"zip_code": 5701,
"amount": 5328
},
{
"zip_code": 5705,
"amount": 525
}
]
}
Request parameters
Geen.
Response gegevens
| Naam | Type | Omschrijving |
|---|---|---|
| 0-5 | Array | Lijst van postcodes die binnen 0 tot 5 minuten van de opgegeven postcode liggen |
| 5-10 | Array | Lijst van postcodes die binnen 5 tot 10 minuten van de opgegeven postcode liggen |
| 10-15 | Array | Lijst van postcodes die binnen 0 tot 5 minuten van de opgegeven postcode liggen |
| zip_code | Integer | Postcode |
| amount | Integer | Aantal adressen, waar Spotta flyers bezorgd kunnen worden, weergegeven. |
Stock Keeping Units
Opvragen van Stock Keeping Units
Geeft een gepagineerd overzicht van alle stock keeping units.
HTTP Request
GET https://menuez.nl/api/v2/stock_keeping_units
curl "https://menuez.nl/api/v2/stock_keeping_units" \
-u "email:password"
Response
[
{
"id": 119,
"sku": "Your Fancy Product",
"archived": false,
"allow_pre_order": false,
"out_of_stock_prompt": "",
"gross_num_in_stock": 5,
"num_in_stock": 5,
"num_reserved": 0,
"created_at": "2018-05-28T15:45:54.065+02:00",
"updated_at": "2018-05-28T15:45:54.065+02:00"
},
{
"id": 80,
"sku": "Your Fancy Product 2",
"archived": false,
"allow_pre_order": false,
"out_of_stock_prompt": "",
"gross_num_in_stock": 0,
"num_in_stock": 0,
"num_reserved": 0,
"created_at": "2016-02-11T17:25:38.308+01:00",
"updated_at": "2016-02-11T17:25:38.308+01:00"
},
...
]
Request Parameters
Geen.
Response gegevens
Lijst van stock keeping units. Voor meer info over de attributen van een stock keeping unit zie Opvragen van Stock Keeping Unit
Opvragen van Stock Keeping Unit
Opvragen van een stock_keeping_unit.
HTTP Request
GET https://menuez.nl/api/v2/stock_keeping_units/:id
curl "https://menuez.nl/api/v2/stock_keeping_units/1" \
-u "email:password"
Response
{
"id": 119,
"sku": "Your Fancy Product",
"archived": false,
"allow_pre_order": false,
"out_of_stock_prompt": "",
"gross_num_in_stock": 5,
"num_in_stock": 5,
"num_reserved": 0,
"created_at": "2018-05-28T15:45:54.065+02:00",
"updated_at": "2018-05-28T15:45:54.065+02:00"
}
Request parameters
Geen.
Response gegevens
| Naam | Type | Omschrijving |
|---|---|---|
| id | Integer | Id van het stock keeping unit |
| sku | String | Naam van het stock keeping unit |
| archived | Boolean | Of de SKU gearchiveerd is of niet. |
| allow_pre_order | Boolean | Of de klant het product vooruit kan bestellen. |
| out_of_stock_prompt | String | Out of stock Prompt |
| gross_num_in_stock | Integer | Het totaal aantal beschikbaar. |
| num_in_stock | Integer | Het totaal in voorraad zonder daarbij rekening te houden met reserveringen. |
| num_reserved | Integer | Het totaal aan gereserveerde voorraad. |
| created_at | DateTime | Wanneer het stock_keeping_unit aangemaakt is. |
| updated_at | DateTime | Wanneer het stock_keeping_unit voor het laatst geüpdate is. |
Aanpassen van een Stock Keeping Unit
Het out_of_stock_prompt en allow_pre_order van een stock_keeping_unit kan bewerkt worden.
HTTP Request
POST https://menuez.nl/api/v2/stock_keeping_units/:id
curl -X POST "https://menuez.nl/api/v2/stock_keeping_units/1" \
-u "email:password" \
--data-urlencode 'out_of_stock_prompt=We will have more stock in 2 weeks.' \
--data-urlencode 'allow_pre_order=true'
Response
{
"id": 1,
"sku": "Your Awesome Product SKU",
"archived": false,
"allow_pre_order": true,
"out_of_stock_prompt": "We will have more stock in 2 weeks.",
"gross_num_in_stock": 1015,
"num_in_stock": 970,
"num_reserved": -45,
"created_at": "2017-05-18T09:10:15.515+02:00",
"updated_at": "2023-05-23T14:31:18.428+02:00"
}
Request parameters
| Naam | Type | Omschrijving |
|---|---|---|
| allow_pre_order | Boolean | Sta je gebruikers toe dit product te bestellen als de voorraad niet toerijkend is. |
| out_of_stock_prompt | String | Out of stock Prompt |
Response gegevens
Het aangepaste stock_keeping_unit. Gelijk aan Opvragen van Stock Keeping Unit response gegevens.
Stock Mutations van Stock keeping Unit
Geeft een gepagineerd overzicht van alle stock_mutations van een stock_keeping_unit
HTTP Request
GET https://menuez.nl/api/v2/stock_keeping_units/:id/stock_mutations/
curl "https://menuez.nl/api/v2/stock_keeping_units/1/stock_mutations/" \
-u "email:password"
Response
[
{
"id": 619,
"order_product": "CC11518P",
"amount": -1,
"reserved": true,
"created_at": "2016-04-01T11:52:04.041+02:00"
},
{
"id": 3,
"order_product": null,
"amount": 500,
"reserved": false,
"created_at": "2015-06-26T16:07:48.325+02:00"
},
...
]
Request Parameters
Geen.
Response gegevens
Lijst van Stock Mutations behorend bij Stock keeping Unit. Voor meer info over de attributen van een stock mutation zie: Opvragen van Stock Mutation
Opvragen van Stock Mutation
Opvragen van een stock_mutation behorend bij stock_keeping_unit.
HTTP Request
GET https://menuez.nl/api/v2/stock_keeping_units/:id/stock_mutations/:id
curl "https://menuez.nl/api/v2/stock_keeping_units/1/stock_mutations/1" \
-u "email:password"
Response
{
"id": 1,
"order_product": "XX00010P",
"amount": 1000,
"reserved": false,
"created_at": "2023-05-22T16:33:57.632+02:00"
}
Request Parameters
Geen.
Response Gegevens
| Naam | Type | Omschrijving |
|---|---|---|
| id | Integer | Het Id van de stock_mutation |
| order_product | String | Unieke referentie naar order_product. |
| amount | Integer | impact die deze mutatie heeft op de amount stock van het stock_keeping_unit. Dit mag negatief zijn. |
| reserved | Boolean | Betreft het een gereserveerde aanpassing? |
| created_at | DateTime | Datum en tijd waarop stock_mutation aangemaakt is. |
Aanmaken van een Stock Mutation
Een stock mutation kan aangemaakt worden via dit endpoint.
HTTP Request
POST https://menuez.nl/api/v2/stock_keeping_units/1/stock_mutations/
curl -X POST "https://menuez.nl/api/v2/stock_keeping_units/1/stock_mutations/" \
-u "email:password" \
-d 'stock_keeping_unit_id=1&amount=1000&reserved=false'
Response
{
"id": 1,
"order_product": null,
"amount": 1000,
"reserved": false,
"created_at": "2023-05-23T15:44:08.704+02:00"
}
Request parameters
| Naam | Type | Omschrijving |
|---|---|---|
| amount | Integer | impact die deze mutatie heeft op de amount stock van het stock_keeping_unit. Dit mag negatief zijn. |
Response gegevens
Het aangemaakte stock mutation. Voor meer info over de attributen zie: Opvragen van Stock Mutation
Out of Stock Prompt
Een tekst die gebruikt wordt om een deel van een notificatie te vervangen. Een notificatie die aan de gebruiker
gepresenteerd wordt wanneer de voorraad laag is. De waarde van dit attribuut wordt gebruikt om %{prompt}
te vervangen in de notificatie:
There is not enough in stock for %{product} - %{product_format}. The current stock holds %{available}, but you requested %{requested}. %{prompt}
Webhooks
Het is mogelijk een webhook te registreren om bij bepaalde acties een signaal vanuit de applicatie te ontvangen.
Opvragen beschikbare gebeurtenissen
Geeft een overzicht van beschikbare gebeurtenissen waarop een webhook zou kunnen signaleren.
HTTP Request
GET https://menuez.nl/api/v2/webhooks/events
curl "https://menuez.nl/api/v2/webhooks/events" \
-u "email:password"
Response
{
"events": {
"orders.create": {
"description": "a new order has been created",
"example_payload": {
"reference": "AA00001"
}
},
"orders.state_change": {
"description": "the state of this order has changed",
"example_payload": {
"reference": "AA00001",
"new_state": "pending_quality_control"
}
}
...
}
}
Request parameters
Geen.
Response gegevens
| Naam | Type | Omschrijving |
|---|---|---|
| events | Object | Overzicht van gebeurtenissen (key) met omschrijving en payload (value) |
Opvragen huidige webhooks
Geeft een overzicht van geregistreerde webhooks terug.
HTTP Request
GET https://menuez.nl/api/v2/webhooks
curl "https://menuez.nl/api/v2/webhooks" \
-u "email:password"
Response
[
{
"uri": "https://example.com/webhook",
"events": [
"orders.state_change"
],
"failures": []
}
]
Request parameters
Geen.
Response gegevens
| Naam | Type | Omschrijving |
|---|---|---|
| uri | String | Geregistreerde uri t.b.v. signalering |
| events | Array | Overzicht van gebeurtenissen |
| failures | Array | Een overzicht met extra informatie van alle momenten, in de afgelopen 100 dagen, waarop het aanroepen van de geregistreerde webhook niet gelukt is door een onverwacht antwoord. |
| failures.timestamp | Datetime | Moment waarop aanroep is mislukt |
| failures.code | Integer | Ontvangen HTTP response code |
| failures.body | String | Ontvangen bericht |
Registreer nieuwe webhook
Registreer een nieuwe webhook.
HTTP Request
POST https://menuez.nl/api/v2/webhooks
curl "https://menuez.nl/api/v2/webhooks" \
-u "email:password" \
-H "Content-Type: application/json" \
-X POST \
-d '{"uri": "https://example.com/webhook", "events": ["orders.state_change"]}'
Response
{
"uri": "https://example.com/webhook",
"events": [
"orders.state_change"
],
"failures": []
}
Request parameters
| Naam | Type | Omschrijving |
|---|---|---|
| uri | String | Uri t.b.v. signalering |
| events | Array | Gebeurtenissen waarop signalering plaats moet vinden |
Response gegevens
Geregistreerde webhook; zie Opvragen huidige webhooks
Wijzig bestaande webhook
Wijzig een bestaande webhook simpelweg door het volgen van de actie Registreer nieuwe webhook. De bestaande webhook zal dan worden overschreven.
Verwijder bestaande webhook
Verwijder een bestaande webhook.
HTTP Request
DELETE https://menuez.nl/api/v2/webhooks
curl "https://menuez.nl/api/v2/webhooks" \
-u "email:password" \
-H "Content-Type: application/json" \
-X DELETE \
-d '{"uri": "https://example.com/webhook"}'
Response
{
"uri": "https://example.com/webhook",
"events": [
"orders.state_change"
],
"failures": []
}
Request parameters
| Naam | Type | Omschrijving |
|---|---|---|
| uri | String | Uri t.b.v. signalering |
Response gegevens
Verwijderde webhook; zie Opvragen huidige webhooks. Optioneel komt hier een 404 uit terug als er geen webhook gevonden kan worden met het gegeven URI.