Introduction

This document is created for bookstores, publishers or any other store who wish to offer sales of e-books on its website.

List of web services

1. Catalog Synchronization

1.1 Full synchronization

1.2 Differential synchronization

1.3 Synchronisation of one publication

2 Sale and Download of a publication

2.1 Simulate a sale

2.2 Selling of a publication

2.3 Download a publication

2.4 Canceling a sale

2.5 Preorders

2.6 Obtaining the state of a download

2.7 Retrieving the Table of Content

3 Organisations

1. Catalog Synchronization

It is possible to update the e-book catalog by using the metadata obtained with the following API:

1. The API for a full synchronization of the catalog, which retrieves the complete metadata of all the publications.

2. The API for a differential synchronization of the catalog, which retrieves the complete metadata of the publications modified since the last synchronization or a precise date.

3. The API for a synchronization of one publication, which retrieve the complete metadata of the requested publication.

The retrieved metadata are divided in several files (ONIX or XML), each one of them containing the metadata of up to 50 publications.

1.1 Full synchronization

This API is used to retrieve the complete metadata of all the publications of the catalog.

It returns the first metadata file. To access the next files, you need to follow the URL indicated in the Link entity header of the HTTP response until you get a HTTP “404 Not Found” code.

Declaration

Address : /api/organisations/[organisation_id]/publications/full[.format]

Formats : onix, xml

Method : GET

Security : HTTP/BASIC (Username and password)

Parameters

organisation_id (Mandatory)

Organization number provided upon registration.

format (Optional)

Format of the files, onix or xml. The default value is onix.

Responses

200 : OK

The file was created with success. The Link entity header of the HTTP response provides an URL (Link: ; rel=next) to access the next file. You reach the end of the file list when you get a HTTP “404 Not Found” code.

401 : access_denied

Access denied to the resource.

404 : not_found

The organisation was not found.

415 : invalid_format

The requested format is not supported.

1.2 Differential synchronization

This API is used to retrieve the complete metadata of the publications modified since the last synchronization (full or differential) or a specified date. It is used to get regular updates.

If the number of changes to the publication is too great (HTTP 400 code), you need to use the full synchronization API.

It returns the first metadata file. To access the next files, you need to follow the URL indicated in the Link entity header of the HTTP response until you get a HTTP “404 Not Found” code.

Declaration

Address : /api/organisations/[organisation_id]/publications/delta[.format]

Formats : onix, xml

Method : GET

Security : HTTP/BASIC (Username and password)

Parameters

organisation_id (Mandatory)

Organisation number provided upon registration.

format (Optional)

Format of the files, onix or xml. The default value is onix.

from (Optional)

Date and time, ISO 8601 Basic format. If the parameter is omitted: returns the metadata of the publications that were modified since the last synchronization (full or differential). If the parameter is present: returns the metadata of the publications that were modified since the specified date and time.
Warning: the date and time must be equal or before the previous date and time used for the start of the last synchronisation

Responses

200 : OK

The file was created with success. The Link entity header of the HTTP response provides an URL (Link: ; rel=next) to access the next file. You reach the end of the file list when you get a HTTP “404 Not Found” code.

400 : too_many_results

The number of modifications is too great. Use the API for a full synchronization of the catalog.

401 : access_denied

Access denied to the resource.

404 : not_found

The organisation was not found or there was no modification.

415 : invalid_format

The requested format is not supported.

1.3 Synchronisation of one publication

This API is used to retrieve the complete metadata of a specific publication.

Declaration

Address : /api/organisations/[organisation_id]/publications/[isbn].[format]

Formats : onix, xml

Method : GET

Security : HTTP/BASIC (Username and password)

Parameters

organisation_id (Mandatory)

Organisation number provided upon registration.

isbn (Mandatory)

ISBN/EAN of the publication.

format (Mandatory)

Format of the files, onix or xml.

Responses

200 : OK

The metadata of the publication in onix or xml format.

401 : access_denied

Access denied to the resource.

404 : not_found

The publication or organisation was not found.

2. Sale and Download of Publications

The Platform's sales and download services answers the needs of three requirements :

1. Simulating a sale, to verify if the actual sale can be performed

2. Declaring an actual sale

3. Obtaining the download link

2.1 : Simulate a Sale

