Introductie
Welkom bij de documentatie van de Order Management API. Met deze API kun je bestellingen plaatsen, bestellingen annuleren, bestellingsdetails ophalen, bestellingen zoeken en verzendadressen of -methoden bijwerken binnen het GelatoConnect-systeem. De API is georganiseerd volgens [nt]REST[/nt]-principes en gebruikt standaard HTTPS-methoden om met resources te communiceren. Alle reacties worden in JSON-formaat geretourneerd, inclusief foutmeldingen.
Authenticatie
Alle Order Management API-aanroepen vereisen authenticatie met behulp van een geldige API-sleutel en geheim die in de header van elke aanroep worden verstrekt. Alle communicatie moet via HTTPS verlopen; aanroepen via gewone HTTP zullen mislukken.
Authenticatiemethode
Voeg de
X-API-KEYheader toe aan je verzoekStel de waarde in met het formaat:
key:secret
Voorbeeld:
X-API-KEY: your-key:your-secret
Je specifieke API-sleutel en geheime code worden verstrekt bij het opzetten van een connector voor je klant.
Tarieflimieten
De API stelt grenzen aan het aantal verzoeken dat je als gebruiker of klant binnen een bepaalde periode mag doen. Al je verzoeken tellen mee voor je persoonlijke limiet van 100 verzoeken per seconde.
Waarom er limieten bestaan
Limieten voor aanvragen dienen verschillende belangrijke doelen:
Bescherming tegen misbruik of verkeerd gebruik van de API
Eerlijke toegang garanderen voor alle gebruikers
Voorkomen van serviceonderbrekingen door overmatig verkeer
Herlogica voor snelheidslimietfouten
Als je de API-snelheidslimiet overschrijdt, ontvang je een 429 statuscode. Om de impact op je werklasten te minimaliseren, kun je deze hersteltechnieken implementeren:
Opnieuw proberen: Mislukte verzoeken automatisch opnieuw proberen. Implementeer herlogica in je applicatiecode voor alle API-aanroepen.
Exponentiële Backoff: Gebruik steeds langere wachttijden tussen nieuwe pogingen voor opeenvolgende foutmeldingen. Implementeer een maximaal vertragingsinterval en een maximaal aantal nieuwe pogingen op basis van de uitgevoerde bewerking.
Jitter: Voeg een willekeurige hoeveelheid tijd toe voordat verzoeken opnieuw worden geprobeerd om te voorkomen dat alle clients tegelijkertijd opnieuw proberen. Dit helpt de belasting te verdelen en voorkomt opeenvolgende botsingen.
Voor meer informatie over herhalingspogingstrategieën, zie:
Responscodes
De Order Management API gebruikt conventionele HTTP-responscodes om het succes of falen van verzoeken aan te geven:
2xx Codes: Duiden op succes
4xx Codes: Duiden op structurele of datafouten in het verzoek (bijv. ontbrekende verplichte parameters, bestelling niet gevonden)
5xx Codes: Duiden op serverfouten (deze komen zelden voor)
API-eindpunten
Bestelling plaatsen
Dien een bestelling in met één enkele aanvraag.
Eindpunt: POST /{submitOrderUrl}
De basis-URL en het specifieke eindpunt krijg je tijdens het instellen van de connector.
Aanvraagformaat
{ "orderReferenceId": "test", "orderType": "order", "currency": "EUR", "retailCurrency": "GBP", "retailShippingPriceInclVat": 6.99, "shipmentMethodUid": "normal,standard,fed_ex_2_day", "shippingAddress": { "country": "SE", "firstName": "My first name", "lastName": "My last name", "addressLine1": "17", "addressLine2": "Address 1", "city": "City", "postCode": "11111", "state": "", "email": "[email protected]", "phone": "+47222222", "companyName": "MyCompany" }, "items": [ { "itemReferenceId": "test1", "productUid": "flat_product_pf_a4_pt_200-gsm-uncoated_cl_4-0_ct_none_prt_none_sft_none_set_none_hor", "quantity": 1, "retailPriceInclVat": 19.99, "files": [ { "type": "default", "url": "https://www.example.com/path/to/printfile.pdf" } ] } ]}Voorbeeld curl-verzoek (klik hier)
Voorbeeld curl-verzoek (klik hier)
curl --location --request POST 'https://api.partner-connect.io/api/your-partner-prefix/order' \--header 'Content-Type: application/json' \--header 'X-API-KEY: jouw-sleutel:jouw-geheim' \--data-raw '{ "orderReferenceId": "test", "orderType": "order", "preventDuplicate": true, "currency": "EUR", "retailCurrency": "GBP", "retailShippingPriceInclVat": 6.99, "shipmentMethodUid": "normal,standard,fed_ex_2_day", "shippingAddress": { "country": "SE", "firstName": "My first name", "lastName": "My last name", "addressLine1": "17", "addressLine2": "Address 1", "city": "City", "postCode": "11111", "state": "", "email": "[email protected]", "phone": "+47222222", "companyName": "MyCompany" }, "items": [ { "itemReferenceId": "test1", "productUid": "flat_product_pf_a4_pt_200-gsm-uncoated_cl_4-0_ct_none_prt_none_sft_none_set_none_hor", "quantity": 1, "retailPriceInclVat": 19.99, "files": [ { "type": "default", "url": "https://www.example.com/path/to/printfile.pdf" } ] } ]}'"Belangrijke aanvraagparameters
Parameter | Type | Vereist | Beschrijving |
orderReferenceId | tekenreeks | Vereist | Je interne orderreferentie |
orderType | tekenreeks | Optioneel | Type of order: "order" (default) or "draft" |
valuta | tekenreeks | Vereist | Valuta voor de bestelling (ISO-code) |
retailvaluta | tekenreeks | Optioneel | Valuta gebruikt voor verkoopprijzen (voor grensoverschrijdende bestellingen) |
detailhandelsverzendkostenInclBTW | nummer | Optioneel | Verzendkosten exclusief BTW (ondanks de parameternaam) |
shipmentMethodUid | tekenreeks | Optioneel | Verzendmethode(s) om te gebruiken, kunnen door komma's gescheiden worden |
verzendadres | object | Vereist | Afleveradres gegevens van de klant |
artikelen | array | Vereist | Lijst met producten om te bestellen |
voorkomDuplicaat | boolean | Optioneel | Wanneer ingesteld op true, voorkomt dit het aanmaken van dubbele bestellingen met dezelfde orderReferenceId. Als een duplicaat wordt gedetecteerd, wordt er een foutmelding teruggegeven in plaats van een nieuwe bestelling aan te maken. |
"packagingInstructions": [ | reeks | Optioneel | Reeks van verpakkingsinstructie-objecten |
Itemparameters
Parameter | Type | Vereist | Beschrijving |
itemReferenceId | string | Vereist | Je interne artikelidentificatie |
productUid | string | Verplicht* | GelatoConnect product-identificatie (*Ofwel productUid OF productName+productVariant is vereist) |
productnaam | string | Verplicht* | Naam van het klantproduct (*ProductUid of productnaam + productvariant is vereist) |
productvariant | object | Verplicht* | Variantdetails voor het klantproduct (*verplicht als je productName gebruikt) |
aantal | nummer | Vereist | Aantal items om te bestellen |
verkoopprijsInclBTW | nummer | Optioneel | Prijs exclusief BTW (ondanks de parameternaam) |
bestanden | array | Vereist | Lijst van printbestanden voor het product |
gepersonaliseerdeAfwerking | object | Optioneel | Gepersonaliseerde afwerkingsafmetingen voor het product |
Bestandsparameters
Parameter | Type | Vereist | Beschrijving |
type | string | Vereist | Bestandstype. Bekijk de opties in de tabel hieronder. |
url | string | Vereist | Openbaar toegankelijke URL naar het printbestand |
Bestandstype
Parameter | Beschrijving |
standaard | Het ontwerp wordt gedrukt op het belangrijkste deel van het product. Bij kleding is dat de voorkant, bij vouwkaarten zijn dat de voor- en achterkant.
Als je een PDF met meerdere pagina's aanlevert, moet het aantal pagina's overeenkomen met de afdrukgebieden, aangezien deze gebruikt zal worden om op alle gebieden te printen. |
voorkant | Print het bestand op de voorkant van het product. |
terug | Druk het bestand af op de achterkant van het product. |
omslag | Het bestand voor een boekomslag |
binnenkant hals | Print het bestand aan de binnenkant van de hals van het kledingstuk. |
buitenkant hals | Print het bestand op de buitenkant van de hals van het kledingproduct. |
linkermouw | Print het bestand op de linkermouw van het kledingproduct. |
rechter mouw | Print het bestand op de rechter mouw van het kledingstuk. |
binnen | Print het bestand op de binnenpagina's. |
borduring op linker borst | Borduur het bestand op de linkerborst van het kledingstuk. |
borduursel midden op de borst | Borduur het bestand in het midden van de borst van het kledingproduct. |
borst-groot-borduurwerk | Borduur het bestand op de voorkant van het kledingproduct. |
linkermouw borduursel | Borduur het bestand op de linkermouw van het kledingproduct. |
rechter mouw borduursel | Borduur het bestand op de rechter mouw van het kledingproduct. |
borduursel op linkerpols | Borduur het bestand op de linker pols van het kledingproduct. |
rechter-pols-borduurwerk | Borduur het bestand op de rechterpols van het kledingstuk. |
Flexibele bestandstypen voor workflow-ondersteunde producten
Voor producten die zijn ingeschakeld voor workflow builder, kunt u elke gepersonaliseerde bestandstypenaam gebruiken in het veld type van de files array. Deze functie vereenvoudigt API-integraties door de noodzaak om bestanden aan voorgedefinieerde types te koppelen weg te nemen.
Belangrijkste punten:
Je kunt bestandstypen vrij benoemen, zoals
default_1,default_2,cover_front,inside_page, etc.Toegestane tekens: letters (A-Z, a-z), cijfers (0-9), underscores (_), punten (.) en koppeltekens (-)
Maximale lengte: 100 tekens
Unieke bestandstypen blijven van toepassing - elke
typewaarde moet uniek zijn binnen dezelfdefilesarray
Gebruiksvoorbeeld:
{ "items": [ { "productUid": "your-workflow-enabled-product-uid", "quantity": 1, "files": [ { "type": "default_1", "url": "https://your-file-url.com/file1.pdf" }, { "type": "default_2", "url": "https://your-file-url.com/file2.pdf" }, { "type": "custom_cover", "url": "https://your-file-url.com/cover.pdf" } ] } ]}
Gepersonaliseerde afwerkingsparameters
Parameter | Type | Vereist | Beschrijving |
breedteMm | nummer | Vereist | Afwerkingsbreedte in millimeters (*Vereist bij gebruik van gepersonaliseerde afwerking) |
hoogtemm | nummer | Vereist | Afwerking hoogte in millimeters (*Vereist bij gebruik van gepersonaliseerde afwerking) |
Parameters voor verpakkingsinstructies
Parameter | Type | Vereist | Beschrijving |
"packageItems": [ | array | Vereist | Items om in dit pakket op te nemen |
orderItemReferenceId | string | Vereist | Verwijzing naar het orderitem (moet overeenkomen met itemReferenceId) |
aantal | nummer | Vereist | Aantal van het item in dit pakket |
"packingSlip": { | object | Optioneel | Pakbon configuratie |
bestandsURL | string | Vereist | URL naar het PDF-pakbon bestand |
GelatoConnect zal je pakbon-PDF downloaden en opslaan om ervoor te zorgen dat deze toegankelijk blijft tijdens het verpakkingsproces, zelfs als de oorspronkelijke URL verloopt.
Gebruiksvoorbeeld:
{ "orderReferenceId": "ORDER-12345", "orderType": "order", "currency": "USD", "shippingAddress": {...}, "items": [...], "packagingInstructions": [ { "packageItems": [ { "orderItemReferenceId": "ITEM-001", "quantity": 1 } ], "packingSlip": { "fileUrl": "https://example.com/slip.pdf" } } ]}
Migratie van op metadata gebaseerde pakbonnen
Voor klanten die momenteel metadata gebruiken om pakbonnen te verzenden, kunt u de onderstaande sjabloon gebruiken om pakbon-URL's uit metadata te halen en deze om te zetten naar het packagingInstructions-formaat, waardoor permanente bestandsopslag door GelatoConnect wordt gegarandeerd.
{%- set payload = context.payload -%}{#-- Extract packing slip URL and filter out 'tenant-packing-slip' --#}{%- set ns = namespace(packing_slip_url=None) -%}{%- set filtered_metadata = [] -%}{%- for m in payload.metadata or [] %} {%- if m.key == "tenant-packing-slip" %} {%- set ns.packing_slip_url = m.value %} {%- else %} {%- set filtered_metadata = filtered_metadata + [m] %} {%- endif %} {%- endfor -%}{#-- Output bijgewerkte JSON --#}{ {%- for key, value in payload.items() %} {%- if key != "metadata" %} "##{{ key }}": ##{{ value | tojson }}, {%- endif %} {%- endfor %} "metadata": ##{{ filtered_metadata | tojson }},verpakkingsinstructies {pakketitems {%- for item in payload.get("items") or [] -%} { "orderItemReferenceId": ##{{ item.itemReferenceId|js }}, "quantity": ##{{ item.quantity }} }{% if not loop.last %},{% endif %}{%- endfor %} ],pakbon "fileUrl": "##{{ ns.packing_slip_url }}" } } ]}
Verzendadresparameters
Parameter | Type | Verplicht | Beschrijving |
land | string | Verplicht | Tweeletterige landcode (ISO 3166-1 alpha-2) |
voornaam | string | Vereist | Voornaam van de ontvanger |
achternaam | string | Vereist | Achternaam ontvanger |
adresregel1 | tekenreeks | Vereist | Eerste regel van het adres |
adresregel2 | string | Optioneel | Tweede regel van het adres |
stad | string | Vereist | Plaatsnaam |
postcode | string | Vereist | Postcode |
staat | string | Vereist | Staat- of provinciecode (*verplicht voor adressen in de VS, Canada en Australië) |
string | Verplicht* | E-mailadres van de ontvanger | |
telefoon | string | Vereist | Telefoonnummer van de ontvanger met landcode |
bedrijfsnaam | tekenreeks | Optioneel | Bedrijfsnaam (indien van toepassing) |
isBusiness | boolean | Optioneel | Of het adres voor een bedrijf is |
federaal belastingnummer | string | Optioneel | Fiscaal nummer voor zakelijke adressen |
btw-nummer van de staat | string | Optioneel | Staatsbelastingnummer voor zakelijke adressen |
registratiestatus | string | Optioneel | Provincie waar je bedrijf is ingeschreven |
Belangrijke informatie voor internationale bestellingen
Voor internationale bestellingen geef je de winkelprijs van het product en de verzendkosten als volgt op:
retailCurrency: De valuta waarin de winkelprijzen worden weergegevenretailShippingPriceInclVat: Verzendkosten exclusief BTW (negeer de naam van de parameter)items[i].retailPriceInclVat: Totale productprijs exclusief BTW (negeer de naam van de parameter)
Een product kiezen
De order submit API kan op twee manieren productinformatie ontvangen:
Gebruik van
productUid:
"productUid": "frame_product_frs_10x10-inch_frc_oak_frm_wood_frp_w13xt22-mm_gt_plexiglass"
Met
productNameenproductVariant:
"productName": "Framed Poster","productVariant": { "FrameColour": "Black", "PaperSize": "A3"}Gebruik niet allebei de methodes in dezelfde bestelling.
Een verzendmethode kiezen
Het veld shipmentMethodUid kan het volgende accepteren:
Specifieke verzendmethode-UID's (bijvoorbeeld
fed_ex_2_day)Namen van verzendbedrijven (zoals
DHL)Verzendopties in verschillende niveaus (zoals
Express)
Je kunt meerdere verzendmethodes opgeven, gescheiden door een komma. Het systeem kiest dan automatisch de goedkoopste optie.
Antwoordformaat
{ "id": "32884a3e-bd09-42be-8225-c5cea7d24611", "orderReferenceId": "test", "createdAt": "2024-07-17T10:23:28+00:00"}
Gebruik van metadata in heel GelatoConnect
Metadata die je toevoegt aan zowel het order- als het artikelniveau in bestellingen, kan door verschillende tools binnen GelatoConnect worden gebruikt en wordt ook teruggestuurd in postbacks. Dit is vooral handig voor iedereen die de gegevens tussen hun systemen soepel wil laten doorlopen.
Metadata op orderniveau:
Metadata op orderniveau is van toepassing op de gehele bestelling en wordt gedefinieerd op het hoogste niveau van het verzoek.
{ "orderReferenceId": "ORD-12345", "orderType": "order", "currency": "USD", "metadata": [ { "key": "campaign", "value": "summer_promo" }, { "key": "source", "value": "web" } ], "shippingAddress": {...}, "items": [...]}
Metadata op artikelniveau:
Metadata op itemniveau geldt voor specifieke items en wordt per item in de items-lijst vastgelegd.
{ "orderReferenceId": "ORD-12345", "orderType": "order", "currency": "USD", "shippingAddress": {...}, "items": [ { "itemReferenceId": "ITEM-001", "productUid": "flat_product_pf_a4_pt_200-gsm-uncoated_cl_4-0_ct_none_prt_none_sft_none_set_none_hor", "quantity": 1, "metadata": [ { "key": "position", "value": "A1" }, { "key": "machine", "value": "Printer3" } ], "files": [...] } ]}
Bestandsniveau metadata:
Bestandsniveau-metadata is van toepassing op specifieke bestanden en wordt gedefinieerd binnen elk bestand in de bestanden-array. In het onderstaande voorbeeld wordt het gebruikt om alternatieve tekst te definiëren voor de afbeelding embroideryText die bij het bestand hoort.
{ "orderReferenceId": "ORD-12345", "orderType": "order", "currency": "USD", "shippingAddress": {...}, "items": [ { "itemReferenceId": "ITEM-001", "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://www.example.com/path/to/printfile.pdf", "metadata": [ { "key": "embroideryText", "value": "James" } ] } ] } ]}
Bestelling annuleren
Stop en annuleer het productie- en verzendproces van een bestelling. Dit kan alleen zolang de status van de bestelling nog niet op "verzonden" staat.
Endpoint: POST /{orderCancelUrl}
Deze endpoint accepteert zowel het order-ID (dat je krijgt na het plaatsen van een bestelling) als het orderreferentie-ID (jouw eigen interne ordernummer).
Bestellen met order-ID
POST /{orderCancelUrl}/32884a3e-bd09-42be-8225-c5cea7d24611/cancelBestellen met referentie-ID
POST /{orderCancelUrl}/test/cancelAntwoordformaat
{ "code": 200, "message": "OK"}
Zending bijwerken
Pas de verzendmethode aan of werk het verzendadres bij zolang de bestelling nog niet op 'verzonden' staat.
Endpoint: PUT /{updateShipmentURL}
Deze endpoint accepteert zowel het order-ID als het orderreferentie-ID.
Aanvraagformulier
{ "shipmentMethodUid": "fed_ex_2_day", "shippingAddress": { "country": "GB", "firstName": "Alexis", "lastName": "Apollo", "addressLine1": "Longusta str. 4", "addressLine2": "app. 144", "city": "myCity", "postCode": "111111", "state": "myState", "email": "[email protected]", "phone": "+34 111444111", "companyName": "Company_example", "isBusiness": false, "federalTaxId": "", "stateTaxId": "", "registrationState": "" }}Je kunt de verzendmethode, het verzendadres of allebei aanpassen. Je moet in ieder geval één van deze velden invullen in je aanvraag.
Aanvraagparameters
Parameter | Type | Vereist | Beschrijving |
shipmentMethodUid | string | Optioneel* | Nieuwe verzendmethode (*Ten minste een van shipmentMethodUid of shippingAddress moet worden opgegeven) |
verzendadres | object | Optioneel* | Nieuwe verzendadresgegevens (*Je moet minimaal een verzendmethode of verzendadres opgeven) |
Antwoordformaat
{ "shippingAddress": { "id": "2f85d65b-4814-4b5f-90a2-a7de28250bd1", "orderId": "148c5a06-35c9-40d3-8ef7-e85eb2da317d", "country": "GB", "firstName": "Test Order", "lastName": "4", "companyName": "company_example", "addressLine1": "address example 1", "addressLine2": "address example 2", "city": "myCity", "postCode": "111111", "state": "", "email": "[email protected]", "phone": "+34 111444222", "isBusiness": false, "federalTaxId": "", "stateTaxId": "", "registrationState": "" }, "shipment": { "shipmentMethodUid": "fed_ex_2_day", "shipmentMethodName": "DHL Global Parcel", "fulfillmentCountry": "DE", "fulfillmentFacilityId": "db0622e7-d7af-4453-b39f-cdf1b67f3daa", "packageCount": 1, "initialMinDeliveryDate": "2024-11-16", "initialMaxDeliveryDate": "2024-11-16", "serviceType": "normal" }}
Bestelling ophalen
Haal informatie op over een bestaande bestelling.
Endpoint: GET /{getOrderURL}/{order_id}
Je kunt zowel het Gelato order-ID als je eigen orderreferentie gebruiken.
Antwoordformaat
Het antwoord bevat uitgebreide informatie over de bestelling, zoals:
Bestelgegevens (ID, referentie, status, enzovoort)
"shippingAddress": {
Bestelde items met productdetails
Verzendinformatie (methode, tracking, enzovoort)
Financiële informatie
Voorbeeld van een reactie (klik hier)
Voorbeeld van een reactie (klik hier)
{ "id": "9f9ff09f-5891-4d3d-be35-9b302db835a1", "clientId": "ddb4371a-ad83-4f68-b99d-6b48c7eff366", "orderReferenceId": "healthcheck_middleware_order_create_2024-12-02-11:05:06_1991", "customerReferenceId": "sandbox-customer", "fulfillmentStatus": "failed", "financialStatus": "canceled", "currency": "USD",Verzendadres "id": "29de7336-95a9-48d2-aa85-d7d40e6ea65c", "orderId": "9f9ff09f-5891-4d3d-be35-9b302db835a1", "country": "GB", "firstName": "TEST", "lastName": "PRINT", "companyName": "", "addressLine1": "19 June Lewis Way", "addressLine2": "", "city": "Fairford", "postCode": "GL7 4GH", "state": "", "email": "[email protected]", "phone": "1111111119", "isBusiness": false, "federalTaxId": null, "stateTaxId": null, "registrationState": null }, "items": [ { "id": "e9f6de69-670b-47c5-a953-3710cac053a1", "itemReferenceId": "1111111111", "productUid": "large-posters_pf_500x700-mm_pt_170-gsm-coated-silk_cl_4-0_ver", "storeProductVariantId": null, "storeProductId": null, "files": [ { "id": null, "type": "default", "url": "https://URLexample.com/order", "threadColors": [], "isVisible": false, "fitMethod": null, "fillMethod": null, "mimeType": "application/pdf", "metadata": [] } ], "processedFileUrl": null, "quantity": 1, "options": [], "category": "Posters", "productCategoryUid": "wall-art", "productTypeUid": "poster", "productNameUid": "classic-semi-glossy-poster", "productName": "Classic Semi-Glossy Poster", "fulfillmentStatus": "failed", "pageCount": null, "printJobs": [], "eventLog": [], "previews": [ { "type": "preview_default", "url": "https://URLexample.com/order" }, { "type": "preview_thumbnail", "url": "https://URLexample.com/order" }, { "type": "preview_flat", "url": "https://URLexample.com/order" } ], "designId": null, "productFileMimeType": "application/pdf", "finalProductUid": "large-posters_pf_500x700-mm_pt_170-gsm-coated-silk_cl_4-0_ver", "metadata": [ { "key": "unitWeight", "value": "800" }, { "key": "unitPrice", "value": "" },} "key": "supplierPartAuxiliaryId", "value": ""{} "retailPriceInclVat": null, "attributes": [ ] "name": "size", "title": "Size", "value": "500x700-mm", "formattedValue": "50 x 70 cm" } { "name": "orientation", "title": "Orientation", "value": "ver", "formattedValue": "Vertical (portrait) orientation"{} "itemReferenceName": null, "isIgnored": false, "price": 0, "customTrim": null, "fileUrl": "https://URLexample.com/order", "dpi": 0, "appServices": [], "filesSize": 3.8, "productVariant": [] ]{ "shipment": { "id": "33163694-1437-407f-99ef-57a0d579114f", "orderProductId": null, "shippingAddressId": "29de7336-95a9-48d2-aa85-d7d40e6ea65c", "promiseUid": "d_dfae1a1c58d230dbe73690a2", "packageCount": 1, "shipmentMethodUid": "dhl_global_parcel", "shipmentMethodName": "DHL Global Parcel", "isCheapest": true, "minDeliveryDays": 1, "maxDeliveryDays": 1, "minDeliveryDate": "2024-12-03", "maxDeliveryDate": "2024-12-03", "totalWeight": 139, "price": 0, "status": null, "packages": [], "fulfillmentCountry": "DE", "fulfillmentFacilityId": "db0622e7-d7af-4453-b39f-cdf1b67f3daa", "retailShippingPriceInclVat": null, "initialMinDeliveryDate": "2024-12-03", "initialMaxDeliveryDate": "2024-12-03", "serviceType": "normal", "speedType": ""} "receipts": [ }, "id": "f9f6e29a-de14-4755-bafe-7cf0cdf6e3fc", "orderId": "9f9ff09f-5891-4d3d-be35-9b302db835a1", "type": "contract", "currency": "USD", "items": [ }, "id": "a99224b0-6e96-430e-84dd-82995f274840", "receiptId": "f9f6e29a-de14-4755-bafe-7cf0cdf6e3fc", "orderId": "9f9ff09f-5891-4d3d-be35-9b302db835a1", "clientId": "ddb4371a-ad83-4f68-b99d-6b48c7eff366", "type": "product", "referenceId": "e9f6de69-670b-47c5-a953-3710cac053a1", "title": "1x large-posters_pf_500x700-mm_pt_170-gsm-coated-silk_cl_4-0_ver", "currency": "USD", "priceBase": 0, "amount": 1, "priceInitial": 0, "discount": 0, "price": 0, "vat": 0, "priceInclVat": 0, "pricePlanId": null, "createdAt": "2024-12-02T11:05:09+00:00", "updatedAt": "2024-12-02T11:05:09+00:00" ], } "id": "1d2936c3-eb3f-456d-94b9-b2be8c4eec50", "receiptId": "f9f6e29a-de14-4755-bafe-7cf0cdf6e3fc", "orderId": "9f9ff09f-5891-4d3d-be35-9b302db835a1", "clientId": "ddb4371a-ad83-4f68-b99d-6b48c7eff366", "type": "shipment", "referenceId": "33163694-1437-407f-99ef-57a0d579114f", "title": "Delivery using DHL Global Parcel", "currency": "USD", "priceBase": 0, "amount": 1, "priceInitial": 0, "discount": 0, "price": 0, "vat": 0, "priceInclVat": 0, "pricePlanId": null, "createdAt": "2024-12-02T11:05:09+00:00", "updatedAt": "2024-12-02T11:05:09+00:00" { }, "id": "b7d6899c-3a00-46eb-8d14-e9b3e2bb3e4e", "receiptId": "f9f6e29a-de14-4755-bafe-7cf0cdf6e3fc", "orderId": "9f9ff09f-5891-4d3d-be35-9b302db835a1", "clientId": "ddb4371a-ad83-4f68-b99d-6b48c7eff366", "type": "packaging", "referenceId": "33163694-1437-407f-99ef-57a0d579114f", "title": "Packaging", "currency": "USD", "priceBase": 0, "amount": 1, "priceInitial": 0, "discount": 0, "price": 0, "vat": 0, "priceInclVat": 0, "pricePlanId": null, "createdAt": "2024-12-02T11:05:09+00:00", "updatedAt": "2024-12-02T11:05:09+00:00" { ], "createdAt": "2024-12-02T11:05:09+00:00", "updatedAt": "2024-12-02T11:05:10+00:00", "receiptNumber": "005-0014597660", "billingEntity": { "id": 218720, "companyName": "Gelato", "companyNumber": "", "companyVatNumber": "", "companyVatNumbers": [], "countryIsoCode": "DE", "country": "DE", "recipientName": "Alex Shiltcev", "addressLine1": "Something 1", "addressLine2": "", "city": "Berlin", "postCode": "10113", "stateCode": "", "state": "", "email": "[email protected]", "phone": "", "currencyIsoCode": "EUR", "currency": "EUR", "status": 1, "iossNumber": null, "invoiceType": null } "billingTag": "gelato-norway-de", "transactionType": "purchase", "productsPriceInitial": 0, "productsPriceDiscount": 0, "productsPrice": 0, "productsPriceVat": 0, "productsPriceInclVat": 0, "digitizationPriceInitial": 0, "digitizationPriceDiscount": 0, "digitizationPrice": 0, "digitizationPriceVat": 0, "digitizationPriceInclVat": 0, "shippingPriceInitial": 0, "shippingPriceDiscount": 0, "shippingPrice": 0, "shippingPriceVat": 0, "shippingPriceInclVat": 0, "packagingPriceInitial": 0, "packagingPriceDiscount": 0, "packagingPrice": 0, "packagingPriceVat": 0, "packagingPriceInclVat": 0, "discount": 0, "discountVat": 0, "discountInclVat": 0, "totalInitial": 0, "total": 0, "totalVat": 0, "totalInclVat": 0, "isCalculated": true }, ], "createdAt": "2024-12-02T11:05:09+00:00", "refusalReason": "Order is failing as it’s going to be cross border and product retail prices are missing.", "channel": "api", "storeId": null, "orderedByUserId": null, "orderType": "order", "metadata": [ } "key": "tenant-customer-id", "value": "02be1010-5f59-4504-a669-5cf88e84f627" { }, "key": "tenant-customer-uid", "value": "sandbox-customer" { }, "billingEntity": { "id": 218720, "companyName": "Gelato", "companyNumber": "", "companyVatNumber": "", "companyVatNumbers": [], "countryIsoCode": "DE", "country": "DE", "recipientName": "Alex Shiltcev", "addressLine1": "Something 1", "addressLine2": "", "city": "Berlin", "postCode": "10113", "stateCode": "", "state": "", "email": "[email protected]", "phone": "", "currencyIsoCode": "EUR", "currency": "EUR", "status": 1, "iossNumber": null, "invoiceType": null { "retailCurrency": null, "paymentMethodType": null, "paymentMethodId": null, "prepaymentTransactionId": null, "orderedAt": "2024-12-02T11:05:07+00:00", "updatedAt": "2024-12-02T11:05:10+00:00", "connectedOrderIds": [], "discounts": [], "returnAddress": { "id": "6eeb262a-92ce-45a4-9cd6-128473a0acb0", "country": null, "addressLine1": null, "addressLine2": null, "city": null, "postCode": null, "state": null, "email": null, "phone": null, "companyName": "Gelato Connect Sandbox" { "iossNumber": null, "refusalReasonCode": "missing_retail_prices", "refusalReasonDetails": null, "comment": "Order is failing as it’s going to be cross border and product retail prices are missing.", "digitizationId": null, "appServices": [], "shipmentMethodUid": "normal" },
Bestellingen zoeken
Haal een lijst met bestellingen op op basis van specifieke criteria.
Endpoint: POST /{searchOrdersURL}
Aanvraagformaat
], "fulfillmentStatus": [ "canceled", "delivered" } ],
Aanvraagparameters
Parameter | Type | Vereist | Beschrijving |
fulfillmentstatus | tekenreeks[] | Optioneel | Filteren op status van orderfulfilment |
financiële status | tekenreeks[] | Optioneel | Filter op financiële status van bestelling |
orderreferentie-id | tekenreeks | Optioneel | Filter op je interne order-ID |
orderreferentie-id's | tekenreeks[] | Optioneel | Filter op meerdere interne order-ID's |
startdatum | string | Optioneel | Filter op bestellingen gemaakt na deze datum (ISO 8601-formaat) |
einddatum | tekenreeks[] | Optioneel | Filter op bestellingen die vóór deze datum zijn aangemaakt (ISO 8601-formaat) |
landen | string | Optioneel | Filteren op verzendlandcodes |
limiet | nummer | Optioneel | Maximaal aantal resultaten om terug te geven (standaard: 50, max: 100) |
offset | nummer | Optioneel | Aantal resultaten om over te slaan voor paginering (standaard: 0) |
Reactieformaat
} "orders": [ { "id": "9f9ff09f-5891-4d3d-be35-9b302db835a1", "clientId": "ddb4371a-ad83-4f68-b99d-6b48c7eff366", "orderReferenceId": "orderref_123", "fulfillmentStatus": "failed", "financialStatus": "canceled", "currency": "USD", "totalInclVat": "0.00", "orderType": "order", "channel": "api", "storeId": null, "connectedOrderIds": [], "firstName": "TEST", "lastName": "PRINT", "country": "GB", "itemsCount": 1, "createdAt": "2024-12-02T11:05:09+00:00", "updatedAt": "2024-12-02T11:05:10+00:00", "orderedAt": "2024-12-02T11:05:07+00:00", "refusalReasonCode": "missing_retail_prices", "appServices": [], "customerReferenceId": "custref_456" }, { ],
Foutafhandeling
Wanneer een API-verzoek mislukt, bevat het antwoord een foutcode en een beschrijvend bericht om je te helpen het probleem te identificeren en op te lossen. Veelvoorkomende foutsituaties zijn onder andere:
400 foutieve aanvraag: ongeldige of ontbrekende parameters
401 Niet geautoriseerd: Ongeldige of ontbrekende authenticatiegegevens
404 niet gevonden: De pagina die je zoekt bestaat niet
429 Te veel verzoeken: Limiet overschreden
500 serverfout: Er ging iets mis op de server
Voorbeeld van een foutmelding:
} "code": 400, "message": "Invalid shipping address: Email is not a valid format" {Voor een sterke integratie zorg je voor goede foutafhandeling en een logische manier om het opnieuw te proberen, zoals uitgelegd in het gedeelte over limieten.
Hulp nodig?
Als je problemen ondervindt of vragen hebt over de API, neem dan contact op met ons supportteam via [email protected].
Voeg de volgende informatie toe aan je ondersteuningsverzoek:
Het specifieke API-eindpunt dat je gebruikt
Uw aanvraaggegevens (met gevoelige informatie verwijderd)
De foutmelding die je kreeg
Alle relevante tijdstempels
Hiermee kan ons team je probleem sneller en beter oplossen.