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.
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.
<?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).
<?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. |
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 |
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 |
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
$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