This web service validates if the sale would be recorded succesfully. Because many parameters are required and validated by the platform for a sale to be recorded successfully (price, protection, availability of the book on the Platform), we recommend that you check with this web service if the sale would work with the actual data you have in your catalog.

The sale is not recorded on the platform. You must use the Sale of a Publication API to record a valid sale.

Declaration

Address : /api/organisations/[organisation_id]/publications/[isbn]/sales/new

Method : GET

Security : HTTP/BASIC (Use your username and password)

Parameters

organisation_id : (Mandatory)

Your merchant number. This number is provided to you upon registration.

isbn : (Mandatory)

The publication's ISBN.

format : (Mandatory)

The publication's format (pdf/epub/mobi).

cost : (Mandatory)

The price of the sale in cents (e.g., $19.99 => 1999).

protection : (Mandatory)

The type of protection on the sold publication (none/watermark/acs4/acs4_timelimited/drm_drm_timelimited).

drm_type : (Optional)

The type of DRM applied on the sold publication (acs/lcp/urms).

country : (Mandatory)

The country which will be considered to validate the price of the publication. ISO 3166-1 Alpha-3 (can, fra, ita) or Alpha-2 (CA, FR, IT) formats.

cost_without_taxes : (Optional / Mandatory on Eden Livres)

Price, without taxes, in the country of the buyer, in cents (ex. : 19,99$ => 1999)

price_type : (Optional)

The ONIX price type used for cost validation. List 58, possible values: 01, 02, 03, 04, 41 and 42.

currency : (Mandatory)

The currency of the amount provided in 'cost'; used for cost validation. 3-letter ISO-4217 code.

Responses

200 : valid

The simulation was executed successfully.

400 : cannot_sell

You cannot sell this publication.

400 : missing_format

You did not enter the format.

400 : invalid_format

The selected format is not available for this publication.

400 : invalid_sale_parameters

cost, country, currency or price_type parameter is invalid.

400 : missing_cost

You did not enter the price.

400 : missing_protection

You did not enter the protection type.

400 : invalid_protection

This protection is not available for this format of the publication.

400 : invalid_country

The country code is invalid.

401 : access_denied

You do not have access to the resource.

404 : not_found

Your organization or the ISBN could not be found.

503 : service_unavailable

A problem has occured while connecting to the server.

Notes

In the case of a code 400 error, a vector containing the types of errors will be sent to you.

2.2 : Sale of a Publication

This web service records a sale in the Platform. The recorded sale links, for a transaction at a specific date, the merchant, the user and the digital file of a book in the Platform. The registration of this sale is necessary so that the user has access to the download of his / her book. The sale will appear in the sales statistics of the Platform for the publisher and the merchant.

Always validate the response code of the server at the call of this web service, because you should not use the Download a publication web service (2.3) if you have not received 201 "created".

When the sale is complete, you must save in your system the used parameters, to generate the correct download link in next step.

Declaration

Address : /api/organisations/[organisation_id]/publications/[isbn]/sales

Method : POST

Security : HTTP/BASIC (Use your username and password)

Parameters

organisation_id : (Mandatory)

Your merchant number. This number is provided to you upon registration.

isbn : (Mandatory)

The publication's ISBN.

format : (Mandatory)

The publication's format (pdf/epub/mobi).

cost : (Mandatory)

The price of the sale in cents (e.g., $19.99 => 1999).

protection : (Mandatory)

The type of protection on the sold publication (none/watermark/acs4/acs4_timelimited/drm/drm_timelimited).

drm_type : (Optional)

The type of DRM applied on the sold publication (acs/lcp/urms).

customer_id : (Mandatory)

Your client's unique ID number. Alphanumerical characters only ("-" and "_" also accepted).

transaction_id : (Mandatory)

The transaction / purchase basket's unique ID number. Multiple sales can be added to a basket, as long as they have the same unique ID number and are related to a single user. Alphanumerical characters only ("-" and "_" also accepted).

credit_card_prefix : (Optional)

4 first numbers of the credit card number used for payment. It allows the publisher to check if the territory constraints (determined by these 4 first numbers) are respected.

sale_state : (Optional)

The sale state. By default, a sale is always in "active" state, but it is possible to specify that the sale must be in "test" state using this parameter. Possible values: active, test, customer_service

country : (Optional)

The country which will be considered to validate the price of the publication. Value by default: the country of your organization. ISO 3166-1 Alpha-3 (can, fra, ita) or Alpha-2 (CA, FR, IT) formats.

