Bij het indienen van bestellingen bij GelatoConnect via de API heb je twee opties om producten te specificeren: het gebruik van Product UID's of het gebruik van Klantproducten. Deze gids legt beide benaderingen uit, hun voordelen, en wanneer je elk van beide kunt gebruiken.
Aanpak voor product-UID
De Product UID-methode houdt in dat je unieke productidentificaties (UID's) gebruikt om producten in je bestellingen aan te duiden.
Hoe het werkt
Bij het gebruik van Product UIDs, neem je de productUid parameter op in je orderitem:
{ \"itemReferenceId\": \"ITEM-001\", \"productUid\": \"flat_product_pf_a4_pt_200-g/m²-ongecoat_cl_4-0_ct_none_prt_none_sft_none_set_none_hor\", "aantal": 1, "bestanden": [ { \"type\": \"default\", "url": "https://example.com/files/printfile.pdf" } ]}Structuur van product-UID
Een product-UID is een gestructureerde reeks die producteigenschappen bevat. Bijvoorbeeld, in flat_product_pf_a4_pt_200-gsm-uncoated_cl_4-0_ct_none_prt_none_sft_none_set_none_hor:
flat_product: Producttypepf_a4: Papierformaat (A4-formaat)pt_200-gsm-uncoated: Papiersoort (200 g/m² ongecoat papier)cl_4-0: Kleurenconfiguratie (4-kleurenproces aan de voorkant, geen kleuren aan de achterkant)ct_none: Snijden (geen)prt_none: Speciale printfuncties (geen)sft_none: Oppervlaktebehandelingen (geen)set_none: Speciale effecten (geen)hor: Oriëntatie (horizontaal)
Aanpak voor klantproducten
De Customer Products-aanpak betekent dat je gepersonaliseerde productdefinities maakt in GelatoConnect en deze in je bestellingen gebruikt door naam en variant te vermelden.
Hoe het werkt
Eerst stel je Klantproducten in GelatoConnect in, waarbij je productnamen en hun variantopties definieert. Vervolgens verwijs je bij het plaatsen van bestellingen naar deze producten met behulp van de productName en productVariant parameters:
{ "itemReferenceId": "ITEM-001", \"productName\": \"Visitekaartje\", \"productVariant\": { \"Formaat\": \"Standaard\", \"Papier\": \"Premium Mat\", "Kleur": "Full color aan beide kanten" }, "quantity": 100, \"files\": [ { \"type\": \"voorkant\", \"url\": \"https://example.com/files/front.pdf\" }, { \"type\": \"back\", "url": "https://example.com/files/back.pdf" } ]}Klantproducten instellen
Voordat je klantproducten in je API-bestellingen gebruikt, moet je ze eerst instellen in GelatoConnect:
Ga naar het gedeelte Producten in GelatoConnect
Maak klantproducten met specifieke namen en varianten
Koppel deze klantproducten aan de productspecificaties van Gelato
Wanneer kies je voor welke aanpak
Gebruik product-UID's wanneer:
Je bent net begonnen met GelatoConnect
Je hebt maar een paar vaste producten
Je wilt snel implementeren zonder extra instellingen
Je bent bezig met een proefversie of een testopzet
Gebruik klantproducten wanneer:
Je hebt een grote productcatalogus
Je wilt makkelijkere productnamen in je code gebruiken
Je productnamen wijken af van de naamgevingsregels van Gelato.
Productconfiguraties kunnen in de loop van de tijd veranderen
Implementatievoorbeelden
Voorbeeld van product-UID
curl --location 'https://api.partner-connect.io/api/{partner-prefix}/order' \--header 'Content-Type: application/json' \--header 'X-API-KEY: jouw-sleutel:jouw-geheim' \--data '{" "orderReferenceId": "ORDER-123", "orderType": "bestelling", \"currency\": \"USD\", \"shippingAddress\": { "country": "VS", "firstName": "John", "lastName": "Doe", "addressLine1": "123 Main St", \"city\": \"New York\", \"postCode\": \"10001\", \"state\": \"NY\", "email": "[email protected]", "phone": "123-456-7890" }, \"items\": [ { "itemReferenceId": "ITEM-001", "productUid": "flat_product_pf_a4_pt_200-g/m²-ongecoat_cl_4-0_ct_none_prt_none_sft_none_set_none_hor", "aantal": 1, "bestanden": [ { "type": "standaard", \"url\": \"https://example.com/files/printfile.pdf\" } ] } ]}'"Voorbeeld van klantproducten
curl --location 'https://api.partner-connect.io/api/{partner-prefix}/order' \--header 'Content-Type: application/json' \--header 'X-API-KEY: your-key:your-secret' \\--data '{" \"orderReferenceId\": \"ORDER-124\", \"orderType\": \"order\", "currency": "USD", \"shippingAddress\": { \"country\": \"US\", \"firstName\": \"John\", \"lastName\": \"Doe\", \"addressLine1\": \"123 Main St\", "city": "New York", \"postCode\": \"10001\", "state": "NY", "email": "[email protected]", \"phone\": \"123-456-7890\" }, "items": [ { "itemReferenceId": "ITEM-001", "productName": "Flyer", \"productVariant\": { \"Formaat\": \"A4\", \"Papier\": \"Ongecoat 200gsm\", \"Afdrukken\": \"Eén zijde in full color\" }, \"quantity\": 100, \"files\": [ { \"type\": \"default\", "url": "https://example.com/files/flyer.pdf" } ] } ]}'Beste praktijken
Ongeacht welke aanpak je kiest, volg deze best practices:
Consistentie: Houd vast aan één aanpak gedurende je implementatie
Documentatie: Zorg voor heldere documentatie van je productkoppelingen
Validatie: Controleer product-ID's voordat je bestellingen plaatst
Testen: Test grondig met voorbeeldbestellingen voordat je live gaat
Foutafhandeling: Zorg voor een sterke foutafhandeling bij ongeldige producten
Overstappen tussen benaderingen
Als je begint met product-UID's en later wilt overstappen naar klantproducten:
Stel je klantproducten in op GelatoConnect
Koppel ze aan de Product UIDs die je hebt gebruikt
Werk je API-implementatie bij om productName en productVariant te gebruiken
Test alles goed voordat je het in productie zet.
De omgekeerde overstap kan ook, maar dat gebeurt niet zo vaak.
Conclusie
Beide manieren hebben hun voordelen. Welke je kiest, hangt af van wat jij nodig hebt en wat er mogelijk is. Product-UID's zijn lekker simpel en geven je direct toegang tot het Gelato-catalogus. Customer Products zijn overzichtelijker, flexibeler en makkelijker centraal te beheren.
Voor de meeste langetermijnimplementaties bieden Klantproducten voordelen op het gebied van onderhoudbaarheid en duidelijkheid. Voor snelle implementaties of specifieke gebruikssituaties kunnen Product-UID's echter de voorkeur hebben.
Voor meer informatie over het instellen van klantproducten in GelatoConnect, bekijk de Handleiding klantproducten maken.