Marketplace API v2.6 Revision: 2.6.1 March 2015

Revision Summary Revision

Author

Summary

2.6

Seller Center Team

- whole documentation

2.6.1

Daniela Stärke

- Revision table

Inhaltsverzeichnis 1. Introduction...................................................................................................................................... 5 1.1. The API..........................................................................................................................................5 1.2. Feeds..............................................................................................................................................6 1.3. Data Types..................................................................................................................................... 6 2. Executing Requests and Authentication...........................................................................................7 2.1. Request Format..............................................................................................................................7 2.2. Signing the Request.......................................................................................................................7 2.2.1. Computing the Signature Parameter...........................................................................................7 2.3. Authenticationadmin......................................................................................................................8 2.4 API Call in Visual Basic.................................................................................................................9 2.5 API Call in Adobe ColdFusion.....................................................................................................10 2.6 API Call in Java............................................................................................................................12 3. Request Format...............................................................................................................................15 4. Response Format............................................................................................................................ 16 4.1. ErrorResponse Format.................................................................................................................16 4.2. SuccessResponse Format.............................................................................................................16 5. Product and Feed API.....................................................................................................................18 5.1. Products and Images....................................................................................................................18 5.1.1. GetProducts Action...................................................................................................................18 5.1.2. ProductCreate Action................................................................................................................19 5.1.3. ProductUpdate Action.............................................................................................................. 21 5.1.4. ProductRemove Action.............................................................................................................21 5.1.5. Image Action............................................................................................................................ 22 5.2. Feeds............................................................................................................................................23 5.2.1. FeedList Action........................................................................................................................ 23 5.2.2. FeedOffsetList Action...............................................................................................................24 5.2.3. FeedCount Action.....................................................................................................................24 5.2.4. FeedCancel Action....................................................................................................................25 5.3 Feed Throttling............................................................................................................................. 25 6. Sales Order API.............................................................................................................................. 26 6.1 Executing Requests and AuthenticationRequestID......................................................................26 6.1.1 Request Format..........................................................................................................................26 6.1.2 URL Request Parameters...........................................................................................................26 6.1.3 Signing the Request...................................................................................................................26 6.1.4 Computing the Signature Parameter..........................................................................................26 6.1.5 Authentication............................................................................................................................27 6.2 Response Format.......................................................................................................................... 27 6.2.1 ErrorResponseFormat................................................................................................................27 6.2.2 SuccessResponseFormat............................................................................................................28 6.3 Order Fetch API............................................................................................................................28 6.3.1 GetOrders.................................................................................................................................. 28 6.3.2 GetOrder....................................................................................................................................31 6.3.3 GetOrderItems........................................................................................................................... 32 6.4 Order Processing API................................................................................................................... 34 6.4.1 SetStatusToCanceled................................................................................................................. 34 6.4.2 SetStatusToReadyToShip.......................................................................................................... 35 6.4.3 SetStatusToShipped...................................................................................................................37 6.4.4 SetStatusToFailedDelivery........................................................................................................37 6.4.5 SetStatusToDelivered................................................................................................................ 39 6.5. Failed Reason API....................................................................................................................... 39

6.5.1 GetFailureReasons.....................................................................................................................39 6.6 Shipment Provider API.................................................................................................................40 6.6.1 GetShipmentProviders...............................................................................................................40 7. API Error Codes............................................................................................................................. 41 7.1 Global Errors................................................................................................................................ 41 7.2 Product API.................................................................................................................................. 42 7.3 Feed API....................................................................................................................................... 43 7.4 Sales Order API............................................................................................................................ 43

1. Introduction This document describes the technical details of Seller-Center API Marketplace Platform. The API uses a request-response mechanism, meaning requests are written and sent to SellerCenter, and a response is returned. Both requests and responses are written in XML format, and are sent via HTML request.

1.1. The API For convenience reasons, the actions are divided into scopes: Products, Feeds, and Orders.

The following Actions are available: Scope

Action

Description

Product

ProductCreate

Create a new product

Product

ProductUpdate

Update an existing product's details

Product

ProductRemove

Removes a product from the database

Product

Image

Upload product images

Feed

FeedList

Display all feed-requests

Feed

FeedOffsetList

Display feed-requests, skipping the first ones

Feed

FeedCount

Retrieves counters of the existing feeds

Feed

FeedStatus

Retrieves detailed information about a given feed-request

Feed

FeedCancel

Cancels a queued feed-request

Order

GetOrders

Retrieves a list of orders created or updated during a given time frame

Order

GetOrder

Retrieves an order's details by its id

Order

GetOrderItems

Returns an order's items

Order

SetStatusToCanceled

Set status of one or more order items to 'canceled'

Order

SetStatusToShipped

Set status of one or more order items to 'shipped'

Order

SetStatusToFailed Delivery

Set status of one or more order items to 'failed'

Order

SetStatusToDeliver

Set status of one or more order items to 'delivered'

Order

GetFailureReasons

Returns all of the failed reasons for unsuccessful setStatusToCanceled and SetStatusToFailedDelivery requests

Order

GetShipmentProviders

Returns a list of all active shipping providers

1.2. Feeds Every insert/update request is stored in a queue to be executed as a batch operation, called a Feed. Each feed is identified by a UUID (see section 1.3. - Data Types). This identifier is returned upon successful submission of the request. Sellers can ask for a list of feeds and errors by using the set of Feed actions. Feeds can have one of several statuses: Status

Meaning

Queued

The feed was successfully added to the queue and is waiting for processing

Processing

The feed is currently being processed by the server

Canceled

The feed was canceled by the Seller

Finished

The feed has finished processing

- Feeds with any status other than 'Queued' will be automatically removed from the system 30 days after their creation - Only Queued feeds can be canceled;

1.3. Data Types There are several consistent data types used throughout the API. Their description in this document is implicit, and validation rules should be implemented in a XSD file. Type

Description

Date

A date field in ISO8601 format

DateTime

A combined date and time field in ISO8601 format

UUID

Type 4 UUID codes

String

A sequence of characters in UTF-8 format

Integer

A natural (whole) number field, without decimal or thousands separators

Decimal

A non-negative numeral field, without thousands separator and optionally up to 2 decimal digits separated by a decimal point (eg. 233.55)

Boolean

A boolean string ('true'/'false') or numeric equivalent (1/0)

Url

A valid RFC1738 URL

List

A list containing single XML elements

Section

An XML tree element

Node

An object inside the tree structure1

Unsigned

A non-negative number

Array

An array either in JSON format, or as the return value of the PHP function 'serialize'

1

In 'Product > Import Products' it is possible to download the whole Category tree, that contains the Category Identifications to be used as Primary Category.

2. Executing Requests and Authentication All of the requests and the responses are written in XML format, using UTF-8 characters. The number of fields a Request has varies according to the action, and a Response has a predefined Head structure and a Body part (if available). The parameters required to execute the request (version, action name, etc) are provided as GET method (url) parameters.

2.1. Request Format The requests are done using normal HTTP. Request parameters must be specified as part of the URL. The additional parameters should be appended to the Request using POST method, in XML format. All data (including parameter names and values) must be UTF8-encoded. URL Request Parameters Parameter

Type

Mandator Description y

Version

Decimal

Yes

The version of the API being called, in format .. Currently it is 1.0

UserID

String

Yes

The merchant identification code

Action

String

Yes

The action to execute

Signature

String

Yes

Authentication signature using HMAC SHA256 function

DateTime

Yes

Time-stamp of the request, in UTC ISO8601 format. The API implements Timestamp verification. Old requests or those too far in the future are denied.

vary

No

Optional additional parameters for some actions, passed as =

Timestamp

[Parameters]

2.2. Signing the Request The Request Signature parameter is RFC2104-compliant HMAC-SHA256 hash of the request, using the merchant's API key. It is computed from the request string. One can find their API key under manage users:

2.2.1. Computing the Signature Parameter

The string to sign is the concatenated result of all request parameters, ordered by name, including optional parameters, and excluding the signature parameter. Names and values should be URL encoded according to RFC 3986 standard, concatenated with the character '='. Each parameter set(name=value) must be separated with the character '&'. Example (PHP code): // the API key for the user $api_key = 'MSZbCm8uZrcHbd@m&oKg'; $now = new DateTime(); $url = "https://sellercenter-api.linio.com.mx/?"; $parameters = array( 'UserID' => '[email protected]', 'Version' => '1.0', 'Action' => 'FeedList', 'Timestamp' => $now->format(DateTime::ISO8601), ); // Sort parameters by name ksort($parameters); $params = array(); foreach ($parameters as $name => $value) { $params[] = rawurlencode($name) . '=' . rawurlencode($value); } $strToSign = implode('&', $params); // Compute signature and add it to the parameters $parameters['Signature'] = rawurlencode(hash_hmac('sha256', $strToSign, $api_key, false));

2.3. Authenticationadmin Each seller has an associated private API token. The API itself doesn't implement session control. Instead, users are authenticated by computing the signature parameter based on the stored private token for the seller associated with that user. Example request : https://sellercenter-api.linio.com.mx/? Action=Price&Signature=2c93bd83586b212f9f29a3af4bc25f5ba4d0b754687b3082ed8 21be1d92b9930&Timestamp=2013-0827T15%3A56%3A11%[email protected]&Version=1.0

To complete the PHP code from part 2.2.1, here is code-sample of how to build a query string and then make the call:

// Build Query String $queryString = http_build_query($parameters, '', '&', PHP_QUERY_RFC3986); // Open Curl connection $ch = curl_init(); curl_setopt($ch, CURLOPT_URL, $url."?".$queryString); // Save response to the variable $data curl_setopt($ch, CURLOPT_FOLLOWLOCATION,1); curl_setopt($ch, CURLOPT_RETURNTRANSFER, TRUE); $data = curl_exec($ch); // Close Curl connection curl_close($ch);

2.4 API Call in Visual Basic In our examples we mostly use PHP as a language to call API functions. Here is an example for Visual Basic code. The same character encoding for the Signature is applied, with a non-standard function (URLEncode).

Imports System Public Module modmain Sub Main() ' add your data here: Dim userId As String = "" 'login name / your email Dim password As String = "" 'your API key/password Dim version As String = "1.0" Dim action As String = "ProductCreate" Dim url As String = "" 'e.g.: "https://sellercenter-api-linio-co.sellercenter.net/" Dim result As String ' this is where the magic happens: result = generateRequest(url, userId, password, version, action) Console.WriteLine (result) End Sub Function generateRequest(Url As String, user As String, key as String, version As String, action As String) As String Dim timeStamp as String = DateTime.UtcNow.ToString("yyyy-MM-ddTHH:mm:ss-0000") ' ATTENTION: parameters must be in alphabetical order Dim stringToHash As String = _ "Action=" + URLEncode(action) + _ "&Timestamp=" + URLEncode(timeStamp) + _ "&UserID=" + URLEncode(user) + _ "&Version=" + URLEncode(version) Dim hash As String = HashString(stringToHash, key) ' ATTENTION: parameters must be in alphabetical order Dim request As String = _ "Action=" + URLEncode(action) + _ "&Signature=" + URLEncode(hash) + _ "&Timestamp=" + URLEncode(timeStamp) + _ "&UserID=" + URLEncode(user) + _ "&Version=" + URLEncode(version)

return url + "?" + request End Function

' use this function instead of HttpServerUtility.UrlEncode() ' because we need uppercase letters Function URLEncode(EncodeStr As String) As String Dim i As Integer Dim erg As String erg = EncodeStr erg = Replace(erg, "%", Chr(1)) erg = Replace(erg, "+", Chr(2)) For i = 0 To 255 Select Case i ' *** Allowed 'regular' characters Case 37, 43, 45, 46, 48 To 57, 65 To 90, 95, 97 To 122, 126 Case 1 ' *** Replace original % erg = Replace(erg, Chr(i), "%25") Case 2 ' *** Replace original + erg = Replace(erg, Chr(i), "%2B") Case 32 erg = Replace(erg, Chr(i), "+") Case 3 To 15 erg = Replace(erg, Chr(i), "%0" & Hex(i)) Case Else erg = Replace(erg, Chr(i), "%" & Hex(i)) Next

End Select

return erg End Function

Function HashString(ByVal StringToHash As String, ByVal HachKey As String) As String Dim myEncoder As New System.Text.UTF8Encoding Dim Key() As Byte = myEncoder.GetBytes(HachKey) Dim Text() As Byte = myEncoder.GetBytes(StringToHash) Dim myHMACSHA256 As New System.Security.Cryptography.HMACSHA256(Key) Dim HashCode As Byte() = myHMACSHA256.ComputeHash(Text) Dim hash As String = Replace(BitConverter.ToString(HashCode), "-", "") Return hash.ToLower End Function End Module

2.5 API Call in Adobe ColdFusion An example of ColdFusion script for generate signature and send the API request to SellerCenter.







4105382173aaee4 12 #cfhttp.filecontent#

2.6 API Call in Java An example script written in Java for generating signature and sending the API request to SellerCenter. /* * Sample Interface for SellerCenter API */ package com.rocket.sellercenter; import import import import import import import import import import import

java.security.InvalidKeyException; java.security.NoSuchAlgorithmException; java.text.SimpleDateFormat; java.text.DateFormat; java.io.*; java.net.HttpURLConnection; java.net.URL; java.net.URLEncoder; java.util.*; javax.crypto.Mac; javax.crypto.spec.SecretKeySpec;

public class SellercenterAPI { private slash private private private

static final String ScApiHost = "http://sellercenter-api.local/"; // API Host // keep the trailing static final String HASH_ALGORITHM = "HmacSHA256"; static final String CHAR_UTF_8 = "UTF-8"; static final String CHAR_ASCII = "ASCII";

public static void main(String[] args) { Map params = new HashMap(); params.put("UserID", "[email protected]"); params.put("Timestamp", getCurrentTimestamp()); params.put("Version", "1.0"); params.put("Action", "ProductUpdate"); final String apiKey = "55f86f79f3b4388507aba8c21a7bfd0d25626551"; final String XML = "4105382173aaee412"; final String out = getSellercenterApiResponse(params, apiKey, XML); // provide XML as an empty string when not needed

}

System.out.println(out); // print out the XML response

/** * calculates the signature and sends the request * * @param params Map - request parameters * @param apiKey String - user's API Key * @param XML String - Request Body */ public static String getSellercenterApiResponse(Map params, String apiKey, String XML) { String queryString = ""; String Output = ""; HttpURLConnection connection = null; URL url = null; Map sortedParams = new TreeMap(params); queryString = toQueryString(sortedParams); final String signature = hmacDigest(queryString, apiKey, HASH_ALGORITHM); queryString = queryString.concat("&Signature=".concat(signature)); final String request = ScApiHost.concat("?".concat(queryString)); try { url = new URL(request);

connection = (HttpURLConnection) url.openConnection(); connection.setDoOutput(true); connection.setDoInput(true); connection.setInstanceFollowRedirects(false); connection.setRequestMethod("POST"); connection.setRequestProperty("Content-Type", "application/x-www-form-urlencoded"); connection.setRequestProperty("charset", CHAR_UTF_8); connection.setUseCaches(false); if (!XML.equals("")) { connection.setRequestProperty("Content-Length", "" + Integer.toString(XML.getBytes().length)); DataOutputStream wr = new DataOutputStream(connection.getOutputStream()); wr.writeBytes(XML); wr.flush(); wr.close(); } String line; BufferedReader reader = new BufferedReader(new InputStreamReader(connection.getInputStream()));

}

}

while ((line = reader.readLine()) != null) { Output += line + "\n"; } } catch (Exception e) { e.printStackTrace();

return Output;

/** * generates hash key * * @param msg * @param keyString * @param algo * @return string */ private static String hmacDigest(String msg, String keyString, String algo) { String digest = null; try { SecretKeySpec key = new SecretKeySpec((keyString).getBytes(CHAR_UTF_8), algo); Mac mac = Mac.getInstance(algo); mac.init(key); final byte[] bytes = mac.doFinal(msg.getBytes(CHAR_ASCII)); StringBuffer hash = new StringBuffer(); for (int i = 0; i < bytes.length; i++) { String hex = Integer.toHexString(0xFF & bytes[i]); if (hex.length() == 1) { hash.append('0'); } hash.append(hex); } digest = hash.toString(); } catch (UnsupportedEncodingException e) { e.printStackTrace(); } catch (InvalidKeyException e) { e.printStackTrace(); } catch (NoSuchAlgorithmException e) { e.printStackTrace(); } return digest; } /** * build querystring out of params map * * @param data map of params * @return string * @throws UnsupportedEncodingException */ private static String toQueryString(Map data) { String queryString = ""; try{ StringBuffer params = new StringBuffer(); for (Map.Entry pair : data.entrySet()) { params.append(URLEncoder.encode((String) pair.getKey(), CHAR_UTF_8) + "="); params.append(URLEncoder.encode((String) pair.getValue(), CHAR_UTF_8) + "&"); } if (params.length() > 0) { params.deleteCharAt(params.length() - 1); }

queryString = params.toString(); } catch(UnsupportedEncodingException e){ e.printStackTrace(); } }

return queryString;

/** * returns the current timestamp * @return current timestamp in ISO 8601 format */ private static String getCurrentTimestamp(){ final TimeZone tz = TimeZone.getTimeZone("UTC"); final DateFormat df = new SimpleDateFormat("yyyy-MM-dd'T'HH:mmZ"); df.setTimeZone(tz); final String nowAsISO = df.format(new Date()); return nowAsISO; } }

