Gå til hovedinnhold

[Ordremottak – GCW] Slik jobber du med Order API-endepunkter

T
Skrevet av Toby Dawson
Oppdatert for over 3 uker siden

Denne guiden gir deg praktiske instruksjoner og eksempler på hvordan du bruker Order API-endepunktene til GelatoConnect. Her viser vi deg hvordan du sender inn bestillinger, kansellerer bestillinger, oppdaterer leveringsinformasjon, henter detaljer om bestillinger og søker etter bestillinger med API-et.

Forutsetninger

Før du begynner å bruke disse endepunktene, sørg for at du har:

  • Din API-nøkkel og hemmelige kode (du får dem når du setter opp en kobling for kunden din)

  • Grunnadressen for API-endepunktene dine

  • Grunnleggende forståelse av hvordan du sender HTTP-forespørsler med curl eller et annet verktøy du liker å bruke

Send inn bestilling

Submit Order-endepunktet lar deg opprette en ny ordre i GelatoConnect.

Endepunkt: POST /{submitOrderUrl}

Eksempel på forespørsel

# Slik legger du inn en bestillingcurl --location 'https://api.partner-connect.io/api/{partner-prefix}/order' \--header «Content-Type: application/json» \--header 'X-API-KEY: din-nøkkel:din-hemmelighet' \--data '{ "orderReferenceId": "DIN-BESTILLING-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]", "telefon": "123-456-7890" }, "items": [ { "itemReferenceId": "ITEM-001", "productUid": "flat_product_pf_a4_pt_200-g/m²-ubestrøket_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": "DIN-BESTILLING-123", "createdAt": "13/04/2025, 10:23:28"}

Bruke personlig tilpassede produkter

I stedet for å bruke en productUid, kan du bruke personlig tilpassede 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: din-nøkkel:din-hemmelighet' \--data '{ "orderReferenceId": "DIN-BESTILLING-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" }, "elementer": [ { "itemReferenceId": "ITEM-001", "productName": "Visittkort", "productVariant": { "Size": "Standard", "Paper": "Premium matt", "Farge": "Fullfarge på begge sider" }, "quantity": 100, "filer": [ { "type": "forside", "url": "https://example.com/files/front.pdf" }, { "type": "bakside", "url": "https://example.com/files/back.pdf" } ] } ]}'

Internasjonale bestillinger

For internasjonale bestillinger, oppgi utsalgsprisene til tollpapirene:

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": "ordre", "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-ubestrøket_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" } ] } ]}'

Vanlige utfordringer

  1. Mangler nødvendige felt: Husk å fylle ut alle obligatoriske felt i forespørselen din.

  2. Ugyldige filadresser: Sørg for at filadressene dine er tilgjengelige for alle.

  3. Ukjent produkt-UID: Sjekk at produktets UID finnes, eller bruk kundens produkter.

  4. Duplikat ordreferanse-ID: Bruk en unik ordreferanse-ID for hver bestilling.

Avbryt bestillingen

Med Avbryt ordre-endepunktet kan du stanse produksjon og utsending for en ordre som ennå ikke er sendt.

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

Eksempel på forespørsel

# Avbryt med Gelato-bestillings-IDcurl --location --request POST 'https://api.partner-connect.io/api/{partner-prefix}/32884a3e-bd09-42be-8225-c5cea7d24611/cancel' \--header 'X-API-KEY: din-nøkkel:din-hemmelighet'# Avbryt med din ordre-IDcurl --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": "OK"}

Vanlige utfordringer

  1. Bestillingen er allerede sendt: Bestillinger som er sendt kan ikke avbestilles.

  2. Fant ikke bestillingen: Sjekk at ordre-ID eller referanse-ID er riktig.

  3. Problemer med innlogging: Sjekk at API-nøkkelen og hemmeligheten din er riktige.

Oppdater forsendelse

Endepunktet for oppdatering av forsendelse lar deg endre fraktmetode eller oppdatere leveringsadressen for en ordre som ennå ikke er sendt.

Endepunkt: POST /{updateShipmentURL}/{orderId}

Eksempel på forespørsel

# Oppdater leveringsdetaljercurl --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": "Parkveien 456", "city": "New York", "postCode": "10022", "state": "NY", "email": "[email protected]", "phone": "987-654-3210" }}'# Oppdater bare fraktmetodecurl --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": "456 Park Ave", "city": "New York", "postCode": "10022", "state": "NY", "email": "[email protected]", "phone": "987-654-3210" }, "forsendelse": { "shipmentMethodUid": "fed_ex_2_day", "shipmentMethodName": "FedEx 2-dagers", "fulfillmentCountry": "US", "fulfillmentFacilityId": "db0622e7-d7af-4453-b39f-cdf1b67f3daa", "packageCount": 1, "initialMinDeliveryDate": "15.04.2025", "initialMaxDeliveryDate": "15.04.2025", "serviceType": "vanlig" }}

Vanlige utfordringer

  1. Bestillingen er allerede sendt: Du kan ikke endre leveringsdetaljer for bestillinger som er sendt.

  2. Mangler nødvendige felt: Husk å fylle ut alle påkrevde felt i leveringsadressen.

  3. Ugyldig fraktmetode: Sjekk at fraktmetode-UID er gyldig.

  4. Fant ikke bestillingen: Sjekk at bestillings-ID eller referanse-ID er riktig.

Hent bestilling

Get Order-endepunktet lar deg hente detaljert informasjon om en eksisterende bestilling.

Endepunkt: POST /{getOrderURL}/{orderId}

Eksempel på forespørsel

# Hent ordre med Gelato ordre-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'# Finn ordren din med referanse-IDcurl --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 inneholder detaljerte opplysninger om bestillingen, blant annet:

  • Ordredetaljer (ID, referanse, status, tidspunkter)

  • Leveringsadresse

  • Bestilte varer

  • Fraktinformasjon

  • Finansiell informasjon

Siden svaret er langt, finner du hele svarstrukturen i API-dokumentasjonen.

Slik bruker du responsdataene

Get Order-svaret gir deg nyttig informasjon du kan bruke til å:

  1. Vis ordrestatus: Vis kundene hvordan det går med bestillingene deres.

  2. Spor forsendelser: Hent ut sporingsinformasjon for å følge forsendelsen.

  3. Sjekk ordreopplysningene: Sørg for at alt stemmer før du går videre.

  4. Analyser ordreoversikt: Lag rapporter og analyser basert på ordredata.

Vanlige utfordringer

  1. Fant ikke bestillingen: Sjekk at ordre-ID eller referanse-ID er riktig.

  2. Problemer med innlogging: Sjekk at API-nøkkelen og hemmeligheten din er riktige.

Søk etter bestillinger

Med Search Orders-endepunktet kan du hente en oversikt over bestillinger basert på bestemte kriterier.

Endepunkt: POST /{searchOrdersURL}

Eksempel på forespørsel

# Søk etter produksjonsstatuscurl --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øk etter tidsperiodecurl --location 'https://api.partner-connect.io/api/{partner-prefix}/search' \--header 'Content-Type: application/json' \--header 'X-API-KEY: din-nøkkel:din-hemmelighet' \--data '{ "startDate": "2025-01-01T00:00:00+00:00", "endDate": "2025-04-13T23:59:59+00:00"}'# Søk med ordre-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": "DIN-BESTILLING-123"}'# Søk med pagineringcurl --location 'https://api.partner-connect.io/api/{partner-prefix}/search' \--header 'Content-Type: application/json' \--header 'X-API-KEY: din-nøkkel:din-hemmelighet' \--data '{ "fulfillmentStatus": ["opprettet", "trykket"], "limit": 50, "offset": 0}'

Eksempel på svar

