Naar de hoofdinhoud

[Orderintake - GCW] Werken met Order API-eindpunten

T
Geschreven door Toby Dawson
Meer dan 3 weken geleden bijgewerkt

Deze gids biedt praktische instructies en voorbeelden voor het werken met de Order API-endpoints van GelatoConnect. We behandelen hoe je bestellingen kunt plaatsen, bestellingen kunt annuleren, verzendgegevens kunt bijwerken, bestellingsdetails kunt ophalen en bestellingen kunt zoeken via de API.

Vereisten

Voordat je met deze endpoints aan de slag gaat, zorg dat je het volgende hebt:

  • Je API-sleutel en geheime code (verstrekt bij het opzetten van een connector voor je klant)

  • De basis-URL voor je API-eindpunten

  • Basiskennis van het maken van HTTP-verzoeken met curl of je favoriete tool

Bestelling plaatsen

Het eindpunt Submit Order stelt je in staat om een nieuwe bestelling aan te maken in GelatoConnect.

Endpoint: POST /{submitOrderUrl}

Verzoekvoorbeeld

# Eenvoudig je bestelling plaatsencurl --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\": \"YOUR-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]\", \"telefoon\": \"123-456-7890\" }, \"items\": [ { \"itemReferenceId\": \"ITEM-001\", "productUid": "flat_product_pf_a4_pt_200-g-m2-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\" } ] } ]}'

Reactievoorbeeld

