OfferIntegration

Context

The object of this section is to describe the format of package expected to manage offers or products data integration.

Open XML Format: overall description

General information

The format of the expected file is Open XML type. It is a compressed file ti the format ZIP which contains a whole of repertories & files describing the document (XML, images .jpg) (XML, .jpg images).

Open XML: format description

Source: Wikipedia

General principle

The Office Open XML format uses a structure respecting Open Packaging Convention and defining in a simple and logic way the internal structure of all Open Office XML documents. According to this convention, the documents are ZIP files from which the various elements composing it, called parts, are connected by logical relations. The use of the ZIP allows in addition to compressing the documents, to store the data in a completely independent way in a segmented architecture.

Besides this architecture makes it possible more effectively to protect the Open Office XML documents vis-a-vis corruption from the data (if an element is damaged, the others will not be affected).

« Package » concept

The package defines the Zip archive including XML document data.

« Part » concept

A part is an element of the Zip file: a compressed file integrated into the structure of the Zip file. There are 3 types:

  • contents,
  • relations,
  • Types of contents.

Contents parts are made up of the document data. They are either with XML format or with binary format (GIF, JPEG, objects OLE,…).

The relations parts contain an XML structure defined in ECMA-376 standard reference schemes.

« Relationship » and « Relationship Part» concepts

Relationship parts specify the links between the package or a source part and a target part.

<?xml version="1.0" encoding="UTF-8" standalone="yes" ?>
<Relationships xmlns="http://schemas.openxmlformats.org/package/2006/relationships">
  <Relationship Id="rId3" Type="http://schemas.../metadata/core-properties" Target="docProps/core.xml" />
  <Relationship Id="rId2" Type="http://schemas.../metadata/thumbnail" Target="docProps/thumbnail.jpeg" />
  <Relationship Id="rId1" Type="http://schemas.../officeDocument" Target="word/document.xml" />
  <Relationship Id="rId4" Type="http://schemas.../extended-properties" Target="docProps/app.xml" />
</Relationships>

A relationship has a relationship type specifying the nature of the pointed part, and the URI relating to the targeted part.

The relationship parts have a name, represented by a URI, which must respect a particular naming convention. This syntax stipulated in the standard is the following: <hierarchic path >/_rels/<source part name>.rels.

Examples:

  • the package Relationship part does not have a source part, since this one is located at the root even of the document (and is obligatory), its syntax is unique : /_rels/.rels
  • the relationship part of content main part of a WordprocessingML document has the following URI: '/word/document.xml', consequently the part of relation associated (which will allow for example, with the contents to target an image inserted in the document) must have the following URI: /word/_rels/document.xml.rels

Content types parts

This obligatory part has unique name: [Content_Types].xml

This name is not compatible with URI syntax: this is a technical choice. Here is an example of the content of the content type part:

<?xml version="1.0" encoding="UTF-8" standalone="yes" ?>
<Types xmlns="http://schemas.openxmlformats.org/package/2006/content-types">
  <Override PartName="/ppt/slides/slide5.xml" ContentType="application/vnd.openxmlformats-officedocument.presentationml.slide+xml" />
  <Default Extension="png" ContentType="image/png" />
  <Default Extension="rels" ContentType="application/vnd.openxmlformats-package.relationships+xml" />
  <Default Extension="xml" ContentType="application/xml" />
  …
</Types>

This type definition defines two extension types, the default one that specifies that all elements having the mentioned extension are of the defined type, and the other that overloads the extension defined by default stipulating a specific type for a specific part.

All contents type must be compatibles with RFC 2616(taking into account packing model rules, the support of parameters of content type is forbidden).

Open XML Format adapted to the Marketplace

Offers import file

The name given to the Zip package has no importance. There is no specific norm.

The offers Zip package content is the following:

Title Type Description
_rels File
.rels xml file
Content File
Offers.xml xml file
[Content_Types].xml xml file

.rels file Structure

<?xml version="1.0" encoding="utf-8"?>
<Relationships xmlns="http://schemas.openxmlformats.org/package/2006/relationships">
  <Relationship Type="http://cdiscount.com/uri/document"  Target="/Content/Offers.xml" Id="Raa033fe51c984c6f" />
</Relationships>

The Id attribute can contain a unique value (but it is not an obligation).

