Hoppa till huvudinnehåll

[Orderingång - GCW] Arbeta med Order API-slutpunkter

T
Skrivet av Toby Dawson
Uppdaterad för mer än 3 veckor sedan

Den här guiden ger praktiska instruktioner och exempel för att arbeta med GelatoConnects Order API-slutpunkter. Vi går igenom hur du skickar in beställningar, avbryter beställningar, uppdaterar leveransinformation, hämtar beställningsdetaljer och söker efter beställningar med hjälp av API:et.

Förutsättningar

Innan du arbetar med dessa endpoints, se till att du har:

  • Din API-nyckel och hemlighet (tillhandahålls när du konfigurerar en anslutning för din kund)

  • Bas-URL för dina API-slutpunkter

  • Grundläggande förståelse för att göra HTTP-förfrågningar med curl eller ditt föredragna verktyg

Skicka beställning

Slutpunkten Submit Order låter dig skapa en ny beställning i GelatoConnect.

Slutpunkt: POST /{submitOrderUrl}

Förfrågningsexempel

# Grundläggande orderläggningcurl --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-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]", \"telefon\": \"123-456-7890\" }, \"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", \"antal\": 1, "filer": [ { \"type\": \"default\", \"url\": \"https://example.com/files/printfile.pdf\" } ] } ]}'

Svarsexempel

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

Så använder du kundprodukter

Istället för att ange ett productUid kan du använda kundprodukter med productName och 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\": \"order\", "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", "productName": "Visitkort", "productVariant": { \"Storlek\": \"Standard\", "Papper": "Premium matt", "Färg": "Färgtryck på båda sidor" }, "quantity": 100, \"files\": [ { "type": "framsida", \"url\": \"https://example.com/files/front.pdf\" }, { "type": "tillbaka", \"url\": \"https://example.com/files/back.pdf\" } ] } ]}'"

Internationella beställningar

För internationella beställningar, ange butikspriser för tullhandlingar:

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-gsm-uncoated_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" } ] } ]}'

Vanliga problem

  1. Saknade obligatoriska fält: Se till att alla obligatoriska fält finns med i din förfrågan.

  2. Ogiltiga filadresser: Se till att dina filadresser är öppna för alla att komma åt.

  3. Okänt produkt-UID: Kolla att produktens UID finns eller använd kundens produkter.

  4. Duplicerat orderreferens-ID: Använd unika orderreferens-ID för varje beställning.

Avbryt beställning

Med Avbryt order-slutpunkten kan du stoppa produktionen och leveransen av en order som ännu inte har skickats.

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

Exempel på förfrågan

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

Exempelsvar

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

Vanliga problem

  1. Order Already Shipped: Beställningar som redan har skickats kan inte avbokas.

  2. Beställning hittades inte: Kontrollera att beställnings-ID eller referens-ID är korrekt.

  3. Problem med inloggning: Dubbelkolla att din API-nyckel och ditt hemliga lösenord är rätt.

Uppdatera försändelse

Med Update Shipment-endpointen kan du ändra fraktsätt eller uppdatera leveransadressen för en order som ännu inte har skickats.

Slutpunkt: POST /{updateShipmentURL}/{orderId}

Förfrågningsexempel

# Uppdatera leveransuppgiftercurl --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\": \"456 Park Ave\", "city": "New York", "postCode": "10022", "state": "NY", \"email\": \"[email protected]\", \"phone\": \"987-654-3210\" }}'# Uppdatera bara fraktsättcurl --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"}'

Exempelsvar

