NAV

Introduction

Welcome to the Open Connector API Documentation.

Layers

The API is devided into two layers: open and commercial.

Authentication

The Open Connector API uses two different type of authorizations.

  1. API Token
  2. JWT

API Token

Authentication example:

curl "api_endpoint_here" \
    -H "X-API-TOKEN: {{apiToken}}"

API Tokens (or "keys") are used to access the open and the commercial layer. A commercial key has access to both layers and the open key only has access to the open layer.

All keys can be (and should be) connected to a Commercial Entity.

The API Token is a UUIDv4 string.

To authorize with the API Token just send it within the X-API-TOKEN header with each call.

X-API-TOKEN: 6b8ec515-c163-4e1e-b082-2a26de96ac09

JWT

Authentication example:

curl "api_endpoint_here" \
    -H "Authorization: Bearer {{jwt}}"

JWT is used to authenticate towards the Commercial User SDK endpoints (except User Registration where a commercial API Token is required).

The JWT is sent using Bearer Authentication and is valid for 12 hours.

Open Layer

The following functions are available in the open layer.

Chip : Get Information

Call:

$curl "/api/open/chip/{{chipId}}" \
    -H "X-API-TOKEN: {{apiToken}}"

200 OK Response:

{
    "id": "c99b339f-719c-4228-b02e-3e68b1c652a6",
    [...]
    "_beta": {
        "viewUrl": "http://example.com/beta/webview/wardrobe/c99b[...]"
    }
}

The chip id read from the NFC is sent to the API which returns the availble open data.

BETA

During beta a _beta section is also returned with a viewUrl value which can be used to update the webview. The loaded webview will show the garment page with all the available information.

Open : Item

Get Item Information

Call:

$curl -X GET "/api/open/item/{{itemId}}" \
    -H "X-API-TOKEN: {{apiToken}}"

200 OK Response:

{
    "id": "1ecfa4db-0b65-649a-87d1-937f2b275ecc",
    "created": "2022-07-02T21:26:52.000000Z",
    "updated": "2023-05-04T10:11:36.855019Z",
    "sku": "SKU001",
    "commercialEntity": {
        "id": "1ecfa4d6-4799-6344-8396-d346e336e775",
        "name": "Company AB"
    },
    "type": {
        "id": "1ecfa4d9-8684-6eb6-8514-d54d3c5555be",
        "name": "Hat",
        "key": "hat"
    },
    "name": "Item 001",
    "description": "",
    "materialData": [
        {
            "id": "01880f5a-199e-7c1e-aa17-a303f7577cfa",
            "materialDataType": {
                "id": "01880f55-df4d-75bb-9385-9759c0e2fa11",
                "name": "Polyester",
                "key": "polyester"
            },
            "value": "100"
        }
    ],
    "metaData": [
        {
            "id": "0187e36c-23e0-7ac2-8fea-05767d910b62",
            "metaDataType": {
                "id": "0187e367-0dc1-747b-8c76-f32126b21bc7",
                "name": "Color",
                "key": "color"
            },
            "value": "Black"
        }
    ],
    "sustainabilityData": [
        {
            "id": "0187e89b-119f-7ce8-8bcd-2a2ef1903467",
            "sustainabilityDataType": {
                "id": "0187e592-3105-7d26-854e-11da8886fca9",
                "name": "Can be worn (minimum)",
                "key": "can-be-worn-min"
            },
            "sustainabilityDataValueType": {
                "id": "0187e59a-d7c1-7ead-a71c-5b76e0bb9e21",
                "name": "Times",
                "key": "times",
                "shortName": "Times"
            },
            "value": "115"
        }
    ],
    "images": [
        {
            "id": "01881e4e-ffb1-7ec7-8df5-9b1fc800ff31",
            "created": "2023-05-15T07:27:53.777390Z",
            "type": {
                "id": "01881e46-5830-7fdc-9272-37a6d666b781",
                "name": "Main",
                "key": "main"
            },
            "fileName": "LM181L29_002_01_e.jpeg",
            "mimeType": "image/jpeg"
        }
    ]
}

Get open layer information about an item.

Item Parameters

Parameter Type Description
id string The Commercial Item Unique identifier.
created datetime When the item was created.
updated datetime, null When the item was updated last. Or null if never.
sku string Item SKU.
commercialEntity object The Commercial Item that is the creator/publisher of the item.
type object The Item Type object.
name string Item name.
description string Longer description. Max 500 characters, no HTML, line breaks allowed.
materialData array An array of Material Meta Data objects.
metaData array An array of Item Meta Data objects.
sustainabilityData array An array of Item Sustainability Data objects.
images array An array of Item Image objects.

Error Codes

If the response is not 200 OK the response code and the response errorCode should be one of the following:

Response code Error code Description
400 ITEM_NOT_FOUND Item not found. Check the id and try again.
500 UNKNOWN Unknown technical error.

Material Data Parameters

Parameter Type Description
id string Unique identifier.
materialDataType object Material data type object.
value integer null

Material Data Type Parameters

Parameter Type Description
id string Unique identifier.
name object Material data type name.
key string Unique text id.

Meta Data Parameters

Parameter Type Description
id string Unique identifier.
metaDataType object Meta data type object.
value string String value.

Meta Data Type Parameters

Parameter Type Description
id string Unique identifier.
name object Meta data type name.
key string Unique text id.

Sustainability Data Parameters

Parameter Type Description
id string Unique identifier.
metaDataType object Sustainability data type object.
value string String value.

Sustainability Data Type Parameters

Parameter Type Description
id string Unique identifier.
name object Sustainability data type name.
key string Unique text id.

Item Sustainability Data Value Parameters

Parameter Type Description
id string Unique identifier.
name object Sustainability data type name.
shortName string Short version of the name.
key string Unique text id.

Item Image Parameters

Parameter Type Description
id string Unique identifier.
created datetime When the image was uploaded.
fileName string The file name for the original uploaded image.
mimeType string Image mime type.
type object The Item Image Type object.

Item Image Type Parameters

Parameter Type Description
id string Unique identifier.
name object Image type name.
key string Unique text id.

Commercial Layer

The commercial layer of the API is sectioned into different SDKs for different features you can use.

Most endpoints within the Commercial Layer requires JWT authorization with an authenticated Commercial User. To authenticate a Commercial User you need an API token in the commercial layer.

Commercial User

The Commercial User SDK gives access to:

Each registered user can only be read by the same Commercial Entity that created it.

Commercial Item

Items are created into the open layer by a Commercial Entity. This way an Item is also always connected to a Commercial Item. This SDK is required for Item creation.

The open Item data can be read via the open layer endpoints, but also through endpoints specifically for the Commercial Item.

The Commercial Item SDK also gives access to:

The Commercial Item data can only be read by the same Commercial Entity that created it.

CMS

The CMS SDK gives access to:

The CMS data can only be read by the same Commercial Entity that created it.

Init Commercial Entity APP Call

Call:

$curl -X GET "/api/commercial/init" \
    -H "X-API-TOKEN: {{apiToken}}" \
    -H "Content-Type: application/json"

200 OK Response:

{
    "webviewUrl": "https://example.com/app/webview/",
    "wardrobeUrl": "https://example.com/app/webview/wardrobe/",
    "privacyUrl": "https://example.com/app/webview/privacy/"
}

This is a "init" call made specifically for APP integrations. An app can call this to get relevant information about the commercial entity environment based on the API Token.

SDK : Commercial User

Read here for information about what is included within the Commercial User SDK.

User Registration

Call:

$curl -X POST "/api/commercial/user/register" \
    -H "X-API-TOKEN: {{apiToken}}" \
    -H "Content-Type: application/json" \
    -d "{{jsonInput}}"

JSON Input:

{
    "email": "[email protected]",
    "password": "plaintext123",
    "name": "John Doe"
}

200 OK Response:

{
    "id": "1ecf935c-5347-6a32-b038-0b9895eb72e3",
    "email": "[email protected]",
    "name": "John Doe",
    "created": "2022-06-21T16:02:22+0000"
}

Error Response:

{
    "errorCode": "INVALID_INPUT",
    "errorMessage": "Invalid input",
    "errorFields": [
        "email",
        "password"
    ],
    "publicErrorMessage": [
        "email": "This value is not a valid email address.",
        "password": "This value should not be blank."
    ],
}

[POST] /api/commercial/user/register

For user registration (and login) the API call needs an API Token with commercial layer access.

Each following User API call requires the JWT.

User Parameters

Parameter Type Description
id * string Unique identifier.
email string Max 255 characters.
name string Max 255 characters.
created * datetime When user was registered.
password + string API has no rules or limitations for password. Can't be empty on registration.

* Read only.

+ Insert only.

Error Codes

If the response is not 200 OK the response code and the response errorCode should be one of the following:

Response code Error code Description
400 EMAIL_DUPLICATE E-mail is already registered.
500 UNKNOWN Unknown technical error.

Signin with Apple

Call:

$curl -X POST "/api/commercial/user/signin-apple" \
    -H "X-API-TOKEN: {{apiToken}}" \
    -H "Content-Type: application/json" \
    -d "{{jsonInput}}"

JSON Input:

{
    "token": "[...]"
}

200 OK Response:

{
    "token": "[...]",
    "password": "P5wZ7itfRDGMzhm
}

Error Response:

{
    "errorCode": "APPLE_TOKEN_INVALID",
    "errorMessage": "Missing apple token",
    "publicErrorMessage": "Sign in with Apple failed, please try again"
}

[POST] /api/commercial/user/signin-apple

For use in iOS Application when implementing "Sign in with Apple". The API call needs an API Token with commercial layer access.

Send in the Apple JWT token and on successfull validation a user is created (if it does not already exist), a new password is set, and a JWT token for the logged in user is returned togheter with the new password.

The new password can be used to store in secure storage within the app to implement a "remember me" function.

Signin Parameters

Parameter Type Description
token string The JWT token returned from Apple.

Error Codes

If the response is not 200 OK the response code and the response errorCode should be one of the following:

Response code Error code Description
400 MISSING_APPLE_TOKEN The token input is missing or empty.
400 MISSING_APPLE_AUTH_KEYS Could not retrieve the public keys from Apple to validate the JWT.
400 INVALID_APPLE_AUTH_KEYS Error when retrieving the public keys from Apple.
400 INVALID_APPLE_TOKEN_KID Unable to read "kid" from the token input.
400 APPLE_TOKEN_INVALID Unable to validate the JWT from Apple. This could be due to a range of issues like expiration.
500 UNKNOWN Unknown technical error.

User Login

[POST] /api/commercial/user/login

Call:

$curl -X POST "/api/commercial/user/login" \
    -H "X-API-TOKEN: {{apiToken}}" \
    -H "Content-Type: application/json" \
    -d "{{jsonInput}}"

JSON Input:

{
    "email": "[email protected]",
    "password": "plaintext123"
}

200 OK Response:

{
    "token": "[...]"
}

Error Response:

{
    "code": 401,
    "message": "No API token provided"
}

For user login (and registration) the API call needs an API Token with commercial layer access.

Each following User API call requires the JWT.

Login Parameters

Parameter Type Description
username string The username (e-mail).
password string The password in plain text.

Error Codes

For login, the error response is not formatted as the other API endpoints. The response contains "code" and "message".

Code is usually 401, unauthorized, and the message is not intended for the end user but can be used to check the error.

If username or password is missing all togheter, or if the data is not sent as application/json the error code can be 404.

(Better error message is planned).

Error message Description
No API token provided. X-API-TOKEN header missing or empty.
Invalid API token provided. X-API-TOKEN is not a valid token. Token can be invalid format, not the right layer, or not a real token at all.
Invalid credentials. Username or password missmatch.

Request Password Reset

[POST] /api/commercial/user/password-reset/request

Call:

$curl -X POST "/api/commercial/user/password-reset/request" \
    -H "X-API-TOKEN: {{apiToken}}" \
    -H "Content-Type: application/json" \
    -d "{{jsonInput}}"

JSON Input:

{
    "email": "[email protected]"
}

200 OK Response:

{
    "success": 1
}

Error Response:

{
    "errorCode": "REQUEST_EMAIL_MISSING",
    "errorMessage": "Missing e-mail input",
    "publicErrorMessage": "You must enter a valid e-mail address"
}

Request Parameters

Parameter Type Description
email string The user e-mail address (username).

Error Codes

If the response is not 200 OK the response code and the response errorCode should be one of the following:

Response code Error code Description
400 INVALID_INPUT_DATA E-mail missing.
400 REQUEST_EMAIL_MISSING Invalid e-mail.
500 UNKNOWN Unknown error.

Confirm Password Reset

[POST] /api/commercial/user/password-reset/confirm

Call:

$curl -X POST "/api/commercial/user/password-reset/confirm" \
    -H "X-API-TOKEN: {{apiToken}}" \
    -H "Content-Type: application/json" \
    -d "{{jsonInput}}"

JSON Input:

{
    "email": "[email protected]",
    "code": "114155"
}

200 OK Response:

{
    "token": "[...]"
}

Error Response:

{
    "errorCode": "PASSWORD_RESET_CODE_INVALID",
    "errorMessage": "Missing code input",
    "publicErrorMessage": "You must enter a valid code"
}

Request Parameters

Parameter Type Description
email string The user e-mail address (username).
code string The password reset code.

Error Codes

If the response is not 200 OK the response code and the response errorCode should be one of the following:

Response code Error code Description
400 INVALID_INPUT_DATA E-mail or code missing.
400 REQUEST_CODE_MISSING Invalid code, for example invalid format.
400 REQUEST_EMAIL_MISSING Invalid e-mail.
400 PASSWORD_RESET_CODE_INVALID Not the right code for the password reset confirmation.
400 PASSWORD_RESET_CODE_EXPIRED Password reset code expired.
500 UNKNOWN Unknown error. But can also be if email is missing or user not found.

Get User Profile

[GET] /api/commercial/user/profile

Call:

$curl -X GET "/api/commercial/user/profile" \
    -H "Authorization: Bearer {{jwt}}" \
    -H "Content-Type: application/json"

200 OK Response:

{
    "id": "018823c1-7115-74c6-a4c2-b70e79a0e1ec",
    "email": "[email protected]",
    "name": "John Doe",
    "created": "2023-05-16T08:50:59.879683Z"
}

Error Response:

{
    "code": 401,
    "message": "JWT Token not found"
}

User Profile Parameters

Field Data type Description
email string 255 User E-mail
name string 255 User real name
created * string Registration date

* Read only.

Update User Profile

[POST] /api/commercial/user/profile

Call:

$curl -X POST "/api/commercial/user/profile" \
    -H "Authorization: Bearer {{jwt}}" \
    -H "Content-Type: application/json" \
    -d "{{jsonInput}}"

JSON Input:

{
    "password": "new-password-123!"
}

200 OK Response:

{
    "id": "018823c1-7115-74c6-a4c2-b70e79a0e1ec",
    "email": "[email protected]",
    "name": "John Doe",
    "created": "2023-05-16T08:50:59.879683Z"
}

To update the user profile you only need to send the parameters with new values.

User Profile Parameters

Field Data type Description
email string 255 User E-mail (unique within the Commercial Entity)
name string 255 User real name
password string 255 User password (only submit if it should be changed)

Create Chip Connection

Call:

$curl -X POST "/api/commercial/user/chip-connection" \
    -H "Authorization: Bearer {{jwt}}" \
    -H "Content-Type: application/json" \
    -d "{{jsonInput}}"

JSON Input:

{
    "chipId": "31fea044-d1c3-45ea-9353-bd0f63975556",
    "location": {
        "lat": 59.327249034, 
        "lng": 18.071655529
    }
}

200 OK Response:

{
    [...]
    "_beta": {
        "viewUrl": "http://example.com/beta/webview/wardrobe/c99b[...]"
    }
}

To register the ownership of an Item the chip needs to be registerd twice, from roughly the same location. The second registration have to be made after a period of 24 hours.

The API call is the same, both times.

Error Codes

If the response is not 200 OK the response code and the response errorCode should be one of the following:

Response code Error code Description
400 WAITING Chip has been registered but can't yet be verified.
403 REGISTERED Chip is registered with another User.
400 MISSING_INPUT_CHIP_ID Unspecified input data missing.
400 MISSING_INPUT_DATA Chip id missing.
400 INVALID_INPUT_CHIP_ID Chip id invalid.

Get Chip Connection Information

Call:

$curl -X GET "/api/commercial/user/chip-connection/{{chipId}}" \
    -H "Authorization: Bearer {{jwt}}" \
    -H "Content-Type: application/json"

200 OK Response:

{
    "id": "1ed02fa3-582f-64bc-8bc1-b92c86793ea4",
    "created": "2022-07-13T22:21:58.110345Z",
    "chip": {
        "id": "1ecfa4ee-ee63-619e-a2ae-c57db78e1afb",
        "created": "2022-07-02T21:35:46.000000Z",
        "item": {
            "id": "1ecfa4db-0b65-649a-87d1-937f2b275ecc",
            "created": "2022-07-02T21:26:52.000000Z",
            "sku": "SKU001",
            "commercialEntity": {
                "id": "1ecfa4d6-4799-6344-8396-d346e336e775",
                "name": "Company AB"
            },
            "type": {
                "id": "1ecfa4d8-efae-64ec-b473-71e217177f07",
                "name": "Garment"
            },
            "name": "SKU 001"
        }
    },
    "verified": null,
    "verifiable": "2022-07-14T22:21:58.110345Z",
    "isVerified": false,
    "status": "ONGOING_CONN",
    "_beta": {
        "viewUrl": "http://example.com/beta/webview/wardrobe/1ed0[...]"
    }
}