In fact, a checksum is calculated every time you import a package. this checksum is calculated depending on data included in the package (whichwhich prevents a seller to submit the same package 2 times consecutively). However, if this Id is unique every time there is a generation, then the checksum will be different.

The seller can therefore put in this attribute the value of his choice.

Offers.xml file structure

Scheme

offers

Examples

A package containing an offer without special offer

<OfferPackage Name="Nom fichier offres" PackageType="Full" PurgeAndReplace="False" xmlns="clr-namespace:Cdiscount.Service.OfferIntegration.Pivot;assembly=Cdiscount.Service.OfferIntegration" xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml">
 <OfferPackage.Offers>
  <OfferCollection Capacity="1">
   <Offer SellerProductId="32427220" ProductEan="0080605625006" ProductCondition="6" Price="19.95" EcoPart="0.10" DeaTax="3.14" Vat="19.6" Stock="10" PreparationTime="3" StrikedPrice="39.95" Comment="Offre avec tous les modes de livraisons possibles">
    <Offer.ShippingInformationList>
     <ShippingInformationList Capacity="3">
		<ShippingInformation AdditionalShippingCharges="0.95" DeliveryMode="Standard" ShippingCharges="1.0" />
		<ShippingInformation AdditionalShippingCharges="1.95" DeliveryMode="Tracked" ShippingCharges="2.0" />
		<ShippingInformation AdditionalShippingCharges="2.95" DeliveryMode="Registered" ShippingCharges="3.0" />
     </ShippingInformationList>
    </Offer.ShippingInformationList>
   </Offer>
  </OfferCollection>
 </OfferPackage.Offers>
</OfferPackage>

A package containing an offer with a flash sale

<OfferPackage Name="Nom fichier offres" PackageType="Full" PurgeAndReplace="False" xmlns="clr-namespace:Cdiscount.Service.OfferIntegration.Pivot;assembly=Cdiscount.Service.OfferIntegration" xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml">
 <OfferPackage.Offers>
  <OfferCollection Capacity="1">
   <Offer SellerProductId="S52458285030" ProductEan="9152458285308" ProductCondition="6" Price="50" PreparationTime="3" EcoPart="0" DeaTax="3.14" Vat="19.6" Stock="10" Comment="offer with flash sales">
    <Offer.PriceAndDiscountList>
     <DiscountComponentList Capacity="1">
      <DiscountComponent DiscountUnit="1" DiscountValue="60" EndDate="2012-12-22T20:00" StartDate="2012-12-21T08:00" Type="1" />
     </DiscountComponentList>
    </Offer.PriceAndDiscountList>
    <Offer.ShippingInformationList>
     <ShippingInformationList Capacity="7">
      <ShippingInformation AdditionalShippingCharges="0.95" DeliveryMode="Standard" ShippingCharges="1.0" />
      <ShippingInformation AdditionalShippingCharges="1.95" DeliveryMode="Tracked" ShippingCharges="2.0" />
      <ShippingInformation AdditionalShippingCharges="2.95" DeliveryMode="Registered" ShippingCharges="3.0" />
      <ShippingInformation AdditionalShippingCharges="4.95" DeliveryMode="Relay" ShippingCharges="5.5" />
      <ShippingInformation AdditionalShippingCharges="4.95" DeliveryMode="MondialRelay" ShippingCharges="5.5" />
      <ShippingInformation AdditionalShippingCharges="6.95" DeliveryMode="RelaisColis" ShippingCharges="7.5" />
      <ShippingInformation AdditionalShippingCharges="7.95" DeliveryMode="SoColissimo" ShippingCharges="8.5" />
     </ShippingInformationList>
    </Offer.ShippingInformationList>
   </Offer>
  </OfferCollection>
 </OfferPackage.Offers>
</OfferPackage>

A package containing an offer with sales

