/
How to: Integrate web shop with CRS platform

How to: Integrate web shop with CRS platform

Owned by Volodymyr (Vova) Dolbnia
Last updated: Jun 18, 2024 by Troels Ejsing
22 min read

This article contains information about main flows that may be used in scope of web shop integration process.



We have type safe proxies for C#, typescript (JS), Kotlin, swift - this guide is however aimed at developers who do not implement for native IOS, Android or typescript (e.g. php developers).

If you need access to our proxies please contact us

General info

CRS public API is exposed via Swagger by following URL:

{host_url}/{microservice_name}/swagger/

where {host_url}- URL of CRS instance to integrate (for example, https://prod02shadow.cloudretailsystems.dk/),

{microservice_name} - name of microservice, which feature is supposed to be used. In scope of web shop integration following microservice names will be used:

"security",

"inventory",

"financial",

"media",

"actors"

Further I will provide only minimal request body that is needed for specific query/operation, extra request fields are exposed in Swagger UI.

Also it is worth to read following document in order to get short CRS API reference: https://mbsolutionsgroup.atlassian.net/wiki/spaces/MBSG/pages/44512/API

 

Basic information for all requests

HTTP word - POST

All requests should contain header Content-Type - application/json.

Work with Get[Something]Page requests



in CRS often used way  possibility to fetch some entities page-by-page. All requests for such cases use some generic properties:

[offset] - current page start (for first page - 0),

[count] - current page size,

[includeOverallEntryCount] - optional fields that indicates that along with entities of current page response should contain information about how many entities exists at all for filter and sort info described in request.

Following approach may be used to fetch all entities by filter page-by-page:

  • should be considered  [page_size]  (for example 100).

  • in first products page request [offset] should be 0, [count] should be [page_size] and [includeOverallEntryCount] should be true. Then in response value along with 100 entities of first page in property "entries" will be available property [overallEntryCount]" with entire count of products that can be fetched by this request parameters.

  • For next request [offset] should be amount of already fetched entities, page size should be the same and [includeOverallEntryCount]  should be false because we already know count for example: request 2: [offset] = 1*page_size, [count] = page_size, request 3: [offset] = 2*page_size, [count] = page_size, and so on till all products will be fetched.

I suggest to set [includeOverallEntryCount]  only for request of first page because for other pages with same filter overall count will remains immutable and its' calculation is time-consuming.

This offset/count management approach may be used in all cases when data should be fetched by pages.

Next will be enlisted set of operations that will be needed for web shop integration.

Authentication 

Login/get user token

Word: POST
URL: {host_url}/api/security/Authentication/Login
Minimal Request:

{ "userNameOrEMail": "your_username", "password": "your_password", "tenantDomainName": "your_tenant" }

In case of happy flow response will contain token   
Response:
All CRS responces contains errorOrValue property, which field [error] will be null in happy flow and field value will contain operation result.
In case of successful authentication  response will contain  ["token"] field that need to be used as [Authorization] header of all next requests.

Actors integration

Create actor

Actor creation flow is described in How to create/update Actor

Please note that customer need to have one of the customer roles (that have system name "CustomerPerson" or "CustomerOrganization");
Response will contain list of variants of product.

Get Actor

Word: POST
URL: {host_url}/api/actors/Actor/GetActor
Minimal request: