Properties of a REST API method document

...

...

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-специфікацію

...

https://ehealthmisapi1.docs.apiary.io/#reference/public.-medical-service-provider-integration-layer/manage-client-configuration/get-client-details

...

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

...

...

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

...

Properties of a REST API method document

Purpose

Describe the purpose of the API method, add Key points (if necessary)

Logic

Service logic

1. Only authenticated and authorized user can use this service

2. Only APPROVED declaration request can be signed

3. The request can be signed only by the employee who works in the same legal entity in which the request was made.

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

Request structure

See on API-specification (посилання на сторінку з API-специфікацією)

Description of the REST API request structure, example

Headers

Request data validation

Digital signature

Digital signature validation is different depending on channel

• for channel PIS and status APPROVED there must be 2 signatures - one for patient and one for doctor

• for channel MIS and status APPROVED there must be only 1 doctor’s signature

Decode content that is encrypted in an electronic digital signature.
Use Digital signature WS. Method checks digital signature(s) and returns result.
See service specification

Validate patient’s signature

This validation must be done in different ways depending on context:

• if request is done by person itself (There is no confidant person in data_to_be_signed data_to_be_signed.person.confidant_person (or is nil)) - we must check that signer DRFO matches with person tax_id or document

• if request is done by confidant person (There is confidant person in data_to_be_signed data_to_be_signed.person.confidant_person) - we must check that signer DRFO matches with confidant person tax_id or document

Request is done by person

1. Check that DRFO in Certificate details exists and not empty

2. Check that DRFO in Certificate details is equal to Person’s tax_id

   1. Get person_id from token

   2. Get Person details using person_id

   3. Compare DRFO in Certificate with person.tax_id

      1. Convert DRFO and TAX_ID to uppercase

      2. Compare DRFO and TAX_ID as Cyrillic letters

      3. Convert DRFO to Cyrillic and compare as Cyrillic letters

   4. In case validation fails - generate 422 error

Request is done by confidant person

1. Check that DRFO in Certificate details exists and not empty

2. Check that DRFO in Certificate details is equal to Confidant Person’s tax_id

   1. Get confidant_person from data_to_be_signed.person

   2. Compare DRFO in Certificate with person.tax_id

      1. Convert DRFO and TAX_ID to uppercase

      2. Compare DRFO and TAX_ID as Cyrillic letters

      3. Convert DRFO to Cyrillic and compare as Cyrillic letters

   3. In case validation fails - generate 422 error

Validate doctor’s signature

1. Check that DRFO in Certificate details (one of) is equal to DRFO in Party

   1. Get party.tax_id using employee_id in declaration payload

   2. Compare DRFO in Certificate with party.tax_id

      1. Convert DRFO and TAX_ID to uppercase

      2. Compare DRFO and TAX_ID as Cyrillic letters

      3. Convert DRFO to Cyrillic and compare as Cyrillic letters

   3. In case validation fails - generate 422 error

Latin to Cyrillic mapping

%{"A" => "А", "B" => "В", "C" => "С", "E" => "Е", "H" => "Н", "I" => "І", "K" => "К", "M" => "М", "O" => "О", "P" => "Р", "T" => "Т", "X" => "Х"}

Validate request

1. Validate request using JSON schema (See specification)

   1. In case validation fails - generate 422 error

2. Check declaration request status

   1. If status is not APPROVED, - returned error 'Incorrect status'

Validate person verification status

• validate patient's verification_status is not equal to NOT_VERIFIED.

  • in case of error return 409, "Patient is not verified"

Validate Parent declaration

Get parent_declaration_id from IL_DB.declaration_requests.parent_declaration_id.

• If parent_declaration_id is not null, check that parent declaration exists and in status 'active'

  • In case of error - return 404 ("Active parent declaration was not found")

Check signed content

Check decoded signed content with previously created on IL.db.

SELECT data.data_to_be_signed
FROM declaration_requests
WHERE id = {:id}

In case if they are not equal - generate 422 error (message: "Signed content does not match the previously created content")

Check employee

Declaration_request can be signed by any employee with necessery scopes in equal legal_entity_id.

1. Extract legal_entity_id (client_id) from token

2. Extract employee_id from request

3. Check if $.client_id=employees.legal_entity_id 

   1. in case error return 422 

Check patient_signed flag

• If "patient_signed" is not present in request, return 422 ("required property patient_signed was not present")

• If "patient_signed"=false in request, return 422 ("Patient must sign declaration form")

• If “patient_signed”=null, check that parent_declaration_id is not null,

  • in case of error, return 422 ("Patient must sign declaration form")

Validate human readable declaration number

Search declaration_number in declarations.declaration_number.

• if exists return 422 - message 'Declaration with the same declaration_number is already exist in DB' 

Processing

Processing

Save signed declaration to media storage

1. Get url for declaration upload.

Use Request a Secret WS

1. Upload signed declaration to media storage

Update declaration request:

1. Change entity status in IL_DB.declaration_request to SIGNED

2. Set status_reason:

   1. If channel = MIS - set status_reason to doctor_signed

   2. If channel = PIS - set status_reason to doctor_approved_over_limit

3. Set updated_at - now() (Get current date-time)

4. Set updated_by - user_id (Extract user from token)

Get active declarations

Search for active declarations using MPI ID

1. If found, - terminate them and create new declaration.

   • If not found - create new declaration.

Terminate declaration

In case active declarations found - terminate all by changing status to TERMINATED.
In case parent_declaration_id of declaration request is not null - terminate parent_declaration with reason reason = 'auto_reorganization'.

Create declaration

1. Check authentication_method_current

   Code Block
   SELECT authentication_method_current FROM declaration_requests WHERE id = {:id}

   1. If "type" = "OFFLINE"

      1.  set declaration status to "PENDING_VERIFICATION"

      2. set reason to 'offline'

   2. if "type" = "OTP" - set declaration status to "ACTIVE" 

   3. if "type" = "NA" - check parent_declaration_id, if not null than set declaration status to "ACTIVE"

2. Check persons 'no_tax_id' flag

   1. if 'no_tax_id'=true and parent_declaration_id is null

      1. set declaration status to "PENDING_VERIFICATION"

      2. set reason to 'no_tax_id'

   2. if ‘no_tax_id’=true and parent_declaration_id is not null - set declaration status to "ACTIVE"

3. Create a new declaration by adding a new entity to the declarations table ops_db without declaration_id.

   1. if there is existing record in the declarations table with the same id and declaration_request_id, return ok to IL

Response structure examples

See on API-specification (посилання на сторінку з API-специфікацією)

Description of the REST API response structure, example

...

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

...