Hi developers!

Welcome to the Brandsdistribution integration APIs

We offer a range of APIs to suit every type of business.


Disclaimer:
Information disclosed herein should be considered proprietary and confidential. The document is property of IDT S.p.A. and may not be disclosed, distributed, or reproduced without the express written permission of IDT S.p.A.

Brandsdistribution Integration APIs

The Brandsdistribution platform can be integrated to any ecommerce platform via RESTful Web Services. Web Services are available for authenticated Dropshipper users only.

Last Update:21/03/2019

REQUIREMENTS:

Getting started on the sandbox

  1. Register at https://idt2015.rewix.zero11.net with a valid e-mail address
  2. Contact dropshipment@brandsdistribution.com to receive your API-key and activate your dropshipping test-account.
  3. Manually download an extract of our catalogue at https://idt2015.rewix.zero11.net/en/tools/export to get familiar with our database structure.
  4. Read this documentation thoroughly before starting the development of the integration.

The sandbox platform is provided to developers for testing purpose of API implementation without disrupting activities on the live platform. The Sandbox platform may be temporary unavailable due to updates of the platform (please wait at least 30 minutes before contacting the support staff). may be temporary unavailable due to updates of the platform (please wait at least 30 minutes before contacting the support staff). The Sandbox platform is updated to last software improvements and may include some API changes in development which are not available on the main platform. Most images are not available in Sandbox platform. We may disable any account on the Sandbox Platform without any notice. While testing, connect your services to https://idt2015.rewix.zero11.net instead of https://www.brandsdistribution.com using your sandbox credentials.

SETTING OF REQUESTS:

Http Headers

API request and response use, in most cases, the XML format. So the followed header must be set in the Http Request:

Header Value Note
Content-Type application/xml In every POST requests
Accept application/xml In GET/POST request receiving XML response body
Authorization “Basic base64 user:password” In every request

Authorization

Use your API-key instead of your username (when you're ready to go public you'll find it on the "My Subscriptions" section on your profile at www.brandsdistribution.com, next to the word "Roles". ) . Use the same password you selected when you first registered. If you change it on Brandsdistribution.com you'll need to update it on your integration. The API platform uses the Basic HTTP authentication RFC 2617 (https://tools.ietf.org/html/rfc2617), so you must add the Authorization header field in every http API call. The Authorization field is constructed as follows:

For example, if Aladdin is the api key and OpenSesame is the password, then the field's value is the base64-encoding of Aladdin:OpenSesame,
that is: QWxhZGRpbjpPcGVuU2VzYW1l. Then the Authorization header will appear as:

Authorization: Basic QWxhZGRpbjpPcGVuU2VzYW1l

Adding the header field depends on the language you use for implementation. This is an exemple in PHP:

$header = "Authorization: Basic " . base64_encode($username . ':' . $password);

Http Return Status Codes

API services always returns an http status code to be tested by the caller. The most common status codes are:

Code Meaning Action
200 OK You may extract data in the response body, if expected it
401 Unauthorized You missed the Authorization header or your credentials are invalid
404 Not found An item you pass in the request data does not exist in the database (i.e. the order_id, stock_id, etc…)
406 Not acceptable You specified an invalid Accept http header, since its value does not match with the response body format (i.e. you specified “application/xml” while response return a plain/text format)
500 Internal server error An internal error arose. Contact you support center

It is possible to download our catalogue in multiple languages. The Brandsdistribution catalogue contains around 5.000 single products with its different variations so depending on your hosting downloading time can vary.

API interface

The API services allow the user clients to download all products present on our database and manage orders. Please note that our products are stored as products including the colors (parent) and our models refer to size variables. Prices, descriptions and tags are stored in the product while quantities are stored in the models.

Services are:

Name (mnemonic) Meaning
Products Gets the products information from catalogue. It contains IDs, descriptions, availability, etc. Files are updated every 15 minutes.
Incremental Updates Gets information on products with stock quantities and prices variation. Files are updated every 4 minutes.
Reserve Adds or remove items quantities from the growing order
ReservationStatus Gets the content of the growing order. It lists all items in the order with their locked and available quantities
SendOrder Books and close an order responding with an order ID. Dispatch information is taken from user profile information.
SingleRecipientOrder Creates a new booked order from the growing order. You can create an order for a subset of the items in the growing order. Dispatch information is requested on the body as to be used for dropshipping orders for third part customers.
OrderStatusOrderID Gets information on status of the order passing Brandsdistributions Order ID.
OrderStatus by key Gets information on status of the order passing Users Order ID (key).