3. Request Format Some API actions require input data. These data variables must be written in a valid UTF-8 XML format, and must be submitted using POST method of HTTP. The expected format of the XML request varies according to the specified request. Regardless of the API action, the variables must be encapsulated inside a Request Section. Request example: SKU-AAAA 10.0 2013-08-23T16:04:43+0000 2013-08-24T16:04:43+0000 8.0 SKU-BBBB 32.5

In paragraph 2.1 the requested parameters in the query string (via GET) were discussed. The difference is that the XML should be always appended to the request via POST. Using PHP and cURL, assuming the XML is saved in the variable $xmlPayload, one should simply add: // Save response to the variable $data curl_setopt($ch, CURLOPT_FOLLOWLOCATION,1); curl_setopt($ch, CURLOPT_RETURNTRANSFER, TRUE); curl_setopt($ch, CURLOPT_POSTFIELDS, $xmlPayload); $data = curl_exec($ch);

4. Response Format The API generates 2 standard response types in XML format that may or may not contain variable Body data. The response type indicates the status of the operation (either Success or Error), and provides results and/or details related to the specified action.

4.1. ErrorResponse Format Every platform-related or user-related error triggers a return of an ErrorResponse. Each ErrorResponse has a mandatory Header section and an optional Body section, which may contain information, regarding of the error. ErrorResponse Header fields:

Name

Type

Mandatory

Description

RequestAction

String

Yes

The action that triggered the error

ErrorType

String

Yes

The error's origin (either Sender or Platform)

ErrorCode

Integer

Yes

An internal error code

ErrorMessage

String

Yes

Explanation message

Additionally, the Body section may contain additional information related to the errors (e.g. invalid field information, associated seller SKU). Error information is grouped in the ErrorDetail section. Body section may contain multiple ErrorDetail, one for each error. ErrorResponse may contain only ErrorDetails for the first 50 incorrect items. Example of ErrorResponse for price update, with a Body section: Price Sender 1000 Format Error Detected StandardPrice Field must contain a positive number with a dot as decimal separator and 2 decimals (e.g. 120.00) 10.0x Example Seller SKU

4.2. SuccessResponse Format Every successful call to an action will generate a SuccessResponse. If additional data is expected, it will be

encapsulated in the Body section. SuccessResponse Header fields:

Name

Type

RequestId

UUID

Yes

Identification for this request, or empty if not applicable

RequestAction

String

Yes

The request action called

ResponseType

String

Yes

The response type contained in the Body, or empty if none

DateTime

Yes

Time in which the request was sent, in ISO 8601 format

List

No

Additional requested parameters

Timestamp RequestParameter s

Mandatory

Description

The SuccessResponse may contain return data in the Body Section, depending on the invoked action. Example of SuccessResponse: 13e55362-3cc4-446b-b3db-c1df0900ae9e PriceFeed 2013-08-27T14:44:13+0000

5. Product and Feed API 5.1. Products and Images 5.1.1. GetProducts Action GetProducts returns a list of all products. The following optional parameters may be used to control which products are returned:

Name

Default

Description

CreatedAfter

Null

Select all products created after or at a specified time, in ISO 8601 date format

CreatedBefore

Null

Select all products created before or at a specified time, in ISO 8601 date format

Search

Null

Free text search. Searches in product's name and SKU

Filter

All

Return only entries which fit the status provided. Possible values are all, active, inactive, deleted, image-missing, pending, rejected, sold-out.

Limit

1000

Number of products to return. No more than 1000 products can be pulled per request.

Offset

0

Offset into the result set

The response type is Products, containing product resources, each of them is composed of the following fields: Name

Type

Description

SellerSku

String

Seller's unique identifier

ShopSku

String

Shop's unique identifier

Name

String

Product's name

Variation

String

Product's variation

Quantity

Integer

The available inventory

Price

Decimal

The product's regular price

SalePrice

Decimal

The product's special sale price

SaleStartDate

DateTime

Starting date for the special sale

SaleEndDate

DateTime

Ending date for the special sale

Status

Integer

Product's status: 'active', 'inactive' or 'deleted'

ProductId

String

EAN/UPC/ISBN of the product, if it exists

5.1.2. ProductCreate Action This action allows the creation of new products. The Product Create action expects Product sections with the following format: Name

Type

SellerSku

String

Yes

Seller's unique identifier

ParentSku

String

No

SellerSKU of a parent product – another product, which the current product will be associated with

Status

String

No

One of the following values: 'active', 'inactive' or 'deleted'. Default is 'active'

Name

String

Yes

Product's name, 2 to 255 characters

Variation

String

No

Identifier for the variation (e.g. “XXL”)

PrimaryCategory

Integer

Yes

Identification of the main category of the product

Categories2

String

No

A list of 1 to 3 unique categories identifications (separated with ',') to which the product belongs

BrowseNodes3

String

No

A list of 1 to 2 unique category identifications (separated with ',')

Description

String

Yes

A text of 6 to 25000 characters describing the product. HTML tags are allowed.

Brand

String

Yes

The product's brand

Price

Decimal

Yes

An optional number with the price of the product

SalePrice

Decimal

No4

A special sale price

SaleStartDate

DateTime

No4

Starting date for the sale

SaleEndDate

DateTime

No4

Ending date for the sale

TaxClass

String

Yes

Tax classification. Usually 'default'

ShipmentType

String

No

A string identifying shipping type, either 'crossdocking' or 'dropshipping'. Only the allowed shipping types for the seller will be accepted.

ProductId

String

No

EAN/UPC/ISBN of the product

Condition

String

No

Product's condition: 'new', 'used' or 'refurbished'

2 3 4

Mandatory

Description

Categories must be of the same top-category as primary category BrowseNodes are additional categories that are not necessarily related to the primary category In case SalePrice is specified - one of 'SaleStartDate' and 'SaleEndDate' must be specified too; and in case at least one of 'SaleStartDate', 'SaleEndDate' is specified – SalePrice must be specified too.

ProductData

Section

