Introduction
Bienvenue dans la documentation de l'API de gestion des commandes. Cette API vous permet de soumettre des commandes, d'annuler des commandes, de récupérer les détails des commandes, de rechercher des commandes et de mettre à jour les adresses ou méthodes d'expédition dans le système GelatoConnect. L'API est organisée selon les principes REST et utilise des méthodes HTTPS standard pour interagir avec les ressources. Toutes les réponses sont renvoyées au format JSON, y compris les erreurs.
Authentification
Toutes les requêtes de l’API de gestion des commandes nécessitent une authentification à l’aide d’une clé API et d’un secret valides, fournis dans l’en-tête de chaque requête. Toutes les communications doivent passer par HTTPS ; les appels effectués via HTTP simple échoueront.
Méthode d’authentification
Ajoutez l’en-tête
X-API-KEYà votre requêteDéfinissez la valeur en utilisant le format :
key:secret
Exemple :
X-API-KEY: your-key:your-secret
Votre clé API et votre secret spécifiques vous seront fournis lors de la configuration d’un connecteur pour votre client.
Limites de taux
L'API impose des restrictions sur le nombre de requêtes qu'un utilisateur ou client peut effectuer dans une période spécifiée. Toutes les requêtes sont comptabilisées dans votre limite personnelle de 100 requêtes par seconde.
Pourquoi les limites de débit existent
Les limites de taux servent plusieurs objectifs importants :
Protection contre l'abus ou la mauvaise utilisation de l'API
Garantir un accès équitable pour tous les utilisateurs
Éviter les interruptions de service causées par un trafic trop important
Logique de nouvelle tentative pour les erreurs de limite de débit
Si vous dépassez la limite de débit de l'API, vous recevrez un code d'état 429. Pour minimiser l'impact sur vos charges de travail, mettez en œuvre ces techniques de nouvelle tentative :
Réessayer : Relancez automatiquement les requêtes échouées. Implémentez une logique de nouvelle tentative dans le code de votre application pour tous les appels API.
Repli exponentiel : Utilisez des temps d'attente progressivement plus longs entre les tentatives pour les réponses d'erreur consécutives. Mettez en place un intervalle de délai maximum et un nombre maximum de tentatives en fonction de l'opération effectuée.
Gigue : Ajoutez un délai aléatoire avant de réessayer les requêtes pour éviter que tous les clients ne réessaient simultanément. Cela aide à répartir la charge et empêche les collisions successives.
Pour plus d'informations sur les stratégies de nouvelle tentative, voir :
Codes de réponse
L'API de gestion des commandes utilise des codes de réponse HTTP conventionnels pour indiquer le succès ou l'échec des requêtes :
2xx Codes : Indiquent un succès
4xx Codes : Indiquent des erreurs structurelles ou de données dans la requête (par exemple, paramètres obligatoires manquants, commande introuvable)
5xx Codes : Indiquent des erreurs de serveur (ces erreurs sont rares)
Points de terminaison API
Soumettre la commande
Soumettez une commande en une seule demande.
Point de terminaison : POST /{submitOrderUrl}
L'URL de base et le point de terminaison spécifique seront fournis lors de la configuration du connecteur.
Format de la demande
{ "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" } ] } ]}Exemple de requête curl (cliquez ici)
Exemple de requête curl (cliquez ici)
curl --location --request POST 'https://api.partner-connect.io/api/your-partner-prefix/order' \--header 'Content-Type: application/json' \\--header 'X-API-KEY : votre-clé:votre-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" } ] } ]}'Principaux paramètres de demande
Paramètre | Type | Obligatoire | Description |
identifiant de référence de commande | chaîne | Obligatoire | Votre identifiant de commande interne |
type de commande | chaîne | Facultatif | Type of order: "order" (default) or "draft" |
devise | chaîne de caractères | Obligatoire | Devise pour la commande (code ISO) |
Devise de vente au détail | chaîne | Facultatif | Devise utilisée pour les prix de vente au détail (pour les commandes transfrontalières) |
Prix de livraison au détail TTC | nombre | Facultatif | Prix de livraison hors TVA (même si le nom du paramètre laisse penser le contraire) |
shipmentMethodUid | chaîne | Facultatif | Méthode(s) d'expédition à utiliser, peut être séparé par des virgules |
adresse de livraison | objet | Obligatoire | Détails de l'adresse de livraison du client |
articles | tableau | Requis | Liste des produits à commander |
éviter les doublons | booléen | Facultatif | Si cette option est activée, la création de commandes en double avec le même orderReferenceId est empêchée. Si un doublon est détecté, un message d’erreur s’affichera au lieu de créer une nouvelle commande. |
"packagingInstructions": [ | tableau | Facultatif | Tableau d'objets d'instructions d'emballage |
Paramètres de l'article
Paramètre | Type | Obligatoire | Description |
itemReferenceId | chaîne de caractères | Obligatoire | Votre identifiant d'article interne |
productUid | chaîne | Obligatoire* | Identifiant de produit GelatoConnect (vous devez renseigner soit le productUid, soit le nom du produit et sa variante) |
Nom du produit | chaîne | Obligatoire* | Nom du produit client (*Soit productUid OU productName+productVariant est requis) |
variante de produit | objet | Obligatoire* | Détails de la variante pour le produit client (obligatoire lorsque vous utilisez productName) |
quantité | nombre | Requis | Nombre d’articles à commander |
prixDeVenteInclTVA | nombre | Optionnel | Prix hors TVA (malgré le nom du paramètre) |
fichiers | tableau | Requis | Liste des fichiers d'impression pour le produit |
Bordure personnalisée | objet | Facultatif | Dimensions de bordure personnalisées pour le produit |
Paramètres du fichier
Paramètre | Type | Obligatoire | Description |
type | chaîne | Requis | Type de fichier. Retrouvez une liste d'options dans le tableau ci-dessous. |
url | chaîne de caractères | Requis | URL accessible au public pour le fichier d'impression |
Type de fichier
Paramètre | Description |
par défaut | Le design est imprimé sur la zone principale du produit. Pour les vêtements, il s'agit de l'avant, tandis que pour les cartes pliées, il s'agit de la couverture et du dos.
Si vous fournissez un PDF de plusieurs pages, le nombre de pages doit correspondre aux zones d'impression car il sera utilisé pour imprimer sur chacune d'entre elles. |
recto | Imprimez le fichier sur le devant du produit. |
retour | Imprimez le fichier au dos du produit. |
couverture | Le fichier pour une couverture de livre |
intérieur du col | Imprimez le fichier sur le col intérieur du vêtement. |
col extérieur | Imprimez le fichier sur le col extérieur du vêtement. |
manche-gauche | Imprimez le fichier sur la manche gauche du vêtement. |
manche droite | Imprimez le fichier sur la manche droite du vêtement. |
à l'intérieur | Imprimez le fichier sur les pages intérieures. |
broderie côté cœur | Brodez le fichier sur le côté gauche de la poitrine du vêtement. |
broderie au centre de la poitrine | Brodez le fichier au centre de la poitrine du vêtement. |
broderie large sur poitrine | Brodez le fichier sur le devant du vêtement. |
broderie manche gauche | Brodez le fichier sur la manche gauche du vêtement. |
broderie sur la manche droite | Brodez le fichier sur la manche droite du vêtement. |
broderie poignet gauche | Brodez le motif sur le poignet gauche du vêtement. |
broderie-poignet-droit | Brodez le fichier sur le poignet droit du vêtement. |
Types de fichiers flexibles pour les produits compatibles avec Workflow
Pour les produits compatibles avec le workflow builder, vous pouvez utiliser n'importe quels noms de types de fichiers personnalisés dans le champ type du tableau files. Cette fonctionnalité simplifie les intégrations API en supprimant la nécessité de mapper les fichiers à des types prédéfinis.
Points clés :
Vous pouvez nommer les types de fichiers librement, comme
default_1,default_2,cover_front,inside_page, etc.Caractères autorisés : lettres (A–Z, a–z), chiffres (0–9), traits de soulignement (_), points (.) et traits d'union (-)
Longueur maximale : 100 caractères
L'unicité du type de fichier s'applique toujours - chaque valeur
typedoit être unique au sein du même tableaufiles
Exemple d'utilisation :
{ "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" } ] } ]}
Paramètres de bordure personnalisée
Paramètre | Type | Obligatoire | Description |
largeurMm | nombre | Requis | Largeur de bordure en millimètres (*Obligatoire lors de l'utilisation de bordure personnalisée) |
hauteurMm | nombre | Obligatoire | Hauteur de la bordure en millimètres (*Obligatoire lors de l'utilisation de customTrim) |
Instructions de paramètres d'emballage
Paramètre | Type | Requis | Description |
"packageItems": [ | tableau | Requis | Articles à inclure dans ce colis |
orderItemReferenceId | chaîne | Obligatoire | Référence à l'article de la commande (doit correspondre à itemReferenceId) |
quantité | nombre | Obligatoire | Quantité de l'article dans ce colis |
"packingSlip": { | objet | Optionnel | Configuration du bordereau d'expédition |
URL du fichier | chaîne | Obligatoire | URL vers le fichier PDF du bordereau d'expédition |
GelatoConnect téléchargera et stockera votre PDF de bordereau d'expédition pour garantir qu'il reste accessible pendant le processus d'emballage, même si l'URL d'origine expire.
Exemple d'utilisation :
{ "orderReferenceId": "ORDER-12345", "orderType": "order", "currency": "USD", "shippingAddress": {...}, "items": [...], "packagingInstructions": [ { "packageItems": [ { "orderItemReferenceId": "ITEM-001", "quantity": 1 } ], "packingSlip": { "fileUrl": "https://example.com/slip.pdf" } } ]}
Migration depuis les bordereaux d'expédition basés sur les métadonnées
Pour les clients qui utilisent actuellement les métadonnées pour envoyer des bordereaux d'expédition, vous pouvez utiliser le modèle ci-dessous pour extraire les URL des bordereaux d'expédition à partir des métadonnées et les convertir au format packagingInstructions, garantissant ainsi un stockage de fichiers persistant par 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 -%}{#-- Sortie JSON mise à jour --#}{ {%- for key, value in payload.items() %} {%- if key != "metadata" %} "##{{ key }}": ##{{ value | tojson }}, {%- endif %} {%- endfor %} "metadata": ##{{ filtered_metadata | tojson }},instructions d'emballage {articles du colis {%- for item in payload.get("items") or [] -%} { "orderItemReferenceId": ##{{ item.itemReferenceId|js }}, "quantity": ##{{ item.quantity }} }{% if not loop.last %},{% endif %}{%- endfor %} ],bordereau d'expédition "fileUrl": "##{{ ns.packing_slip_url }}" } } ]}
Paramètres de l'adresse de livraison
Paramètre | Type | Requis | Description |
pays | chaîne de caractères | Obligatoire | Code pays à deux lettres (ISO 3166-1 alpha-2) |
prénom | chaîne | Obligatoire | Prénom du destinataire |
nom | chaîne | Obligatoire | Nom de famille du destinataire |
Adresse (ligne 1) | chaîne de caractères | Obligatoire | Première ligne de l'adresse |
complément d'adresse | chaîne de caractères | Facultatif | Deuxième ligne de l'adresse postale |
ville | chaîne | Obligatoire | Nom de la ville |
Code postal | chaîne | Obligatoire | Code postal |
état | chaîne | Obligatoire | Code de l’état ou de la province (obligatoire pour les adresses aux États-Unis, au Canada et en Australie) |
chaîne de caractères | Obligatoire* | Adresse e-mail du destinataire | |
téléphone | chaîne de caractères | Obligatoire | Numéro de téléphone du destinataire avec l'indicatif du pays |
companyName | chaîne | Optionnel | Nom de l'entreprise (si applicable) |
estProfessionnel | booléen | Optionnel | Si l'adresse correspond à une entreprise |
Numéro d'identification fiscale fédéral | chaîne | Facultatif | Numéro d'identification fiscale fédéral pour les adresses professionnelles |
identifiant fiscal de l'État | chaîne | Facultatif | Numéro d'identification fiscale pour les adresses professionnelles |
état d'inscription | chaîne | Facultatif | Indiquez l’État où votre entreprise est enregistrée |
Remarques spéciales pour les commandes internationales
Pour les commandes internationales, indiquez le prix de vente du produit et le prix de livraison comme suit :
retailCurrency: Devise dans laquelle les prix de vente sont indiquésretailShippingPriceInclVat: Prix de la livraison hors TVA (ignorez le nom du paramètre)items[i].retailPriceInclVat: Prix total du produit hors TVA (ignorez le nom du paramètre)
Choisir un produit
L’API de soumission de commande peut recevoir les informations produit de deux façons :
Utilisation de
productUid:
"productUid": "frame_product_frs_10x10-inch_frc_oak_frm_wood_frp_w13xt22-mm_gt_plexiglass"
Utilisation de
productNameetproductVariant:
"productName": "Framed Poster","productVariant": { "FrameColour": "Black", "PaperSize": "A3"}N'utilisez pas les deux méthodes dans une même demande de commande.
Choisir une méthode de livraison
Le champ shipmentMethodUid peut accepter :
Identifiants uniques de modes d'expédition spécifiques (par exemple,
fed_ex_2_day)Noms des transporteurs (par exemple,
DHL)Niveaux d’options de livraison (par exemple,
Express)
Vous pouvez proposer plusieurs modes de livraison en les séparant par des virgules, et le système choisira l’option la moins chère.
Format de réponse
{ "id": "32884a3e-bd09-42be-8225-c5cea7d24611", "orderReferenceId": "test", "createdAt": "2024-07-17T10:23:28+00:00"}
Utilisation des métadonnées dans tout GelatoConnect
Les métadonnées fournies aux niveaux de la commande et des articles dans les demandes de commande peuvent être utilisées par plusieurs outils au sein de GelatoConnect et sont également renvoyées dans les postbacks. Cela est particulièrement utile pour ceux qui ont besoin de maintenir la continuité des données entre leurs systèmes.
Métadonnées au niveau de la commande :
Les métadonnées au niveau de la commande s'appliquent à l'ensemble de la commande et sont définies au niveau supérieur de la requête.
{ "orderReferenceId": "ORD-12345", "orderType": "order", "currency": "USD", "metadata": [ { "key": "campaign", "value": "summer_promo" }, { "key": "source", "value": "web" } ], "shippingAddress": {...}, "items": [...]}
Métadonnées au niveau de l'article :
Les métadonnées au niveau de l'article s'appliquent à des articles précis et sont définies dans chaque article de la liste des articles.
{ "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": [...] } ]}
Métadonnées au niveau du fichier :
Les métadonnées au niveau du fichier s'appliquent à des fichiers spécifiques et sont définies dans chaque fichier du tableau files. Dans l'exemple ci-dessous, elles sont utilisées pour définir un texte alternatif pour l'image embroideryText associée au fichier.
{ "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" } ] } ] } ]}
Annuler la commande
Arrêtez et annulez le processus de production et d'expédition d'une commande. Cela n'est possible que jusqu'à ce que le statut de la commande passe à \"expédié\".
Point de terminaison: POST /{orderCancelUrl}
Ce point de terminaison peut accepter soit l'ID de commande (fourni dans la réponse de soumission de commande), soit l'ID de référence de commande (votre ID de commande interne).
Utilisation de l'identifiant de commande
POST /{orderCancelUrl}/32884a3e-bd09-42be-8225-c5cea7d24611/cancelUtilisation de l'identifiant de référence de commande
POST /{orderCancelUrl}/test/annulerFormat de réponse
{ "code": 200, "message": "OK"}
Mettre à jour l'expédition
Modifiez le mode de livraison ou mettez à jour l'adresse de livraison tant que la commande n'est pas passée au statut "expédiée".
Point de terminaison : PUT /{updateShipmentURL}
Ce point de terminaison accepte soit l’ID de commande, soit la référence de commande.
Format de demande
{ "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": "" }}Vous pouvez mettre à jour soit la méthode d'expédition, soit l'adresse de livraison, soit les deux. Au moins l'un de ces champs doit être inclus dans la demande.
Paramètres de requête
Paramètre | Type | Obligatoire | Description |
shipmentMethodUid | chaîne | Facultatif* | Nouvelle méthode d'expédition (*Au moins un des éléments shipmentMethodUid ou shippingAddress doit être fourni) |
Adresse de livraison | objet | Facultatif* | Nouvelles informations d'adresse de livraison (au moins l'un des deux, shipmentMethodUid ou shippingAddress, doit être renseigné) |
Format de réponse
{ "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" }}
Obtenir la commande
Obtenez des informations sur une commande existante.
Point de terminaison : GET /{getOrderURL}/{order_id}
Vous pouvez utiliser soit l’identifiant de commande Gelato, soit votre référence de commande.
Format de réponse
La réponse comprendra des informations détaillées sur la commande, notamment :
Détails de la commande (ID, référence, statut, etc.)
"shippingAddress": {
Articles commandés avec les détails du produit
Informations sur l’expédition (méthode, suivi, etc.)
Informations financières
Exemple de réponse (cliquez ici)
Exemple de réponse (cliquez ici)
{ "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",Adresse de livraison "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" },
Rechercher des commandes
Obtenez la liste des commandes selon des critères précis.
Point de terminaison : POST /{searchOrdersURL}
Format de la demande
], "fulfillmentStatus": [ "canceled", "delivered" } ],
Paramètres de la demande
Paramètre | Type | Obligatoire | Description |
statut de traitement | chaîne[] | Facultatif | Filtrer par statut de traitement des commandes |
statut financier | chaîne[] | Facultatif | Filtrer par statut financier de la commande |
identifiant de référence de commande | chaîne | Facultatif | Filtrez par votre identifiant de commande interne |
Identifiants de référence de commande | chaîne[] | Facultatif | Filtrer par plusieurs identifiants de commande internes |
date de début | chaîne | Optionnel | Filtrer par commandes créées après cette date (format ISO 8601) |
date de fin | chaîne[] | Facultatif | Filtrer par commandes créées avant cette date (format ISO 8601) |
des pays | chaîne | Facultatif | Filtrer par codes pays de livraison |
limite | nombre | Facultatif | Nombre maximum de résultats à afficher (par défaut : 50, maximum : 100) |
Décalage | nombre | Facultatif | Nombre de résultats à ignorer pour la pagination (par défaut : 0) |
Format de réponse
} "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" }, { ],
Gestion des erreurs
Lorsqu'une requête API échoue, la réponse inclut un code d'erreur et un message explicatif pour vous aider à identifier et à résoudre le problème. Voici quelques exemples de situations courantes d'erreur :
400 mauvaise requête : paramètres invalides ou manquants
401 non autorisé : identifiants d’authentification invalides ou manquants
404 introuvable : La ressource demandée n'existe pas
429 Trop de requêtes : Vous avez dépassé la limite autorisée
Erreur serveur 500 : Une erreur inattendue s'est produite sur le serveur
Exemple de réponse en cas d’erreur :
} "code": 400, "message": "Invalid shipping address: Email is not a valid format" {Pour une intégration solide, mettez en place une gestion des erreurs efficace et une logique de nouvelle tentative, comme expliqué dans la section sur les limites de débit.
Besoin d’un coup de main ?
Si vous rencontrez des difficultés ou si vous avez des questions concernant l'API, n'hésitez pas à contacter notre équipe d'assistance à l'adresse suivante : [email protected].
Veuillez inclure les informations suivantes dans votre demande d’assistance :
L'API précise que vous utilisez
Votre demande (avec les informations sensibles masquées)
La réponse d’erreur que vous avez reçue
Tous les horaires pertinents
Cela permettra à notre équipe de résoudre votre problème plus rapidement et efficacement.