/
REST API Get Medication Requests by Search Params [API-005-008-002-0146]

ЕСОЗ - публічна документація

REST API Get Medication Requests by Search Params [API-005-008-002-0146]

By Kateryna Yakovleva
6 min

Properties of a REST API method document

Document type

Метод REST API

Document title

REST API Get Medication Requests by Search Params [API-005-008-002-0146]

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-0146

Microservices (namespace)

IL

Link на API-специфікацію

ESOZ · Apiary

Resource

{{host}}/api/persons/{{person_id}}/medication_requests

Scope

medication_request:read

Protocol type

REST

Request type

GET

Sync/Async

Sync

Public/Private

Public

Purpose

This WS is designed to return records about Medication requests in person context by search parameters

Preconditions

MRs should be created

Logic

Технічний опис бізнес-процесу виписування рецепту в ЕСОЗ (загальний процес для усіх рецептурних ЛЗ, в т.ч. і тих, які підлягають реімбурсації)

Процеси роботи з випискою електронних рецептів

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

Input parameter

Mandatory

Type

Description

Example

Input parameter

Mandatory

Type

Description

Example

1

person_id

M

String

person_id of a patient

5e661b15-a39a-4713-b18e-ba03a4a48ecc

2

legal_entity_id

O

String

legal entity identifier

d290f1ee-6c54-4b01-90e6-d701748f0851

3

employee_id

O

String

user_id of a doctor

7124259c-eeb1-4cbb-acac-ada2162675d1

4

status

O

Enum

  • ACTIVE

  • COMPLETED

  • EXPIRED

  • REJECTED

ACTIVE

5

request_number

O

String

Public medication request human readable number

0000-243P-1X53-EH38

6

created_from

O

String

Medication request creation date period start, which is determined by the external system. Format DATE '2017-08-17'

2017-08-17

7

created_to

O

String

Medication request creation date period end, which is determined by the external system. Format DATE '2017-08-30'

2017-08-30

8

medication_id

O

String

innm dosage id

b075f148-7f93-4fc2-b2ec-2d81b19a9b5b

9

intent

O

String

Medication request intent

order

10

care_plan_id

O

String

care plan identifier

8838982b-6a77-4cb5-87cd-cdb82eb55364

11

encounter_id

O

String

encounter identifier

7075e0e2-6b57-47fd-aff7-324806efa7e5

12

episode_id

O

String

Unique episode identifier, look into episode in encounter

6f305d0e-1758-4920-9167-d4f97225ad7e

13

medical_program_id

O

String

Internal medical program ID, a UUID string

9a2fc263-6029-4b2b-b40a-66f4435509b7

14

started_at_from

O

String

tart date of the period of treatment initiation period. Format DATE '2017-08-16

2017-08-16

15

ended_at_from

O

String

End date of the period of treatment initiation period. Format DATE '2017-09-16'

2017-09-16

16

started_at_to

O

String

Start date of the period of treatment ending period. Format DATE '2017-08-20'

2017-08-20

17

ended_at_to

O

String

End date of the period of treatment ending period. Format DATE '2017-09-20'

2017-09-20

18

dispense_valid_from_start

O

String

Start date of the period of dispense issue date. Format DATE '2017-02-17'

2017-02-17

19

dispense_valid_from_end

O

String

End date of the period of dispense issue date. Format DATE '2017-02-19'

2017-02-19

20

dispense_valid_to_start

O

String

Start date of the period of dispense expiry date. Format DATE '2017-03-26'

2017-03-26

21

dispense_valid_to_end

O

String

nd date of the period of dispense expiry date. Format DATE '2017-03-30

2017-03-30

22

page

O

Number

Page number

2

23

page_size

O

Number

A limit on the number of objects to be returned, between 1 and 300. Default: 50

50

Request structure

See on API-specification

Headers

Headers

Request data validation

Authorize

  1. Verify the validity of access token

    1. Return (401, 'Invalid access token') in case of validation fails

  2. Verify that token is not expired

    1. in case of error - return (401, 'Invalid access token')

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

    1. Return (403, 'Your scope does not allow to access this resource. Missing allowances: medication_request:read') in case of invalid scope(s)

Access to the resource is also managed by ABAC rules (EN).

Processing

Service returns all Medication requests related to the person filtered by submitted parameters:

  1. Get all Medication requests by person_id from medication_requests (OPS database).

  2. Validate data consistency:

    1. Ensure that requested Medication requests have ABAC context

      1. Return 403 ('Access denied') in case of error.

  3. Filter list above by submitted search parameters.

  4. Render a response according to specification with found Medication requests entities.

Response structure examples

See on API-specification

{ "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", "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 } } ], "paging": { "page_number": 2, "page_size": 50, "total_entries": 1000, "total_pages": 23 } }

HTTP status codes

Response code

HTTP Status code

Message

Internal name

Description

Response code

HTTP Status code

Message

Internal name

Description

1

Базові

2

 

401

Invalid access token

 

Недійсний токен доступу

3

 

403

Access denied

 

Доступ заборонено

4

 

403

Your scope does not allow to access this resource. Missing allowances: medication_request:read

 

Для вашої ролі відсутній доступ до цього ресурсу. Необхідний доступ на отримання переліку рецептів

5

Специфічні

6

 

 

 

 

 

Post-processing processes

N/A

Technical modules where the method is used

 

Related content

REST API Get Medication Requests Details [API-005-008-002-0148]
REST API Get Medication Requests Details [API-005-008-002-0148]
ЕСОЗ публічна документація
More like this
REST API Get Medication Requests in Care Plan Context [API-005-008-002-0147]
REST API Get Medication Requests in Care Plan Context [API-005-008-002-0147]
ЕСОЗ публічна документація
More like this
REST API Get Medication Request by Id by Pharmacy User [API-005-008-002-0153]
REST API Get Medication Request by Id by Pharmacy User [API-005-008-002-0153]
ЕСОЗ публічна документація
More like this
REST API Qualify Medication Request by Id [API-005-008-002-0145]
REST API Qualify Medication Request by Id [API-005-008-002-0145]
ЕСОЗ публічна документація
Read with this
REST API Get medication request requests by search params [API-005-008-003-0163]
REST API Get medication request requests by search params [API-005-008-003-0163]
ЕСОЗ публічна документація
More like this
REST API Resend Medication Request [API-005-008-002-0151]
REST API Resend Medication Request [API-005-008-002-0151]
ЕСОЗ публічна документація
Read with this

ЕСОЗ - публічна документація