| Info |
|---|
REST API method / Метод REST API (настанова) (remove the link block before publishing the document) |
| Table of Contents |
|---|
Properties of a REST API method document
...
| id | page_properties_method_REST API |
|---|
...
Document type
...
Метод REST API
...
Guideline ID
...
GUI-0011
...
Author
...
@
...
Document version
...
1
...
Document status
...
DRAFT
...
Date of creation
...
ХХ.ХХ.ХХХХ (дата фінальної версії документа – RC або PROD)
...
Date of update
...
ХХ.ХХ.ХХХХ (дата зміни версії)
...
Method API ID
...
API-001-001-001-0001
...
Microservices (namespace)
...
MPI
...
Component
...
Auth
...
Component ID
...
COM-001-001
...
Link на API-специфікацію
...
...
Resource
...
{{host}}//api.ehealth.gov.ua/api/patients/id/encounter_package
...
Scope
...
Protocol type
...
Request type
...
Sync/Async
...
Public/Private
Purpose
Describe the purpose of the API method, add Key points (if necessary)
Logic
Description of the working algorithm of the API method and the interaction of services with each other add Service logic (if necessary)
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
...
composition_id
...
M
...
String ($uuid) (path)
...
Composition object ID
...
89678f60-4cdc-4fe3-ae83-e8b3ebd35c59
...
Request structure
See on API-specification (посилання на сторінку з API-специфікацією)
Description of the REST API request structure, example
...
| title | Example |
|---|
...
Headers
...
Key
...
Value
...
Mandatory
...
Description
...
Example
...
Content-Type
...
application/json
...
M
...
Тип контенту
...
Content-Type:application/json
...
Authorization
...
Bearer c2778f3064753ea70de870a53795f5c9
...
M
...
Перевірка користувача
...
Authorization:Bearer c2778f3064753ea70de870a53795f5c9
...
Request data validation
Describe the process of checking the input data transmitted in the request for compliance with the given rules and restrictions set in the API
Processing
A list of processes related to receiving, changing or transmitting data according to the logic defined in the REST API
Response structure examples
Description of the REST API response structure, example
...
| title | Example |
|---|
...
HTTP status codes
...
Response code
...
HTTP Status code
...
Message
...
Internal name
...
Description
...
Базові
...
1000
...
404
...
Composition not found
...
COMPOSITION_NOT_FOUND_404
...
Не знайдено медичний висновок
...
401
...
Unauthorized
...
Помилка підтвердження
...
Специфічні
...
422
...
| Info |
|---|
/wiki/spaces/EN/pages/17591304241 (remove the link block before publishing the document) |
| Table of Contents |
|---|
Properties of a REST API method document
| Page Properties | ||||||||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| ||||||||||||||||||||||||||||||||||||||
|
Purpose
This method must be used to cancel existing Service Request.
Logic
Відкликання направлення (entered in error)
This method must be used to cancel existing Service Request. Method receives signed message (pkcs7) that consists of signed content, digital signature and signer public key. All signature fields will be validated (including signer certificate authority)
Important
Signed content of service request must be equal to service request stored in DB. See Get Service Request details
status_reason and explanatory_letter (optional) must be added to signed content
Please see Service request (Referral) state model and Dummy Cancel Service Request for more details
Scopes required: service_request:cancel
It can be processed in both sync and async methods depends on Server decision.
Service logic
Save signed content to media storage
Update service request status to entered_in_error (update also updated_at, updated_by)
Write record to status history
Send SMS to patient (if authentication_method_current == SMS, do NOT send sms in case performer is present in SR)
Template - TBD
Async! Revoke all approvals made by this service request
if the service request is based on the activity with quantity:
Recalculate and set remaining_quantity for the activity as described at PreQualify Service Request | Validate service request
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
Input parameter | Mandatory | Type | Description | Example | |
|---|---|---|---|---|---|
| 1 | |||||
| 2 |
Request structure
See on Apiary
See on API-specification
| Expand | ||
|---|---|---|
| ||
|
Headers
Key | Value | Mandatory | Description | Example | |
|---|---|---|---|---|---|
| 1 | Content-Type | application/json | M | Тип контенту | Content-Type:application/json |
| 2 | Authorization | Bearer: {{access_token}} | Authorization:Bearer: {{access_token}} | ||
| 3 | api-key | {{secret}} | api-key: {{secret}} |
Request data validation
Authorize
Verify the validity of access token
Return (401, 'unauthorized') in case of validation fails
Verify that token is not expired
in case of error - return (401, 'unauthorized')
Check user scopes in order to perform this action (scope = 'service_request:cancel')
Return (403, 'invalid scopes') in case of invalid scope(s)
If BLOCK_UNVERIFIED_PARTY_USERS is true, then check party's data match following condition: verification_status != NOT_VERIFIED or (verification_status = NOT_VERIFIED and updated_at > current_date - UNVERIFIED_PARTY_PERIOD_DAYS_ALLOWED):
in case not match - return 403 ("Access denied. Party is not verified")
If BLOCK_DECEASED_PARTY_USERS is true, check that party is not deceased (party_verification record does not equal to: dracs_death_verification_status = VERIFIED and dracs_death_verification_reason = MANUAL_CONFIRMED):
in case of error - return 403 ("Access denied. Party is deceased")
Request to process the request using a token in the headers
Validate legal entity
Check legal entity type: it has to be in me_allowed_transactions_le_types config parameter, has status = active and nhs_verified = true
in case of error return 409 "Action is not allowed for the legal entity"
Validate digital signature
Decode content that is encrypted in an electronic digital signature.
Use Digital signature WS. Method checks digital signature and returns result.
See service specification
Ensure that digital signature is valid
Validate that requester of service request is a current user
2.1. Get token metadata
Extract user_id, client_id, client_type
2.2. Determine the party_id associated with this user_id
| Code Block |
|---|
SELECT pu.party_id FROM party_users pu
WHERE pu.user_id = :user_id; |
2.3. Determine employees related to this party_id in current MSP
| Code Block |
|---|
SELECT e.id FROM employees e WHERE e.party_id = :party_id
AND e.legal_entity_id = :client_id; |
2.4 Ensure that $.requester.identifier.value matches with user employees
Validate that DS belongs to the requester of encounter
3.1. Determine the party_id associated with requester ($.requester.identifier.value)
| Code Block |
|---|
SELECT p.tax_id FROM employees e, parties p WHERE e.party_id = p.id
AND e.id = :requester; |
Validate request using JSON Schema
Return 422 with the list of validation errors in case validation fails
Validate permission to cancel
Only doctor who signed this service request is able to cancel this service request
Implemented by DS validation (see Validate digital signature p.2)
Validate transition
Only active service request can be canceled
Get current service request status
Check that status in ('active', 'completed')
in case of error - return 409 error ('Service request in status %status% cannot be canceled')
Validate cancelation reason
Validate $.status_reason.code is a value from eHealth/service_request_cancel_reasons dictionary
in case of error - return 422 ("value is not allowed in enum")
Validate content
Signed content must match with service request in DB in order to be canceled
Render service request from DB
Exclude $.status_reason and $.explanatory_letter from signed content
Compare rendered service request and signed content
In case both object doesn't match - return 422 ('Signed content doesn't match with previously created service request')
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 Apiary
See on API-specification
| Expand | ||
|---|---|---|
| ||
|
| Expand | ||
|---|---|---|
| ||
|
HTTP status codes
Response code | HTTP Status code | Message | Internal name | Description | |
|---|---|---|---|---|---|
| 1 | Базові | ||||
| 2 | 201 | use payload from response | sync | ||
| 3 | 202 | use Get job details to get processing result. Response payload will be returned in the job details | async: default method | ||
| 4 | 403 | Access denied. Party is not verified | |||
| 5 | 403 | Access denied. Party is deceased | |||
| 6 | 403 | invalid scopes | |||
| 7 | 409 | Action is not allowed for the legal entity | |||
| 8 | 409 | Only an employee from legal entity where service request is created can cancel service request | |||
| 9 | 409 | Service request in status %status% cannot be canceled | |||
| 10 | 422 | Signed content doesn't match with previously created service request | |||
| 11 | 422 | value is not allowed in enum | |||
| 12 | Специфічні | ||||
| 13 | |||||
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
| Page Properties Report | ||||
|---|---|---|---|---|
|
...