📄Prescriptions

Like medication prescriptions at a pharmacy, users on the FibriCheck platform require an active prescription to analyse their measurements.

An active prescription links a user, a group, and a package.

The relevant properties of a prescription are:

Property	Description
hash	The hash is a random string and uniquely identifies the prescription
userId	The FibriCheck user to which the prescription is linked
groupId	The group to which the user should be added. This is typically a single group per integration partner. You will receive a dedicated groupId for your integration from FibriCheck.
packageId	The chosen package determines the duration of the prescription, which is always limited in time. You will receive a list of possible packageId values for your integration from FibriCheck.
isTemplate	Indicates if this prescription is a template.

Obtaining an active prescription involves three simple steps:

1. Create a prescription hash: typically done in the (partner's) backend or provided by FibriCheck.

2. Scan the prescription hash: links the prescription to the user. This can be done in the front or backend.

3. Activate the prescription hash: from this moment, measurements will be analyzed. This is also the start of the prescription duration.

A group can be configured with a number of activation credits. When configured, every activated prescription will consume a credit. When the credits run out, activating new prescriptions will not be possible anymore until new credits are added to the group.

Create a prescription hash

There are multiple ways to obtain a prescription hash. For integration partners, typically the partner instead of the end-user pays for using FibriCheck. In this scenario there are 2 options:

• Use a template hash A template hash is linked to a package and a group and can be re-used by different users. Every user can use this template hash code at most once. This method is typically used in screening campaigns where users will only use FibriCheck for a single screening period.

• Generate prescriptions through the API As a partner, you also have the ability to create prescription hashes yourself. This gives you more flexibility in how your customers can use FibriCheck.

Prescriptions can only be created by specific users with elevated rights. Typically only a few integration partner user accounts obtain those rights. Reach out via [e-mail] to know more.

REST API

Execute an API call with the following payload to create a new prescription:

{
  "data": {
    "command": "create-prescription",
    "data": {
      "groupId": "{groupId}",
      "packageId": "{packageId}",
      "isTemplate" : <true|false>
    }
  }
}

In case you want to create a template hash, you can add the isTemplate: true property to the data object.

Create a prescription

POST https://api.fibricheck.com/tasks/v1/functions/integration/execute

Request Body

Name	Type	Description
data*	object	payload

200: OK Successful creation of a prescription

{
  "result": {
    "prescription": {
      "id": "58074804b2148f3b28ad758b",
      "creator_id": "58074804b2148f3b28ad758b",
      "hash": "string",
      "reference": "string",
      "status": "FREE",
      "group_id": "58074804b2148f3b28ad758b",
      "user_id": "58074804b2148f3b28ad758b",
      "package_id": "58074804b2148f3b28ad758b",
      "duration": 0,
      "price": 0,
      "tags": [
        "string"
      ],
      "bundle_id": "58074804b2148f3b28ad758b"
    }
  }
}

Get the status of a prescription

You can query the status of a prescription to know if a prescription has been used. Execute an API call with the following payload to the endpoint below:

{
  "data": {
    "command": "get-prescription",
    "data": {
      "hash": "{hash}"
    }
  }
}

If the response has result.prescription.status set to ACTIVATED, the prescription has been activated by the respective user. In that case, result.prescription.user_id will contain the reference to the user that activated the prescription.

Get the prescription status

POST https://api.fibricheck.com/tasks/v1/functions/integration/execute

200: OK Returns prescription status

{
    "result": {
        "prescription": {
            "id": "642544e20d43ab",
            "creator_id": "641ac2c659744976404b685d",
            "reference": "ABC123",
            "hash": "aa121212121212121359874db296b8115a32d3",
            "status": "PAID_BY_GROUP",
            "group_id": "6425767bc7801a7f69392577",
            "package_id": "5588424dreddd4",
            "is_template": false,
            "logs": [
                {
                    "old_status": "NOT_PAID",
                    "new_status": "PAID_BY_GROUP",
                    "timestamp": 1680177647943
                }
            ],
            "paid_timestamp": 1680177647943,
            "creation_timestamp": 1680177647943,
            "update_timestamp": 1680177647943
        }
    }
}

The integration REST API is implemented in a serverless computing environment. This causes some additional information to be present in the API endpoints. Only the information in the result property of the API response should be considered. If no prescription is present in the result, it indicates that no prescription is found.

Administrative activation of a prescription

You can activate a prescription for other users than the authenticated users. The typical use case is when the partner backend activates prescriptions for a user.

REST API

Activate an existing prescription by executing an API call with the following payload:

{
  "data": {
    "command": "activate-prescription",
    "data": {
      "hash": "{prescriptionHash}",
      "userId": "{userId}"
    }
  }
}

Activate a prescription

POST https://api.fibricheck.com/tasks/v1/functions/integration/execute

Request Body

Name	Type	Description
data*	String	payload

200: OK

{
  "result": {
    "prescription": {
      "id": "58074804b2148f3b28ad758b",
      "creator_id": "58074804b2148f3b28ad758b",
      "hash": "string",
      "reference": "string",
      "status": "FREE",
      "group_id": "58074804b2148f3b28ad758b",
      "user_id": "58074804b2148f3b28ad758b",
      "package_id": "58074804b2148f3b28ad758b",
      "duration": 0,
      "price": 0,
      "tags": [
        "string"
      ],
      "bundle_id": "58074804b2148f3b28ad758b"
    }
  }
}

For ease of use, we can also combine both into one call with the following payload:

{
  "data": {
    "command": "create-and-activate-prescription",
    "data": {
      "groupId": "{groupId}",
      "packageId": "{packageId}",
      "userId": "{userId}>"
    }
  }
}

Generate & activate a prescription

POST https://api.fibricheck.com/tasks/v1/functions/integration/execute

Request Body

Name	Type	Description
data*	String	payload

200: OK

{
  "result": {
    "prescription": {
      "id": "58074804b2148f3b28ad758b",
      "creator_id": "58074804b2148f3b28ad758b",
      "hash": "string",
      "reference": "string",
      "status": "FREE",
      "group_id": "58074804b2148f3b28ad758b",
      "user_id": "58074804b2148f3b28ad758b",
      "package_id": "58074804b2148f3b28ad758b",
      "duration": 0,
      "price": 0,
      "tags": [
        "string"
      ],
      "bundle_id": "58074804b2148f3b28ad758b"
    }
  }
}

User activation of a prescription

If the user receives a prescription hash, they can activate the prescription themselves. In this case, the prescription is linked to the authenticated user.

SDK

The activatePrescription method in the SDK scans the prescription, links it to the authenticated user, and activates it. This method takes the prescription hash as a parameter.

This function can throw 2 errors:

• NotPaidError: A paying prescription has not yet been paid.

• AlreadyActivatedError : The prescription has already been used.

Flutter

await _sdk.activatePrescription(hash);

React Native

await sdk.activatePrescription(hash);

REST API

Activating a prescription through the REST API is a two-step process. First, you have to scan the prescription, then you have to activate the prescription. You can only scan a prescription once.

The following API call will scan the prescription and link the prescription to the user that executes the API call.

Scan a prescription

GET https://api.fibricheck.com/prescriptions/v1/{prescriptionHash}/scan

200: OK Prescription scanned successfully

{
    "id": "63f632e4fa725244e20d421c",
    "creator_id": "6255af75590801000bdb1c30",
    "reference": "GBX4L5JB",
    "hash": "1f3f4cbb79be1aac595fb07a5e2ac16548ddf9d7",
    "status": "FREE",
    "group_id": "6258156365220500073f0c7d",
    "user_id": "5811c7a046e0fb000530a465",
    "duration": 604800000,
    "price": 1000,
    "package_id": "5923fbc44cedfd0005042cbb",
    "is_template": false,
    "logs": [
        {
            "old_status": "NOT_PAID",
            "new_status": "FREE",
            "timestamp": 1677079268566
        }
    ],
    "paid_timestamp": 1677079268565,
    "creation_timestamp": 1677079268566,
    "update_timestamp": 1677079364798
}

400: Bad Request When a prescription is already scanned

{
    "code": 502,
    "name": "ALREADY_SCANNED_EXCEPTION",
    "message": "This prescription has already been scanned and assigned to a user"
}

Check the status of the prescription after executing the API call. If the status is ACTIVATED or NOT_PAID , the prescription cannot be activated.

Next, activate the prescription.

Activate a prescription

GET https://api.fibricheck.com/prescriptions/v1/{prescriptionHash}/activate

Path Parameters

Name	Type	Description
prescriptionHash	String

200: OK Successful activation of a prescription

{
    "id": "63f632e4fa725244e20d421c",
    "creator_id": "6255af75590801000bdb1c30",
    "reference": "GBX4L5JB",
    "hash": "1f3f4cbb79be1aac595fb07a5e2ac16548ddf9d7",
    "status": "ACTIVATED",
    "group_id": "6258156365220500073f0c7d",
    "user_id": "5811c7a046e0fb000530a465",
    "duration": 604800000,
    "price": 1000,
    "package_id": "5923fbc44cedfd0005042cbb",
    "is_template": false,
    "logs": [
        {
            "old_status": "NOT_PAID",
            "new_status": "FREE",
            "timestamp": 1677079268566
        },
        {
            "old_status": "FREE",
            "new_status": "ACTIVATED",
            "timestamp": 1677079784876
        }
    ],
    "paid_timestamp": 1677079268565,
    "activated_timestamp": 1677079784876,
    "creation_timestamp": 1677079268566,
    "update_timestamp": 1677079784876
}

400: Bad Request Multiple activations are not allowed

{
    "code": 510,
    "name": "WRONG_STATUS_EXCEPTION",
    "message": "This prescription is already activated"
}

Get remaining prescription duration

To know the remaining duration of the active prescription, you can request this per group. Execute an API call with the following payload to the endpoint below:

{
  "data": {
    "command": "get-remaining-prescription-duration",
    "data": {
      "userId": "{userId}",
      "groupId": "{groupId}"
    }
  }
}

Get remaining prescription duration

POST https://api.fibricheck.com/tasks/v1/functions/integration/execute

Request Body

Name	Type	Description
data*	String	payload

200: OK

The result.endTimestamp in the response will include the prescription's ending time in ISO format.

Cancel prescription

A prescription can always be canceled by executing the following API call:

{  
    "data": {
        "command": "cancel-prescription",
        "data": {
          "userId": "{userId}",
          "groupId": "{groupId}"
        }
    }
}

Cancel subscription

POST https://api.fibricheck.com/tasks/v1/functions/integration/execute

Request Body

Name	Type	Description
data*	String	payload

200: OK