Get information about a chip connection, if none exists or the status of a created connection.

Chip Connection Parameters

Parameter Type Description
id string Unique identifier.
created datetime When chip connection was initated, first created.
chip object Chip object.
verified datetime null
verifiable datetime null
isVerified bool Is chip connection verified.
status string Chip connection status: ONGOING_CONN, VERIFIED_CONN.
timeLeft int Seconds left until verifiable (or 0 if verified).

Error Codes

If the response is not 200 OK the response code and the response errorCode should be one of the following:

Response code Error code Description
400 MISSING_INPUT_DATA Unspecified input data missing.
400 MISSING_INPUT_CHIP_ID Chip id missing.
400 INVALID_INPUT_CHIP_ID Chip id invalid.
400 NO_CONN_FOUND No connection for the authorized user to the chip found.

Get Chip Connections

Call:

$curl -X GET "/api/commercial/user/chip-connections" \
    -H "Authorization: Bearer {{jwt}}" \
    -H "Content-Type: application/json"

200 OK Response:

[
    {
        "id": "1ed02fa3-582f-64bc-8bc1-b92c86793ea4",
        [...]
    }
]

Get a list of all the chip connections a user has.

SDK : Commercial Item

Read here for information about what is included within the Commercial Item SDK.

Each call within the Commercial Item SDK requires an authenticated Commercial User and authorization using the JWT token.

Get Commercial Item Information

Call:

$curl -X GET "/api/commercial/item/{{itemId}}" \
    -H "Authorization: Bearer {{jwt}}" \
    -H "Content-Type: application/json"

200 OK Response:

{
    "id": "1ed5fa65-1c8d-6534-8a15-4b3a1388b63f",
    "created": "2022-11-08T20:45:45.967933Z",
    "updated": null,
    "openItem": {
        "id": "1ecfa4db-0b65-649a-87d1-937f2b275ecc",
        "created": "2022-07-02T21:26:52.000000Z",
        "updated": "2023-05-04T10:11:36.855019Z",
        "sku": "SKU001",
        "commercialEntity": {
            "id": "1ecfa4d6-4799-6344-8396-d346e336e775",
            "name": "Company AB"
        },
        "type": {
            "id": "1ecfa4d9-8684-6eb6-8514-d54d3c5555be",
            "name": "Hat",
            "key": "hat"
        },
        "name": "Item 001",
        [...]
    },
    "content": [
        {
            "id": "0187dcc3-7e91-7ea3-9998-2ad3f2f391b7",
            "created": "2023-05-02T14:00:12.049086Z",
            "updated": "2023-05-08T08:55:52.829364Z",
            "contentJson": {
                [...]
            },
            "type": {
                "id": "0187dc24-686a-7fc8-88a5-f0a3bffccf2a",
                "name": "Main",
                "key": "main",
                "description": "This is the main content visible in the app once an Item has been scanned."
            }
        }
    ]
}

Get information about an item.

Read more about the contents of openItem from the open layer documentation section.

Item Parameters

Parameter Type Description
id string The Commercial Item Unique identifier.
created datetime When the item was created.
updated datetime, null When the item was updated last. Or null if never.
openItem object The Item object from the open layer.
content array An object with Item Content objects.

Content Type Parameters

The content parameter in the Item response contains an array of all "fixed" content types of which it should only exist at the most one per type:

Read more here about Item Content parameters.

Error Codes

If the response is not 200 OK the response code and the response errorCode should be one of the following:

Response code Error code Description
400 ITEM_NOT_FOUND Item not found. Check the id and try again.
500 UNKNOWN Unknown technical error.

Get Commercial Item Content

Call:

$curl -X GET "/api/commercial/item/{{itemId}}/content" \
    -H "Authorization: Bearer {{jwt}}" \
    -H "Content-Type: application/json"

200 OK Response:

[
    {
        "id": "0187dcc3-7e91-7ea3-9998-2ad3f2f391b7",
        "created": "2023-05-02T14:00:12.049086Z",
        "updated": "2023-05-16T09:51:53.117630Z",
        "contentJson": {
            [...]
        },
        "type": {
            "id": "0187dc24-686a-7fc8-88a5-f0a3bffccf2a",
            "name": "Main",
            "key": "main",
            "description": "This is the main content visible in the app once an Item has been scanned.",
            "fixed": true,
            "editor": true,
            "link": false
        },
        "contentLink": null,
        "colorThemeMain": "#07f380",
        "colorThemeSecondary": "#b9adf5",
        "colorThemeBackground": "#4d2a19",
        "preamble": "This is preamble.\n\nOn multiple rows.",
        "mainImage": null
    },
    {
        "id": "0187e1c8-5a84-79dc-b4a0-bbc20a7c2e49",
        "created": "2023-05-03T13:23:36.680785Z",
        "updated": "2023-05-04T10:35:06.754506Z",
        "contentJson": {
            [...]
        },
        "type": {
            "id": "0187dc24-6877-71d3-995d-cb7847f32627",
            "name": "Post",
            "key": "post",
            "description": "The Post type content is displayed in the app as a feed of extra articles once an Item has been scanned.",
            "fixed": false,
            "editor": true,
            "link": false
        },
        "contentLink": null,
        "colorThemeMain": null,
        "colorThemeSecondary": null,
        "colorThemeBackground": null,
        "preamble": null,
        "mainImage": null
    },
    {
        "id": "018805ea-6760-70f7-92d0-aab2052b8c4c",
        "created": "2023-05-10T13:47:07.936351Z",
        "updated": null,
        "contentJson": {
            [...]
        },
        "type": {
            "id": "018805aa-e10a-7a0d-a69f-122690ef1817",
            "name": "Material",
            "key": "material",
            "description": "The material content is visible in the app once an Item has been scanned below the material content and the laundry advice.",
            "fixed": true,
            "editor": true,
            "link": false
        },
        "contentLink": null,
        "colorThemeMain": null,
        "colorThemeSecondary": null,
        "colorThemeBackground": null,
        "preamble": null,
        "mainImage": null
    },
    {
        "id": "01882506-eb4c-7c79-b884-04052506a094",
        "created": "2023-05-16T14:46:30.447740Z",
        "updated": "2023-05-16T18:47:37.884561Z",
        "contentJson": [],
        "type": {
            "id": "01882505-eadc-764d-b696-edaa3af1a20d",
            "name": "Link",
            "key": "link",
            "description": null,
            "fixed": false,
            "editor": false,
            "link": true
        },
        "contentLink": "https:\/\/www.google.com",
        "colorThemeMain": "#d23f3f",
        "colorThemeSecondary": "#482bdc",
        "colorThemeBackground": "",
        "preamble": "",
        "mainImage": {
            "id": "01882982-438e-7090-9d49-eb71bf38801d",
            "created": "2023-05-17T11:39:42.823253Z",
            "type": "main",
            "fileName": "partner-logo-test.png",
            "extension": "png",
            "mimeType": "image/png",
            "fileUrl": "https://sys.open-connector.com/uploads/commercial/1ecfa4d6-4799-6344-8396-d346e336e775/item/1ed5fa65-1c8d-6534-8a15-4b3a1388b63f/content/0187e1c8-5a84-79dc-b4a0-bbc20a7c2e49/01882982-438e-7090-9d49-eb71bf38801d.png"
        }
    }
]

Get a list of all content connected to an item.

Item Content Parameters

The return is an array with "Item Content" objects that contains the following parameters.

Parameter Type Description
id string The Item Content Unique identifier.
created datetime When the content was created.
updated datetime, null When the content was updated last. Or null if never.
type object Content Type object.
contentJson object The Editor.js content object, or an empty array, as json data.
contentLink string, null The link content for Content Type "Link".
colorThemeMain string, null Color theme "main". Can be, for example, "#ffffff" or "rgba(255, 255, 255, 0)".
colorThemeSecondary string, null Color theme "secondary". Can be, for example, "#ffffff" or "rgba(255, 255, 255, 0)".
colorThemeBackground string, null Color theme "background". Can be, for example, "#ffffff" or "rgba(255, 255, 255, 0)".
preamble string, null Preamble or short version of the text. Max 500 characters, no HTML, line breaks allowed.
mainImage object, null A Content Image object, or null, for the main image uploaded to the content. Main image is only available on Content Types that are not fixed.

