Hi developers!

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.

Authentication

To authenticate to the API platform you need to use the API Key you can find on the Subscriptions page of your profile on Brandsdistribution, that will be used instead of your username for all api calls. The password is the same of your brandsdistribution.com website account. Password of your ecommerce account and password used with the API are keep in sync so when you change brandsdistribution.com account password website you will also have to change the password you are using to implement API in 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 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

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

API interface

The API services allow the user clients to manage orders. They can add or remove items into the order and confirm all or a part of the items in multiple orders.

Services are:

Name (mnemonic) Meaning
Products Gets the products information from catalog. It contains IDs, descriptions, availability, etc…
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
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

Order management workflow

How to correctly use APIs:

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

Sandbox

A sandbox platform is provided to developers for testing purpose of API implementation without disrupting activities on the live platform. Please read following notes regarding the use of the sandbox platform.
Getting started on the sandbox:

API Services reference

This is a reference to use API services. All services use RESTful architecture with authentication. The data format is XML.

Products

Allows to get the products and items informations from the catalog. Catalog 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
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)
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

*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)
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 modifications from the last update. Pricing variations will not appear in this list unless the quantities also change.

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

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

• The maximum addable quantity of a model is dipendent on the available quantity. You can't exceed this quantity: if you require more than the available quantity, only the available quantity will be added and no error or message will be returned. In order to make sure that all your models are correctly added to your order make sure to have reserved them (using Reserve) before calling this API
• If the request body contains not existing stock_id, this will cause the abort of the order creation. The error code 500 (Internal Server Error) will be returned. Some of the required quantites may have been added to your reservation. We recommend you to 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 the stock_id of the products belongs to the content of the order.
• If the request body contains errors this will cause the abort of the order creation. The http status code 429 will be returned and request body contains the error message.

SingleRecipientOrder

Creates an order with the given items and quantities for a user’s customer. The order will be dispatched, after users payment, to the given recipient (user’s customer).

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 recipient 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