Spring videre til hovedindholdet

[Ordremodtagelse – GCW] Sådan arbejder du med Order API-endpoints

T
Skrevet af Toby Dawson
Opdateret for over 3 uger siden

Denne guide giver dig praktiske instruktioner og eksempler på, hvordan du arbejder med GelatoConnects Order API-endpoints. Vi gennemgår, hvordan du indsender ordrer, annullerer ordrer, opdaterer leveringsoplysninger, henter ordredetaljer og søger efter ordrer via API'et.

Forudsætninger

Før du går i gang med de her endpoints, skal du sørge for, at du har:

  • Din API-nøgle og hemmelige kode (du får dem, når du sætter en connector op for din kunde)

  • Basis-URL'en for dine API-endepunkter

  • Grundlæggende forståelse for at lave HTTP-forespørgsler med curl eller det værktøj, du bedst kan lide

Afgiv ordre

Med Submit Order-endpointet kan du oprette en ny ordre i GelatoConnect.

Endpoint: POST /{submitOrderUrl}

Eksempel på anmodning

# Sådan sender du en ordre afstedcurl --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": "DIN-ORDRE-123", "orderType": "ordre", "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", "productUid": "flat_product_pf_a4_pt_200-g-m2-ubestroget_cl_4-0_ct_none_prt_none_sft_none_set_none_hor", "quantity": 1, "filer": [ { "type": "standard", "url": "https://example.com/files/printfile.pdf" } ] } ]}'

Eksempel på svar

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

Sådan bruger du kundens produkter

I stedet for at angive en productUid, kan du bruge kundens produkter med productName og 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": "ordre", "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": "Visitkort", "productVariant": { "Size": "Standard", "Paper": "Premium Mat", "Farve": "Fuld farve på begge sider" }, "quantity": 100, "filer": [ { "type": "forside", "url": "https://example.com/files/front.pdf" }, { "type": "tilbage", "url": "https://example.com/files/back.pdf" } ] } ]}'

Internationale ordrer

For internationale ordrer, skal du oplyse udsalgspriser til tolddeklarationer:

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": "Berlin", "postCode": "10117", "email": "[email protected]", "phone": "+49123456789" }, "items": [ { "itemReferenceId": "ITEM-001", "productUid": "flat_product_pf_a4_pt_200-g-m2-ubestroget_cl_4-0_ct_none_prt_none_sft_none_set_none_hor", "quantity": 1, "retailPriceInclVat": 19,99, "filer": [ { "type": "standard", "url": "https://example.com/files/printfile.pdf" } ] } ]}'

Typiske udfordringer

  1. Mangler påkrævede felter: Sørg for, at du har udfyldt alle de nødvendige felter i din anmodning.

  2. Ugyldige fil-URL'er: Sørg for, at dine fil-URL'er er offentligt tilgængelige.

  3. Ukendt produkt-UID: Tjek om produktets UID findes, eller brug kundens produkter.

  4. Dublet af ordreferencenummer: Brug et unikt ordreferencenummer til hver ordre.

Aflys ordre

Med Cancel Order-endpointet kan du stoppe produktion og forsendelse af en ordre, der endnu ikke er sendt afsted.

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

Eksempel på anmodning

# Annuller med 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'# Annuller med dit ordrenummercurl --location --request POST 'https://api.partner-connect.io/api/{partner-prefix}/YOUR-ORDER-123/cancel' \--header 'X-API-KEY: your-key:your-secret'

Eksempel på svar

{ "code": 200, "message": "Fint"}

Typiske udfordringer

  1. Ordre er allerede sendt: Ordrer, der allerede er sendt, kan ikke annulleres.

  2. Ordre ikke fundet: Tjek, at ordre-ID eller reference-ID er korrekt.

  3. Problemer med login: Tjek, at din API-nøgle og hemmelige kode er korrekte.

Opdater forsendelse

Med Update Shipment-endpointet kan du ændre leveringsmetode eller opdatere leveringsadressen for en ordre, der endnu ikke er sendt afsted.

Endpoint: POST /{updateShipmentURL}/{orderId}

Eksempel på anmodning

# Opdater dine leveringsoplysningercurl --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": "Park Allé 456", "city": "New York", "postCode": "10022", "state": "NY", "email": "[email protected]", "phone": "987-654-3210" }}'# Opdater kun leveringsmetodecurl --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"}'

Eksempel på svar

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