Content Type Parameters

Each Item Content has one type which contains the following parameters.

Parameter Type Description
id string The Content Type Unique identifier.
name string The type name, mostly used in Commercial Admin and similar.
key string A text id/slug representation of the type name.
description string Type description (plain text), mostly used in Commercial Admin and similar.
fixed boolean Fixed content type limits the content to only one with that content type for each Item.
editor boolean If the content type activates the editor. If false, content.contentJson should be ignored.
link boolean If the content type activates the link field. If false, content.contentLink should be ignored.

Content Image Parameters

Parameter Type Description
id string The Content Type Unique identifier.
created datetime When the image was uploaded.
fileName string The original file name of the uploaded file.
extension string The extension for the stored file.
mimeType string The mime type for the stored file.
fileUrl string The absolute URL to the stored file.

Possible Content Image Types:

Error Codes

If the response is not 200 OK the response code and the response errorCode should be one of the following:

Response code Error code Description
400 ITEM_NOT_FOUND Item not found. Check the id and try again.
500 UNKNOWN Unknown technical error.

SDK : CMS

Read here for information about what is included within the CMS SDK.

Get Content

Call:

$curl -X GET "/api/commercial/cms/content" \
    -H "Authorization: Bearer {{jwt}}" \
    -H "Content-Type: application/json"

200 OK Response:

[
    {
        "id": "01886bac-3dfd-7343-a133-9627a964898b",
        "commercialEntity": {
            "id": "1ecfa4d6-4799-6344-8396-d346e336e775",
            "name": "Company AB"
        },
        "created": "2023-05-30T08:00:30.158467Z",
        "updated": "2023-05-30T08:00:57.859632Z",
        "contentJson": {
            [...]
        },
        "type": {
            "id": "018868f1-aa5e-70dd-a31c-82cb6d7364fa",
            "name": "App Home Screen",
            "key": "app_home",
            "description": "This content is displayed on the app home screen.",
            "fixed": true,
            "editor": true,
            "link": false
        },
        "contentLink": "",
        "colorThemeMain": "#e60e0e",
        "colorThemeSecondary": "#3310e4",
        "colorThemeBackground": "#dc16a6",
        "preamble": "Preamble",
        "mainImage": null
    }
]

Get a list of all content created in the CMS for the Commercial Entity.

CMS Content Parameters

The return is an array with "CMS Content" objects that contains the following parameters.

Parameter Type Description
id string The CMS Content Unique identifier.
commercialEntity object The Commercial Entity object, same as the user asking for the information belongs to.
created datetime When the content was created.
updated datetime, null When the content was updated last. Or null if never.
type object Content Type object.
contentJson object The Editor.js content object, or an empty array, as json data.
contentLink string, null The link content for Content Type "Link".
colorThemeMain string, null Color theme "main". Can be, for example, "#ffffff" or "rgba(255, 255, 255, 0)".
colorThemeSecondary string, null Color theme "secondary". Can be, for example, "#ffffff" or "rgba(255, 255, 255, 0)".
colorThemeBackground string, null Color theme "background". Can be, for example, "#ffffff" or "rgba(255, 255, 255, 0)".
preamble string, null Preamble or short version of the text. Max 500 characters, no HTML, line breaks allowed.
mainImage object, null A Content Image object, or null, for the main image uploaded to the content. Main image is only available on Content Types that are not fixed.

CMS Content Type Parameters

Each CMS Content has one type which contains the following parameters.

Parameter Type Description
id string The Content Type Unique identifier.
name string The type name, mostly used in Commercial Admin and similar.
key string A text id/slug representation of the type name.
description string Type description (plain text), mostly used in Commercial Admin and similar.
fixed boolean Fixed content type limits the content to only one with that content type for each Commercial Entity within the CMS SDK.
editor boolean If the content type activates the editor. If false, content.contentJson should be ignored.
link boolean If the content type activates the link field. If false, content.contentLink should be ignored.

CMS Content Image Parameters

Parameter Type Description
id string The Content Type Unique identifier.
created datetime When the image was uploaded.
fileName string The original file name of the uploaded file.
extension string The extension for the stored file.
mimeType string The mime type for the stored file.
fileUrl string The absolute URL to the stored file.

Possible CMS Content Image Types:

Error Codes

If the response is not 200 OK the response code and the response errorCode should be one of the following:

Response code Error code Description
500 UNKNOWN Unknown technical error.

Get Images

Call:

$curl -X GET "/api/commercial/cms/images" \
    -H "Authorization: Bearer {{jwt}}" \
    -H "Content-Type: application/json"

200 OK Response:

[
    {
        "id": "0188b160-83ba-76df-860f-b082b33b3619",
        "created": "2023-06-12T20:51:12.416663Z",
        "commercialEntity": {
            "id": "1ecfa4d6-4799-6344-8396-d346e336e775",
            "name": "Company AB"
        },
        "type": {
            "id": "0188af99-4560-7beb-9e30-09a915af1e55",
            "name": "Commercial Profile Logo",
            "key": "commercial_profile_logo",
            "single": true
        },
        "fileName": "company-ab-logo.jpg",
        "extension": "jpg",
        "mimeType": "image/jpeg",
        "fileUrl": "https://sys.open-connector.com/uploads/commercial/1ecfa4d6-4799-6344-8396-d346e336e775/image/0188b160-83ba-76df-860f-b082b33b3619.jpg"
    }
]

Get a list of all images uploaded in the CMS for the Commercial Entity.

CMS Content Parameters

The return is an array with "CMS Image" objects that contains the following parameters.

Parameter Type Description
id string The CMS Image Unique identifier.
commercialEntity object The Commercial Entity object, same as the user asking for the information belongs to.
created datetime When the image was uploaded.
type object Image Type object.
fileName string The original file name for the image.
extension string The file extension.
mimeType string The file mime type.
fileUrl string The URL for the file.

CMS Image Type Parameters

Each CMS Image has one type which contains the following parameters.

Parameter Type Description
id string The Image Type Unique identifier.
name string The type name, mostly used in Commercial Admin and similar.
key string A text id/slug representation of the type name.
single boolean If true, only one image of this type can be uploaded for a Commercial Entity.

Error Codes

If the response is not 200 OK the response code and the response errorCode should be one of the following:

Response code Error code Description
500 UNKNOWN Unknown technical error.

Get Commercial Profile

Call:

$curl -X GET "/api/commercial/cms/commercial-profile" \
    -H "Authorization: Bearer {{jwt}}" \
    -H "Content-Type: application/json"

200 OK Response:

{
    "commercialEntity": {
        "id": "1ecfa4d6-4799-6344-8396-d346e336e775",
        "name": "Fila"
    },
    "images": {
        "commercial_profile_logo": {
            [...]
        }
    },
    "content": {
        "app_home": {
            [...]
        },
        "privacy_policy": {
            [...]
        }
    }
}

Returns the "Commercial Profile" for the Commercial Entity.

Commercial Profile Return Parameters

The return is an array with "CMS Image" objects that contains the following parameters.

Parameter Type Description
commercialEntity object The Commercial Entity object, same as the user asking for the information belongs to.
images object A selection of "CMS Images" (see "Image Types Returned" below and "Get Images" above for more information about each image returnd).
content object A selection of "CMS Content" (see "Content Types Returned" below and "Get Content" above for more information about each content returnd).

Image Types Returned

Content Types Returned

Error Codes

If the response is not 200 OK the response code and the response errorCode should be one of the following:

Response code Error code Description
500 UNKNOWN Unknown technical error.

Errors

Error Formatting

Single Error Response Example:

{
    "errorCode": "UNAUTHENTICATED",
    "errorMessage": "Expired JWT Token",
    "publicErrorMessage": "Login required"
}

Input Field Error Response Example:

{
    "errorCode": "INVALID_INPUT",
    "errorMessage": "Invalid input",
    "errorFields": [
        "email",
        "password"
    ],
    "publicErrorMessage": [
        "email": "This value is not a valid email address.",
        "password": "This value should not be blank."
    ],
}

Error messages should be returned with an error response code (4xx or 5xx) as well as a JSON response body with an error code and optional error message and public message.

The errorCode and the optional errorMessage data are for internal use. But publicErrorMessage, if available, can be displayed to an end user.

When the API call contains input field, for example when creating a user, publicErrorMessage can be an array where the index is the input field name. In this case errorFields are also available containing the field names that contains an error.

General Error Messages

During any call to the API one of the following general error codes could be returned.

Response code Error code Description
401 UNAUTHENTICATED The API Token or JWT was not accepted.
500 UNKNOWN Unknown technical error.