Properties of a REST API method document

Document type	Метод REST API
Document title	Get Medication dispense details in person context [API-005-008-001-0129]
Guideline ID	GUI-0011
Author	@
Document version	1
Document status	DRAFT
Date of creation	ХХ.ХХ.ХХХХ (дата фінальної версії документа – RC або PROD)
Date of update	ХХ.ХХ.ХХХХ (дата зміни версії)
Method API ID	API-005-008-001-0129
Microservices (namespace)	IL
Component	ePrescription
Component ID	COM-005-008
Link на API-специфікацію	GENERAL MIS API · Apiary
Resource	{{host}}/api/persons/person_id/medication_dispenses/id
Scope	medication_dispense:read
Protocol type	REST
Request type	GET
Sync/Async	Sync
Public/Private	Public

Purpose

This method allows getting short information about the patient’s Medication dispense. Obtaining a medication dispenses list or receiving full information is restricted for the MSP side. Only short medication dispense information is allowed.

Logic

Service returns specified Medication dispense related to the patient:

Get Medication dispense by ID from medication_dispenses DB (OPS).
Validate data consistency:
- Ensure that requested Medication dispense relates to requested Patient (from URL)
  - Return 404 ('not_found') in case of error.
Render a response according to specification.

Preconditions

N/A

Configuration parameters

Access to the method is defined by the scope medication_dispense:read. Permission for this scope is determined by the System administrator by configuring scopes in the context of clients and roles.

Dictionaries

API paragraph not found

Input parameters

	Input parameter	Mandatory	Type	Description	Example
1	id	M	String	Medication Dispense Response Identifier. Required.	a89f6a26-4221-4597-a1d2-542d5e40b565

Request structure

See on API-specification

Headers

Request data validation

Authorize

Verify the validity of access token
- Return (401, 'Invalid access token') in case of validation fails.
Verify that token is not expired
- in case of error - return (401, 'Invalid access token').
Check user scopes in order to perform this action (scope = 'medication_dispense:read')
- Return (403, 'Your scope does not allow to access this resource. Missing allowances: medication dispense:read') in case of invalid scope(s).

Validate Person

Get Person identifier from the URL.
Check it exists in DB
- Return 404 ('not_found') in case of error.

Validate Medication dispense

Get Medication dispense identifier from the URL
- Check it exists in DB
  - Return 404 ('not_found') in case of error;
- Check Medication dispense belongs to patient
  - Return 404 ('not_found') in case of error.

Validate User

Extract user_id from token.
Check user has an active and approved employee from legal entity (token) that:
- has an active declaration with the patient;
- has access to connected with medication requests episode with the patient (created in current MSP or approval on Episode resource);
- has access to connected with medication requests care plan with the patient (approval on Care plan resource)
  - Return 403 ('Access denied') in case employee has no declaration or access connected with medication requests episode or care plan.

Response structure examples

See on API-specification

Expand

title	Example

Code Block

