Construire un fichier en XML pour la création et mise à jour d’annonces

  • Documentation

    Table des matières

    1. Structure générale
      1. Entête
      2. Items
      3. Produits, annonces, images, promotions et frais de port
    2. Format des attributs
      1. Produits, annonce et images
      2. Format des différents attributs
      3. Statut Reconditionné
      4. Campagnes produit et soldes
      5. Expédition et retrait sur place
      6. Frais de port / Rakuten Expédition / Retrait en Magasin
        1. Ajouter le poids du colis
        2. Gestion des frais de port par annonce
        3. Indiquer la disponibilité (Quantités) en Point de Retrait en Magasin (Click&Collect)
    3. Règles d’implémentation
      1. Modification d’une annonce
      2. Création d’une annonce sur un produit déjà chez Rakuten France
      3. Création produit + annonce
      4. Modification de produit
    4. Questions les plus fréquentes

    1. Structure générale

    1.1. Entête

    Tout d’abord, votre fichier doit commencer par une de ces balises décrivant votre XML:

    • <?xml version=’1.0′ encoding=’ISO-8859-1′?>
    • <?xml version=’1.0′ encoding=’UTF-8′?>

    Seul ces 2 encodages sont acceptés, et vos textes seront interprétés suivant cet encodage. Si votre fichier est encodé en UTF-8, pensez à le sauvegarder sans BOM (l’indicateur d’ordre des octets).

    1.2. Items

    Chaque item que vous voulez modifier se trouve dans une balise <item>.
    Tous les <item> sont entourés d’une balise <items>.

    <?xml version=”1.0″ encoding=”ISO-8859-1″?>
    <items>
    <item>
    </item>
    <item>
    </item>
    <item>
    </item>
    <item>
    </item>
    <item>
    </item>
    <item>
    </item>
    <item>
    </item>
    <item>
    </item>
    <item>
    </item>
    <item>
    </item>
    <item>
    </item>
    <item>
    </item>

    </items>

     

    1.3. Produits, annonces, images, promotions et frais de port

    Chaque item peut contenir ensuite au maximum 6 sections:

    Balise Description
    alias Alias du type de produit (uniquement pour la création de produit).
    Les types de produits sont fournis par le webservice ProductTypes.
    product Balise contenant les attributs produits
    advert Balise contenant les attributs annonces
    media Balise contenant les attributs média
    campaigns Balise contenant les attributs campagne produit
    shipping Balise contenant les attributs frais de port

     

    Mis à part la balise <alias>, toutes les autres sections sont entourées par une balise <attributes>.

     

    <?xml version=”1.0″ encoding=”ISO-8859-1″?>
    <items>
    <item>
    <alias>
    </alias>
    <attributes>
    <product>
    </product>
    <advert>
    </advert>
    <media>
    </media>
    <campaigns>
    </campaigns>
    <shipping>
    </shipping>
    </attributes>
    </item>
    </items>

    2. Format des attributs

    2.1. Produits, annonce et images

    Dans chacune de ces 3 sections, les attributs sont fournis par le webservice ProductTypeTemplate.

    Balise Description
    attribut Balise contenant chaque attribut
    key Clé de l’attribut
    value Valeur de l’attribut
    unit Unité de la valeur (Si demandé dans le webservice ProductTypeTemplate)

     

    Voici la structure de ces balises pour mettre un attribut.

     

    <items>
    <item>
    <attributes>
    <advert>
    <attribute>
    <key> </key>
    <value> </value>
    <unit> </unit>
    </attribute>
    </advert>
    </attributes>
    </item>
    </items>

    2.2. Format des différents attributs

    2.2.1. Format de type « Text »

    Les attributs de type « Text » n’ont pas de restriction sur le format.
    Attention toutefois à protéger vos valeurs avec un <![CDATA[xxx]]>, si vous envoyez des valeurs non compatibles XML.

    2.2.2. Format avec <hasvalues = 1>

    Les attributs avec des listes fermées (détectés avec la balise <hasvalues>) doivent être envoyés avec une valeur obligatoire (lire la liste des valeurs dans la balise <valueslist>).
    Pour faire apparaitre la liste des valeurs, utilisez le Webservice ProductTypeTemplate (avec le scope=VALUES).
    Si votre valeur n’existe pas, merci de la demander à fr-validation.produits@mail.rakuten.com en indiquant votre type de produit et votre attribut. Toutes les valeurs ne seront pas acceptées pour des raisons de référencements. Merci donc de vous rapprocher au mieux des valeurs disponibles afin d’être bien référencé.

    2.2.3. Format de type « Boolean »

    Les attributs de type « Boolean » doivent avoir une valeur égale à 0 ou 1

    2.2.4. Format de type « Number »

    Les attributs de type « Number » sont des nombres. Le séparateur décimal peut être la virgule ou le point.

    2.2.5. Format de type « Date »

    Les attributs de type « Date » correspondent à des dates. Leur format est JJ/MM/AAAA.

    2.2.6. Attribut qualité (code : <state>)

    L’attribut qualité doit être envoyé sous forme de code :

    Qualité Code
    Neuf 0
    Comme neuf 10
    Très bon état 20
    Bon état 30
    Etat correct 40
    Hors service 50

    2.2.7. Attribut Image (code : <image_url>)

    Les images doivent être fournies sous formes d’URL. Si vous avez plusieurs images, vous pouvez séparer les URL avec le séparateur |
    Les images sont importées indépendamment des données produits/annonces.

    2.3. Statut Reconditionné

    La balise “refurbished” dans le nœud “Advert” permet d’activer ou désactiver le Reconditionné avec les valeurs “true” (activer) ou “false” (désactiver).

    2.4. Campagnes produit et soldes

    Contrairement aux autres attributs produits/annonces, il est possible d’associer plusieurs campagnes à une annonce.
    Pour cela, il faut dupliquer le nœud « campaign », et y associer le numéro de la campagne visible dans votre interface marchand (Colonne 1 : ID)

     

    Seul l’attribut <key>productsCampaignId</key> est obligatoire.

     

    Règles de gestion:

    • Si vous indiquez uniquement l’attribut <key>productsCampaignId</key>, alors la promotion appliquée sera la promotion configurée dans votre interface marchand.
    • Si vous indiquez les attributs <key>productsCampaignRefPrice</key> (Prix de référence) et <key>productsCampaignPct</key> (Pourcentage de réduction) alors le prix “promo” sera calculé avec ces 2 paramètres.
    • Si vous indiquez les attributs <key>productsCampaignRefPrice</key> (Prix de référence) et <key>productsCampaignPrice</key> (Prix “promo”) alors le pourcentage de réduction sera calculé avec ces 2 paramètres.

     

    <?xml version=”1.0″ encoding=”ISO-8859-1″?>
    <items>
    <item>
    <attributes>
    <advert>
    <attribute>
    <key>sellerReference</key>
    <value>3069</value>
    </attribute>
    </advert>
    <campaigns>
    <!– Example 1: Only with the “Product Campaign ID” –>
    <campaign>
    <attribute>
    <key>productsCampaignId</key>
    <value>11012</value>
    </attribute>
    </campaign>
    <!–
    Example 2: With the
    – “Product Campaign ID”
    – “Products Campaign Reference Price”
    – “Products Campaign Percentage”
    –>
    <campaign>
    <attribute>
    <key>productsCampaignId</key>
    <value>11017</value>
    </attribute>
    <attribute>
    <key>productsCampaignRefPrice</key>
    <value>100</value>
    </attribute>
    <attribute>
    <key>productsCampaignPct</key>
    <value>20</value>
    </attribute>
    </campaign>
    <!– Example 3: With the
    – “Product Campaign ID”
    – “Products Campaign Reference Price”
    – “Products Campaign Selling Price”
    –>
    <campaign>
    <attribute>
    <key>productsCampaignId</key>
    <value>11017</value>
    </attribute>
    <attribute>
    <key>productsCampaignRefPrice</key>
    <value>100</value>
    </attribute>
    <attribute>
    <key>productsCampaignPrice</key>
    <value>80</value>
    </attribute>
    </campaign>
    </campaigns>
    </attributes>
    </item>
    </items>

    2.5. Expédition et retrait sur place

    Afin de configurer le retrait sur place, trois nouveaux attributs sont disponibles dans le webservice ProductTypeTemplate (depuis la version 2015-02-02):

    • <key>shipping</key>: permet de définir à l’annonce si elle est disponible en mode expédition et/ou retrait sur place. La valeur par défaut est “Expédition“.
    • <key>zipcode</key>: permet de définir le code postal du retrait sur place (obligatoire pour le mode retrait sur place)
    • <key>phoneNumber</key>: permet de définir le téléphone du retrait sur place (obligatoire pour le mode retrait sur place)

    Vous devez ensuite envoyer votre fichier XML avec le webservice GenericImportFile (à partir de la version 2015-02-02).
    Le retrait sur place n’est autorisé que pour les marchands français.

     

    <attribute>
    <key>shipping</key>
    <value>Expédition</value>
    <value>Retrait</value>
    </attribute>

    2.6. Frais de port

    Les frais de port Rakuten France sont sur 3 niveaux possibles:

    1. la grille par défaut Rakuten France
    2. la personnalisation par poids (contacter votre chargé de compte pour la configuration)
    3. la personnalisation par annonce / zone de livraison / mode de livraison (contacter votre chargé de compte pour l’activation)

    Attention:
    La personnalisation des frais de port par annonce, ainsi que le mode de livraison express sont soumis à l’activation par votre chargé de compte commercial.
    Afin de vérifier vos droits, utiliser le webservice GetAvailableShippingTypes et vérifier l’existence de ces balises.

    2.6.1. Ajouter le poids du colis (personnalisation par poids)

    Afin d’indiquer le poids de votre colis, vous devez ajouter une balise <package_weight> dans la section <shipping>.
    Le poids doit être ajouté en grammes sans décimales.

     

    <?xml version=”1.0″ encoding=”ISO-8859-1″?>
    <items>
    <item>
    <attributes>
    <advert>
    <attribute><key>sellerReference</key><value><![CDATA[SKU1]]></value></attribute>
    </advert>
    <shipping>
    <package_weight>30</package_weight>
    </shipping>
    </attributes>
    </item>
    </items>

    2.6.2. Gestion des frais de port par annonce

    La gestion des frais de port par annonce se fait suivant 3 critères:

    • La zone de livraison
      • FRANCE
      • FRANCE_DROM_COM
      • EUROPE
      • WORLD
    • Le mode de livraison
      • NORMAL
      • RECOMMANDE
      • SUIVI (disponible pour la France uniquement)
      • EXPRESS_DELIVERY (disponible pour la France uniquement)

      Vous avez la possibilité de désactiver certains modes de livraison pour certaines zones de livraison.

    • Suivant une règle de frais de port dégressifs
      • Les frais de port “leader” correspondent aux frais de port appliqués si la commande ne comporte qu’un seul produit ou aux frais de port les plus élevés en cas de commande multi-produits.
      • Les frais de port “follower” correspondent à des frais de port dégressifs s’ajoutant pour chaque produit supplémentaire de la commande.
        Vous pouvez désactiver cette règle de frais de port degressifs en indiquant que vos frais de port “leader” sont égaux aux frais de port “follower”.
      • Les frais de port “leader” doivent être supérieur à 0. Les frais de port “follower” doivent être supérieurs ou égal à 0. Contacter votre chargé de compte, si vous souhaitez mettre en place une livraison gratuite.
      • Les frais de port “leader” doivent être supérieurs ou égaux aux frais de port “follower”.
      • Le séparateur de centime est le point.
    • Si l’autorisation est activée, un des 3 modes suivant est obligatoire:
      • Recommandé
      • Express
      • un mode personnalisé
    • Les modes prépayés (Chronopost / So colissimo) et le retrait ne sont pas personnalisables (activables/désactivables dans votre interface marchand).
    • Afin d’activer/désactiver vos modes d’expédition, rendez-vous dans votre interface marchand

     

    FRANCE FRANCE_DROM_COM EUROPE WORLD
    Modes classiques NORMAL OK OK OK OK
    RECOMMANDE OK OK OK OK
    SUIVI OK
    EXPRESS_DELIVERY Nécessite l’activation de votre chargé de compte commercial
    MONDIAL_RELAY
    Modes personnalisés MODE_1 OK
    MODE_2 OK
    MODE_3 OK
    etc… OK

     

    Modes personnalisés : Afin de connaitre les modes personnalisés qui vous sont attribués, il faut utiliser le webservice GetAvailableShippingTypes. Pour avoir d’autres modes d’expédition personnalisés, merci de contacter votre chargé de compte commercial.

     

    Si vous ne souhaitez pas utiliser un certain mode dans une zone de livraison, il est nécessaire de le mentionner explicitement en utilisant la balise <authorization>.
    Si vous ne faites pas de configuration pour un certain mode de livraison, alors la grille globale (ou la grille par défaut) configurée par votre chargé de compte sera appliquée.

     

    Voici la liste des différentes balises à utiliser, ainsi que leur signification

    Balise Description
    configuration Configuration des frais de port par annonce
    zone Zone de livraison (cf liste ci-dessus)
    type Configuration d’un mode de livraison dans une zone de livraison
    name Nom du mode de livraison (cf liste ci-dessus)
    authorization Activation ou non du mode de livraison dans la zone de livraison (0 ou 1)
    leader_price Frais de port primaire (leader). IMPORTANT: Il doit être supérieur à 0
    follower_price Frais de port secondaire (follower). Peut être égal à zéro
    contract_level Niveau de service minimum (uniquement pour Mondial Relay)
    Valeurs possibles:

    • 24R
    • 24L
    • 24X
    • DRI

     

    Si l'<authorization> est activée, toutes les autres balises sont obligatoires.

    Frais de port gratuits : Si vous souhaitez activer le frais de port gratuit, vous devez contacter votre chargé de compte afin d’activer cet option. Sachez qu’il n’est pas possible de mettre un prix leader=0, le prix leader doit être toujours > 0 (nombre réel supérieur à 0). L’option gratuite (si elle est active) se rapportera toujours sur le mode d’envoi le moins cher.

     

    <?xml version=”1.0″ encoding=”ISO-8859-1″?>
    <items>
    <item>
    <attributes>
    <advert>
    <attribute><key>sellerReference</key><value><![CDATA[FG4562RFZR]]></value></attribute>
    </advert>
    <shipping>
    <configuration>

    <zone>
    <name>FRANCE</name>
    <type>
    <name>NORMAL</name>
    <authorization>1</authorization>
    <leader_price>20.33</leader_price>
    <follower_price>10.44</follower_price>
    </type>
    <type>
    <name>SUIVI</name>
    <authorization>0</authorization>
    </type>
    <type>
    <name>RECOMMANDE</name>
    <authorization>1</authorization>
    <leader_price>55.55</leader_price>
    <follower_price>11.11</follower_price>
    </type>
    <type>
    <name>EXPRESS_DELIVERY</name>
    <authorization>1</authorization>
    <leader_price>66.66</leader_price>
    <follower_price>22.22</follower_price>
    </type>
    </zone>

    <zone>
    <name>FRANCE_DROM_COM</name>
    <type>
    <name>NORMAL</name>
    <authorization>1</authorization>
    <leader_price>22.22</leader_price>
    <follower_price>14.44</follower_price>
    </type>
    <type>
    <name>RECOMMANDE</name>
    <authorization>1</authorization>
    <leader_price>99.40</leader_price>
    <follower_price>10.99</follower_price>
    </type>
    </zone>

    <zone>
    <name>EUROPE</name>
    <type>
    <name>NORMAL</name>
    <authorization>1</authorization>
    <leader_price>88.88</leader_price>
    <follower_price>77.77</follower_price>
    </type>
    <type>
    <name>RECOMMANDE</name>
    <authorization>0</authorization>
    </type>

    </zone>

    <zone>

    <name>WORLD</name>
    <type>
    <name>NORMAL</name>
    <authorization>1</authorization>
    <leader_price>44.44</leader_price>
    <follower_price>33.33</follower_price>
    </type>
    <type>
    <name>RECOMMANDE</name>
    <authorization>0</authorization>
    </type>

    </zone>

    </configuration>
    </shipping>
    </attributes>
    </item>
    </items>

     

    2.6.4. Indiquer la disponibilité en Point de Retrait en Magasin (Click&Collect)

    Vous pouvez ainsi définir une disponibilité pour tous les modes d’expédition, indépendamment des disponibilités en magasin comme dans l’exemple ci-dessous. Afin de définir les points de retrait, vous devez contacter l’équipe commerciale.

    IMPORTANT : Vous devez vous engager à mettre à disposition le produit sous 2h. Le frais de port associé à un article commandé avec l’option retrait en magasin est gratuit.

     

    <?xml version=”1.0″ encoding=”ISO-8859-1″?>
    <items>
    <item>
    <attributes>
    <advert>
    <attribute>
    <key>sellerReference</key>
    <value>ZS7119A99</value>
    </attribute>
    <attribute>
    <key>qty</key>
    <value>1</value>
    </attribute>
    </advert>
    <pickupStores>
    <pickupStore>
    <pickupStoreId>C4568</pickupStoreId>
    <qty>2</qty>
    </pickupStore>
    <pickupStore>
    <pickupStoreId>C4569</pickupStoreId>
    <qty>0</qty>
    </pickupStore>
    </pickupStores>
    </attributes>
    </item>
    </items>

     

    3. Règles d’implémentation

    3 actions sont possibles pour chacun des items du flux XML.
    Il n’est pas possible de modifier des attributs produits (<product>) et images (<media>) pour le moment.

    3.1. Modification d’une annonce

    Afin de modifier une annonce, vous devez indiquer l’attribut ci-dessous :

    • SKU Vendeur: <key>sellerReference</key>

    Tous les autres attributs <advert> de votre flux modifieront chacun des attributs de l’annonce.

     

    <?xml version=”1.0″ encoding=”ISO-8859-1″?>
    <items>
    <item>
    <attributes>
    <advert>
    <attribute>
    <key>state</key>
    <value>10</value>
    </attribute>
    <attribute>
    <key>sellerReference</key>
    <value>PM011</value>
    </attribute>
    </advert>
    </attributes>
    </item>
    <item>
    <attributes>
    <advert>
    <attribute>
    <key>sellingPrice</key>
    <value>50</value>
    </attribute>
    <attribute>
    <key>qty</key>
    <value>10</value>
    </attribute>
    <attribute>
    <key>sellerReference</key>
    <value>PM012</value>
    </attribute>
    </advert>
    </attributes>
    </item>
    <item>
    <attributes>
    <advert>
    <attribute>
    <key>sellerReference</key>
    <value>PM013</value>
    </attribute>
    <attribute>
    <key>comment</key>
    <value>Commentaire Modifié</value>
    </attribute>
    <attribute>
    <key>qty</key>
    <value>1</value>
    </attribute>
    </advert>
    </attributes>
    </item>
    </items>

     

    Nouveau: Depuis la version 2012-09-11, il n’est plus nécessaire de mettre la balise <alias> pour la modification d’une annonce

    3.2. Création d’une annonce sur un produit déjà chez Rakuten France

    Afin de créer une annonce sur un produit déjà existant, vous devez indiquer tous les attributs <advert> obligatoires.
    Ensuite, le matching sur le produit se fait sur l’un des 2 attributs <product> suivants:

    1. Un code-barres (EAN, ISBN):<key>codebarres</key> (tous les produits sauf privés)
    2. Référence privée : <key>submitterreference</key> (pour les vêtements, chaussures, mobilier, décoration et bijoux)

     

    Selon le type de produit, les références utilisables (parmi les 2 précédentes) apparaissent dans le Webservice Modèle produit.

     

    <?xml version=”1.0″ encoding=”ISO-8859-1″?>
    <items>

    <item>
    <attributes>
    <product>
    <attribute>
    <key>codebarres</key>
    <value>0000000000000</value>
    </attribute>
    </product>

    <advert>

    <attribute>
    <key>state</key>
    <value>20</value>
    </attribute>

    <attribute>
    <key>comment</key>
    <value>Cartes téléphoniques non fournies.</value>
    </attribute>

    <attribute>
    <key>sellingPrice</key>
    <value>366</value>
    </attribute>

    <attribute>
    <key>qty</key>
    <value>1</value>
    </attribute>

    <attribute>
    <key>sellerReference</key>
    <value>PM012</value>
    </attribute>

    </advert>

    </attributes>
    </item>

    <item>
    <attributes>
    <product>
    <attribute>

    <key>submitterreference</key>
    <value>LT001</value>
    </attribute>
    </product>
    <advert>
    <attribute>
    <key>state</key>
    <value>0</value>
    </attribute>
    <attribute>
    <key>comment</key>
    <value>Test</value>
    </attribute>
    <attribute>
    <key>sellingPrice</key>
    <value>5499</value>
    </attribute>
    <attribute>
    <key>qty</key>
    <value>3</value>
    </attribute>
    <attribute>
    <key>sellerReference</key>
    <value>PM011</value>
    </attribute>
    </advert>

    </attributes>
    </item>

    </items>

     

    Nouveau: Depuis la version 2012-09-11, il n’est plus nécessaire de mettre la balise <alias> pour la création d’une annonce.

    3.3. Création produit + annonce

    Afin de créer un produit et une annonce sur Rakuten France, l’ensemble des attributs obligatoires (produit + annonce) est nécessaire.
    Il est toutefois conseillé de remplir tous les attributs, afin d’être mieux référencé.

     

    Afin de créer un produit, il faut obligatoirement (en plus des attributs obligatoires) un des 2 attributs suivants :

    • Un code-barres (EAN, ISBN): <key>codebarres</key>
    • Une référence privée :<key>submitterreference</key>

    3.4. Modification de produit

    La modification de données produit (balise <product> dans le flux) est soumise à certaines règles.

    3.4.1. Définition des droits

    • Lors de la création d’un produit, le marchand est soumetteur et propriétaire du produit.
    • Dès qu’un produit a été enrichit par Rakuten France, Rakuten France devient le propriétaire du produit, et le marchand reste soumetteur du produit.

    3.4.2. Actions possibles

    Le droit du… Dans le cas où… Ajouts de données dans attribut vide Mise à jour “attributs restreints” (*) Mise à jour attributs autre que “attributs restreints” (*) Suppression de valeurs (hors attributs restreints et obligatoires)
    Soumetteur 1 seul vendeur du produit OK
    Plusieurs marchands vendent ce produit OK
    Propriétaire 1 seul vendeur du produit OK OK OK OK
    Plusieurs marchands vendent ce produit OK OK OK

    (*) Les attributs restreints sont

    • Titre du produit
    • Code-barre (EAN / ISBN)
    • Référence Soumetteur

     

    Détails:

    • Renseigner de nouvelles valeurs d’attribut est possible au propriétaire et au soumetteur du produit.
    • Les droits de mise à jour sont plus restreints si d’autres vendeurs ont une annonce sur le même produit (active ou réactivable).
    • La mise à jour des attributs multi-valués se fait par écrasement. Il faut donc indiquer la liste complète des nouvelles valeurs qui vont remplacer les anciennes.
    • Certaines valeurs d’attributs peuvent être bloquées à la modification par Rakuten France, mais ne génère pas d’erreur dans le rapport d’import.
    • Une erreur dans la modification d’un attribut produit ne bloque pas les autres modifications sur cette offre. Un warning est affiché dans le rapport d’import.

    3.4.3. Supprimer la valeur d’un attribut

    • Il est possible de supprimer la valeur d’un attribut en mettant simplement <value></value> ou <value/> dans la valeur.
    • On ne peut pas supprimer les attributs obligatoires ou restreints.
    • Le produit ne doit pas avoir d’annonce active / réactivable d’un autre marchand.

Privacy Preference Center

Privacy Preferences