Not logged in - Login

Webshop API Interface Specification

Version 0.1

Table of Contents

  1. Introduction
    1. Overview
    2. Audience
    3. Document Overview
    4. Getting Started
    5. How to Send Request
  2. Basic Concepts
    1. Message Transport
    2. Authentication
    3. Message Structure
  3. XML Message
    1. WS_AuthenticationRQ/RS
      1. Support Operations
      2. Business Rules
      3. WS_AuthenticationRQ
      4. Sample Message Request
      5. WS_AuthenticationRS
      6. Simple Message Response Success
    2. WS_CategroySetRQ/RS
      1. Support Operations
      2. Business Rules
      3. WS_CategroySetRQ
      4. Sample Message Request
      5. WS_CategroySetRS
      6. Simple Message Response Success
    3. WS_UpdateCategoryRQ/RS
      1. Support Operations
      2. Business Rules
      3. WS_UpdateCategoryRQ
      4. Sample Message Request
      5. WS_UpdateCategoryRS
      6. Simple Message Response Success
    4. WS_UpdateProductRQ/RS
      1. Support Operations
      2. Business Rules
      3. WS_UpdateProductRQ
      4. Sample Message Request
      5. WS_UpdateProductRS
      6. Simple Message Response Success
    5. WS API ‘Status’ Values List

1 Introduction

1.1 Overview

The use of this interface for communication with the exPub Service Providers using OTA compliant XML messaging over an HTTP protocol. The interface supports the exchange of:
  • Authentication
  • Get Category Set
  • Add/Update Category
  • Add/Update Product

The purpose of this interface is to facilitate dynamic data synchronization such as category name, product name, product variant name, description

1.2 Audience

This document is intended for technical staff at the webshop portal development company. The reader should be familiar with the underlying technologies used, including XML and HTTPS.

1.3 Document Overview

This document is divided into chapters covering background information, business rules, use cases, error and warning messages. The chapter detailing each of the messages describes some or all of the following:
  • An overview of the message format
  • The XML and business rules that apply to the message
  • A tabular listing of the elements and attributes in the message
  • Sample XML messages

1.4 Getting started

Our XML Web Service cannot be accessed by unauthorized requests. You will first need to contact us to get the Application Token before you can make requests. Your usage of our XML Web Service will be monitored by our staff: we reserve the right to close an XML account if its number of requests is huge.

1.5 How to send requests

The addresses to which to send requests are the following:

https://api.expubwebsites.net/WebshopApi/Authentication
https://api.expubwebsites.net/WebshopApi/GetCategorySet
https://api.expubwebsites.net/WebshopApi/UpdateCategory
https://api.expubwebsites.net/WebshopApi/UpdateProduct

You must send your XML with POST request. This can be achieved through various programming methods, which will vary according to the programming language you're using. For example, in PHP the simplest way to send this kind of requests is using the CURL extension.

2 Basic Concepts

2.1 Message Transport

All messages are transported via HTTP POST.

2.2 Authentication

The WebShopAPI provides the credentials necessary for consuming the WebServices being offered to the receiving system. Security credentials consist of: Token – A login for authentication that is provided by the WebShopAPI at the time of the order e.g. The requesting system should have the ability to connect to different URLs. Connections to the different servers may use the same account information

2.3 Message Structure

Version - This decimal value identifies the specific version of the WebShop API XML schema associated with an XML instance document. Our system does not block requests that are earlier or later than the version we are supporting, and will try to reply to them if possible.

Token - The value of this attribute is assigned by a requesting system and serves as a reference for messages that may follow an initial request. When a request message includes an echo token, the corresponding response message must include an echo token with an identical value. This makes it possible for two or more messages to be correlated together as part of a single transaction.

Message - This element indicates that the recipient of a message identified one or more warnings. A warning is a business-level error. The XML content might be syntactically valid, but the receiving application cannot fulfill the request.

Status - Message Code.

Request - This date and time value specifies the creation date and time of a message. This value is UTC format specified by ISO 8601—YYYY-MM-DDThh:mm:ssZ—with time values using the 24-hour clock (e.g., 20 May 2014, 1:59:38 p.m. UTC becomes 2013-05- 20T13:59:38).

3 XML Messages

3.1 WS_AuthenticationRQ/RS

This message identifies the initial request for checking authentication.

3.1.1 Support Operations

Portal requests information about the authentication.

3.1.2 Business Rules

This message is only sent from the portal to the Service Providers. Only requests received via POST method will be accepted.

3.1.3 WS_AuthenticationRQ

This message identifies the initial request for order data. Using this message the requester may retrieve status authentication.

ParameterElement(E)
Attribute(A)
Required(R)
Optional(O)
NotesData Type/ Possible values
WS_AuthenticationRQERRoot Element 
WS_AuthenticationRQ/TokenARA reference for additional message identification, assigned by the requesting host system. When a request message includes an echo token the corresponding response message include an echo token with the identical valueString Length:1 -128

3.1.4 Sample Message Request

Post on url https://api.expup.net/WebshopApi/Authentication

<WS_AuthenticationRQ Token=”99999999999999999999999999999999999999999999999”> </WS_AuthenticationRQ>

3.1.5 WS_AuthenticationRS

The WS_AuthenticationRS is the message used to indicate the status of processing the WS_AuthenticationRQ message. This message returns ''json'' that meets the requested criteria and/or Warnings, or Errors if the request did not succeed.

Element(E)
Attribute(A)
NameNotesData Type/ Possible values
EWS_AuthenticationRSRoot Element 
AWS_AuthenticationRS/APIAPI NameString Length:1 -20
AWS_AuthenticationRS/VersionThe message version indicated by a decimal value.Decimal
AWS_AuthenticationRS/TokenA reference for additional message identification, assigned by the requesting host system. When a request message includes an echo token the corresponding response message includes an echo token with the identical valueString Length:1 -128
AWS_AuthenticationRS/StatusIdentifies the status of the call url request.Integer
AWS_AuthenticationRS/MessageMessage call url request of statusString Length: 1 - 500
AWS_AuthenticationRS/RequestDate RequestTimeStamp

3.1.6 Simple Message Response Success

<WS_AuthenticationRS xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" API="WSP_Authentication" Version="0.1" Token="340FDFAE958CD5335A8CD22B390A6F76497ED23BFBAC877467" Status="2" Message="Success Authentication" Request="2015-07-02T09:58:41.8418681+07:00"/>

3.2 WS_CategorySetRQ/RS

This message identifies the initial request to get information category set.

3.2.1 Support Operations

Portal requests information about the authentication.

3.2.2 Business Rules

This message is only sent from the portal to the Service Providers. Only requests received via POST method will be accepted.

3.2.3 WS_CategorySetRQ

This message identifies the initial request for category set data. Using this message the requester may retrieve information category set

ParameterElement(E)
Attribute(A)
Required(R)
Optional(O)
NotesData Type/ Possible values
WS_CategorySetRQERRoot Element 
WS_CategorySetRQ/TokenARA reference for additional message identification, assigned by the requesting host system. When a request message includes an echo token the corresponding response message include an echo token with the identical valueString Length:1 -128
WS_CategorySetRQ/LanguageIdARThe primary language preference for the message encoded as ISO 639String Length:2

3.2.4 Sample Message Request

Post on url https://api.expub.net/WebshopApi/GetCategorySet

<WS_CategorySetRQ Token=340FDFAE958CD5335A8CD22B390A6F76497ED23BFBAC877467" LanguageId="en"></WS_CategorySetRQ>

3.2.5 WS_CategorySetRS

The WS_CategorySetRS is the message used to indicate the status of processing the WS_CategorySetRQ message. This message returns xml that meets the requested criteria and/or Warnings, or Errors if the request did not succeed.

Element(E)
Attribute(A)
NameNotesData Type/Possible values
EWS_CategorySetRSRoot Element 
AWS_CategorySetRS/APIAPI NameString Length:1 -20
AWS_CategorySetRS/VersionThe message version indicated by a decimal value.Decimal
AWS_CategorySetRS/TokenA reference for additional message identification, assigned by the requesting host system. When a request message includes an echo token the corresponding response message includes an echo token with the identical valueString Length:1 -128
AWS_CategorySetRS/StatusIdentifies the status of the call url request.Integer
AWS_CategorySetRS/MessageMessage call url request of statusString Length: 1 - 500
AWS_CategorySetRS/RequestDate RequestTimeStamp
EWS_CategorySetRS.CategorySets  
EWS_CategorySetRS.CategorySets.CategorySet  
EWS_CategorySetRS.CategorySets.CategorySet.CategorySetIdCategory Set IdInteger
EWS_CategorySetRS.CategorySets.CategorySet.NameCategory Set NameString Length: 1 - 500

3.2.6 Simple Message Response Success

<WS_CategorySetRS xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" Version="0.1" Token="340FDFAE958CD5335A8CD22B390A6F76497ED23BFBAC877467" Status="3" Message="Success Get CateogrySet" Request="2015-07-02T10:33:28.4720242+07:00">
  <CategorySets>
    <CategorySet>
      <CategorySetId>249</CategorySetId>
      <Name>Foo</Name>
    </CategorySet>
    <CategorySet>
      <CategorySetId>257</CategorySetId>
      <Name>Article category</Name>
    </CategorySet>
    <CategorySet>
      <CategorySetId>268</CategorySetId>
      <Name>Product Cateory</Name>
    </CategorySet>
    <CategorySet>
      <CategorySetId>270</CategorySetId>
      <Name>List Product</Name>
    </CategorySet>
  </CategorySets>
</WS_CategorySetRS>

3.3 WS_UpdateCategoryRQ/RS

This message identifies the initial request for updating category.

3.3.1 Support Operations

Portal requests update about a category.

3.3.2 Business Rules

This message is only sent from the portal to the Service Providers. Only requests received via POST method will be accepted.

3.3.3 WS_UpdateCategoryRQ

This message identifies the initial request update for categories. Using this message the requester may update a category

ParameterElement(E)
Attribute(A)
Required(R)
Optional(O)
NotesData Type/ Possible values
WS_UpdateCategoryRQERRoot Element 
WS_UpdateCategoryRQ/TokenARA reference for additional message identification, assigned by the requesting host system. When a request message includes an echo token the corresponding response message includes an echo token with the identical valueString Length:1 -128
WS_UpdateCategoryRQ/LanguageIdARThe primary language preference for the message encoded as ISO 639String Length:2
WS_UpdateCategoryRQ.CategorysE  
WS_UpdateCategoryRQ.Categorys.CategoryE  
WS_UpdateCategoryRQ.Categorys.Category.LegacyIdERExternal IdInteger
WS_UpdateCategoryRQ.Categorys.Category.CategorySetIdERThe Category Set that uniquely identifies from WS_CategorySetRSInteger
WS_UpdateCategoryRQ.Categorys.Category.NameERCategory NameString Length:1 - 200
WS_UpdateCategoryRQ.Categorys.Category.DescriptionEOCategory DescriptionString Length:1 - 999,999
WS_UpdateCategoryRQ.Categorys.Category.TopLevelCategoryEOCategory Setting About Top Level CategoryBoolean
WS_UpdateCategoryRQ.Categorys.Category.IsActiveEOCategory Setting About AvailableBoolean

3.3.4 Sample Message Request

Post to url https://api.expupwebsites.net/WebshopApi/UpdateCategory
<WS_UpdateCategoryRQ LanguageId="en" Token="340FDFAE958CD5335A8CD22B390A6F76497ED23BFBAC877467">
   <Categorys>
      <Category>
         <LegacyId>20</LegacyId>
         <CategorySetId>268</CategorySetId>
         <Name>Sofa</Name>
         <Description>All types of sofas</Description>
         <TopLevelCategory>true</TopLevelCategory>
         <IsActive>true</IsActive>
      </Category>
      <Category>
          <LegacyId>21</LegacyId>
          <CategorySetId>268</CategorySetId>
          <Name>Table</Name>
          <Description>All types of tables</Description>
          <TopLevelCategory>true</TopLevelCategory>
          <IsActive>true</IsActive>
      </Category>
   </Categorys>
</WS_UpdateCategoryRQ>

3.3.5 WS_UpdateCategoryRS

The WS_UpdatCategoryRS is the message used to indicate the status of processing the WS_UpdateCategoryRQ message. This message returns xml that meet the requested criteria and/or Warnings, or Errors if the request did not succeed.

