Retailer Operating Manual for e-books Wholesale Distribution and Fulfillment Services Volume 1.1a
Ingram Content Group, through its CoreSource and Lightning Source (LSI) companies, provides content fulfillment to industry partners via Ingram Partner Web Services (IPWS). This document describes partner integration with the e-book fulfillment services and how a developer would implement the services. The web services are RESTful (REST-based) to offer the optimal integration in terms of speed to market, security, and simplicity. Prior to implementing these services you must have an account with Lightning Source. The document attempts to be language agnostic, but example code is provided in Java and from the command line. In your environment, you will be able to harness these services with PHP, Ruby, JavaScript, Perl, Python, ASP, Java, C, C++, C#, VB, etc. This integration manual is a living document ; periodic updates will be distributed. 1 Definition of Terms The following terms are used throughout the document and are defined below: Customer/Consumer Any individual or entity to whom the Retail Partner sells content and for whom Ingram provides fulfillment. IPWS Ingram Partner Web Service. Retail Partner/Retailer The seller of the digital content. REST The style of software architecture for distributed hypermedia systems such as the World Wide Web. The term was introduced in 2000 by Roy Fielding, one of the principal authors of the Hypertext Transfer Protocol (HTTP) specification, and has come into widespread use in the Internet community. We recommend O Reilly s RESTful Web Services as a supplement for understanding RESTful architecture and integration. Secure Hash Algorithm (SHA-1) A 1-way hash designed by the National Security Agency (NSA) and published by NIST. It is used to encrypt data, such as a username, in such a way that it would be computationally infeasible to decrypt and identify the original data. Single Sign-on (SSO) A transaction approach that leverages an existing authentication mechanism. As a partner integrating with IPWS, you will use your existing account management and authentication mechanisms. Ingram only sees minimal, anonymous information necessary to fulfill transactions. Web Service A software system designed to support interoperable Machine to Machine interaction over a network. Web Services use Web APIs that can be accessed over a network, such as the Internet, and executed on a remote system hosting the requested services. The Ingram web services are RESTful and therefore use the HTTP specification.
2 DRM Formats Supported Ingram supports the following DRM formats: Adobe Digital Editions (EPUB and.pdf) encrypted using Adobe Content Server 4 (ACS4) Adobe standard (.pdf unencrypted) ereader (formerly Palm) encrypted using ereader DRM The specific format(s) available are determined by the Publisher. All DRM encryption/encapsulation is managed by Ingram for both title setup and title fulfillment. Note: While DRM suppliers and Ingram have taken significant steps to provide deterrents to piracy, none would suggest that the mechanisms deployed are unbreakable. Ingram cannot guarantee the security of DRM. 3 The Wholesale Distribution Model: Retail The Wholesale Distribution model is a wholesale buy/sell transaction between the Publisher and Ingram and Ingram and the Retailer. 1. Retailer takes an order from Consumer and performs commercial transaction. 2. Retailer provides a link to Consumer who in turn clicks on the link and sends a download request to Ingram. 3. Ingram prepares content in requested format and applies DRM as required for electronic delivery. 4. Ingram distributes content via the Internet to Consumer. 5. Ingram bills Retailer for the content and distribution services performed. 6. Ingram pays Publisher wholesale price of the content. (5) Invoice Retailer Publisher Ingram (6) Payment (3) Product (2) Order (1) Order/ Payment (4) digital e-book Customer
4 Fulfillment Services The Fulfillment Services model is a direct business relationship between the Publisher and Retailer. Ingram hosts the content for the publisher and distributes the content to the consumer on behalf of the Retailer. This model is also used for situations where publishers are retailing content from their own web sites. 1. Retailer takes an order from Consumer and performs commercial transaction. 2. Retailer sends the order via the Internet to Ingram, including the consumer s bill-to country. 3. Ingram prepares content in requested format and DRM required for electronic delivery 4. Ingram distributes content via the Internet to Consumer. 5. Ingram bills Retailer for transaction cost of distribution to Consumer. 6. Retailer pays Publisher for negotiated cost of the content. (5) Invoice Publisher (6) Ingram (3) Product (2) Order (4) digital e-book Retailer Customer (1) Order/ Payment 5 Integration Overview The IPWS is a collection of REST-based web services that securely provide product fulfillment to Retail Partners and their customers. In order to integrate the IPWS with your offerings, you will need to work with three primary services. Product Catalog Provides product metadata, including links to product images in multiple sizes, DRM usage rules, and support URLs. Territory File Provides allowed sales countries for each SKU. Publishers can optionally require retailers to enforce territory restrictions based on the Customer s credit card Bill to country. Fulfillment Web Service Receives fulfillment requests via post and provides embeddable code back from which your customer can click through to the download.
5.1 Catalog Integration Overview The Ingram e-book catalog includes all the metadata you need to make downloadable e-books available on your site. Titles, descriptions, authors, and all other available metadata can be found in the catalog. Most importantly, it includes the unique identifier required to make a download request to our fulfillment systems. Every IPWS fulfillment request must contain the unique identifier for the title and format requested. The simple steps for catalog integration are below: 1. Download catalog feed(s). 2. Import titles and image links. 3. Import the allowed sales countries. 4. Render available titles on your site. 5.2 Fulfillment Integration Overview Once titles are available in the catalog, and the catalog has been integrated, e-book fulfillment occurs through the Ingram Partner Web Service (IPWS). The fulfillment web services are Single Sign-on (SSO) and allow your users to stay on your site for the duration of the transaction. Ingram e-book fulfillment works as follows: 1. Your customer selects and purchases a title from a Retailer s website. 7. Once the purchase is complete, and while the consumer is still signed into your website (from the purchase transaction) the Retailer s server sends a request for fulfillment to IPWS. This request includes the unique SKU (the SKU field in catalog), the customer s Bill-to country, and any other parameters necessary for the fulfillment. a. If successful, IPWS returns an encrypted download URL to embed in your target page. b. If unsuccessful, IPWS returns an HTTP error code that tells the partner what the problem was. 1. The URL is embedded, user clicks link. 2. The encrypted URL opens the Ingram hosted Preparing page and starts the content download. 3. Once the download begins, the user is taken to the Ingram hosted Thank You page. 4. If the Retailer chooses, a callback message can be sent to them stating the result of the customer experience. 6 Technical Support Services Ingram provides 2nd-level technical support as part of the E-book Retailer Agreement. This function serves to backup customer support services provided by the Retailer. The Ingram Technical Support service is not intended to interface directly with e-book consumers, but to provide technical services behind the scenes. This section outlines the e-book technical support services provided by Ingram.
6.1 Technical Support Services Members of the Retailer s support team have direct access to Ingram s Technical Support services. These services are currently available during normal business hours Monday through Friday from 8 a.m. to 5 p.m. Central Standard Time to provide Retailers support in delivering e-books to the consumer. The services are there to handle problems with e-book downloads, questions concerning e-book content and other content delivery issues. 6.2 Common Issues Many consumer questions and problems are addressed on Ingram s e-book support web site, www.helpebook.com. This web site has information on typical issues that arise when downloading e-books. For instance, it includes details on how to obtain and install popular e-book reader software products such as ereader and Adobe Digital Editions. There is also a Frequently Asked Questions section and Tutorial. This is the best source for first level support and Retailers should either use this site or direct consumers to this site. If the Retailer s first level support is unable to resolve the issue then they may contact Ingram Technical Support for assistance with issue resolution. 6.3 Problem Reports Second level issues should be directed to Ingram s Technical Support team. To do this, send an e-mail to ebook.issues@ingramdigital.com. Please include the following information on download problems: E-book title SKU E-book Reference Number (the Order ID from the download URL) Nature of problem/question Date and time of problem(s) Error message received, if applicable Desired method of response and associated address/number (e-mail reply, phone, page) Problem reports received via this e-mail address will be addressed quickly and effectively. A response will be delivered back to the Retailer s support personnel within four business hours acknowledging receipt of the message and outlining the steps for resolution. It will be the responsibility of the Retailer to contact the consumer to bring the issue to resolution.
6.4 Hacker and Fraud Control There are times when attempts are made to hack into the Ingram e-book fulfillment site. In response to these attempts, Ingram may elect to block the originating IP address(es) of the hacker from further e-book download access. Ingram will not block IP addresses for issues that stem from the Retailer transaction, such as credit card fraud. It is the Retailer s responsibility to manage credit card risk and deny access to users who engage in fraudulent or criminal e-commerce activity. In addition, while Ingram, upon request of the Retailer, will disable future transactions originating from a particular location, Ingram will not issue a credit for any transaction that has already been fulfilled by Ingram. 7 Billing and Payment Procedures The month-end cutoff schedule for accounting purposes is based upon a four/four/five-week monthly cycle. The reporting of processed business transactions, compensation for services and the reimbursement of expenses to Lightning Source (LSI) are cut-off each accounting month on this schedule. This schedule is published each new calendar year, and is available in November of the current year from the Retailer s assigned Account Manager. Retailers who currently have an active account in good standing with LSI are invoiced weekly for titles sales and fulfillment services. Remittance is due 30 days from the end of the month in which the invoice is dated. Retailers who do not have an account or are not in good standing with LSI must submit a credit application for approval prior to ID initiating any integration or e-book distribution services. LSI may request payment in advance via a cashier s check based on the credit standing of the Retailer.