bindCommerce API - Documents Import

The document import API allows an external system (for example an ERP) to add or update one or more sales documents (orders or invoices), including any attachments.

Connector configuration on bindCommerce

To configure the appropriate connector, you need to go to the menu

Process >> Connectors

Click on Add and fill in the fields as follows:

  • Connector Name: Indicate the name you prefer
  • Node Type (Technology): API
  • Node: the previously created API type node. For more information on creating this node visit the API Node page
  • Connector type: API [import documents]

By clicking on SAVE AND CONTINUE you will have access to the URL to which the calling system will have to make the call.

thumb api import documents1 

 

Call and authentication

The call is made to the URL generated by bindCommerce for the specific connector (to be configured through the bindCommerce interface as explained in the previous paragraph).
Authentication takes place through tokens assigned to the API node. The parameter is passed in the request header.

Example PHP script to make the call

<?php

//  $strXml = … contenuto del file xml

$curl = curl_init();

curl_setopt_array($curl, array(

  CURLOPT_URL => "https://miohost.bindcommerce.cloud/integrator-tool/api/documents.php?connector=N",

  CURLOPT_RETURNTRANSFER => true,

  CURLOPT_ENCODING => "",

  CURLOPT_MAXREDIRS => 10,

  CURLOPT_TIMEOUT => 30,

  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,

  CURLOPT_CUSTOMREQUEST => "POST",

   CURLOPT_POSTFIELDS => $strXml,

  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
'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))
]

Documents files

In the XML file sent it is necessary to specify the type of operation to do through the tag:

 <bindCommerceDocuments mode="[insert the action]">

Possible values are:

  • CreateModify: it is used to create or modify a document, which will have as assignee node the API type that is making the call. This mode can for example be used by an eCommerce platform or a marketplace to manage integration with bindCommerce.
  • StatusUpdate: used to update the status of a document or of one or more lines of the document, even if the order was generated by a sales channel other than the node making the call.

When the chosen mode is StatusUpdate, the status that is sent for the order or the order line (<State>) must find a correspondence with the possible statuses already present in bindCommerce in the correspondence table (which can be consulted and modified by following the "Processes> menu" Conversions and Normalizations> Order Status Conversion "). The starting technology must be "API" and the starting state the one written in the XML file sent. If this status is not present in bindCommerce it will be necessary to create it (following the menu "System parameters> Order status").

In the absence of correspondence, the order status will not be updated.

When the mode chosen is CreateModify, if the status sent for the order or the order line (<State>) is not already present, bindCommerce will create it (combined with the API node that created or modified the order).

Example to update the order status

<?xml version="1.0" encoding="UTF-8"?>

<bindCommerceDocuments mode="StatusUpdate">

<Documents>

       <Document>

              <General>

                     <bindNumber>15918</bindNumber>

                     (oppure <OrderNumber>89568-GFGNJK</OrderNumber>)

                     <LastUpdate>2021:01:10 12:36:19</LastUpdate>

                     <State>Shipped</Name>

              </General>

              <Shipping>

                     <Carrier>UPS</Carrier>

                     <TrackingNumber>254131634364326012</TrackingNumber>

                     <TransportedWeight>0.2</TransportedWeight>

                    <ShippedTime>2021-03-23 16:47:22</ShippedTime>

             </Shipping>

       </Document>

       <Document>

       […..]

</Document>

</Documents>

</bindCommerceDocuments>

File fields

GENERAL STATEMENTS

Field

Description

Documents

Contains one or more <Document> tags

INFORMATION ABOUT THE DOCUMENT (GENERAL)

Field

Description

DocumentType

Type of document. In standard implementations it is used (C = Sales order, E = Purchase order, I = Invoice, N = Credit note, R = Receipt)

bindNumber

Internal bindCommerce identifier, Does not need to be filled in to create a new document

OrderNumber

Sales or vendor order number relative to the source node of the document. It will not be considered in the update phase if the Id field is also present.

DocumentNumber

Document number other than order (invoice, credit note or receipt). It will not be considered in the update phase if the Id field is also present.

Date

Creation date and time (UTC time)

LastUpdate

Date and time of last update (UTC time)

State

Status of the document. Free value to identify the status of the document in the source node. The transmitted value assumes the value of a code although it can speak (e.g. Shipped, Canceled, Unshipped, Sent, etc.)

B2B

B2B order (1 or 0)

Currency

ISO 4217 currency (e.g. EUR, CHF, GBP, USD).

Notes

Notes entered by the buyer (ref. Notes)

SellerNote

Notes entered by the seller (ref. Seller_note)

ATTACHMENTS

Field

Description

Attached

Content of the file to be attached encoded in base64 MIME.
The filename attribute is mandatory and must contain the name of the file to be imported

BILLING INFORMATION (CUSTOMER)

Field

Description

Code

Alphanumeric code that identifies the customer

Name

Name

Surname

Surname

Company

Company

Address

Street Address

Postcode

ZIP code / Postcode

City

City / Town

Province

County

CountryCode

Country code ISO 3166-1 Alpha-2 (e.g. IT)

VatCode

VAT number

FiscalCode

Personal tax code or similar identification

Phone

Phone

MobPhone

Mobile phone number

Email

Email

EInvoiceDestCode

Recipient code for electronic invoicing (SDI) or certified email address

Pec

Certified email

SHIPPING INFORMATION (DELIVERY)

Field

Description

Name

Name

Surname

Surname

Company

Company

Address

Street Address

Postcode

ZIP code / Postecode

City

Town / City

Province

County

CountryCode

Country code ISO 3166-1 Alpha-2 (e.g. IT)

Phone

Phone

MobPhone

Mobile phone number

Email

Email

PAYMENT INFORMATION (PAYMENTS)

Field

Description

PaymentName

Payment method name

PaymentCode

Payment method code

PaymentTotal

Cost of collection including VAT (for example for cash on delivery payments there is an additional cost to be paid by the customer)

PaidTime

Payment date and time

PaymentStatus
Payment status. Allowed values: "Complete", "Incomplete", "Pending"

ORDER LINES (ROWS)

Each order line is contained in a <Row> tag

Field

Description

Code

Product SKU code

Description

Description of the order line as it appears on the sales channel.

Qty

Purchased quantity (number)

PriceVatExcluded

Unit price excluding VAT (possibly already discounted)

Price

Unit price including VAT (possibly already discounted)

VatRate

VAT rate (e.g. 0.22 to indicate 22%).

AMOUNTS

Field

Description

ShippingCost

Shipping cost including VAT

ShippingTax

VAT on shipping

CouponDiscount

Coupon discount (ref. coupon_discount)

CouponCode

Coupon code

DiscountToCart

Shopping cart discount

Total

Total order including all expenses and all costs

INFORMATION ABOUT SHIPPING (SHIPPING)

Field

Description

Carrier

Carrier

TrackingNumber

Tracking Number

TransportedWeight

Transported weight

ShippedTime

Date and time of shipment

ShippingMethod

Shipping Method

STATUS CHECK CALL

The previous call to import documents via API takes delivery of all documents and provides a successful result only with regard to taking delivery, but not with regard to the final import result. This is because it is a batch call that can take several minutes. To check the outcome of the import instead, you need to make a new call that provides the execution status log.

The same log can be consulted from the "Logs> Connector execution log" menu

To do it programmatically, you can use the following function (where N = id of the connector).

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 script example to check the connector log

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

0 of 5 - 0 votes
Thank you for rating this article.

Tutorials

bindCommerce platform
Nodes
Creating a Web Server node to publish images
Connectors
Procedures
Logs
Products
Categories
Product attributes
Price lists and prices
Manufacturers
Alternative descriptions
Payment and shipping methods
Orders
Customers
Filter setting on products
Filter setting on orders
Multi warehouse
Internal processing
How to use templates
Template gallery
Creation and customization of templates
Responsive photo gallery in eBay description
Creation and activation of a connector to create/update alternative descriptions
Match categories
Update Price List
Dynamic currency conversion
Internal processing script
Attribute enrichment script
Barcode type calculation
Generation of derived products
Order transformation
Quantity rules
Distribution grid
Conversions and normalizations
Conversions
Currency conversion
Order status normalization
SKU recoding
Marketplaces
eBay integration
eBay nodes installation
Matching with eBay categories
Sales terms
Parameters for listing generation
eBay listing generation
Download listings from eBay
Fixed price sale or auction
eBay listing details list
Listing update
Early ending of listings
Relisting
Responses from eBay and related logs
The automated workflow
Download orders from eBay
Download categories from the eBay shop and match with product categories
Matching of eBay categories international markets
Copy Manufacturer and MPN to Attributes
Amazon integration
Amazon node
PRE-SALE ACTIVITIES
Amazon listings and details
Creation and publication of products/offers to Amazon
Set up Amazon shipping templates
Products already on Amazon
Parameters configuration for preparing Amazon offers
Amazon offers generation connector
Creation of products already present on Amazon
New products publishing
Parameters configuration for preparing Amazon offers
Creation of products not present on Amazon
Amazon offers generation connector
Matches with Amazon categories
Selling on Amazon: Attributes tutorial
Clothing category tutorial
Shoes category tutorial
Responses from Amazon and related Logs
AFTER-SALES ACTIVITIES
Download orders from Amazon
Order status update from bindCommerce
Amazon Business integration
PRE-SALES ACTIVITIES
B2B prices
VAT classification
Discounts for quantities
AFTER-SALES ACTIVITIES
Amazon Business order download
Billing management
Upload invoices issued by Danea
Download invoices on Danea
ePrice integration
ePrice listings preparation
ePrice node installation
Sending ePrice listings
Download ePrice orders
Creation of sample product files
Orders update to ePrice
ManoMano integration
ManoMano nodes installation
Send listings to ManoMano
Download orders from ManoMano
cDiscount integration
Category matching
Shipping methods mapping
Cdiscount node
Couriers mapping
Publishing new products on cDiscount
Publication of offers on Cdiscount
Import orders from Cdiscount
Cdiscount problem fixing
Allegro integration
Allegro node installation and configuration
Create Allegro Category Matches
Publishing products on Allegro
Product update on Allegro
Import orders from Allegro
AliExpress integration
AliExpress node installation
AliExpress category matching
Publishing products on AliExpress
Product groups and AliExpress brands
Download orders from AliExpress
Wish integration
Wish node installation
Publishing products on Wish
Carrier mapping for Wish
Download orders from Wish
Order update on Wish
eCommerce
VirtueMart integration
VirtueMart node
Download orders from VirtueMart
Upload orders on Virtuemart
Upload products on VirtueMart
Download products from VirtueMart
Download product link from Virtuemart
WooCommerce integration
WooCommerce node
Download orders from WooCommerce
Download configurations from WooCommerce
Uploading orders on WooCommerce
Product publishing
Import products from Woocommerce
Plugin bindCommerce for WooCommerce
Prestashop integration
Prestashop node installation
Uploading orders on PrestaShop
Download orders from Prestashop
Downloading products from Prestashop
Product publishing on Prestashop
Connector for downloading Prestashop configurations
Magento integration
Magento node
Download orders from Magento
Upload orders on Magento
Product publishing on Magento
Import of Magento products
Shopify integration
Shopify node
Products import from Shopify
Publishing products on Shopify
Download configurations from Shopify
Integration of Mlveda's Multi Country Pricing App
Download orders from Shopify
Upload orders on Shopify
OpenCart integration
OpenCart node installation
Publishing products on OpenCart
Download orders from OpenCart
Import products from OpenCart
Uploading orders on OpenCart
Ads sites
Social Networks
Facebook Catalogue integration
Configuring the Facebook Catalogue feed
Price comparators
Google Shopping integration
Translation and content enrichment
Integration with Google Translate
Integration with Icecat
Payment systems
Integration with PayPal
Import files
File format
Data file import
API for developers
API node
Export Orders
Import Products
Export Products
Documents import
Shipping update (legacy)

bindCommerce

bindCommerce s.r.l.

VAT Number IT07798861212 - SDI M5UXCR1
Registered in Napoli - REA: NA - 910618
Share capital € 20.000,00 fully paid
Tel: +39 011 089 122 0
E-mail: [email protected]

PON 2014>20 Riaccendiamo lo sviluppo