CLA DMS / S@LTO

Project : S@LTO

Interface Application Agreement
(CLA)

[Objet ]

 

 

Versions History
Version Version Date

Creation or change request description

Author(s)

V 1.0

05/09/2014

document Finalized

Stéphane Raoul

Table of content

1. Introduction    3

1.1. Applications involved in the CLA    3

1.2. S@lto Goals    3

1.3. S@lto constraints    3

2. Stakeholders commitment    4

2.1. Initialization    4

2.2. Testing Environments    4

3. Management    5

3.1. Planning    5

3.2. Validation process    5

3.3. Follow-up and communication    5

4. High Level Specification    6

4.1. Security and confidentiality requirements    6

5. XAT2V2 Technical Information    7

5.1. Exchange format : XAT2V2    7

5.2. Data Flow Compression    7

5.3. XAT2V2 identifier management    7

5.4. Response Message    8

5.5. Blocking issues in XAT2V2 protocol    8

5.6. Warning in XAT2V2 protocol    9

6. getPrice / getStock / GetPriceAndStock requests    10

6.1. API detailed description    10

6.2. XAT2V2 request: S@lto Ú Partner Parts Soft    10

6.3. XAT2V2 Response (to the getPrice, getStock and getPriceAndStock requests) : Partner Parts SoftÚ S@lto    11

6.4. Error Handling    17

7. Send Basket/ Order    18

7.1. Description    18

7.2. XAT2V2 request : S@lto Ú Partner application    18

7.3. XAT2V2 response : Partner Application Ú S@lto    21

7.4. Error Handling    27

7.5. Availability date label format    27

 

  1. Introduction

    1. Applications involved in the CLA

      1. Partner Application partenaire

Partner Application partenaireStakeholders :

Role

Name

Organization

Product Owner

Development Lead

  1. S@lto

S@lto is an application that implements services to get prices and stocks from Partner Application (aka DMS), and order Part baskets to these same DMS, through Salto Application.

S@lto Stakeholders:

Role

Name

Organization

Product Owner Aurélien VIRIEUX Product Group
Development manager Bernard Francis R&D
Development Lead (XAT2V2) Stéphane RAOUL R&D
  1. S@lto Goals

S@lto goal is to :

Get prices and stocks for vehicle parts from a partner application.

Send a basket order containing a list of parts description and quantity to a Partner application.

  1. S@lto constraints

Data transportation is done through the Xat2V2 protocol (ETAI property)

  1. Stakeholders commitment

The goal of this document is to define a CLA between both applications (ETAI and Partner). It is a commitment to maintain a reliable and up-to-date interface between the two applications (ETAI and Partner).

This document is established between product owners and development leads of both applications.

  1. Initialization

    1. CLA Initialization and updates

ETAI is responsible for initializing and updating the CLA.

  • The CLA has to be approved and signed by ETAI and the Partner ( list of stakeholders in section 1.1)
  • The CLA can be modified at any of the stakeholders’ request. It then goes thru a new approval process.
  • ETAI must inform the Partner of any change (data, exchange format) no later than when the detailed specifications are fixed.
  1. CLA Follow up

Any delay on a delivery due date has to be notified to the other party when/if it has consequences on the overall project execution timeline. Workaround solutions have to be implemented as soon as possible to unlock the other party.

S@lto

Partner Application

The Product owner must:

  • Check there is no confidentiality and security risks caused by the changes and inform the product owner from the Partner application about security and confidentiality requirements
    • Notify as soon as possible the product owner from the Partner application when there is a change in the structure of the XML sent.
    • Take into account Partner time constraint to plan these changes
  • Do the functional Testing on Time.

The Product owner must :

  • Check there is no confidentiality and security risks caused by the changes and inform the product owner from the ETAI about security and confidentiality requirements
  • Inform as soon as possible ETAI product Owner when intending to use the new data and negotiate first usage and following updates.
  • Take into account ETAI testing phase and « go live » time constraints, when planning the integration of the changes
  • Do the functional Testing on time.
  • Decide of the « GO Live » at the end of the functional testing phase.
  • Inform S@lto Product owner if the API is not used anymore.

The development lead must:

  • Take into account security and confidentiality requirements by implementing the corresponding developments.
  • Schedule a technical testing phase for the new developments
  • Provide a testing environment to the Partner.
  • Coordinate the « Go Live » with the Partner product owner
  • Inform the Partner development Lead, on any maintenance activities (purge…)

The development lead must:

  • Take into account security and confidentiality requirements by implementing the corresponding developments.
  • Implement the changes on time.
  • Schedule a technical testing phase
  • Provide a testing environment to ETAI.
  • Coordinate the « Go Live » with ETAI product owner
  1. Testing Environments

Providing a test environment is mandatory for both Partner and ETAI applications. This testing environment is required for several reasons, among which are : avoiding regressions during version upgrade, troubleshooting issues, and for demonstration purpose.

ETAI provide a dedicated testing environment to his partners, on a dedicated server, « clone » of the production environment. Access roles (repairer, wholesaler, administrator) will be available to recreate a perfect copy to the partner.

ETAI can « host » Partner application, or use an online access for saas applications.

  1. Management

    1. Planning

Sketch the operational planning. This planning must show every milestone linked to the mutual obligations of the partner and ETAI.

Task

Partner Application partenaire

S@lto

developments end date

S@lto 1rst test cycle end date

test cycle with Partner Application partenaire

XAT2 V2 validation cycle

Beta or restricted Candidate end Date

  1. Validation process

Responsibility, participants, validation form….

  1. Follow-up and communication

For notes and meeting minutes : writer,diffusion list, delay

For meetings : frequency, agenda, participants, Action item follow-up rules …..

  1. High Level Specification

    1. Security and confidentiality requirements

Frequency :on demand, real time, scheduled

Volume : number of exchanges / day

Technology: Protocol

Client

Provider

Comments

S@lto

Application partenaire

Service availability

YES/NO

YES/NO

 Data Confidentiality

YES/NO

YES/NO

 Data Integrity

YES/NO

YES/NO

 Access Traceability

YES/NO

YES/NO

 Data loss allowed

YES/NO

YES/NO

  DRP

YES/NO

YES/NO

 

 

  1. XAT2V2 Technical Information

    1. Exchange format : XAT2V2

Xat2V2 uses XML.

For message exchange, use the POST method, from the http protocol.

The message content-type is : Content-Type: application/xml; charset= »UTF-8″

The message content is the xml itself.

The xml encoding is UTF-8. Ie, : <?xml version= »1.0″ encoding= »UTF-8″ ?>

The xml has to be UTF-8 encoded, conform to the charset and encoding indicated.

The XSD schema is available here : http://www.xat2.etai.fr/xat2/v2/xsd/xat2_v2_0.xsd

And its documentation is available here: http://www.xat2.etai.fr/v2/xat2/XSDoc/xat2_v2_0.html

  1. Data Flow Compression

S@lto compresses the data flows to use less bandwith.

S@lto can also receive compressed data flows. They will be automatically uncompressed by S@lto. GZIP is used for that process :

Accept-Encoding: gzip

When S@lto sends a compressed data flow, a property is added in the request-header :

Content-Encoding: gzip

Example : http header for a compressed request ( Content-Encoding Header)

POST /rest/xat2v2/ HTTP/1.1

User-Agent: ETAI/Xat2V2 fr.etai.xat2v2.client.impl.Xat2RestClient

Accept: application/xml

Accept-Charset: UTF-8

Content-Type: application/xml

Content-Encoding: gzip

Accept-Encoding: gzip

Host: localhost.:8081

Connection: keep-alive

Content-Length: 2201

  1. XAT2V2 identifier management

All the Services have to be authenticated by the server.

Authentication parameters are passed in a <session-context> element, part of the Xat2V2 message.

Table 1 – XAT2V2 Identifiers Description

XML

Comments

<?xml
version=« 1.0 »
encoding=« utf-8 »
standalone=« no »?>

<xat2
xmlns=« http://xat2.etai.fr » version=« 2.0 »>

<session-context>

<application-id>{applicationId}</application-id>

<dms-login>{dmsLogin}</dms-login>

<user-shared-id>{userSharedId}</user-shared-id>

