Naar de hoofdinhoud

[Aan de slag - GCW] Aan de slag met GelatoConnect API

Geschreven door Kyle Sawyer

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:

  1. Voeg de X-API-KEY header toe aan je verzoek

  2. Stel de waarde in op je sleutel en geheim in het formaat key:secret

Voorbeeld:

X-API-KEY: your-api-key:your-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",
  "currency": "USD",
  "shippingAddress": {
    "country": "US",
    "firstName": "John",
    "lastName": "Doe",
    "addressLine1": "123 Main St",
    "city": "New York",
    "postCode": "10001",
    "state": "NY",
    "email": "[email protected]",
    "phone": "1234567890"
  },
  "items": [
    {
      "itemReferenceId": "item-123",
      "productUid": "flat_product_pf_a4_pt_200-gsm-uncoated_cl_4-0_ct_none_prt_none_sft_none_set_none_hor",
      "quantity": 1,
      "files": [
        {
          "type": "default",
          "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}/order

Voeg 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": "2025-04-12T10:23:28+00:00"
}

Het veld id bevat de GelatoConnect-order-ID, die je moet bewaren voor toekomstig gebruik.

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}/cancel

Bestellingen zoeken

Vind bestellingen op basis van jouw eigen criteria:

POST https://api.partner-connect.io/api/{partner-prefix}/search

Verzending 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": "Business Card",
  "productVariant": {
    "Size": "Standard",
    "Paper": "Premium Matte",
    "Color": "Full Color Both Sides"
  }
}

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:

  1. Testen met voorbeeldbestellingen: maak testbestellingen met kleine aantallen en controleer of ze correct worden weergegeven in GelatoConnect.

  2. Controleer updates van de orderstatus: Volg bestellingen tijdens het hele proces, zodat je systeem altijd op de hoogte is en goed omgaat met statuswijzigingen.

  3. Foutafhandeling: Maak expres ongeldige bestellingen aan om te testen of je foutafhandeling goed werkt.

  4. 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:secret in 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 stappen

Nu je de basis van de GelatoConnect API begrijpt, ben je klaar om:

  1. Lees de volledige API-documentatie voor gedetailleerde informatie over endpoints

  2. Kom meer te weten over API-best practices voor authenticatie, snelheidslimieten en foutafhandeling

  3. Ontdek hoe u met API-eindpunten werkt met gedetailleerde voorbeeldbewerkingen

Voor extra ondersteuning bij uw API-integratie kunt u contact opnemen met ons supportteam via [email protected].

Gerelateerde artikelen
Was dit een antwoord op uw vraag?