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.
The Brandsdistribution platform can be integrated to any ecommerce platform via RESTful Web Services. Web Services are available for authenticated Dropshipper users only.
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.
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 |
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);
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.
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). |
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
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 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 |
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>
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 |
<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>
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).
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 |
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:
<?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>
The response body contains a list of the model in the order. Each model has three attributes:
<?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
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 |
The response body contains a list of the model in the order. Each model has three attributes:
<?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>
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 |
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)The quantity can be less, equal or greater than the quantities in the growing order:
• less: the remaining quantities are kept in the growing orderExample
<?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>
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.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 |
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:
The response body contains a list of the model in the order. Each model has three attributes:
<?xml version="1.0" encoding="UTF-8" standalone="yes"?> <root order_id="0"> <model stock_id="148148" locked="10" available="5" /> </root>Notes
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 |
order_id : the number that identificates the user's order
<?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>
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 |
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 |
key : identifies the user’s platform order id.
<?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>
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 |
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 ?>