ЕСОЗ - публічна документація
RC_Create approval v2
Purpose
This WS is designed to create approval on entity, which aggregate other entities (episode_of_care, diagnostic_report, care_plan), OR forbidden group OR diagnoses group, OR on service_request including it’s permitted_resources OR on cancel for encounter and procedure.
Approvals are processed in the async way.
Only authenticated and authorized employees with appropriate scope can create approval.
Specification
Link | |
Resource | /api/patients/{{patient_id}}/approvals |
Scope | approval:create |
Components | API paragraph not found |
Microservices | API paragraph not found |
Protocol type | REST |
Request type | POST |
Sync/Async | Async |
Logic
Method to create approval: time-limited access to user's resources. It can be processed in both sync and async methods depends on Server decision.
Input parameters
Input parameter | Values | Type | Description | Example |
---|---|---|---|---|
patient_id |
| String | mpi_id. Required | aff00bf6-68bf-4b49-b66d-f031d48922b3 |
Request structure
See on Apiary
Example:
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 = 'approval:create ')
return 403 (“Your scope does not allow to access this resource. Missing allowances: approval:create ”) in case of invalid scope(s)
Headers
Наприклад:
Content-Type:application/json
Authorization:Bearer d368a4b0-4a0e-457a-b267-32359fa6288f
Request data validation
Validate user
Granted_to.employee_id should be active
in case of error - return 422 “Should be active“
Check if employee from the same legal entity as user:
client_id from token should be linked with employee_id from granted_to object.
in case of error - return 422 “Employee <employee_id> doesn't belong to your legal entity“
Validate resources or block of resources
Approvals are processed in the async way
Validate resources
if episode_of_care is presented in request as the code of resource
Check episode_of_care in the request exists and is in active or closed status in DB
in case of error return - 422 (Episode is canceled)
if diagnostic_report is presented in request as the code of resource
Check diagnostic_report block in the request exists and is in final status in DB
in case of error return - 422 (Diagnostic report in \"entered_in_error\" status can not be referenced or Diagnostic report with such id is not found)
if care_plan is presented in request as the code of resource
Check care_plan in the request exists in DB
in case of error return - 422 (Care plan with such id is not found)
Check there no other objects in request
in case of error return - 422 (Approval for care plan can not contain other entities)
if encounter is presented in request as the code of resource
Check encounter in the request exists in DB
in case of error return - 422 (not found)
if procedure is presented in request as the code of resource
Check procedure in the request exists in DB
in case of error return - 422 (not found)
Validate service_request
If service_request block is presented in request
Get Service_request details (only in active status)
use Response.permitted_resources as resources for approval(could be episode or diagnostic_report).
Validate forbidden_group
if forbidden_group block is presented in request
Check forbidden group in the request exists and is_active in DB
in case of error return - 404 (not found)
Validate patient
if patient block is presented in request
Get patient_id from URL:
Check person_id from the request equal to the patient_id from URL
in case of error return - 404 (“Approval for one patient can not be created in another patient’s context”)
exists and is_active in DB
in case of error return - 404 (Person is not found)
Validate block child_resource
if child_resource is not empty:
validate that access_level == read
in case of error return - 422 ("$.access_level. value is not allowed in enum")
check that $.child_resource.identifier.value context is equal to $.resource.identifier.value
in case of error return - 422 (Child resource context id is not equal to granted resource id)
validate that service_requests / forbidden_groups / diagnoses_group / patients are not filled
in case of error return - 422 (schema does not allow additional properties)
validate that resources max items = 1
in case of error return - 422 ($.resources.expected a maximum of 1 items but got 2)
Validate person authentication_method
Check patient_id:
if belongs to person, then GET auth_method from MPI using {patient_id}
If it's OTP:
send SMS to the auth_phone via otpч_verification service POST /verifications
save approval to DB
save authentication_method_current.type and number to DB
return authentication_method_current.type = OTP
If it is offline
save approval to DB
save authentication_method_current.type and number to DB
return authentication_method_current.type = offline
if it is null:
return error 409 (Person does not have active authentication method)
if belongs to preperson:
save approval to DB
set approval status = active
set approval urgent = null
Validate access_level
Validate that access_level correspond to granted_resources:
In case error return 422 ("Resource types [\"$.granted_resources[].code\"] not allowed to use write access_level")
block | granted_resources | access_level | access to | reason |
---|---|---|---|---|
resources | episode_of_care | read | Reading all the data of specified in approval episode | null |
diagnostic_report | read | Reading all the data of specified in approval diagnostic report | null | |
diagnostic_report | write | Canceling diagnostic report package | ||
care_plan | read | Reading all the data of specified in approval care plan | null | |
care_plan | write | Creating activities for care plan, cancelling medication requests or recalling/cancelling service requests based on care plan | ||
encounter | write | Canceling encounter data package | null | |
procedure | write | Canceling procedure | null | |
child_resources | diagnostic_report | read | Reading all the data of specified in context for diagnostic_report | null |
encounter | Reading all the data of specified in context for encounter | null | ||
condition | Reading all the data of specified in context for condition | null | ||
observation | Reading all the data of specified in context for observation | null | ||
activity | Reading all the data of specified in context for activity | null | ||
clinical_impression | Reading all the data of specified in context for clinical_impression | null | ||
allergy_intolerance | Reading all the data of specified in context for allergy_intolerance | null | ||
immunization | Reading all the data of specified in context for immunization | null | ||
device | Reading all the data of specified in context for device | null | ||
risk_assessment | Reading all the data of specified in context for risk_assessment | null | ||
procedure | Reading all the data of specified in context for procedure | null | ||
service_request | episode_of_care | read | Reading data from granted_resources in approval service request | service_request |
diagnostic_report | read | |||
forbidden_group | forbidden_group | read | Reading all the medical events with items (codes/services/service_groups) of specified in approval forbidden groups | null |
diagnoses_group | episode_of_care array | read | Reading all data of episodes with diagnoses_history.codes that specified in approval diagnoses group | null |
patient_id | patient_id | read | Reading all the data of specified patient | null |
Validate authorize_with
The patient can pass the id of his auth_method which he wants to confirm the approval. The necessary auth method can be found by making Get person's auth methods
validate auth_method.id is UUID
in case error return 422
search auth method in MPI.person_authentication_method
in case error return 422, "such authentication method doesn't exist"
search auth method of this patient where MPI.person_authentication_method.person_id = $.patient.id
in case error return 422, "such authentication method does not belong to this person"
validate if auth_method.type = NA
error return 422, "Сannot be confirmed by a method with type= NA. Use a different method."
validate that this method is active ( authentication_method.ended_at > now() and is_active = true)
This field is optional and set in new field authorize_with
and save type
and phone_number
in approvals.urgent.authentication_method_current.
If approval doesn't have this field, then choose that method which is returned from mpi as person's default method.
Processing
Cancel existing approvals
Search if there exists active and not expired approvals with current patient_id, for the same granted_resources, granted_to and access_level as in request.
If found - set their status to
terminated
. Also, set updated_at and updated_by to current user.
Additional logic
All the approvals in status "new" should be deleted 12 hours after creation - env. configuration parameter
All approvals with forbidden_group has its own expires_at config parameter - env. configuration parameter
All approvals with care_plan has its own expires_at config parameter - env. configuration parameter
All approvals with patient has its own expires_at config parameter - env. configuration parameter
Approvals with child_resources will be created ON entity which is context of this child_resources
For approvals on child_resource with resource and on service_request:
set child resource to block reason
set service_request to block reason
Check if for granted_resource and\or for reason there are forbidden groups
if there are items from forbidden group
check type of authentication_method for patient
If type = 'OTP' send SMS (Код <code>: доступ на записи ВІЛ та/або РПП https://bit.ly/nszu1677a)
if there NO forbidden group items
check type of authentication_method for patient
If type = 'OTP' send SMS (Код авторизації дій в системі eHealth: <code>')
Response structure
See on Apiary
Example:
Post-processing processes
API paragraph not found
HTTP status codes
HTTP status code | Message | What caused the error |
---|---|---|
201 | use payload from response | sync |
202 | use Get job details to get processing result. Response payload will be returned in the job details | async: default method |
401 | Invalid access token |
|
403 | Your scope does not allow to access this resource. Missing allowances: approval:create |
|
404 |
|
|
409 | Person does not have active authentication method |
|
422 |
| 7. Check encounter in the request exists in DB in case of error return failed 8. Check procedure in the request exists in DB in case of error return failed 14. Validation of the auth_method.id is UUID failed
|
ЕСОЗ - публічна документація