Skip to content
Cantook Cloud

Adding Purchases to Cantook Cloud

In order to add a customer’s purchase to Cantook Cloud, in addition to the Cantook Cloud Identifier explained in accounts association, the bookstore must acquire the following two pieces of information related to the purchase:

  • Its status document url
  • Its access token

With those three items, the bookstore can call the Delivery API.

The acquisition of the status document url and access token, and the Delivery API are explained in this section.

Acquiring status_document_url and access_token for new salesLink Icon

This section assumes the reader is familiar with the Cantook Hub’s sales declaration API and is already using it. This API has been slightly modified to allow the addition of sales to Cantook Cloud. The response when declaring a sale now contains a JSON document that must be used subsequently to add the sale to Cantook Cloud. The formula for declaring sales is the same as previously used, with a few additions:

  1. First, it is necessary to add the parameter output=json to the sales declaration in order to receive metadata about the sale instead of a simple message.

  2. The API now returns, within a JSON document, the two pieces of information that will be required when adding the purchase to Cantook Cloud in the following fields: status_document_url and access_token.

When a retail sale is successfully declared with the parameter output=json, in addition to the unchanged HTTP status code 201, the response body contains a JSON document which looks like this:

{
  "status": "created",
  "status_document_url": "https://www.entrepotnumerique.com/api/sales/11/status_document?sigid=1111111111&signature=1111111111111111111111111111111111111111111111111111111111111111",
  "access_token": "enqcs_111111111111111111111111111111111111111111111111111111111111111111111111"
}

In case of an error, there is no change; the response is provided in plain text format despite the output=json parameter.

Acquiring status_document_url and access_token for existing salesLink Icon

In addition to the Sales API modifications, a new API is now available to also allow a bookstore to fetch those same values for an already existing values.

Address: /api/organisations/[ ]/publications/[ ]/sales/[ ]?format=[ ]:organisation_id :publication_id :transaction_id :nature &customer_id=[ ]:customer_id

Method: GET

Parameters description:

NameRequired?Description
organisation_id Organisation’s id, provided by De Marque
publication_id Publication’s identifier (ISBN, EAN)
transaction_id The sale’s transaction’s unique identifier

Responses:

HTTP StatusValueDescription
200OKA JSON Document that includes status_document_url and access_token.
400The input does not follow the specification
401access_deniedThe caller does not have the necessary permissions for this call
404not_foundThe sale could not be found with the given parameters
503service_unavailableThe server is not available

Example response:

{
  "status_document_url": "https://www.entrepotnumerique.com/api/sales/11/status_document?sigid=1111111111&signature=1111111111111111111111111111111111111111111111111111111111111111",


  "access_token": "enqcs_111111111111111111111111111111111111111111111111111111111111111111111111"
}

Delivery APILink Icon

This section explains how the book is “pushed” into Cantook Cloud using its Delivery API

Requirements

Request

Method: POST

Authentication: Bearer Token

End-points

EnvironmentURL
Productionhttps://cantook-cloud-delivery-api-prod.demarque.workers.dev/hub
Staginghttps://cantook-cloud-delivery-api-staging.demarque.workers.dev/hub

Request payload

NameRequiredDescription
user_id The user identifier, as returned in the 'sub' claim of the OpenID Connect token.
status_document_url URL to obtain the Status Document from.
access_token The library bearer token.
test The sale is a test

Example

{
 "user_id": "4b1163f5-742c-4e42-9643-c4f875f3bf5f",
 "status_document_url": "https://enqc.hub.staging-northamerica.demarque.dev/api/sales/174/status_document?sigid=1687923692&signature=2e8a2f44f8fa8e3204b82355958b3c6rb27ff6f8a443a563f91eb4969cf6a780",
 "access_token": "enqcs_dJfRfyJWDHTpEooC4osdRrQP3NIA5b5so6gJfoFZBvjKarrZ1HfMI2AQzFZbMech8979080c"
}

Responses

Status codes

Status codeSuccessTypeDescription
200 -The publication already exists in the user’s bookshelf.
201 -The publication was properly added to the user’s bookshelf.
400 https://cloud.cantook.com/api/error/alreadyDeliveredThe sale has already been delivered to another user.
400 https://cloud.cantook.com/api/error/invalidInputThe input is not a valid json document or it does not respect the schema.
400 https://cloud.cantook.com/api/error/revokedThe sale has been revoked.
400 https://cloud.cantook.com/api/error/accountNotFoundNo account found for the identifier.
401 -The bearer token is missing or it’s no longer valid.
405 -The client is using any method other than POST.
502 https://cloud.cantook.com/api/error/contentProviderNetworkThere was a network problem with the content provider.
502 https://cloud.cantook.com/api/error/contentProviderAuthThere was an authorization problem with the content provider.
502 https://cloud.cantook.com/api/error/contentProviderThere was an unspecified problem with the content provider.

Response payload

{
  "identifier": "https://cloud.cantook.com/api/publication/d73e03b0-2c09-4f1a-a95a-94a8f1b949d8 "
}

Error handling

Error handling will be handled using the Problem Details JSON Object where:

  • we identify errors using “type” and the URI references listed in the previous section

  • along with “title” to communicate the error descriptions listed in the previous section

{
  "status": 400,
  "type": "https://cloud.cantook.com/api/error/duplicate ",
  "title": "The sale has already been delivered."
}