<OfferPackage Name="Nom fichier offres" PackageType="Full" PurgeAndReplace="False" xmlns="clr-namespace:Cdiscount.Service.OfferIntegration.Pivot;assembly=Cdiscount.Service.OfferIntegration" xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml">
 <OfferPackage.Offers>
  <OfferCollection Capacity="3">
   <Offer SellerProductId="S53262149036" ProductEan="9153262149367" ProductCondition="6" Price="19.95" EcoPart="0" DeaTax="3.14" Vat="19.6" Stock="10" PreparationTime="3" StrikedPrice="3995" Comment="Offre avec soldes" PriceMustBeAligned="DontAlign">
    <Offer.PriceAndDiscountList>
     <DiscountComponentList Capacity="1">
      <DiscountComponent DiscountUnit="1" DiscountValue="30" SalesReferencePrice="100" Type="3" EndDate="0001-01-01T00:01" StartDate="0001-01-01T00:00" />
     </DiscountComponentList>
    </Offer.PriceAndDiscountList>
    <Offer.ShippingInformationList>
     <ShippingInformationList Capacity="7">
      <ShippingInformation AdditionalShippingCharges="0.95" DeliveryMode="Standard" ShippingCharges="1.0" />
      <ShippingInformation AdditionalShippingCharges="1.95" DeliveryMode="Tracked" ShippingCharges="2.0" />
      <ShippingInformation AdditionalShippingCharges="2.95" DeliveryMode="Registered" ShippingCharges="3.0" />
      <ShippingInformation AdditionalShippingCharges="6.95" DeliveryMode="RelaisColis" ShippingCharges="7.5" />
      <ShippingInformation AdditionalShippingCharges="7.95" DeliveryMode="SoColissimo" ShippingCharges="8.5" />
      <ShippingInformation AdditionalShippingCharges="7.95" DeliveryMode="MondialRelay ShippingCharges="8.5" />
     </ShippingInformationList>
    </Offer.ShippingInformationList>
   </Offer>
  </OfferCollection>
 </OfferPackage.Offers>
</OfferPackage>

A package containing an offer with home delivery information

<OfferPackage Name="Nom fichier offres" PackageType="Full" PurgeAndReplace="False" xmlns="clr-namespace:Cdiscount.Service.OfferIntegration.Pivot;assembly=Cdiscount.Service.OfferIntegration" xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml">
 <OfferPackage.Offers>
  <OfferCollection Capacity="1">
   <Offer SellerProductId="S52458285030" ProductEan="9152458285308" ProductCondition="6" Price="50" EcoPart="0" DeaTax="3.14" Vat="19.6" Stock="10" PreparationTime="3" Comment="offer avec livraison magasin">
    <Offer.ShippingInformationList>
     <ShippingInformationList Capacity="4">
      <ShippingInformation AdditionalShippingCharges="0.95" DeliveryMode="Standard" ShippingCharges="1.0" />
      <ShippingInformation AdditionalShippingCharges="1.95" DeliveryMode="Tracked" ShippingCharges="2.0" />
      <ShippingInformation AdditionalShippingCharges="2.95" DeliveryMode="Registered" ShippingCharges="3.0" />
      <ShippingInformation AdditionalShippingCharges="4.95" DeliveryMode="Relay"  ShippingCharges="5.5" />
     </ShippingInformationList>
    </Offer.ShippingInformationList>
   </Offer>
  </OfferCollection>
 </OfferPackage.Offers>
</OfferPackage>

A package containing an offer with automatic price alignment activated

<OfferPackage Name="Nom fichier offres" PackageType="Full" PurgeAndReplace="False" xmlns="clr-namespace:Cdiscount.Service.OfferIntegration.Pivot;assembly=Cdiscount.Service.OfferIntegration" xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml">
 <OfferPackage.Offers>
  <OfferCollection Capacity="1">
   <Offer SellerProductId="S52458285030" ProductEan="9152458285308" ProductCondition="6" Price="50" EcoPart="0" DeaTax="3.14" Vat="19.6" Stock="10" PreparationTime="3" Comment="offer with flash sales" PriceMustBeAligned="Align" MinimumPriceForPriceAlignment="45.5">
     <ShippingInformationList Capacity="3">
      <ShippingInformation AdditionalShippingCharges="0.95" DeliveryMode="Standard" ShippingCharges="1.0" />
      <ShippingInformation AdditionalShippingCharges="1.95" DeliveryMode="Tracked" ShippingCharges="2.0" />
      <ShippingInformation AdditionalShippingCharges="2.95" DeliveryMode="Registered" ShippingCharges="3.0" />
     </ShippingInformationList>
    </Offer.ShippingInformationList>
   </Offer>
  </OfferCollection>
 </OfferPackage.Offers>
</OfferPackage>

A package containing an offer with in shop delivery information