aggregator : (Optional)

When a parent store makes a sale for one of it's child store, this field represents the ID of the parent store.

cost_without_taxes : (Optional / Mandatory on Eden Livres)

Price, without taxes, in the country of the buyer, in cents (ex. : 19,99$ => 1999)

price_type : (Optional)

The ONIX price type used for cost validation. List 58, possible values: 01, 02, 03, 04, 41 and 42.

currency : (Optional)

The currency of the amount provided in 'cost'; used for cost validation. 3-letter ISO-4217 code.

uname : (Mandatory only if protection is watermark)

First and last name of the user. The value of this parameter will appear in the text of the digital watermark that will be placed on the file. When this parameter is provided on Sale API call, the watermarking delay will be shortened on the download request (the download will begin as soon as the user clicks on the download button instead of waiting for the platform to generate the watermarked copy).

Responses

201 : created

The sale has been added successfully.

400 : cannot_sell

You cannot sell this publication.

400 : duplicate

The sale already exists.

400 : missing_format

You did not enter the format.

400 : invalid_format

The selected format is not available for this publication.

400 : missing_cost

You did not enter the price.

400 : missing_customer_id

You did not enter your client's unique ID number.

400 : missing_transaction_id

You did not enter the transaction's unique ID number.

400 : missing_protection

You did not enter the protection type.

400 : invalid_protection

This protection is not available for this format of the publication.

400 : invalid_sale_state

The sale state is invalid.

400 : invalid_country

The country code is invalid.

401 : access_denied

You do not have access to the resource.

404 : not_found

Your organization or the ISBN could not be found.

503 : service_unavailable

A problem has occured while connecting to the server.

Notes

1. Sales are by default invoiceable. However, while developing your solution, or at any later time, if you want to perform a test sale, simply add the sale_state=test parameter to the transaction call. As such, the download will work, but the sale will not appear in the sale statistics and the publisher will not bill you for this sale.

2. In the case of a code 400 error, a vector containing the types of errors will be sent to you.

2.3 : Download a publication

The download requires that you use a temporary script page on your server. This page will call the Download a publication API, and will then redirect the user's browser to the final download URL received in the response. This final download URL is time-limited.

Use the following web service when the user has requested the download of an e-book. The Platform will return a chronodegradable URL (valid for one minute). Do not post the URL to the user: you simply need to redirect the user's browser to this URL so that the download begins immediately and automatically.

Steps for downloading a file :

1. The user clicks on the link to download a book (from an email or confirmation page);

2. The merchant receives the request for download and uses the web service for downloading a publication (2.2). In return, he receives a chronodegradable URL for download;

3. The merchant automatically and instantly redirects the user to the received chronodegradable download URL;

4. Download starts.

Declaration

Address : /api/organisations/[organisation_id]/customers/[customer_id]/transactions/[transaction_id]/publications/[isbn]/download_links/[format]

Method : GET

Security : HTTP/BASIC (Use your username and password)

Parameters

organisation_id : (Mandatory)

Your merchant number. This number is provided upon registration.

customer_id : (Mandatory)

The client's unique ID number. Alphanumerical characters ("-" and "_" accepted).

transaction_id : (Mandatory)

The transaction / purchase basket's unique ID number.

isbn : (Mandatory)

The publication's ISBN/EAN.

format : (Mandatory)

The publication format (pdf/epub/mobi).

uname : (Mandatory)

First and last name of the user. The value of this parameter will appear in the text of the digital watermark that will be placed on the file.

Responses

200 : OK

Chronodegradable download URL (expires after 1 minute). Redirect user toward this URL.

400 : missing_transaction_id

You did not enter a transaction ID.

401 : access_denied

You do not have access to the resource.

404 : not_found

Your organisation could not be found.

2.4 Sales Cancelation

A refund can be performed when :

• the bookstore has the right to refund sales (a user permission needs to be enabled)

• the referred sale is found on the platform

