The product import API allows an external system (for example, a warehouse management system) to add and modify products on bindCommerce, in order to subsequently be sent to the sales channels.
Connector configuration on bindCommerce
To allow the API management system to create and update products on bindCommerce it will be necessary to create a specific configuration and the relative connector.
To create the configuration go to the menu:
API >> Product iport configuration
Click on Add and fill in the fields as follows:
- Configuration Name: Choose the name you think is most appropriate
- Action type: you can choose between - Creation - Creation and update - Update
- Information to consider: Title - Description - Short description - Manufacturer - Supplier - Dimensions and weight - Quantity - Attributes - Tags - Prices - Alternatives - Images - Categories
- Elimination of data not transmitted: Barcode - Images - Products
- Calculate quantity of parent product from the sum of the variants ?: option that allows you to determine if the parent products should have the quantity calculated based on the sum of the stock of the individual variants
- Calculate parent price from the minimum of variants ?: option that allows you to determine if the parent products should have the price calculated based on the lowest price of the individual variants
Click on SAVE AND CLOSE.
To create the connector that will allow you to import products from the API management to bindCommerce you need to go to the menu:
Process >> Connectors
Click on Add and fill in the fields as follows:
- Connector Name: Use whatever name you prefer
- Node Type (Technology): API
- Node: the node created earlier
- Connector type: API [import products]
By clicking on SAVE AND CONTINUE you will have access to the additional fields to be filled in.
- The calling system must use the following string: copy the URL in this field and paste it in the appropriate field on the management control panel
- Connector Configuration: Select the configuration created earlier
- Product filter: to create a product filter, please follow the instructions given in the product Filters guide
Click on SAVE AND CLOSE.
Call and authentication
The call is made to the URL generated by bindCommerce for the specific connector (to be configured in advance through the bindCommerce interface).
Authentication occurs through tokens assigned for the API node. The parameter is passed into the request header.
<?php
ini_set('display_errors', true);
error_reporting(E_ALL);
$strXml = file_get_contents(__DIR__.'/Products.xml');
$curl = curl_init();
curl_setopt_array($curl, array(
CURLOPT_URL => "https://miohost.bindcommerce.cloud/integrator-tool/api/products.php?connector=N",
CURLOPT_SSL_VERIFYPEER => 0,
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_VERBOSE => true,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => $strXml,
CURLOPT_HTTPHEADER => array(
"cache-control: no-cache",
"content-type: text/xml",
"token: 0435a03b361d7cc24fc1acacdeaae1d7"
),
));
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}
This call returns a json so formed:
[ 'status' => success || error 'message' => String with the description of the connector log 'code' => a numerical code that expresses success or failure 'id_exec' => optional - id exec, provided if needed to check the call status (see the STATUS CHECK CALL section) 'id_procedure' => optional - id procedure, provided if needed to check the call status ((see the STATUS CHECK CALL section)) ]
Product files
<?xml version="1.0" encoding="UTF-8"?>
<bindCommerceProducts Mode="full">
<Products>
<Product>
<Language>IT</Language>
<Code>3410116</Code>
<Barcode>8001066510405</Barcode>
<BarcodeKind>EAN</BarcodeKind>
<Title>6 MATITE PER FALEGNAMI 18CM.</Title>
<DescriptionHtml>6 MATITE PER FALEGNAMI 18CM. COLORE ROSSO</DescriptionHtml>
<ShortDescription></ShortDescription>
<Notes />
<Categories>
<Category>Scarpe|Donna|Scarpe da ginnastica</Category>
<Category>Promo</Category>
</Categories>
<Alternatives>
<Alternative>
<Language>IT</Language>
<Title></Title>
<DescriptionHtml></DescriptionHtml>
<ShortDescription></ShortDescription>
<Notes />
</Alternative>
</Alternatives>
<Prices>
<Price>
<ListCode>Public</ListCode>
<ListName>Prezzo pubblico</ListName>
<Currency>EUR</Currency>
<Vat>0.22</Vat>
<NetPrice>1.0820</NetPrice>
<GrossPrice>1.32</GrossPrice>
<OverridePrice>0</OverridePrice>
<Override>0</Override>
</Price>
<Price>
<ListCode>00045</ListCode>
<Currency>EUR</Currency>
<Vat>0.22</Vat>
<NetPrice>0.3200</NetPrice>
<GrossPrice>1.3904</GrossPrice>
<OverridePrice>0</OverridePrice>
<Override>0</Override>
</Price>
<Price>
<ListCode>Quantity discount</ListCode>
<Currency>EUR</Currency>
<Vat>0.22</Vat>
<NetPrice>0.3200</NetPrice>
<GrossPrice>1.3904</GrossPrice>
<OverridePrice>0</OverridePrice>
<Override>0</Override>
<PriceQuantityStart>1</PriceQuantityStart>
<PriceQuantityEnd>5</PriceQuantityEnd>
</Price>
<Price>
<ListCode>Quantity discount</ListCode>
<Currency>EUR</Currency>
<Vat>0.22</Vat>
<NetPrice>0.3200</NetPrice>
<GrossPrice>1.3904</GrossPrice>
<OverridePrice>0</OverridePrice>
<Override>0</Override>
<PriceQuantityStart>6</PriceQuantityStart>
<PriceQuantityEnd>999</PriceQuantityEnd>
</Price>
<Price>
<ListName>Listino 46</ListName>
<Currency>EUR</Currency>
<Vat>0.22</Vat>
<NetPrice>0.3200</NetPrice>
<GrossPrice>1.3904</GrossPrice>
<OverridePrice>0</OverridePrice>
<Override>0</Override>
</Price>
</Prices>
<Manufacturer>METRICA</Manufacturer>
<MPN />
<Supplier>GLP</Supplier>
<Dimensions>
<Weight>0.50</Weight>
<WeightUom>kg</WeightUom>
<WeightVolume />
<LwhUom>cm</LwhUom>
<Length>20.00</Length>
<Width>20.00</Width>
<Height>10.00</Height>
</Dimensions>
<Qty>1</Qty>
<Pictures>
<Picture>
<URL>http://miosito.com/shop/images/341011.jpg</URL>
</Picture>
<Picture tags=”scarpe,sport,estate”>
<URL>http://miosito.com/shop/images/3410116.jpg</URL>
</Picture>
<Picture>
<URL>http://miosito.com/shop/images/3410116.jpg</URL>
</Picture>
</Pictures>
<Attributes>
<Attribute lang=”it”>
<Name>Materiale</Name>
<Value>Gomma</Value>
</Attribute>
<Attribute lang=”it”>
<Name>Colore</Name>
<Value>Rosso</Value>
</Attribute>
<Attribute lang=”en”>
<Name>Color</Name>
<Value>Red</Value>
</Attribute>
</Attributes>
<Warehouses>
<Warehouse>
<WarehouseKey>Magazzino Roma</WarehouseKey>
<Qty>8</Qty>
</Warehouse>
<Warehouse>
<WarehouseKey>Magazzino Milano</WarehouseKey>
<Qty>13</Qty>
</Warehouse>
</Warehouses>
<Variants>
<Variant>
<Code>100383----F254/701/-</Code>
<Barcode>8033766128031</Barcode>
<BarcodeKind>EAN</BarcodeKind>
<Title>BRIKO Maschera sci discesa snowboard unisex S3 nero bianco 100383[701]</Title>
<Qty>1</Qty>
<Pictures>
<Picture>
<URL>http://miosito.com/shop/images/341011.jpg</URL>
</Picture>
<Picture tags=”scarpe,sport,estate”>
<URL>http://miosito.com/shop/images/3410116.jpg</URL>
</Picture>
<Picture>
<URL>http://miosito.com/shop/images/3410116.jpg</URL>
</Picture>
</Pictures>
<Attributes>
<Attribute>
<Name />
<Value />
</Attribute>
</Attributes>
<Prices>
<Price>
<ListName>Prezzo pubblico</ListName>
<Vat>22.0000</Vat>
<NetPrice>1.0820</NetPrice>
<GrossPrice>1.32</GrossPrice>
<OverridePrice>0</OverridePrice>
<Override>0</Override>
</Price>
</Prices>
<Warehouses>
<Warehouse>
<WarehouseKey>Magazzino Roma</WarehouseKey>
<Qty>8</Qty>
</Warehouse>
<Warehouse>
<WarehouseKey>Magazzino Milano</WarehouseKey>
<Qty>13</Qty>
</Warehouse>
</Warehouses>
</Variant>
</Variants>
<Derivatives>
<Derivate>
<Title>Confezione 60 MATITE PER FALEGNAMI 18CM.</Title>
<Code>3410116A</Code>
<Barcode>8001066510405A</Barcode>
<BarcodeKind>EAN</BarcodeKind>
<PackageQty>6</PackageQty>
<PriceMultiplied>9</PriceMultiplied>
</Derivate>
</Derivatives>
</Product>
<Product>
….
</Product>
</Products>
<Delete>
<sku>SKUTEST123</sku>
<sku>SKUTEST456</sku>
</Delete>
</bindCommerceProducts>
File fields
GENERAL STATEMENTS
Field | Description |
|---|---|
Mode | Sending type:
|
Products | Contains one or more <Product> tags |
PRODUCT INFORMATION
Field | Description |
|---|---|
Language | Language in which the product is described in ISO 639-1 format (e.g. IT) |
Code | Product code / SKU (e.g. 3410116) |
Barcode | Bar code (e.g. 8001066510405) |
BarcodeKind | Barcode type (e.g. EAN, UPS, ISBN) |
Title | Product title |
DescriptionHtml | Full description in HTML |
ShortDescription | Short description |
Notes | Notes |
Categories | Group containing categories |
Alternatives | Group containing alternative descriptions |
Prices | Group containing prices |
Manufacturer | Manufacturer or Brand (e.g. Adidas) |
MPN | Manufacturer Product Number, or original manufacturer code (e.g. PERT-G-8678) |
Supplier | Supplier (e.g. Rossi Distribuzioni S.p.A.) |
Dimensions | Group containing dimensions |
Qty | Quantity in stock. Both integer and decimal values (with separator.) Are accepted, e.g. 1 or 55.31 |
MetaTitle
| Meta Title
|
MetaDescription
| Meta Description
|
MetaKeywords
| Meta Keywords
|
Warehouses | Group containing availability on alternative warehouses |
Pictures | Group containing the images |
Attributes | Group containing the attributes |
Variants | Group containing the variants |
CATEGORY (CONTAINED IN THE < CATEGORY > TAG)
Field | Description |
|---|---|
Category | Category tree with pipe separator |
If you want to match multiple category trees to a product, you can add multiple Category tags
ALTERNATIVE (CONTAINED IN THE < ALTERNATIVE > TAG)
Field | Description |
|---|---|
Language | Language in which the product alternative is described in ISO 639-1 format (e.g. EN) |
Title | Title translation |
DescriptionHtml | Translation of the HTML description |
ShortDescription | Translation of the short description |
Notes | Translation of the notes |
PRICE (CONTAINED IN THE < PRICE > TAG)
Field | Description |
|---|---|
ListCode | Price list identification code (eg Public01) corresponding to the price list key "Key Gest (Management price list and API)" |
ListName | Identification name of the price list (eg Public Discounted) |
Currency | Currency |
Vat | VAT rate (e.g. 0.2200) |
NetPrice | Price excluding VAT (e.g. 1.08200) |
GrossPrice | Price including VAT (e.g. 1.32000) |
OverridePrice | Discounted price (e.g. 0) |
Override | Discounted price application |
PriceQuantityStart | Lower quantity limit |
PriceQuantityEnd | Upper quantity limit |
The need to populate both NetPrice and GrossPrice is justified by the certainty of rounding the values. In the event that one of the 2 values should not be completed (not recommended), it will still be possible to have it calculated by bindCommerce at the end of the import.
If a product is structured by variants, updating the price of the variant will automatically calculate the relative price of the parent product as a minimum of the prices of the variants.
With regard to the identification of the price lists, the following rules apply:
- If only the ListCode is present in the XML file, the list key is used to identify it and match it to the existing ones, or possibly create a new one if no match is found (in this case the list code will also be used as its name)
- If only ListName is present in the XML file, the name of the price list is used to identify it and match it to the existing ones, or if necessary create a new one (without key, only with the name) if no matching is found
- If both ListCode and ListName are in the XML file, only ListCode is considered for comparison
DIMENSIONS (CONTAINED IN THE < DIMENSIONS > TAG)
Field | Description |
|---|---|
Weight | Weight (e.g. 0.50) |
WeightUom | Weight measurement unit (e.g. Kg) |
WeightVolume | Volumetric weight (e.g. 0.67). |
LwhUom | Linear unit of measure (e.g. cm) |
Length | Length (e.g. 15.12) |
Width | Base (e.g. 32.00) |
Height | Height (e.g. 5.00) |
WAREHOUSES (CONTAINED IN THE < WAREHOUSE > TAG)
Field | Description |
|---|---|
WarehouseKey | A unique identifier to associate with the warehouse. Automatically, the API call assigns the following name which can be viewed (and changed) in the binding interface. Example if the key is "Milan warehouse" the name will be-> |
Qty | The quantity of product present in the warehouse with the key "WarehouseKey" |
IMAGES (CONTAINED IN THE < PICTURE > TAG)
Field | Description |
|---|---|
URL | Absolute URL of the image to be imported. |
The import order (which determines the export order) is determined by the order of the tags in the XML file, except for the main image, which will always appear first).
Each image can contain comma separated tags which must be passed in the following way:
<Picture tags = "tag1, tag2, tag3"> ... </Picture>
ATTRIBUTE (CONTAINED IN THE < ATTRIBUTE > TAG)
Field | Description |
|---|---|
Name | Name of the attribute |
Value | Value of the attribute |
In order to create a new attribute, the <Attribute lang = "it"> tag must be complete with the language
VARIANT (CONTAINED IN THE < VARIANT > TAG)
Field | Description |
|---|---|
Code | SKU code of the variant |
Barcode | Barcode of the variant |
BarcodeKind | Barcode type of the variant |
Title | Variant title |
Qty | Stock quantity of the variant |
Attributes | Group containing the attributes |
Prices | Group containing prices |
Warehouses | Group containing availability on alternative warehouses |
DERIVATIVE PRODUCTS (CONTAINED IN THE < DERIVATIVES > TAG)
Field | Description |
|---|---|
Code | SKU code of the derivative product |
Barcode | Bar code of the derivative product |
BarcodeKind | Barcode type |
Title | Variant title |
PackageQty | Necessary quantities of the original product |
MultiplierPrice | Price |
Derived products are composed of other products and in turn generate a product.
SKU RECORDINGS (CONTAINED IN THE < RECODES > TAG)
Field | Description |
|---|---|
CodeExt | External code to which you want to combine the product sku |
NodeId | BindCommerce node for which you want to recode |
eBaySiteId | eBay market id for which you want to recode |
AmazonMarket | Amazon market code for which you want to recode (e.g. APJ6JRA9NG5V4) |
Every single recoding must be contained in the <Recode> </Recode> tags. The <Recode> tag can have an “action” attribute that can be set with the value “delete” (<Recode action = "delete">) to cancel a specific recoding previously loaded. The pairing is done with the data sent. It is possible, for example, to cancel all the recodings linked to a node by sending only the "NodeId" tag. For this reason, the advice is to be as precise as possible with the sending of the tags, to avoid accidental massive cancellations.
SPECIFIC SKU DELETION (< DELETE > TAG)
Field | Description |
|---|---|
Sku | Product sku on bindCommerce to be marked as canceled. Any child products will also be marked as canceled.ou want to combine the product sku |
STATUS CHECK CALL
The previous call to import products via API takes delivery of all products and provides a successful result only with regard to taking over, but not with regard to the final import result. This is because it is a batch call which can take several minutes. Instead, to check the result of the import, a new call must be made which provides the execution status log.
The same log can be consulted by clicking on the "Connectors" and "In process" buttons in the bindCommerce interface in the top menu.
To do it instead programmatically, you can use the following instead using the id of the connector whose status you want to know. N = connector id.
In addition to the id parameter (which is always mandatory) it is possible to use the id_exec and id_procedure parameters as returned by the previous call (see the "Call and authentication" section)
Authentication takes place through the same token assigned for the API node.
<?php
$curl = curl_init();
curl_setopt_array($curl, array(
CURLOPT_URL => "https://miohost.bindcommerce.cloud/integrator-tool/api/connector_status.php?id=N",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "GET",
CURLOPT_HTTPHEADER => array(
"cache-control: no-cache",
"content-type: text/xml",
"token: 0a09039b989e7b705da2575ec4ae882f"
),
));
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}
This call returns a json so formed:
[ 'status' => success || error 'message' => String with the description of the connector log 'code' => a numerical code that expresses success or failure ]
If the id_exec or id_exec and id_procedure parameters are specified, the "message" field will be filled in with the content of the log file in CSV format.
The values of the code parameter are shown below
200 => no connector running
201 => connector running
401 => internal error
402 => the connector is missing
403 => internal error
404 => authentication token is missing
405 => token not configured on the node
406 => failed authentication
407 => connector does not exist
509 => Procedure (procedure id) already running since (date)
