Aller au contenu principal

Importation de fichier XML

Si votre système exporte des commandes ou des adresses en XML, vous pouvez les importer avec la fonction Importation de fichiers — de la même manière que les fichiers CSV, mais avec un profil d'importation XML.

La différence par rapport au CSV réside dans la manière dont le profil apprend vos noms de champs :

CSVXML
Colonne Nom du champUne liste déroulante, remplie depuis la ligne d'en-tête d'un fichier exempleUne zone de texte libre — vous saisissez le nom de l'élément ou le chemin
Fichier exemple dans le profilOui (Télécharger le fichier → Traiter le fichier)Pas nécessaire — le profil n'a pas d'étape de téléchargement
StructureColonnes à platLes éléments imbriqués et les attributs sont pris en charge

Créer un profil​

Avant d'importer le fichier, vous devez créer un profil d'importation.

Menu d'importation XML

  1. Allez dans Profils → Adresses ou Expéditions → appuyez sur +
  2. Sélectionnez Type d'import → Adresses ou Expéditions
  3. Ajoutez un Nom du profil (p. ex. Commandes XML)
  4. Sélectionnez le Type de fichier d'importation → XML
  5. Renseignez Elément XML de ligne (balise ou XPath) — l'élément qui se répète une fois par expédition ou par adresse (voir Choisir l'élément de ligne)

Créer un profil XML — formulaire

Le Séparateur décimal et le Délimiteur de valeurs multiples peuvent rester tels quels par défaut (. et ,).

attention

Elément XML de ligne est obligatoire — vous ne pouvez pas continuer sans le renseigner.

L'élément XML de ligne est obligatoire

  1. Appuyez sur Continuer
  2. Renseignez dans la colonne Nom du champ le nom de l'élément ou le chemin de chaque champ que vous souhaitez importer

Mappage des champs XML

remarque

Pour les profils XML, Nom du champ est une zone de texte libre, et non une liste déroulante, et il n'y a pas de bouton Télécharger le fichier / Traiter le fichier. Saisissez le nom exactement tel qu'il apparaît dans votre fichier — voir Comment les noms d'éléments deviennent des noms de champs.

La colonne Fonction peut rester telle quelle.

Si nécessaire, vous pouvez ajouter une Transformation — créée et utilisée lorsqu'il faut modifier les données du fichier XML pour l'importation. Par exemple, lorsque le nom du pays dans votre fichier est «Suisse», mais que notre système a besoin de l'avoir au format ISO 3166-1 alpha-2 («CH»).

Transformation

Une fois que tous les noms des champs obligatoires (et facultatifs) sont saisis, appuyez sur Enregistrer.

Champs d'envoi que vous pouvez mapper​

La liste des champs que vous pouvez remplir est exactement la même que pour le CSV — adresse de l'expéditeur et du destinataire, détails de service, de colis et de douane, avec les mêmes longueurs maximales et les mêmes champs obligatoires. Voir Champs d'envoi que vous pouvez mapper sur la page CSV.

astuce

Le poids est obligatoire pour chaque colis — assurez-vous que votre fichier XML contient un élément ou un attribut de poids (en kg) avant l'importation.

Télécharger le fichier XML​

Menu Importations de fichiers

  1. Allez dans Importations de fichiers
  2. Appuyez sur Importer un fichier en haut à droite