{ "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]", \"telefon\": \"987-654-3210\" }, \"shipment\": { \"shipmentMethodUid\": \"fed_ex_2_day\", "shipmentMethodName": "FedEx 2Day", \"fulfillmentCountry\": \"US\", \"fulfillmentFacilityId\": \"db0622e7-d7af-4453-b39f-cdf1b67f3daa\", "packageCount": 1, "initialMinDeliveryDate": "2025-04-15", "initialMaxDeliveryDate": "2025-04-15", "serviceType": "normal" }}

Vanliga problem

  1. Beställningen har redan skickats: Du kan tyvärr inte ändra leveransuppgifter för beställningar som redan är på väg.

  2. Saknade obligatoriska fält: Se till att alla obligatoriska fält är ifyllda i leveransadressen.

  3. Ogiltig leveransmetod: Kontrollera att leveransmetodens UID är giltig.

  4. Beställning hittades inte: Dubbelkolla att order-ID eller referens-ID är rätt.

Hämta order

Slutpunkten Hämta order låter dig hämta detaljerad information om en befintlig order.

Slutpunkt: POST /{getOrderURL}/{orderId}

Förfrågningsexempel

# Hämta order 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'# Hämta din beställning med ditt orderreferensnummercurl --location --request GET 'https://api.partner-connect.io/api/{partner-prefix}/YOUR-ORDER-123' \--header 'X-API-KEY: your-key:your-secret'

Exempel på svar

Svaret innehåller detaljerad information om beställningen, inklusive:

  • Orderdetaljer (ID, referens, status, tidsstämplar)

  • Leveransadress

  • Beställda produkter

  • Leveransinformation

  • Ekonomisk information

På grund av svarets längd, se API-dokumentationen för den fullständiga svarsstrukturen.

Använda svarsdata

Svaret på Hämta order ger dig värdefull information som du kan använda för att:

  1. Visa orderstatus: Låt kunderna se hur det går med deras beställningar.

  2. Spåra leveranser: Hämta spårningsinformation för att följa dina leveranser.

  3. Dubbelkolla orderdetaljer: Se till att allt stämmer innan du går vidare.

  4. Analysera orderhistorik: Skapa rapporter och insikter utifrån dina orderdata.

Vanliga problem

  1. Ordern hittades inte: Dubbelkolla att order-ID eller referens-ID är rätt.

  2. Problem med inloggning: Dubbelkolla att din API-nyckel och ditt hemliga lösenord är rätt.

Sök ordrar

Slutpunkten Sök ordrar låter dig hämta en lista över ordrar baserat på specifika kriterier.

Slutpunkt: POST /{searchOrdersURL}

Exempel på förfrågan

# Sök efter leveransstatuscurl --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": ["skickad", "levererad"]}'# Sök efter datumintervallcurl --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": "2025-01-01T00:00:00+00:00", "endDate": "2025-04-13T23:59:59+00:00"}'"# Sök med orderreferens-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ök med sidindelningcurl --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": ["skapad", "tryckt"], "limit": 50, "offset": 0}'"

Svarsexempel

{ "orders": [ { \"id\": \"9f9ff09f-5891-4d3d-be35-9b302db835a1\", "clientId": "ddb4371a-ad83-4f68-b99d-6b48c7eff366", \"orderReferenceId\": \"YOUR-ORDER-123\", "fulfillmentStatus": "skickad", "financialStatus": "betald", \"currency\": \"USD\", "totalInclVat": "33,45", "orderType": "order", \"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" }, // Fler beställningar... ]}

Sidindelning

Sökorder-endpointen har sidindelning så att du enkelt kan hantera stora mängder resultat:

# Första sidan (50 produkter)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": ["skickad"], "gräns": 50, "offset": 0}'# Sida två (nästa 50 produkter)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\": [\"shipped\"], "limit": 50, \"offset\": 50}'

Vanliga söksituationer

  1. Beställningar efter status:

    { "fulfillmentStatus": ["skapad", "tryckt"] }

  2. Beställningar efter datumintervall:

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

  3. Beställningar per land:

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

  4. Kombinera kriterier:

    { "fulfillmentStatus": ["skickad"], "countries": ["US"], \"startDate\": \"2025-04-01T00:00:00+00:00\"}

Vanliga problem

  1. Inga resultat: Kolla så att du inte har gjort din sökning för snäv.

  2. För många resultat: Använd sidnumrering och/eller ytterligare filter för att begränsa din sökning.

  3. Ogiltigt format: Se till att datumformatet följer ISO 8601 (ÅÅÅÅ-MM-DDTT:MM:SS+00:00).

Koppla mallar till API-endpoints

När du skickar in beställningar via API behöver du ofta omvandla data mellan ditt format och GelatoConnects format. Mallar fixar den omvandlingen, men du måste själv koppla din mall till API-endpointen för att det ska fungera.

Så här kopplar du en mall till en orderinlämningspunkt:

  1. Gå till din connector-lista och klicka på länken Redigera bredvid submit order-endpunkten.

  2. På konfigurationssidan för slutpunkten, hitta avsnittet Slutpunktsmall

  3. Välj din orderbekräftelsemall från rullgardinsmenyn

  4. Klicka på knappen Ställ in slutpunkt uppe till höger på sidan

  5. Klicka på Spara ändringar uppe till höger för att spara dina inställningar

När du har slutfört dessa steg kommer alla orderförfrågningar som skickas till denna endpoint att använda din mall för att omvandla data innan bearbetning. Detta säkerställer att formatet från ditt system korrekt konverteras till det format som GelatoConnect förväntar sig.

Utan denna konfiguration kommer din mall inte att tillämpas även om den existerar och är korrekt utformad, vilket kan leda till att ordern inte valideras om ditt dataformat inte exakt matchar kraven från GelatoConnect.

Bästa sättet att integrera

När du integrerar med Order API-slutpunkterna, tänk på dessa bästa metoder:

1. Spara order-ID:n

Spara alltid både ditt orderreferens-ID och Gelato-order-ID:t som du får i svaret. Då blir det mycket enklare att hålla koll på och hitta dina beställningar i båda systemen.

2. Hantera misstag på ett smidigt sätt

Se till att hantera fel på rätt sätt vid varje API-anrop. Läs in felmeddelandet från svaret så att du kan ge användarna tydlig feedback och bygga in smarta sätt att återhämta sig om något går snett.

För tips om hur du bygger riktigt bra felhantering, kolla in avsnittet "Bästa praxis för felhantering" i Order Management API Documentation.

3. Implementera idempotens

Skapa unika orderreferens-ID för varje order och använd preventDuplicate-parametern för att vara säker på att en order inte skickas in två gånger, även om det skulle bli problem med nätverket och du behöver försöka igen.

4. Använd Webhook-notiser

Slipp att sitta och uppdatera sidan för att se om orderstatusen har ändrats – ställ in Webhook-notiser så får du uppdateringar direkt när något händer.

5. Dubbelkolla dina uppgifter innan du skickar in dem

Validera orderdata på din sida innan du skickar den till API:et för att fånga uppenbara fel och förbättra användarupplevelsen.

6. Implementera återförsökslogik

Lägg till en funktion som försöker igen automatiskt med ökande väntetid vid tillfälliga fel, särskilt om du får ett felmeddelande om att du nått gränsen för antal försök (429).

För implementeringsdetaljer om exponentiell backoff och jitter, se avsnittet "Bästa praxis för hastighetsbegränsning" i dokumentationen för Order Management API eller AWS blogginlägg om exponentiell backoff och jitter.

7. Finslipa dina sökningar

Var tydlig med dina sökkriterier så får du färre träffar och snabbare resultat.

8. Spara referensdata i cache

Spara produkt-ID:n och annan referensdata så du slipper göra onödigt många API-anrop.

Sammanfattning

GelatoConnect Order API ger dig smarta verktyg för att hantera hela orderflödet. När du lär dig använda dessa endpoints på rätt sätt kan du enkelt koppla ihop dina system med GelatoConnect och få allt att flyta på smidigt.

För mer detaljerad information, kolla in Order Management API Documentation.

Relaterade artiklar
[Orderingång - GCW] Dokumentation för API för orderhantering
[Orderingång - GCW] Använda kundprodukter vs. ProductUID i API-beställningar
[Orderingång - GCW] Skapa mallar för orderingång
[Order Intake - GCW] Så här använder du de kundneutrala Order API-endpunkterna
[Orderingång - GCW] GelatoConnect API-grunder
Fick du svar på din fråga?