Element(E)
Attribute(A)
NameNotesData Type/ Possible values
EWS_UpdateCategoryRSRoot Element 
AWS_UpdateCategoryRS/APIAPI NameString Length:1 -20
AWS_UpdateCategoryRS/VersionThe message version indicated by a decimal value.Decimal
AWS_UpdateCategoryRS/TokenA reference for additional message identification, assigned by the requesting host system. When a request message includes an echo token the corresponding response message includes an echo token with the identical valueString Length:1 -128
AWS_UpdateCategoryRS/StatusIdentifies the status of the call url request.Integer
AWS_UpdateCategoryRS/MessageMessage call url request of statusString Length: 1 - 500
AWS_UpdateCategoryRS/RequestDate RequestTimeStamp

3.2.6 Simple Message Response Success

<WS_UpdateProductRS xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" API="WSP_UpdateCategory" Version="0.1" Token="340FDFAE958CD5335A8CD22B390A6F76497ED23BFBAC877467" Status="4" Message="Success Updating Category" Request="2015-07-02T11:09:16.5481186+07:00"/>

3.4 WS_UpdateProductRQ/RS

This message identifies the initial request for update a product.

3.4.1 Support Operations

Portal requests update about a product.

3.4.2 Business Rules

This message is only sent from the portal to the Service Providers. Only requests received via POST method will be accepted.

3.4.3 WS_UpdateProductRQ

This message identifies the initial request update for products. Using this message the requester may update products.