<OfferPackage Name="Nom fichier offres" PackageType="Full" PurgeAndReplace="False" xmlns="clr-namespace:Cdiscount.Service.OfferIntegration.Pivot;assembly=Cdiscount.Service.OfferIntegration" xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml">
 <OfferPackage.Offers>
  <OfferCollection Capacity="1">
   <Offer SellerProductId="32427220" ProductEan="0080605625006" ProductCondition="6" Price="19.95" EcoPart="0.10" DeaTax="3.14" Vat="19.6" Stock="10" StrikedPrice="39.95" Comment="Offre avec tous les modes de livraisons possibles" PriceMustBeAligned="Unknown" PreparationTime=”3”>
    <Offer.ShippingInformationList>
     <ShippingInformationList Capacity="6">
      <ShippingInformation AdditionalShippingCharges="0.95" DeliveryMode="Standard" ShippingCharges="1.0" />
<ShippingInformation AdditionalShippingCharges="1.95" DeliveryMode="Tracked" ShippingCharges="2.0" />
<ShippingInformation AdditionalShippingCharges="2.95" DeliveryMode="Registered" ShippingCharges="3.0" />
<ShippingInformation AdditionalShippingCharges="6.95" DeliveryMode="RelaisColis" ShippingCharges="7.5" />
<ShippingInformation AdditionalShippingCharges="7.95" DeliveryMode="SoColissimo" ShippingCharges="8.5" />
     </ShippingInformationList>
    </Offer.ShippingInformationList>

A package containing an offer with the unit price

<OfferPackage Name="Nom fichier offres" PackageType="Full" PurgeAndReplace="False" xmlns="clr-namespace:Cdiscount.Service.OfferIntegration.Pivot;assembly=Cdiscount.Service.OfferIntegration" xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml">
 <OfferPackage.Offers>
  <OfferCollection Capacity="1">
   <Offer SellerProductId="324272201" ProductEan="0080605625006" ProductCondition="6" Price="19.95" EcoPart="0.10" DeaTax="3.14" Vat="19.6" Stock="10" StrikedPrice="39.95" Comment="Offre avec prix à l'unité de conditionnement"  ProductPackagingUnit="Liter" ProductPackagingValue="0.5" PreparationTime="3" >
    <Offer.ShippingInformationList>
     <ShippingInformationList Capacity="3">
      <ShippingInformation AdditionalShippingCharges="0.95" DeliveryMode="Standard" ShippingCharges="1.0" />
      <ShippingInformation AdditionalShippingCharges="1.95" DeliveryMode="Tracked" ShippingCharges="2.0" />
      <ShippingInformation AdditionalShippingCharges="2.95" DeliveryMode="Registered" ShippingCharges="3.0" />
     </ShippingInformationList>
    </Offer.ShippingInformationList>
   </Offer>
  </OfferCollection>
 </OfferPackage.Offers>
</OfferPackage>

A package containing an offer with the Cdiscount At Will mode (Cdiscount à volonté in french : CDAV)

<OfferPackage Name="Nom fichier offres" PackageType="Full" PurgeAndReplace="False" xmlns="clr-namespace:Cdiscount.Service.OfferIntegration.Pivot;assembly=Cdiscount.Service.OfferIntegration" xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml">
 <OfferPackage.Offers>
  <OfferCollection Capacity="1">
   <Offer SellerProductId="324272201" ProductEan="0080605625006" ProductCondition="6" Price="19.95" EcoPart="0.10" DeaTax="3.14" Vat="19.6" Stock="10" StrikedPrice="39.95" Comment="Offer with CDAV activated" IsCDAV="True" PreparationTime=”3”>
    <Offer.ShippingInformationList>
     <ShippingInformationList Capacity="3">
      <ShippingInformation AdditionalShippingCharges="0.95" DeliveryMode="Standard" ShippingCharges="1.0" />
      <ShippingInformation AdditionalShippingCharges="1.95" DeliveryMode="Tracked" ShippingCharges="2.0" />
      <ShippingInformation AdditionalShippingCharges="2.95" DeliveryMode="Registered" ShippingCharges="3.0" />
     </ShippingInformationList>
    </Offer.ShippingInformationList>
   </Offer>
  </OfferCollection>
 </OfferPackage.Offers>
</OfferPackage>

A package with big parcel delivery mode

