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.