Properties of a REST API method document
Document type
Метод REST API
Document title
REST API Block Medication Request [API-005-008-002-0155]
Guideline ID
GUI-0011
Author
@Iryna Lishtaba (SoE eHealth)
Document version
1
Document status
DRAFT
Date of creation
03.03.2025
Date of update
03.03.2025
Method API ID
API-005-008-002-0155
Microservices (namespace)
IL
Link на API-специфікацію
ESOZ · Apiary
Resource
{{host}}/api/medication_requests/{{id}}/actions/block
Scope
medication_request:block
Protocol type
REST
Request type
PATCH
Sync/Async
Sync
Public/Private
Public
Purpose This WS is designed to block previously created Medication request with indicating block_reason_code and block_reason
Key points Only authenticated and authorized user with an appropriate scope can block Medication request.
Medication request can be blocked only from the ‘ACTIVE' status.
Logic Update Medication request in OPS DB:
set is_blocked = true
set block_reason_system = $.block_reason_system
set block_reason_code = $.block_reason_code
set block_reason = $.block_reason
set updated_by = user_id
set updated_at = now()
set block_legal_entity_id = legal entity id out of token
Send SMS for person
If Medication request has program with medical program setting request_notification_disabled = true , then don't send SMS.
Else:
Get authentication_method of person from MPI
If authentication_method == OTP, then send SMS to a person from Medication request:
Generate SMS text
get template from block_template_sms parameter
enrich template with data from Medication request
Send SMS to a person
Add new record in Event manager:
event_type
StateChangeEvent
entity_type
MedicationRequest
entity_id
$.id
properties.is_blocked.new_value
true
event_time
$.update_at
changed_by
$.changed_by
Configuration parameters N/A
Dictionaries MEDICATION_REQUEST_BLOCK_REASON
MEDICATION_REQUEST_INTENT
MEDICATION_REQUEST_CATEGORY
MEDICATION_REQUEST_PRIORITY
eHealth/SNOMED/additional_dosage_instructions
eHealth/SNOMED/anatomical_structure_administration_site_codes
eHealth/SNOMED/route_codes
eHealth/SNOMED/administration_methods
eHealth/SNOMED/dose_and_rate
eHealth/ICD10_AM/condition_codes
eHealth/ICPC2/condition_codes
ADDRESS_TYPE
SETTLEMENT_TYPE
STREET_TYPE
PHONE_TYPE
DIVISION_TYPE
POSITION
MEDICATION_FORM
MEDICATION_UNIT
eHealth/clinical_impression_patient_categories
LICENSE_TYPE
FUNDING_SOURCE
MR_BLANK_TYPES
MEDICATION_REQUEST_REJECT_REASON
Input parameters
1 id
String
Medication Request identifier
d290f1ee-6c54-4b01-90e6-d701748f0851
Request structure See on API-specification
Example
{
"block_reason": "перевищено норми відпуску",
"block_reason_code": "WRONG_QTY_DRUG"
}Headers Headers Headers
Request data validation Validate request Validate request using JSON schema
in case of error - return 422
Validate Medication request Get Medication request identifier from the URL. Check Medication request exists in OPS DB
in case of error - return 404 ("Medication request does not exist").
Validate user Medication Request blocking is allowed for user if he has one of the following active and approved employee that:
is an author of the Medication request (medication_request.employee_id);
has an approval on write Care plan if Medication request based on the Care plan (medication_request.based_on);
is Med_Admin from legal entity where Medication request is created;
in case of error - return 409 ("Only an author, employee with approval on care plan or med_admin from the same legal entity can block medication request").
Validation transition Get Medication request by $.id in OPS DB. Check that Medication request status = ‘ACTIVE’
in case of error - return 409 ("Medication request must be in active status").
Get Medication request by $.id in OPS DB. Check that Medication request is not blocked, i.e. is_blocked = false
in case of error - return 409 ("Medication request is already blocked").
Validate block reason Validate $.block_reason_system should be “MEDICATION_REQUEST_BLOCK_REASON ”
in case of error return 422 error ("value is not allowed in enum")
Validate $.block_reason_code is a value from MEDICATION_REQUEST_BLOCK_REASON dictionary
in case of error - return 422 ("value is not allowed in enum")
Check that $.block_reason_code is present in <EMPLOYEE_TYPE>_MEDICATION_REQUEST_BLOCK_REASON_CODES chart parameter for validated user
in case of error - return 422 ("Block reason code is not allowed for <employee_type>")
Processing N/A
Response structure examples See on API-specification
Example
{
"meta": {
"code": 200,
"url": "https://example.com/resource",
"type": "object",
"request_id": "req-adasdoijasdojsda"
},
"data": {
"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
}
}
}N HTTP status codes
1 2
404
Medication request does not exist
Електронний рецепт не існує
3
409
Medication request is already blocked.
Електронний рецепт вже заблоковано
4
409
Medication request must be in active status
Електронний рецепт має бути в статусі "Активний"
5
409
Only an author, employee with approval on care plan or med_admin from the same legal entity can block medication request
Лише автор та співробітник із доступом до плану лікування або медичний адміністратор закладу, де було створено рецепт, може заблокувати електронний рецепт
6 7
422
Block reason code is not allowed for <employee_type>
Вказана причина блокування не може бути використана <даним типом співробітника>
8
422
Value is not allowed in enum
Недопустиме значення
9
422
Request validation fails
Помилка валідації
Post-processing processes N/A
Technical modules where the method is used