September 2006
XML order notifications to remote URL
We have added support for XML order notifications to be sent to a remote URL.
This will allow you to receive each order notification directly from our system. No more worries about lost or non-secure email!
Each product can be set up for separate notifications to be sent. To utilize this feature, simply insert the URL to your XML parser in the “XML order notifications to remote URL” field under the Vendor Order Notifications section of the Add/Edit products interface.
XML order notifications are sent out with UTF-8 character encoding. Please also remember that the XML standard requires encoding of some characters, most notably the ampersand (‘&’).
The XML order notification is a request and REQUIRES a response. Without proper response, BMT will assume that the request was not received, and will resend until the expected response is obtained. (BMT will abandon the request after 7 days of failure). An XML order notification request always has the required tags and . The response to the order notification must have the tags and . If you need to report an error back to BMT micro, the tags and can be used.
Example of request:
<request>
<ordernotification>
<orderid>BMT Micro Order ID number, 7 digits or more</orderid>
<ordernumber>BMT Micro Long format order number</ordernumber>
<customer>
<billing>
<company>Name of company, billing address</company>
<lastname>Last name of customer, billing address</lastname>
<firstname>First name of customer, billing address</firstname>
<address1>Address of customer, line 1, billing address</address1>
<address2>Address of customer, line 2, billing address</address2>
<city>City of customer, billing address</city>
<state>State of customer, billing address</state>
<zip>ZIP code of customer, billing address</zip>
<country>Country of customer, billing address</country>
<phone>Phone number of customer, billing address</phone>
<altphone>Alternate phone number of customer, billing address</altphone>
<fax>Fax number of customer, billing address</fax>
<email>Customer e-mail address, billing address</email>
<altemail>Customer alternate e-mail address, billing address</altemail>
<vatnumber>Customer Value Added Tax number in the European Union</vatnumber>
</billing>
<shipping>
<company>Name of company, shipping address</company>
<lastname>Last name of customer, shipping address</lastname>
<firstname>First name of customer, shipping address</firstname>
<address1>Address of customer, line 1, shipping address</address1>
<address2>Address of customer, line 2, shipping address</address2>
<city>City of customer, shipping address</city>
<state>State of customer, shipping address</state>
<zip>ZIP code of customer, shipping address</zip>
<country>Country of customer, shipping address</country>
<phone>Phone number of customer, shipping address</phone>
<fax>Fax number of customer, shipping address</fax>
<email>Customer e-mail address, shipping address</email>
</shipping>
<registername>The name on which the product should be registered</registername>
</customer>
<orderitem>
<itemnumber>Ordinal number of item in order</itemnumber>
<productid>Product ID</productid>
<productname>Product name</productname>
<quantity>Quantity ordered</quantity>
<productprice>Price of product in product currency</productprice>
<productdiscount>Discount amount</productdiscount>
<vendorroyalty>Vendor royalty (in vendor currency)</vendorroyalty>
<affiliateroyalty>Affiliate royalty (in vendor currency)</affiliateroyalty>
<bmtroyalty>BMT's royalty (in vendor currency)</bmtroyalty>
<vendorcurrency>Vendor currency</vendorcurrency>
<productcurrency>Product currency</productcurrency>
<affiliateid>Affiliate id</affiliateid>
<discountcode>Discount code</discountcode>
<iteminfo>Item info</iteminfo>
<downloadpassword>Download password</downloadpassword>
<registrationkeys>
<keydata keynumber="1" keypart="1">Registration key 1, part 1</keydata>
<keydata keynumber="1" keypart="2">Registration key 1, part 2</keydata>
<keydata keynumber="2" keypart="1">Registration key 2, part 1</keydata>
<keydata keynumber="2" keypart="2">Registration key 2, part 2</keydata>
</registrationkeys>
</orderitem>
<orderdate>The date the order was placed in ISO-8601 calendar date format</orderdate>
<ordercurrency>The currency used for the order (payment currency)</ordercurrency>
<ipaddress>IP-address of the remote system placing the order in decimal dotted format (xxx.xxx.xxx.xxx)</ipaddress>
<referral>Referral field copied from order form, if present</referral>
<orderparameters>Order parameters</orderparameters>
<ponumber>Purchase order number</ponumber>
<comments>Customer comments</comments>
<howheard>Customer comments, howheard field</howheard>
<ccom index="0">Customer comments, ccom0 field</ccom>
<ccom index="1">Customer comments, ccom1 field</ccom>
<ccom index="2">Customer comments, ccom2 field</ccom>
</ordernotification>
</request>
Example of response if notification received OK:
<response> <ordernotification/> </response>
Example of response if notification cannot be processed at this time:
<response>
<ordernotification>
<errorcode>1</errorcode>
<errormessage>Our database is currently down for maintenance</errormessage>
</ordernotification>
</response>
Here is a sample PHP script for parsing the XML sent by our system.
<?php
class BMTXMLParser {
var $tag_name;
var $tag_data;
var $tag_prev_name;
var $tag_parent_name;
function BMTXMLParser () {
$tag_name = NULL;
$tag_data = array ();
$tag_prev_name = NULL;
$tag_parent_name = NULL;
}
function startElement ($parser, $name, $attrs) {
if ($this->tag_name != NULL) {
$this->tag_parent_name = $this->tag_name;
}
$this->tag_name = $name;
}
function endElement ($parser, $name) {
if ($this->tag_name == NULL) {
$this->tag_parent_name = NULL;
}
$this->tag_name = NULL;
$this->tag_prev_name = NULL;
}
function characterData ($parser, $data) {
if ($this->tag_name == $this->tag_prev_name) {
$data = $this->tag_data[$this->tag_name] . $data;
}
$this->tag_data[$this->tag_name] = $data;
if ($this->tag_parent_name != NULL) {
$this->tag_data[$this->tag_parent_name . "." . $this->tag_name] = $data;
}
$this->tag_prev_name = $this->tag_name;
}
function parse ($data) {
$xml_parser = xml_parser_create ();
xml_set_object ($xml_parser, $this);
xml_parser_set_option ($xml_parser, XML_OPTION_CASE_FOLDING, false);
xml_set_element_handler ($xml_parser, "startElement", "endElement");
xml_set_character_data_handler ($xml_parser, "characterData");
$success = xml_parse ($xml_parser, $data, true);
if (!$success) {
$this->tag_data['error'] = sprintf ("XML error: %s at line %d", xml_error_string(xml_get_error_code ($xml_parser)), xml_get_current_line_number ($xml_parser));
}
xml_parser_free ($xml_parser);
return ($success);
}
function getElement ($tag) {
return ($this->tag_data[$tag]);
}
}
$bmtparser = new BMTXMLParser ();
echo '<?xml version="1.0" encoding="utf-8"?>';
echo '<response>';
echo '<ordernotification>';
#
# Simple example of writing the data
# to a local XML file. Substitute your
# dB connection or other functions here.
#
########################################
$postdata = file_get_contents ("php://input");
if ($bmtparser->parse ($postdata)) {
$filename = $bmtparser->getElement ('orderid') . "-" . $bmtparser->getElement ('itemnumber') . ".xml";
$fp = fopen ($filename, "wt");
fwrite ($fp, "Order ID: " . $bmtparser->getElement ('orderid') . "\n");
fwrite ($fp, "Order Number: " . $bmtparser->getElement ('ordernumber') . "\n");
fwrite ($fp, "Name of company, billing address: " . $bmtparser->getElement ('billing.company') . "\n");
fwrite ($fp, "Last name of customer, billing address: " . $bmtparser->getElement ('billing.lastname') . "\n");
fwrite ($fp, "First name of customer, billing address: " . $bmtparser->getElement ('billing.firstname') . "\n");
fwrite ($fp, "Address of customer, line 1, billing address: " . $bmtparser->getElement ('billing.address1') . "\n");
fwrite ($fp, "Address of customer, line 2, billing address: " . $bmtparser->getElement ('billing.address2') . "\n");
fwrite ($fp, "City of customer, billing address: " . $bmtparser->getElement ('billing.city') . "\n");
fwrite ($fp, "State of customer, billing address: " . $bmtparser->getElement ('billing.state') . "\n");
fwrite ($fp, "ZIP code of customer, billing address: " . $bmtparser->getElement ('billing.zip') . "\n");
fwrite ($fp, "Country of customer, billing address: " . $bmtparser->getElement ('billing.country') . "\n");
fwrite ($fp, "Phone number of customer, billing address: " . $bmtparser->getElement ('billing.phone') . "\n");
fwrite ($fp, "Alternate phone number of customer, billing address: " . $bmtparser->getElement ('billing.altphone') . "\n");
fwrite ($fp, "Fax number of customer, billing address: " . $bmtparser->getElement ('billing.fax') . "\n");
fwrite ($fp, "Customer e-mail address, billing address: " . $bmtparser->getElement ('billing.email') . "\n");
fwrite ($fp, "Customer alternate e-mail address, billing address: " . $bmtparser->getElement ('billing.altemail') . "\n");
fwrite ($fp, "Customer Value Added Tax number in the European Union: " . $bmtparser->getElement ('billing.vatnumber') . "\n");
fwrite ($fp, "Name of company, shipping address: " . $bmtparser->getElement ('shipping.company') . "\n");
fwrite ($fp, "Last name of customer, shipping address: " . $bmtparser->getElement ('shipping.lastname') . "\n");
fwrite ($fp, "First name of customer, shipping address: " . $bmtparser->getElement ('shipping.firstname') . "\n");
fwrite ($fp, "Address of customer, line 1, shipping address: " . $bmtparser->getElement ('shipping.address1') . "\n");
fwrite ($fp, "Address of customer, line 2, shipping address: " . $bmtparser->getElement ('shipping.address2') . "\n");
fwrite ($fp, "City of customer, shipping address: " . $bmtparser->getElement ('shipping.city') . "\n");
fwrite ($fp, "State of customer, shipping address: " . $bmtparser->getElement ('shipping.state') . "\n");
fwrite ($fp, "ZIP code of customer, shipping address: " . $bmtparser->getElement ('shipping.zip') . "\n");
fwrite ($fp, "Country of customer, shipping address: " . $bmtparser->getElement ('shipping.country') . "\n");
fwrite ($fp, "Phone number of customer, shipping address: " . $bmtparser->getElement ('shipping.phone') . "\n");
fwrite ($fp, "Fax number of customer, shipping address: " . $bmtparser->getElement ('shipping.fax') . "\n");
fwrite ($fp, "Customer e-mail address, shipping address: " . $bmtparser->getElement ('shipping.email') . "\n");
fwrite ($fp, "The name on which the product should be registered: " . $bmtparser->getElement ('registername') . "\n");
fwrite ($fp, "Ordinal number of item in order: " . $bmtparser->getElement ('itemnumber') . "\n");
fwrite ($fp, "Product ID: " . $bmtparser->getElement ('productid') . "\n");
fwrite ($fp, "Product name: " . $bmtparser->getElement ('productname') . "\n");
fwrite ($fp, "Quantity ordered: " . $bmtparser->getElement ('quantity') . "\n");
fwrite ($fp, "Price of product: " . $bmtparser->getElement ('productprice') . " " . $bmtparser->getElement ('productcurrency') . "\n");
fwrite ($fp, "Discount amount: " . $bmtparser->getElement ('productdiscount') . " " . $bmtparser->getElement ('productcurrency') . "\n");
fwrite ($fp, "Vendor royalty: " . $bmtparser->getElement ('vendorroyalty') . " " . $bmtparser->getElement ('vendorcurrency') . "\n");
fwrite ($fp, "Affiliate royalty: " . $bmtparser->getElement ('affiliateroyalty') . " " . $bmtparser->getElement ('vendorcurrency') . "\n");
fwrite ($fp, "BMT's royalty: " . $bmtparser->getElement ('bmtroyalty') . " " . $bmtparser->getElement ('vendorcurrency') . "\n");
fwrite ($fp, "Vendor currency: " . $bmtparser->getElement ('vendorcurrency') . "\n");
fwrite ($fp, "Product currency: " . $bmtparser->getElement ('productcurrency') . "\n");
fwrite ($fp, "Affiliate id: " . $bmtparser->getElement ('affiliateid') . "\n");
fwrite ($fp, "Discount code: " . $bmtparser->getElement ('discountcode') . "\n");
fwrite ($fp, "Item info: " . $bmtparser->getElement ('iteminfo') . "\n");
fwrite ($fp, "Download password: " . $bmtparser->getElement ('downloadpassword') . "\n");
fwrite ($fp, "Registration key: " . $bmtparser->getElement ('keydata') . "\n");
fwrite ($fp, "Order date: " . $bmtparser->getElement ('orderdate') . "\n");
fwrite ($fp, "Payment currency: " . $bmtparser->getElement ('ordercurrency') . "\n");
fwrite ($fp, "Order IP address: " . $bmtparser->getElement ('ipaddress') . "\n");
fwrite ($fp, "Referral: " . $bmtparser->getElement ('referral') . "\n");
fwrite ($fp, "Order parameters: " . $bmtparser->getElement ('orderparameters') . "\n");
fwrite ($fp, "Purchase order: " . $bmtparser->getElement ('ponumber') . "\n");
fwrite ($fp, "Customer comments: " . $bmtparser->getElement ('comments') . "\n");
fwrite ($fp, "How heard: " . $bmtparser->getElement ('howheard') . "\n");
fwrite ($fp, "Comments (ccom): " . $bmtparser->getElement ('ccom') . "\n");
fclose ($fp);
}
#
# Insert an error code into the response
# so we can distinguish between no response
# and an error with the transaction.
#
###########################################
else {
echo '<errorcode>1</errorcode>';
echo '<errormessage>' . $bmtparser->getElement ('error') . '</errormessage>';
}
echo '</ordernotification>';
echo '</response>';
?>
You can view any error messages while testing with this System Error report.
For further information or help regarding this option, please contact us.