No

Additional product attributes, depends on the primary category.

Quantity

Integer

No

The available inventory

Request example: 4105382173aaee4 active Magic Product XXL 4 2,3,5 This description is magic ASM 1.00 32.5 2013-09-03T11:31:23+0000 2013-10-03T11:31:23+0000 default dropshipping xyzabc new 490 7 4 32 This is network 10

•

In Seller-Center, under 'Administration > Attribute Set Editor > API Examples', for each category family there are dynamically generated XML examples for the minimum required, and for the full API call.

•

In 'Product > Import Products' it is possible to download the whole Category tree, that contains the Category Identifications to be used as Primary Category.

Note: in ProductCreate, Tags without any value will be ignored.

5.1.3. ProductUpdate Action This action provides a way to update product information. The ProductUpdate Request expects Product section(s) with the same format as described in Section 5.3.1 for ProductCreate. All fields except the Seller SKU are optional. Example Request: 4105382173aaee4 12 4105382173aaee5 5 4105382173aaee6 disabled

Note: in ProductUpdate, tags without any value will delete the previous value.

5.1.4. ProductRemove Action This action removes one or more products. This action expects Product sections with the following format: Name

Type

SellerSku

String

Mandatory Yes

Description Seller's unique identifier

Example Request: 220823ff419c6ad 80c6f3211da3f2e 6f03b1f86579a7b 171165c5bd6df0f

5.1.5. Image Action This action provides URLs for the images of products. All existing images will be replaced. The first entry will be used as a default image. This action expects ProductImage sections with the following format: Name

Type

Mandatory

Description

SellerSku

String

Yes

Seller's unique identifier

Images

List

Yes

A list of Image sections

Image

URL

Yes

URL for a valid image (png or jpeg format)

Example Request: SKU_1 http://www.rocketinternet.de/sites/default/files/header_bg_imgs/map_home.jpg

5.2. Feeds See chapter 1.2. for more information about feeds.

5.2.1. FeedList Action The FeedList action returns a SuccessResponse with a list of all feeds created in the past 30 days in the Body section. The ResponseType is Feed. Transaction Section fields: Name Description Feed

The UUID of the feed

Status

Queued/Processing/Canceled/Finished

Action

The action that created the feed

CreationDate

Time in ISO 8601 format of the feed's creation

UpdatedDate

Time in ISO 8601 format of the feed's last update

Source

The feed's source (either „api“ or „csv“)

TotalRecords

Number of entries to be processed

ProcessedRecords

Number of entries already processed

FailedRecords

Number of entries that failed to be processed

FeedList response example: FeedList Feed 2013-10-28T16:33:55+0000 829a8d2a-d370-4fa6-8613-8554f43d5fed Processing ProductCreate 2013-10-23 15:43:26 api 9999 0 0

5.2.2. FeedOffsetList Action This action is similar to FeedList, but requests extra parameters. The ResponseType is Feed (see examples for FeedList). FeedOffsetList optional parameters: Name Type Description Offset

Integer

Index of the first entry to retrieve from the total list of feeds

PageSize

Integer

Number of entries to retrieve

Status

String

Filter only feeds with the specified status

5.2.3. FeedCount Action The FeedCount action returns a list of counters of the feeds. Only the last 30 days are considered (remember that feeds that are not queued are being deleted after 30 days from the creation date). The ResponseType is FeedCount. FeedCount fields: Name Description Total

Total number of submitted feeds on the last 30 days

Queued

Number of queued feeds

Processing

Number of processing feeds

Finished

Number of finished feeds

Canceled

Number of canceled feeds

FeedCount example response: FeedCount FeedCount 2013-10-28T16:47:55+0000 59 10 2 46 1

5.2.4. FeedCancel Action This action cancels submitted feeds with „Queued“ status. This action has no ResponseType. FeedCancel fields: Name

Description

FeedID

Identification of the feed to cancel

FeedCancel response example: FeedCancel 2013-08-28T09:08:52+0000 c685b76e-180d-484c-b0ef-7e9aee9e3f98

5.3 Feed Throttling For feed creating, see chapter 1.2. Each feed which is created may contain one or more products. It is more efficient to use one feed containing many product creations / updates, rather than one feed creation per product creation / update. Seller Center limits the number of feeds that can be created in a certain time-frame: normally, 1 feed is allowed to be created every 2 minutes. In addition, the maximum number of feeds that can be in the system is 50. Note: This limitation is applied for each seller separately. To visualize this behaviour, consider the Leaky Bucket metaphor. There is a bucket with a hole in the bottom, which leaks in a given rhythm. Once the bucket is filled, it's impossible to add more requests to it, and we have to wait for some of them to leak. In conclusion, the normal processing (or leaking) rate is 30/hour, but the container can hold more requests, so long as there are no more than 50 of them at a time in the system.

6. Sales Order API

6.1 Executing Requests and AuthenticationRequestID 6.1.1 Request Format The requests are done using regular HTTP requests. Request parameters must be specified on the URL (HTTP GET method).

6.1.2 URL Request Parameters Parameter

Type

Mandatory

Description

Version

Decimal

Yes

The version of the API being called, in format .. Currently it is 1.0

UserID

String

Yes

The merchant identification code

Action

String

Yes

The action to execute

Signature

String

Yes

Authentication signature using HMAC SHA256 function

DateTime

Yes

Time-stamp of the request, in UTC ISO8601 format. The API implements Timestamp verification. Old requests or those too far in the future are denied.

vary

No

Optional additional parameters for some actions, passed as =

Timestamp

[Parameters]

6.1.3 Signing the Request The Request Signature parameter is encoded RFC2104-compliant HMAC-SHA256, using the seller's private key. It is computed from the request string.

6.1.4 Computing the Signature Parameter PHP code example // the API Secret for the user $password = 'SecretPassword'; $now = new DateTime(); $url = "http://api.sellercenter/"; $parameters = array( 'UserID' => '[email protected]', 'Version' => '1.0', 'Action' => 'GetOrder', 'Timestamp' => $now->format(DateTime::ISO8601),