<garage-shared-id>{garageSharedId}</garage-shared id></session-context>

This Element is required for all the XAT2 Messages.

<SessionContext> identifies the caller :

by a quadruplet :

application-id/ dms-login / user-shared-id / garage-shared-id / 

</xat2>

 

 


application-id : unique identifier for the Partner application


dms-login : This is an identifier for an instance of the partner application (DMS) within a garage


garage-shared-id : garage identifier


user-shared-id : S@lto’ User identifier. This is the identification of a user within S@lto. This ID is linked to an S@lto login.

  1. Response Message

The answer sent back from the Partner application is also a XAT2 XML. It is contained in the answer from the POST described above.

Then checks are required to make sure that the communication was successful and that the request was well interpreted.

To notify that the request sent from ETAI application was correct, an acknowledgement with a message and a status is sent back.

Table 2 – XAT2V2 Acknowledgement

XML

Comments

<?xml
version=« 1.0 »
encoding=« utf-8 »
standalone=« no »?>

<xat2
xmlns=« http://xat2.etai.fr » version=« 2.0 »>

 
<message-list>


<message>


<message-category>ack</message-category>


<technical-description>Processing complete</technical-description>


<classification-list>


<classification
dictionary=« Xat2:message »


ref=« complete »/>


</classification-list>


</message>


</message-list>

The success of a service execution is notified by a message from the <message-list> element. The message-category is « ack » and the classification ref « complete » from the Xat2:message dictionary.

 

Otherwise, a problem occured.

</xat2>

 

 

  1. Blocking issues in XAT2V2 protocol

When a critical issue arises, the Xat2V2 server sends back to the client an error message.

Table 3 – XAT2V2 Error messages

XML

Comments

<?xml
version=« 1.0 »
encoding=« utf-8 »
standalone=« no »?>

<xat2
xmlns=« http://xat2.etai.fr » version=« 2.0 »>

 
<message-list>


<message>


<message-category>error</message-category>


<user-description dictionary=« Xat2:message »


ref=« {errorCode} »/>

>{description de l’erreur}</user-description>


</message>


</message-list>

A technical error is specified by a message of <message-category> error.

 

The <user-description> element specifies the error label for the end-user .

{errorCode} has one of the values from the « Error code » column of Table 4 – XAT2V2 critical issues messages

 

</xat2>

 

 

List of errors from the « Xat2:message » dictionary:

Table 4 – XAT2V2 critical issues messages

Error Code

Description

Impossible

Application can not handle the message

applicationTimeout

Application did not answer during the dedicated timeslot

Error

Technical error

  1. Warning in XAT2V2 protocol

When a non blocking issue arises, the Xat2V2 protocol sends a warning message to the client.

Table 5 – XAT2V2 Warning messages

XML

Comments

<?xml
version=« 1.0 »
encoding=« utf-8 »
standalone=« no »?>

<xat2
xmlns=« http://xat2.etai.fr » version=« 2.0 »>

 


<message-list>


<message>


<message-category>warning</message-category>


<user-description dictionary=« Xat2:message »


ref=« {alertCode} »/>

>{description de l’erreur}</user-description>


</message>


</message-list>

A warning is specified by a message of <message-category> warning, and a classification from the Xat2:message dictionary

The <user-description> element specifies the warning label for the end-user .

{alertCode} has one of the values from the « Error code » column of Table 6 – XAT2V2 Warnings

</xat2>

 

List of warnings from the « Xat2:message » dictionary:

Table 6 – XAT2V2 warnings

Error code

Description

unknownTerm

One item in the XML shuttle is not part of the dictionary

unknownDictionary

The dictionary used by the partner application (DMS) is unknown.

It means that at least one item could not be interpreted correctly by E-T-A-I Connect.


 

  1. getPrice / getStock / GetPriceAndStock requests

    1. API detailed description

This service sends a list of parts to the Partner application.

The partner application sends back a response with a list of parts and the related stock and price for each part.

S@lto act as the « Client » in this data exchange.

  1. XAT2V2 request: S@lto Ú Partner Application partenaire

Verbs :

  • getPrice : to get the price
  • getStock : to get the stock
  • getPriceAndStock : to get price and stock in one call

Table 7 – Price and Stock XML requests

XML

Description

<?xml
version=« 1.0 »
encoding=« utf-8 »
standalone=« no »?>

<xat2
xmlns=« http://xat2.etai.fr » version=« 2.0 »>
 <session-context>


<application-id>{applicationId}</application-id>


<dms-login>{dmsLogin}</dms-login>


<user-shared-id>{userSharedId}</user-shared-id>


<garage-shared-id>{garageSharedId}</garage-shared-id>

</session-context>

session identifiers(mandatory)

<shuttle>

 

<transport>  <partner>

<name>S@lto</name>

<editor dictionary=« ETAI:editor »
ref=« etai »>

<version-code>{applicationVersion}</version-code>

</partner>

XAT2V2 Partner (optional)

Name of the application that sends the request

<partner-data-list> Partner information list (optional)

 

 

This element is used for transferring miscellaneous data to a Partner application (ie, discounts, specific user identifier,etc ….)


number of elements  : 0 to 1

<partner-data
ref=« {dmsLoginValue} »>
DMS definition
{dmsLoginValue} is the dmsLogin from the DMS to which these data are targetted

 

number of elements  : 1 to N<classification
ref=« {partnerDataRef} »>{partnerDataValue}

</classification> Partner application Data Definition

For each Partner, several data can be defined . One data per <classification>element .

 

{partnerDataRef} is the data identifier (exemple : ID_USER)

{partnerDataValue} is the value of the data (exemple : 12345)

 

number of elements  : 1 to N
</partner-data>
 </partner-data-list>  <action-list>

<action>

<verb>{verbe}</verb>

</action>

</action-list>
XAT2V2 verb (mandatory)

{verb} can be  :

  • « getPrice » to get prices
  • « getStock » to get stock
  • « getPriceAndStock » to get both prices and stocks

</transport>
 <default-shuttle-settings>  <currency
dictionary=« ETAI:unit »
ref=« euro »/>

Default currrency (optional)

Euro is the default currency

<language
dictionary=« ETAI:language »
ref=« {languageRef} »
/>

User language (optional)

Language of the request’s sender.

{languageRef} contains values from the dictionary ETAI :language dictionary

Examples : FR / NL / DE / IT / etc.

</default-shuttle-settings> <part-list>

 


<part>
  <breakdown-list>

<classification
dictionary=« ETAI:breakdown »


ref=« {breakdownValue} »/>

<classification
dictionary=« ETAI:partIdentification »


ref=« {partIdentificationValue} »/>

</breakdown-list>

Part Type identifier. (optional)

The part Type is defined by the « ETAI:breakdown » dictionary.

{breakdownValue} values are :

  • « part » for a part
  • « tire » for a tire
  • « ingredient » for an ingredient

 

Additional information -for Parts only – can be added thru « ETAI:partIdentification » dictionary .

{partIdentificationValue}  values are :

  • « elementOE » for origin equipment parts
  • « elementAM » for parts from car parts manufacturer
  • « elementPRE » for re-use parts
  • « elementGU » for parts from the Universal products list
  • « elementIU » for ingredient from the universal ingredient list

<reference-list>

 


<classification
source=« {sourceValue} »

ref=« {referenceValue} »>

</classification>


</reference-list>

Part reference (mandatory)


Source attribute, contains the source/type of the reference.

{sourceValue} values are :

  • « catalog » : raw reference from the catalogue
  • « clean » : clean reference
  • « ean » : ean13
  • « articleCode » : PLC + reference
  • « ipc » : for tire only (International Patent Classification)
  • « refcom » : for tire only (commercial reference)

{referenceValue} is the value for the reference

 

number of elements  : 1 to N: depends on the Partner application

 

<supplier>

 

<abbreviation>{abbreviationValue}</abbreviation>


<classification-list>


<classification
source=« etai »


ref= »{supplierIdETAI} »/>


</classification-list>


</supplier>

part manufacturer (mandatory)

 

{abbreviationValue} is the short for the supplier .

For all Parts, the ETAI identifier for the manufacturer is specified by the {supplierIdETAI}.

 