{ "orders": [ { "id": "9f9ff09f-5891-4d3d-be35-9b302db835a1", "clientId": "ddb4371a-ad83-4f68-b99d-6b48c7eff366", "orderReferenceId": "DIN-BESTILLING-123", "fulfillmentStatus": "sendt", "financialStatus": "betalt", "currency": "USD", "totalInclVat": "33,45", "orderType": "ordre", "channel": "api", "firstName": "John", "lastName": "Doe", "country": "US", "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" }, // Flere bestillinger... ]}

Paginering

Søk etter ordre-endepunktet støtter paginering, så du enkelt kan håndtere store mengder 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: din-nøkkel:din-hemmelighet' \--data '{ "fulfillmentStatus": ["sendt"], "grense": 50, "offset": 0}'# Side to (neste 50 elementer)curl --location 'https://api.partner-connect.io/api/{partner-prefix}/search' \--header 'Content-Type: application/json' \--header 'X-API-KEY: din-nøkkel:din-hemmelighet' \--data '{ "fulfillmentStatus": ["sendt"], "limit": 50, "offset": 50}'

Vanlige søkesituasjoner

  1. Bestillinger etter status:

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

  2. Bestillinger etter datoperiode:

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

  3. Bestillinger per land:

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

  4. Kombinere kriterier:

    { "fulfillmentStatus": ["sendt"], "countries": ["US"], "startDate": "01.04.2025 00:00"}

Vanlige utfordringer

  1. Ingen resultater: Sjekk at søkekriteriene dine ikke er for strenge.

  2. For mange resultater: Bruk paginering og/eller flere filtre for å gjøre søket ditt mer presist.

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

Koble maler til API-endepunkter

Når du sender inn bestillinger via API, må du ofte endre data fra ditt eget format til GelatoConnect sitt format. Maler tar seg av denne overgangen, men du må selv koble malen til API-endepunktet for at den skal brukes.

Slik kobler du en mal til et innsending-endepunkt for bestillinger:

  1. Gå til listen over koblinger og klikk på Rediger-lenken ved siden av send inn bestilling-endepunktet.

  2. På siden for endepunktoppsett finner du delen Endepunktmal

  3. Velg mal for innsending av bestilling fra rullegardinmenyen

  4. Klikk på Angi endepunkt-knappen øverst til høyre på siden

  5. Klikk på Lagre endringer oppe til høyre for å ta i bruk oppsettet ditt

Når du har gjort disse stegene, vil alle ordreinnsendinger til dette endepunktet bruke malen din for å tilpasse dataene før de behandles. Da blir formatet fra systemet ditt riktig omgjort til det GelatoConnect forventer.

Uten denne konfigurasjonen blir ikke malen din brukt, selv om den finnes og er riktig utformet. Det kan føre til at bestillingen ikke blir godkjent hvis dataformatet ditt ikke stemmer helt med kravene til GelatoConnect.

Beste praksis for integrasjon

Når du integrerer med Order API-endepunktene, bør du ha disse beste praksisene i bakhodet:

1. Lagre ordre-ID-er

Husk å lagre både din egen ordre-ID og Gelato sin ordre-ID som du får i svaret. Da blir det enklere å følge opp og finne igjen ordre i begge systemene.

2. Håndter feil på en god måte

Sørg for god feilhåndtering for hver API-forespørsel. Les feilmeldingen fra svaret slik at brukerne får nyttig tilbakemelding, og lag gode løsninger for å rette opp feil.

For tips om hvordan du kan håndtere feil på en god måte, se avsnittet «Beste praksis for feilbehandling» i Order Management API Documentation.

3. Gjør handlingen idempotent

Lag unike referanse-ID-er for hver bestilling, og bruk preventDuplicate-parameteren for å være sikker på at en bestilling ikke sendes inn to ganger selv om det oppstår nettverksproblemer og du må prøve på nytt.

4. Bruk Webhook-varsler

I stedet for å sjekke ordrestatus hele tiden, kan du sette opp Webhook-varsler og få oppdateringer med en gang noe endrer seg.

5. Sjekk dataene før du sender inn

Sjekk bestillingsdataene dine før du sender dem til API-et, så unngår du åpenbare feil og gir en bedre opplevelse for brukeren.

6. Legg inn en løsning for å prøve igjen

Legg til ny forsøk-logikk med gradvis økende ventetid for midlertidige feil, spesielt ved svar med grense for antall forespørsler (429).

For detaljer om hvordan du implementerer eksponentiell tilbakeholdelse og variasjon, kan du se avsnittet «Rate Limit Best Practices» i Order Management API Documentation eller AWS-blogginnlegget om eksponentiell tilbakeholdelse og variasjon.

7. Gjør søkene dine smartere

Vær tydelig med søkekriteriene for å få færre treff og bedre ytelse.

8. Hurtiglager referansedata

Lagre produkt-UID-er og annen referansedata for å slippe å gjøre så mange API-kall.

Oppsummering

GelatoConnect Order API gir deg en kraftfull verktøykasse for å håndtere hele bestillingsprosessen. Når du lærer deg å bruke disse endepunktene effektivt, kan du skape en sømløs kobling mellom dine systemer og GelatoConnect.

For mer detaljert informasjon, se Order Management API Documentation.

Relaterte artikler
[Ordremottak – GCW] API-dokumentasjon for ordrebehandling
[Ordreinngang – GCW] Bruke kundeprodukter vs. ProductUID i API-ordre
[Order Intake – GCW] Slik bruker du kundeuavhengige API-endepunkter for ordre
[Order Intake – GCW] Finn ut hvordan du tar imot bestillinger
[Ordremottak – GCW] GelatoConnect API-grunnleggende
Svarte dette på spørsmålet?