ParameterElement(E)
Attribute(A)
Required(R)
Optional(O)
NotesData Type/ Possible values
WS_UpdateProductRQERRoot Element 
WS_UpdateProductRQ /TokenARA reference for additional message identification, assigned by the requesting host system. When a request message includes an echo token the corresponding response message include an echo token with the identical valueString Length:1 -128
WS_UpdateProductRQ /LanguageIdARThe primary language preference for the message encoded as ISO 639String Length:2
WS_UpdateProductRQ.ProductsER  
WS_UpdateProductRQ.Products.ProuductER  
WS_UpdateProductRQ.Products.Prouduct.ProductIdEOUpdate Product LecacyIdInteger
WS_UpdateProductRQ.Products.Prouduct.CateogryLegacyIdEO Integer
Products.Prouduct.CateogryLegacyId.LegacyIdEOExternal Category IdInteger
Products.Prouduct.LegacyIdERExternal Product IdInteger
Products.Prouduct.WebShopIdERFrom Admin AreaInteger
Products.Prouduct.CodeEOProduct CodeString Length:1 - 50
Products.Prouduct.IsActiveEOAvailableBoolean / Default False
Products.Prouduct.IsDeletedEODeleteBoolean / Default False
Products.Prouduct.PriceEOPrice For ProductDecimal / Default 0
Products.Prouduct.ProductNameERProduct NameString Length:1 - 500
Products.Prouduct.ShortDescriptionEOProduct DescriptionString Length:1 - 999,999
Products.Prouduct.FullDescriptionEOProduct Full DescriptionString Length:1 - 999,999
Products.Prouduct.MetaKeyWordEOProduct Meta KeywordString Length:1 - 400
Products.Prouduct.MetaDescriptionEOProduct Meta DescriptionString Length:1 - 4000
Products.Prouduct.MetaTitleEOProduct Meta TitleString Length:1 - 400
Products.Prouduct.SENameEOProduct SENameString Length:1 - 100
Products.Prouduct.TagEOProduct TagString Length:1 - 999,999
Products.Prouduct.ProductVideoEOProduct VideoString Length:1 - 200
Products.Prouduct.FeatureProductStartDateEOProduct Feature Start DateString / (yyyy-MM-dd)
Products.Prouduct.FeatureProductEndDateEOProduct Feature End DateString / (yyyy-MM-dd)
Products.Prouduct.FeatureMessageEOProduct Feature MessageString Length:1 - 500
Products.Prouduct.ImagesEO  
Products.Prouduct.Images.ImageEO  
Products.Prouduct.Images.Image.TitleEOProduct Image TitleString Length:1 - 999,999
Products.Prouduct.Images.Image.DescriptionEOProduct Image DescriptionString Length:1 - 999,999
Products.Prouduct.Images.Image.UrlERProduct Image UrlString Length:1 - 999,999
Products.Prouduct.VariantsEO  
Products.Prouduct.Variants.VariantEO  
Products.Prouduct.Variants.Variant.ProductVariantIdEOUpdate Variant LecacyIdInteger
Products.Prouduct.Variants.Variant.LegacyIdERExternal Product Variant IdInteger
Products.Prouduct.Variants.Variant.HeightEOProduct Variant HeightDouble
Products.Prouduct.Variants.Variant.WidthEOProduct Variant WidthDouble
Products.Prouduct.Variants.Variant.LenghtEOProduct Variant LenghtDouble
Products.Prouduct.Variants.Variant.WeightEOProduct Variant Weight (gram)Integer
Products.Prouduct.Variants.Variant.OrderMinimumQuantityEOProduct Variant Order Minimum QuantityInteger
Products.Prouduct.Variants.Variant.OrderMaximumQuantityEOProduct Variant Order Maximum QuantityInteger
Products.Prouduct.Variants.Variant.CallForPriceEOProduct Variant Call For PriceBoolean / Default is False
Products.Prouduct.Variants.Variant.PriceEOProduct Variant PriceDouble
Products.Prouduct.Variants.Variant.SKUEOProduct Variant SKUString Length:1 - 50
Products.Prouduct.Variants.Variant.StockEOProduct Variant StockInteger
Products.Prouduct.Variants.Variant.BackOrderPermittedEOProduct Variant BackOrder PermittedBoolean / Default is False
Products.Prouduct.Variants.Variant.ProductVariantTypeIdEOProduct Variant TypeInteger /
Default = 1,
CustomForm = 2,
PostCard = 3,
Calendar = 4,
Picture = 5,
File = 6,
Attribute = 7,
ProductAttribute = 8
Products.Prouduct.Variants.Variant.ProductUnitTypeIdEOProduct Variant Unit TypeInteger
Products.Prouduct.Variants.Variant.ProductPackageIdEOProduct Variant PackageInteger
Products.Prouduct.Variants.Variant.IncludedTaxEOProduct Variant Included TaxBoolean / Default is False
Products.Prouduct.Variants.Variant.TaxCategoryIdEOProduct Variant Tax Category IdInteger
Products.Prouduct.Variants.Variant.TaxExemptEOProduct Variant Tax ExemptBoolean / Default is False
Products.Prouduct.Variants.Variant.VolumeEOProduct Variant VolumeDouble
Products.Prouduct.Variants.Variant.FeatureVariantStartDateEOProduct Feature Start DateString / (yyyy-MM-dd)
Products.Prouduct.Variants.Variant.FeatureVariantEndDateEOProduct Feature EndDateString / (yyyy-MM-dd)
Products.Prouduct.Variants.Variant.NameERProduct Variant NameString Length:1 - 500
Products.Prouduct.Variants.Variant.DescriptionEOProduct Variant DescriptionString Length:1 - 999,999
Products.Prouduct.Variants.Variant.ImageEO  
Products.Prouduct.Variants.Variant.Image.UrlEOProduct Variant Image UrlString Length:1 - 999,999

3.4.4 Sample Message Request

Post to url https://api.expupwebsites.net/WebshopApi/UpdateProduct

