Retailer Integration
Overview
So, you want to sell eBooks from your Website under DRM (Digital Rights Management) Security?
Yes, this is now possible. Digital Media Reserve offers Web Services which includes a centralized repository of ebook files and the sales fulfillment of DRM protected ebooks (EPUB and PDF/A Formats).
A Web Service is a method of communications between two electronic devices over the World Wide Web
Publishers upload their ebook (EPUB and PDF/A) files to Digital Media Reserve's digital warehouse. Publisher and Retailers can integrate with Digital Media Reserve in order to sell ebooks from their own Websites.
The Retail Website and the Digital Media Reserve server communicate using Web Services with encrypted parameters embedded in request messages.
Requirements for Retailer for Selling eBooks:
-
Dynamic Website with Search, Shopping Cart and Payment Gateway (developed in PHP, ASP or JSP with SOAP support).
-
Website should be capable in calling SOAP based Web Services and should be able to receive their response.
-
Website should have a Static IP.
Steps for a Retail Website Integration with Digital Media Reserve Web Services
-
Apply for a Digital Media Reserve Retailer account. [Publisher Registration: http://www.digitalmediareserve.com/?module=register]
-
Once your account is activated, you can browse and download the title metadata for the available eBooks catalog in form of an XML file.
-
Import the eBooks data into your Website in order to create pages for customers to browse and purchase eBooks from your Website. You will be required to add your retailer account details (CommerceID, RetailerID and RetailerKey) on your Website which will be used at the time of calling Web Services.
-
Implement CheckAvailability Web Service to check the availability of an ebook for sale before a customer may add it to the shopping cart.
-
After a successful payment on your Website, call the NewTransaction Web Service in order to get the eBook file download link(s) from Digital Media Reserve. Provide the link(s) to your customer.
CheckAvailability Web Service
A Retailer (identified by its Authentication Parameters) can use this Web Service to check the availability of an eBook before asking the customer to pay.
Syntax:
URL: http://www.digitalmediareserve.com/webservices/retailers/
URN: http://www.digitalmediareserve.com/webservices/retailers/
SOAP Request:
<?xml version="1.0" encoding="UTF-8"?>
<SOAP-ENV:Envelope>
<SOAP-ENV:Header>
<Username>CommerceID</Username><Password>Password</Password>
</SOAP-ENV:Header>
<SOAP-ENV:Body>
<CheckAvailability>
<RetailerID>RetailerID</RetailerID><BookID>BookID</BookID><Format>Format</Format>
</CheckAvailability>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>
SOAP Response:
<?xml version="1.0" encoding="UTF-8"?>
<SOAP-ENV:Envelope>
<SOAP-ENV:Body>
<CheckAvailabilityResponse>
<Books><Book><Availability>1=>Available | 0=>Not Available</Availability></Book></Books>
</CheckAvailabilityResponse>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>
SOAP Response For Error:
<?xml version="1.0" encoding="UTF-8"?>
<SOAP-ENV:Envelope>
<SOAP-ENV:Body>
<CheckAvailabilityResponse>
<Errors><Error><Code>ErrorCode</Code><Message>ErrorMessage</Message></Error></Errors>
</CheckAvailabilityResponse>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>
PHP Code By PEAR-SOAP 0.12.0
<?php
require_once('SOAP/Client.php');
define('_URL','http://digitalmediareserve.com/webservices/retailers/');
define('_NS','urn:http://digitalmediareserve.com/webservices/retailers/');
define('retailerkey','<your retailer key>');
define('commerceid','<your commerce id>');
define('retailerid','<your retailer id>');
$client = new SOAP_Client(_URL); //Create Soap Client Object
$bookid = 28; //Unique eBook ID provided by DMR
$format = “epub or pdf”; //eBook Format
/*Create sh1 hash password by encrypting retailerid, bookid and format by your retailer key*/
$stringpass = md5(commerceid).retailerid.$bookid.$format;
$password = hash_hmac("sha1",$stringpass,retailerkey);
$value = array('Username',md5(commerceid),_NS);
$client->addHeader($value);
$value = array('Password',$password,_NS);
$client->addHeader($value);
$options = array('namespace'=>_NS);
$options['trace'] = true; //true or false
//Call webservice
$result = $client->call('CheckAvailability', $params = array('RetailerID'=>retailerid,'BookID'=>$bookid,'Format'=>$format),$options);
//print $client->getWire(); //remove comment if you want to see soap xml
if (strlen($result->Book->Availability) > 0)
{
echo "<Book><Availability>".$result->Book->Availability."</Availability></Book>";
}
else
{
echo "<Error><Code>".$result->Error->Code."</Code>
<Description>".$result->Error->Message."</Description></Error>";
}
?>
NewTransaction Web Service
A Retailer (identified by its Authentication Parameters) can use this Web Service to generate encrypted download link for given BookID, Format (EPUB or PDF/A) and TransactionID.
Syntax:
URL: http://www.digitalmediareserve.com/webservices/retailers/
URN: http://www.digitalmediareserve.com/webservices/retailers/
SOAP Request:
<?xml version="1.0" encoding="UTF-8"?>
<SOAP-ENV:Envelope>
<SOAP-ENV:Header>
<Username>CommerceID</Username><Password>Password</Password></SOAP-ENV:Header>
<SOAP-ENV:Body>
<NewTransaction>
<RetailerID>RetailerID</RetailerID><TransID>20111101</TransID><BookID>BookID</BookID>
<Format>Format</Format>
</NewTransaction>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>
SOAP Response:
<?xml version="1.0" encoding="UTF-8"?>
<SOAP-ENV:Envelope>
<SOAP-ENV:Body>
<NewTransactionResponse>
<Books><Book><DownloadLink>Download Link for BookID</DownloadLink></Book></Books>
</NewTransactionResponse>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>
SOAP Response For Error:
<?xml version="1.0" encoding="UTF-8"?>
<SOAP-ENV:Envelope>
<SOAP-ENV:Body>
<NewTransactionResponse>
<Errors><Error><Code>ErrorCode</Code><Message>ErrorMessage</Message></Error></Errors>
</NewTransactionResponse>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>
PHP Code By PEAR-SOAP 0.12.0
<?php
require_once('SOAP/Client.php');
define('_URL','http://digitalmediareserve.com/webservices/retailers/');
define('_NS','urn:http://digitalmediareserve.com/webservices/retailers/');
define('retailerkey','<your retailer key>');
define('commerceid','<your commerce id>');
define('retailerid','<your retailer id>');
$client = new SOAP_Client(_URL); //Create Soap Client Object
$transid = 1002; //Your unique Transaction ID
$bookid = 28; //Unique eBook ID provided by DMR
$format = “epub or pdf”; //eBook Format
/*Create sh1 hash password by encrypting retailerid, bookid, format and transaction id by your retailer key*/
$stringpass = md5(commerceid).retailerid.$bookid.$format.$transid;
$password = hash_hmac("sha1",$stringpass,retailerkey);
$value = array('Username',md5(commerceid),_NS);
$client->addHeader($value);
$value = array('Password',$password,_NS);
$client->addHeader($value);
$options = array('namespace'=>_NS);
$options['trace'] = true; //true or false
//Call webservice
$result = $client->call('NewTransaction', $params = array('RetailerID'=>retailerid,'TransID'=>$transid,'BookID'=>$bookid,'Format'=>$format),$options);
//print $client->getWire(); //remove comment if you want to see soap xml
if (strlen($result->Book->DownloadLink) > 0)
{
echo "<Book><DownloadLink>".$result->Book->DownloadLink."</DownloadLink></Book>";
}
else
{
echo "<Error><Code>".$result->Error->Code."</Code>
<Description>".$result->Error->Message."</Description></Error>";
}
?>
ReGenerateDownloadLink Web Service
A Retailer (identified by its Authentication Parameters) can use this service to regenerate encrypted download link for given eBookId and Format (EPUB or PDF/A) and Transaction ID.
Syntax:
URL: http://www.digitalmediareserve.com/webservices/retailers/
URN: http://www.digitalmediareserve.com/webservices/retailers/
SOAP Request:
<?xml version="1.0" encoding="UTF-8"?>
<SOAP-ENV:Envelope>
<SOAP-ENV:Header><Username>CommerceID</Username><Password>Password</Password></SOAP-ENV:Header>
<SOAP-ENV:Body>
<ReGenerateDownloadLink>
<RetailerID>RetailerID</RetailerID><TransID>TransactionID</TransID><BookID>BookID</BookID>
<Format>Format</Format></ReGenerateDownloadLink>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>
SOAP Response:
<?xml version="1.0" encoding="UTF-8"?>
<SOAP-ENV:Envelope>
<SOAP-ENV:Body>
<ReGenerateDownloadLinkResponse>
<Books><Book><DownloadLink>Download Link for BookID</DownloadLink></Book></Books>
</ReGenerateDownloadLinkResponse>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>
SOAP Response For Error:
<?xml version="1.0" encoding="UTF-8"?>
<SOAP-ENV:Envelope>
<SOAP-ENV:Body>
<ReGenerateDownloadLinkResponse>
<Errors><Error><Code>ErrorCode</Code><Message>ErrorMessage</Message></Error></Errors>
</ReGenerateDownloadLinkResponse>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>
PHP Code By PEAR-SOAP 0.12.0
<?php
require_once('SOAP/Client.php');
define('_URL','http://digitalmediareserve.com/webservices/retailers/');
define('_NS','urn:http://digitalmediareserve.com/webservices/retailers/');
define('retailerkey','<your retailer key>');
define('commerceid','<your commerce id>');
define('retailerid','<your retailer id>');
$client = new SOAP_Client(_URL); //Create Soap Client Object
$transid = 1002; //Your Transaction ID
$bookid = 28; //Unique eBook ID provided by DMR
$format = “epub or pdf”; //eBook Format
/*Create sh1 hash password by encrypting retailerid, bookid,
format and transaction id by your retailer key*/
$stringpass = md5(commerceid).retailerid.$bookid.$format.$transid;
$password = hash_hmac("sha1",$stringpass,retailerkey);
$value = array('Username',md5(commerceid),_NS);
$client->addHeader($value);
$value = array('Password',$password,_NS);
$client->addHeader($value);
$options = array('namespace'=>_NS);
$options['trace'] = true; //true or false
//Call webservice
$result = $client->call('NewTransaction', $params = array('RetailerID'=>retailerid,'TransID'=>$transid,'BookID'=>$bookid,'Format'=>$format),$options);
//print $client->getWire(); //remove comment if you want to see soap xml
if (strlen($result->Book->DownloadLink) > 0)
{
echo "<Book><DownloadLink>".$result->Book->DownloadLink."</DownloadLink></Book>";
}
else
{
echo "<Error><Code>".$result->Error->Code."</Code>
<Description>".$result->Error->Message."</Description></Error>";
}
?>
Parameters
Name |
Description |
Username (mandatory) |
Identifies a Retailer. We need to pass md5 hash of CommerceID (Issued by Digital Media Reserve) in Username. |
Password (mandatory) |
We need to pass sh1 Hash code, used to validate the integrity of the retailer calling the web service in Password field. See codes ow to produce sh1 Hash code. |
RetailerID (mandatory) |
Identifies a Retailer. Digital Media Reserve assigned a unique retailer id to each retailer. |
TransID (mandatory) |
Retailer unique transaction id. Retailer can regenerate download link by this transaction id in future. |
BookID (mandatory) |
This BookID is provided by Digital Media Reserve for each eBook. |
Format (mandatory) |
The format of eBook: epub or pdf |
Error Codes & Description
Error Code |
Description |
INVALID_SOAP_REQUEST |
Invalid SOAP Request, Got Nothing! |
INVALID_SOAP_MESSAGE |
Invalid Soap Message. |
INVALID_HEADER |
Soap request header have blank parameter. |
MISSING_PARAMETER |
Your request is missing service parameter. |
INVALID_USERNAME |
Invalid input Parameter : Username. |
INVALID_PASSWORD |
Invalid input Parameter : Password. |
ACNT_NOT_APPROVED |
Your account approval is pending. |
ACNT_BLOCKED |
Your account has been blocked. |
RETAIL_ACNT_NOT_APPROVED |
Your retail account is pending. |
RETAIL_ACNT_BLOCKED |
Your retail account has been blocked. |
INVALID_RETAILER_ID |
Invalid Retailer ID. |
DUPLICATE_TRANSID |
Duplicate Transaction ID. |
NOT_AVAILABLE_FOR_PURCHASE |
eBook not available for purchase. |
ERROR_IN_LINK_GENERATION |
Error in Link Generation. |
TRANSID_NOT_EXISTS |
Transaction id is not exists. |
INTERNAL_ERROR |
System is unable to process your request, Please try after some time. |