Typiske udfordringer

  1. Ordren er allerede sendt: Du kan ikke ændre forsendelsesoplysningerne, når ordren er afsendt.

  2. Mangler påkrævede felter: Sørg for, at alle nødvendige felter er udfyldt i leveringsadressen.

  3. Ugyldig leveringsmetode: Tjek, at leveringsmetodens UID er gyldig.

  4. Ordre ikke fundet: Tjek, at ordre-ID eller reference-ID er korrekt.

Hent ordre

Get Order-endpointet giver dig mulighed for at hente detaljerede oplysninger om en eksisterende ordre.

Endpoint: POST /{getOrderURL}/{orderId}

Eksempel på anmodning

# Hent ordre med Gelato Order IDcurl --location --request GET 'https://api.partner-connect.io/api/{partner-prefix}/32884a3e-bd09-42be-8225-c5cea7d24611' \--header 'X-API-KEY: your-key:your-secret'# Find din ordre med dit ordrenummercurl --location --request GET 'https://api.partner-connect.io/api/{partner-prefix}/YOUR-ORDER-123' \--header 'X-API-KEY: your-key:your-secret'

Eksempel på svar

Svaret indeholder detaljeret information om ordren, herunder:

  • Ordredetaljer (ID, reference, status, tidsstempler)

  • Leveringsadresse

  • Bestilte varer

  • Forsendelsesoplysninger

  • Finansielle oplysninger

Da svaret er ret langt, kan du finde hele svaret i API-dokumentationen.

Sådan bruger du svardata

Get Order-svaret giver dig værdifuld information, som du kan bruge til at:

  1. Vis ordrestatus: Giv kunderne et hurtigt overblik over, hvor deres ordre er lige nu.

  2. Spor forsendelser: Få trackingoplysninger, så du kan følge dine pakker.

  3. Tjek ordreoplysninger: Sørg for, at alt i din ordre stemmer.

  4. Analyser ordreoversigt: Få overblik og indsigt med rapporter baseret på dine ordredata.

Typiske udfordringer

  1. Ordre ikke fundet: Tjek, at ordre-ID eller reference-ID er korrekt.

  2. Problemer med login: Tjek, at din API-nøgle og hemmelige kode er korrekte.

Søg efter ordrer

Med Search Orders-endpointet kan du finde en liste over ordrer, der matcher dine ønsker.

Endpoint: POST /{searchOrdersURL}

Eksempel på anmodning

# Søg efter Fulfillment-statuscurl --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", "delivered"]}'# Søg efter datointervalcurl --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": "01/01/2025 00:00", "endDate": "2025-04-13T23:59:59+00:00"}'# Søg med ordre reference-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"}'# Søg med sideinddelingcurl --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": ["created", "printed"], "limit": 50, "offset": 0}'

Eksempel på svar