<quantity>

 


<amount>{quantityValue}</amount>

</quantity> quantity needed (optional)

{quantityValue} is the quantity expected by the end-user
</part>


</part-list>
 </shuttle>

</xat2>

  1. XAT2V2 Response (to the getPrice, getStock and getPriceAndStock requests) : Partner Application partenaireÚ S@lto

This section contains the description of the content of the message containing prices and stocks from a DS (DS = Destination Site, the site of the partner DMS)

The data flow contains the prices and stocks of the parts requested.

Table 8 – Prices and stocks XML response

XML

Description

<?xml
version=« 1.0 »
encoding=« utf-8 »
standalone=« no »?>

<xat2
xmlns=« http://xat2.etai.fr » version=« 2.0 »>
 
<message-list>


<message>


<message-category>ack</message-category>


<technical-description>


{verbe} processing complete


</technical-description>


<classification-list>


<classification
dictionary=« Xat2:message »

ref=« complete »>


</classification>


</classification-list>


</message>


</message-list>

Achnowledgement (mandatory)

Message of ack category.

The <technical-description> {verb} will specify the verb to which this message is responding followed by processing complete if the processing goes well.

<message-list> contains a message indicating the status of the exchange via a <classification> from the « Xat2:message » dictionary and the ref « complete ».

<session-context>

<application-id>{applicationId}</application-id>

<dms-login>{dmsLogin}</dms-login>

<user-shared-id>{userSharedId}</user-shared-id>

<garage-shared-id>{garageSharedId}</garage-shared-id>

</session-context>

XAT2V2 session (mandatory)

<shuttle> 
<settings>
 
<VAT-list>
 
<VAT-rate internal-id=« {idValue} »>


<value><amount>{amountValue}</amount></value>


</VAT-rate>

VAT (mandatory if prices include Taxes)

Not available in the get stock request

« internal-id » links a VAT rate to a price.

VAT is a percentage specified in {amountValue}. Declaration of multiple VAT rate is possible.

numbers of elements <VAT-rate> : 0 to N


</VAT-list>
  <discount-list>
 
<discount
internal-id=« {discountId}} »>


<breakdown-list>


<classification
dictionary=« ETAI:applicability »


ref=« part »/>


</breakdown-list>


<value
value-type=« percent »>


<amount>{amountValue}</amount>


</value>

<label>

    <short-label>{discountCode}</short-label>

    <long-label>{discountLabel}</long-label>

</label>


</discount>

Discount definition (optional)

Not available in the getStock request

Definition of the discount that can be applied to one or several parts

All the discounts are expressed as percentage.

When a discount is defined for a whole set of parts, its applicability has to be defined via the ETAI:applicability dictionary as well as its reference « part ».

If a discount does not apply to all the parts, there is no need to define applicability

{discountCode} is the code of the discount.

{discountLabel} is the label of the discount

A same discount can be used for several parts by declaring the discount {discountId} in the price of the part

Number of <discount> elements  : 0 to N

 


</discount-list>


</settings>


<person-list>
 
<person
internal-id=« {personInternalId} »>

<breakdown-list>

<classification
dictionary=« ETAI:breakdown »


ref=« storageLocation »/>

<classification

dictionary=« ETAI:storageLocationType »
ref=« {storageLocationTypeValue} »/>

</breakdown-list>

<name>{nameOfStorageLocation}</name>


<place>


<address
number=« 1 »>{addressLine1}</address>


<address
number=« 2 »>{addressLine2}</address>


<zip-code>{zipCode}</zip-code>


<city>{city}</city>


<country>


<classification
dictionary=« ETAI:country »


ref=« {countryRef} »>

{countryLabel}


</classification>


</country>


</place>


Storage(s) location (optional)

Not available in the getPrice

Person and storage are linked through the {personInternalId} value.

{storageLocationTypeValue} represents the type of storage, and can be one of the values below :

  • « primary » primary storage location
  • « secondary » secondary storage location
  • « express » express storage location
  • « external » external storage location

Address can contain several lines. In that case, there are several <address> tags, and the value of the attribute « number » is increased.

The country of the address is specified by « ETAI:country » dictionary

Number of elements <person> of type « storageLocation » : 0 to N


</person>
 
</person-list>
 
<part-list>


<part>

List of parts

<breakdown-list>

<classification
dictionary=« ETAI:breakdown »


ref=« {breakdownValue} »/>

<classification
dictionary=« ETAI:partIdentification »


ref=« {partIdentificationValue} »/>

</breakdown-list>

Part type identification (optional)

Same information as in the initial request.



<reference-list>


<classification
source=« {sourceValue} »>

ref=« {referenceValue} »>

</classification>


</reference-list>

Part reference (mandatory)

Same as in the initial request.

If the Part identification is ambiguous (several parts found) then the DMS

Can send back several « articleCode » with their labels (in the source attribute of the classification element), so that the end-user can specify an article code

Format :

<classification
source=« articleCode » ref=« {referenceValue} »>{Label}

</classification>

<supplier>


<classification-list>


<classification
source=« etai »


ref=« {supplierIdETAI} »/>


<classification
source=« {otherSource} »


ref=« {otherSupplierId} »/>

 


</classification-list>


</supplier>

Part Supplier (mandatory)

For all the parts, {supplierIdETAI} describes the ETAI identifier for the supplier .

This is mandatory. It must have the same value as the one sent in the request.

Other suppliers’ identifier can be added, by specifying a different <source>

Example : {OtherSource} can have the value TECCOM

{otherSupplierId} can have the supplier id for TECCOM.


<packaging-list>


<packaging>


<value>


<amount>{amountValue}</amount>


</value>

<label>

     <long-label>{packagingLabel}</long-label>


</label>


</packaging>


</packaging-list>

Packaging (optional)

{amountValue} defines the packaging quantity

Example : for a box of spark plugs with 4 spark plugs the {amountValue} will be 4

{packagingLabel} is the packaging label


<stock-list>


<stock
person-internal-id=« {personInternalId} »>

Part stock

Not available in the getPrice request

Stock is linked to an address, specified in {personInternalId}.


<value-list>


<value>


<amount>{stockAmount}</amount>


<amount-of>


<classification
dictionary=« ETAI:stock »



ref=« {stockRef} »/>


</amount-of>


</value>


</value-list>

Stock Type and quantity

Not available in the getPrice request.

Definition of all the types of stocks in value-list.

{stockAmount} specifies the quantity of parts in stock (optional)

Specifies the stock type in the classification of the <amount-of> element using the « ETAI:stock » dictionary.

{stockRef} Values :

  • « availableStock » : stock available
  • « reserved » : stock booked by another customer
  • « inOrder » : stock ordered
  • « unavailableStock » : stock not available

{stockAmount} being optional , if a <value> of one of the Type defined above has no information in {stockAmount}, it means that a stock exists for this type.

To specify that a stock is not available, {stockRef} must be set to « unavailableStock »


<availability>


<delivery-list>


<delivery>


<label>


<short-label>{deliveryLabel}</short-label>


</label>


<date>


<date
format=« {datePattern} »>{dateValue}</date>


</date>


<carriage>


<breakdown-list>


<classification
dictionary=« ETAI:carriage »


ref=« {carriageValue} »>{deliveryTourCode}</classification>

</breakdown-list>


<price>


<value-list>


<value
value-type=« exclTaxes »>

<amount>{carriagePriceAmount}</amount>


</value>


</value-list>


<currency
dictionary=« ETAI:unit » ref=« euro »/>


</price>


</carriage>


</delivery>


</delivery-list>


</availability>

stock availability (optional)

Not available in the getPrice request.

The stock availability is specified in the <availability> element.

<short-label> element describes the availability ( example : delivered tomorow at 10 AM) . {deliveryLabel} is a free-formed text but it can be formatted (cf. Erreur ! Source du renvoi introuvable. availability label format)

The <date> element describes the availability date –

Format is customizable. The {dateValue} format must correspond to the Format defined.

Example 1 : Year Month Day

<date format = « yyyMMdd  »

{dateValue}=20140413

Which corresponds to a delivery date on April 13th 2014

Example 2 : Year Month Day – Hour

