Introduction

Welcome to the CheckMaxx Account API !

You can use our API to access endpoints, which gives read/write to CheckMaxx user accounts.

Endpoints description, method, url, request/response schema and their description are presented on the left. The right side contains example requests (via curl) and responses (in JSON).

For more information on types and possible value, refer to the Models and Enumeration section.

In the future, more endpoints will be added in order to provide complete access to CheckMaxx database.

If this is your first time reading the docs, check out the Authentication section for obtaining and using API keys.

Changelog section contains all updates related to this API.

Authentication

To authorize, use this code:

# With shell, you can just pass the correct header with each request
curl "api_endpoint_here"
  -H "Authorization: $your_api_key"

CheckMaxx API uses API keys to allow access to the API... You can receive a new API key by logging in, and it will be provided as a session token.

Account Service IAM Controller

Enables a user to login and logout.

Enables a user to login and logout. This begins a user session that is required for using the other services of CheckMaxx.

Logout

curl "API_BASE/v1/iam/logout"
    -H "Authorization: $your_api_key"

This endpoint allows users to logout

HTTP Request

GET /v1/iam/logout

The request JSON response is:

This endpoint do not return anything, only the HTTP status code matters.

Request schema

This request does not accept any parameters.

Response schema

This endpoint do not return anything, only the HTTP status code matters.

Retrieves user-specific information from the session

curl "API_BASE/v1/iam/me"
    -H "Authorization: $your_api_key"

This endpoint returns data associated with the authenticated user. The Shop associated with the User is embedded

HTTP Request

GET /v1/iam/me

The request JSON response is:

{
    "created_on": "0001-01-01T00:00:00Z",
    "updated_on": "0001-01-01T00:00:00Z",
    "id": 0,
    "email": "",
    "language_code": "",
    "app_version": "",
    "web_version": "",
    "role_id": 0,
    "shop_id": null,
    "shop": null
}

Request schema

This request does not accept any parameters.

Response schema

This endpoint return an object of type User, please refer to the JSON response column on the right, or to the Models and Enumeration section for more details.

Login through Google

curl "API_BASE/v1/iam/google_login"
    -H "Authorization: $your_api_key"

This endpoint allows users to sign in with a Google account. If the user does not exists yet, an account will be created, without a shop. See the shops/create endpoint from this service to create and assign a shop. The user returned contains the SessionToken. If a shop is assigned it's embedded to avoid having to call /me after each login.

HTTP Request

POST /v1/iam/google_login

The request Body payload is:

{
    "id_token": "",
    "app_version": ""
}

The request JSON response is:

{
    "user": null,
    "session_token": ""
}

Request schema

Response schema

This endpoint return an object with the following fields, please refer to the JSON response column on the right for an example.

Account Service Shop Controller

When users login on the app, an account will be created for them if they don't have one yet.

If a user does not have a shop assigned, the app will ask to create one, and use this controller to create and assign it.

Later on, more shop management and assignment endpoints will be added.

Update a shop

curl "API_BASE/v1/shops/update"
    -H "Authorization: $your_api_key"

This endpoint update an existing shop.

HTTP Request

POST /v1/shops/update

The request Body payload is:

{
    "shop": {
        "created_on": "0001-01-01T00:00:00Z",
        "updated_on": "0001-01-01T00:00:00Z",
        "id": 0,
        "photo_url": "",
        "thumbnail_url": "",
        "name": "",
        "address": "",
        "phone": "",
        "email": "",
        "checkable_id": 0,
        "shop_tier_id": 0,
        "created_by_id": 0,
        "updated_by_id": null
    }
}

The request JSON response is:

This endpoint do not return anything, only the HTTP status code matters.

Request schema

Response schema

This endpoint do not return anything, only the HTTP status code matters.

Upload a shop photo

curl "API_BASE/v1/shops/upload_photo"

This endpoint upload a picture and return it's URL to be used as shop.photo_url.

HTTP MultiPart Request

POST /v1/shops/upload_photo

The request parts are:

--XXX
Content-Disposition: form-data; name=

...
--XXX
Content-Disposition: form-data; name=

...--XXX--

The request JSON response is:

{
    "photo_url": "",
    "thumbnail_url": ""
}

This request must be a multipart/form-data content-type with valid boundary for each part

Request parts schema

Response schema

This endpoint return an object with the following fields, please refer to the JSON response column on the right for an example.

Creates a shop

curl "API_BASE/v1/shops/create"
    -H "Authorization: $your_api_key"

This endpoint create a shop and assign it for users that does not have one with the provided details.

HTTP Request

POST /v1/shops/create

The request Body payload is:

{
    "shop": {
        "created_on": "0001-01-01T00:00:00Z",
        "updated_on": "0001-01-01T00:00:00Z",
        "id": 0,
        "photo_url": "",
        "thumbnail_url": "",
        "name": "",
        "address": "",
        "phone": "",
        "email": "",
        "checkable_id": 0,
        "shop_tier_id": 0,
        "created_by_id": 0,
        "updated_by_id": null
    }
}

The request JSON response is:

{
    "id": 0
}

Request schema

Response schema

This endpoint return an object with the following fields, please refer to the JSON response column on the right for an example.

Models and Enumeration

Checkable Enumeration

LanguageCode Enumeration

Role Enumeration

ShopTier Enumeration

FormFile Model

Shop Model

User Model

Changelog

This section contains changes related to the API service. Changes will be included if:

• A new endpoint is added
• A new field is added to an existing endpoint
• Field description changes
• A field is deprecated

Initial release - 08.06.2023.

The following endpoints are included with initial release:

• /v1/user/create
• /v1/iam/google_login
• /v1/iam/logout
• /v1/iam/me

Errors

CheckMaxx APIs uses the following error codes: