Introduktion
Velkommen til dokumentationen for Order Management API. Med dette API kan du oprette ordrer, annullere ordrer, hente ordredetaljer, søge efter ordrer og opdatere leveringsadresser eller leveringsmetoder i GelatoConnect-systemet. API'et er bygget op omkring REST-principper og bruger standard HTTPS-metoder til at arbejde med ressourcer. Alle svar returneres i JSON-format – også fejlmeddelelser.
Godkendelse
Alle kald til Order Management API kræver, at du logger ind med en gyldig API-nøgle og hemmelighed, som skal medsendes i headeren for hvert kald. Al kommunikation skal ske via HTTPS – hvis du bruger almindelig HTTP, virker det ikke.
Godkendelsesmetode
Tilføj
X-API-KEY-headeren til din forespørgselIndstil værdien med formatet:
key:secret
Eksempel:
X-API-KEY: your-key:your-secret
Din unikke API-nøgle og hemmelige kode får du, når du opretter en connector til din kunde.
Begrænsninger for hvor meget du kan bruge
API'en sætter grænser for, hvor mange forespørgsler du eller din klient kan lave inden for en bestemt periode. Alle forespørgsler tæller med i din personlige grænse på 100 forespørgsler pr. sekund.
Derfor findes der grænser for, hvor meget du kan bruge REST
Begrænsninger på, hvor meget du kan gøre ad gangen, har flere vigtige formål:
Beskytter mod misbrug eller forkert brug af API'en
Vi sikrer, at alle har lige adgang
Sådan undgår du afbrydelser, når der er ekstra meget trafik
Genforsøg ved for mange forespørgsler
Hvis du overskrider API-rategrænsen, får du en 429-statuskode. For at undgå problemer med dine arbejdsopgaver, kan du bruge disse metoder til at prøve igen:
Prøv igen: Forsøg automatisk at gentage mislykkede forespørgsler. Sørg for at din applikation automatisk prøver igen, hvis et API-kald fejler.
Eksponentiel tilbageholdelse: Vent lidt længere mellem hvert forsøg, hvis du får flere fejl i træk. Sæt en grænse for, hvor længe du maksimalt venter, og hvor mange gange du prøver igen – alt efter, hvad du laver.
Jitter: Tilføj en tilfældig ventetid, før du prøver igen, så ikke alle prøver på samme tid. Det hjælper med at fordele belastningen og undgår, at alle rammer ind i hinanden på én gang.
Vil du vide mere om, hvordan du kan prøve igen? Læs mere her:
Svarkoder
Order Management API bruger almindelige HTTP-svar-koder til at vise, om dine forespørgsler lykkes eller ej:
2xx-koder: Betyder, at alt gik som det skulle
4xx-koder: Fortæller dig, at der er fejl i strukturen eller dataene i din forespørgsel (for eksempel hvis der mangler vigtige oplysninger, eller ordren ikke kan findes)
5xx-koder: Fortæller, at der er serverfejl (det sker sjældent)
API-endpoints
Afgiv ordre
Send en ordre afsted med én enkelt handling.
Endepunkt: POST /{submitOrderUrl}
Basis-URL'en og det specifikke endpoint får du, når du sætter connectoren op.
Anmodningsformat
{ "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" } ] } ]}Eksempel på curl-forespørgsel (klik her)
Eksempel på curl-forespørgsel (klik her)
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" } ] } ]}'Vigtige oplysninger du skal bruge
Parameter | Type | Påkrævet | Beskrivelse |
ordreReferenceId | streng | Påkrævet | Dit interne ordrenummer |
ordretype | streng | Valgfri | Type of order: "order" (default) or "draft" |
valuta | streng | Påkrævet | Valuta for ordren (ISO-kode) |
retailCurrency | streng | Valgfri | Valuta brugt til detailpriser (ved grænseoverskridende ordrer) |
retailShippingPriceInclVat | nummer | Valgfrit | Forsendelsespris uden moms (selvom parameterens navn antyder andet) |
shipmentMethodUid | streng | Valgfri | Forsendelsesmetode(r) du kan bruge, adskilt med komma |
leveringsadresse | ting | Påkrævet | Kundens leveringsadresseoplysninger |
genstande | række | Påkrævet | Liste over produkter, du kan bestille |
undgå gentagelser | boolesk | Valgfri | Når denne er sat til sand, forhindrer det oprettelse af dublerede ordrer med samme orderReferenceId. Hvis der opdages en dublet, får du en fejlbesked i stedet for at oprette en ny ordre. |
"packagingInstructions": [ | række | Valgfri | Array af emballageinstruktionsobjekter |
Vareparametre
Parameter | Type | Påkrævet | Beskrivelse |
itemReferenceId | streng | Påkrævet | Dit interne vare-id |
productUid | streng | Påkrævet* | GelatoConnect produkt-id (*Enten productUid ELLER productName+productVariant er påkrævet) |
produktnavn | streng | Påkrævet* | Navn på kundens produkt (*Enten produktUid ELLER produktNavn+produktVariant er påkrævet) |
produktvariant | ting | Påkrævet* | Variantdetaljer for kundens produkt (*Påkrævet når du bruger productName) |
antal | nummer | Påkrævet | Antal varer du vil bestille |
Udsalgspris inkl. moms | nummer | Valgfri | Pris uden moms (selvom parameterens navn antyder noget andet) |
filer | række | Påkrævet | Liste over printfiler til produktet |
tilpassetBeskæring | ting | Valgfri | Tilpassede beskæringsmål for produktet |
Filparametre
Parameter | Type | Påkrævet | Beskrivelse |
type | streng | Påkrævet | Filtype. Du kan se en liste over muligheder i tabellen nedenfor. |
url | streng | Påkrævet | Offentligt tilgængelig URL til printfilen |
Filtype
Parameter | Beskrivelse |
standard | Designet bliver trykt på det vigtigste område af produktet. For Beklædning er det forsiden, og for foldede kort er det for- og bagsiden.
Hvis du uploader en PDF med flere sider, skal antallet af sider passe med antallet af trykområder – vi bruger nemlig hver side til at trykke på hvert område. |
forside | Print filen på forsiden af produktet. |
tilbage | Print filen på bagsiden af produktet. |
forside | Filen til et bogomslag |
inderside af hals | Print filen på indersiden af halsen på beklædningsproduktet. |
hals – yderste lag | Print filen på ydersiden af halsen på beklædningsproduktet. |
ærme – venstre | Print filen på venstre ærme af beklædningsproduktet. |
højre ærme | Print filen på højre ærme af beklædningsproduktet. |
indenfor | Print filen på de indvendige sider. |
broderi på venstre bryst | Broder filen på venstre bryst af beklædningsproduktet. |
broderi midt på brystet | Brodér filen midt på brystet af beklædningsproduktet. |
stor brystbrodering | Brodér filen på forsiden af beklædningsproduktet. |
venstre ærme – broderi | Broder filen på venstre ærme af beklædningsproduktet. |
højre ærme – broderi | Broder filen på højre ærme af beklædningsproduktet. |
venstre håndledsbroderi | Brodér filen på venstre håndled af beklædningsproduktet. |
højre håndled – broderi | Broder filen på højre håndled af beklædningsproduktet. |
Fleksible filtyper til produkter med Workflow builder
For produkter, der er aktiveret til Workflow builder, kan du bruge alle tilpassede filtypenavne i type-feltet i files-arrayet. Denne funktion gør API-integrationer nemmere, fordi du ikke længere behøver at matche filer med foruddefinerede typer.
Vigtige pointer:
Du kan frit navngive filtyper, for eksempel
default_1,default_2,cover_front,inside_pageosv.Tilladte tegn: bogstaver (A–Z, a–z), tal (0–9), understregninger (_), punktummer (.), og bindestreger (-)
Maksimal længde: 100 tegn
Filtype-unikhed gælder stadig – hver
type-værdi skal være unik inden for sammefiles-array
Eksempel på brug:
{ "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" } ] } ]}
Tilpassede beskæringsparametre
Parameter | Type | Påkrævet | Beskrivelse |
widthMm | nummer | Påkrævet | Beskæringsbredde i millimeter (*Påkrævet når du bruger tilpassetBeskæring) |
heightMm | nummer | Påkrævet | Beskæringshøjde i millimeter (*Påkrævet når du bruger tilpassetBeskæring) |
Parametre for emballageinstruktioner
Parameter | Type | Påkrævet | Beskrivelse |
"packageItems": [ | række | Påkrævet | Varer, der skal med i denne pakke |
orderItemReferenceId | streng | Påkrævet | Reference til ordrelinjen (skal matche itemReferenceId) |
antal | nummer | Påkrævet | Antal af varen i denne pakke |
"packingSlip": { | ting | Valgfrit | Indstillinger for pakkeseddel |
fileUrl | streng | Påkrævet | URL til PDF-pakkeseddelfilen |
GelatoConnect downloader og gemmer din pakkeseddel som PDF, så du altid har adgang til den under pakkeprocessen – også selvom det oprindelige link udløber.
Eksempel på brug:
{ "orderReferenceId": "ORDER-12345", "orderType": "order", "currency": "USD", "shippingAddress": {...}, "items": [...], "packagingInstructions": [ { "packageItems": [ { "orderItemReferenceId": "ITEM-001", "quantity": 1 } ], "packingSlip": { "fileUrl": "https://example.com/slip.pdf" } } ]}
Migrering fra metadata-baserede pakkesedler
Hvis du som kunde allerede bruger metadata til at sende pakkesedler, kan du bruge skabelonen herunder til at udtrække pakkeseddel-URL’er fra metadata og omdanne dem til packagingInstructions-formatet. På den måde sikrer du, at filerne bliver gemt permanent af GelatoConnect.
{%- set payload = context.payload -%}{#-- Udtræk pakkeseddel-URL og filtrer 'tenant-packing-slip' fra --#}{%- 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 opdateret JSON --#}{ {%- for key, value in payload.items() %} {%- if key != "metadata" %} "##{{ key }}": ##{{ value | tojson }}, {%- endif %} {%- endfor %} "metadata": ##{{ filtered_metadata | tojson }},emballeringsinstruktioner {pakkevarer {%- for item in payload.get("items") or [] -%} { "orderItemReferenceId": ##{{ item.itemReferenceId|js }}, "quantity": ##{{ item.quantity }} }{% if not loop.last %},{% endif %}{%- endfor %} ],pakkeseddel "fileUrl": "##{{ ns.packing_slip_url }}" } } ]}
Parametre for leveringsadresse
Parameter | Type | Påkrævet | Beskrivelse |
land | streng | Påkrævet | To-bogstavs landekode (ISO 3166-1 alpha-2) |
fornavn | streng | Påkrævet | Modtagerens fornavn |
Efternavn | streng | Påkrævet | Modtagers efternavn |
adresse linje 1 | streng | Påkrævet | Første linje af gadeadressen |
Adresse linje 2 | streng | Valgfri | Anden linje af gadeadressen |
by | streng | Påkrævet | Bynavn |
postnummer | streng | Påkrævet | Postnummer |
tilstand | string | Påkrævet | Stat eller provinskode (*Påkrævet for adresser i USA, Canada og Australien) |
streng | Påkrævet* | Modtagerens e-mailadresse | |
telefon | streng | Påkrævet | Modtagerens telefonnummer med landekode |
companyName | streng | Valgfrit | Firmanavn (hvis relevant) |
erErhverv | boolesk | Valgfrit | Om adressen er til en virksomhed |
federalTaxId | streng | Valgfrit | CVR-nummer til virksomhedsadresser |
statsskatte-id | streng | Valgfrit | Statens skatte-ID til virksomhedsadresser |
registreringstilstand | streng | Valgfri | Angiv den stat, hvor din virksomhed er registreret |
Særlige bemærkninger til internationale ordrer
For internationale ordrer, skal du oplyse detailprisen på produktet og detailprisen på forsendelsen som:
retailCurrency: Valutaen, som detailpriserne vises iretailShippingPriceInclVat: Forsendelsespris uden moms (se bort fra parameternavnet)items[i].retailPriceInclVat: Samlet produktpris uden moms (du kan se bort fra navnet på parameteren)
Vælg et produkt
API'en til ordreafgivelse kan modtage produktoplysninger på to måder:
Brug af
productUid:
"productUid": "frame_product_frs_10x10-inch_frc_oak_frm_wood_frp_w13xt22-mm_gt_plexiglass"
Brug af
productNameogproductVariant:
"productName": "Framed Poster","productVariant": { "FrameColour": "Black", "PaperSize": "A3"}Brug ikke begge metoder i den samme ordre.
Vælg en leveringsmetode
shipmentMethodUid-feltet kan tage imod:
Specifikke forsendelsesmetode-UID'er (f.eks.
fed_ex_2_day)Navne på fragtfirmaer (f.eks.
DHL)Forsendelsesmuligheder (f.eks.
Express)
Du kan angive flere leveringsmetoder adskilt med komma, og systemet vælger automatisk den billigste mulighed.
Svarformat
{ "id": "32884a3e-bd09-42be-8225-c5cea7d24611", "orderReferenceId": "test", "createdAt": "2024-07-17T10:23:28+00:00"}
Brug af metadata i hele GelatoConnect
Metadata, der gives både på ordre- og vareniveau i ordreanmodninger, kan bruges af flere værktøjer i GelatoConnect og sendes også tilbage i postbacks. Det er især værdifuldt for dig, der har brug for at holde styr på dataene mellem dine systemer.
Metadata for ordre:
Metadata på ordreniveau gælder for hele ordren og angives øverst i anmodningen.
{ "orderReferenceId": "ORD-12345", "orderType": "order", "currency": "USD", "metadata": [ { "key": "campaign", "value": "summer_promo" }, { "key": "source", "value": "web" } ], "shippingAddress": {...}, "items": [...]}
Metadata på vareniveau:
Metadata på vareniveau gælder for enkelte varer og angives direkte i hver vare i items-listen.
{ "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å filniveau:
Metadata på filniveau gælder for specifikke filer og defineres i hver fil i files-arrayet. I eksemplet nedenfor bruges det til at angive alternativ tekst til billedet embroideryText, der er knyttet til 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" } ] } ] } ]}
Aflys ordre
Stop og annuller produktion og forsendelse af en ordre. Det er kun muligt, indtil ordren får status "afsendt".
Endpoint: POST /{orderCancelUrl}
Dette endpoint kan tage imod enten Ordre-ID'et (som du får i svaret, når du indsender en ordre) eller Ordre Reference-ID'et (dit eget interne ordre-ID).
Brug af ordre-ID
POST /{orderCancelUrl}/32884a3e-bd09-42be-8225-c5cea7d24611/cancelBrug af ordre reference-ID
POST /{orderCancelUrl}/test/annullerSvarformat
{ "code": 200, "message": "OK"}
Opdater forsendelse
Du kan ændre leveringsmetode eller opdatere leveringsadressen, indtil ordren har fået status "shipped".
Endpoint: PUT /{updateShipmentURL}
Dette endpoint kan tage imod enten Ordre-ID eller Ordre Reference-ID.
Anmodningsformat
{ "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 opdatere enten leveringsmetoden, leveringsadressen eller begge dele. Du skal mindst vælge ét af disse felter i din anmodning.
Forespørgselsparametre
Parameter | Type | Påkrævet | Beskrivelse |
shipmentMethodUid | streng | Valgfrit* | Ny leveringsmetode (*Du skal mindst angive enten shipmentMethodUid eller leveringsadresse) |
leveringsadresse | ting | Valgfrit* | Nye leveringsadresseoplysninger (*Du skal mindst angive enten shipmentMethodUid eller shippingAddress) |
Svarformat
{ "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" }}
Hent ordre
Få oplysninger om en eksisterende ordre.
Endpoint: GET /{getOrderURL}/{order_id}
Du kan bruge enten Gelato Order ID eller dit Order Reference ID.
Svarformat
Svaret vil indeholde alle de vigtige detaljer om ordren, herunder:
Ordredetaljer (ID, reference, status osv.)
"shippingAddress": {
Varer bestilt med produktdetaljer
Forsendelsesinfo (metode, tracking osv.)
Økonomiske oplysninger
Eksempel på svar (klik her)
Eksempel på svar (klik her)
{ "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",Leveringsadresse "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øg efter ordrer
Få en liste over ordrer, der matcher dine ønsker.
Endpoint: POST /{searchOrdersURL}
Anmodningsformat
], "fulfillmentStatus": [ "canceled", "delivered" } ],
Forespørgselsparametre
Parameter | Type | Påkrævet | Beskrivelse |
fulfillmentStatus | string[] | Valgfrit | Filtrér efter ordre Fulfillment-status |
økonomisk status | string[] | Valgfri | Filtrér efter ordres økonomiske status |
ordrereference-id | streng | Valgfrit | Filtrér efter din interne ordre-ID |
ordrereference-id'er | string[] | Valgfri | Filtrér efter flere interne ordre-ID'er |
startDate | streng | Valgfrit | Filtrér efter ordrer oprettet efter denne dato (ISO 8601-format) |
slutdato | string[] | Valgfrit | Filtrér efter ordrer oprettet før denne dato (ISO 8601-format) |
lande | streng | Valgfrit | Filtrér efter forsendelseslandekoder |
grænse | nummer | Valgfrit | Maksimalt antal resultater, der vises (standard: 50, maks: 100) |
offset | nummer | Valgfrit | Antal resultater der springes over ved sideinddeling (standard: 0) |
Svarformat
} "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" }, { ],
Fejlhåndtering
Når en API-forespørgsel fejler, får du et svar med en fejlkode og en beskrivende besked, så du nemt kan finde og løse problemet. Typiske fejl kan for eksempel være:
400 Forkert anmodning: Ugyldige eller manglende oplysninger
401 Ikke autoriseret: Ugyldige eller manglende loginoplysninger
404 – Siden blev ikke fundet: Det, du leder efter, findes ikke
429 For mange forespørgsler: Du har nået grænsen for, hvor mange gange du kan prøve lige nu
500 Serverfejl: Noget gik galt på serveren
Eksempel på fejlmeddelelse:
} "code": 400, "message": "Invalid shipping address: Email is not a valid format" {For at få en stærk integration, skal du sørge for at håndtere fejl rigtigt og prøve igen, som beskrevet i afsnittet om Rate Limits.
Brug for hjælp?
Hvis du oplever problemer eller har spørgsmål om API'en, så tag endelig fat i vores Supportteam på [email protected].
Husk at få disse oplysninger med i din supportanmodning:
Den specifikke API-endpoint, du bruger
Din forespørgsel (med følsomme oplysninger skjult)
Fejlbeskeden du fik
Alle relevante tidspunkter
Det gør det nemmere og hurtigere for vores team at hjælpe dig.