Using Snapplify Product API

This article outlines how to use product API to ingest a product feed of metadata (including cover imagery) to enable you to sell the Snapplify digital content catalogue via your existing retail platform.

This article is for DEVELOPERS. 😀

With Snapplify Product API, you’ll be able to give your customers more diversity, offering them access to an expansive and growing digital catalogue of content. 📚

Let’s get started

The Product Webhook provides an interface for programmatically receiving product data from Snapplify. You will need to implement this webhook in order to ingest Snapplify’s product feed for sale through your store’s front end. 



Webhook publish

The webhook is a POST request which is sent from the Snapplify catalogue server whenever products are added, updated or archived. The request consists of an HTTP BODY containing a JSON string with the product information. See the next section (Product data’) for the structure.

Additionally, an OAuth2 style authorisation header will be applied to the request, to prevent this public endpoint from being called by an unintended source. You should check this header. The auth token is a standard token supplied by the customer.

Example request made from catalogue service to a client using curl:

curl --request POST \
  --url https://example.com/action/push-asset \
  --header 'Host: example.com' \
  --header 'content-type: application/json' \
  --header 'authorisation: Bearer XXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXX' \
  --data '{ … product … }'

The API request is sent under the following circumstances:

Action

Description

product updated

When properties or images are updated.

Availability and price changes included.

product added

When a new product has been added.

product archive

When the product has been archived.

Product data

Below is a table of notes about the structure. Further down is a full example of the structure of the data that is sent in the API request.

Note the allow.

Property

Allow Empty

Description

takedown

No

Available for sale, true or false.

copyright

Yes

The product’s copyright message.

relatedIdentfier

Yes

Print ISBN.

subject

Yes

The product’s subject.

edition

Yes

The product’s edition.

description

Yes

The product’s description.

includedForSaleInCountries

Yes

can either be null or a comma separated string of ISO 3166-1 alpha-2 country codes.

language

Yes

The language of the product. ISO 3 letter code.

availability

No

The product sale availability.

AVAILABLE: Item is available for sale.

UNAVAILABLE: Item is unavailable for sale.

type

No

The type indicates the type of asset, LIBRARY, PRODUCT and RESOURCE. 

title

Yes

The product’s title.

archived

No

If true, this product should not be available for sale.

gradeLevel

Yes

The education level. This can be a string or a number.

prescribed

Yes

If this product has been selected for prescribed content.

subTitle

Yes

The product’s alternative or subtitle.

numberOfPages

Yes

The number of pages in the product. 

price

No

float or decimal (32,2). Can be 0.00 to indicate the item is free content. Always VAT excl.

imageUrl

No

The image URL is for a full-sized image. This should be downloaded, and not used to serve images from your front-end. Consider comparing the imageMd5Hash since this may not always change.

supplier

No

The product’s supplier’

currency

No

ISO 3 letter currency code’

categories

Yes

The product’s category’

assetUrl

No

The product’s asset file URL.

assetMd5Hash

No

The MD5 hash of the encrypted product source file.

identifier

No

The product identifier (ISBN).

imageUrlOriginal

No

The product’s image file URL.

seriesName

Yes

The product’s series name.

excludedForSaleInCountries

Yes

Can either be null or a comma separated string of ISO 3166-1 alpha-2 country codes.

assetUrlOriginal

No

The product’s original asset file URL.

subjects

Yes

The product’s subject code and label.

JSON product example

The following depicts the structure of a single product:

{

   "identifier":"9780323138727",

   "id":16519827,

   "takeDown":false,

   "copyright":"Elsevier Science",

   "relatedIdentifier":"9780122771613",

   "subject":null,

   "edition":null,

   "Description":"sample description.",

   "includedForSaleInCountries":"",

   "language":"English",

   "availability":"AVAILABLE",

   "type":"asset",

   "title":"Statistical Reasoning in Law and Public Policy",

   "archived":false,

   "gradeLevel":null,

   "prescribed":false,

   "subTitle":"Tort Law, Evidence and Health",

   "numberOfPages":925,

   "price":1462.5196294784546,

   "imageUrl":"https://img2.snapplify.com/... /9780323138727.jpg",

   "supplier":{

      "label":"Elsevier",

      "code":"supplierexample"

   },

   "currency":"ZAR",

   "categories":[

      {

         "id":35,

         "label":"Society & Social Sciences",

         "parent":null

      }

   ],

   "assetUrlOriginal":"https://assets2.snapplify.com/ ... /9780323138727.pdf",

   "imageUrlOriginal":"https://img2.snapplify.com/... /9780323138727.jpg",

   "assetUrl":"https://assets2.snapplify.com/... /9780323138727.pdf",

   "assetMd5Hash":"d298883594eb818bd17912ab0ee1e195",

   "imageMd5Hash":null,

   "seriesName":"Statistical Modeling and Decision Science",

   "excludedForSaleInCountries":"",

   "subjects":[

      {

         "code":null,

         "name":null

      }

   ],

   "format":"PDF",

   "bisacCode":"PSY039000",

   "embargoDate":null,

   "bicCode":"JMC JNC",

   "seriesNumber":"Volume 2",

   "drmEnabled":true,

   "fileSize":57589054,

   "fileMd5Hash":"d298883594eb818bd17912ab0ee1e195",

   "publisher":"Academic Press",

   "drmRestrictions":[

      {

         "limited":true,

         "type":"DEVICES",

         "value":"5"

      },

      {

         "limited":true,

         "type":"LICENSE_DAYS",

         "value":"0"

      }

   ],

   "publishedDate":"28-11-1988",

   "contributors":[

      {

         "firstName":"Gastwirth, Joseph L.",

         "lastName":""

      }

   ]

}

 

Errors

A webhook publish will be in error if you respond with anything other than a 200 HTTP Response.

The response body should be EMPTY.

You must respond within 15 seconds or the publish will be considered an error.

If you fail to respond, the message will be sent again after 90 seconds, 120 seconds,for a maximum of 15 minutes. The delay between messages is based on response times, some randomness and an exponential increase in the delay.

If a webhook client accumulates more than 20 failed attempts consecutively, the client will be marked as unstable, no further requests will be sent, and our system will flag this for our support team to make contact with you.

👉 Learn how to use Snapplify voucher API.

 

Need help? Use the live chat in the bottom right corner of your screen or email us at help@snapplify.com.