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
2 Sale and Download of a publication
1. Catalog Synchronization
It is possible to update the e-book catalog by using the metadata obtained with the following API:
The API for a full synchronization of the catalog, which retrieves the complete metadata of all the publications.
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.
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
Warning: This is the new API of differential synchronization (which uses the GET method). The former API (which uses the POST method) is still available and its documentation can be found here: Former differential synchronization API
If it is still possible to use the former API, we encourage all of our users to give priority to the new API presented below.
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.
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 :
Simulating a sale, to verify if the actual sale can be performed
Declaring an actual sale
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
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.
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 :
The user clicks on the link to download a book (from an email or confirmation page);
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;
The merchant automatically and instantly redirects the user to the received chronodegradable download URL;
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:
State is not available for sale:
- <ProductAvailability>40</ProductAvailability>
Date from wich it is allowed to take preorders :
<PublishingDate>
<PublishingDateRole>09</PublishingDateRole>
<DateFormat>14</DateFormat>
<Date>20131107T000000-0500</Date>
</PublishingDate>
The expected start of sale date is indicated in the ONIX feed like this, always in the future :
<SupplyDate>
<SupplyDateRole>02</SupplyDateRole>
<DateFormat>14</DateFormat>
<Date>2012-10-25T00:00:00-04:00</Date>
</SupplyDate>
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:
<status>
<transaction>
<id>transaction_id</id>
<customer>
<id>customer_id</id>
</customer>
<publications>
<publication>
<format>
<nature>epub</nature>
<keytype>isbn</keytype>
<value>9780000000001</value>
<protectiontype>watermark</protectiontype>
</format>
<fulfillment>complete</fulfillment>
<refundable>false</refundable>
</publication>
</publications>
</transaction>
</status>
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 :
<chapters>
<chapter>
<page>1</page>
<title>Cover</title>
</chapter>
<chapter>
<page>7</page>
<title>Table of content</title>
</chapter>
<chapter>
<page>13</page>
<title>Chapter 1</title>
</chapter>
<chapter>
<page>24</page>
<title>Chapter 2</title>
</chapter>
...
</chapters>
JSON format :
[{"page":1,"title":"Cover"},{"page":7,"title":"Table of content"},{"page":13,"title":"Chapter 1"},{"page":24,"title":"Chapter 2"}...
[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"}]}]}