{ \"id\": \"32884a3e-bd09-42be-8225-c5cea7d24611\", \"orderReferenceId\": \"YOUR-ORDER-123\", "createdAt": "13-04-2025T10:23:28+00:00"}

Klantproducten gebruiken

In plaats van een productUid op te geven, kun je gepersonaliseerde producten gebruiken met productName en productVariant:

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\": \"YOUR-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]", \"telefoon\": \"123-456-7890\" }, \"items\": [ { \"itemReferenceId\": \"ITEM-001\", "productName": "Visitekaartje", \"productVariant\": { "Size": "Standaard", \"Papier\": \"Premium Mat\", \"Kleur\": \"Volledig in kleur aan beide zijden\" }," \"aantal\": 100, \"files\": [ { \"type\": \"front\", \"url\": \"https://example.com/files/front.pdf\" }, { "type": "terug", \"url\": \"https://example.com/files/back.pdf\" } ] } ]}'"

Internationale bestellingen

Voor internationale bestellingen, geef retailprijzen op voor douaneaangiftes:

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": "INTL-ORDER-456", \"orderType\": \"order\", \"currency\": \"EUR\", "retailCurrency": "GBP", \"retailShippingPriceInclVat\": 6,99, "shippingAddress": { \"country\": \"DE\", \"firstName\": \"Hans\", \"lastName\": \"Schmidt\", "addressLine1": "Unter den Linden 10", "city": "Berlijn", \"postCode\": \"10117\", \"email\": \"[email protected]\", \"phone\": \"+49123456789\" }," "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, \"retailPriceInclVat\": 19,99, \"files\": [ { "type": "standaard", "url": "https://example.com/files/printfile.pdf" } ] } ]}'

Veelvoorkomende problemen

  1. Ontbrekende verplichte velden: Zorg ervoor dat je alle verplichte velden invult in je aanvraag.

  2. Ongeldige bestandsURL's: Zorg ervoor dat je bestandsURL's openbaar toegankelijk zijn.

  3. Onbekend product-UID: Controleer of de product-UID bestaat of gebruik gepersonaliseerde producten.

  4. Dubbele orderreferentie-ID: Gebruik unieke orderreferentie-ID's voor elke bestelling.

Bestelling annuleren

Het eindpunt Bestelling annuleren stelt je in staat om het productie- en verzendproces te stoppen voor een bestelling die nog niet is verzonden.

Eindpunt: POST /{orderCancelUrl}/{orderId}/cancel

Voorbeeld van een aanvraag

# Annuleren met behulp van Gelato Order IDcurl --location --request POST 'https://api.partner-connect.io/api/{partner-prefix}/32884a3e-bd09-42be-8225-c5cea7d24611/cancel' \--header 'X-API-KEY: your-key:your-secret'# Annuleren met je orderreferentiecurl --location --request POST 'https://api.partner-connect.io/api/{partner-prefix}/YOUR-ORDER-123/cancel' \--header 'X-API-KEY: your-key:your-secret'

Reactievoorbeeld

{ "code": 200, \"message\": \"OK\"}

Veelvoorkomende problemen

  1. Bestelling al verzonden: Bestellingen die al verzonden zijn kunnen niet worden geannuleerd.

  2. Bestelling niet gevonden: Controleer of het bestelnummer of referentienummer correct is.

  3. Problemen met inloggen: Controleer of je API-sleutel en geheim juist zijn.

Zending bijwerken

Het Update Shipment-eindpunt stelt je in staat om de verzendmethode te wijzigen of het verzendadres bij te werken voor een bestelling die nog niet is verzonden.

Eindpunt: POST /{updateShipmentURL}/{orderId}

Voorbeeld van een aanvraag

# Verzendgegevens bijwerkencurl --location --request PUT 'https://api.partner-connect.io/api/{partner-prefix}/32884a3e-bd09-42be-8225-c5cea7d24611' \--header 'Content-Type: application/json' \--header 'X-API-KEY: your-key:your-secret' \--data '{" \"shipmentMethodUid\": \"fed_ex_2_day\", "shippingAddress": { \"country\": \"US\", "firstName": "Jane", "lastName": "Smith", \"addressLine1\": \"456 Park Ave\", "city": "New York", \"postCode\": \"10022\", "state": "NY", \"email\": \"[email protected]\", \"telefoon\": \"987-654-3210\" }}\"# Alleen verzendmethode bijwerkencurl --location --request PUT 'https://api.partner-connect.io/api/{partner-prefix}/32884a3e-bd09-42be-8225-c5cea7d24611' \--header 'Content-Type: application/json' \--header 'X-API-KEY: your-key:your-secret' \\--data '{" \"shipmentMethodUid\": \"fed_ex_2_day\"}\"

Voorbeeld van een reactie

{ "shippingAddress": { \"id\": \"2f85d65b-4814-4b5f-90a2-a7de28250bd1\", \"orderId\": \"32884a3e-bd09-42be-8225-c5cea7d24611\", "country": "US", \"firstName\": \"Jane\", "lastName": "Smith", \"addressLine1\": \"456 Park Ave\", "city": "New York", "postCode": "10022", \"state\": \"NY\", "email": "[email protected]", \"telefoon\": \"987-654-3210\" }, "shipment": { "shipmentMethodUid": "fed_ex_2_day", "shipmentMethodName": "FedEx 2Day", "fulfillmentCountry": "VS", "fulfillmentFacilityId": "db0622e7-d7af-4453-b39f-cdf1b67f3daa", "packageCount": 1, "initialMinDeliveryDate": "15-04-2025", "initialMaxDeliveryDate": "15-04-2025", "serviceType": "normaal" }}

Veelvoorkomende problemen

  1. Bestelling al verzonden: Verzendgegevens voor verzonden bestellingen kunnen niet worden bijgewerkt.

  2. Verplichte velden ontbreken: Zorg ervoor dat alle verplichte velden in het verzendadres zijn ingevuld.

  3. Ongeldige verzendmethode: Controleer of de verzendmethode UID geldig is.

  4. Bestelling niet gevonden: Controleer of het order-ID of referentie-ID klopt.

Bestelling ophalen

Met de Get Order-endpoint kun je alle details van een bestaande bestelling bekijken.

Endpoint: POST /{getOrderURL}/{orderId}

Voorbeeld aanvragen

# Haal bestelling op met Gelato order-IDcurl --location --request GET 'https://api.partner-connect.io/api/{partner-prefix}/32884a3e-bd09-42be-8225-c5cea7d24611' \--header 'X-API-KEY: jouw-sleutel:jouw-geheim'# Haal je bestelling op met je orderreferentiecurl --location --request GET 'https://api.partner-connect.io/api/{partner-prefix}/YOUR-ORDER-123' \--header 'X-API-KEY: your-key:your-secret'

Reactievoorbeeld

Het antwoord bevat uitgebreide informatie over de bestelling, zoals:

  • Bestelgegevens (ID, referentie, status, tijdstempels)

  • Verzendadres

  • Bestelde items

  • Verzendinformatie

  • Financiële informatie

Vanwege de lengte van het antwoord, raadpleeg de API-documentatie voor de volledige responsstructuur.

Aan de slag met de antwoordgegevens

De reactie op de bestelling geeft je waardevolle informatie waarmee je het volgende kunt doen:

  1. Bestelstatus tonen: Laat klanten zien wat de huidige status van hun bestelling is.

  2. Zendingen volgen: Haal de trackinginformatie op om je zending te volgen.

  3. Controleer bestelgegevens: Bevestig dat de bestelgegevens correct zijn.

  4. Bestelgeschiedenis analyseren: Maak rapportages en analyses op basis van bestelgegevens.

Veelvoorkomende problemen

  1. Bestelling niet gevonden: Controleer of het order-ID of referentie-ID klopt.

  2. Problemen met inloggen: Controleer of je API-sleutel en geheim juist zijn.

Bestellingen zoeken

Met het eindpunt Bestellingen zoeken kun je een lijst met bestellingen ophalen op basis van specifieke criteria.

Eindpunt: POST /{searchOrdersURL}

Voorbeeld van een aanvraag

# Zoeken op fulfilmentstatuscurl --location 'https://api.partner-connect.io/api/{partner-prefix}/search' \--header 'Content-Type: application/json' \--header 'X-API-KEY: your-key:your-secret' \--data '{" "fulfillmentStatus": ["verzonden", "geleverd"]}'"# Zoeken op datumbereikcurl --location 'https://api.partner-connect.io/api/{partner-prefix}/search' \--header 'Content-Type: application/json' \--header 'X-API-KEY: your-key:your-secret' \\--data '{ \"startDate\": \"2025-01-01T00:00:00+00:00\", "endDate": "2025-04-13T23:59:59+00:00"}'# Zoeken op orderreferentie-IDcurl --location 'https://api.partner-connect.io/api/{partner-prefix}/search' \--header 'Content-Type: application/json' \--header 'X-API-KEY: your-key:your-secret' \--data '{" \"orderReferenceId\": \"YOUR-ORDER-123\"}'"# Zoeken met pagineringcurl --location 'https://api.partner-connect.io/api/{partner-prefix}/search' \--header 'Content-Type: application/json' \--header 'X-API-KEY: jouw-sleutel:jouw-geheim' \--data '{ \"fulfillmentStatus\": [\"created\", \"printed\"], \"limit\": 50, "offset": 0}'

Reactievoorbeeld

{ "orders": [ { "id": "9f9ff09f-5891-4d3d-be35-9b302db835a1", "clientId": "ddb4371a-ad83-4f68-b99d-6b48c7eff366", \"orderReferenceId\": \"YOUR-ORDER-123\", "fulfillmentStatus": "verzonden", "financialStatus": "betaald", "currency": "USD", "totalInclVat": "33,45", "orderType": "order", \"channel\": \"api\", "firstName": "John", \"lastName\": \"Doe\", "country": "VS", "itemsCount": 1, \"createdAt\": \"2025-04-10T11:05:09+00:00\", \"updatedAt\": \"2025-04-10T14:05:10+00:00\", \"orderedAt\": \"2025-04-10T11:05:07+00:00\", \"customerReferenceId\": \"CUST-456\" }, // Meer bestellingen... ]}

Paginering

Het eindpunt Bestellingen zoeken ondersteunt paginering om grote resultaatsets te beheren:

# Eerste pagina (50 items)curl --location 'https://api.partner-connect.io/api/{partner-prefix}/search' \--header 'Content-Type: application/json' \--header 'X-API-KEY: your-key:your-secret' \--data '{ \"fulfillmentStatus\": [\"shipped\"], \"limit\": 50, "offset": 0}'"# Tweede pagina (volgende 50 items)curl --location 'https://api.partner-connect.io/api/{partner-prefix}/search' \--header 'Content-Type: application/json' \--header 'X-API-KEY: jouw-sleutel:jouw-geheim' \--data '{" \"fulfillmentStatus\": [\"shipped\"], \"limit\": 50, \"offset\": 50}'

Veelvoorkomende zoekscenario's

  1. Bestellingen per status:

    { \"fulfillmentStatus\": [\"aangemaakt\", \"afgedrukt\"] }

  2. Bestellingen per datumbereik:

    { "startDate": "01/04/2025T00:00:00+00:00", \"endDate\": \"2025-04-13T23:59:59+00:00\"}

  3. Bestellingen per land:

    { "countries": ["VS", "CA"] }

  4. Criteria combineren:

    { \"fulfillmentStatus\": [\"shipped\"], \"countries\": [\"US\"], "startDate": "01/04/2025 00:00:00"}

Veelvoorkomende problemen

  1. Geen resultaten: Kijk of je zoekcriteria niet te streng zijn.

  2. Te veel resultaten: Gebruik paginering en/of extra filters om je zoekopdracht te verfijnen.

  3. Ongeldig formaat: Zorg ervoor dat datumformaten voldoen aan ISO 8601 (JJJJ-MM-DDTUU:MM:SS+00:00).

Templates koppelen aan API-eindpunten

Als je bestellingen via de API indient, moet je vaak gegevens omzetten van jouw formaat naar het formaat van GelatoConnect. Templates regelen deze omzetting, maar je moet je template wel expliciet koppelen aan het API-endpoint om het te laten werken.

Zo koppel je een template aan een order submit-endpoint:

  1. Navigeer naar je lijst met connectoren en klik op de Bewerken hyperlink naast het eindpunt voor het indienen van bestellingen.

  2. Zoek op de pagina voor eindpuntconfiguratie het gedeelte Endpoint template

  3. Kies je sjabloon voor het indienen van bestellingen in het dropdownmenu.

  4. Klik op de knop Endpoint instellen rechtsboven op de pagina.

  5. Klik op Wijzigingen opslaan rechtsboven om je configuratie toe te passen

Na het voltooien van deze stappen zullen alle bestellingen die naar dit eindpunt worden verzonden je template gebruiken om de gegevens te transformeren voordat ze worden verwerkt. Dit zorgt ervoor dat het formaat van jouw systeem correct wordt omgezet naar het verwachte formaat van GelatoConnect.

Zonder deze configuratie wordt je template niet toegepast, zelfs als die bestaat en goed is ontworpen. Dit kan ervoor zorgen dat je bestelling niet wordt goedgekeurd als je gegevens niet precies voldoen aan de eisen van GelatoConnect.

Integratie Best Practices

Als je de Order API-eindpunten gebruikt, houd dan rekening met deze tips:

1. Winkelbestellings-ID's

Bewaar altijd zowel je orderreferentie als het Gelato order-ID dat je in de reactie ontvangt. Zo kun je bestellingen in beide systemen makkelijk terugvinden en volgen.

2. Ga soepel om met fouten

Implementeer goede foutafhandeling voor elke API-aanroep. Analyseer de foutmelding uit de respons om betekenisvolle feedback aan gebruikers te geven en implementeer passende herstelmechanismen.

Voor tips over hoe je sterke foutafhandeling implementeert, kijk je bij het onderdeel "Best practices voor foutafhandeling" in de Order Management API-documentatie.

3. Implementeer Idempotentie

Genereer unieke orderreferentie-ID's voor elke bestelling en gebruik de preventDuplicate-parameter om ervoor te zorgen dat een bestelling niet dubbel wordt ingediend, zelfs niet als er netwerkproblemen zijn en je het opnieuw probeert.

4. Gebruik Webhook-meldingen

In plaats van steeds te checken of de orderstatus is veranderd, kun je webhookmeldingen instellen. Zo krijg je direct een seintje zodra de status van je bestelling wijzigt.

5. Valideer gegevens voor verzending

Valideer ordergegevens aan jouw kant voordat je ze naar de API stuurt om duidelijke fouten te onderscheppen en de gebruikerservaring te verbeteren.

6. Implementeer herlogica

Voeg een retry-logica toe met een steeds langere wachttijd bij tijdelijke fouten, vooral bij rate limit (429) meldingen.

Voor meer informatie over hoe je exponential backoff en jitter toepast, kijk je bij het onderdeel "Rate limit best practices" in de Order management API documentatie of lees je de AWS blogpost over exponential backoff en jitter.

7. Optimaliseer zoekopdrachten

Wees duidelijk in je zoekcriteria, zo krijg je minder resultaten en werkt alles sneller.

8. Referentiegegevens cachen

Sla product-UID's en andere referentiegegevens op in de cache, zodat je minder vaak een API-aanvraag hoeft te doen.

Conclusie

De GelatoConnect Order API biedt een krachtig pakket aan endpoints om het hele bestelproces te beheren. Als je weet hoe je deze endpoints slim gebruikt, kun je jouw systemen moeiteloos koppelen aan GelatoConnect.

Voor meer gedetailleerde informatie kun je terecht in de Order Management API-documentatie.

Gerelateerde artikelen
[Orderintake - GCW] Hoe stel je postbacks in?
[Orderontvangst - GCW] Documentatie voor Order Management API
[Orderintake - GCW] Gebruik van klantproducten versus ProductUID in API-bestellingen
[Order Intake - GCW] Hoe je de klant-agnostische Order API-eindpunten gebruikt
[Orderverwerking - GCW] GelatoConnect API Basics
Was dit een antwoord op uw vraag?