Introduzione
Benvenuto nella documentazione dell’API di gestione ordini. Questa API ti permette di inviare ordini, annullare ordini, recuperare i dettagli degli ordini, cercare ordini e aggiornare indirizzi o metodi di spedizione all’interno del sistema GelatoConnect. L’API è strutturata secondo i principi REST e utilizza i metodi HTTPS standard per interagire con le risorse. Tutte le risposte sono restituite in formato JSON, inclusi gli errori.
Autenticazione
Tutte le chiamate all'API di gestione ordini richiedono l'autenticazione tramite una chiave API e un secret validi, forniti nell'header di ogni chiamata. Tutte le comunicazioni devono avvenire tramite HTTPS; le chiamate effettuate su HTTP semplice non andranno a buon fine.
Metodo di autenticazione
Aggiungi l'intestazione
X-API-KEYalla tua richiestaImposta il valore usando questo formato:
key:secret
Esempio:
X-API-KEY: your-key:your-secret
Riceverai la tua chiave API e il tuo secret personali quando configuri un connettore per il tuo cliente.
Limiti di utilizzo
L'API impone dei limiti al numero di richieste che tu o il tuo client potete fare in un determinato periodo. Tutte le richieste vengono conteggiate nel tuo limite personale di 100 richieste al secondo.
Perché esistono i limiti di utilizzo
I limiti di frequenza hanno diversi scopi importanti:
Proteggere l’API da abusi o utilizzi impropri
Garantire a tutti un accesso equo
Evitare interruzioni del servizio quando il traffico è troppo intenso
Logica di ripetizione per errori di limite di frequenza
Se superi il limite di richieste API, riceverai un codice di stato 429. Per ridurre al minimo l’impatto sul tuo lavoro, prova queste tecniche di ripetizione:
Riprova: ritenta automaticamente le richieste non riuscite. Inserisci una logica di ripetizione nel codice della tua App per tutte le chiamate API.
Exponential Backoff: aumenta gradualmente il tempo di attesa tra un tentativo e l'altro quando ricevi più errori di seguito; imposta un intervallo massimo di attesa e un numero massimo di tentativi in base all'operazione che stai eseguendo.
Jitter: aggiungi un intervallo di tempo casuale prima di riprovare le richieste, così eviti che tutti i client riprovino nello stesso momento. In questo modo il carico si distribuisce meglio e si riducono i conflitti uno dopo l'altro.
Per saperne di più sulle strategie di ripetizione, dai un'occhiata a:
Codici di risposta
L'API di gestione degli ordini utilizza i classici codici di risposta HTTP per indicare se una richiesta è andata a buon fine o meno:
Codici 2xx: indicano che tutto è andato a buon fine
Codici 4xx: indicano errori di struttura o di dati nella richiesta (ad esempio: parametri obbligatori mancanti, ordine non trovato)
Codici 5xx: indicano errori del server (succede di rado)
Endpoint API
Invia ordine
Invia un ordine con una sola richiesta.
Endpoint: POST /{submitOrderUrl}
L'URL di base e l'endpoint specifico ti verranno forniti durante la configurazione del connettore.
Formato della richiesta
{ "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" } ] } ]}Esempio di richiesta curl (clicca qui)
Esempio di richiesta curl (clicca qui)
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" } ] } ]}'Parametri chiave della richiesta
Parametro | Tipologia | Obbligatorio | Descrizione |
orderReferenceId | string | Obbligatorio | Il tuo identificatore interno dell’ordine |
tipo di ordine | string | Facoltativo | Type of order: "order" (default) or "draft" |
valuta | string | Obbligatorio | Valuta dell’ordine (codice ISO) |
valuta al dettaglio | string | Facoltativo | Valuta utilizzata per i prezzi al dettaglio (per ordini internazionali) |
prezzo di spedizione al dettaglio IVA inclusa | numero | Facoltativo | Prezzo di spedizione senza IVA (anche se il nome del parametro può trarre in inganno) |
shipmentMethodUid | string | Facoltativo | Metodo di spedizione da usare; puoi separare più opzioni con una virgola |
indirizzo di spedizione | oggetto | Obbligatorio | Dettagli dell'indirizzo di consegna del cliente |
elementi | una serie | Obbligatorio | Elenco dei prodotti da ordinare |
evita i duplicati | booleano | Facoltativo | Se impostato su true, impedisce la creazione di ordini duplicati con lo stesso orderReferenceId. Se viene rilevato un duplicato, verrà restituito un messaggio di errore invece di creare un nuovo ordine. |
"packagingInstructions": [ | elenco | Facoltativo | Array di oggetti istruzione di imballaggio |
Parametri dell'articolo
Parametro | Tipologia | Obbligatorio | Descrizione |
ID riferimento articolo | string | Obbligatorio | Il tuo identificatore interno dell'articolo |
productUid | string | Obbligatorio* | Identificatore prodotto GelatoConnect (*È necessario inserire o il productUid oppure productName+productVariant) |
nome prodotto | string | Obbligatorio* | Nome del prodotto personalizzato del cliente (*È necessario inserire o il productUid oppure il productName insieme al productVariant) |
variante prodotto | oggetto | Obbligatorio* | Dettagli della variante per il prodotto personalizzato del cliente (*Obbligatorio quando usi productName) |
quantità | numero | Obbligatorio | Numero di articoli da ordinare |
prezzo al dettaglio IVA inclusa | numero | Facoltativo | Prezzo senza IVA (anche se il nome del parametro può trarre in inganno) |
file | una serie | Obbligatorio | Elenco dei file di stampa per il prodotto |
finituraPersonalizzata | oggetto | Facoltativo | Dimensioni di finitura personalizzate per il prodotto |
Parametri del file
Parametro | Tipologia | Obbligatorio | Descrizione |
tipo | string | Obbligatorio | Tipo di file. Trovi un elenco di opzioni nella tabella qui sotto. |
url | string | Obbligatorio | URL accessibile pubblicamente al file di stampa |
Tipo di file
Parametro | Descrizione |
predefinito | La grafica viene stampata sull'area principale del prodotto; per l'Abbigliamento è la parte frontale, mentre per i Biglietti pieghevoli sono la copertina e il retro.
Se carichi un PDF con più pagine, il numero di pagine deve corrispondere alle aree di stampa, perché verrà usato per stampare su tutte. |
fronte | Stampa il file sulla parte frontale del prodotto. |
indietro | Stampa il file sul retro del prodotto. |
copertina | Il file per la copertina di un libro |
interno collo | Stampa il file all'interno del collo del prodotto di abbigliamento. |
collo esterno | Stampa il file sulla parte esterna del collo del prodotto di abbigliamento. |
manica sinistra | Stampa il file sulla manica sinistra del prodotto di abbigliamento. |
manica destra | Stampa il file sulla manica destra del prodotto di abbigliamento. |
all'interno | Stampa il file sulle pagine interne. |
ricamo lato sinistro del petto | Ricama il file sul lato sinistro del petto del prodotto di abbigliamento. |
ricamo al centro del petto | Ricama il file al centro del petto del prodotto di abbigliamento. |
ricamo grande sul petto | Ricama il file sulla parte frontale del prodotto di abbigliamento. |
ricamo manica sinistra | Ricama il file sulla manica sinistra del prodotto di abbigliamento. |
ricamo manica destra | Ricama il file sulla manica destra del prodotto di abbigliamento. |
ricamo lato sinistro del polso | Ricama il file sul polso sinistro del prodotto di abbigliamento. |
ricamo lato destro del polso | Ricama il file sul polso destro del prodotto di abbigliamento. |
Tipi di file flessibili per prodotti abilitati al Workflow builder
Per i prodotti abilitati per Workflow builder, puoi usare qualsiasi nome di tipo file personalizzato nel campo type dell’array files. Questa funzione semplifica le integrazioni API perché non è più necessario associare i file a tipi predefiniti.
Punti chiave:
Puoi dare ai tipi di file il nome che preferisci, ad esempio
default_1,default_2,cover_front,inside_pagee così via.Caratteri consentiti: lettere (A–Z, a–z), numeri (0–9), underscore (_), punti (.) e trattini (-)
Lunghezza massima: 100 caratteri
L'unicità del tipo di file si applica comunque: ogni valore
typedeve essere unico all'interno dello stesso arrayfiles.
Esempio di utilizzo:
{ "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" } ] } ]}
Parametri di finitura personalizzati
Parametro | Tipologia | Obbligatorio | Descrizione |
widthMm | numero | Obbligatorio | Larghezza della finitura in millimetri (*Obbligatorio quando si utilizza personalizzatoFinitura) |
heightMm | numero | Obbligatorio | Altezza della finitura in millimetri (*Obbligatorio quando si utilizza personalizzatoFinitura) |
Parametri delle istruzioni di confezionamento
Parametro | Tipologia | Obbligatorio | Descrizione |
"packageItems": [ | una serie | Obbligatorio | Articoli da includere in questo pacco |
orderItemReferenceId | string | Obbligatorio | Riferimento all'articolo dell'ordine (deve corrispondere a itemReferenceId) |
quantità | numero | Obbligatorio | Quantità dell'articolo in questo pacco |
"packingSlip": { | oggetto | Facoltativo | Configurazione della bolla di accompagnamento |
fileUrl | string | Obbligatorio | URL al file PDF della bolla di accompagnamento |
GelatoConnect scaricherà e salverà il PDF della tua bolla di accompagnamento per garantirne l’accessibilità durante il processo di imballaggio, anche se l’URL originale dovesse scadere.
Esempio di utilizzo:
{ "orderReferenceId": "ORDER-12345", "orderType": "order", "currency": "USD", "shippingAddress": {...}, "items": [...], "packagingInstructions": [ { "packageItems": [ { "orderItemReferenceId": "ITEM-001", "quantity": 1 } ], "packingSlip": { "fileUrl": "https://example.com/slip.pdf" } } ]}
Importazione da packing slip basati su metadati
Per chi sta già usando i metadati per inviare le distinte di imballaggio, puoi usare il modello qui sotto per estrarre gli URL delle distinte dai metadati e convertirli nel formato packagingInstructions, così da garantire l’archiviazione permanente dei file da parte di GelatoConnect.
{%- set payload = context.payload -%}{#-- Estrai l'URL della bolla di accompagnamento ed escludi '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 -%}{#-- Output updated JSON --#}{ {%- for key, value in payload.items() %} {%- if key != "metadata" %} "##{{ key }}": ##{{ value | tojson }}, {%- endif %} {%- endfor %} "metadata": ##{{ filtered_metadata | tojson }},istruzioni per il packaging {articoli del pacco {%- for item in payload.get("items") or [] -%} { "orderItemReferenceId": ##{{ item.itemReferenceId|js }}, "quantity": ##{{ item.quantity }} }{% if not loop.last %},{% endif %}{%- endfor %} ],packingSlip "fileUrl": "##{{ ns.packing_slip_url }}" } } ]}
Parametri dell'indirizzo di spedizione
Parametro | Tipologia | Obbligatorio | Descrizione |
paese | stringa | Obbligatorio | Codice paese a due lettere (ISO 3166-1 alpha-2) |
firstName | string | Obbligatorio | Nome di battesimo del destinatario |
Cognome | string | Obbligatorio | Cognome del destinatario |
indirizzo (linea 1) | stringa | Obbligatorio | Prima riga dell’indirizzo |
indirizzo (seconda riga) | string | Facoltativo | Seconda riga dell'indirizzo |
città | string | Obbligatorio | Nome della città |
codice postale | string | Obbligatorio | CAP o codice postale |
stato | string | Obbligatorio | Codice dello stato o della provincia (obbligatorio per indirizzi negli Stati Uniti, Canada e Australia) |
string | Obbligatorio* | Indirizzo email del destinatario | |
telefono | string | Obbligatorio | Numero di telefono del destinatario con prefisso internazionale |
companyName | string | Facoltativo | Nome dell’attività (se applicabile) |
èBusiness | booleano | Facoltativo | Se l'indirizzo è destinato a un'attività |
partita IVA | string | Facoltativo | Partita IVA per indirizzi aziendali |
codice fiscale statale | string | Facoltativo | Partita IVA per indirizzi aziendali |
stato di registrazione | string | Facoltativo | Indica dove è registrata la tua attività |
Note importanti per gli ordini internazionali
Per gli ordini internazionali, indica il prezzo al dettaglio del prodotto e il prezzo di spedizione al dettaglio come segue:
retailCurrency: valuta in cui sono indicati i prezzi al dettaglioretailShippingPriceInclVat: prezzo di spedizione esclusa IVA (ignora il nome del parametro)items[i].retailPriceInclVat: Prezzo totale del prodotto esclusa IVA (ignora il nome del parametro)
Scegliere un prodotto
L'API per l'invio degli ordini può ricevere le informazioni sui prodotti in due modi:
Usando
productUid:
"productUid": "frame_product_frs_10x10-inch_frc_oak_frm_wood_frp_w13xt22-mm_gt_plexiglass"
Usando
productNameeproductVariant:
"productName": "Framed Poster","productVariant": { "FrameColour": "Black", "PaperSize": "A3"}Non usare entrambi i metodi nella stessa richiesta d'ordine.
Scegliere un metodo di spedizione
Il campo shipmentMethodUid può accettare:
UID specifici dei metodi di spedizione (ad esempio:
fed_ex_2_day)Nomi dei corrieri di spedizione (ad esempio,
DHL)Livelli delle opzioni di spedizione (ad esempio,
Express)
Puoi inserire più metodi di spedizione separandoli con una virgola; il sistema sceglierà automaticamente l'opzione più conveniente.
Formato di risposta
{ "id": "32884a3e-bd09-42be-8225-c5cea7d24611", "orderReferenceId": "test", "createdAt": "2024-07-17T10:23:28+00:00"}
Utilizzo dei metadati in tutta GelatoConnect
I metadati forniti sia a livello di ordine che di articolo nelle richieste d’ordine possono essere utilizzati da diversi strumenti all’interno di GelatoConnect e vengono anche restituiti nei postback. Questo è particolarmente utile per chi vuole mantenere la continuità dei dati tra i propri sistemi.
Metadati a livello di ordine:
I metadati a livello di ordine si applicano all’intero ordine e vengono definiti nella parte superiore della richiesta.
{ "orderReferenceId": "ORD-12345", "orderType": "order", "currency": "USD", "metadata": [ { "key": "campaign", "value": "summer_promo" }, { "key": "source", "value": "web" } ], "shippingAddress": {...}, "items": [...]}
Metadati a livello di articolo:
I metadati a livello di articolo si applicano a singoli articoli e vengono definiti all'interno di ciascun articolo nell'elenco degli articoli.
{ "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": [...] } ]}
Metadati a livello di file:
I metadati a livello di file si applicano a file specifici e vengono definiti all'interno di ciascun file nell'array dei file. Nell'esempio qui sotto, vengono utilizzati per definire un testo alternativo per l'immagine embroideryText associata al file.
{ "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" } ] } ] } ]}
Annulla Ordine
Ferma e annulla il processo di produzione e spedizione di un ordine. Puoi farlo solo finché lo stato dell’ordine non cambia in "spedito".
Endpoint: POST /{orderCancelUrl}
Questo endpoint può accettare sia l'ID ordine (fornito nella risposta di invio ordine) sia l'ID di riferimento ordine (il tuo ID ordine interno).
Utilizzando l’ID ordine
POST /{orderCancelUrl}/32884a3e-bd09-42be-8225-c5cea7d24611/cancelUtilizzare l’ID di riferimento dell’ordine
POST /{orderCancelUrl}/test/cancelFormato di risposta
{ "code": 200, "message": "OK"}
Aggiorna spedizione
Puoi modificare il metodo di spedizione o aggiornare l'indirizzo di consegna finché l'ordine non passa allo stato "spedito".
Endpoint: PUT /{updateShipmentURL}
Questo endpoint accetta sia l’ID ordine che il riferimento ordine.
Formato della richiesta
{ "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": "" }}Puoi aggiornare il metodo di spedizione, l'indirizzo di spedizione o entrambi. Devi includere almeno uno di questi campi nella richiesta.
Parametri della richiesta
Parametro | Tipologia | Obbligatorio | Descrizione |
shipmentMethodUid | string | Facoltativo* | Nuovo metodo di spedizione (*Devi fornire almeno shipmentMethodUid o shippingAddress) |
indirizzo di spedizione | oggetto | Facoltativo* | Nuovi dettagli dell'indirizzo di spedizione (devi fornire almeno shipmentMethodUid o shippingAddress) |
Formato di risposta
{ "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" }}
Ricevi ordine
Recupera le informazioni su un ordine già esistente.
Endpoint: GET /{getOrderURL}/{order_id}
Puoi usare sia l’ID ordine Gelato che il tuo ID di riferimento ordine.
Formato di risposta
La risposta conterrà informazioni dettagliate sull’ordine, tra cui:
Dettagli dell’ordine (ID, riferimento, stato, ecc.)
"shippingAddress": {
Articoli ordinati con dettagli sul prodotto
Informazioni sulla spedizione (metodo, tracciamento, ecc.)
Informazioni finanziarie
Esempio di risposta (clicca qui)
Esempio di risposta (clicca qui)
{ "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",Indirizzo di spedizione "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" },
Cerca ordini
Recupera l’elenco degli ordini in base ai criteri che scegli.
Endpoint: POST /{searchOrdersURL}
Formato della richiesta
], "fulfillmentStatus": [ "canceled", "delivered" } ],
Parametri della richiesta
Parametro | Tipologia | Obbligatorio | Descrizione |
stato di evasione | string[] | Facoltativo | Filtra per stato di realizzazione dell’ordine |
stato finanziario | string[] | Facoltativo | Filtra per stato finanziario dell'ordine |
ID riferimento ordine | string | Facoltativo | Filtra per il tuo ID ordine interno |
ID di riferimento ordine | string[] | Facoltativo | Filtra per più ID ordine interni |
data di inizio | string | Facoltativo | Filtra per ordini creati dopo questa data (formato ISO 8601) |
data di fine | string[] | Facoltativo | Filtra per ordini creati prima di questa data (formato ISO 8601) |
Paesi | string | Facoltativo | Filtra per codici paese di spedizione |
limite | numero | Facoltativo | Numero massimo di risultati da mostrare (predefinito: 50, massimo: 100) |
offset | numero | Facoltativo | Numero di risultati da saltare per la paginazione (predefinito: 0) |
Formato di risposta
} "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" }, { ],
Gestione degli errori
Quando una richiesta API non va a buon fine, la risposta include un codice di errore e un messaggio che ti aiuta a capire e risolvere il problema. Ecco alcuni degli errori più comuni:
400 richiesta non valida: parametri non validi o mancanti
401 non autorizzato: credenziali di autenticazione non valide o mancanti
404 non trovato: la risorsa richiesta non esiste
429 troppe richieste: hai superato il limite consentito
Errore 500 del server: si è verificato un errore inaspettato sul server
Esempio di risposta di errore:
} "code": 400, "message": "Invalid shipping address: Email is not a valid format" {Per un'integrazione solida, segui le indicazioni della sezione sui limiti di frequenza e assicurati di gestire bene gli errori e i tentativi di nuovo invio.
Serve una mano?
Se hai problemi o domande sull'API, contatta il nostro team di supporto a [email protected].
Includi queste informazioni nella tua richiesta di supporto:
L'endpoint API specifico che stai usando
La tua richiesta (con informazioni sensibili oscurate)
La risposta di errore che hai ricevuto
Eventuali orari rilevanti
Così il nostro team potrà risolvere il tuo problema in modo più rapido ed efficace.