{ "orders": [ { "id": "9f9ff09f-5891-4d3d-be35-9b302db835a1", "clientId": "ddb4371a-ad83-4f68-b99d-6b48c7eff366", "orderReferenceId": "YOUR-ORDER-123", "fulfillmentStatus": "afsendt", "financialStatus": "betalt", "currency": "USD", "totalInclVat": "33,45", "orderType": "ordre", "channel": "api", "firstName": "John", "lastName": "Doe", "country": "US", "itemsCount": 1, "createdAt": "10/04/2025 11:05:09", "updatedAt": "10/04/2025 14:05:10", "orderedAt": "2025-04-10T11:05:07+00:00", "customerReferenceId": "CUST-456" }, // Flere ordrer... ]}

Paginering

Søgeordrer-endpointet understøtter sideinddeling, så du nemt kan håndtere store mængder resultater:

# Første side (50 elementer)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": ["afsendt"], "limit": 50, "offset": 0}'# Side to (de næste 50 elementer)curl --location 'https://api.partner-connect.io/api/{partner-prefix}/search' \--header 'Content-Type: application/json' \--header 'X-API-KEY: din-nøgle:dit-secret' \--data '{ "fulfillmentStatus": ["shipped"], "limit": 50, "offset": 50}'

Typiske søgesituationer

  1. Ordrer efter status:

    { "fulfillmentStatus": ["oprettet", "trykt"] }

  2. Ordrer efter dato:

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

  3. Ordrer fordelt på lande:

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

  4. Kombinerede kriterier:

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

Typiske udfordringer

  1. Ingen resultater: Tjek om dine søgekriterier er for snævre.

  2. For mange resultater: Brug paginering og/eller flere filtre for at gøre din søgning mere præcis.

  3. Ugyldigt format: Sørg for, at datoformater følger ISO 8601 (ÅÅÅÅ-MM-DDTT:MM:SS+00:00).

Sådan forbinder du skabeloner med API-endpoints

Når du sender ordrer via API, skal du ofte omdanne data mellem dit eget format og GelatoConnects format. Skabeloner klarer den omstilling, men du skal selv koble din skabelon til API-endpointet, før den bliver brugt.

Sådan kobler du en skabelon til et ordreafleveringspunkt:

  1. Gå til din connector-liste, og klik på Rediger-linket ved siden af submit order-endpointet.

  2. På siden til opsætning af endpoint skal du finde afsnittet Endpoint-skabelon

  3. Vælg din skabelon til ordreafgivelse i rullemenuen

  4. Klik på knappen Angiv endpoint øverst til højre på siden

  5. Klik på Gem ændringer øverst til højre for at gemme din opsætning

Når du har fulgt disse trin, vil alle ordreindsendelser til dette endpoint bruge din skabelon til at omdanne dataene, før de behandles. Sådan sikrer du, at dit systems format bliver omdannet korrekt til det format, GelatoConnect forventer.

Uden denne konfiguration bliver din skabelon ikke brugt, selvom den findes og er korrekt designet. Det kan betyde, at din ordre ikke bliver godkendt, hvis dit dataformat ikke passer præcis til GelatoConnects krav.

Bedste tips til integration

Når du integrerer med Order API-endpoints, så husk disse gode råd:

1. Gem storede ordre-ID'er

Gem altid både dit ordre-referencenummer og det Gelato-ordrenummer, du får i svaret. Så bliver det nemmere at holde styr på og finde dine ordrer i begge systemer.

2. Håndter fejl på en god måde

Sørg for at håndtere fejl korrekt ved hvert API-kald. Læs fejlbeskeden fra svaret, så du kan give brugerne brugbar feedback og sætte passende løsninger i gang.

Hvis du vil have tips til, hvordan du håndterer fejl på en smart måde, så tjek afsnittet "Best practices for fejlhåndtering" i Order Management API Documentation.

3. Gør det ensartet

Opret unikke ordre-referencer for hver ordre, og brug preventDuplicate-parameteren for at sikre, at en ordre ikke bliver sendt to gange – selv hvis der opstår netværksproblemer og du prøver igen.

4. Brug Webhook-notifikationer

I stedet for at tjekke ordrestatus hele tiden, kan du sætte Webhook-notifikationer op og få besked med det samme, når der sker ændringer i ordrestatus.

5. Tjek dine data, før du sender dem

Tjek dine ordredata igennem, før du sender dem til API'et – så fanger du nemt fejl og giver brugerne en bedre oplevelse.

6. Tilføj genforsøg

Tilføj genforsøg med eksponentiel ventetid ved midlertidige fejl – især hvis du får en rate limit (429) besked.

Hvis du vil vide mere om, hvordan du bruger exponential backoff og jitter, kan du tjekke afsnittet "Rate Limit Best Practices" i Order Management API Documentation eller læse AWS’ blogindlæg om exponential backoff og jitter.

7. Gør dine søgninger skarpere

Vær præcis med dine søgekriterier, så du får færre resultater og hurtigere svar.

8. Gem reference-data i cache

Gem produkt-UID'er og andre referenceoplysninger, så du ikke behøver at lave så mange API-kald.

Konklusion

GelatoConnect Order API giver dig stærke værktøjer til at styre hele ordreprocessen. Når du lærer at bruge disse værktøjer rigtigt, kan du nemt få dine systemer til at spille sammen med GelatoConnect.

Hvis du vil have flere detaljer, kan du tjekke Order Management API Documentation.

Relaterede artikler
[Ordremodtagelse – GCW] Dokumentation for Order Management API
[Ordreindtag – GCW] Brug af kundens produkter vs. ProductUID i API-ordrer
[Order Intake - GCW] Sådan bruger du de kunde-uafhængige Order API-endpoints
[Ordremodtagelse – GCW] Begreber og vilkår for ordremodtagelse
[Ordremodtagelse – GCW] GelatoConnect API-grundlæggende
Besvarede dette dit spørgsmål?