<date format = « yyyMMdd-HH »

{dateValue}=20140413-15

Which corresponds to a delivery date on April 13th 2014 at 3PM

The parts ordered can be delivered in several ways, defined in the <delivery> element.

Values are specified in the « ETAI:carriage » dictionary

{carriageValue} Values are  :

  • « deliveryOnSite » : on site delivery
  • « removalOnSite » : removal on site
  • « deliveryOnTour » : delivery on Tour
  • « postalParcel » : Postal Parcel
  • « expressDelivery » : express delivery
  • « other » : other
  • « unknown » : unknown

{deliveryTourCode} specifies the code of the delivery Tour.

The delivery price is specified in the <price> element of the carriage element



</stock>


</stock-list>

<instruction-list>  <instruction>

<quantity>

<amount>{orderableMinimalQuantityValue}</amount>

</quantity>

<classification-list>

<classification
dictionary=« ETAI:instruction »
ref=« orderableMinimalQuantity »
/>

</classification-list>

</instruction>

Order Minimum quantity (optional)

The minimum order quantity for a part is defined in the <instruction> <quantity> element , with a classification ref « orderableMinimalQuantiy ».

In the <Amount> element {orderableMinimalQuantityValue is set to the minimum quantity to be ordered.

Example : if the minimum quantity for a part order is 2 then {orderableMinimalQuantityValue} will be set to 2.

<instruction>

<quantity>

<amount>{multipleOrderableQuantityValue}</amount>

</quantity>

<classification-list>

<classification
dictionary=« ETAI:instruction »
ref=« multipleOrderableQuantity »
/>

</classification-list>

</instruction>

sales packaging (optional)

A sales multiple for the part can be defined in the <instruction> <quantity>element with a <classification ref>  » multipleOrderableQuantity » from the ETAI:Instruction dictionary

In the <amount> element, {multipleOrderableQuantiyValue} will be set to the order multiple

Example : if a part has to be ordered in pairs (2 or 4, or 6…) {multipleOrderableQuantiyValue} is set to 2.

</instruction-list>  <price-list>



<price discountinternal-id=« {discountInternalId} » personinternal-id=« {personInternalId} »>

<breakdown-list>


<classification
dictionary=« ETAI:unit »
ref=« unit »/>


</breakdown-list>


<value-list>


<value
value-type=« exclTaxes »>


<amount>{amountValue}</amount>


<include-deduction>


<classification
dictionary=« ETAI:deductionType »


ref=« discount »/>

</include-deduction>


</value>


</value-list>


<debtor>


<classification
dictionary=« ETAI:person »


ref=« {personRef} »/>

</debtor>


<date-list>


<explicit-date>


<breakdown-list>


<classification
dictionary=« ETAI:date »


ref=« validity »/>

</breakdown-list>


<date
format=« {datePattern} »>{dateValue}</date>


<classification-list>


<classification
dictionary=« ETAI:availability »


ref=« {availabilityRef} »/>


</classification-list>


</explicit-date>


</date-list>


<currency
dictionary=« ETAI:unit » ref=« euro »/>


<discount-link-list>


<discount-link discount-internal-id=« {discountInternalId} »


number=« {discountNumber} »/>


</discount-link-list>


</price>

Unit price at the purchase date

Not available in the getStock request

Each price can be linked to a discount through {discountInternalId}

Each price can be linked to a <person> corresponding to a storage location specified by {personInternalId}

The part’s Unit price is specified by the <classification> element referring to « unit » in the ETAI:Unit dictionary.

The {amountvalue} in the <Value><amount> element is the price excluding tax.

If there is a deduction for this price, the <value> element will contain a <include-deduction> element referring to the « ETAI:deductionType » dictionary and the ref « discount »

The <Debtor> element specifies that the purchase price is for a « person » referring to the « ETAI:person » dictionary.

{personRef} values are :

  • « repairer » : purchase price for a repairer (a mechanic)
  • « wholesaler » : purchase price for a wholesaler

The validity date for a price is specified in the <date-list> element, the « ETAI:date » dictionary and the ref « validity »

The validity type is specified by the « ETAI:availability » dictionary

Selfexplanatory Values for {availabilityRef} are :

  • «within24h »
  • « within48h »
  • « withinWeek »
  • « forthnight »
  • « other »
  • « unknown »

Dates are defined using a pattern (see stock availability for more information).

The currency refers to the « ETAI:unit » dictionary and the « euro » ref. Optional if already specified in the default settings

If there are several discounts for the same price then all these discounts will be

listed in <discount-link-list> by specifying several <discount-link>elements.

{discountInternalId} in <discount-link> does make the link to the discount, and {discountNumber} specifies a discount order.

Number of <discount-link> : 0 to n discounts

<price discountinternal-id=« {discountInternalId} » personinternal-id=« {personInternalId} »>

<breakdown-list>


<classification
dictionary=« ETAI:unit »


ref=« packet »/>


</breakdown-list>


<value-list>


<value
value-type=« exclTaxes »>


<amount>{priceAmount}</amount>


<amount-of>


<classification
dictionary=« ETAI:unit »


ref=« packet »>

{quantity}

</classification>


</amount-of>


<include-deduction>


<classification
dictionary=« ETAI:deductionType »


ref=« discount »/>

</include-deduction>

</value>

</value-list>


<debtor>


<classification
dictionary=« ETAI:person »


ref=« {personRef} »/>


</debtor>


<date-list>


<explicit-date>


<breakdown-list>


<classification
dictionary=« ETAI:date »


ref=« validity »/>

</breakdown-list>

<date
format=« {datePattern} »>{dateValue}</date>


<classification-list>


<classification
dictionary=« ETAI:availability »


ref=« {availabilityRef} »/>

</classification-list>


</explicit-date>


</date-list>


<currency
dictionary=« ETAI:unit » ref=« euro »/>


<discount-link-list>


<discount-link discount-internal-id=« {discountInternalId} »


number=« {discountNumber} »/>


</discount-link-list>

 


</price>

Price for Parts packet

Not available in the getStock request

Each price can be linked to a discount through {discountInternalId}

Each price can be linked to a <person> corresponding to a storage location specified by {personInternalId}

Prices can vary depending on the quantity ordered. For example, for 10 items ordered, the price is 10 euros, and for 100 ordered the price is 95 euros.

Several <values> can be defined. {priceAmount} is the total price for the {quantity} ordered

If there is a deduction for this price, the <value> element will contain a <include-deduction> element referring to the « ETAI:deductionType » dictionary and the ref « discount »

The <debtor> element specifies that the price being described is a purchase price.

{personRef} values are :

  • « repairer » : part price for a repairer (mechanic)
  • « wholesaler » : part price for a wholesaler

For the validity date description, please refer to the unit price description.

 

If there are several discounts for the same price then all these discounts will be listed in <discount-link-list> by specifying several <discount-link>elements.

{discountInternalId} in <discount-link> does make the link to the discount, and {discountNumber} specifies a discount order.

Numbers of <discount-link> : 0 to n discounts


<price discountinternal-id=« {discountInternalId} » personinternal-id=« {personInternalId} »>


<breakdown-list>


<classification
dictionary=« ETAI:unit »
ref=« unit »/>


</breakdown-list>


<value-list>


<value
value-type=« exclTaxes »>


<amount>{amountValue}</amount>


<amount-of>


<classification
dictionary=« ETAI:unit »


ref=« unit »/>

</amount-of>


<include-deduction>


<classification
dictionary=« ETAI:deductionType »


ref=« discount »/>

</include-deduction>


</value>


</value-list>


<debtor>


<classification
dictionary=« ETAI:person »


ref=« client »/>

</debtor>


<currency
dictionary=« ETAI:unit » ref=« euro »/>


<discount-link-list>


<discount-link discount-internal-id=« {discountInternalId} »


number=« {discountNumber} »/>


</discount-link-list>

 


</price>

Part Selling Unit price

Not available in the getStock request

Each price can be linked to a discount through {discountInternalId}

Each price can be linked to a <person> corresponding to a storage location specified by {personInternalId}

If there is a deduction for this price, the <value> element will contain a <include-deduction> element referring to the « ETAI:deductionType » dictionary and the ref « discount

The element <debtor> specifies that the price is an end-user selling price via the <classification> from « ETAI:person » dictionary and the ref  « client ».

If there are several discounts for the same price then all these discounts will be listed in <discount-link-list> by specifying several <discount-link>elements.

{discountInternalId} in <discount-link> makes the link to the discount, and {discountNumber} specifies a discount order.

Numbers of <discount-link> : 0 to n discounts


<price>


<breakdown-list>


<classification
dictionary=« ETAI:price »
ref=« {price-ref} »/>


</breakdown-list>


<value-list>


<value
value-type=« exclTaxes »>


<amount>{amountValue}</amount>


</value>


</value-list>


</price>

related article price (optional)

Not available for the getStock request

This element specifies the price for related articles, by defining the values for ecotaxes and payback deposit.

{price-ref} has 2 values  :

ecotaxe : for eco-taxes

depositPayback : for the deposit payback

{amountValue} : is the value for the related article


</price-list>
 
<status>
 
<classification
dictionary=« ETAI:status »


ref=« {statusRef} »>{statusValue}<classification/>

Part status (optional)

Definition of the Part status ( see ETAI :status dictionary).

{statusRef} values are  :

  • « finished »
  • « known »
  • « obsolete »
  • « replaced »
  • « transcoded » : transcoded reference
  • « unknown »
  • « ambiguous » : several parts correspond to the sent reference
  • « orderableMinimalQuantityError » : the quantity ordered is below the minimum orderable quantity
  • « multipleOrderableQuantityError » : error on the sales multiple
  • « insufficientStock »
  • « other » : any other reason
  • « onError » : the part could not be processed

If S@lto does not know a part, then a <part> with an « unknown » <status> is sent back (without price and without stock, because the part is unknown)

{statusValue} is used to add extra information to the part


<classification
dictionary=« ETAI:cause »


ref=« {causeRef} »>{causeLabel}


</classification>

Error cause (optional)

If the status above is « onError », the error cause must be explained.

If the error is due to a missing reference {causeRef} values are :

  • « noCatalogReference »
  • « noReferenceClean »
  • « noEan »
  • « noArticleCode »
  • « noIpc »
  • « NoRefcom »

For any other reasons  :

  • « other »

{causeLabel} adds a label. Used mainly for the « other » case


</status>
  <comment-list>

<comment>{comment}</comment>

<classification-list>

<classification
dictionary=« ETAI:commentType »
ref=« {commentTypeRef} »/>

</classification-list>

</comment-list>

Comment (optional )

Comment on the Part.

{commentTypeRef} Values are :

  • « commercial » : refers to a commercial comment
  • « other » : for any other comment

</part>

</part-list>

</shuttle>

</xat2>

  1. Error Handling

The Partner Application must handle errors to notify S@lto when the request was not successfully processed.

Technical errors that have to be handled by the Partner application are listed in Section 5.5 Blocking issues in XAT2V2.

  1. Send Basket/ Order

    1. Description

The goal of this service is to send a basket to a Partner application. « Secondary DMS » or « partner application » will be equally use in the remaining of this chapter to describe the application to which the basket is sent.

« Primary DMS » is a DMS to which only prices and stocks messages are sent.

« Secondary DMS » is a DMS to which sent basket/orders messages are exchanged in addition to the getStock and Price requests.

  1. Request Volume and frequency

Avg nb of requests/day

Request max nb /
15 minutes

Request Avg size

For the partner information

Request Max size

Partner Application

Response avg size

S@lto

Response max size
réponse

S@lto

  1. XAT2V2 request : S@lto Ú Partner application

Verb : postBasket

XAT2V2 message sent by S@lto to the Partner application

Table 9 – postBasket XML

XML

Description

<?xml
version=« 1.0 »
encoding=« utf-8 »
standalone=«  »?>

<xat2
xmlns=« http://xat2.etai.fr » version=« 2.0 »>
 <session-context>

<application-id>{applicationId}</application-id>

<dms-login>{dmsLogin}</dms-login>

<user-shared-id>{userSharedId}</user-shared-id>

<garage-shared-id>{garageSharedId}</garage-shared-id>

</session-context>

session identifiers (mandatory)

<shuttle>

 

<transport>
  <partner>

<name>S@lto</name>

<editor dictionary=« ETAI:editor »
ref=« etai »>

<version-code>{applicationVersion}</version-code>

</partner>

S@lto Information (Optional)

{applicationVersion} S@lto application version


<partner-data-list> Partner information list (optional)

 

 

This element is used for transferring miscellaneous data to a Partner application (ie, discounts, specific user identifier,etc ….)


number of elements  : 0 to 1


<partner-data
ref=« {dmsLoginValue} »>
DMS definition
{dmsLoginValue} is the dmsLogin from the DMS to which these data are targetted

 

number of elements  : 1 to N


<classification
ref=« {partnerDataRef} »>{partnerDataValue}</classification>
Partner application Data Definition

For each Partner, several data can be defined . One data per <classification>element .

 

{partnerDataRef} is the data identifier (exemple : ID_USER)

{partnerDataValue} is the value of the data (exemple : 12345)

 

number of elements  : 1 to N


</partner-data>
  </partner-data-list> 
<action-list>


<action>


<verb>postBasket</verb>

XAT2V2 Verb (mandatory)

postBasket is a verb used when sending an order


</action>


</action-list>

</transport> <default-shuttle-settings>  <currency
dictionary=« ETAI:unit »
ref=« euro »/>

Default currrency (optional)

Euro is the default currency

<language
dictionary=« ETAI:language »
ref=« {languageRef} »
/>

User language (optional)

Language of the request’s sender.

{languageRef} any of the values from the dictionary ETAI :language dictionary

Examples : FR / NL / DE / IT / etc.

</default-shuttle-settings> <person-list>
 
<person>


<breakdown-list>


<classification
dictionary=« ETAI:person »



ref=« {personRef} »/>


</breakdown-list>

Repairer/Wholesaler Declaration

{personRef} values are :

  • « repairer » : for a repairer (mechanic)
  • « wholesaler » : for a wholesaler


<name>{garageName}</name>


repairer/wholesaler’ name


<place>


<address
number=« 1 »>{addressLine1}</address>


<address
number=« 2 »>{addressLine2}</address>


<zip-code>{zipCode}</zip-code>


<city>{city}</city>


<country>


<classification
dictionary=« ETAI:country »


ref=« {countryRef} »>

{countryLabel}

</classification>


</country>


</place>

repairer/wholesaler’ address

An address can be split into several lines : Several <address> elements are defined and the number attribute value is increased for each element ( maximum : 5)

The country of the address is specified in the ETAI:Country dictionary.


<contact-list>


<contact>


<contact-category
dictionary=« ETAI:contact »


ref=« {contactRef} »/>


<contact-value>{contactValue}</contact-value>


</contact>


</contact-list>

Preferred repairer/wholesaler communication means

Communication means are defined in the « ETAI:contact »dictionary

{contactRef} values are :

  • « phone »
  • « mobile »
  • « fax »
  • « email »


</person>

</person-list>

<vehicle-list>

Cars list (optional)

Describes the cars linked to the basket

number of elements  : 0 to N

<vehicle internal-id=« {vehicleInternalId} »>

Car Definition

{vehicleInternalId} is the technical id that links a part to a car

Internal-id definition is optional

It is used only if the current basket refer to several cars, to be able to make the link between a part, and a specific car.


<label>


<short-label>{shortLabel}</short-label>


<long-label>{longLabel}</long-label>


</label>

Variant Label


<identification-list>

List of vehicle identifiers


<identification>


<breakdown-list>


<classification
dictionary=« ETAI:vehicle »



ref=« make »/>


</breakdown-list>

<label>

<short-label>{makeLabel}</short-label>

</label>


<classification-list>


<classification
dictionary=« ETAI:identifier »


ref=« makeId »


source=« etai »>

{makeId}


</classification>


</classification-list>


</identification>

Vehicle Make

The vehicle make is specified within the <identification> element , by the <classification> refering to the ETAI:vehicle dictionary and the « make » ref.

{makeLabel} : is the make label, like« RENAULT »

The Make identifier is also specified within the <identification> element , by the <classification> refering to the ETAI:identifier dictionary and the « makeId » ref,

the source attribute value is « etai », which is the identifier of the E-T-A-I vehicle database.


<identification>


<breakdown-list>


<classification
dictionary=« ETAI:vehicle »



ref=« model »/>


</breakdown-list>

<label>

<short-label>{modelLabel}</short-label>

</label>


<classification-list>


<classification
dictionary=« ETAI:identifier »


ref=« modelId »


source=« etai »>

{modelId}


</classification>


</classification-list>


</identification>

Vehicle Model

The vehicle model is specified within the <identification> element , by the <classification> refering to the ETAI:vehicle dictionary and the « model » ref.

This kind of identification is related to the car-body (number of doors, body shape …)


{modelLabel} : is the label of the model vehicle, like « CLIO IV ».

The model identifier is also specified within the <identification> element , by the <classification> refering to the ETAI:identifier dictionary and the « modelId » ref, the source attribute value is « etai », which is the identifier of the E-T-A-I vehicle database.



<identification>


<breakdown-list>


<classification
dictionary=« ETAI:vehicle »



ref=« variation »/>


</breakdown-list>

<label>

<short-label>{variationLabel}</short-label>

</label>


<classification-list>


<classification
dictionary=« ETAI:identifier »


ref=« variationId »


source=« etai »>

{variationId}


</classification>


</classification-list>


</identification>

Variation identification

The vehicle variation is specified within the <identification> element , by the <classification> refering to the ETAI:vehicle dictionary and the « variation » ref

This kind of identification is related to the car mechanics (capacity, fuel …)


{variationLabel} : variation label, like « 1.6i [RS] 200 16V Turbo (147kW) -M5M_400- R6 ».

The variation identifier is also specified within the <identification> element , by the <classification> refering to the ETAI:identifier dictionary and the « VariationId » ref, the source attribute value is « etai », which is the identifier of the E-T-A-I vehicle database.



</identification-list>

 


<alternative-ref-list>


<classification
dictionary=« ETAI:vehicle »


ref=« {refType} »>

{refValue}


</classification>


</alternative-ref-list>

Vehicle administrative identifiers

The administrative identifiers are specified within the <alternative-ref-list> element , by the <classification> refering to the ETAI:vehicle dictionary and the « RefType » ref

{refType} values are:

  • « engineType »
  • « vvt » (variation version type)
  • « cnit »
  • « vin »
  • « registration »

</vehicle>

</vehicle-list>

<part-list>

<part>

< <breakdown-list>

<classification
dictionary=« ETAI:breakdown »


ref=« {breakdownValue} »/>

<classification
dictionary=« ETAI:partIdentification »


ref=« {partIdentificationValue} »/>

</breakdown-list>

Part Type identifiers.

The Part Type identifiers are specified within the <Part-list> element , by 2 <classification> elements refering to the ETAI:breakdown dictionary and the « breakdownvValue » ref and by the ETAI:partIdentification dictionary and the « partIdentificationValue » ref.

{breakdownValue} values are :

  • « part » for a part
  • « tire » for a tire
  • « ingredient » for an ingredient

Values for {partIdentificationValue} :

  • « elementOE » for original equipment parts
  • « elementAM » for parts from car parts manufacturer (secondary market parts)
  • « elementPRE » for re-used parts
  • « elementGU » for parts from the Universal products list
  • « elementIU » for ingredient from the universal ingredient list

<reference-list>


<classification
source=« {sourceValue} »>

ref=« {referenceValue} »>

</classification>


</reference-list>

Part reference (mandatory)


Source attribute
, contains the source/type of the reference.

{sourceValue} values are :

  • « catalog » : raw reference from the catalogue
  • « clean » : clean reference
  • « ean » : ean-13 code
  • « articleCode » : PLC + reference
  • « ipc » : for tire only (International Patent Classification)
  • « refcom » : for tire only (commercial reference)

{referenceValue} is the value for the reference

number of elements  : 1 to N: depends on the Partner application

<supplier>


<classification-list>


<classification
source=« etai »


ref= »{supplierIdETAI} »/>


</classification-list>


</supplier>

part manufacturer (mandatory)

{abbreviationValue} is the abbreviation of the supplier .

For all Parts, the ETAI identifier for the manufacturer is used in {supplierIdETAI}.


<quantity
value-type=« amount »>


<amount>{quantityAmount}</amount>


</quantity>


quantity needed (optional)

{quantityValue} is the quantity expected by the end-user

<vehicle-link-list>

    <vehicle-link
vehicle-internal-id=« {vehicleInternalId} »
/>

</vehicle-link-list>

Link between part and vehicle (optional)

If the current basket refers to several cars, a part can be linked to a specific car via the {vehicleInternalId} which is defined in a <vehicle> element of the initial request <settings>

number of elements  : 0 to N


</part>


</part-list>


<comment-list>


<comment>{comment}</comment>


</comment-list>

Comments (optional)

{comment} about the basket and its contents.

</shuttle>

</xat2>

 

  1. XAT2V2 response : Partner Application Ú S@lto

Description of the content of the response of a PostBasket request.

The response data flow is a Xat2V2 message containing a Part Basket.

The Partner application (DMS) has to send a response to the request, specifying for each part the order status.

Table 10 – Response to the postBasket request

XML

Description

<?xml
version=« 1.0 »
encoding=« utf-8 »
standalone=« no »?>
<xat2
xmlns= »http://xat2.etai.fr«  version=« 2.0 »>

<message-list>

<message>


<message-category>ack</message-category>


<technical-description>


postBasket processing complete


</technical-description>


<classification-list>


<classification
dictionary=« Xat2:message »

ref=« complete »>


</classification>


</classification-list>


</message>


</message-list>

Acknowledgement

Message of ack category.

The <technical-description> {verb} specifies the verb to which this message is responding followed by processing complete if the processing went well.

<message-list> contains a message indicating the status of the exchange via a <classification> from the « Xat2:message » dictionary and the ref « complete 

<session-context>

 

<application-id>{applicationId}</application-id>

<dms-login>{dmsLogin}</dms-login>

<user-shared-id>{userSharedId}</user-shared-id>

<garage-shared-id>{garageSharedId}</garage-shared-id>

</session-context>

XAT2V2 session

<shuttle>
<transport> 
<message-list>

<message>

 


<message-category>information</message-category>


<classification-list>


<classification
dictionary=« ETAI:status »


ref=« {statusRef} »/>


</classification-list>


</message>


</message-list>

Basket status

Basket status is specified in a message of category « information »  and a classification in the dictionary ETAI :status

{statusRef} values are :

  • « complete » : all the parts have been correctly processed.
  • « partial » : some parts haven’t been correctly processed
  • « rejected » : all the parts haven’t been correctly processed
  • « deliveryTourUnavailable » : delivery tour specified in the request is not available

<admin-list> 

<classification
dictionary=« ETAI:admin »
ref=« fileNumber »
source=« etai »>{basketId}</classification>

Order/Basket identifier (mandatory if specified in the request)

{basketId} is the basket identifier

If the request contains a filenumber, the same filenumber must be sent back in the response.


<classification
dictionary=« ETA:admin »


ref=« deliveryNumber »>

 


{deliveryNumberValue}

</classification>

Delivery Number

</admin-list> 

</transport>
<settings> 
<VAT-list>
 
<VAT-rate internal-id=« {idValue} »>

<value><amount>{amountValue}</amount></value>

 


</VAT-rate>

VAT (mandatory if prices includes Taxes)

VAT is a percentage in {amountValue}. Declaration of multiple VAT rate is possible.

« internal-id » links a VAT rate and a price.

numbers of elements <VAT-rate> : 0 to N


</VAT-list>
  <discount-list>

<discount
internal-id=« {internalIdValue} »>

 


<breakdown-list>


<classification
dictionary=« ETAI:applicability »


ref=« {applicabilityRef} »/>


</breakdown-list>


<value
value-type=« percent »>


<amount>{amountValue}</amount>


</value>

<label>

    <short-label>{discountCode}</short-label>

    <long-label>{discountLabel}</long-label>

</label>


</discount>


</discount>


</discount-list>

Basket/part Discount (optional)

Definition of the discount that can be applied to a part price and/or to the basket total price

All the discounts are expressed as percentages.

When a discount is defined for a whole set of parts from a same type, or on the total basket price, an applicability has to be defined using the ETAI:applicability dictionary

{applicabilityRef} values are :

  • « part » : default discount for parts and ingredients
  • « tire » : default discount for tire.
  • « total » : discount for the whole basket.

If a discount does not apply to all the parts, there is no need for defining applicability

{discountCode} is the code of the discount.

{discountLabel} is the label of the discount

A same discount can be used for several parts by declaring the discount {discountId} in the price of these parts.

Number of <discount> elements  : 0 to N


</settings>
 
<person-list>
 
<person
internal-id=« {personInternalId} »>
<breakdown-list>

 

<classification
dictionary=« ETAI:breakdown »


ref=« storageLocation »/>

<classification

dictionary=« ETAI:storageLocationType »
ref=« {storageLocationTypeValue} »/>

 

</breakdown-list>

<name>{nameOfStorageLocation}</name>


<place>


<address
number=« 1 »>{addressLine1}</address>


<address
number=« 2 »>{addressLine2}</address>


<zip-code>{zipCode}</zip-code>


<city>{city}</city>


<country>


<classification
dictionary=« ETAI:country »


ref=« {countryRef} »>

{countryLabel}


</classification>


</country>


</place>


</person>


</person-list>

stock(s) location (optional)

{storageLocationTypeValue} represents the type of storage, and can be one of the values below :

  • « primary » primary storage location
  • « secondary » secondary storage location
  • « express » express storage location

Address can contain several lines. In that case, there are several <address> tags, and the value of the attribute « number » is increased.

The address’ country is defined by « ETAI:country » dictionary

{personInternalId} links a person to a stock

Number of elements <person> of type « storageLocation » : 0 to N

 


</person-list>


<part-list>
 
<price-list>

Basket price list (mandatory)


<price discountinternal-id=« {discountInternalId} »>

<value-list>

 


<value
value-type=« exclTaxes »>


<amount>{amountValue}</amount>


</value>


<value
value-type=« taxes »>


<amount>{amountValue}</amount>


</value>


<value
value-type=« inclTaxes »>


<amount>{amountValue}</amount>


</value>


<value
value-type=« exclTaxes »>


<amount>{amountValue}</amount>


<include-deduction>


<classification
dictionary=« ETAI:deductionType »


ref=« discount »/>

</include-deduction>


</value>


<value
value-type=« taxes »>


<amount>{amountValue}</amount>


<include-deduction>


<classification
dictionary=« ETAI:deductionType »


ref=« discount »/>

</include-deduction>


</value>


<value
value-type=« inclTaxes »>


<amount>{amountValue}</amount>


<include-deduction>


<classification
dictionary=« ETAI:deductionType »


ref=« discount »/>

</include-deduction>


</value>


</value-list>

 


</price>

Total Basket price (mandatory)

The specificity of this price is that it is not linked to a VAT.

The totalprice can be linked to a discount through the {discountInternalId}.

The price excluding tax without deduction is mandatory. It is represented by the element <value/> of « exclTaxes » type with no <include-deduction/> element.

The VAT corresponding to the price with no deduction is optional. It is represented by the element <value/> of type « taxes » without <include-deduction/> element.

The price including VAT without deduction is optional. It is represented by the <value/>element of type « inclTaxes » without <include-deduction/> element.

The price exluding VAT with deduction is optional. It is represented by the element <value/> of type « exclTaxes » with a <include-deduction/> element.

The VAT corresponding to the price including tax with deduction is optional. It is represented by the element <value/> of type « taxes » with a <include-deduction/> element.

The price including tax with deduction is optional. It is represented by the element <value/> of type « inclTaxes » with a <include-deduction/> element.

Number of elements : 1


<price VATinternal-id=« {vatInternalId} »>

<value-list>

 


<value
value-type=« exclTaxes »>


<amount>{amountValue}</amount>


</value>


<value
value-type=« taxes »>


<amount>{amountValue}</amount>


</value>


</value-list>


</price>

Basket VAT Rate Breakdown (optional)

This price has the specificity of being linked to a VAT rate.

This price is linked to a VAT through the {vatInternalId}.

The price excluding tax is mandatory. It is specified by the element <value/> with a value-type set to « exclTaxes ».

The VAT amount is mandatory. It is specified by the element <value/> with a value-type set to « taxes ».

Number of <price/> elements with a VAT link : 0 to N (N being the number of VAT rates)


</price-list>
 
<part>
<breakdown-list>

 

<classification
dictionary=« ETAI:breakdown »


ref=« {breakdownValue} »/>

<classification
dictionary=« ETAI:partIdentification »


ref=« {partIdentificationValue} »/>

</breakdown-list>

Part Type identifier (if exists in the request)

The part Type is defined by the « ETAI:breakdown » dictionary.

Values for {breakdownValue} :

  • « part » for a part
  • « tire » for a tire
  • « ingredient » for an ingredient

 

Additional information for Parts only  can be added through « ETAI:partIdentification » dictionary .

Values for {partIdentificationValue} :

  • « elementOE » for original equipment parts
  • « elementAM » for parts from car parts manufacturer (secondary market)
  • « elementPRE » for re-used parts
  • « elementGU » for parts from the Universal products
  • « elementIU » for ingredient from the universal ingredient list

<reference-list>

<classification
source=« {sourceValue} » ref=« {referenceValue} » />

 

</reference-list>


Part reference

Same as in the initial request.

If Part identification is ambiguous (several parts found) then the DMS

Can send back several « articleCode » with their labels (in the source of the classification) so that the end-user can specify an article code

Format :

<classification
source=« articleCode » ref=« {referenceValue} »>{Label}

</classification>

<supplier>
<abbreviation>{abbreviationValue}</abbreviation>

 


<classification-list>


<classification
source=« etai »


ref=« {supplierIdETAI} »/>


</classification-list>


</supplier>

Part supplier (mandatory)

The < abbreviation > element specifies the supplier abbreviation for AfterMarket parts ( 3 or 4 characters ) . (optional)

For all the parts, ETAI identifiers are specified in the {supplierIdETAI}.

This is mandatory : it has to be the same as the supplier identifier sent in the initial request.


<quantity
value-type=« amount »>

<amount>{quantityValue}</amount>

 


</quantity>

Quantity of parts ordered (optional)

{quantityValue } Defines the number or parts ordered


<stock-list>

<stock
person-internal-id=« {personInternalId} »>

Part stock (optional)

Stock is linked to an address, defined by the {personInternalId} 


<value-list>

<value>

 


<amount>{stockAmount}</amount>


<amount-of>


<classification
dictionary=« ETAI:stock »



ref=« {stockRef} »/>


</amount-of>


</value>


</value-list>

Stock Type and quantity

Definition of all the types of stocks in value-list.

{stockAmount} specifies the quantity of parts in stock (optional)

Specifies the stock type in the classification of the <amount-of> element using the « ETAI:stock » dictionary.

{stockRef} Values :

  • « availableStock » : stock available
  • « reserved » : stock booked by another customer
  • « inOrder » : stock ordered
  • « unavailableStock » : stock not available

{stockAmount} being optional , if a <value> of one of the Type defined above has no information in {stockAmount}, it means that a stock exists for this type.

To indicate that a stock is not available, {stockRef} must be set to « unavailableStock »


<availability>

<delivery-list>

 


<delivery>


<label>


<short-label>{deliveryLabel}</short-label>


</label>


<date>


<date
format=« {datePattern} »>{dateValue}</date>


</date>


<carriage>


<breakdown-list>


<classification
dictionary=« ETAI:carriage »


ref=« {carriageValue} »>{deliveryTourCode}</classification>

</breakdown-list>


<price>


<value-list>


<value
value-type=« exclTaxes »>

<amount>{carriagePriceAmount}</amount>


</value>


</value-list>


<currency
dictionary=« ETAI:unit » ref=« euro »/>


</price>


</carriage>


</delivery>


</delivery-list>


</availability>

stock availability (optional)

The stock availability is specified in the <availability> element.

<short-label> element describes the availability ( example : delivered tomorow at 10 AM)

{deliveryLabel} is free-formed, but it can be formatted (cf. section 7.5 – availability date label format)

The <date> element describes the availability date –

Format is customizable. The {dateValue} format must correspond to the Format defined.

Example 1 : Year Month Day

<date format = « yyyMMdd  »

{dateValue}=20140413

Which corresponds to a delivery date on April 13th 2014

Example 2 : Year Month Day – Hour

<date format = « yyyMMdd-HH »

{dateValue}=20140413-15

Which corresponds to a delivery date on April 13th 2014 at 3PM

The parts ordered can be delivered in several ways, defined in the <delivery> element.

Values are specified in the « ETAI:carriage » dictionary

{carriageValue} Values are  :

  • « deliveryOnSite » : on site delivery
  • « removalOnSite » : removal on site
  • « deliveryOnTour » : delivery on Tour
  • « postalParcel » : Postal Parcel
  • « expressDelivery » : express delivery
  • « other » : other
  • « unknown » : unknown

{deliveryTourCode} states the code of the delivery Tour.

The delivery price is specified in the <price> element of the carriage element



</stock>

</stock-list>
  <instruction-list>  <instruction>
<quantity>

 

<amount>{orderableMinimalQuantityValue}</amount>

</quantity>

<classification-list>

<classification
dictionary=« ETAI:instruction »
ref=« orderableMinimalQuantity »
/>

</classification-list>

</instruction>

Order Minimum quantity (optional)

The minimum order quantity for a part is defined in the <instruction> <quantity> element , with a classification ref « orderableMinimalQuantiy ».

In the <Amount> element {orderableMinimalQuantityValue is set to the minimum quantity to be ordered.

Example : if the minimum quantity for a part order is 2 then {orderableMinimalQuantityValue} will be set to 2.

<instruction>
<quantity>

 

<amount>{multipleOrderableQuantityValue}</amount>

</quantity>

<classification-list>

<classification
dictionary=« ETAI:instruction »
ref=« multipleOrderableQuantity »
/>

</classification-list>

</instruction>

sales packaging (optional)

An order quantity multiple for the part can be defined in the <instruction> <quantity>element with a <classification ref>  » multipleOrderableQuantity » from the ETAI:Instruction dictionary

In the <amount> element, {multipleOrderableQuantiyValue} will be set to the order multiple

Example : if a part has to be ordered in pairs (2 or 4, or 6…) {multipleOrderableQuantiyValue} is set to 2.

</instruction-list> 
<price-list>

<price personinternal-id=« {personInternalId} »>

 


<breakdown-list>


<classification
dictionary=« ETAI:unit »


ref=« unit »/>

</breakdown-list>


<value-list>


<value
value-type=« exclTaxes »>


<amount>{amountUnitValue}</amount>


</value>


</value-list>


</price>

 


<price VATinternal-id=« {vatInternalId} »

discountinternal-id=« {discountInternalId} » personinternal-id=« {personInternalId} »>


<breakdown-list>


<classification
dictionary=« ETAI:unit »


ref=« packet »/>


</breakdown-list>


<value-list>


<value
value-type=« exclTaxes »>


<amount>{amountTotalValue}</amount>


<include-deduction>


<classification
dictionary=« ETAI:deductionType »


ref=« discount »/>

</include-deduction>


</value>


<value
value-type=« inclTaxes »>


<amount>{amountTotalValue}</amount>


<include-deduction>


<classification
dictionary=« ETAI:deductionType »


ref=« discount »/>

</include-deduction>


</value>


</value-list>


<discount-link-list>


<discount-link discount-internal-id=« {discountInternalId} »


number=« {discountNumber} »/>


</discount-link-list>

 


</price>


</price-list>

Part Price

Part Unit price, and price for the total quantity of parts ordered

Each price can be associated with a <person> corresponding to a storage location thru the {personInternalId}

Part unit price is characterized by the element classification, refering to the Unit value in the ETAI:unit. Dictionary.

The <value> in {amountUnitValue} contains the price excluding taxes .

The part total price can be linked to a VAT through the attribute VAT-internal-id and a discount thru the discount-internal-id attribute for the price including tax.

The price with VAT is optional

A discount can be associated to each price, through the {discountInternalId} of the <price> element.

If there are several discounts for the same price then all these discounts can be listed in <discount-link-list> by specifying several <discount-link>elements.

{discountInternalId} in <discount-link> does make the link to the discount, and {discountNumber} specifies a discount order.

Number of <discount-link> : 0 to n discounts

The <value> on which a discount is applied contains an element <include-deduction> of the dictionary « ETAI:deductionType



<status>
 
<classification
dictionary=« ETAI:status »


ref=« {statusRef} » />

Part command status (mandatory)

Definition of the Part command status. (see status dictionary ETAI:status).

{statusRef} values are :

  • « complete » (order entirely made)
  • « partial » (order partialy made)
  • « rejected » (no part of this type has been ordered)
  • « onError » : the order for this part could not be processed successfully


<classification
dictionary=« ETAI:cause »


ref=« {statusRef} »>{statusValue}

 


</classification>

complement of the part Status (optional)

Definition of the complement part status (cf ETAI:cause dictionary).

{statusRef} values are :

  • unknown » (part unknown)
  • « ambiguous » (several parts for the same reference)
  • « orderableMinimalQuantityError » (minimum quantity is greater than the quantity requested)
  • « multipleOrderableQuantityError » (error on the multiple orderable quantity)
  • « insufficientStock » : (insufficient stock)
  • « other » : (miscellaneous reason)

For the « OnError » status, the {statusValue} may specify if the error is due to a missing reference :

  • « noCatalogReference »
  • « noReferenceClean »
  • « noEan »
  • « noArticleCode »
  • « noIpc »
  • « NoRefcom »

{statusValue} : additional information on the part status.

.

 


</status>


</part>

</part-list>
 
<comment-list>

<comment>{comment}</comment>

 


</comment-list>

Comments

This item is used for adding comments on the basket.

</shuttle>
</xat2>

 

  1. Error Handling

The partner application has to handle errors and notify S@lto in the case a request can not be executed.

Technical errors that must be handled by the partner application are listed in chapter 5.5, XAT2V2 Blocking issues

Table 11 : Partner Application Errors

Error Code

Description

expected behaviour

  1. Availability date label format

Date and Time formats can be specified in the <short-label/> of the <delivery/> element.

Specifying a new delivery date in the short-label is a way to add extra days to the initial delivery date.

The format is as follows :

for Date : {0, date[, format]}

for Time : {0, time[, format]}

Format has the following values :

08/07/2014 13:32:49

Date Examples

Time Example

French

English

Dutch

French

English

Dutch

Short 08/07/14 7/8/14 8-7-14 13:32 1:32 PM 13:32
Medium 8 juil. 2014 Jul 8, 2014 8-jul-2014 13:32:49 1:32:49 PM 13:32:49
Long 8 juillet 2014 July 8, 2014 8 juli 2014 13:32:49 CEST 1:32:49 PM CEST 13:32:49 CEST
Full mardi 8 juillet 2014 Tuesday, July 8, 2014 dinsdag 8 juli 2014 13 h 32 CEST 1:32:49 PM CEST 13:35:41 uur CEST
pattern java, example :

 

       yyyy 2014 2014 2014      
       yyyyMMdd 20140708 20140708 20140708      
       HHmm       1332 1332 1332

Example :

For :

<availability>

    <delivery-list>

        <delivery>

            <label><short-label>{0, date, long}</short-label></label>

            <date><date format= »yyyyMMdd »>20140709</date></date>

        </delivery>

    </delivery-list>

</availability>

The english label <short-label/> is « july 9, 2014 ».

For :

<availability>

    <delivery-list>

        <delivery>

            <label><short-label>Delivery on {0, date, full} at {0, time, short}</short-label></label>

            <date><date format= »yyyyMMddHHmm »>201407081000</date></date>

        </delivery>

    </delivery-list>

</availability>

The english Label is « delivery on Tuesday, July 8, 2014 at 10:00AM ».

Publié dans Documentation technique