Importer un fichier — bouton

  1. Sélectionnez le Profil (le profil XML créé à l'étape 1)
  2. Téléchargez le fichier .xml et appuyez sur Importer

Dialogue d'importation XML

  1. Appuyez sur Actualiser

Après l'importation — Actualiser

Les informations importées apparaîtront dans votre carnet d'adresses ou vos expéditions. Les lignes qui n'ont pas pu être importées sont listées avec leur message d'erreur, et le reste du fichier est tout de même importé.

Exigences techniques pour le fichier XML​

Le fichier doit être un document XML bien formé portant l'extension .xml, et ne pas dépasser 25 Mo.

Choisir l'élément de ligne​

L'élément XML de ligne indique à l'importation où commence et où se termine une expédition (ou une adresse). Chaque élément correspondant devient une ligne.

Vous pouvez le saisir de deux façons :

Ce que vous saisissezSignificationQuand l'utiliser
Un nom de balise simple, p. ex. shipmentChaque élément portant ce nomVos lignes se trouvent directement dans un document simple
Une expression XPath, p. ex. //order ou /root/data/orders/orderChaque élément sélectionné par l'expressionVos lignes sont imbriquées plus profondément, ou le même nom de balise est utilisé à plusieurs endroits

Pour ce fichier, l'élément de ligne est shipment :

<?xml version="1.0" encoding="UTF-8"?>
<shipments>
    <shipment>
        <receiver_name>Andreas Brauchle</receiver_name>
        <receiver_countryCode>CH</receiver_countryCode>
        <receiver_zipCode>8055</receiver_zipCode>
        <receiver_city>ZÜRICH</receiver_city>
        <receiver_street>Schaufelbergerstrasse 30</receiver_street>
        <service_code>B2B</service_code>
        <weight>2.3</weight>
    </shipment>
    <shipment>
        ...
    </shipment>
</shipments>
danger

Utilisez l'élément qui se répète, et non le conteneur qui l'entoure. Ci-dessus, shipment est correct et shipments est incorrect.

Un conteneur ne correspond qu'une seule fois : tout le fichier se réduit alors à une seule ligne qui ne conserve que les valeurs de la dernière entrée. Rien ne signale cette perte : si cette unique ligne est valide, l'importation est marquée Réussi, et un nombre d'enregistrements n'est affiché que pour les fichiers partiellement importés — un fichier réduit paraît donc parfaitement normal. Si un fichier de 5 entrées en importe 1, c'est la raison.

Pour un fichier d'adresses encadré par <Recipients><Recipient>…, l'élément de ligne est donc Recipient — ou //Recipient, qui le trouve à n'importe quelle profondeur :

Elément XML de ligne défini sur //Recipient

Pour ce fichier, l'élément de ligne est //order (ou /root/data/orders/order) :

<?xml version="1.0" encoding="UTF-8"?>
<root>
    <data>
        <orders>
            <order id="ORD-001">
                <recipient>
                    <address>
                        <name>John Doe</name>
                        <street>Main Street 1</street>
                        <zip>8000</zip>
                        <city>Zurich</city>
                        <country>CH</country>
                    </address>
                    <contact>
                        <email>john@example.com</email>
                    </contact>
                </recipient>
                <parcel weight="2.5" service="B2B">
                    <reference>REF-001</reference>
                </parcel>
            </order>
        </orders>
    </data>
</root>
attention

Si l'élément de ligne ne correspond à rien, l'importation échoue avec «No XML elements matched the configured row element». Vérifiez l'orthographe et la casse — les noms d'éléments XML sont sensibles à la casse.

Comment les noms d'éléments deviennent des noms de champs​

Les noms de champs s'écrivent relativement à l'élément de ligne, avec / entre les niveaux et @ pour les attributs. D'après l'exemple order imbriqué ci-dessus :

Dans le fichierCe que vous saisissez comme champ sourceValeur
Attribut id sur l'élément de ligne@idORD-001
<city> directement sous l'élément de lignecity—
<recipient><address><city>recipient/address/cityZurich
<recipient><contact><email>recipient/contact/emailjohn@example.com
Attribut weight sur <parcel>parcel/@weight2.5
<parcel><reference>parcel/referenceREF-001

Règles applicables à chaque valeur :

  • Les valeurs sont nettoyées des espaces en début et fin, et les caractères invisibles (espaces insécables, espaces de largeur nulle, caractères de contrôle) sont supprimés
  • Les éléments vides (<recipient_name2></recipient_name2> ou <customs_date />) sont considérés comme non fournis
  • Un texte réparti sur plusieurs lignes est réuni en une seule valeur
  • Les éléments que vous ne mappez pas sont simplement ignorés
attention

Restez cohérent au sein d'un même profil : si votre XML est imbriqué, saisissez le chemin complet pour chaque champ. Mélanger un nom de feuille simple (city) avec un chemin (recipient/address/city) dans le même profil peut laisser le premier vide, car pour les fichiers imbriqués la valeur n'est disponible que sous son chemin complet.

Avancé : choisir l'un de plusieurs éléments répétés​

Lorsque le même élément se répète à l'intérieur d'une ligne et que vous avez besoin d'une occurrence précise, ajoutez un prédicat XPath au champ source. Avec :

<shipment id="ORD-001">
    <addresses>
        <address kind="billing">
            <city>Zurich</city>
        </address>
        <address kind="shipping">
            <city>Bern</city>
        </address>
    </addresses>
    <parcels>
        <parcel type="standard" weight="1.0">
            <reference>REF-STD-001</reference>
        </parcel>
        <parcel type="express" weight="2.5">
            <reference>REF-EXP-001</reference>
        </parcel>
    </parcels>
    <items>
        <item>First item</item>
        <item>Second item</item>
    </items>
</shipment>
Champ sourceSélectionneValeur
addresses/address[@kind='shipping']/cityL'adresse de livraison, et non celle de facturationBern
parcels/parcel[@type='express']/@weightLe poids du colis express2.5
parcels/parcel[@type='express']/referenceLa référence du colis expressREF-EXP-001
items/item[1]Le premier élément par positionFirst item
attention

Les chemins de champs doivent rester à l'intérieur de la ligne. Un chemin commençant par / ou // est refusé lors de l'enregistrement du profil, avec «Mapping XPaths must be relative to the root row element» — cela évite qu'une ligne reprenne par accident les données d'une autre. Les chemins absolus et // sont autorisés uniquement dans le paramètre de l'élément de ligne lui-même.

XML avec espaces de noms​

Si vos éléments portent un préfixe d'espace de noms (<ns:order>), sélectionnez l'élément de ligne par son nom local plutôt que par son préfixe :

//*[local-name()='order']

Les chemins de champs peuvent s'écrire de la même façon, p. ex. *[local-name()='recipient']/*[local-name()='city'].

Encodage des caractères​

Les fichiers XML déclarent eux-mêmes leur encodage sur la première ligne :

<?xml version="1.0" encoding="UTF-8"?>
Paramètre Encodage du profilCe qui se passe
Détecter automatiquement (recommandé pour XML)L'encodage indiqué dans la déclaration XML est utilisé
Un encodage précis (UTF-8, ISO-8859-1, Windows-1250/1251/1252)Cet encodage est utilisé
astuce

Réglez l'Encodage du profil sur Détecter automatiquement et veillez à ce que la déclaration de votre fichier soit correcte. Si vous choisissez un encodage précis, il doit correspondre au fichier — sinon les caractères spéciaux sont altérés (Müller devient Müller).

Vous pouvez également remplacer l'encodage pour un seul fichier avec Encodage d'importation dans le dialogue Importer un fichier, sans modifier le profil — laissez Utiliser le paramètre du profil pour conserver la valeur du profil.

Paramètres de configuration XML​

ParamètreTypeDescriptionExemples de valeurs
xmlTagChaîneL'élément de ligne — nom de balise simple ou XPathshipment, //order
decimalSeparatorChaîneSéparateur décimal pour les nombres tels que le poids. (par défaut) ou ,
multiValueDelimiterChaîneSéparateur au sein d'un élément contenant plusieurs valeurs, p. ex. des codes d'option, (par défaut), ;, |

Poids avec un point (decimalSeparator = .) :

<weight>2.5</weight>

Poids avec une virgule (decimalSeparator = ,) :

<weight>2,5</weight>

Plusieurs codes d'option dans un seul élément (multiValueDelimiter = ,) :

<option_codes>136,140</option_codes>

Restrictions de sécurité​

Pour des raisons de sécurité, l'importation rejette les fichiers contenant une définition de type de document (<!DOCTYPE ...>) ou des entités personnalisées, et ne charge jamais de contenu référencé depuis l'extérieur du fichier. Exportez vos données sans DTD.

Problèmes courants et solutions​

«No XML elements matched the configured row element»

L'élément de ligne du profil n'existe pas dans le fichier. Ouvrez le fichier dans un éditeur de texte et vérifiez l'orthographe exacte et la casse de l'élément qui se répète. Si vos lignes sont imbriquées plus profondément, utilisez un XPath tel que //order au lieu d'un nom de balise simple.

Un champ mappé reste vide

Le texte du champ source ne correspond pas exactement au fichier. Vérifiez que vous avez saisi le chemin complet relatif à l'élément de ligne (recipient/address/city, et non city), que les attributs commencent par @ (parcel/@weight), et que la casse correspond.

«Invalid content type for XML»

Le fichier téléchargé n'a pas été reconnu comme du XML. Assurez-vous qu'il porte l'extension .xml et qu'il commence par une déclaration XML ou un élément racine correct — un fichier réellement CSV ou texte renommé en .xml est rejeté.

«Failed to parse XML file»

Le fichier n'est pas bien formé (balise non fermée, & isolé, export tronqué) ou contient une déclaration <!DOCTYPE ...>. Ouvrez-le dans un navigateur ou un éditeur XML — il indiquera la première ligne incorrecte. Échappez & en &amp; et < en &lt;.

«Mapping XPaths must be relative to the root row element»

Un chemin de champ commence par / ou //. Supprimez les barres obliques initiales pour que le chemin soit relatif à l'élément de ligne : recipient/address/city au lieu de //city.

Les caractères spéciaux s'affichent mal — p. ex. Müller apparaît comme Müller

L'encodage du profil ne correspond pas au fichier. Réglez Encodage sur Détecter automatiquement pour laisser la déclaration XML décider, ou choisissez l'encodage réellement utilisé pour enregistrer votre fichier.

Le poids n'est pas reconnu comme un nombre

Votre signe décimal ne correspond pas au profil. Réglez le Séparateur décimal en fonction du fichier : une virgule (,) si le fichier écrit 2,5, un point (.) s'il écrit 2.5.

Moins d'enregistrements ont été importés que le fichier n'en contient

L'élément de ligne désigne le conteneur au lieu de l'élément qui se répète, donc tout le fichier a été lu comme une seule ligne. Comparez les deux noms d'éléments dans votre fichier — pour <shipments><shipment>…, l'élément de ligne est shipment. Voir l'avertissement sous Choisir l'élément de ligne.

Seules certaines lignes ont échoué

C'est le comportement attendu : chaque ligne est importée séparément, et une ligne qui échoue à la validation (poids manquant, pays inconnu, code postal invalide) est listée comme échouée avec son message d'erreur, tandis que les autres lignes sont importées. Corrigez ces lignes et importez à nouveau le fichier.

Le fichier est alors marqué Partiellement importé, avec Valeurs incorrectes et le nombre de lignes concernées. Ouvrez-le pour voir une entrée par ligne échouée, chacune avec le motif et une vue Données brutes des valeurs lues :

Fichier partiellement importé avec des erreurs

Dans l'exemple ci-dessus, le fichier utilisait des codes pays numériques (528, 276) alors que le système attend un code ISO à deux lettres — exactement le genre d'écart qu'une Transformation sur le champ pays corrige.

Liste de contrôle avant l'importation​

Avant d'importer, vérifiez :

  • Le fichier est un XML bien formé et porte l'extension .xml
  • Aucune déclaration <!DOCTYPE ...> dans le fichier
  • La déclaration XML indique le bon encodage, et l'Encodage du profil est sur Détecter automatiquement
  • L'élément de ligne du profil correspond à l'élément qui se répète dans le fichier, et non à son conteneur (casse exacte)
  • Après l'importation, le nombre d'enregistrements correspond au nombre d'entrées du fichier
  • Chaque champ source mappé est écrit relativement à l'élément de ligne, avec / pour les niveaux et @ pour les attributs
  • Tous les champs obligatoires sont mappés — nom du destinataire, rue, code postal, ville, pays et poids
  • Le poids est en kg, et le séparateur décimal correspond au profil
  • Les caractères spéciaux (ä, ö, ü, é) s'affichent correctement dans un éditeur de texte
  • La taille du fichier est inférieure à 25 Mo