ORDER MANAGEMENT WORKFLOW

How to correctly use APIs:

  1. DOWNLOAD CATALOGUE: The dropshippers platform periodically imports the products with “Products” API. If using xml the platform can call the Incremental Updates to get only products that have changed in quantity or prices since main import.
  2. PLACE AN ORDER: When order is made on the dropshippers platform the "Reserve" API can be requested for checking on real-time availability of the ordered product before proceeding with the payment. The same is used also to remove items for abandoned, failed or modified carts. Removing items from the growing order created with the “Reserve” API is mandatory and these orders will be automatically emptied daily. When the dropshipper’s customer successfully concludes the order, the request “SingleRecipientOrder” API should be posted to create the order on Brandsdistribution.com with the recipients shipping information deleting items from the Reserved order. The order will appear in the Brandsdistribution platform under status Booked unless the dropshipper's given it's consense to pay order by Paypal Vault or have a credit that excede the order total . In that case, orders will be automatically confirmed and will be sent to the customer within the day. Please note that the Brandsdistribution staff can manually delete items in the orders if dropshipment users don't follow these instructions. To reserve products while waiting for payment you must use the Reserve API.
  3. TRACK AN ORDER: As soon as the order is placed dropshippers can get information about it status's and tracking code. The last order status is Dispatched.

Please note that the Brandsdistribution staff can manually delete items in the orders if dropshipment users don't follow these instructions. To reserve products while waiting for payment you must use the Reserve API

Products

Allows to get the products and items informations from the catalogue. Catalogue is updated in the platform every 15 minutes, so at least 20 minutes polling is recommended.

Products can be filtered by brands, category, gender, season. Even if you can download catalog in XML, CSV and XLS format, we recommend, for the API use, to use the XML format.

URL Method headers
/restful/export/api/products.xml GET Accept: application/xml
/restful/export/api/products.xls GET
/restful/export/api/products.csv GET

The XML format is recommended for online purposes. However, XLS and CSV formats are available. N.B. In these formats, applications must access data by column name in the header row (row 1) and not position, since the order and the number of columns are not fixed and may vary.

Query parameters

Query parameters must be added to the url:

Name Description Values Mandatory
acceptedlocales Locale code for the language(s). Comma separated values it_IT, en_US, ecc… Y
output-filetype Format for the output data. Fixed to “xml” xml Y
since The timestamp of the last update ISO8601 date format N
tag_1 Brand name (only one value accepted) Any brand name N
tag_4 Category (only one value accepted) “clothing”, “accessories”, “bags”, “cosmetics”, “underwear”, “shoes” N
tag_26 Gender (only one value accepted) “kids”, “women”, “unisex”, “men” N
tag_11 Season (only one value accepted) “fw” (fall/winter), “ss” (spring/summer), “all-year” N

Response Body

The output xml contains the item list for the request. Items contains all informations about the product, such as the codes, the pictures links, the availabilities, the models (size, color, price) and so on.

Example (XML format):
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<page totalPages="1" totalNumberOfElements="345" pageSize="345" lastUpdate="""2017-10- 31T14:05:12.322+01:00""" currentPage="1">
	<query/>
	<items>
		<item xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="product">
			<availability>1</availability>
			<bestTaxable>12.0</bestTaxable>
			<brand>BRAND NAME</brand>
			<code>GD65_CELESTE</code>
			<country_selling_restrictions>
				<country>IT</country>
				[...]
			</country_selling_restrictions>
			<currency>EUR</currency>
			<descriptions>
				<description>
					<description>
						PRODUCT DESCRIPTION I18N
					</description>
					<localecode>en_US</localecode>
				</description>
				<description> ... </description>
				...
			</descriptions>
			<id>31741</id>
			<pictures>
				<image>
					<id>111695</id>	
				<url>/prod/image_1412490303.jpg</url>
				</image>
				<image> ... </image>
				...
			</pictures>
			<intra>42022100</intra>
			<models>
				<model>
					<availability>1</availability>
					<barcode>00000000</barcode>
					<code>GD065_CELESTE</code>
					<color>#000000</color>
					<id>100617</id>
                    <lastUpdate>2017-10-31T14:24:55.048+01:00</lastUpdate>
					<model>MODEL NAME</model>
					<size>SIZE</size>
					<streetPrice>75.0</streetPrice>
					<taxable>12.0</taxable>
				</model>
				<model>...</model>
					...
			</models>
			<name>Borse</name>
			<online>true</online>
			<streetPrice>75.0</streetPrice>
			<tags>
				<tag>
					<<hidden>false</hidden>
					<id>1</id>
					<name>brand</name>
					<priority>0</priority>
					<translations>
						<translation>
						<description>Firme</description>
						<localecode>it_IT</localecode>
						</translation>
					</translations>
					<value>
						<translations>
							<translation>
						<description>Borse</description>
						<localecode>it_IT</localecode>
							</translation>
						</translation>
						<value>Ana Lublin</value>
					</value>
				</tag>
				<tag>...</tag>
					...
			</tags>
			<taxable>12.0</taxable>
			<weight>4.0</weight>
		</item>
		<item xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="product">...</item>
			...
	</items>
