Documentation

Main principles and mechanisms

Definitions

Article

An article refers to all the attributes that describe a sellable entity (SKU) from your catalog.
Each article has mandatory attributes:

id: the identifier of the article

title: describing the title of the article

product_type: describing the taxonomy of the article

price: describing the price of the article

link: describing the link of the article

availability: describing its availability ("in stock" or "out of stock")

The attribute names are stored in lower case in our system.

Product

A product is a grouping of articles (sometimes called "variants" or "variations"). Articles can therefore be linked together by a common identifier item_group_id.

Offer

An offer designates an article/store_code combination allowing to model assortments, availabilities, prices, promotions,... according to the sales context.
A sales context can correspond to a physical or virtual store, a geography, a customer segment, etc.
The presence of an offer for an article generates its accessibility (visibility) in the store/sales context associated with it (store_code). An article sold in several stores/sales contexts therefore has several offers.
All offers constitute the notion of local inventory.
Each offer has mandatory attributes:

article_id: the identifier of the article to which the offer belongs

store_code: the code of the store or sales context

price: describing the price of the offer

availability: describing its availability ("in stock" or "out of stock")

The attribute names are stored in lower case in our system.

Import phase

During the import phase, Sensefuel will ingest your feeds (catalog and/or local inventory), evaluate the validity of your articles/offers, enrich and format them.

It is during this phase that your files will be read (during a realignment) or the modifications made via the Catalog API.

It is also during this phase that errors such as non-compliance with required specifications or errors related to configurations can be raised and transmitted by email. These errors are also viewable from the import monitoring screen available in the Sensefuel platform.

Compilation phase

This phase only occurs in case of success of the import phase. The compilation will be responsible for preparing your articles, products and offers for their exploitation in the Sensefuel platform as well as for updating data within search, navigation/ranking, recommendation, conversation,...

Catalog Management

The Catalog API enables you to manage your catalog of articles and your offers within the Sensefuel platform.

Via the Catalog API you are able to:

create, replace, update and delete your articles (possible via bulks)

create, replace, update and delete your offers (possible via bulks)

Consult an article or all your articles via pagination

Consult an offer or all offers attached to an article via pagination

Each modification on articles/offers triggers verifications.
You will consequently have direct feedback in case of validation errors on an article or an offer (example: missing price and/or availability), and it will therefore not be handled by sensefuel. In this case a 400 error is raised with details regarding validation errors. Thus, it is necessary to correct the article or offer in order to submit it again to the Catalog API.

It is impossible to submit offers concerning an article not created beforehand. A 404 error will be raised in this case.
Moreover, in case of deletion of an article, all its offers will also be deleted.

In the case of errors such as non-compliance with required specifications or errors related to configurations, alerts can be raised and transmitted by email. These errors are also viewable from the import monitoring screen available in the Sensefuel platform.

Import triggering

An import of your catalog is triggered when a modification (addition, update, replacement or deletion) is detected in the articles and offers of the latter. This import is triggered within 5 minutes following your modifications.

The import will prepare your catalog for the Sensefuel platform, applying numerous modifications and verifications. It will be followed by a compilation phase.

Only one import at a time can occur. If a new import were to be triggered while another is already in progress, it will wait for the end of the latter.

Realignment by file imports

It is possible to continue importing file feeds (from the Sensefuel platform) in order to realign your catalog and offers from time to time.

The configuration of file import is done from the import configuration screen.

When importing one or more files (file import frequencies being at your discretion), modifications produced by the Catalog API will be ignored and the entire catalog and offers will be realigned relative to this same file.

It is therefore not recommended to use the Catalog API during file imports. Sensefuel cannot indeed guarantee the absence of inconsistencies due to use of the Catalog API during a file realignment.

API Usage

Authentication

To use the API, you will need to request its activation to your Customer Success Manager and this will generate an API key necessary for your API calls.

This API key will be mandatory for each API call, and you must provide it in the X-API-KEY header.

If your key is no longer valid or not recognized, a detailed 401 error will be returned to the API user.

The API key is linked to a unique Sensefuel environment, characterized by a URL parameter siteUUID. In case of using a key that does not correspond to the environment used, a detailed 403 error will be returned.

Usage limitations (rate-limit)

The Catalog API limits by default the number of calls to 100 calls per minute.

Beyond that, a 429 error will be returned to the API user.

To prevent this, it is preferable:

to favor bulk routes (allowing to send several instructions via a single call)

to apply a reasonable delay before new attempts if an exceeding of the call limit occurs.

Article management

Consulting an article

To consult an article, one can retrieve a given article resource:

curl -XGET -X 'X-API-KEY: {YOUR_KEY}' https://api.sensefuel.live/catalog/{siteUUID}/articles/{articleId}

In case of success, the API will return a 200 response with the associated article in response.

An error can appear:

404: The article does not exist.

Creating an article

To create an article, one pushes a new article into the articles collection:

curl -XPOST -H 'Content-Type: application/json' -X 'X-API-KEY: {YOUR_KEY}' https://api.sensefuel.live/catalog/{siteUUID}/articles -d '{YOUR_ARTICLE}'

In case of success, the API will return a 201 response with the created article.

Several errors can appear:

400: The article contains invalid properties or is malformed.

409: The article already exists.

The properties required for creating an article are as follows:

id

title

product_type

price

link

availability

For more details on validations, please refer to the open api specifications.

Replacing an article

To replace an article in its entirety, one comes to replace an existing article:

curl -XPUT -H 'Content-Type: application/json' -X 'X-API-KEY: {YOUR_KEY}' https://api.sensefuel.live/catalog/{siteUUID}/article/{articleId} -d '{YOUR_ARTICLE}'

In case of success, the API will return a 200 response with the replaced article.

Several errors can appear:

400: The article contains invalid properties or is malformed.

404: The article does not exist.

The properties required for replacing an article are as follows:

title

product_type

price

link

availability

For more details on validations, please refer to the open api specifications.

Updating an article

To update an article, one can partially update a given article resource:

curl -XPATCH -H 'Content-Type: application/json' -X 'X-API-KEY: {YOUR_KEY}' https://api.sensefuel.live/catalog/{siteUUID}/articles/{articleId} -d '{YOUR_ARTICLE_UPDATE}'

In case of success, the API will return a 200 response with the modified article.

Several errors can appear:

400: The article update contains invalid properties or is malformed.

404: The article does not exist.

For more details on validations, please refer to the open api specifications.

Deleting an article

To delete an article, one can delete a given article resource:

curl -XDELETE -X 'X-API-KEY: {YOUR_KEY}' https://api.sensefuel.live/catalog/{siteUUID}/articles/{articleId}

In case of success, the API will return a 204 response without returns.

An error can appear:

404: The article does not exist.

Consulting all articles

To consult all articles, one can iterate on the articles resource collection, part by part:

curl -XGET -X 'X-API-KEY: {YOUR_KEY}' https://api.sensefuel.live/catalog/{siteUUID}/articles?limit=1000&offset=0

In case of success, the API will return a 200 response with a list containing articles. The list can be empty if no article is available.

By default, articles are returned in ascending order based on their identifier (id).

To consult all articles present, you must increment the offset provided with the limit. Iteration can then stop when a response contains an empty list.

The response carries a content-range header expressing the current position in iteration, and the total number of elements. Example: items 300-399/2500 indicates that the response contains 100 articles, from position 300 to 399, and that there are currently 2500 articles.

Note that the maximum number of articles can vary if insertions/deletions are performed in parallel, sometimes causing anomalies during pagination.

Offer management

Consulting an offer

To consult an offer, one can retrieve a given offer resource from a given article resource:

curl -XGET -X 'X-API-KEY: {YOUR_KEY}' https://api.sensefuel.live/catalog/{siteUUID}/articles/{articleId}/offers/{storeCode}

In case of success, the API will return a 200 response with the associated offer in response.

An error can appear:

404: The offer or associated article does not exist.

Creating an offer

To create an offer, one pushes a new offer into the offers collection of a given article:

curl -XPOST -H 'Content-Type: application/json' -X 'X-API-KEY: {YOUR_KEY}' https://api.sensefuel.live/catalog/{siteUUID}/articles/{articleId}/offers -d '{YOUR_OFFER}'

In case of success, the API will return a 201 response with the created offer.

Several errors can appear:

400: The offer contains invalid properties or is malformed.

404: The article does not exist.

409: The offer already exists for this article.

The properties required for creating an offer are as follows:

article_id

store_code

price

availability

For more details on validations, please refer to the open api specifications.

Replacing an offer

To replace an offer in its entirety, one comes to replace an existing offer:

curl -XPUT -H 'Content-Type: application/json' -X 'X-API-KEY: {YOUR_KEY}' https://api.sensefuel.live/catalog/{siteUUID}/article/{articleId}/offers/{storeCode} -d '{YOUR_OFFER}'

In case of success, the API will return a 200 response with the replaced offer.

Several errors can appear:

400: The offer contains invalid properties or is malformed.

404: The article or offer does not exist.

The properties required for replacing an offer are as follows:

price

availability

For more details on validations, please refer to the open api specifications.

Updating an offer

To update an offer, one can partially update a given offer resource:

curl -XPATCH -H 'Content-Type: application/json' -X 'X-API-KEY: {YOUR_KEY}' https://api.sensefuel.live/catalog/{siteUUID}/articles/{articleId}/offers/{storeCode} -d '{YOUR_OFFER_UPDATE}'

In case of success, the API will return a 200 response with the modified offer.

Several errors can appear:

400: The offer update contains invalid properties or is malformed.

404: The article or offer does not exist.

For more details on validations, please refer to the open api specifications.

Deleting an offer

To delete an offer, one can delete a given offer resource:

curl -XDELETE -X 'X-API-KEY: {YOUR_KEY}' https://api.sensefuel.live/catalog/{siteUUID}/articles/{articleId}/offers/{storeCode}

In case of success, the API will return a 204 response without returns.

An error can appear:

404: The article or offer does not exist.

Consulting all offers of an article

To consult all offers of an article, one can iterate on the offers resource collection of a given article, part by part:

curl -XGET -X 'X-API-KEY: {YOUR_KEY}' https://api.sensefuel.live/catalog/{siteUUID}/articles/{articleId}/offers?limit=1000&offset=0

In case of success, the API will return a 200 response with a list containing offers. The list can be empty if no offer is available.

By default, offers are returned in ascending order based on their store_code.

To consult all offers present, you must increment the offset provided with the limit. Iteration can then stop when a response contains an empty list.

The response carries a content-range header expressing the current position in iteration, and the total number of elements. Example: items 300-399/2500 indicates that the response contains 100 offers, from position 300 to 399, and that there are currently 2500 offers.

Note that the maximum number of offers can vary if insertions/deletions are performed in parallel, sometimes causing anomalies during pagination.
An error can appear:

404: The associated article does not exist

Bulk modifications on articles

In order to optimize the number of requests made, it is possible to mutualize several operations of the same type on articles via a bulk call:

curl -XPOST -H 'Content-Type: application/json' -X 'X-API-KEY: {YOUR_KEY}' https://api.sensefuel.live/catalog/{siteUUID}/articles/bulk -d '{YOUR_BULK}'

A bulk contains:

an operationType describing the type of operations to apply create, replace, delete, update

a list operations where each operation is composed of:

an article object describing the content of the article to apply, containing obligatorily an id property describing the identifier of the article.

The API will return in case of success a 200 response accompanied by a list of responses in the order of operations provided as input containing:

a status adopting 2 possible values, success or error

an article object containing the modified article and can be null in the case of a deletion operation

an error object (null in case of success) if the operation was in error

For each operation, the article object will be subject to the same validations as unit calls based on the operationType:

create: corresponds to the article creation route

replace: corresponds to the article replacement route

update: corresponds to the article update route

delete: corresponds to the article deletion route

Each operation in error will therefore be rejected by the Catalog API, and it is necessary to iterate on the bulk response to identify necessary corrections, correct them and replay them.

Note that a bulk on articles has a maximum size of 20 operations.

It is impossible to provide several operations concerning the same article. The API will return a 400 error and reject the entire bulk in this case.

Bulk modifications on offers

In order to optimize the number of requests made, it is possible to mutualize several operations of the same type on offers within a bulk call:

curl -XPOST -H 'Content-Type: application/json' -X 'X-API-KEY: {YOUR_KEY}' https://api.sensefuel.live/catalog/{siteUUID}/offers/bulk -d '{YOUR_BULK}'

A bulk contains:

an operationType describing the type of operations to apply create, replace, delete, update

a list operations where each operation is composed of:

an offer object describing the content of the offer to apply, containing obligatorily an article_id and store_code property describing the identifier of the article and context concerned by the offer.

The API will return in case of success a 200 response accompanied by a list of responses in the order of operations provided as input containing:

a status adopting 2 possible values, success or error

an offer object containing the modified offer, can be null in the case of a deletion operation

an error object (null in case of success) if the operation was in error

For each operation, the offer object will be subject to the same validations as unit calls based on the operationType:

create: corresponds to the offer creation route

replace: corresponds to the offer replacement route

update: corresponds to the offer update route

delete: corresponds to the offer deletion route

Each operation in error will therefore be rejected by the Catalog API, and it is necessary to iterate on the bulk response to identify necessary corrections, correct them and replay them.

Note that a bulk on offers has a maximum size of 500 operations.

It is impossible to provide several operations concerning the same offer. The API will return a 400 error and reject the entire bulk in this case.

Main principles and mechanisms#

Definitions#

Article#

Product#

Offer#

Import phase#

Compilation phase#

Catalog Management#

Import triggering#

Realignment by file imports#

API Usage#

Authentication#

Usage limitations (rate-limit)#

Article management#

Consulting an article#

Creating an article#

Replacing an article#

Updating an article#

Deleting an article#

Consulting all articles#

Offer management#

Consulting an offer#

Creating an offer#

Replacing an offer#

Updating an offer#

Deleting an offer#

Consulting all offers of an article#

Bulk modifications on articles#

Bulk modifications on offers#

Main principles and mechanisms

Definitions

Article

Product

Offer

Import phase

Compilation phase

Catalog Management

Import triggering

Realignment by file imports

API Usage

Authentication

Usage limitations (rate-limit)

Article management

Consulting an article

Creating an article

Replacing an article

Updating an article

Deleting an article

Consulting all articles

Offer management

Consulting an offer

Creating an offer

Replacing an offer

Updating an offer

Deleting an offer

Consulting all offers of an article

Bulk modifications on articles

Bulk modifications on offers