{
  "meta": {
    "code": 200,
    "url": "https://example.com/resource",
    "type": "object",
    "request_id": "req-adasdoijasdojsda"
  },
  "data": {
    "id": "b075f148-7f93-4fc2-b2ec-2d81b19a9b7b",
    "medication_request": {
      "id": "b075f148-7f93-4fc2-b2ec-2d81b19a9b7b",
      "status": "ACTIVE",
      "request_number": "0000-243P-1X53-EH38",
      "created_at": "2017-08-17",
      "started_at": "2017-08-17",
      "ended_at": "2017-09-16",
      "dispense_valid_from": "2017-08-17",
      "dispense_valid_to": "2017-09-16",
      "legal_entity": {
        "id": "b075f148-7f93-4fc2-b2ec-2d81b19a9b7b",
        "name": "Клініка Ноунейм",
        "short_name": "Ноунейм",
        "public_name": "Клініка Ноунейм",
        "type": "MSP",
        "edrpou": "5432345432",
        "status": "ACTIVE"
      },
      "division": {
        "id": "d290f1ee-6c54-4b01-90e6-d701748f0851",
        "legal_entity_id": "c8aadb87-ecb9-41ca-9ad4-ffdfe1dd89c9",
        "name": "Бориспільське відділення Клініки Ноунейм",
        "addresses": [
          {
            "type": "RESIDENCE",
            "country": "UA",
            "area": "Житомирська",
            "region": "Бердичівський",
            "settlement": "Київ",
            "settlement_type": "CITY",
            "settlement_id": "b075f148",
            "street_type": "STREET",
            "street": "вул. Ніжинська",
            "building": "15",
            "apartment": "23",
            "zip": "02090"
          }
        ],
        "phones": [
          {
            "type": "MOBILE",
            "number": "+380503410870"
          }
        ],
        "email": "email@example.com",
        "working_hours": {
          "mon": [
            [
              "08.00",
              "12.00"
            ],
            [
              "14.00",
              "18.00"
            ]
          ],
          "tue": [
            [
              "08.00",
              "12.00"
            ]
          ],
          "wed": [
            [
              "08.00",
              "12.00"
            ]
          ],
          "thu": [
            [
              "08.00",
              "12.00"
            ]
          ],
          "fri": [
            [
              "08.00",
              "12.00"
            ]
          ]
        },
        "type": "CLINIC",
        "external_id": "3213213",
        "location": {
          "latitude": 30.1233,
          "longitude": 50.32423
        },
        "dls_id": "2872985",
        "dls_verified": true
      },
      "employee": {
        "id": "d290f1ee-6c54-4b01-90e6-d701748f0851",
        "position": "P6",
        "party": {
          "id": "b075f148-7f93-4fc2-b2ec-2d81b19a9b7b",
          "no_tax_id": true,
          "first_name": "Петро",
          "last_name": "Іванов",
          "second_name": "Миколайович",
          "email": "email@example.com",
          "phones": [
            {
              "type": "MOBILE",
              "number": "+380503410870"
            }
          ]
        }
      },
      "person": {
        "id": "b075f148-7f93-4fc2-b2ec-2d81b19a9b7b",
        "short_name": "Петро І. І.",
        "age": 35
      },
      "medication_info": {
        "medication_id": "4a63b858-c138-4921-9341-ae9e384bcbd6",
        "medication_name": "Аміодарон 200мг таблетки",
        "form": "PILL",
        "dosage": {
          "numerator_unit": "MG",
          "numerator_value": 200,
          "denumerator_unit": "PILL",
          "denumerator_value": 1
        },
        "ingredients": [
          {
            "id": "1349a693-4db1-4a3f-9ac6-8c2f9e541982",
            "name": "Інсулін деглюдек",
            "name_original": "Insulin degludec",
            "sctid": "52574003",
            "dosage": {
              "numerator_unit": "MG",
              "numerator_value": 200,
              "denumerator_unit": "PILL",
              "denumerator_value": 1
            },
            "is_primary": true
          }
        ],
        "medication_qty": 10.34
      },
      "medical_program": {
        "id": "c7d52544-0bd4-4129-97b0-2d72633e0490",
        "name": "Доступні ліки",
        "medical_program_settings": {
          "care_plan_required": true,
          "employee_types_to_create_medication_request": [
            "SPECIALIST",
            "DOCTOR"
          ],
          "skip_mnn_in_treatment_period": true,
          "skip_employee_validation": true,
          "speciality_types_allowed": [
            "ENDOCRINOLOGY",
            "PEDIATRIC_NEUROLOGY"
          ],
          "conditions_icd10_am_allowed": [
            "A00.0",
            "A00.1"
          ],
          "conditions_icpc2_allowed": [
            "A01",
            "A02"
          ],
          "providing_conditions_allowed": [
            "INPATIENT",
            "OUTPATIENT"
          ],
          "medication_request_max_period_day": 90,
          "skip_medication_request_employee_declaration_verify": true,
          "skip_medication_request_legal_entity_declaration_verify": true,
          "multi_medication_dispense_allowed": true,
          "skip_medication_dispense_sign": true,
          "medication_request_notification_disabled": true,
          "skip_contract_provision_verify": true,
          "medication_dispense_period_day": 90
        },
        "medical_program_settings_text": "Some text",
        "is_active": true,
        "medication_dispense_allowed": true,
        "medication_dispense_allowed_text": "Some text",
        "medication_request_allowed": true,
        "medication_request_allowed_text": "Some text",
        "type": "MEDICATION",
        "funding_source": "NHS",
        "mr_blank_type": "F-1",
        "inserted_at": "2017-04-20T19:14:13Z",
        "inserted_by": "e1453f4c-1077-4e85-8c98-c13ffca0063e",
        "updated_at": "2017-04-20T19:14:13Z",
        "updated_by": "2922a240-63db-404e-b730-09222bfeb2dd"
      },
      "intent": "plan",
      "category": "community",
      "based_on": [
        {
          "identifier": {
            "type": {
              "coding": [
                {
                  "system": "eHealth/resources",
                  "code": "care_plan"
                }
              ]
            },
            "value": "9183a36b-4d45-4244-9339-63d81cd08d9c"
          }
        },
        {
          "identifier": {
            "type": {
              "coding": [
                {
                  "system": "eHealth/resources",
                  "code": "activity"
                }
              ]
            },
            "value": "9183a36b-4d45-4244-9339-63d81cd08d9c"
          }
        }
      ],
      "context": {
        "identifier": {
          "type": {
            "coding": [
              {
                "system": "eHealth/resources",
                "code": "encounter"
              }
            ]
          },
          "value": "9183a36b-4d45-4244-9339-63d81cd08d9c"
        }
      },
      "dosage_instruction": [
        {
          "sequence": 1,
          "text": "0.25mg PO every 6-12 hours as needed for menses from Jan 15-20, 2015.  Do not exceed more than 4mg per day",
          "additional_instruction": [
            {
              "coding": [
                {
                  "system": "eHealth/SNOMED/additional_dosage_instructions",
                  "code": "311504000"
                }
              ]
            }
          ],
          "patient_instruction": "0.25mg PO every 6-12 hours as needed for menses from Jan 15-20, 2015.  Do not exceed more than 4mg per day",
          "timing": {
            "event": [
              "2017-04-20T19:14:13Z"
            ],
            "repeat": {
              "bounds_duration": {
                "value": 10,
                "unit": "days",
                "system": "eHealth/ucum/units",
                "code": "d"
              },
              "count": 2,
              "count_max": 4,
              "duration": 4,
              "duration_max": 6,
              "duration_unit": "d",
              "frequency": 1,
              "frequency_max": 2,
              "period": 4,
              "period_max": 6,
              "period_unit": "d",
              "day_of_week": [
                "mon"
              ],
              "time_of_day": [
                "2017-04-20T19:14:13Z"
              ],
              "when": [
                "WAKE"
              ],
              "offset": 4
            },
            "code": {
              "coding": [
                {
                  "system": "TIMING_ABBREVIATIONS",
                  "code": "patient"
                }
              ]
            }
          },
          "as_needed_boolean": true,
          "site": {
            "coding": [
              {
                "system": "eHealth/SNOMED/anatomical_structure_administration_site_codes",
                "code": "344001"
              }
            ]
          },
          "route": {
            "coding": [
              {
                "system": "eHealth/SNOMED/route_codes",
                "code": "46713006"
              }
            ]
          },
          "method": {
            "coding": [
              {
                "system": "eHealth/SNOMED/administration_methods",
                "code": "419747000"
              }
            ]
          },
          "dose_and_rate": {
            "type": {
              "coding": [
                {
                  "system": "eHealth/dose_and_rate",
                  "code": "'ordered'"
                }
              ]
            },
            "dose_range": {
              "low": {
                "value": 0,
                "unit": "mg",
                "system": "eHealth/ucum/units",
                "code": "mg"
              },
              "high": {
                "value": 0,
                "unit": "mg",
                "system": "eHealth/ucum/units",
                "code": "mg"
              }
            },
            "rate_ratio": {
              "numerator": {
                "value": 0,
                "unit": "mg",
                "system": "eHealth/ucum/units",
                "code": "mg"
              },
              "denominator": {
                "value": 0,
                "unit": "mg",
                "system": "eHealth/ucum/units",
                "code": "mg"
              }
            }
          },
          "max_dose_per_period": {
            "numerator": {
              "value": 0,
              "unit": "mg",
              "system": "eHealth/ucum/units",
              "code": "mg"
            },
            "denominator": {
              "value": 0,
              "unit": "mg",
              "system": "eHealth/ucum/units",
              "code": "mg"
            }
          },
          "max_dose_per_administration": {
            "value": 0,
            "unit": "mg",
            "system": "eHealth/ucum/units",
            "code": "mg"
          },
          "max_dose_per_lifetime": {
            "value": 0,
            "unit": "mg",
            "system": "eHealth/ucum/units",
            "code": "mg"
          }
        }
      ],
      "rejected_at": "2022-01-28",
      "rejected_by": "e8e5a969-74d8-4620-8496-f5e41f2e8312",
      "reject_reason": "Incompatible drugs",
      "reject_reason_code": "PATIENT_REJECT",
      "is_blocked": false,
      "block_reason": "Підозра на фрод",
      "block_reason_code": "WRONG_QTY_DRUG",
      "priority": "routine",
      "prior_prescription": {
        "identifier": {
          "type": {
            "coding": [
              {
                "system": "eHealth/resources",
                "code": "medication_request"
              }
            ]
          },
          "value": "9183a36b-4d45-4244-9339-63d81cd08d9c"
        }
      },
      "container_dosage": {
        "system": "MEDICATION_UNIT",
        "code": "ML",
        "value": 4
      }
    },
    "dispensed_at": "2017-08-17",
    "medical_program": {
      "id": "c7d52544-0bd4-4129-97b0-2d72633e0490",
      "name": "Доступні ліки",
      "medical_program_settings": {
        "care_plan_required": true,
        "employee_types_to_create_medication_request": [
          "SPECIALIST",
          "DOCTOR"
        ],
        "skip_mnn_in_treatment_period": true,
        "skip_employee_validation": true,
        "speciality_types_allowed": [
          "ENDOCRINOLOGY",
          "PEDIATRIC_NEUROLOGY"
        ],
        "conditions_icd10_am_allowed": [
          "A00.0",
          "A00.1"
        ],
        "conditions_icpc2_allowed": [
          "A01",
          "A02"
        ],
        "providing_conditions_allowed": [
          "INPATIENT",
          "OUTPATIENT"
        ],
        "medication_request_max_period_day": 90,
        "skip_medication_request_employee_declaration_verify": true,
        "skip_medication_request_legal_entity_declaration_verify": true,
        "multi_medication_dispense_allowed": true,
        "skip_medication_dispense_sign": true,
        "medication_request_notification_disabled": true,
        "skip_contract_provision_verify": true,
        "medication_dispense_period_day": 90
      },
      "medical_program_settings_text": "Some text",
      "is_active": true,
      "medication_dispense_allowed": true,
      "medication_dispense_allowed_text": "Some text",
      "medication_request_allowed": true,
      "medication_request_allowed_text": "Some text",
      "type": "MEDICATION",
      "funding_source": "NHS",
      "mr_blank_type": "F-1",
      "inserted_at": "2017-04-20T19:14:13Z",
      "inserted_by": "e1453f4c-1077-4e85-8c98-c13ffca0063e",
      "updated_at": "2017-04-20T19:14:13Z",
      "updated_by": "2922a240-63db-404e-b730-09222bfeb2dd"
    },
    "status": "NEW",
    "inserted_at": "2017-04-20T19:14:13Z",
    "updated_at": "2017-04-20T19:14:13Z"
  }
}

HTTP status codes

	Response code	HTTP Status code	Message	Description
1	Базові
2		401	Invalid access token	Недійсний токен доступу
3		403	Your scope does not allow to access this resource. Missing allowances: medication dispense:read	Для вашої ролі відсутній доступ до цього ресурсу. Необхідний доступ на отримання інформації про відпущені рецепти
4		403	Access denied	У доступі відмовлено
5		404	not_found	не знайдено
6	Специфічні
7

Post-processing processes

N/A

Technical modules where the method is used

Title
No content found

Versions Compared

Old Version 1

New Version Current

Key

Properties of a REST API method document

Purpose

Logic

Preconditions

Configuration parameters

Dictionaries

Input parameters

Request structure

Headers

Request data validation

Authorize

Validate Person

Validate Medication dispense

Validate User

Response structure examples

HTTP status codes

Post-processing processes

Technical modules where the method is used

Page Comparison

Versions Compared

Old Version 1

New Version Current

Key

Properties of a REST API method document

Purpose

Logic

Preconditions

Configuration parameters

Dictionaries

Input parameters

Request structure

Headers

Request data validation

Authorize

Validate Person

Validate Medication dispense

Validate User

Response structure examples

HTTP status codes

Post-processing processes

Technical modules where the method is used