L'API Shipping order create est une API RESTful qui vous permet de créer une commande d'expédition pour générer une étiquette d'expédition et un code de suivi pour un colis.
POST /v1/shipping-orders
Exemple de demande
{ "orderReferenceId": "EXMPL0001234", "currency": "EUR", "options": { "weightUnit": "g", "dimensionUnit": "mm", "label": { "format": "pdf" } }, "partner": { "clientName": "ExampleCustomer" }, "shippingMethod": { "uid": "", "carrier": "", "tier": "standard" }, "receiver": { "person": { "firstName": "Foo", "lastName": "Bar", "company": "", "email": "[email protected]", "phone": "01273552886" }, "address": { "country": "GB", "state": "East Sussex", "city": "Brighton", "postcode": "BN1 8YQ", "addressLine1": "11 London Rd", "addressLine2": "", "addressLine3": "", "street": "London Rd", "houseNumber": "11", "suburb": null }, "customs": { "vatNumber": null } }, "sender": { "person": { "firstName": "", "lastName": "", "company": "Example Company", "email": "[email protected]", "phone": "01666 123456" }, "address": { "country": "DE", "state": "", "city": "Donauwörth", "postcode": "86609", "addressLine1": "Am Wassergraben 11", "addressLine2": null, "addressLine3": null, "street": "Am Wassergraben", "houseNumber": "11", "suburb": null }, "customs": { "vatNumber": "DE123456789000", "iossNumber": null, "eoriNumber": "GB987654321000", "pcccNumber": null, "australianBusinessNumber": null } }, "packages": [ { "packageReferenceId": "EXMPL0001234-0-1", "grossWeight": 810, "netWeight": 760, "length": 229, "width": 200, "height": 36, "boxType": "rectangle", "volumetricWeight": 700, "items": [ { "itemReferenceId": "EXMPL0001234-0-1-ITEM1", "description": "Mug", "value": 18.42, "quantity": 4, "weight": 760, "hsCode": "44199090", "countryOfOrigin": "DE" } ] } ]}Exemple de réponse réussie
{ "orderId": "fb7c0bf6-bdb1-4443-b5db-7263793be32b", "orderReferenceId": "EXMPL0001234", "shippingMethod": { "carrier": "UPS", "uid": "ups_standard_tariff" }, "packages": [ { "packageReferenceId": "EXMPL0001234-0-1", "trackingNumber": "EXMPL0001234TRCKNUM", "trackingUrl": "https://www.ups.com/track?track=yes&trackNums=EXMPL0001234TRCKNUM&loc=en_US&requester=ST", "label": { "fileName": "18437f55ec0cd1b64ae6a0eabf03e21b67a57ea1_UPS.pdf", "fileUrl": "https://s3-eu-west-1.amazonaws.com/printcloud.storage-test/label/18437f55ec0cd1b64ae6a0eabf03e21b67a57ea1_UPS.pdf", "contentType": "application/pdf" }, "documents": [ { "documentType": "invoice", "fileName": "18437f55ec0cd1b64ae6a0eabf03e21b67a57ea1_UPS_invoice.pdf", "fileUrl": "https://s3-eu-west-1.amazonaws.com/printcloud.storage-test/label/18437f55ec0cd1b64ae6a0eabf03e21b67a57ea1_UPS_invoice.pdf", "contentType": "application/pdf" } ], "totalCost": { "value": 2.56, "currency": "EUR" } } ]}Exemple de réponse d'erreur
{ "orderReferenceId": "EXMPL0001234", "code": "PUBLIC_API_ERROR", "message": "Processing error", "detail": { "code": "UPS_API_ERROR", "message": { "status": { "title": "Bad Request", "status": 400, "detail": "0 of 1 shipment successfully created.", "statusCode": 400 }, "items": [ { "sstatus": { "title": "Bad Request", "status": 400, "statusCode": 400 }, "validationMessages": [ { "property": "packages[0].items[0].hsCode", "validationMessage": "Parameter hsCode must be between 4 and 11 characters long.", "validationState": "Error" } ] } ] } }, "errors": [ { "code": "IS_BLANK_ERROR", "reference": "receiver.address.country", "message": "This value should not be blank." }, { "code": "IS_BLANK_ERROR", "reference": "receiver.address.city", "message": "This value should not be blank." }, { "code": "MISSING_FIELD_ERROR", "reference": "packages[EXMPL0001234-0-1][length]", "message": "This field is missing." } ]}Demande
Paramètre | Type | Description |
orderReferenceId (obligatoire) | chaîne | Identifiant unique pour la commande d'expédition. Identifiant fourni par vous. |
Devise (obligatoire) | chaîne | Devise de la commande d'expédition au format à 3 lettres. |
Options (facultatif) | Options | Paramètres facultatifs. |
Partenaire (optionnel) | Partenaire | Détails du partenaire. |
shippingMethod (obligatoire) | ShippingMethod | Détails de la méthode d'expédition. |
destinataire (obligatoire) | Destinataire | Détails du destinataire. |
Expéditeur (obligatoire) | Expéditeur | Détails de l'expéditeur. |
Colis (obligatoire) | Colis[] | Détails du colis. |
Options
Paramètre | Type | Description |
weightUnit (facultatif) | chaîne | Unité de poids. Choix disponibles : g, kg, oz, lb. Par défaut : g. |
Unité de dimension (facultatif) | chaîne | Unité de longueur. Choix disponibles : mm, cm, po. Par défaut : mm. |
Étiquette (facultatif) | Étiquette | Paramètres du format d'étiquette. |
Étiquette
Paramètre | Type | Description |
Format (facultatif) | chaîne | Format d'étiquette. Choix disponibles : pdf, zpl (*). Par défaut : pdf. |
Remarque : Les formats autres que pdf peuvent ne pas être activés pour certains transporteurs.
Partenaire
Paramètre | Type | Description |
Nom du client (facultatif) | chaîne | Expédition du profil client. |
ShippingMethod
Paramètre | Type | Description |
UID (optionnel*) | chaîne | À utiliser pour une méthode d'expédition spécifique, par exemple amazon_shipping_24. |
Transporteur (facultatif) | chaîne | Nom du transporteur, par exemple Amazon, DHL |
Niveau (obligatoire*) | chaîne | Niveau d'option d'expédition. Choix disponibles : standard, express. |
Remarque : *Utilisez tier pour la sélection de transporteur optimisée de Gelato. Si vous utilisez tier, laissez uid vide, et vice versa.
Destinataire
Paramètre | Type | Description |
Personne (obligatoire) | Personne destinataire | Détails personnels du destinataire. |
Adresse (obligatoire) | Adresse | Détails de l'adresse du destinataire. |
Personnalisé (facultatif) | Douanes du destinataire | Détails des douanes du destinataire. |
Expéditeur
Paramètre | Type | Description |
Personne (obligatoire) | Nom de l'expéditeur | Détails personnels de l'expéditeur. |
Adresse (obligatoire) | Adresse | Détails de l'adresse de l'expéditeur. |
Douanes (obligatoire pour les expéditions internationales) | ExpéditeurDédouanement | Détails douaniers de l'expéditeur. |
Personne destinataire
Paramètre | Type | Description |
Prénom (obligatoire) | chaîne | Prénom du destinataire. |
Nom de famille (obligatoire) | chaîne | Nom de famille du destinataire. |
Entreprise (facultatif) | chaîne | Le titre de l'entreprise. |
E-mail (optionnel*) | chaîne | Adresse e-mail de la personne. Cela peut être utilisé pour les notifications d'expédition. |
Téléphone (optionnel*) | chaîne | Numéro de téléphone de la personne. Cela peut être utilisé pour les notifications d'expédition. |
Remarque : *L'e-mail et le téléphone peuvent être des champs obligatoires selon le transporteur.
Nom de l'expéditeur
Paramètre | Type | Description |
Prénom (facultatif) | chaîne | Prénom de l'expéditeur ou de l'expéditrice. |
Nom de famille (optionnel) | chaîne | Nom de famille de l'expéditeur. |
Entreprise (obligatoire) | chaîne | Le nom de l'entreprise expéditrice. |
E-mail (optionnel*) | chaîne | Adresse e-mail de la personne ou de l'entreprise expéditrice. |
Téléphone (optionnel*) | chaîne | Numéro de téléphone de la personne ou de l'entreprise expéditrice. |
Remarque : *L'e-mail et le téléphone peuvent être des champs obligatoires selon le transporteur.
Adresse
Paramètre | Type | Description |
Pays (obligatoire) | chaîne | Code pays au format à 2 lettres. |
État (optionnel*) | chaîne | État / comté / région. |
ville (obligatoire) | chaîne | Ville. |
Code postal (obligatoire) | chaîne | Code postal. |
addressLine1 (obligatoire) | chaîne | Première ligne de l'adresse postale. Doit inclure la rue et le numéro de maison. |
Adresse ligne 2 (facultatif) | chaîne | Deuxième ligne de l'adresse postale. Numéro d'appartement / de bureau / d'étage. |
Ligne d'adresse 3 (facultatif) | chaîne | Troisième ligne de l'adresse postale. |
Rue (optionnel*) | chaîne | Rue (obligatoire pour les adresses en Allemagne). |
Numéro de maison (optionnel*) | chaîne | Numéro de maison (obligatoire pour les adresses en Allemagne). |
Banlieue (optionnel*) | chaîne | Banlieue (obligatoire pour les adresses en Australie/Nouvelle-Zélande). |
Remarque : *Ces champs facultatifs sont obligatoires pour certains pays et transporteurs.
Douanes du destinataire
Paramètre | Type | Description |
vatNumber (facultatif) | chaîne | Numéro de TVA du destinataire. |
ExpéditeurDédouanement
Paramètre | Type | Description |
Numéro de TVA (facultatif*) | chaîne | Numéro de TVA de l'expéditeur. |
Numéro IOSS (optionnel*) | chaîne | Numéro IOSS de l'expéditeur. |
Numéro EORI (facultatif*) | chaîne | Numéro EORI de l'expéditeur. |
pcccNumber (optionnel*) | chaîne | Numéro PCCC de l'expéditeur. |
Numéro d'entreprise australien (optionnel*) | chaîne | Numéro d'entreprise australien de l'expéditeur. |
Remarque : *Selon le pays d'expédition et de réception, ces champs peuvent être obligatoires.
Emballage
Paramètre | Type | Description |
packageReferenceId (obligatoire) | chaîne | ID du colis fourni par le partenaire. |
Poids brut (obligatoire) | nombre | Poids de l'emballage + poids des articles (en grammes par défaut). |
netWeight (optionnel) | nombre | Poids des articles (en grammes par défaut). |
Longueur (obligatoire) | nombre | Longueur du colis (en mm par défaut). |
Largeur (obligatoire) | nombre | Largeur du colis (en mm par défaut). |
Hauteur (obligatoire) | nombre | Hauteur du colis (en mm par défaut). |
volumetricWeight (facultatif) | nombre | Poids calculé en fonction de la taille du colis (en grammes par défaut). |
Type de boîte (facultatif) | chaîne | Forme de la boîte (par exemple, rectangle, tube). |
valeur (requis pour les expéditions internationales) | nombre | Valeur totale de tous les articles du colis (dans la devise sélectionnée). |
articles (obligatoire pour les expéditions internationales) | Article[] | Liste des articles dans le colis. |
Article*
Paramètre | Type | Description |
itemReferenceId (obligatoire) | chaîne | ID de l'article du colis fourni par le partenaire. |
Description (obligatoire) | chaîne | Description de l'article. |
Quantité (obligatoire) | nombre | Quantité de l'article. |
valeur (obligatoire) | nombre | Valeur de l'article (dans la devise sélectionnée). |
Poids (obligatoire) | nombre | Poids de l'article (en grammes par défaut). |
Code SH (obligatoire) | chaîne | Code du Système harmonisé (Wiki). |
Pays d'origine (obligatoire) | chaîne | Code pays au format à 2 lettres où l'article a été produit. |
Remarque : *Tous les paramètres d'article sont requis uniquement pour l'expédition internationale.
Réponse réussie
Paramètre | Type | Description |
orderId | chaîne | Identifiant unique de la commande d'expédition dans notre système. |
identifiant de référence de commande | chaîne | UID unique pour la commande d'expédition fourni par vous. |
shippingMethod | ResponseShippingMethod | Méthode d'expédition utilisée pour la commande d'expédition. |
colis | ResponsePackage[] | Emballages utilisés pour la commande d'expédition. |
ResponseShippingMethod
Paramètre | Type | Description |
transporteur | chaîne | Transporteur utilisé pour créer une commande. |
uid | chaîne | UID du mode d'expédition utilisé pour créer une commande. |
ResponsePackage
Paramètre | Type | Description |
packageReferenceId | chaîne | ID du colis fourni par le partenaire. |
Numéro de suivi | chaîne | Numéro de suivi fourni par le transporteur. |
trackingUrl | chaîne | URL de suivi fournie par le transporteur. |
étiquette | ResponseLabel | Étiquette d'expédition pour la commande d'expédition. |
Documents (optionnel) | ResponseDocument[] | Documents pour la commande d'expédition. |
totalCost (optionnel) | ResponseTotalCost | Coût estimé de l'expédition du colis. |
Étiquette de réponse
Paramètre | Type | Description |
Nom du fichier | chaîne | Nom du fichier de l'étiquette. |
URL du fichier | chaîne | URL pour télécharger l'étiquette. |
Type de contenu | chaîne | Type de contenu de l'étiquette. |
ResponseDocument
Paramètre | Type | Description |
documentType | chaîne | Type de document (par exemple : facture). |
fileName | chaîne | Nom du fichier du document. |
URL du fichier | chaîne | URL pour télécharger le document. |
Type de contenu | chaîne | Type de contenu du document. |
ResponseTotalCost
Paramètre | Type | Description |
Valeur (facultatif) | nombre | Coût estimé de l'expédition du colis. (facultatif) |
Devise (optionnel) | chaîne | Devise |
Réponse d'erreur
Paramètre | Type | Description |
identifiant de référence de commande | chaîne | UID unique pour la commande d'expédition fourni par vous. |
code | chaîne | Code d'erreur. |
message | chaîne | Message d'erreur. |
détail (optionnel) | objet | Message d'erreur détaillé (objet JSON d'une structure arbitraire). |
Erreurs (facultatif) | ResponseErrorDetails[] | Liste d'erreurs. |
ResponseErrorDetails
Paramètre | Type | Description |
code | chaîne | Code d'erreur. |
message | chaîne | Message d'erreur |
Référence (optionnel) | chaîne | ID de référence. |
Étape suivante : 🔗[GCL] API logistique - Créer un brouillon de commande d'expédition
📝 Pas ce dont vous aviez besoin ?
Aidez-nous à améliorer cet article, envoyez-nous un e-mail à [email protected] — veuillez inclure le titre de l'article.