txtr (1.22.2) release date: 09:57 02.02.2012
The txtr Catalog contains hundreds of thousands of commercial eBook titles in EPUB or PDF. API users can buy these titles directly from txtr, but they can also implement clients that sell titles under their own brand, in which case the Reaktor will take care of everything from sending out receipts to storing Adobe ACSM files in an end-user's personal vault.
Clients can access the txtr Catalog through the Reaktor API. If you don't want to start implementing txtr Catalog integration right away, but are merely interested in what the txtr Catalog actually contains, please do get in contact with our sales people, who can provide you with a recent catalog export in an Excel-friendly format.
The live catalog is sliced into user natures, which are basically independent catalog configurations for specific countries or txtr's white-label customers. Every txtr user has a user nature that determines what catalog she sees when browsing and searching. Depending on the user nature, set when the user is created, catalog contents will be different, prices will be in local currencies, and may vary from user nature to user nature.
You can create a new user for accessing a specific catalog by calling IWSUserMgmt.createUser. The last parameter is the user nature of the new user. For instance, txtr's German catalog can be reached by users with the nature "txtr.de". (Nature names are not domain names, but consist of a normalized name of the commercial entity selling the content and the country the content is meant to be sold in.)
Once you have a user with the correct nature and are authenticated as that user, you can browse the catalog by category using the IWSContentCategoryMgmt and IWSDocMgmt interfaces.
Interesting methods are:
IWSContentCategoryMgmt.getContentCategoryRootForUser - gives you the root category and n levels of subcategories.
IWSDocMgmt.getDocumentsInContentCategory - gives you the actual eBook objects ("documents") in a category.
You can also search for eBooks in the catalog using the IWSSearchDocument interface:
IWSSearchDocument.createBlockingSearch - this is a standard Reaktor API search. For searching catalog documents, supply com.bookpac.archive.search.sources.local.shop as the only source to be searched.
For buying books through the Reaktor API, you need to do two things: Construct a basket and submit payment information. Depending on the user nature (see above for more information) of the user that checks out, submitting payment information can be very different. Baskets contain information on how this is done, but typically, there is a minimal amount of customization to be done for each user nature.
To construct a basket, call IWSShopMgmt.getNewBasket The basket marker parameter is to identify your kind of client. Use short, lowercase markers. For instance, txtr iPhone Apps use "iphone" as a basket marker. The newly constructed basket will already contain information on payment methods that may already be authorized for the current user (so she wouldn't have to submit any new payment data), and payment properties to indicate how payment data would have to be submitted.
To add an eBook to the basket, call IWSDocMgmt.changeDocumentBasketPosition with the basket's and the eBook's id. (The quantity field should always be 1.)
To check out a basket (once payment data has been submitted or the list of authorized payment method contains at least one entry), call IWSShopMgmt.checkoutBasket Basket checkout is atomic and will block until either the checkout succeeded or was cancelled. By design, failed checkouts will be rolled back completely (no vault content created, no financial transactions made.)
The result will contain information on the new documents that have been created in the user's vault. For eBooks without DRM, binaries can be downloaded through the usual txtr Reaktor download facilities. For eBooks under Adobe DRM, clients can export the ACSM files needed for fulfillment in an Adobe RMSDK-based piece of software, or Adobe Digital Editions. The ACSM file can be accessed like this:
http://txtr.com/delivery/document/$docID/metadata/com.bookpac.exporter.fulfillmenttoken?token=$token