Introduktion
Välkommen till dokumentationen för Order Management API. Med det här API:et kan du lägga in beställningar, avbryta beställningar, hämta orderdetaljer, söka efter ordrar och uppdatera leveransadresser eller leveranssätt i GelatoConnect-systemet. API:et är uppbyggt kring REST-principer och använder vanliga HTTPS-metoder för att hantera resurser. Alla svar returneras i JSON-format, även felmeddelanden.
Inloggning
Alla samtal till Order Management API kräver att du autentiserar dig med en giltig API-nyckel och hemlighet som anges i samtalets header. All kommunikation måste ske via HTTPS – om du försöker använda vanlig HTTP kommer det inte att fungera.
Inloggningsmetod
Lägg till
X-API-KEY-huvudet i din förfråganAnge värdet med formatet:
key:secret
Exempel:
X-API-KEY: your-key:your-secret
Din unika API-nyckel och hemlighet får du när du sätter upp en connector för din kund.
Begränsningar för hur ofta du kan använda REST
API:et har en gräns för hur många förfrågningar du eller din klient kan göra under en viss tid. Alla förfrågningar räknas mot din personliga gräns på 100 förfrågningar per sekund.
Varför det finns gränser för hur mycket du kan använda REST
Begränsningar för hur ofta du kan använda tjänsten fyller flera viktiga funktioner:
Skydda mot att API:et används fel eller missbrukas
Vi ser till att alla får en rättvis chans
Så undviker du avbrott när det blir mycket trafik
Försök igen-automatik vid för många förfrågningar
Om du överskrider API:ets gräns för antal anrop får du en 429-statuskod. För att undvika onödiga problem med ditt arbete, testa de här sätten att försöka igen:
Försök igen: Misslyckade förfrågningar hanteras automatiskt genom att försöka på nytt. Se till att din app försöker igen automatiskt vid alla API-anrop.
Exponential backoff: Vänta lite längre för varje gång du försöker igen efter ett fel. Sätt en gräns för hur länge du kan vänta och hur många gånger du försöker, beroende på vad du gör.
Jitter: Lägg till en slumpmässig fördröjning innan du försöker igen, så att inte alla skickar sina förfrågningar samtidigt. Det gör att belastningen sprids ut och minskar risken för att allt krockar på en gång.
Vill du veta mer om hur du kan försöka igen? Kolla in det här:
Svarskoder
Order Management API använder vanliga HTTP-svarskoder för att visa om en begäran lyckades eller inte:
2xx-koder: Visar att allt gick som det skulle
4xx-koder: Visar att det är fel på strukturen eller datan i din förfrågan (till exempel om något viktigt saknas eller om vi inte hittar din order)
5xx-koder: Visar att det är fel på servern (det händer sällan)
API-slutpunkter
Skicka beställning
Skicka in en beställning med ett enda klick.
Slutpunkt: POST /{submitOrderUrl}
Bas-URL och specifik slutpunkt kommer att tillhandahållas under konfigurationen av anslutningen.
Begäran format
{ "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" } ] } ]}Exempel på curl-begäran (klicka här)
Exempel på curl-begäran (klicka här)
curl --location --request POST 'https://api.partner-connect.io/api/your-partner-prefix/order' \--header 'Content-Type: application/json' \--header 'X-API-KEY: your-key:your-secret' \--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" } ] } ]}'Viktiga saker att tänka på när du skickar en förfrågan
Parameter | Typ | Obligatoriskt | Beskrivning |
orderReferenceId | sträng | Obligatorisk | Ditt interna order-ID |
orderTyp | sträng | Valfritt | Type of order: "order" (default) or "draft" |
valuta | sträng | Obligatoriskt | Valuta för beställningen (ISO-kod) |
valuta för återförsäljning | sträng | Valfritt | Valuta som används för butikspriser (vid gränsöverskridande beställningar) |
butikspris för frakt inkl. moms | nummer | Valfritt | Fraktpris exklusive moms (trots parameternamnet) |
shipmentMethodUid | sträng | Valfritt | Fraktsätt att använda, kan separeras med kommatecken |
leveransadress | sak | Obligatoriskt | Kundens leveransadressuppgifter |
föremål | array | Obligatoriskt | Lista över produkter att beställa |
förhindra dubbletter | boolesk | Valfritt | Om det här är inställt på sant, förhindras att dubblettbeställningar skapas med samma orderReferenceId. Om en dubblett upptäcks får du ett felmeddelande istället för att en ny beställning skapas. |
"packagingInstructions": [ | array | Valfritt | Array med förpackningsinstruktionsobjekt |
Produktinställningar
Parameter | Typ | Obligatoriskt | Beskrivning |
itemReferenceId | sträng | Obligatoriskt | Ditt interna artikelnummer |
productUid | sträng | Obligatoriskt* | GelatoConnect produktidentifierare (*Antingen productUid ELLER productName+productVariant krävs) |
produktnamn | sträng | Obligatoriskt* | Namn på kundens produkt (*Antingen productUid ELLER productName+productVariant krävs) |
produktvariant | sak | Obligatoriskt* | Variantdetaljer för kundprodukten (*Obligatoriskt när du använder productName) |
antal | nummer | Obligatoriskt | Antal produkter du vill beställa |
detaljpris inkl. moms | nummer | Valfritt | Pris exklusive moms (även om parametern heter så) |
filer | array | Obligatorisk | Lista över tryckfiler för produkten |
customTrim | objekt | Valfritt | Anpassade måttdimensioner för produkten |
Filinställningar
Parameter | Typ | Obligatorisk | Beskrivning |
typ | sträng | Obligatorisk | Typ av fil. Hitta en lista med alternativ i tabellen nedan. |
url | sträng | Obligatoriskt | Offentligt tillgänglig länk till tryckfilen |
Filtyp
Parameter | Beskrivning |
standard | Designen trycks på produktens primära område. För kläder är det framsidan, medan för vikta kort är det omslaget+baksidorna.
Om du laddar upp en PDF med flera sidor, se till att antalet sidor stämmer överens med antalet tryckytor – varje sida används för att trycka på en yta. |
framsida | Skriv ut filen på framsidan av produkten. |
tillbaka | Skriv ut filen på baksidan av produkten. |
omslag | Filen för ett bokomslag |
insida av kragen | Skriv ut filen på insidan av tröjans nacke. |
halsringning | Skriv ut filen på utsidan av halsen på plagget. |
vänster ärm | Skriv ut filen på vänster ärm av plagget. |
höger ärm | Skriv ut filen på höger ärm på plagget. |
inuti | Skriv ut filen på de inre sidorna. |
vänster bröstbroderi | Brodera filen på vänster bröst på plagget. |
broderi mitt på bröstet | Brodera filen på mitten av framsidan på plagget. |
bröst-stor-broderi | Brodera filen på framsidan av klädesplagget. |
vänsterärm-broderi | Brodera filen på vänster ärm på plagget. |
brodyr på höger ärm | Brodera filen på höger ärm på plagget. |
vänster handled-broderi | Brodera filen på vänster handled på klädesplagget. |
broderi på höger handled | Brodera filen på höger handled på klädesplagget. |
Flexibla filformat för workflow-aktiverade produkter
För produkter som är aktiverade för [nt]workflow builder[/nt], kan du använda valfria anpassade filtypsnamn i fältet type i files-arrayen. Denna funktion förenklar API-integrationer genom att ta bort behovet av att mappa filer till fördefinierade typer.
Nyckelpunkter:
Du kan namnge filtyper fritt, som
default_1,default_2,cover_front,inside_page, osv.Tillåtna tecken: bokstäver (A–Z, a–z), siffror (0–9), understreck (_), punkter (.) och bindestreck (-)
Maximal längd: 100 tecken
Filtypsuniciteten gäller fortfarande - varje
type-värde måste vara unikt inom sammafiles-array
Exempel på användning:
{ "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" } ] } ]}
Anpassade trimningsparametrar
Parameter | Typ | Obligatoriskt | Beskrivning |
breddMm | nummer | Obligatoriskt | Beskärningsbredd i millimeter (*Krävs när du använder customTrim) |
höjdMm | nummer | Obligatoriskt | Beskärhöjd i millimeter (*Krävs när du använder customTrim) |
Parametrar för förpackningsinstruktioner
Parameter | Typ | Obligatoriskt | Beskrivning |
"packageItems": [ | array | Obligatoriskt | Artiklar att inkludera i detta paket |
orderItemReferenceId | sträng | Obligatoriskt | Referens till orderartikeln (måste matcha itemReferenceId) |
antal | nummer | Obligatoriskt | Antal av artikeln i detta paket |
"packingSlip": { | objekt | Valfritt | Konfiguration av följesedel |
fileUrl | sträng | Obligatoriskt | URL till PDF-följesedeln |
GelatoConnect kommer att ladda ner och lagra din följesedel i PDF-format för att säkerställa att den förblir tillgänglig under packningsprocessen, även om den ursprungliga URL:en upphör att gälla.
Exempel på användning:
{ "orderReferenceId": "ORDER-12345", "orderType": "order", "currency": "USD", "shippingAddress": {...}, "items": [...], "packagingInstructions": [ { "packageItems": [ { "orderItemReferenceId": "ITEM-001", "quantity": 1 } ], "packingSlip": { "fileUrl": "https://example.com/slip.pdf" } } ]}
Migrering från metadatabaserade följesedlar
För kunder som för närvarande använder metadata för att skicka följesedlar kan du använda mallen nedan för att extrahera följesedlarnas URL:er från metadata och konvertera dem till packagingInstructions-format, vilket säkerställer permanent fillagring av GelatoConnect.
{%- 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 -%}{#-- Utdata uppdaterad JSON --#}{ {%- for key, value in payload.items() %} {%- if key != "metadata" %} "##{{ key }}": ##{{ value | tojson }}, {%- endif %} {%- endfor %} "metadata": ##{{ filtered_metadata | tojson }},förpackningsinstruktioner {paketartiklar {%- for item in payload.get("items") or [] -%} { "orderItemReferenceId": ##{{ item.itemReferenceId|js }}, "quantity": ##{{ item.quantity }} }{% if not loop.last %},{% endif %}{%- endfor %} ],följesedel "fileUrl": "##{{ ns.packing_slip_url }}" } } ]}
Leveransadressparametrar
Parameter | Typ | Obligatoriskt | Beskrivning |
land | sträng | Obligatoriskt | Tvåbokstavslandskod (ISO 3166-1 alpha-2) |
förnamn | sträng | Obligatoriskt | Mottagarens förnamn |
efternamn | sträng | Obligatoriskt | Mottagarens efternamn |
adressrad1 | sträng | Obligatoriskt | Första raden i gatans adress |
Adressrad 2 | sträng | Valfritt | Andra raden i gatuadressen |
stad | sträng | Obligatoriskt | Stadsnamn |
postnummer | sträng | Obligatoriskt | Postnummer |
tillstånd | sträng | Obligatoriskt | Delstat eller provinskod (*Obligatoriskt för adresser i USA, Kanada och Australien) |
e-post | sträng | Obligatoriskt* | Mottagarens e-postadress |
mobil | sträng | Obligatoriskt | Mottagarens telefonnummer med landskod |
företagsnamn | sträng | Valfritt | Företagsnamn (om tillämpligt) |
ärFöretag | boolean | Valfritt | Om adressen är för ett företag |
federalt skatteregistreringsnummer | sträng | Valfritt | Organisationsnummer för företagsadresser |
momsregistreringsnummer | sträng | Valfritt | Skatteregistreringsnummer för företagsadresser |
registreringstillstånd | sträng | Valfritt | Ange var företaget är registrerat |
Särskild information för internationella beställningar
För internationella beställningar, ange produktens butikspris och fraktens butikspris som:
retailCurrency: Valuta som butikspriser anges iretailShippingPriceInclVat: Fraktpris exklusive moms (bortse från parameternamnet)items[i].retailPriceInclVat: Totalt produktpris exklusive moms (bortse från parameternamnet)
Välja en produkt
API:et för orderläggning kan ta emot produktinformation på två sätt:
Använda
productUid:
"productUid": "frame_product_frs_10x10-inch_frc_oak_frm_wood_frp_w13xt22-mm_gt_plexiglass"
Använda
productNameochproductVariant:
"productName": "Framed Poster","productVariant": { "FrameColour": "Black", "PaperSize": "A3"}Använd inte båda metoderna i samma beställning.
Välj leveranssätt
Fältet shipmentMethodUid kan acceptera:
Specifika UID:n för leveransmetoder (t.ex.
fed_ex_2_day)Namn på fraktleverantörer (t.ex.,
DHL)Fraktalternativnivåer (t.ex.
Express)
Flera fraktalternativ kan anges som en kommaseparerad sträng, och systemet kommer att använda det billigaste alternativet.
Svarsformat
{ "id": "32884a3e-bd09-42be-8225-c5cea7d24611", "orderReferenceId": "test", "createdAt": "2024-07-17T10:23:28+00:00"}
Användning av metadata i GelatoConnect
Metadata som tillhandahålls på både order- och artikelnivå i orderförfrågningar kan användas av flera verktyg inom GelatoConnect och även returneras i postbacks. Detta är särskilt värdefullt för dem som behöver upprätthålla datakontinuitet mellan sina system.
Metadata på ordernivå:
Metadata på ordernivå gäller för hela ordern och definieras på den översta nivån i förfrågan.
{ "orderReferenceId": "ORD-12345", "orderType": "order", "currency": "USD", "metadata": [ { "key": "campaign", "value": "summer_promo" }, { "key": "source", "value": "web" } ], "shippingAddress": {...}, "items": [...]}
Metadata på artikelnivå:
Metadata på artikelnivå gäller för specifika artiklar och definieras inom varje artikel i artikelmatrisen.
{ "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": [...] } ]}
Metadata på filnivå:
Metadata på filnivå gäller för specifika filer och definieras inom varje fil i filarrayen. I exemplet nedan används det för att definiera alternativ text för bilden embroideryText som är kopplad till filen.
{ "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" } ] } ] } ]}
Avbryt beställning
Stoppa och avbryt produktions- och leveransprocessen för en beställning. Detta är endast möjligt tills beställningens status ändras till \"skickad\".
Slutpunkt: POST /{orderCancelUrl}
Denna slutpunkt kan acceptera antingen Order-ID (som tillhandahålls i svaret när ordern skickas) eller Order-referens-ID (ditt interna order-ID).
Använda ordernummer
POST /{orderCancelUrl}/32884a3e-bd09-42be-8225-c5cea7d24611/cancelAnvända orderreferens-ID
POST /{orderCancelUrl}/test/cancelSvarsformat
{ "code": 200, "message": "OK"}
Uppdatera leverans
Ändra leveranssätt eller uppdatera leveransadressen tills ordern har ändrat status till \"skickad\".
Slutpunkt: PUT /{updateShipmentURL}
Denna slutpunkt kan acceptera antingen Order-ID eller Order-referens-ID.
Begäransformat
{ "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": "" }}Du kan uppdatera antingen leveransmetoden, leveransadressen eller båda. Minst ett av dessa fält måste inkluderas i begäran.
Förfrågningsparametrar
Parameter | Typ | Obligatoriskt | Beskrivning |
shipmentMethodUid | sträng | Valfritt* | Ny fraktmetod (*Minst en av shipmentMethodUid eller shippingAddress måste anges) |
leveransadress | objekt | Valfritt* | Nya leveransadressuppgifter (*Minst en av shipmentMethodUid eller shippingAddress måste anges) |
Svarsformat
{ "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" }}
Hämta beställning
Hämta information om en befintlig beställning.
Slutpunkt: GET /{getOrderURL}/{order_id}
Du kan använda antingen Gelato-ordernumret eller ditt eget referensnummer.
Svarsmall
Svaret kommer att innehålla detaljerad information om beställningen, bland annat:
Beställningsdetaljer (ID, referens, status, osv.)
"shippingAddress": {
Artiklar beställda med produktdetaljer
Fraktinformation (sätt, spårning och mer)
Ekonomisk information
Svarsexempel (klicka här)
Svarsexempel (klicka här)
{ "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",Leveransadress "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" },
Sök ordrar
Hämta en lista med beställningar baserat på specifika kriterier.
Slutpunkt: POST /{searchOrdersURL}
Så här gör du en förfrågan
], "fulfillmentStatus": [ "canceled", "delivered" } ],
Begärda parametrar
Parameter | Typ | Obligatoriskt | Beskrivning |
leveransstatus | string[] | Valfritt | Filtrera efter orderns leveransstatus |
ekonomisk status | string[] | Valfritt | Filtrera efter beställningens ekonomiska status |
orderReferenceId | sträng | Valfritt | Filtrera efter ditt interna order-ID |
orderReferenceIds | string[] | Valfritt | Filtrera efter flera interna order-ID |
startdatum | sträng | Valfritt | Filtrera efter beställningar skapade efter detta datum (ISO 8601-format) |
slutdatum | string[] | Valfritt | Filtrera på beställningar skapade före det här datumet (ISO 8601-format) |
länder | sträng | Valfritt | Filtrera efter leveranslandskoder |
gräns | nummer | Valfritt | Maximalt antal resultat att visa (standard: 50, max: 100) |
offset | nummer | Valfritt | Antal resultat att hoppa över för sidnumrering (standard: 0) |
Svarsformat
} "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" }, { ],
Felhantering
När en API-förfrågan misslyckas får du ett felmeddelande med en kod och en beskrivning som hjälper dig att förstå och lösa problemet. Vanliga fel kan till exempel vara:
400 Felaktig förfrågan: Ogiltiga eller saknade parametrar
401 Obehörig: Ogiltiga eller saknade autentiseringsuppgifter
404 Hittades inte: Den begärda resursen finns inte
429 För många förfrågningar: Hastighetsgräns överskriden
500 Serverfel: Ett oväntat fel inträffade på servern
Exempel på felmeddelande:
} "code": 400, "message": "Invalid shipping address: Email is not a valid format" {För en robust integration, implementera ordentlig felhantering och återförsökslogik enligt beskrivningen i avsnittet om hastighetsbegränsningar.
Behöver du hjälp?
Om du stöter på problem eller har frågor om API:et, kontakta vårt supportteam på [email protected].
Kom ihåg att ta med följande information när du kontaktar supporten:
Den specifika API-endpoint du använder
Din förfrågans data (med känslig information redigerad)
Felmeddelandet du fick
Relevanta tidsstämplar
Det här gör att vårt team kan lösa ditt problem snabbare och smidigare.