'OrderId' => '1', ); // sort parameters by name ksort($parameters); $strToSign = http_build_query($parameters, '', '&', PHP_QUERY_RFC3986); $signature = rawurlencode(hash_hmac('sha256', $strToSign, $password, false)); $parameters['Signature'] = $signature; After the generation of the Signature, it should be chained to the parameters array itself and then encoded again as query string for the CURL call:

// Build Query String $queryString = http_build_query($parameters, '', '&', PHP_QUERY_RFC3986); // Open Curl connection $ch = curl_init(); curl_setopt($ch, CURLOPT_URL, $url."?".$queryString); // If URL is protected by .htaccess, use these lines to grant access // curl_setopt($ch, CURLOPT_HTTPAUTH, CURLAUTH_BASIC); // curl_setopt($ch, CURLOPT_USERPWD, "youruser:yourpassword"); // Save response to the variable $data curl_setopt($ch, CURLOPT_FOLLOWLOCATION,1); curl_setopt($ch, CURLOPT_RETURNTRANSFER, TRUE); $data = curl_exec($ch); // Close Curl connection curl_close($ch);

6.1.5 Authentication Each seller has an associated private API token. The API itself implements no session control – users are authenticated by computing the signature parameter using the stored private token for the given seller.

6.2 Response Format The API generates 2 standard response types in XML format, that may or may not contain variable Body data. The response type indicates the status of the operation (either Success or Error).

6.2.1 ErrorResponseFormat Name RequestAction ErrorType

Type

Mandatory

String

Yes

String

Yes

Desription The action that triggered the error The origin of the error (either Sender or Platform)

Name ErrorCode ErrorMessage

Type

Mandatory

String

Yes

String

Yes

Desription Internal error code The error message

6.2.2 SuccessResponseFormat Name

Type

Mandatory

RequestId

UUID

Yes

RequestAction

String

Yes

ResponseType

String

Yes

The response type contained in Body, or empty if none

Date

Yes

Date in ISO 8601 format, specifying the time the response was created

List

No

Timestamp RequestParameters

Description The request identification The request action called

Optional additional requested parameters

6.3 Order Fetch API 6.3.1 GetOrders The GetOrders action returns a list of orders created or updated during a time period.

Request parameters

Name CreatedAfter CreatedBefore UpdatedAfter UpdatedBefore

Type

Mandatory

DateTime

No1

DateTime

No

DateTime

No1

DateTime

No

Integer

No

Integer

No

Limit Offset

Description ISO 8601 standard date. Orders returned were created after or at the time specified ISO 8601 standard date. Orders returned were created before or at the time specified ISO 8601 standard date. Orders returned were updated after or at the time specified ISO 8601 standard date. Orders returned were updated before or at the time specified Number of orders to retrieve. Allowed value is 1 to 100, default is 100 Amount of orders to skip

Request example http://api.sellercenter/ ?Action=GetOrders &CreatedAfter=2010-10-04T15%3A56%3A11%2B0200 &CreatedBefore=2013-10-04T15%3A56%3A11%2B0200 &Limit=100 &Offset=0 &Signature=2c93bd83586b212f9f29a3af4bc25f5ba4d0b754687b3082ed821be1d92b993 0 &Timestamp=2013-08-27T15%3A56%3A11%2B0200 [email protected] &Version=1.0 Response Elements

Name OrderId CustomerFirstName CustomerLastName OrderNumber PaymentMethod Remarks 1

Type

Mandatory

Unsigned

Yes

String

Yes

Customer's first name

String

Yes

Customer's last name

Unsigned

Yes

Order number in Seller Center

String

Yes

The payment method of the order

String

No

A remark for the order

One of “createdAfter” and “UpdatedAfter” is mandatory

Description Order identification in Seller Center

Name DeliveryInfo GiftOption GiftMessage CreatedAt UpdatedAt

AddressBilling

AddressShipping

NationalRegistrationNumber

Type

Mandatory

String

No

Boolean

No

1 if item is a gift, 0 if not

String

No

Greeting, in case the order is a gift

DateTime

Yes

Date of order placement

DateTime

Yes

Date of last change

Node

Yes

Node

Yes

String

No

Description

• • • • • • • • •

FirstName LastName Phone Phone2 Address1 Address2 City PostCode Country

• FirstName • LastName • Phone • Phone2 • Address1 • Address2 • City • PostCode • Country Registration number, which is required in some countries

Response Example GetOrders Orders 2013-08-27T14:44:13+0000 1 John Doe 3000

CashOnDelivery 0 2013-09-02 02:28:17 2013-09-02 02:28:17 John Doe 0123456789 testtestcarmen testtestcarmen Kuala Lumpur 12345 Germany John Doe 0123456789 testtestcarmen testtestcarmen Kuala Lumpur 11111 Malaysia

6.3.2 GetOrder Description The GetOrder action returns an order using Seller-Center's field OrderId. Request Paramters

Name OrderId

Type Unsigned

Mandatory Yes

Description Order identification in Seller Center

Example request http://api.sellercenter/ ?Action=getOrder &OrderId=1 &Signature=2c93bd83586b212f9f29a3af4bc25f5ba4d0b754687b3082ed821be1d92b993

0 &Timestamp=2013-08-27T15%3A56%3A11%2B0200 &UserID=admin &Version=1.0 Response Elements Same as GetOrders response (see above).

6.3.3 GetOrderItems Description The GetOrderItems action returns order items based on the OrderId. Request Paramters Similar to GetOrder (see above). Example request http://api.sellercenter/ ?Action=getOrderItems &OrderI=1 &Signature=2c93bd83586b212f9f29a3af4bc25f5ba4d0b754687b3082ed821be1d92b993 0 &Timestamp=2013-08-27T15%3A56%3A11%2B0200 &UserID=admin &Version=1.0 Response Elements

Name OrderItemId OrderId Name Sku ShopSku

ShippingType

ItemPrice

Type

Mandatory

Description

unsigned

yes

Sales order items id

unsigned

yes

Order id

string

yes

Name of order item

string

yes

Seller SKU

string

yes

string

yes

Decimal

Yes

The SKU for the product as it appears in the shop database Available types: • dropshipping • crossdocking Unit Price

Name PaidPrice TaxAmount ShippingAmount VoucherAmount

Status

ShipmentProvider

Reason

ReasonDetail

PurchaseOrderId PurchaseOrderNumber PackageId CreatedAt UpdatedAt

Type

Mandatory

Description

Decimal

Yes

Paid Price

Decimal

Yes

Tax Amount

Decimal

Yes

Shipping Fee

Decimal

Yes

Amount of the voucher used

String

Yes

String

No

String

No

String

No

Unsigned

No

String

No

Unsigned

No

DateTime

Yes

DateTime

Yes

Status of the order item. Available statuses: “pending”, “cancelled”, “shipped”, “failed”, “delivered”, “returned” Shipment provider. Available for shipped items with shipping type “drop-shipping”. The cancel/failed reason for canceled/failed delivered/returned items The description of the reason for canceled/failed delivered/returned items PurchaseOrderId is available for shipped items PurchaseOrderNumber is available for shipped items PackageId is available for shipped items The date when the order item was created The date when the order item was last updated

Response Example GetOrderItems OrderItems 2013-08-27T14:44:13+0000

1 1 Checkmate Contrasted Two Pocket Short Sleeve Check Shirt CH650FA84EFZANMY-113840 dropshipping 100.00 100.00 0.00 12.50 0.00 shipped Aramax 3000001 MPDSD1405600108 12345 2013-09-02 02:28:17 2013-09-02 02:28:17

6.4 Order Processing API 6.4.1 SetStatusToCanceled Description The SetStatusToCanceled action informs SellerCenter that an item with Id OrderItemId has been canceled. Request Parameters

Name OrderItemId

Type

Mandatory

Unsigned

Yes

Reason

String

Yes

ReasonDetail

String

No

Example Request http://api.sellercenter/ ?Action=SetStatusToCanceled

Description Identification of the order in Seller Center Cancellation reason, must be a valid reason. Valid reasons can be fetched via GetFailureReasons action; a valid reason should be Type 'canceled' and one of the string Name tag (e.g. 'Wrong Address') Cancellation reason detail

&OrderItemId=1 &Reason=Changed%20mind &ReasonDetail=Reason%20Detail &Signature=2c93bd83586b212f9f29a3af4bc25f5ba4d0b754687b3082ed821be1d92b993 0 &Timestamp=2013-08-27T15%3A56%3A11%2B0200 &UserID=admin &Version=1.0 Success Response Example SetStatusToCanceled 2013-08-27T14:44:13+0000 Error Response Example SetStatusToCanceled Sender 1000 Invalid cancelation reason

6.4.2 SetStatusToReadyToShip Description The SetStatusToReadyToShip action informs Seller Center that the item is ready to ship. Request Parameters

Name OrderItemIds DeliveryType

Type

Mandatory

Description

Array

Yes

List of Order item identifications

String

Yes

One of the following: dropship - The seller will send out the package on his own pickup - Shop should pick up the item from the

Name

Type

Mandatory

Description seller (cross-docking) send_to_warehouse - The seller will send the item to the warehouse (cross-docking)

ShippingProvider

String

TrackingNumber

String

Only needed for drop-shipping. Must be a valid Yes for shipping provider (fetched via delivery type GetShipmentProviders action. A valid shipment is dropship one of the string Name tag e.g. 'DHL') Yes for Shipment tracking id of the package only for delivery type dropshipping dropship

Example Request http://api.sellercenter/ ?Action=SetStatusToReadyToShip &OrderItemIds=[1] &DeliveryType=dropship &ShippingProvider=Aramax &TrackingNumber=123456789 &Signature=2c93bd83586b212f9f29a3af4bc25f5ba4d0b754687b3082ed821be1d92b993 0 &Timestamp=2013-08-27T15%3A56%3A11%2B0200 &UserID=admin &Version=1.0 Response Elements

Name

Type

Mandatory

PurchaseOrderId

Unsigned

Yes

PurchaseOrderNumber

String

Yes

Description SellerCenter identification Order number in SellerCenter

Response Example SetStatusToReadyToShip OrderItems 2013-08-27T14:44:13+0000

123456 ABC-123456

6.4.3 SetStatusToShipped Description The SetStatusToShipped action informs Seller Center that an item with id OrderItemId has been shipped. Request Parameters

Name OrderItemId

Type Unsigned

Mandatory Yes

Description Order Item identification

Example request http://api.sellercenter/ ?Action=SetStatusToShipped &OrderItemId=1 &Signature=2c93bd83586b212f9f29a3af4bc25f5ba4d0b754687b3082ed821be1d92b993 0 &Timestamp=2013-08-27T15%3A56%3A11%2B0200 &UserID=admin &Version=1.0 Response Example SetStatusToShipped 2013-08-27T14:44:13+0000

6.4.4 SetStatusToFailedDelivery Description The SetStatusToFailedDelivery action informs Seller Center that an item with identification OrderItemID has failed. Request Parameters

Name OrderItemId

Type

Mandatory

Unsigned

Yes

Reason

String

Yes

ReasonDetail

String

No

Description Order Item identification Cancellation reason name, must be a valid reason. (Valid reasons can be fetched via GetFailureReasons action. A valid reason should be Type 'failed' and one of the string Name tag e.g. 'Wrong Address') Failed reason detail

Example Request http://api.sellercenter/ ?Action=SetStatusToFailedDelivery &OrderItemId=1 &Reason=Reason &ReasonDetail=Reason%20Detail &Signature=2c93bd83586b212f9f29a3af4bc25f5ba4d0b754687b3082ed821be1d92b993 0 &Timestamp=2013-08-27T15%3A56%3A11%2B0200 &UserID=admin &Version=1.0 Success Response Example SetStatusToFailedDelivery 2013-08-27T14:44:13+0000 Error Response Example SetStatusToFailedDelivery Sender 1000 Invalid reason Reason Invalid reason strange reason

