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

Response structure examples

Description of the REST API response structure, example

...

...

HTTP status codes

...

Response code

...

HTTP Status code

...

Message

...

Internal name

...

Description

...

Базові

...

1000

...

404

...

Composition not found

...

COMPOSITION_NOT_FOUND_404

...

Не знайдено медичний висновок

...

401

...

Unauthorized

...

Помилка підтвердження

...

Специфічні

...

Properties of a REST API method document

Purpose

This WS is used to create Declaration Request (as part of Declaration creation process) via new api.

Створення декларації (версія 3)

Key points

1. This method method allows to create a declaration only for an existing person.

2. To create declaration request based on active declaration in reorganized legal entity, parent_declaration_id must be passed in request.

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

Request structure

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

Description of the REST API request structure, example

Headers

Request data validation

Validate request using JSON schema

Validate Legal Entity Type

Validate legal entity from token:  legal_entities.type should be in DECLARATION_REQUEST_LEGAL_ENTITY_TYPES("MSP,PRIMARY_CARE,MSP_PHARMACY") and legal_entities.status =='active' 

Validate doctor

...

Get employee details

Invoke Get employee details

Validate Response $.data.employee_type == DOCTOR

Take the doctor_id and the division_id from the token

Validate person 

• validate person_id UUID

  • in case error return 422

• search person by person_id in MPI 

  • in case error return 404, "Such person doesn't exist"

• validate person.auth_method != NA

  • in case error return 422, "Person must have authentication method"

• validate person.status = ‘active’ and is_active =true

  • in case error return 404, "Such person doesn't exist"

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 authorize_with

The person can pass the id of his auth_method which he wants to confirm the create declaration request. The necessary auth method can be found by making Get person's auth methods

1. validate auth_method.id is UUID

   1. in case error return 422

2. search auth method in MPI.person_authentication_method

   1. in case error return 422, "such authentication method doesn't exist"

3. search auth method of this person where  MPI.person_authentication_method.person_id = $.person.id

   1. in case error return 422, "such authentication method does not belong to this person"

4. validate that auth_method.type != NA

   1. in case error return 422, "Сannot be confirmed by a method with type= NA. Use a different method."

5. validate that this method is active ( authentication_method.ended_at > now() and is_active = true)

This field is optional and set in il.declaration_reques.authentication_method_current.

If person request doesn't have this field, then choose that method which is returned from mpi as person's default method

Validate parent declaration

• check that parent declaration exists and in status ‘active’

  • in case of error - return 404 (‘Active parent declaration was not found’)

• check that the parent declaration belongs to a person (person_id of parent declaration and person_id from request are the same)

  • in case of error - return 409 (‘Parent declaration does not belong to this person’)

• check that the legal entity of parent declaration and the current legal entity are in reorganization process with types ACCESSION, MERGING, DIVIDING, SEPARATING (request: select * from related_legal_entities where is_active=true and merged_from_id=parent_declaration_id.legal_entity_id and merged_to_id=employee_id.legal_entity_id and type in (‘ACCESSION’, ‘MERGING’, ‘DIVIDING’, ‘SEPARATING’); returns at least one record)

  • in case of error - return 409 (‘Legal entities of parent declaration and current are not in reorganization process’)    

• check that party_id of employee from parent declaration and party_id of current employee are the same

  • in case of error - return 409 (‘Employee of parent declaration and current employee are not the same’)

This field is optional and set in il.declaration_reques.parent_declaration_id.

If parent_declaration_id is passed in request, authorize_with validation and processing must be skipped, created declaration request will be processed without patients involvement.

Get global parameters

Invoke Global parameters to get following parameters:

• ADULT_AGE

• DECLARATION_TERM

• no_self_auth_ag

Calculate patient age

Calculate patient age

age = MONTHS_BETWEEN (now(), $.mpi.person.birth_date) / 12

Check that doctor speciality meets the patient age requirements

1. Get doctor's speciality_officio (speciality object where speciality_officio == true)

2. Check age requirements according to global parameters

Validate confidant person

If person age < prm.global_parameters.no_self_auth_age check existence of confidant_person

• in case error return 422 - msg "Confidant person is mandatory for children"

Processing

Search pending declaration requests

Search declarations in IL_DB.declaration_requests to prevent requests duplication:

where IL.Declaration_request.mpi_id = :($.person.id) and status in ('NEW' or 'APPROVED)
Cancel declaration requests

Change status and status reason of all found declaration requests:

• status: CANCELED

• status_reason: request_cancelled

SET   IL_DB.declaration_requests.status = 'CANCELED'
WHERE IL_DB.declaration_requests.id IN (:LIST)

Calculate declaration end/start date

Declaration 

Start date:

start_date = Current_date()

End date:

if (person.age < prm.global_parametrs.adult_age)&(doctor.speciality = PEDIATRICIAN) {
  end_date = min(birth_date + prm.global_parametrs.adult_age - 1d, start_date + declaration_term - 1d);
} else {
  end_date = start_date + declaration_term - 1d;
}

Save declaration request

1. Insert record to IL.declaration_request:

   1. status 'NEW'

   2. is_shareable: false

Generate upload URL

If auth_method_requests.auth_method_current = OFFLINE

• URL for person.documents

Depending on the payload system generates list of signed urls for document scan-copies upload.

Signed URLs to be expired after some period of time (configurable `SECRETS_TTL`, розташування на Gitlab: (ael.api/docs/Centrul Național de Mediu )). If it has been expired - new declaration request should be created.

Each link is generated for one one-page document in jpeg format. Document should be no more than 10MB.

Set auth_method_current

Get parent_declaration_id from il.declaration_requests.parent_declaration_id.

If parent_declaration_id is null, set default auth method of person on IL.auth_method_request.auth_method_current - use function in mpi, that return default auth method.

If auth_method_current = NA - return Error "person authentication method is undefined".

If parent_declaration_id is not null, set auth_method_current = NA (request is processed without patients involvement).

Generate verification code

If auth_method_requests.auth_method_current = OTP 

Invoke Initialize OTP to generate one time password and send it where auth_method_requests.auth_method_current = OTP.

cURL example

curl -X POST \
  http://localhost:4000/verifications \
  -H 'content-type: application/json' \
  -d '{
  "phone_number": "+380936235985"
}'

Generate human readable declaration number

• Use algorithm to generate declaration_number

• Declaration number should consist of a 4 serial symbols and 8 number symbols and looks like XXXX-12H4-245D

• Add field to ops.declarations and il.declaration_requests - declaration_number 

• Add declaration_number to print out form

Validate uniqueness of human readable declaration number

• generate declaration_number

• Search declaration_number in declaration_requests.declaration_number

• if exists = go to 'generate declaration_number'

• else save declaration_number to declaration_request

Response structure examples

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

Description of the REST API response structure, example

HTTP status codes

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

...