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:

  1. Dynamic Website with Search, Shopping Cart and Payment Gateway (developed in PHP, ASP or JSP with SOAP support).

  2. Website should be capable in calling SOAP based Web Services and should be able to receive their response.

  3. 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.