Introduksjon
Velkommen til dokumentasjonen for Order Management API. Med dette API-et kan du sende inn bestillinger, kansellere bestillinger, hente detaljer om bestillinger, søke etter bestillinger og oppdatere leveringsadresser eller leveringsmetoder i GelatoConnect-systemet. API-et er bygget på REST-prinsipper og bruker vanlige HTTPS-metoder for å samhandle med ressurser. Alle svar returneres i JSON-format, også feilmeldinger.
Autentisering
Alle API-kall for ordrebehandling krever autentisering med en gyldig API-nøkkel og hemmelighet i headeren for hvert kall. All kommunikasjon må skje via HTTPS – kall gjort over vanlig HTTP vil ikke fungere.
Autentiseringsmetode
Legg til
X-API-KEY-headeren i forespørselen dinSett verdien med dette formatet:
key:secret
Eksempel:
X-API-KEY: your-key:your-secret
Du får din unike API-nøkkel og hemmelige kode når du setter opp en kobling for kunden din.
Begrensninger for antall forespørsler
API-en har begrensninger på hvor mange forespørsler du eller en klient kan sende i løpet av en bestemt periode. Alle forespørsler teller mot din personlige grense på 100 forespørsler per sekund.
Derfor finnes det begrensninger på hvor mye du kan bruke
Begrensninger på hvor mye du kan bruke tjenesten har flere viktige formål:
Beskytte mot misbruk eller feil bruk av API-et
Sikrer rettferdig tilgang for alle brukere
Unngå avbrudd i tjenesten på grunn av for mye trafikk
Prøv igjen-tilnærming ved grense for antall forespørsler
Hvis du overskrider API-grensen, får du en 429-statuskode. For å unngå problemer med arbeidsflyten din, kan du bruke disse metodene for å prøve igjen:
Prøv igjen: Forsøk automatisk på nytt hvis en forespørsel mislykkes. Legg inn logikk for å prøve igjen i applikasjonskoden for alle API-kall.
Eksponentiell ventetid: Vent litt lenger for hver gang du prøver på nytt etter en feil. Sett en maksgrense for hvor lenge du venter og hvor mange ganger du prøver, tilpasset det du skal gjøre.
Jitter: Legg til en tilfeldig forsinkelse før du prøver på nytt, slik at ikke alle klienter prøver samtidig. Dette fordeler belastningen og reduserer risikoen for at flere kolliderer etter hverandre.
For mer informasjon om hvordan du kan prøve igjen, se:
Svarkoder
Order Management API bruker vanlige HTTP-responskoder for å vise om forespørsler har lykkes eller ikke:
2xx-koder: Viser at alt gikk som det skulle
4xx-koder: Viser til feil i strukturen eller dataene i forespørselen (for eksempel manglende nødvendige parametere eller at bestillingen ikke ble funnet)
5xx-koder: Viser at det har oppstått en serverfeil (dette skjer sjelden)
API-endepunkter
Send inn bestilling
Send inn en bestilling med én forespørsel.
Endepunkt: POST /{submitOrderUrl}
Grunnleggende nettadresse og spesifikk endepunkt får du når du setter opp koblingen.
Forespørselsformat
{ "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ørsel (klikk her)
Eksempel på curl-forespørsel (klikk 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" } ] } ]}'Viktige forespørselsparametere
Parameter | Type | Obligatorisk | Beskrivelse |
ordrereferanseId | streng | Obligatorisk | Din interne ordre-ID |
ordretype | streng | Valgfritt | Type of order: "order" (default) or "draft" |
valuta | streng | Obligatorisk | Valuta for bestillingen (ISO-kode) |
butikkvaluta | streng | Valgfritt | Valuta brukt for utsalgspriser (ved grensekryssende bestillinger) |
utsalgspris for frakt inkl. mva | nummer | Valgfritt | Fraktpris uten mva (selv om parameteren heter noe annet) |
shipmentMethodUid | streng | Valgfritt | Fraktmetode(r) du kan bruke, flere kan skilles med komma |
leveringsadresse | ting | Påkrevd | Kundeadresse for levering |
gjenstander | rekke | Obligatorisk | Liste over produkter du kan bestille |
unngå duplikater | boolsk | Valgfritt | Når dette er satt til «true», hindrer det at det opprettes flere ordrer med samme orderReferenceId. Hvis en duplikat oppdages, får du en feilmelding i stedet for at en ny ordre blir opprettet. |
"packagingInstructions": [ | rekke | Valgfritt | Array med emballasjeinstruksjonsobjekter |
Produktparametere
Parameter | Type | Obligatorisk | Beskrivelse |
vareReferanseId | streng | Påkrevd | Din interne vareidentifikator |
productUid | streng | Obligatorisk* | GelatoConnect produktidentifikator (*Du må fylle ut enten productUid eller productName+productVariant) |
produktnavn | streng | Obligatorisk* | Navn på det personlig tilpassede produktet (*Enten produktUid ELLER produktNavn+produktVariant er nødvendig) |
produktvariant | gjenstand | Obligatorisk* | Variantdetaljer for kundens produkt (*Påkrevd når du bruker produktnavn) |
antall | nummer | Obligatorisk | Antall varer du vil bestille |
utsalgspris inkl. mva | nummer | Valgfritt | Pris uten mva (selv om parameteren heter noe annet) |
filer | rekke | Obligatorisk | Liste over trykkfiler for produktet |
personlig tilpassetBeskjæring | ting | Valgfritt | Personlig tilpassede beskjæringsmål for produktet |
Filparametere
Parameter | Type | Obligatorisk | Beskrivelse |
type | streng | Obligatorisk | Filtype. Du finner en oversikt over valgene i tabellen under. |
url | streng | Obligatorisk | Offentlig tilgjengelig nettadresse til trykkfilen |
Filtype
Parameter | Beskrivelse |
standard | Designet trykkes på hovedområdet av produktet. For klær er det forsiden, mens for foldekort er det omslaget og baksiden.
Hvis du leverer en PDF med flere sider, må antall sider matche trykkflatene, siden den brukes til å trykke på alle. |
forside | Skriv ut filen på forsiden av produktet. |
tilbake | Skriv ut filen på baksiden av produktet. |
omslag | Filen til et bokomslag |
innside hals | Skriv ut filen på innsiden av halsen på klesproduktet. |
hals-ytter | Skriv ut filen på utsiden av halsen på klesproduktet. |
venstre erme | Skriv ut filen på venstre erme på klærne. |
høyre erme | Skriv ut filen på høyre erme på klær-produktet. |
innsiden | Skriv ut filen på innsiden av sidene. |
broderi på venstre side av brystet | Broder filen på venstre side av brystet på klær-produktet. |
broderi midt på brystet | Broder filen midt på brystet på klær-produktet. |
stor brodering på brystet | Broder filen på forsiden av klesproduktet. |
broderi på venstre erme | Broder filen på venstre erme av klær-produktet. |
broderi på høyre erme | Broder filen på høyre erme av klærproduktet. |
broderi på venstre håndledd | Broder filen på venstre håndledd på klær-produktet. |
broderi på høyre håndledd | Broder filen på høyre håndledd på klær-produktet. |
Fleksible filtyper for produkter med Workflow builder
For produkter som er aktivert for Workflow builder, kan du bruke hvilken som helst personlig tilpasset filtypenavn i type-feltet i files-arrayen. Denne funksjonen gjør API-integrasjoner enklere ved at du slipper å koble filer til forhåndsdefinerte typer.
Viktige punkter:
Du kan gi filtyper navn fritt, for eksempel
default_1,default_2,cover_front,inside_pageog så videre.Tillatte tegn: bokstaver (A–Z, a–z), tall (0–9), understrek (_), punktum (.) og bindestrek (-)
Maksimal lengde: 100 tegn
Filtype må fortsatt være unik – hver
type-verdi må være unik innenfor sammefiles-liste
Eksempel på bruk:
{ "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" } ] } ]}
Personlig tilpassede beskjæringsparametere
Parameter | Type | Obligatorisk | Beskrivelse |
breddeMm | nummer | Obligatorisk | Beskjæringsbredde i millimeter (*Påkrevd når du bruker personlig tilpassetBeskjæring) |
heightMm | nummer | Påkrevd | Beskjæringshøyde i millimeter (*Påkrevd når du bruker personlig tilpasset Beskjæring) |
Parametere for emballasjeinstruksjoner
Parameter | Type | Obligatorisk | Beskrivelse |
"packageItems": [ | rekke | Obligatorisk | Varer som skal være med i denne pakken |
orderItemReferenceId | streng | Obligatorisk | Referanse til ordrelinjen (må samsvare med itemReferenceId) |
antall | nummer | Obligatorisk | Antall av varen i denne pakken |
"packingSlip": { | ting | Valgfritt | Innstillinger for pakkeseddel |
fileUrl | streng | Obligatorisk | URL til PDF-pakkseddelfilen |
GelatoConnect vil laste ned og lagre din pakkeseddel som PDF, slik at den alltid er tilgjengelig under pakkingen – selv om den opprinnelige URL-en utløper.
Eksempel på bruk:
{ "orderReferenceId": "ORDER-12345", "orderType": "order", "currency": "USD", "shippingAddress": {...}, "items": [...], "packagingInstructions": [ { "packageItems": [ { "orderItemReferenceId": "ITEM-001", "quantity": 1 } ], "packingSlip": { "fileUrl": "https://example.com/slip.pdf" } } ]}
Overføring fra metadata-baserte pakkesedler
For kunder som i dag bruker metadata for å sende pakkesedler, kan du bruke malen under for å hente ut pakkeseddel-URL-er fra metadata og konvertere dem til packagingInstructions-formatet. Dette sikrer varig fil-lagring gjennom GelatoConnect.
{%- set payload = context.payload -%}{#-- Hent ut URL for pakkeseddel og filtrer bort '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 %} {%- ellers %} {%- set filtered_metadata = filtered_metadata + [m] %} {%- endif %} {%- endfor -%}{#-- Oppdatert JSON --#}{ {%- for key, value in payload.items() %} {%- if key != "metadata" %} "##{{ key }}": ##{{ value | tojson }}, {%- endif %} {%- endfor %} "metadata": ##{{ filtered_metadata | tojson }},emballeringsinstruksjoner {pakkevarer {%- for item in payload.get("items") or [] -%} { "orderItemReferenceId": ##{{ item.itemReferenceId|js }}, "quantity": ##{{ item.quantity }} }{% if not loop.last %},{% endif %}{%- endfor %} ],pakkseddel "fileUrl": "##{{ ns.packing_slip_url }}" } } ]}
Parametere for leveringsadresse
Parameter | Type | Obligatorisk | Beskrivelse |
land | streng | Obligatorisk | Tosifret landskode (ISO 3166-1 alfa-2) |
fornavn | streng | Obligatorisk | Mottakers fornavn |
etternavn | streng | Obligatorisk | Mottakers etternavn |
adressefelt 1 | streng | Obligatorisk | Første linje i gateadressen |
adressefelt 2 | streng | Valgfritt | Andre linje i gateadressen |
by | streng | Obligatorisk | Stedsnavn |
postnummer | streng | Obligatorisk | Postnummer |
delstat | streng | Obligatorisk | Fylkes- eller delstatkode (*Påkrevd for adresser i USA, Canada og Australia) |
e-post | streng | Obligatorisk* | Mottakerens e-postadresse |
telefon | streng | Obligatorisk | Mottakerens telefonnummer med landskode |
firmanavn | streng | Valgfritt | Firmanavn (hvis aktuelt) |
erBedrift | boolsk | Valgfritt | Om adressen er til en bedrift |
føderalt skatte-ID | streng | Valgfritt | Føderalt skatte-ID for bedriftsadresser |
statlig skatte-ID | streng | Valgfritt | Statlig skatte-ID for bedriftsadresser |
registreringsstatus | streng | Valgfritt | Fylket der bedriften er registrert |
Viktig å vite om internasjonale bestillinger
For internasjonale bestillinger, oppgi utsalgspris på produktet og utsalgspris på frakt slik:
retailCurrency: Valutaen som utsalgsprisene oppgis iretailShippingPriceInclVat: Fraktpris uten mva (se bort fra navnet på parameteren)items[i].retailPriceInclVat: Total produktpris uten mva (se bort fra navnet på parameteren)
Velge et produkt
Bestillings-API-et kan ta imot produktinformasjon på to måter:
Bruk av
productUid:
"productUid": "frame_product_frs_10x10-inch_frc_oak_frm_wood_frp_w13xt22-mm_gt_plexiglass"
Bruker
productNameogproductVariant:
"productName": "Framed Poster","productVariant": { "FrameColour": "Black", "PaperSize": "A3"}Ikke bruk begge metodene i samme bestilling.
Velg en fraktmetode
Feltet shipmentMethodUid kan ta imot:
Spesifikke fraktmetode-UID-er (for eksempel
fed_ex_2_day)Navn på fraktselskaper (for eksempel
DHL)Forsendelsesvalg i ulike nivåer (for eksempel
Express)
Du kan legge inn flere fraktmetoder som en kommaseparert liste, så velger systemet det rimeligste alternativet.
Svarformat
{ "id": "32884a3e-bd09-42be-8225-c5cea7d24611", "orderReferenceId": "test", "createdAt": "2024-07-17T10:23:28+00:00"}
Bruk av metadata i hele GelatoConnect
Metadata som legges ved både på ordre- og varenivå i ordreforespørsler, kan brukes av flere verktøy i GelatoConnect og sendes også tilbake i postbacks. Dette er spesielt nyttig for deg som vil holde dataene sømløse mellom ulike systemer.
Metadata for bestillingsnivå:
Metadata på ordrenivå gjelder for hele bestillingen og legges inn øverst i forespørselen.
{ "orderReferenceId": "ORD-12345", "orderType": "order", "currency": "USD", "metadata": [ { "key": "campaign", "value": "summer_promo" }, { "key": "source", "value": "web" } ], "shippingAddress": {...}, "items": [...]}
Metadata for hvert enkelt element:
Metadata på varenivå gjelder for enkeltvarer og defineres inne i hver vare i varelisten.
{ "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å gjelder for bestemte filer og defineres i hver enkelt fil i fil-arrayen. I eksempelet under brukes det til å angi alternativ tekst for bildet embroideryText som 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" } ] } ] } ]}
Avbryt bestillingen
Stopp og avbryt produksjon og utsendelse av en bestilling. Dette er bare mulig frem til bestillingen får status «sendt».
Endepunkt: POST /{orderCancelUrl}
Dette endepunktet kan ta imot enten ordre-ID-en (gitt i svaret når du sender inn en ordre) eller ordreferanse-ID-en (din interne ordre-ID).
Bruke ordrenummer
POST /{orderCancelUrl}/32884a3e-bd09-42be-8225-c5cea7d24611/cancelBruke ordrehenvisnings-ID
POST /{orderCancelUrl}/test/cancelSvarformat
{ "code": 200, "message": "OK"}
Oppdater forsendelse
Du kan endre fraktmetode eller oppdatere leveringsadressen helt til bestillingen har fått status «sendt».
Endepunkt: PUT /{updateShipmentURL}
Dette endepunktet kan bruke enten ordre-ID eller referanse-ID for ordren.
Forespørselsformat
{ "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 endre enten fraktmetode, leveringsadresse eller begge deler. Minst ett av disse feltene må være med i forespørselen.
Forespørselsparametere
Parameter | Type | Obligatorisk | Beskrivelse |
shipmentMethodUid | streng | Valgfritt* | Ny fraktmetode (*Du må oppgi enten shipmentMethodUid eller leveringsadresse) |
leveringsadresse | ting | Valgfritt* | Nye leveringsadresseopplysninger (*Du må oppgi enten shipmentMethodUid eller leveringsadresse) |
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 bestilling
Hent informasjon om en eksisterende bestilling.
Endepunkt: GET /{getOrderURL}/{order_id}
Du kan bruke enten Gelato-bestillings-ID eller din egen referanse-ID.
Svarformat
Svaret vil inneholde detaljerte opplysninger om bestillingen, blant annet:
Ordredetaljer (ID, referanse, status og lignende)
"shippingAddress": {
Varer bestilt med produktdetaljer
Fraktinformasjon (metode, sporing og lignende)
Økonomisk informasjon
Eksempel på svar (klikk her)
Eksempel på svar (klikk 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øk etter bestillinger
Hent en oversikt over bestillinger basert på bestemte kriterier.
Endepunkt: POST /{searchOrdersURL}
Forespørselsformat
], "fulfillmentStatus": [ "canceled", "delivered" } ],
Forespørselsparametere
Parameter | Type | Obligatorisk | Beskrivelse |
oppfyllelsesstatus | string[] | Valgfritt | Filtrer etter produksjonsstatus for bestillinger |
økonomisk status | string[] | Valgfritt | Filtrer etter økonomisk status på bestilling |
ordrereferanseId | streng | Valgfritt | Filtrer etter din interne ordre-ID |
ordrereferanse-ID-er | string[] | Valgfritt | Filtrer etter flere interne ordre-ID-er |
startdato | streng | Valgfritt | Filtrer etter bestillinger opprettet etter denne datoen (ISO 8601-format) |
sluttdato | string[] | Valgfritt | Filtrer etter bestillinger opprettet før denne datoen (ISO 8601-format) |
land | streng | Valgfritt | Filtrer etter landkode for frakt |
grense | nummer | Valgfritt | Maksimalt antall resultater som vises (standard: 50, maks: 100) |
forskyvning | nummer | Valgfritt | Antall resultater som skal hoppes over ved paginering (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" }, { ],
Feilhåndtering
Når et API-kall mislykkes, får du et svar med en feilkode og en forklarende melding som hjelper deg å finne ut av og løse problemet. Vanlige feil kan være:
400 Ugyldig forespørsel: Manglende eller ugyldige parametere
401 Ikke autorisert: Ugyldige eller manglende påloggingsopplysninger
404 Ikke funnet: Det du leter etter finnes ikke
429 For mange forespørsler: Du har nådd grensen for hvor mange forespørsler du kan sende
500 Serverfeil: Noe uventet skjedde på serveren
Eksempel på feilmelding:
} "code": 400, "message": "Invalid shipping address: Email is not a valid format" {For å få en solid integrasjon, bør du bruke god feilhåndtering og sørge for at systemet prøver på nytt ved feil, slik det står beskrevet i delen om grenseverdier.
Trenger du en hånd?
Hvis du støter på problemer eller har spørsmål om API-et, kan du ta kontakt med brukerstøtte på [email protected].
Husk å ta med denne informasjonen i supporthenvendelsen din:
Den API-endepunktet du bruker
Forespørselen din (med sensitive opplysninger fjernet)
Feilmeldingen du fikk
Eventuelle relevante tidspunkter
Dette gjør at teamet vårt kan løse saken din raskere og bedre.