</page>

Tags description

This is a description of the main tags in the returned XML:

“page”

totalPages Deprecated. Always 1
totalNumberOfElements The number of products available
pageSize Deprecated. Same value of totalNumberOfElements
currentPage Deprecated. Always 1

“item”

availability the number of available products with its variables
brand the product brand; also available as product tag
code the product code (unique string code)
country_selling_restrictions a list of the country where product can't be sold
currency the currency used to show prices
descriptions a list of the description with i18n; for each description the locale code is also available
id the product id (unique numeric id of 5 numbers)
pictures a list of the picture available for the product's models; for each picture its id, name and path are also available
intra the intra code of the product
models the list of all the models
name the product name
tags a list of the tag assigned to the product
taxable the product taxable
streetPrice the product retail price tax included*
suggestedPrice the products suggested retail price tax included (Available since early january 2015 may not be available on all products)*
weight the product weight for our carriers

*Suggested retail prices and prices regard the european market only and are to be read in EURO.

“model”

availability the number of available products
barcode the model barcode
code the model code
color the model color (may contain not accurate data for some product)
Id the model id (unique numeric id of 6 numbers)
model the model name
size the model size


Example (CSV format)
<data contentType="text/csv" contentLength="4259">
<![CDATA[record_type,product_id,brand,name,code,product_quantity,street_price,suggested_price,price_novat,plain_description,weight,picture 1,picture 2,picture 3,Firme,heel,Categorie,Sottocategorie,altro,season,color,partner,service,Warehouse2,Sunglasses,Watches,bicolors,Genere,Print,productname,model_id,barcode,model_size,model_quantity
PRODUCT,12345,BRAND NAME,PRODUCT NAME,PRODUCT CODE,1,119.00,39.90,19.90,PRODUCT DESCRIPTION,1.00,https://www.brandsdistribution.com/prod/stock_product_image_12345_2395857.jpg,https://www.brandsdistribution.com/prod/stock_product_image_12345_2395858.jpg," ",FIRME NAME," ",Sunglasses," ",Autumn/Winter,Pink," "," "," "," "," ","rosybrown,silver",Woman," "," "," "," "," "," "
MODEL,12345," "," "," "," "," "," "," "," "," "," "," "," "," "," "," "," "," "," "," "," "," "," "," "," "," "," "," "," ",239768,762753167262,NOSIZE,1
]]></data>

Incremental updates (XML format)

Once you download the whole catalog, you can ask for updates only. The “since” query parameter is used to ask for quantity modifications after a given timestamp. The last update timestamp is retrieved from the “lastUpdate” attribute of the XML “page” tag.

Consider that:

Example

If the last XML response contains:

<page totalPages="1" totalNumberOfElements="345" pageSize="345" lastUpdate="2017-10- 31T14:05:12.322+01:00" currentPage="1">

To check for updates use the service in this way:

/restful/export/api/products.xml?acceptedlocales=en_US&output-filetype=xml&since=2017-10- 31T14:05:12.322+01:00

This ensure that you receive all quantity and pricing modifications from the last update.

Incremental updates (CSV and XLS formats)

In CSV and XLS formats the “lastUpdate” value is contained in the “X-LastUpdate” Http Header field of the Http Response with status 200 (OK).

Reserve

This method allows to reserve a given quantity of a specific model. You can increment or decrement a quantity of a reserved model. Furthermore, you may also add a new model to your "growing order". If a model is not in the "reservation"growing order", the method will automatically add it.

URL Method headers
/restful/ghost/orders/sold POST Content-Type: application/xml
Accept: application/xml

Request Body

The request body contains a list of the operations necessary to update the quantity of some products in the order.

There are three kind of operations:

Lock and unlock change quantities relatively to a previous quantity, set changes quantities regardless of the previous values.

These three kinds of operations can be combined in any way: you can use just one of these or all of them. Each operation contains a list of the model affected by it. Each model has two attributes:

Example:
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<root>
<operation type="lock">
	<model stock_id="3" quantity="3"/>
	<model stock_id="5" quantity="10"/>
</operation>
<operation type="unlock">
	<model stock_id="69" quantity="5"/>
	<model stock_id="79" quantity="8"/>
</operation>
<operation type="set">
	<model stock_id="55" quantity="10"/>
	<model stock_id="29" quantity="15"/>
</operation>
</root>

Response Body

The response body contains a list of the model in the order. Each model has three attributes:

Example:
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<root order_id="0">
	<model stock_id="3" locked="11" available="5" />
	<model stock_id="5" locked="33" available="2" />
	<model stock_id="29" locked="5" available="1" />
	<model stock_id="55" locked="2" available="11" />
	<model stock_id="120" locked="1" available="120" />
	<model stock_id="133" locked="9" available="0" />
</root>
Notes

The maximum bookable quantity of a model depends on the available quantity. You can't exceed this quantity with a lock or set operation. If the request body contains an invalid model stock_id, this will not affect the other operation. For invalid stock_id of a model you will receive error 412 Precondition Failed

ReservationStatus

With this method you can get the amout of items reserved and their available quantity in stock.

URL Method Headers
/restful/ghost/orders/dropshipping/locked/ GET Content-Type: application/xml
Accept: application/xml

Response Body

The response body contains a list of the model in the order. Each model has three attributes:

Example:
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<root order_id="0">
	<model stock_id="3" locked="11" available="5" />
	<model stock_id="5" locked="33" available="2" />
	<model stock_id="29" locked="5" available="1" />
	<model stock_id="55" locked="2" available="11" />
	<model stock_id="120" locked="1" available="120" />
	<model stock_id="133" locked="9" available="0" />
</root>

SendOrder

This method allows to book and close an order with the desired products.
It creates a new order in Booked status, acking you the numerical id of the order created. The products, if previously added to the reservation, will be automatically removed from reservation (created with Reserve) and added to this one.

URL Method Headers
/restful/ghost/supplierorder/acquire/ POST Content-Type: application/xml

Request Body

The request body contains a list of the wished products that will join the current growing order. Each product has two attributes:

• stock_id - the numerical id of the model of the product (model stock_id)
• quantity - the desired quantity in the order

The quantity can be less, equal or greater than the quantities in the growing order:

• less: the remaining quantities are kept in the growing order
• equal: stock is removed from the "growing order"
• greater: if there are stocks available, they are added to the order, otherwise a “not found” error is returned

Example

    <?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<supplierorder>
	<products>
		<product stock_id="3" quantity="11" />
		<product stock_id="5" quantity="30" />
		<product stock_id="29" quantity="6" />
	</products>
</supplierorder>

Response Body

The response body contains a number which identifies the order_id of the created order.

Notes

• You can only add available quantity to your order. If you request for more than available, only the available quantity will be added and no error or message will be returned. Make sure to have reserved them (Reserve) before calling this API.
• Order creation will be aborted if requesting not existing stock_id. Error code 500 (Internal Server Error) will be returned. Other required models may be added to your reservation. Always add all required quantities to your reservation before trying to use this API so you don't get any error caused by missing items.
• The platform does not check that the request matches the final response body.
• Order creation will be aborted if the request body contains errors. Http status code 429 and error message will be returned.

SingleRecipientOrder

Creates an order with the given items and quantities with the user’s customers shipping information. Status of the order will be booked until payment unless dropshipper has a credit that excede the total of the order or has authorised an automatic payment method.

URL Method Headers
/restful/ghost/orders/0/dropshipping POST Content-Type: application/xml
Accept: application/xml

Request Body

The request body contains the order items and the addressees shipping details.

Example:
 
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<root>
	<order_list>
		<order>
			<key>2345</key>
			<date>2017/01/31 23:59:59 +0000</date>
			<recipient_details>
				<recipient>ACME srl</recipient>
				<careof />
				<cfpiva>12345558</cfpiva>
				<customer_key>7777</customer_key>
				<notes></notes>
				<address>
					<street_type>Via</street_type>
					<street_name>Roma</street_name>
					<address_number>1</address_number>
					<zip>10100</zip>
					<city>TORINO</city>
					<province>TO</province>
					<countrycode>IT</countrycode>
				</address>
				<phone>
					<prefix>+39</prefix>
					<number>0112838474</number>
				</phone>
			</recipient_details>
			<item_list>
				<item>
					<stock_id>148148</stock_id>
					<quantity>10</quantity>
				</item>
			</item_list>			
		</order>
	</order_list>
</root>
Note that:

Response Body

The response body contains a list of the model in the order. Each model has three attributes:

Example:
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<root order_id="0">
	<model stock_id="148148" locked="10" available="5" />
</root>
Notes

OrderStatusOrderId

This method allows to get information about the status of an order by passing the unique identification of the order on Brandsdistribution.

The Response Body contains the follow parameters:

URL Method Headers
/restful/ghost/clientorders/serverkey/{order_id} GET

Path Parameter

order_id : the number that identificates the user's order


Example:
    <?xml version="1.0" encoding="UTF-8" standalone="yes"?>
	<root>
	<order_list>
	<order>
		<ext_ref>2345</ext_ref>
			<last_update>2018/05/25 12:20:37 +0200</last_update>
			<order_id>123456</order_id>
			<parsedDate>2018-05-25T12:20:37+02:00</parsedDate>
			<status>3002</status>
            <tracking_url>http://www.dhl.com/content/g0/en/express/tracking.shtml?AWB=0123456789012&brand=DHL</tracking_url>
					</order>
				</order_list>
			</root>


Order Status

Code value Description
0 PENDING User is managing the cart
1 MONEY WAITING Awaiting for payment gateway response
2 TO DISPATCH Ready to be dispatched
3 DISPATCHED Shipment has been picked up by carrier
5 BOOKED Order created by API Acquire or booked by bank transfer
2000 CANCELLED Order cancelled
2002 VERIFY FAILED Payment was not accepted by payment gateway
3001 WORKING ON Logistics office is working on the order
3002 READY Order is ready for pick up
5003 DROPSHIPPER GROWING Virtual order for growing cart

OrderStatus by key

This method allows to get information about the status of an order by passing the unique identification of the orderID on the external platform (key on Single recipient Order api)

The Response Body contains the follow parameters:

URL Method Headers
/restful/ghost/clientorders/clientkey/{key}/ GET

Path Parameter

key : identifies the user’s platform order id.


Example:
    <?xml version="1.0" encoding="UTF-8" standalone="yes"?>
	<root>
	<order_list>
	<order>
		<ext_ref>2345</ext_ref>
			<last_update>2018/05/25 12:20:37 +0200</last_update>
			<order_id>123456</order_id>
			<parsedDate>2018-05-25T12:20:37+02:00</parsedDate>
			<status>3002</status>
            <tracking_url>http://www.dhl.com/content/g0/en/express/tracking.shtml?AWB=0123456789012&brand=DHL</tracking_url>
					</order>
				</order_list>
			</root>


Order Status

Code value Description
0 PENDING User is managing the cart
1 MONEY WAITING Awaiting for payment gateway response
2 TO DISPATCH Ready to be dispatched
3 DISPATCHED Shipment has been picked up by carrier
5 BOOKED Order created by API Acquire or booked by bank transfer
2000 CANCELLED Order cancelled
2002 VERIFY FAILED Payment was not accepted by payment gateway
3001 WORKING ON Logistics office is working on the order
3002 READY Order is ready for pick up
5003 DROPSHIPPER GROWING Virtual order for growing cart

Samples

This is a sample code for a call to the Order API in PHP language (version 5.0.1 or superior):

<?php
……
$xml = new SimpleXMLElement('<?xml version="1.0" encoding="UTF-8" standalone="yes"?>');
$xmlOperation = $xml->addChild('operation');
$xmlOperation->addAttribute(‘type’, ‘lock’);
$xmlModel = $xmlOperation->addChild('model');
$xmlModel->addAttribute(‘stock_id’, $stockId);
$xmlModel->addAttribute(‘quantity’, $quantity);
$xmlText = $xml->asXML();
$ch = curl_init($url);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_USERPWD, $username . ':' . $password);
curl_setopt($ch, CURLOPT_HTTPHEADER,     array('Content-Type: application/xml','Accept: application/xml')); 
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_POSTFIELDS, $xmlText); 
$data = curl_exec($ch);
$httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);
if(!$this->handleCurlError($logger,$httpCode))
	manage error…..
$reader = new XMLReader();
$reader->xml($data);
$reader -> read();
….use $reader
?>

MODULES & BRANDSYNC PLUGIN


Do you want to integrate Brandsdistribution dropshipping with your ecommerce? Checkout these solutions:

MAGENTO

SEE MORE

WORDPRESS

SEE MORE

PRESTASHOP

SEE MORE

SHOPIFY

SEE MORE