<OfferPackage Name="Nom fichier offres" PackageType="Full" PurgeAndReplace="False" xmlns="clr-namespace:Cdiscount.Service.OfferIntegration.Pivot;assembly=Cdiscount.Service.OfferIntegration" xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml">
 <OfferPackage.Offers>
  <OfferCollection Capacity="1">
   <Offer SellerProductId="32427220" ProductEan="0080605625006" ProductCondition="6" Price="19.95" EcoPart="0.10" DeaTax="3.14" Vat="19.6" Stock="10" StrikedPrice="39.95" Comment="Offre avec tous les modes de livraisons possibles" PreparationTime="1">
    <Offer.ShippingInformationList>
     <ShippingInformationList Capacity="3">
      <ShippingInformation AdditionalShippingCharges="0.95" DeliveryMode="Standard" ShippingCharges="1.0" />
<ShippingInformation AdditionalShippingCharges="1.95" DeliveryMode="BigParcelEco" ShippingCharges="2.0" />
<ShippingInformation AdditionalShippingCharges="2.95" DeliveryMode="BigParcelStandard" ShippingCharges="3.0" />
<ShippingInformation AdditionalShippingCharges="2.95" DeliveryMode="BigParcelComfort" ShippingCharges="3.0" />
     </ShippingInformationList>
    </Offer.ShippingInformationList>
   </Offer>
  </OfferCollection>

A package with express delivery mode

<OfferPackage Name="Nom fichier offres" PackageType="Full" PurgeAndReplace="False" xmlns="clr-namespace:Cdiscount.Service.OfferIntegration.Pivot;assembly=Cdiscount.Service.OfferIntegration" xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml">
 <OfferPackage.Offers>
  <OfferCollection Capacity="1">
   <Offer SellerProductId="32427220" ProductEan="0080605625006" ProductCondition="6" Price="19.95" EcoPart="0.10" DeaTax="3.14" Vat="19.6" Stock="10" StrikedPrice="39.95" Comment="Offre avec tous les modes de livraisons possibles" PreparationTime="1">
    <Offer.ShippingInformationList>
     <ShippingInformationList Capacity="3">
      <ShippingInformation AdditionalShippingCharges="0.95" DeliveryMode="Standard" ShippingCharges="1.0" />
<ShippingInformation AdditionalShippingCharges="1.95" DeliveryMode="Express" ShippingCharges="2.0" />
     </ShippingInformationList>
    </Offer.ShippingInformationList>
   </Offer>
  </OfferCollection>

Detailed Structure

The detailed structure of the Offers.Xml file is described in Offers.xml files

Decimal separator

The decimal separator of decimal number is the dot « . ».

[Content_Types].xml file structure

The content of this file is fixed:

<?xml version="1.0" encoding="utf-8"?>
<Types xmlns="http://schemas.openxmlformats.org/package/2006/content-types">

  <Default Extension="xml" ContentType="text/xml" />
  <Default Extension="rels"
  ContentType="application/vnd.openxmlformats-package.relationships+xml" />
</Types>

Points of attention

Activation / deactivation of special offers

The sales and flash sales are defined by the information contained in the element Offer.PriceAndDiscountList in the file offer.xml.

To deactivate all special offers on an offer, you have to update this offer without information in Offer.PriceAndDiscountList.

The duration of flash sales is limited at 72h from the start date noticed, at the end of this delay the flash sale is deactivated.

Shippingmode modification

Sellers can propose three delivery mode

  • Home delivery
  • In shop delivery
  • Immediate pick up at store

These mode can be selected in the sellershop in the StoreSettings/Shipping options  section.

the shipping mode choosen must be available for all offers online.

That is why, the shipping mode modifications will be effective after an offers update with the Purge&Replace mode activated.

You  must therefore  submit all your offers you want online, and their shipping information will be checked to be accorded to the shipping mode choosen.

Multi tenant

Sellers can be registered on several websites.

You can chose on which websites you create/update your offers thanks to the OfferPublicationList/@PublicationPool.

if you do not use the attribute OfferPublicationList/@PublicationPool, the default website is Cdiscount.

if you are not registered on Cdiscount you have to mention the attributes OfferPublicationList/@PublicationPool, otherwise your offers ill not be updated / created.

if you use the Purge&Replace mode, the purge will only be made on the offers of the website mentionned.

If no website is mentionned only the offers on Cdiscount website will be purged.

Offer Package Submission error codes

The detailled page of offers package submission error codes is described in Offer integration