/wiki/spaces/EN/pages/17591304241 (remove the link block before publishing the document)
Properties of a REST API method document
Document type | Метод REST API |
---|---|
Document title | [Document status] REST API [Назва методу] [ID методу] |
Guideline ID | GUI-0011 |
Author | @ |
Document version | 1 |
Document status | DRAFT |
Date of creation | ХХ.ХХ.ХХХХ (дата фінальної версії документа – RC або PROD) |
Date of update | ХХ.ХХ.ХХХХ (дата зміни версії) |
Method API ID | API-001007-001011-001-00010475 |
Microservices (namespace) | MPI |
Component | Auth |
Component ID | COM-001007-001011 |
Link на API-специфікацію | |
Resource | {{host}}//api.ehealth.gov.ua/api/patients/id/encounter_package |
Scope | |
Protocol type | REST |
Request type | |
Sync/Async | |
Public/Private |
Purpose
This WS allows to mark Composition as entered_in_error.
Key points
Only an employee who registered a Composition, employee from the same legal entity, or employee that has an approval to mark the Composition as as entered_in_error are able to perform this action.
Request should be signed with DS.
Composition is marked as entered-in-error asynchronously.
Logic
Service logic
Create job and return it’s id.
Update Composition record with following:
status = $.status
status_reason = $.status_reason
explanatory_letter =$.explanatory_letter
updated_at = current datetime
updated_by = user_id from token
Send SMS to patient with composition number via template
MARK_IN_ERROR_{{COMPOSITION_TYPE}}_COMPOSITION_SMS_TEMPLATE
If $.authorize_with is submitted - use it as patient’s authentication method
If $.authorize_with is not submitted - determine patient's default authentication method as described atDetermination of a default authentication method and return person's active auth_methods
Configuration parameters
Description of the configuration parameters that are used when processing a request in the system
Dictionaries
Provides a list of links to dictionaries that are available in Confluence
Input parameters
Description of input parameters
Input parameter | Mandatory | Type | Description | Example | |
---|---|---|---|---|---|
1 | composition_id | M | String ($uuid) (path) | Composition object ID | 89678f60-4cdc-4fe3-ae83-e8b3ebd35c59 |
2 |
|
|
|
|
|
Request structure
See on API-specification (посилання на сторінку з API-специфікацією)
Description of the REST API request structure, example
Expand | ||
---|---|---|
| ||
|
Headers
Key | Value | Mandatory | Description | Example | |
---|---|---|---|---|---|
1 | Content-Type | application/json | M | Тип контенту | Content-Type:application/json |
2 | Authorization | Bearer c2778f3064753ea70de870a53795f5c9 | M | Перевірка користувача | Authorization:Bearer c2778f3064753ea70de870a53795f5c9 |
3 |
|
|
|
|
|
Request data validation
Validate Digital Sign
Validate request is signed
in case of error - return 422 (“Invalid signed content”)
Check DS is valid and not expired
Validate that DS belongs to the user
Check that DRFO from DS and user's party.tax_id matches
in case of error - return 409 (“Does not match the signer drfo“)
Validate legal entity
Extract client_id from token
Check legal entity status (status = ACTIVE)
In case of error - return 409 ('client_id refers to legal entity that is not active')
Validate the Composition belongs to the legal entity where the current user works
Check $.composition.custodian==token.client_id
in case of error - return 409 ("User is not allowed to perform actions with an enity that belongs to another legal entity")
Validate user
Cancelation of a Composition is allowed for a user if he has one of the following active and approved employee that:
is an attester of the Composition (Composition.attester)
has a Med_Admin employee type and belong to same legal entity
has an approval granted by the patient with access_level:write for the Composition resource (approvals.granted_resources) and has a DOCTOR or SPECIALIST employee type
in case of error - return 409 ("Employee is not the one who registered the Composition, doesn't have an approval or required employee type")
Validate data consistency
Ensure that submitted Composition relates to the Patient (from URL)
in case of error - return 404 (not found)
Validate status transition
Check Composition’s status is not entered-in-error
in case of error - return 409 ('Composition in status <status> cannot be marked as entered-in-error ')
Validate Composition mark-in-error term
Get config parameter COMPOSITION_MARK_IN_ERROR_TERM, where Configuration.type=Composition.type and Configuration.category=Composition.catergory
Validate today >= (Composition.date+COMPOSITION_MARK_IN_ERROR_TERM.min)
Validate today <= (Composition.date+COMPOSITION_MARK_IN_ERROR_TERM.max)
Return 422 ("Difference between Composition date and todays date must be in range of <min value> and <max value> days") in case of error
Validate request
Validate request by schema and return 422 error code with the list of validation errors in case of fails. User fills following fields in the request:
1. Status reason
1.1 Validate value in the field $.status_reason, CodeableConcept type, required.
Check that value is in allowed values from
COMPOSITION_CANCELLATION_REASONS
dictionary.in case of error - return 422 ('value is not allowed in enum')
1.2 Validate value in the field $.status_reason corresponds to the config
Get config parameter COMPOSITION_MARK_IN_ERROR_STATUS_REASON, where Configuration.type=Composition.type and Configuration.category=Composition.catergory
Check that value is in allowed values from COMPOSITION_MARK_IN_ERROR_STATUS_REASON
in case of error - return 422 ('Invalid status reason for such composition type and category')
2. Status
The target status value must be submitted in the order of display in the signed content (media storage)
Validate $.status is entered_in_error
in case of error - return 422 ("value is not allowed in enum")
3. explanatory_letter
Validate explanatory_letter is not an empty
in case of error - return 422 ("explanatory_letter can not be empty")
Validate content
Signed content must match to the Composition from DB in order to be canceled
Render the Composition from DB
Exclude $status, $.status_reason, $.explanatory_letter from signed content
Compare rendered Composition and signed content
In case both object doesn't match - return 422 ('Signed content doesn't match with previously created Composition')
Processing
A list of processes related to receiving, changing or transmitting data according to the logic defined in the REST API
Response structure examples
See on API-specification (посилання на сторінку з API-специфікацією)
Description of the REST API response structure, example
Expand | ||
---|---|---|
| ||
|
HTTP status codes
Response code | HTTP Status code | Message | Internal name | Description | |
---|---|---|---|---|---|
1 | Базові | ||||
2 | 401 | Invalid access token | |||
3 |
| 401 | Unauthorized |
| Помилка підтвердження |
4 | 403 | Access denied. Party is not verified | |||
5 | 403 | Your scope does not allow to access this resource. Missing allowances: composition:mark_in_error | |||
6 | 1000 | 404 | Composition not found | COMPOSITION_NOT_FOUND_404 | Не знайдено медичний висновок |
7 | 404 | not found | |||
8 | 409 | client_id refers to legal entity that is not active | |||
9 | 409 | Composition in status <status> cannot be marked as entered-in-error | |||
10 | 409 | Does not match the signer drfo | |||
11 | 409 | Employee is not the one who registered the Composition, doesn't have an approval or required employee type | |||
12 | 409 | User is not allowed to perform actions with an enity that belongs to another legal entity" | |||
13 | 422 | Difference between Composition date and todays date must be in range of <min value> and <max value> days | |||
14 | 422 | explanatory_letter can not be empty | |||
15 | 422 | Invalid signed content | |||
16 | 422 | Invalid status reason for such composition type and category | |||
17 | 422 | Signed content doesn't match with previously created Composition | |||
18 | 422 | value is not allowed in enum | |||
19 | Специфічні | ||||
20 |
| 422 | Only for active MPI record can be created medication request! |
|
|
Post-processing processes
Description of actions performed on data after processing
Technical modules where the method is used
List of pages describing technical modules where the method is used
Название | ID ТМ | Статус |
---|---|---|
TM0112 | ||