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.
To authenticate to the API platform you must require an API Key from your handler 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);
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 |
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 |
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 |
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.
This is a reference to use API services. All services use RESTful architecture with authentication. The data format is XML.
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 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 |
---|---|
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 |
<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 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).
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="1000"> <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
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="1000"> <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
• 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 APICreates 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 |
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:
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="1000"> <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 ?>