Using the « Webservice Add-On » to verify the purchase status of Downloadable Products through SOAP, XMLRPC or REST request

This addon allows to request the current purchase status for a purchased Downloadable Product from the Magento store remotely using SOAP, XMLRPC or REST requests. Each request must contain order and customer related data to successfully complete:

• Request the purchase status using the Customer Email-Address and a Serialnumber to verify if a serialnumber is purchased by the customer.
• Request the purchase status using the Customer Email-Address, Order Increment-ID and Product SKU to get the order status and order item status for a purchased Downloadable Product.

Installation of the import adapter for DownloadPlus is the same as for the DownloadPlus extension itself.

Add a new Web Service Role in the Administrator Backend through System » Web Services » SOAP/XML-RPC Roles (or Roles on Magento 1.6 and below). Use a dedicated role with only the Downloadable Product web service for security reasons.

Select Downloadable Product for this role to allow access to the web service function for all users assigned to this role:

Add a new Web Service user in the Administrator Backend through System » Web Services » SOAP/XML-RPC Users (or Users on Magento 1.6 and below). Use this users credentials to authenticate the web service requests, for security reasons you should create a Web Service user dedicated for the requests to the Downloadplus Web Service API.

Add the data for the web service user, the User Name and API Key are later required to authenticate all requests to the web service.

In the tab User Role select the previously created role for this user to assign the required access privileges to the web service.

Web Service URL for SOAP Request: http://your-store-url/api/v2_soap?wsdl=1 or https://your-store-url/api/v2_soap?wsdl=1 (if your store supports SSL) Data to include in the SOAP Request:

• To query a Serialnumber: customer_email, serialnumber
• To query a Downloadable Product purchase: customer_email, order_increment_id, product_sku

/*
 * SOAP Test Script
 */
$client = new SoapClient('http://your-store-url/api/v2_soap?wsdl=1');
 
$client->startSession();
$session = $client->login('apiuser', 'apikey');
 
$params = Array('filter' => Array(
	    Array('key' => 'customer_email', 'value' => 'someemail@domain.tld.at'),
	    Array('key' => 'serialnumber', 'value' => '#serialnumber#'),
	  ));
 
$result = $client->downloadableProductPurchaseStatus($session, $params);
 
$client->endSession($session);

/*
 * SOAP Test Script
 */
$client = new SoapClient('http://your-store-url/api/v2_soap?wsdl=1');
 
$client->startSession();
$session = $client->login('apiuser', 'apikey');
 
$params = Array('filter' => Array(
	    Array('key' => 'customer_email', 'value' => 'someemail@domain.tld.at'),
	    Array('key' => 'order_increment_id', 'value' => '100001267'),
	    Array('key' => 'product_sku', 'value' => 'TEST-DOWNL')
	  ));
 
$result = $client->downloadableProductPurchaseStatus($session, $params);
 
$client->endSession($session);

Web Service URL for XML-RPC Request: http://your-store-url/api/xmlrpc or https://your-store-url/api/xmlrpc (if your store supports SSL) Data to include in the XML-RPC Request:

• To query a Serialnumber: customer_email, serialnumber
• To query a Downloadable Product purchase: customer_email, order_increment_id, product_sku

/*
 * XML-RPC Test
 */
require_once('app/Mage.php');
 
$client = new Zend_XmlRpc_Client('http://your-store-url/api/xmlrpc/');
 
$session = $client->call('login', array('apiuser', 'apikey'));
 
$params = Array(
	  'customer_email'=>'someemail@domain.tld',
	  'serialnumber'=>'#serialnumber#'
	  );
 
$response = $client->call('call', array($session, 'downloadable_product.purchase_status', array($params)));
 
$client->call('endSession', array($session));

/*
 * XML-RPC Test
 */
require_once('app/Mage.php');
 
$client = new Zend_XmlRpc_Client('http://your-store-url/api/xmlrpc/');
 
$session = $client->call('login', array('apiuser', 'apikey'));
 
$params = Array(
	  'customer_email'=>'someemail@domain.tld',
	  'order_increment_id'=>'100001267',
	  'product_sku'=>'TEST-DOWNL'
	  );
 
$response = $client->call('call', array($session, 'downloadable_product.purchase_status', array($params)));
 
$client->call('endSession', array($session));

The REST requests are GET requests using the following URL-Format, you need to URL-Encode all parameters:

/downloadable_product/purchase_status/customer_email/<customer_email>/serialnumber/<serialnumber>

When requiring to also include the Store-ID of the Magento Store use:
/downloadable_product/purchase_status/customer_email/<customer_email>/serialnumber/<serialnumber>/store/<store_id>

http://your-store-url/downloadable_product/purchase_status/customer_email/someemail%40domain.tld/serialnumber/%23serialnumbe%23
http://your-store-url/downloadable_product/purchase_status/customer_email/someemail%40domain.tld/serialnumber/%23serialnumbe%23/store/3

/downloadable_product/purchase_status/customer_email/<customer_email>/order_increment_id/<order_increment_id>/product_sku/<product_sku>

When requiring to also include the Store-ID of the Magento Store use:
/downloadable_product/purchase_status/customer_email/<customer_email>/order_increment_id/<order_increment_id>/product_sku/<product_sku>/store/<store_id>

http://your-store-url/downloadable_product/purchase_status/customer_email/someemail%40domain.tld/order_increment_id/100001267/product_sku/TEST-DOWNL
http://your-store-url/downloadable_product/purchase_status/customer_email/someemail%40domain.tld/order_increment_id/100001267/product_sku/TEST-DOWNL/store/3

Unauthenticated requests as a REST Guest USER require to use set a Access Token for REST-API Guest Access and include it in the REST request. To set this token go to System » Configuration » Catalog » Downloadable Delivery:

/downloadable_product/purchase_status/customer_email/<customer_email>/serialnumber/<serialnumber>/token/<token>

When requiring to also include the Store-ID of the Magento Store use:
/downloadable_product/purchase_status/customer_email/<customer_email>/serialnumber/<serialnumber>/token/<token>/store/<store_id>

http://your-store-url/downloadable_product/purchase_status/customer_email/someemail%40domain.tld/serialnumber/%23serialnumbe%23/token/somesecret
http://your-store-url/downloadable_product/purchase_status/customer_email/someemail%40domain.tld/serialnumber/%23serialnumbe%23/token/somesecret/store/3

/downloadable_product/purchase_status/customer_email/<customer_email>/order_increment_id/<order_increment_id>/product_sku/<product_sku>/token/<token>

When requiring to also include the Store-ID of the Magento Store use:
/downloadable_product/purchase_status/customer_email/<customer_email>/order_increment_id/<order_increment_id>/product_sku/<product_sku>/token/<token>/store/<store_id>

http://your-store-url/downloadable_product/purchase_status/customer_email/someemail%40domain.tld/order_increment_id/100001267/product_sku/TEST-DOWNL/token/somesecret
http://your-store-url/downloadable_product/purchase_status/customer_email/someemail%40domain.tld/order_increment_id/100001267/product_sku/TEST-DOWNL/token/somesecret/store/3

The web service add-on delivers the following response with the status on the Customer, Serialnumber, Order Status or Orderitem Status in '|' separated form as string value for requests using SOAP or XML-RPC.
For REST requests the response will be XML data and may also include additional error information:

<magento_api>
   <status>customer-not-found</status>
</magento_api>