| Note |
|---|
Сторінка знаходиться в процесі розробки. Інформація на ній може бути застарілою. |
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-0133
...
Microservices (namespace)
...
IL
...
Component
...
ePrescription
...
Component ID
...
COM-005-008
...
Link на API-специфікацію
...
...
Resource
...
{{host}}/api/pharmacy/medication_dispenses/{{id}}/actions/process
...
Scope
...
medication_dispense:process
...
Protocol type
...
REST
...
Request type
...
PATCH
...
Sync/Async
...
Sync
...
Public/Private
...
Public
Purpose
This method is designed to process previously created Medication dispense
Key points
Only authenticated and authorized users of a legal entity who has created Medication dispense can process Medication dispense
Medication dispense can be processed only from ‘NEW' status.
The process should be signed with DS. So, all the Medication dispense data should be submitted.
Invoke Get Medication dispense details by Pharmacy User to obtain previously created Medication dispense. In order to process dispense payment_id (optional) and payment_amount (optional, if medical program has funding sourse != NHS) should be added.
Logic
...
Save signed content to media storage
...
Update Medication dispense data in OPS DB:
set status = ‘PROCESSED’
updated_by = user_id
updated_at = now()
...
Update related Medication request data in OPS DB:
set status = ‘COMPLETED’
updated_by = user_id
updated_at = now()
...
Write changes to event manager (Medication dispense and Medication request)
Сhange Care plan activity (If related medication request has reference on Care plan, then corresponding care plan activity should be changed after Medication dispense processed):
...
Set activity status to in_progress if previous activity status was scheduled
Check the MD identifier in outcome_reference attribute of the activity:
if not found:
...
Add reference on the medication dispense resource to the outcome_reference attribute .
If quantity in the activity was set - validate $.activity.details.remaining_quantity_type:
...
select all MRR in status NEW which based on current activity
select all MR in statuses ACTIVE based on current activity
select all MD (medication dispenses) in status PROCESSED related to the Medication requests which are in status COMPLETED, REJECTED, EXPIRED
calculate:
reserved_qty as sum of medication_qty in the filtered MRR and MR list
dispensed_qty as sum of medication_qty in the filtered MD list
calculate and update remaining quantity by subtracting reserved_quantity and dispensed_qty from activity quantity
...
if $.activity.details.remaining_quantity_type = for_use than:
select all MD in status PROCESSED related to MR which based on care plan and current activity
calculate dispensed quantity in the current activity as sum of medication_qty in the filtered MD list
calculate remaining quantity by subtracting dispensed quantity from activity quantity
update remaining_quantity value in the activity with calculated value
...
If found, then skip updating activity (it means that activity has been already updated by event from current MD processing).
Preconditions
If skip_medication_dispense_sign=false, MD should be created
Configuration parameters
N/A
Dictionaries
Input parameters
...
Input parameter
...
Mandatory
...
Type
...
Description
...
Example
...
id
...
M
...
String
...
Medication Dispense Response Identifier
...
a89f6a26-4221-4597-a1d2-542d5e40b565
Request structure
See on API-specification
...
| title | Example |
|---|
...
Headers
Request data validation
Authorize
Verify the validity of access token
in case of error - 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:process')
return 403 (“Your scope does not allow to access this resource. Missing allowances: medication_dispense:process”) in case of invalid scope(s)
Validate digital signature
Validate request is signed
in case of error - return 400 (“document must be signed by 1 signer but contains 0 signatures”)
Validate that DS is valid and not expired
Validate that DS belongs to the user
Check that DRFO from DS and party.tax_id matches
in case of error - return 422 (“Does not match the signer drfo“)
Check that Last Name from DS and party.last_name matches
in case of error - return 422 (“Does not match the signer last name“).
Validate Medication dispense
Get Medication dispense identifier from the URL
Check Medication dispense exists in DB (OPS)
Return 404 ('not_found') in case of error
Check Medication dispense belongs to legal entity
Return 404 ('not_found') in case of error
Validate User
Extract user_id from token
Return 404 ('not_found') in case employee didn’t create medication dispense
Validate Care plan and Activity
It is needed to check if medication request with a program allowed to be created for specified care plan and activity.
If based_on submitted, check field has array with two values of Reference type: one is valid Care plan resource, another - Activity resource.
Verify Care plan:
It should belong to the same person as set in MRR
in case of error return 422 with msg ("Care plan not found")
It should be in active status
Verify submitted Activity:
It belongs to the Care plan.
in case of error return 422 with msg ("Activity not found")
It has activity.detail.kind=medication_request; activity.detail.product_reference=medication_id.
in case of error return 422 with msg ("Invalid activity kind")
It has scheduled, in_progress status
in case of error return 422 with msg ("Invalid activity status")
If it hasquantitythen calculateremaining quantity:select all MRR in status NEW which based on current activityselect all MR in statuses ACTIVE, COMPLETED based on current activitycalculate reserved at the moment medication quantity as sum of medication_qty in the filtered MRR and MR list, including medication_qty from current MRRcalculate remaining quantity by subtracting reserved quantity from activity quantityCheckremaining quantityis greater then or equal to zeroin case of error return 409 "The total amount of the prescribed medication quantity exceeds quantity in care plan activity"
check that medical_program_id equal to $.activity[].program
in case of error return 422 with msg ("Medical program from activity should be equal to medical program from request")
Validate started_at/ended_at of Medication request Request:
if care plan activity has detail.scheduled_timing.repeat.bounds_period - validate started_at/ended_at within bounds_period
if care plan activity has detail.scheduled_period - validate started_at/ended_at within scheduled_period
else - validate started_at/ended_at within care_plan.period
in the case of started_at/ended_at is not within care_plan.period return 422 with msg ("Invalid care plan period")
Validate signed content
Check that signed content is equal to online generated dispense with ids in DB
Do not compare:
payment_amount field
payment_id field
medication_request/legal_entity object
medication_request/division object
medication_request/employee object
medication_request/person/id field
medication_request/rejected_at field
medication_request/rejected_by field
in case error return 422 ("Signed content does not match to previously created dispense")
Validate transition
Get status of Medication dispense by $.id in OPS DB. Check that Medication dispense is in status ‘NEW’
in case of error - return 409 ("Can't update medication dispense status from {status} to PROCESSED")
For more information look at [Transferred] Medication dispense status model
Validate payment_amount
In case if medical program has funding sourse == NHS check that payment_amount is submitted and greater or equal to 0
in case of error - return 422 ("expected the value to be >= 0")
Validate division
If the medical program has no setting skip_dispense_division_dls_verify or it is set in false/null validate:
Check $.division.dls_verify == true:
In case of error - return 409 "Invalid division dls status"
else if skip_dispense_division_dls_verify = true, then skip license verification for the division
Validate related Medication request
Medication request should be active in order to process medication dispense
is_active = true
status = 'ACTIVE'
In case error - return 409 ("Medication request is not active")
Medication request should not be blocked in order to process medication dispenseis_blocked <> trueIn case of error - return 409 ("Medication request is blocked")
Check that Medication request not blocked
medication_requests.blocked_to <= now() (datetime) or NULL
in case of error - return 409 error ('Medication request is blocked')
Medication request should be up to date
medication_request.dispense_valid_from ≤ now OR medication_request.dispense_valid_to ≥ now
In case of error - return 409 ("Invalid dispense period")
Checking the status of the legal entity where the medication request was issued
status in ('ACTIVE', 'CLOSED', 'REORGANIZED')
In case of error - return 422 ("value is not allowed in enum")
Check if related medication request has reference on the Care plan - based_on attribute filled. If it has, validate following:
Care plan is not in final status.
In case of error - return 409 error (Care plan is not active)
If end_date Care plan is present then it should be less than or equal than todays date
In case of error - return 409 ("Care plan expired")
Corresponding Care plan activity is not in final status.
In case of error - return 409 error (Care plan activity should be scheduled or in_progress)
Processing
...
Save signed content to media storage
...
Update Medication dispense data in OPS DB:
set status = ‘PROCESSED’
updated_by = user_id
updated_at = now()
...
Update related Medication request data in OPS DB (if total medication_dispense quantity = medication_request.medication_qty):
set status = ‘COMPLETED’
updated_by = user_id
updated_at = now()
...
Write changes to event manager (Medication dispense and Medication request)
Сhange Care plan activity (If related medication request has reference on Care plan, then corresponding care plan activity should be changed after Medication dispense processed):
...
Set activity status to in_progress if previous activity status was scheduled
Check the MD identifier in outcome_reference attribute of the activity:
if not found:
...
Add reference on the medication dispense resource to the outcome_reference attribute.
If quantity in the activity was set - validate $.activity.details.remaining_quantity_type:
...
select all MRR in status NEW which based on current activity
select all MR in statuses ACTIVE based on current activity
select all MD (medication dispenses) in status PROCESSED related to the Medication requests which are in status COMPLETE, REJECTED, EXPIRED
calculate:
reserved_qty as sum of medication_qty in the filtered MRR and MR list
dispensed_qty as sum of medication_qty in the filtered MD list
calculate and update remaining quantity by subtracting reserved_quantity and dispensed_qty from activity quantity
...
if $.activity.details.remaining_quantity_type = for_use than:
select all MD in status PROCESSED related to MR which based on care plan and current activity
calculate dispensed quantity in the current activity as sum of medication_qty in the filtered MD list
calculate remaining quantity by subtracting dispensed quantity from activity quantity
update remaining_quantity value in the activity with calculated value
...
If found, then skip updating activity (it means that activity has been already updated by event from current MD processing).
Response structure examples
See on API-specification
...
| title | Example |
|---|
...
HTTP status codes
...
Response code
...
HTTP Status code
...
Message
...
Internal name
...
Description
...
Базові
...
...
400
...
document must be signed by 1 signer but contains 0 signatures
...
...
На документ має бути накладено 1 цифровий підпис за допомогою КЕП, проте маємо 0 цифрових підписів
...
...
401
...
Invalid access token
...
...
Недійсний токен доступу
...
...
403
...
Your scope does not allow to access this resource. Missing allowances: medication_dispense:process
...
...
Для вашої ролі відсутній доступ до цього ресурсу. Необхідний доступ на обробку, перевірку погашення рецепта
...
...
404
...
not_found
...
...
не знайдено
...
...
409
...
Medication request is not active
...
...
Рецепт не активний
...
...
409
...
Medication request is blocked
...
...
Рецепт заблоковано
...
...
409
...
Invalid dispense period
...
...
Недійсний період погашення рецепта
...
...
409
...
Care plan is not active
...
...
План лікування не активний
...
...
409
...
Care plan expired
...
...
Період дії плану лікування завершився
...
...
409
...
Care plan activity should be scheduled or in_progress
...
...
Призначення має бути у плані лікування або у роботі (не у фінальному статусі)
...
Специфічні
...
...
422
...
Does not match the signer drfo
...
...
РНОКПП користувача не співпадає з РНОКПП, зазначеним у КЕП
...
...
422
...
Does not match the signer last name
...
...
Прізвище користувача не співпадає з прізвищем, зазначеним у КЕП
...
...
422
...
Care plan not found
...
...
План лікування не знайдено
...
...
422
...
Activity not found
...
...
Призначення не знайдено
...
...
422
...
Invalid activity kind
...
...
Невірний тип призначення
...
...
422
...
Invalid activity status
...
...
Невірний статус призначення
...
...
422
...
Medical program from activity should be equal to medical program from request
...
...
Програма відшкодування у заявці на рецепт повинна бути такою ж як і в призначенні на лікарський засіб
...
...
422
...
Invalid care plan period
...
...
Недійсний період плану лікування
...
...
422
...
Signed content does not match to previously created dispense
...
...
Підписані дані не збігаються з попередньо створеною заявкою на погашення рецепта
...
...
422
...
Can't update medication dispense status from {status} to PROCESSED
...
...
Не вдається оновити статус заявки на погашення рецепта із вказаного статусу {status} на PROCESSED
...
...
422
...
expected the value to be >= 0
...
...
Очікується, що значення буде >= 0
...
...
422
...
value is not allowed in enum
...
...
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-специфікацію | |
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 | ||
|---|---|---|
| ||
|
HTTP status codes
Response code | HTTP Status code | Message | Internal name | 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 |