Ordres de transport / Envois
L'ordre de transport est l'entité essentielle pour la planification et l'exécution des envois dans X4fleet. Comme l'entité est très étendue, sa structure de données est présentée en premier, suivie de ses segments les plus importants.
De plus, la plupart des propriétés sont optionnelles, car selon le cas d'utilisation, toutes les données ne sont pas disponibles ou ne sont ajoutées que plus tard dans le processus.
En principe, plus le répartiteur connaît tôt les informations pertinentes pour le transport, mieux il peut planifier à l'avance des ressources telles que le véhicule et le chauffeur. La priorité est :
- Quand et où quelque chose doit-il être chargé
- Quand et où ce quelque chose doit-il être déchargé
- Quelles quantités, volumes et poids doivent être transportés
- Y a-t-il quelque chose de particulier à observer concernant les marchandises, les sites et pendant le transport ?
Endpoints
POST /x4gateway/v1/import/shipment
ainsi que
GET /x4gateway/v1/import/shipment/{id} --> requête GET normale via ID d'envoi
GET /x4gateway/v1/import/shipment --> requête GET via RefID et/ou date d'envoi et/ou système source
GET /x4gateway/v1/import/shipments --> requête GET via plusieurs RefID et/ou système source
DELETE /x4gateway/v1/import/shipment/{id} --> requête DELETE normale via ID d'envoi
DELETE /x4gateway/v1/import/shipments --> requête DELETE via plusieurs ID d'envoi
PUT /x4gateway/v1/import/shipment/{id} --> requête UPDATE via ID d'envoi
PUT /x4gateway/v1/import/shipment --> requête UPDATE via RefID
Request
Comme la structure de la requête est utilisée différemment selon le cas d'utilisation, nous nous en tenons ici à l'application de base. Différents exemples de requêtes peuvent être consultés et copiés plus bas.
Structure de base / aperçu :
[
{
"id": 0, //ID d'envoi (attribué par le système)
"extOrderRefId": "string", //Référence de commande du client
"orderNumber": "string", //Ordre de vente (peut avoir N envois)
"refId": "string", //Référence d'envoi (p. ex. de l'ERP)
"groupId": 0, //Si la commande doit aller dans un sous-groupe spécifique
"source": "string", //Système source, les mêmes RefIds de sources différentes sont autorisés
"client": {[]}, //Client
"provider": {[]}, //Donneur d'ordre
"pickup": {[]}, //Lieu d'enlèvement
"dropoff": {[]}, //Lieu de livraison
"products": [{},], //Positions d'envoi / articles
"datePickup": "datetime", //Date d'enlèvement/de tournée prévue
"status": 0, //Statut d'envoi, ENUM
"fiscalStatus": 0, //Statut de facturation, ENUM
"note": "string", //Remarque d'envoi, texte libre
"customField1": "string", //Champ personnalisé d'envoi, doit d'abord être configuré dans le backend
"specialities": [], //Spécialités d'envoi, doivent d'abord être configurées dans le backend
"skills": [{},], //Compétences du chauffeur, doivent d'abord être configurées dans le backend
"checklists": [{},], //Listes de contrôle pertinentes pour l'envoi, doivent d'abord être configurées dans le backend
"vehicleQualifications": [{},], //Qualifications de véhicule, doivent d'abord être configurées dans le backend
"agreedIncome": 0, //Revenu convenu (remplace le tarif transporteur et les valeurs des positions)
}
]Énumérations utilisées : Statut d'envoi, FiscalStatus.
Client / Provider
Le donneur d'ordre (provider) a soumis l'ordre de transport au mandant X4fleet. Le client est en relation commerciale avec le donneur d'ordre, pas nécessairement avec le mandant X4fleet. Les coûts des marchandises, services et transport sont facturés au donneur d'ordre.
À titre d'exemple, le client a commandé un ordinateur portable auprès du donneur d'ordre. Le donneur d'ordre charge le client Xplanis du transport. L'ordinateur portable est facturé au client par le donneur d'ordre. Le client Xplanis facture quant à lui le transport au donneur d'ordre.
Les segments Provider (donneur d'ordre) et Client (client) sont similaires dans leur structure, cependant un client n'est pas requis dans chaque ordre de transport, c'est pourquoi seul Provider est décrit ci-dessous.
"provider": {
"id": 0, //ID du partenaire commercial (attribué par le système)
"refId": "string", //ID du partenaire commercial depuis l'ERP
"organisation": "string",
"contactName": "string",
"name2": "string",
"clientNumber": "string",
"guSurchargePercent": 0, //Supplément / remise %
"guFuelSurchargePercent": 0, //Supplément carburant %
"guLoadingToolSurchargePercent": 0, //Supplément matériel de chargement %
"guLoadingToolSurchargeFix": 0, //Supplément matériel de chargement absolu
"phone1": "string",
"phone2": "string",
"email": "string",
"location": {
"id": 0, //attribué par le système
"name": "string", //obsolète/deprecated
"streetAddress": "string",
"postCode": "string",
"city": "string",
"countryCode": "string", //code pays à 2 lettres p. ex. CH
"coordinates": { //si aucune adresse n'existe ou qu'elle n'est pas assez précise
"lat": 47.193913278119449, //si aucune coordonnée n'est envoyée, l'adresse est géocodée automatiquement
"lng": 8.523516289875717
},
},
"language": "string", //DE, EN, FR, IT, ES
"contacts": [
{
"id": 0, //attribué par le système
"refId": "string", //Référence à la personne de contact depuis l'ERP
"contactName": "string",
"organisation": "string",
"...": "...", //analogue au partenaire commercial
"isMainContact": true //ce contact est affiché par défaut comme personne de contact
}
],
"poBox": "string", //Case postale
"fax": "string",
"web": "string"
}Les mêmes règles que pour les partenaires commerciaux s'appliquent aux personnes de contact.
Pickup & Dropoff
Décrit le lieu où les marchandises sont chargées/enlevées ou déchargées/livrées.
"pickup": {
"id": 0, //ID du lieu d'enlèvement (attribué par le système)
"shipmentLocation": { //Site ou adresse
"kind": 0, //Type de site, ENUM
"name": "string",
"name2": "string",
"organization": "string",
"contactPhone": "string",
"contactPhone1": "string",
"contactPhone2": "string",
"email": "string",
"contacts": [], //Analogue au partenaire commercial / personne de contact
"location": {}, //Adresse du site, analogue au partenaire commercial
"start": "2025-03-28T15:02:55.359Z", //À partir de quand les marchandises peuvent être enlevées
"end": "2025-03-28T15:02:55.359Z", //Jusqu'à quand les marchandises peuvent être enlevées
"notes": "string" //Remarque d'enlèvement (également visible pour le chauffeur)
},
"dropoff": {}, //Analogue à PickupÉnumérations utilisées : Type de site (kind).
Lors de la création d'un envoi, les remarques enregistrées sur le lieu d'enlèvement ou de livraison sont ajoutées sur une nouvelle ligne à la remarque d'enlèvement ou de livraison (notes). Les remarques de disposition des lieux sont ajoutées à la remarque de disposition de l'envoi (noteHiddenForDriver), d'abord celles du lieu d'enlèvement, puis celles du lieu de livraison. Les remarques vides et les textes déjà contenus dans la remarque de l'envoi ne sont pas ajoutés. Lors de la mise à jour d'un envoi existant, aucune remarque des lieux n'est ajoutée.
Via les propriétés start et end, des fenêtres horaires dans lesquelles l'enlèvement ou la livraison doit avoir lieu peuvent être définies :
- On indique à partir de quand les marchandises peuvent être enlevées (open end)
→ ne transmettre questart - On indique jusqu'à quand les marchandises doivent être enlevées (open
start)
→ ne transmettre queend - Une fenêtre horaire fixe est indiquée, dans laquelle les marchandises doivent être enlevées (between)
→ transmettre les deux - Une heure précise est indiquée, à laquelle exactement les marchandises doivent être enlevées
→ transmettre les deux,startetenddoivent avoir la même valeur
Position de commande & article
"products": [ // N positions de commande
{
"id": 0, //ID de la position d'envoi (attribué par le système)
"product": { //Article/service de la position de commande
"id": 0, //attribué par le système
"refId": "string" //du système client, peut référencer les données de base X4fleet pour utiliser des articles préconfigurés
"name": "string",
"type": "string", //Product, Service, Tool (matériel de chargement), Container (colis)
"unit": "string", //voir la description
"notes": "string",
"description": "string",
"diameter": 0,
"palletCount": 0,
"weight": 0,
"volume": 0,
"width": 0,
"height": 0,
"length": 0,
"centiLiters": 0,
"squareCentimetersPerUnit": 0,
"loadingCentimeters": 0,
"storageLocation": "string",
"isVisibleOnApp": true,
"nameTranslation": {}, //Traduction du nom de l'article DE, FR, IT, EN, ES
"descriptionTranslation": {}, //Traduction de la description de l'article DE, FR, IT, EN, ES
"notesTranslation": {}, //Trad. de la remarque de l'article DE, FR, IT, EN, ES
"code": "string",
"isPilable": true,
},
"requiredQuantity": 0, //Quantité requise
"description": "string",
"sortOrder": 0, //Ordre de tri, si nécessaire
"refStr": "string", //Référence au système client p. ex. position dans l'ordre de vente
"storageLocation": "string", //Emplacement de stockage/de préparation
"barCode": "string",
"pickupNotes": "string",
"dropoffNotes": "string",
"totalPallets": 0, //Nombre de palettes = palette EUR 80x120cm
"totalWeight": 0, //Les dimensions totales sont calculées automatiquement à partir des poids individuels
"totalVolume": 0,
"totalCentiLiters": 0,
"totalSquareCentimetersPerUnit": 0,
"totalLoadingCentimeters": 0,
"totalPrice": 0,
"totalShippingPrice": 0,
"price": 0,
"isExplosive": true,
"isHazardous": true,
"isRefrigerated": true,
"isTire": true,
"code": "string" //p. ex. code article ERP
}
]Des structures de conteneurs peuvent également être représentées, voir Positions
Toutes les unités de produit unit possibles :
- Distances
- Centimeters, Kilometer, LoadingMeters, Meters, Millimeter, RunningMeters
- Surfaces
- SquareDecimeters, SquareMeters
- Volume
- CubicDecimeters, CubicCentimeter, CubicMeters, Deciliter, Liter
- Poids
- Gram, Kilo, Ton
- Temps
- Days, Hours, Minutes
- Unités d'expédition & divers
- Apparat, Bag, Bale, Barrel, BigBag, Bottle, Bundle, Canister, Carton, Cartridge, Cassette, Coil, Colis, Container, Diverse, EinwegPalet, EuroPalet, Flat, Gitterbox, Halbpalet, Kettle, P10, P100, P20, P50, Packaging, Pair, Parcel, Plate, Pole, Poster, Ring, Set, Tin, Tube, Unit
Paramètres d'import pour les ordres de transport
Les paramètres suivants ne peuvent être définis que par les administrateurs Xplanis.
Via Paramètres > Paramètres > Import, il est possible de configurer le comportement lors de l'envoi des ordres de transport et de leur mise à jour.
Les plus utilisés :
Libérer automatiquement les commandes- Souvent utile lorsque les ordres de transport provenant du système client n'ont pas besoin d'être enrichis avec des informations supplémentaires dans X4fleet avant d'être répartis
Règle pour la mise à jour des envoisMise à jour de l'envoi possible à tout moment- c'est-à-dire aussi lorsque l'envoi est déjà en cours d'exécution dans une tournée (non recommandé)L'envoi ne peut plus être mis à jour après l'affectation à une tournée- processus stable au prix de la flexibilité.L'envoi ne peut plus être mis à jour après la libération de la tournée- En cas de modifications pertinentes du lieu d'enlèvement/de livraison, de la date ou des quantités/volumes/poids, un envoi peut « sortir » d'une tournée déjà planifiée. Cela ne devrait être envisagé que si une bonne communication est assurée entre le gestionnaire de l'ordre de vente et le répartiteur, car ici les modifications peuvent perturber la planification du répartiteur
Règle pour la suppression des commandesest le pendant de « Mise à jour des envois »L'envoi ne peut plus être supprimé après l'affectation à une tournée..., après la libération de la tournée..., après le démarrage de la tournée..., après le début du chargement- Selon le processus interne du client, la manière de gérer les annulations/reports spontanés.
Response
La structure de la réponse est analogue à la structure de la requête, et toutes les informations qui ont été envoyées dans le POST, ainsi que les informations ajoutées par le système, sont renvoyées.
À cet égard, l'ID / ID d'envoi est une information importante qui devrait idéalement être conservée dans le système amont.
En outre, la réponse contient le champ troughProcessType (en lecture seule). Pour les ordres de benne, il indique le type de processus : 0 = Place, 1 = Empty, 2 = Change, 3 = Fetch. Pour les envois sans ordre de benne, la valeur est null. Voir aussi Enums.
Exemples de requêtes
[
{
"extOrderRefId": "ExtOrderRefId",
"orderNumber": "OrderNumber",
"provider": {
"refId": "XS0001",
"organisation": "Muster AG",
"contactName": "Max Muster",
"name2": "Anlieferung",
"phone1": "+41 61 123 45 67",
"email": "info@muster-ag.ch",
"location": {
"streetAddress": "Musterstrasse 1",
"postCode": "3006",
"city": "Bern",
"countryCode": "CH",
},
},
"pickup": {
"shipmentLocation": {
"kind": 0,
"name": "PickUp AG - Abholung",
"name2": "Maskus Muster",
"organization": "PickUp AG",
"contactPhone": "+41 78 765 43 21",
"email": "maskus.muster@pickup.com",
"location": {
"streetAddress": "Mustergasse 5",
"postCode": "4001",
"city": "Basel",
"countryCode": "CH",
},
"refId": "XS0002",
},
"start": "2025-04-15T00:00:00.000Z",
"end": "2025-04-20T00:00:00.000Z",
},
"dropoff": {
"shipmentLocation": {
"kind": 1,
"name": "Muster AG - Depot",
"name2": "Lager",
"organization": "Muster AG",
"location": {
"streetAddress": "Musterstrasse 1",
"postCode": "3006",
"city": "Bern",
"countryCode": "CH",
},
"refId": "XS0003",
},
"start": "2025-04-21T00:00:00.000Z",
"end": "2025-04-21T23:59:59.000Z",
},
"datePickup": "2025-04-15T12:41:08.524Z",
"refId": "L0001",
"source": "ERP1",
}
]Les données de base existantes peuvent être référencées au moyen de la RefId. Les valeurs transmises écrasent les données de base. Si une RefId n'est pas déjà enregistrée, elle est créée temporairement ou de manière permanente (selon l'entité et le paramètre d'import).
[
{
"extOrderRefId": "ExtOrderRefId",
"orderNumber": "OrderNumber",
"provider": {
"refId": "XS0001",
"organisation": "Muster AG",
"contactName": "Max Muster",
"name2": "Anlieferung",
"phone1": "+41 61 123 45 67",
"email": "info@muster-ag.ch",
"location": {
"streetAddress": "Musterstrasse 1",
"postCode": "3006",
"city": "Bern",
"countryCode": "CH"
}
},
"pickup": {
"shipmentLocation": {
"kind": 0,
"name": "PickUp AG - Abholung",
"name2": "Maskus Muster",
"organization": "PickUp AG",
"contactPhone": "+41 78 765 43 21",
"email": "maskus.muster@pickup.com",
"location": {
"streetAddress": "Mustergasse 5",
"postCode": "4001",
"city": "Basel",
"countryCode": "CH"
},
"refId": "XS0002"
},
"start": "2025-06-11T00:00:00.000Z",
"end": "2025-06-12T00:00:00.000Z"
},
"dropoff": {
"shipmentLocation": {
"kind": 1,
"name": "Muster AG - Depot",
"name2": "Lager",
"organization": "Muster AG",
"location": {
"streetAddress": "Musterstrasse 1",
"postCode": "3006",
"city": "Bern",
"countryCode": "CH"
},
"refId": "XS0003"
},
"start": "2025-06-12T00:00:00.000Z",
"end": "2025-06-13T00:00:00.000Z"
},
"products": [
{
"product": {
"refId": "ART10001",
},
"requiredQuantity": 5,
"totalWeight": 55000,
},
{
"product": {
"refId": "ART10002",
},
"requiredQuantity": 1,
}
],
"datePickup": "2025-06-11T12:41:08.524Z",
"refId": "L0001",
"source": "ERP1"
}
]Un nombre quelconque de produits peut être transmis ; si le produit peut être référencé (au moyen de la RefId), les données de base enregistrées dans X4fleet sont utilisées. Des valeurs spécifiques, comme par exemple le poids total, peuvent être écrasées. Si le produit avec cette RefId n'existe pas, il est créé temporairement (ou de manière permanente avec le paramètre d'import correspondant).
[
{
"extOrderRefId": "ExtOrderRefId",
"orderNumber": "OrderNumber",
"provider": {
"refId": "XS0001",
"organisation": "Muster AG",
"contactName": "Max Muster",
"name2": "Anlieferung",
"phone1": "+41 61 123 45 67",
"email": "info@muster-ag.ch",
"location": {
"streetAddress": "Musterstrasse 1",
"postCode": "3006",
"city": "Bern",
"countryCode": "CH"
}
},
"pickup": {
"shipmentLocation": {
"kind": 0,
"name": "PickUp AG - Abholung",
"name2": "Maskus Muster",
"organization": "PickUp AG",
"contactPhone": "+41 78 765 43 21",
"email": "maskus.muster@pickup.com",
"location": {
"streetAddress": "Mustergasse 5",
"postCode": "4001",
"city": "Basel",
"countryCode": "CH"
},
"refId": "XS0002"
},
"start": "2025-06-11T00:00:00.000Z",
"end": "2025-06-12T00:00:00.000Z"
},
"dropoff": {
"shipmentLocation": {
"kind": 1,
"name": "Muster AG - Depot",
"name2": "Lager",
"organization": "Muster AG",
"location": {
"streetAddress": "Musterstrasse 1",
"postCode": "3006",
"city": "Bern",
"countryCode": "CH"
},
"refId": "XS0003"
},
"start": "2025-06-12T00:00:00.000Z",
"end": "2025-06-13T00:00:00.000Z"
},
"products": [
{
"product": {
"name": "Montage",
"type": "Service",
"unit": "Hours",
"notes": "auf 15min runden",
"description": "Montagezeit vor Ort",
"code": "SER10001",
"refId": "SER10001",
},
"requiredQuantity": 1,
"dropoffNotes": "auf 15min runden, nicht vergessen!",
}
],
"datePickup": "2025-06-11T12:41:08.524Z",
"refId": "L0001",
"source": "ERP1"
}
]Lors de l'utilisation de produits non prédéfinis, le type de produit peut également être défini. Pour les types de produits disponibles, voir la liste des énumérations.
Messages d'erreur fréquents
- {"code":99,"messages":["There was an general error","SqlDateTime overflow. Must be between 1/1/1753 12:00:00 AM and 12/31/9999 11:59:59 PM."],"RequestId":null,"Id":0}
--> Date ou format de date incorrect. Toutes les dates doivent être indiquées en UTC. - {"code":45,"messages":["Shipment has invalid pickup/dropoff dates. Shipment OrderNumber = XXX."],"RequestId":null,"Id":0}
--> Date ou format de date incorrect. Toutes les dates doivent être indiquées en UTC. - {"code":45,"messages":["Shipment has invalid date. Pickup date should be before dropoff date. Shipment OrderNumber = XXX."],"RequestId":null,"Id":0}
--> La date d'enlèvement doit impérativement être antérieure à la date de livraison. - {"code":99,"messages":["There was an general error","Product unit Days is not available for containers."],"RequestId":null,"Id":0}
--> Nous avons différents types de produits, et toutes les unités de produit ne sont pas disponibles pour tous les types de produits (p. ex. les heures ne sont pas disponibles pour les liquides). Vérifiez l'énumération concernée, sinon contactez notre support. - {"code":7,"messages":["Shipment cannot be inserted because there is already one","property: RefId='XXX', Source='XXX'"],"RequestId":null,"Id":0}
--> Les doublons sont désactivés pour ce groupe, la RefID d'envoi doit être unique par système source (source).