• the file has not been download by the end user (i.e. the watermarked file or the .acsm licence file wasn't downloaded)

• the refund amount matches the sale cost

Déclaration

Adress : /api/organisations/[organisation_id]/publications/[publication_id]/sales/cancel

Method : POST

Security : HTTP Basic

Parameters

organisation_id : (Mandatory)

bookstore ID

publication_id : (Mandatory)

publication ISBN

customer_id : (Mandatory)

the customer_id of the referred sale

transaction_id : (Mandatory)

the transaction_id of the referred sale

amount : (Mandatory)

the amount must match the "cost" parameter value of the original sale

reason : (Optional)

optional, the reason for the refund, which will be shown to the publisher

Responses

200 : OK

The refund has been successfully performed and a token is provided as a receipt.

400 : refund_unauthorized

The refund is unauthorized because it has already been fulfilled by the end user.

400 : already_refunded

The refund was already refunded.

400 : cost_mismatch

The amount mismatches the "cost" from the original sale.

401

User authentication failed or user can't perform refunds.

404

The referred sale wasn't found.

2.5 Preorders

Stores can offer to their customers the possibility to purchase a publication in advance, before the official start of sale date. When a preorder is declared, the store must warn the warehouse with the preorder API. As soon as the publication becomes available for sale, a regular sale must be posted with the sales API. The customer identifier (customer_id) must match what was used to make the preorder. Download of the publication will be available as soon as the actual sale is declared on the platfom. The download can be initiated through the Download API.

Publications available for preorders

The following rules can be used in order to determine wich publications are available for preorders:

1. State is not available for sale:

2. <ProductAvailability>40</ProductAvailability>

3. Date from wich it is allowed to take preorders :

3. The expected start of sale date is indicated in the ONIX feed like this, always in the future :

Declaration

Adresse : /api/organisations/[organisation_id]/publications/[publication_id]/preorders

Mehod : POST

Security : HTTP/BASIC (User and password)

Parameters

organisation_id : (Mandatory)

Id of the organisation doing the sale

publication_id : (Mandatory)

Identifier (ISBN, EAN or custom key) of the publication

for : (Mandatory)

epub or pdf

customer_id : (Mandatory)

Customer id for the preorder

Responses

200 : created

The preorder was created.

401

User authentification error.

404

The publication was not found.

2.6 Obtaining the state of a download

This web service allows to know if the customer as downloaded a title or not.

Declaration

Address : /api/organisations/{organisation_id}/customers/{customer_id}/transactions/{transaction_id}/publications/{isbn}/formats/{format}/status

Parameters

All parameters of the URL should be the same that were used in the Sale of a publication web service

Response

The answer will be as follows:

Notes

The <fulfillment> tag tells you the state of download by the end user:

in the case of a watermark protection: complete and incomplete refers to start downloading file

in the case of ACS4 DRM protection: complete and incomplete refers to the activation of the licence in Adobe Digital Edition or other compatible software.

The remaining tags correspond to the information provided during the call to the service.

2.7 Retrieving the Table of Content

This web service returns the Table of Content for the specified publication, as an XML or JSON document.

Adress : /api/publications/[isbn]/toc.[xml|js]

Formats : XML or JSON

Method : GET

Security : HTTP/BASIC (Use your username and password)

Parameters

Name Mandatory Description

Responses

XML format :

JSON format :

[RETOUR]

3. Organisations

The publishers.json API returns the list of organizations that a store has agreements with. The structure of the returned json file is the following :

1. A list of publishers with a direct agreement (under publishers)

2. A list of distributors with an agreement (under distributors), including, for each, the list of publishers where that agreement applies (the publishers that have granted their distributors the management of their market).

Each organisation is described with the following fields :

- id (organisation id)

- name (organisation name)

- identifier (identifier or GLN)

- website (publisher's web site)

- logo (link to the image file stored on the platform)

Declaration

Address : /api/organisations/{id}/publishers.json]

Formats : JSON

Method : GET

Security : HTTP/BASIC (Utilisez votre identifiant et mot de passe)

Parameters

id : (Mandatory)

Identifier of the organisation

Format JSON :

{"publishers":[{"id":"ENQC7","name":"First Organisation Inc.","identifier":"7","website":"http:www.example.com","logo":"http://assets.example.com/logo.jpg"}],"distributors":[{"id":"ENQC1","name":"My Big Distributor","identifier":"1","website":"http://www.example.com","logo":"http://assets.example.com/logo2.jpg","publishers":[{"id":"ENQC2","name":"A publisher under My Big Distributor","identifier":"2","website":"http://www.example.com","logo":"http://assets.example.com/logo3.jpg"}]}]}