Purpose

This WS is designed to qualify Device Request: check the ability of dispense Device Request within the Medical program.This method is used to qualify (possibility to use device definition for the program) Device request by Id . Fields descriptions are listed in request Example view.

Key points

1. Only authenticated and authorized users with appropriate scope can invoke Qualify Device Request

2. This method returns for existing Device Request the result of data validation within each submitted medical program, but not creates any entities in the system.

3. Each Medical program may have its unique conditions for the Device Dispense. They can be based on analysis of personal info, device definition list, terms, locations and combinations of them.

4. Any Medical program can have separate block of branching logic configured at /wiki/spaces/CSI/pages/17467605147 by NHS administrator.

5. Сompatibility is checked only for programs which are available in payload (array).

6. Successful invocation of the method returns decision for each program if it is valid or not to create Device dispense with submitted combination of parameters in the payload. If program is invalid, the reason must be returned in the response.

7. Allowed for existing and active Device Requests

8. Also medical program provision is checked for the division of the pharmacy.

Specification

...

...

Link

...

https://ehealthmedicaleventsapi.docs.apiary.io/#reference/device-requests/qualify-device-request-by-id/qualify-device-request-by-id

...

Apiary

...

Resource

...

/api/device_requests/{{device_request_id}}/actions/qualify

...

Посилання на ресурс, наприклад: /api/persons/create

...

Scope

...

Scope для доступу

...

Components

...

Зазначається перелік бізнес компонентів, які використовують цей метод, наприклад: ePrescription

...

Microservices

...

Перелік мікросервісів, які використовує метод API, наприклад: Auth, ABAC

...

Protocol type

...

Тип протоколу, який використовується запитом, наприклад: SOAP | REST

...

Request type

...

POST

...

Тип запиту API, наприклад: GET, POST, PATCH…

...

Sync/Async

...

Метод є синхронним чи асинхронним?

...

Public/Private/Internal

...

Потрібно зазначити тип методу за ступенем доступності

Logic

Generate structure for response

1. If general error found at Validate division section, that doesn’t depend on medical program, then return corresponding error code with error message

2. If general validation passed, then collect array for all programs in payload with status for each (VALID or INVALID) and rejection_reason

3. For each program return a list of appropriate Device Definitions found at Validate Device Definitions step

4. Generate response according to specification

Input parameters

...

Input parameter

...

Values

...

Type

...

Description

...

Example

...

device_request_id

...

String

...

Device request identifier

...

2848a935-5fd7-48ba-b235-a9b5d475c647

Request structure

See on Apiary

Example:

{
  "location": {
    "identifier": {
      "type": {
        "coding": [
          {
            "system": "eHealth/resources",
            "code": "division"
          }
        ]
      },
      "value": "9183a36b-4d45-4244-9339-63d81cd08d9c"
    }
  },
  "programs": [
    {
      "identifier": {
        "type": {
          "coding": [
            {
              "system": "eHealth/resources",
              "code": "medical_program"
            }
          ]
        },
        "value": "9183a36b-4d45-4244-9339-63d81cd08d9c"
      }
    }
  ]
}

Authorize

Authorization

1. Verify the validity of access token

   • in case of error - return 401 (“Invalid access token”) in case of validation fails

2. Verify that token is not expired

   • in case of error - return 401 (“Invalid access token”)

3. Check user and client scopes in order to perform this action (scope = 'device_request:read')

   • return 403 (“Your scope does not allow to access this resource. Missing allowances: device_request:read”) in case of invalid scope(s)

Headers

• Content-Type:application/json

• Authorization:Bearer c2778f3064753ea70de870a53795f5c9

• api-key:aFBLVTZ6Z2dON1V

Request data validation

Validate Device request

Get Device request identifier from URL and check:

• it exists in DB and has ACTIVE status

  • in case of error - return 404 ('Device request not found')

• has a program

  • in case of error - return 409 ('Device request without a program cannot be qualified')

Check for existing Device dispenses

• Check that there is no other IN_PROGRESS device dispenses based on the same device request

  • Find all device dispenses related to the same device request ($.based_on)

  • Check that there are no records in status IN_PROGRESS where inserted_at + config device_dispense_ttl >= current date-time()

    • in case of error - return 422 "Other active device dispense already exist."

Validate request

Validate request using schema. Return 422 with the list of validation errors in case validation fails. In addition, check following:

...

• Check there is at least one appropriate Device Definition for a program:

  • Find program_devices related to the program, that:

    • is active

    • has validity period (start_date and end_date) within current date

    • has max_daily_count is null or max_daily_count >= quantity.value/(occurence_period.end - occurence_period.start) of the Device Request

      • in case not found - return reject_reason = “No appropriate participants found for this medical program“

  • For found program_devices check there at least one appropriate Device Definition, that:

    • is active

    • has the same code as in the Device Request

    • has packaging_unit that matches to quantity.code of the Device Request

      • in case of error - return reject_reason = “Not found any active Device Definition with the same units of measure as pointed in the quantity of the Device Request”

    • has a remainder of the division ($.device_request.quantity.value/device_definition.packaging_count) that is equal to 0

      • in case of error - return reject_reason = “The quantity in the Device Request must be divisible to packaging_count of at least one related Device Definition”

Processing

API paragraph not found

Response structure

See on Apiary

Example:

{
  "meta": {
    "code": 200,
    "url": "http://example.com/resource",
    "type": "object",
    "request_id": "req-adasdoijasdojsda"
  },
  "data": [
    {
      "program_id": "59781de0-2e64-4359-b716-bcc05a32c10f",
      "program_name": "Доступні медичні вироби",
      "status": "INVALID",
      "rejection_reason": "No appropriate participants found for this medical program",
      "participants": [
        {
          "id": "0f2fbf93-3041-4c0d-a3cf-ff558c861df8",
          "device_definition": {
            "id": "3e34da3d-9b8c-4aaf-be8e-24a161279b6a",
            "device_names": [
              {
                "name": "Тест-смужки Accu-Chek Active для глюкометра",
                "type": "user_friendly"
              }
            ],
            "classification_type": "30221",
            "manufacturer": {
              "name": "ПАТ \"Київський вітамінний завод\"",
              "country": "UA"
            },
            "model_number": "M23N76",
            "packaging": {
              "packaging_type": "undefined",
              "packaging_count": 50,
              "packaging_unit": "pcs"
            }
          },
          "reimbursement": {
            "type": "FIXED",
            "percentage_discount": 12.45,
            "reimbursement_amount": 50.98
          },
          "wholesale_price": 25.14,
          "consumer_price": 34.03,
          "reimbursement_daily_count": 5,
          "estimated_payment_amount": 5.15,
          "max_daily_count": 10,
          "registry_number": "REG-1111",
          "start_date": "2019-01-01",
          "end_date": "2019-06-30"
        }
      ]
    }
  ]
}

{
  "meta": {
    "code": "422",
    "url": "http://example.com/resource",
    "type": "object",
    "request_id": "req-adasdoijasdojsda"
  },
  "error": {
    "type": "unverified",
    "message": "Division is not active"
  }
}

Post-processing processes

API paragraph not found

HTTP status codes

...

...

HTTP status code

...

Message

...

What caused the error

...

 200

...

...

...

 422

...

...

Service logic

Generate structure for response

1. If general error found at Validate division section, that doesn’t depend on medical program, then return corresponding error code with error message

2. If general validation passed, then collect array for all programs in payload with status for each (VALID or INVALID) and rejection_reason

3. For each program return a list of appropriate Device Definitions found at Validate Device Definitions step

4. Generate response according to specification