Introductie
De GelatoConnect API stelt je in staat om je systemen programmatisch te integreren met GelatoConnect om bestellingen te plaatsen, hun status bij te houden en verzendgegevens te beheren. Deze handleiding helpt je om aan de slag te gaan met de API en je eerste integratie te implementeren.
Wat je nodig hebt
Voordat je aan de slag gaat met de GelatoConnect API, zorg dat je het volgende hebt:
Je API-sleutel en geheim (die je krijgt als je een connector instelt voor je klant)
Basiskennis van REST API's en HTTP-methoden
Bekend zijn met het JSON-dataformaat
Een ontwikkelomgeving waarmee je HTTP-verzoeken kunt doen
De basis van de API
De GelatoConnect Order Management API is opgebouwd volgens REST-principes en maakt gebruik van standaard HTTP-methoden om met resources te werken. Alle API-verzoeken moeten via HTTPS verlopen en alle antwoorden worden teruggegeven in JSON-formaat, inclusief foutmeldingen.
Basis-URL
De basis-URL voor de GelatoConnect API is:
https://api.partner-connect.io/api/{partner-prefix}/Je krijgt jouw specifieke partnerprefix tijdens het onboarden.
Authenticatie
Alle API-verzoeken moeten je inloggegevens in de header bevatten. Zo kun je je aanmelden:
Voeg de
X-API-KEYheader toe aan je verzoekStel de waarde in op je sleutel en geheim in het formaat
key:secret
Voorbeeld:
X-API-KEY: jouw-api-key:jouw-api-secret
Je eerste API-verzoek doen
Laten we samen stap voor stap bekijken hoe je eenvoudig een API-verzoek doet om een bestelling te plaatsen.
1. Bereid je bestelgegevens voor
Maak een JSON-object aan met de bestelgegevens. Hier is een eenvoudig voorbeeld:
{"orderReferenceId": "your-order-ref-123",\"orderType\": \"order\",\"valuta\": \"USD\",\"verzendadres\": {\"country\": \"US\",\"firstName\": \"John\",\"lastName\": \"Doe\","addressLine1": "Hoofdstraat 123","city": "New York","postCode": "10001","state": "NY",\"email\": \"[email protected]\",\"telefoon\": \"1234567890\"},"\"items\": [{"itemReferenceId": "item-123","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/path/to/printfile.pdf"}]}]}2. Plaats de bestelling
Stuur een POST-verzoek naar het endpoint om je bestelling te plaatsen:
POST https://api.partner-connect.io/api/{partner-prefix}/orderVoeg je authenticatieheader en de JSON-bestelgegevens toe aan de body van je verzoek.
3. Ga aan de slag met het antwoord
Als alles goed gaat, krijg je zo'n antwoord:
{"id": "32884a3e-bd09-42be-8225-c5cea7d24611","orderReferenceId": "your-order-ref-123","createdAt": "12/04/2025 10:23:28"}Het veld id bevat de GelatoConnect order-ID. Bewaar deze goed, zodat je hem later makkelijk kunt terugvinden.
Veelvoorkomende API-bewerkingen
Als je de basis van het bestellen onder de knie hebt, kun je andere API-mogelijkheden ontdekken:
Bekijk je bestelgegevens
Haal informatie op over een bestaande bestelling:
GET https://api.partner-connect.io/api/{partner-prefix}/{orderId}Een bestelling annuleren
Annuleer een bestelling die nog niet is verzonden:
POST https://api.partner-connect.io/api/{partner-prefix}/{orderId}/cancelBestellingen zoeken
Vind bestellingen op basis van jouw eigen criteria:
POST https://api.partner-connect.io/api/{partner-prefix}/searchVerzending bijwerken
Verzendgegevens van een bestelling aanpassen:
PUT https://api.partner-connect.io/api/{partner-prefix}/{orderId}Klantproducten in de praktijk brengen
In plaats van product-UID's te gebruiken, kun je klantproducten gebruiken voor een meer begrijpelijke aanpak:
{"productName": "Visitekaartje",\"productVariant\": {"Maat": "Standaard","Papier": "Premium mat","Kleur": "Full color aan beide kanten"}}Hiervoor moet je eerst klantproducten instellen in GelatoConnect voordat je ze kunt gebruiken in API-aanvragen.
Je integratie testen
Voordat je live gaat met je integratie, test alles grondig met deze aanpakken:
Test met proefbestellingen: Maak proefbestellingen met lage aantallen en controleer of ze goed zichtbaar zijn in GelatoConnect.
Controleer updates van de orderstatus: Volg bestellingen tijdens het hele proces, zodat je systeem altijd op de hoogte is en goed omgaat met statuswijzigingen.
Foutafhandeling: Maak expres ongeldige bestellingen aan om te testen of je foutafhandeling goed werkt.
End-to-End testen: Doorloop het hele bestelproces van begin tot eind met een paar testbestellingen.
Beste praktijken
Om optimaal samen te werken met de GelatoConnect API:
Order-ID's van de winkel: Sla altijd het GelatoConnect order-ID op dat je krijgt bij het aanmaken van een bestelling.
Foutafhandeling toevoegen: Zorg voor een sterke foutafhandeling zodat je onverwachte reacties of een niet-beschikbare API makkelijk kunt opvangen.
Gebruik idempotentie: Maak unieke orderreferenties aan om dubbele bestellingen te voorkomen.
Gebruik exponentiële wachttijd: Krijg je een foutmelding door te veel verzoeken (429)? Wacht dan steeds iets langer voordat je het opnieuw probeert.
API-gebruik monitoren: Houd je API-gebruik in de gaten zodat je niet tegen limieten aanloopt.
Veelvoorkomende problemen oplossen
Authenticatieproblemen
Als je een 401 Unauthorized error ontvangt, controleer dan of:
Je API-sleutel en geheim zijn juist
Het formaat is
key:secretin de X-API-KEY header.Je gebruikt HTTPS, niet HTTP
Ongeldige aanvraagfouten
Krijg je een 400 Bad Request-foutmelding:
Bekijk het foutbericht om te zien bij welk veld het misgaat.
Controleer of alle verplichte velden zijn ingevuld
Bevestig dat het JSON-formaat geldig is
Foutmeldingen door te veel aanvragen
Krijg je een 429-foutmelding omdat je te veel verzoeken hebt gedaan:
Implementeer een terugvalstrategie om verzoeken te spreiden
Probeer je verzoeken te bundelen als dat kan
Controleer je integratie op onnodige herhaalde aanroepen
Volgende stap
Nu je de basis van de GelatoConnect API begrijpt, ben je ook klaar om de volledige API-documentatie te lezen voor gedetailleerde endpoint-informatie 🔗 [Orderverwerking - GCW] Documentatie voor Order Management API