6.4.5 SetStatusToDelivered Description The SetStatusToDelivered action informs Seller Center that an item with identification OrderItemId has been delivered. Request Parameters

Name OrderItemId

Type Unsigned

Mandatory Yes

Description Order Item identification

Example request http://api.sellercenter/ ?Action=SetStatusToDelivered &OrderItemId=1 &Signature=2c93bd83586b212f9f29a3af4bc25f5ba4d0b754687b3082ed821be1d92b993 0 &Timestamp=2013-08-27T15%3A56%3A11%2B0200 &UserID=admin &Version=1.0 Response Example SetStatusToDelivered 2013-08-27T14:44:13+0000

6.5. Failed Reason API 6.5.1 GetFailureReasons Description The GetFailureReasons action returns reasons for SetToCancelled and SetToFailedDelivery calls. Request Parameters No parameters. Example request

http://api.sellercenter/ ?Action=GetFailureReasons &Signature=2c93bd83586b212f9f29a3af4bc25f5ba4d0b754687b3082ed821be1d92b993 0 &Timestamp=2013-08-27T15%3A56%3A11%2B0200 [email protected] &Version=1.0 Response Elements

Name Type Type

Mandatory

String

Yes

Description Type of failed reason. Possible values are: "canceled", "failed", "returned" Name of the reason. Should be used in

Name

String

Yes

SetStatusToCanceled and SetStatusToFailedDelivery calls

Response Example GetFailureReasons Reasons 2013-08-27T14:44:13+0000 canceled Sourcing team couldn't find items canceled Wrong address

6.6 Shipment Provider API 6.6.1 GetShipmentProviders Description The GetShipmentProviders action returns all active shipping providers Request Parameters No specific parameters.

Example request http://api.sellercenter/ ?Action=GetShipmentProviders &Signature=2c93bd83586b212f9f29a3af4bc25f5ba4d0b754687b3082ed821be1d92b993 0 &Timestamp=2013-08-27T15%3A56%3A11%2B0200 [email protected] &Version=1.0 Response Elements

Name Name

Type

Mandatory

String

Yes

Description Name of shipping provider, the name should be used in SetStatusToShipped call

Response Example GetShipmentProviders ShipmentProvider 2013-08-27T14:44:13+0000 GDEX

7. API Error Codes 7.1 Global Errors Error Code

Error Message

1

E001: Parameter {field} is mandatory

2

E002: Invalid Version

3

E003: Timestamp has expired

4

E004: Invalid Timestamp format

5

E005: Invalid Request Format

6

E006: Unexpected internal error

7

E007: Login failed. Signature mismatching

8

E008: Invalid Action

9

E009: Access Denied

10

E010: Insecure Channel

11

E011: Request too Big

429

E429:Too many requests

1000

Internal Application Error

7.2 Product API GetProducts Error Code

Message

17

E017: "%s" Invalid Date Format

19

E019: "%s" Invalid Limit

14

E014: "%s" Invalid Offset

36

E036: Invalid status filter

ProductCreate Error Code

Message

1000

Could not save product: %s

1000

Format Error Detected

ProductUpdate Error Code

Message

1000

Could not save product: %s

1000

Format Error Detected

ProductRemove Error Code 1000

Message

Format Error Detected

Image Error Code 1000

Message

Format Error Detected

7.3 Feed API FeedList: No specific errors FeedOffsetList Error Code

Message

13

E013: Invalid Feed Status

14

E014: Invalid Feed Status

15

E015: Invalid PageSize

FeedCount No specific errors

FeedCount Error Code 12

Message

E012: Invalid Feed ID

7.4 Sales Order API GetOrders Error Code

Message

14

E014: "%s" Invalid Offset

17

E017: "%s" Invalid Date Format

18

E018: Either CreatedAfter or UpdatedAfter is mandatory

19

E019: "%s" Invalid Limit

GetOrder Error Code 16

Message

E016: "%s" Invalid Order ID

GetOrderItems Error Code 16

Message

E016: "%s" Invalid Order ID

SetStatusToCanceled Error Code

Message

20

E020: "%s" Invalid Order Item ID

21

E021: OMS Api Error Occurred

22

EE022: "%s" Invalid Reason

28

E028: It is not possible to set the order to the status "%s"

SetStatusToReadyToShip Error Code

Message

20

E020: "%s" Invalid Order Item ID

21

E021: OMS Api Error Occurred

23

E023: "%s" Invalid Order Item IDs

24

E024: "%s" Invalid Delivery Type

25

E025: "%s" Invalid Shipping Provider

26

E026: "%s" Invalid Tracking Number

29

E029: Order items must be from the same order

31

E031: Tracking ID incorrect. Example tracking ID: "%s"

SetStatusToShipped Error Code

Message

20

E020: "%s" Invalid Order Item ID

21

E021: OMS Api Error Occurred

28

E028: It is not possible to set the order to the status "%s"

SetStatusToFailedDelivery Error Code

Message

20

E020: "%s" Invalid Order Item ID

21

E021: OMS Api Error Occurred

22

EE022: "%s" Invalid Reason

28

E028: It is not possible to set the order to the status "%s"

SetStatusToDelivered Error Code

Message

20

E020: "%s" Invalid Order Item ID

21

E021: OMS Api Error Occurred

28

E028: It is not possible to set the order to the status "%s"

GetDocument Error Code

Message

20

E020: "%s" Invalid Order Item ID

21

E021: OMS Api Error Occurred

32

E032: Document type "%s" is not valid

33

E033: InvoiceNumber is mandatory for Invoices

34

E034: Order Item must be packed. Please call setStatusToReadyToShip before

35

E035: "%s" was not found

GetFailureReasons No specific errors GetShipmentProviders No specific errors