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

Requires the API Add-On for DownloadPlus

Requesting the purchase status for a purchased Downloadable Product required the add-on available here...



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.

Update DownloadPlus to the most recent release prior to installation of this Add-On. Updates are available in your Customer Account.



Allow access to the Magento SOAP/XML-RPC Web Service

Add a Role

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 User and assign 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 User data

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.

Assign the users Role

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


SOAP Request

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

PHP Code Example: Query a Serialnumber

/*
 * 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);

PHP Code Example: Query a Downloadable Product purchase

/*
 * 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);



XML-RPC Request

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

PHP Code Example: Query a Serialnumber

/*
 * 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));

PHP Code Example: Query a Downloadable Product purchase

/*
 * 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));



This requires Magento 1.7 or higher, as the required REST-API has been introduced with Magento 1.7.

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

URL Format for REST requests as authenticated REST Admin or REST Customer user

To query a Serialnumber

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

Example

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


To query a Downloadable Product purchase

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

Example

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



For REST requests as unauthenticated REST Guest user

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:


To query a Serialnumber

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

Example

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


To query a Downloadable Product purchase

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

Example

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:

XML response on REST request

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


Response when querying a Serialnumber

Response Example for a request on a Serialnumber

serialnumber-found|customer-found|order-status-complete
Response CodeMeaning
status-unknownThe request did not render a useful response.
serialnumber-not-foundThe Serialnumber was not found as purchased.
serialnumber-foundThe Serialnumber was found as purchased.
customer-not-foundThe Customer Account for the email address was not found.
customer-foundThe Customer Account for the email address in the request was found.
customer-email-mismatchThe serialnumber in the request is assigned to a customer account but the email addresses in the request and on the Customer Account do not match.
order-status-pending order-status-pending_payment order-status-cancelled order-status-hold order-status-completeThe status of the order related to the Serialnumber and Customer Account with the status codes of Magento.


Response when querying a Downloadable Product purchase

Response Example for a request on a Downloadable Product purchase

customer-found|order-status-complete|order-item-status-expired
Response CodeMeaning
status-unknownThe request did not render a useful response.
customer-not-foundThe Customer Account for the email address was not found.
customer-foundThe Customer Account for the email address in the request was found.
product-not-foundThe Product with the Product SKU of the request was found.
product-foundThe Product with the Product SKU of the request was not found.
order-not-foundThe Order with the Order-Increment-ID of the request was not found.
order-status-pending order-status-pending_payment order-status-cancelled order-status-hold order-status-completeThe status of the order related to the Serialnumber and Customer Account with the status codes of Magento.
order-item-status-available order-item-status-expiredThe status of the purchased Downloadable Product with the status codes of Magento. If the purchased Downloadable Product has expired due to maximum number of downloads, or a expiration date, then the response order-item-status-expired is used.