<WS_UpdateProductRQ  LanguageId="en" Token="340FDFAE958CD5335A8CD22B390A6F76497ED23BFBAC877467">
    <Products>
        <Product>
            <CateogryLegacyId>
                <LegacyId>20</LegacyId>
                <LegacyId>21</LegacyId>
            </CateogryLegacyId>
            <LegacyId>39</LegacyId>
            <WebShopId>59</WebShopId>
            <Code>003</Code>
            <IsActive>true</IsActive>
            <Price>10000.00</Price>
            <EAN>8888888888</EAN>
            <ProductName>Leather sofa</ProductName>
            <ShortDescription>L-shaped sofa</ShortDescription>
            <FullDescription>5 seat L-shaped sofa</FullDescription>
            <MetaKeyWord></MetaKeyWord>
            <MetaDescription></MetaDescription>
            <MetaTitle></MetaTitle>
            <SEName></SEName>
            <Tag></Tag>
            <ProductVideo></ProductVideo>
            <FeatureProductStartDate>2015-06-01</FeatureProductStartDate>
            <FeatureProductEndDate>2015-06-25</FeatureProductEndDate>
            <FeatureMessage></FeatureMessage>
            <Permalink></Permalink>
            <Images>
                <Image>
                    <Title>Brown Sofa</Title>
                    <Description>Brown leather sofa</Description>
                    <Url>https://www.domain.com/images/brown-sofa1.png</Url>
                </Image>
                <Image>
                    <Title>Black Sofa</Title>
                    <Description>Black leather sofa</Description>
                    <Url>https://www.domain.com/images/black-sofa.png</Url>
                </Image>
            </Images>
            <Variants>
                <Variant>
                    <LegacyId>47</LegacyId>
                    <Height>123</Height>
                    <Width>12</Width>
                    <Lenght>2</Lenght>
                    <Weight>0</Weight>
                    <OrderMinimumQuantity>0</OrderMinimumQuantity>
                    <OrderMaximumQuantity>5</OrderMaximumQuantity>
                    <CallForPrice>false</CallForPrice>
                    <Price>10000.0000</Price>
                    <SKU>033</SKU>
                    <Stock>0</Stock>
                    <BackOrderPermitted>false</BackOrderPermitted>
                    <ProductVariantTypeId>0</ProductVariantTypeId>
                    <ProductUnitTypeId>0</ProductUnitTypeId>
                    <EAN>88888888</EAN>
                    <ProductUnitTypeId>0</ProductUnitTypeId>
                    <ProductPackageId>0</ProductPackageId>
                    <IncludedTax>true</IncludedTax>
                    <TaxCategoryId>0</TaxCategoryId>
                    <TaxExempt>false</TaxExempt>
                    <Volume>045</Volume>
                    <FeatureVariantStartDate>2015-06-02</FeatureVariantStartDate>
                    <FeatureVariantEndDate>2015-06-25</FeatureVariantEndDate>
                    <Name>Brown Sofa</Name>
                    <Description>L-shaped brown leather sofa</Description>
                    <PackageSize></PackageSize>
                    <Image>
                        <Url>https://www.domain.com/images/brown-sofa2.png</Url>
                    </Image>
                </Variant>
            </Variants>
        </Product>
    </Products>
</WS_UpdateProductRQ>

3.4.5 WS_UpdateProductRS

The WS_UpdatProductRS is the message used to indicate the status of processing the WS_UpdateProductRQ message. This message returns xml that meets the requested criteria and/or Warnings, or Errors if the request did not succeed.

Element(E)
Attribute(A)
NameNotesData Type/ Possible values
EWS_UpdateProductRSRoot Element 
AWS_UpdateProductRS/APIAPI NameString Length:1 -20
AWS_UpdateProductRS/VersionThe message version indicated by a decimal value.Decimal
AWS_UpdateProductRS/TokenA reference for additional message identification, assigned by the requesting host system. When a request message includes an echo token the corresponding response message includes an echo token with the identical valueString Length:1 -128
AWS_UpdateProductRS/StatusIdentifies the status of the call url request.Integer
AWS_UpdateProductRS/MessageMessage call url request of statusString Length: 1 - 500
AWS_UpdateProductRS/RequestDate RequestTimeStamp

3.4.6 Simple Message Response Success

<WS_UpdateProductRS xmlns:xsi="{{{http://www.w3.org/2001/XMLSchema-instance}}}" xmlns:xsd="[[[http://www.w3.org/2001/XMLSchema}}}" API="WSP_UpdateProduct" Version="0.1" Token="340FDFAE958CD5335G8CD22B390A6F76497ED23BFBAC877467" Status="5" Message="Success Update Product" Request="2015-07-03T13:43:07.5944621+07:00"/>

3.5 WS API 'Status' Values List

Status ValueDescription
1Success
2Success Authentication
3Success Get Category Set
4Success Update Category
5Success Update Product
6WebshopAPIError
7WebshopAPIErrorAuthentication