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

...

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

...

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

...

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

...

Note
Сторінка знаходиться в процесі розробки. Інформація на ній може бути застарілою.

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

id	page_properties_method_REST API

Document type	Метод REST API
Document title	[DRAFT] Create Employee Request v2 [API-005-007-002-0112]
Guideline ID	GUI-0011
Author	@
Document version	1
Document status	DRAFT
Date of creation	ХХ.ХХ.ХХХХ (дата фінальної версії документа – RC або PROD)
Date of update	ХХ.ХХ.ХХХХ (дата зміни версії)
Method API ID	API-005-007-002-0112
Microservices (namespace)	IL
Component	Employees
Component ID	COM-005-007
Link на API-специфікацію	https://ehealthmisapi1.docs.apiary.io/#reference/public.-medical-service-provider-integration-layer/employee-requests/create-employee-request-v2
Resource	{{host}}/api/employee_requests
Scope	employee_request:write
Protocol type	REST
Request type	POST
Sync/Async	Sync
Public/Private	Public

Purpose

The method is used to register new employee or to update an existing one. There are two different flows of registration depending on whether the employee has tax_id or doesn't have one.

Logic

...

Configuration parameters

N/A

Dictionaries

POSITION
EMPLOYEE_TYPE
GENDER
+DOCUMENT_TYPE
COUNTRY
EDUCATION_DEGREE
QUALIFICATION_TYPE
PHONE_TYPE
SPECIALITY_TYPE
SPECIALITY_LEVEL
SPEC_QUALIFICATION_TYPE

Input parameters

	Input parameter	Mandatory	Type	Description	Example
1
2

Request structure

See on API-specification

Expand

title	Example

Code Block

language	json

{
  "signed_content": "...",
  "signed_content_encoding": "base64"
}

Headers

Request data validation

Authorize

User authorization
1. Validate MIS API Key
2. Check MIS scopes employee_request:write in order to perform this action
  1. In case error - generate 401 response

Digital signature

Decode content that is encrypted in an electronic digital signature.
Use Digital signature WS. Method checks digital signature and returns result.

Validate DRFO

Check that DRFO in Certificate details exists and not empty
Check that DRFO in Certificate details is equal to DRFO of the user that creates employee_request in Party
1. Get party.tax_id using user_id from employee request 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 using legal table

Validate request (JSON schema)

Validate request using JSON schema
1. In case validation fails - generate 422 error

new_employee_request_schema.json

There is an object “<employee_type>” (“doctor”, “assistant”, “specialist”…) in the body of the “employee_request”; <employee_type> is the same as employee to be created (DOCTOR, ASSISTANT, SPECIALIST, etc). Required for the employees with mandatory medical education (“doctor”, “assistant”, “specialist”, “laborant”, “med_coordinator”, ”med_admin”, ”pharmasist”).

if employee_type == PHARMACY_EMPLOYEE_TYPES check division_id
1. if division_id is absent - return error 422 "division_id should be specified"

Validate request (Logic)

Check employee_type: Employee configurable validation rules and dictionaries
If employee_id is passed in the payload:
1. search employees by employee_id
  1. if not found - return error 404
2. check that employee_type not in (OWNER, PHARMACY_OWNER)
  1. in case of error - return 409 “Forbidden to create <employee_type>“
3. check employee_type and tax_id (or passport_id, if no_tax_id: true)
  1. If dosn't match, return error 409 “<field> doesn't match"
4. check that employee is active (status = APPROVED and is_active = true)
  1. in case of error - return 409 “employee is <status>“
Check allowed employee types for legal_entity type: Legal_Entity_Type vs Employee_Type validation rules
1. if not found - return error 404
Validate legal entity type status for current legal entity: status should be active or suspended
Validate party
1. first_name, last_name, second_name have the same validation pattern - `^(?!.*[ЫЪЭЁыъэё@%&$^#])[А-ЯҐЇІЄа-яґїіє’\\'\\- ]+$`
  1. if doesn't match, return error 422 "string does not match pattern ..."
2. validate birth_date
  1. birth_date > 1900-01-01 and birth_date < current date
    1. otherwise return error 422 "invalid birth_date value"
  2. birth_date has validation pattern - `^(\\d{4}(?!\\d{2}\\b))((-?)((0[1-9]|1[0-2])(\\3([12]\\d|0[1-9]|3[01]))?|W([0-4]\\d|5[0-2])(-?[1-7])?|(00[1-9]|0[1-9]\\d|[12]\\d{2}|3([0-5]\\d|6[1-6])))?)?$`
    1. if doesn't match, return error 422 "expected 'birth_date' to be a valid ISO 8601 date"
3. gender has one of the following values - "FEMALE", "MALE"
  1. otherwise return error 422 "value is not allowed in enum"
4. validate tax_id
  1. tax_id has validation pattern - `^([0-9]{9,10}|[А-ЯЁЇIЄҐ]{2}\\d{6})$`
    1. if doesn't match, return error 422 "string does not match pattern ..."
5. email has validation pattern - `^[\\w!#$%&'*+/=?`{|}~^-]+(?:\\.[\\w!#$%&'*+/=?`{|}~^-]+)*@(?:[A-Z0-9-]+\\.)+[A-Z]{2,6}$`
  1. if doesn't match, return error 422 "expected 'email' to be an email address"
6. validate documents
  1. documents.type has one of the following values:
    1. "BIRTH_CERTIFICATE"
    2. "BIRTH_CERTIFICATE_FOREIGN"
    3. "COMPLEMENTARY_PROTECTION_CERTIFICATE"
    4. "NATIONAL_ID"
    5. "PASSPORT"
    6. "PERMANENT_RESIDENCE_PERMIT"
    7. "REFUGEE_CERTIFICATE"
    8. "TEMPORARY_CERTIFICATE"
    9. "TEMPORARY_PASSPORT"
      1. otherwise return error 422 "value is not allowed in enum"
  2. documents.number has validation pattern according to documents.type
    1. BIRTH_CERTIFICATE - `^((?![ЫЪЭЁыъэё@%&$^#`~:,.*|}{?!])[A-ZА-ЯҐЇІЄ0-9№\\/()-]){2,25}$`
    2. COMPLEMENTARY_PROTECTION_CERTIFICATE - `^((?![ЫЪЭЁ])([А-ЯҐЇІЄ])){2}[0-9]{6}$`
    3. NATIONAL_ID - `^[0-9]{9}$`
    4. PASSPORT - `^((?![ЫЪЭЁ])([А-ЯҐЇІЄ])){2}[0-9]{6}$`
    5. PERMANENT_RESIDENCE_PERMIT - `^(((?![ЫЪЭЁ])([А-ЯҐЇІЄ])){2}[0-9]{4,6}|[0-9]{9}|((?![ЫЪЭЁ])([А-ЯҐЇІЄ])){2}[0-9]{5}\\/[0-9]{5})$`
    6. REFUGEE_CERTIFICATE - `^((?![ЫЪЭЁ])([А-ЯҐЇІЄ])){2}[0-9]{6}$`
    7. TEMPORARY_CERTIFICATE - `^(((?![ЫЪЭЁ])([А-ЯҐЇІЄ])){2}[0-9]{4,6}|[0-9]{9}|((?![ЫЪЭЁ])([А-ЯҐЇІЄ])){2}[0-9]{5}\\/[0-9]{5})$`
    8. TEMPORARY_PASSPORT - `^((?![ЫЪЭЁыъэё@%&$^#`~:,.*|}{?!])[A-ZА-ЯҐЇІЄ0-9№\\/()-]){2,25}$`
  3. validate documents.issued_at
    1. documents.issued_at has validation pattern - `^(\\d{4}(?!\\d{2}\\b))((-?)((0[1-9]|1[0-2])(\\3([12]\\d|0[1-9]|3[01]))?|W([0-4]\\d|5[0-2])(-?[1-7])?|(00[1-9]|0[1-9]\\d|[12]\\d{2}|3([0-5]\\d|6[1-6])))?)?$`
      1. if doesn't match, return error 422 "expected 'issued_at' to be a valid ISO 8601 date"
7. validate phones
  1. phones.type has one of the following values - "LAND_LINE", "MOBILE"
    1. otherwise return error 422 "value is not allowed in enum"
  2. phones.number has validation pattern - `^\\+38[0-9]{10}$`
    1. if doesn't match, return error 422 "string does not match pattern ..."

Alternative notation 2 of validation :

Code Block

language	json

if (employee_id is passed in the payload) {
	result=search employees by employee_id;
	if (result == false) {
		return error 404 }
	else { 
		result=check * employee_type and * tax_id
		if (result == false) {
			return error 409}
		else {
			if (employee is active) {
				if (employee_type = OWNER || employee_type = PHARMACY_OWNER) {
					set status = APPROVED
					set is_active = false}
				if (employee_type not OWNER && employee_type not PHARMACY_OWNER) {
					set status = DISMISSED
					set is_active = true}
				if (employee is active) {
					create employee request }
				else {
					return error 409 }
					}
				}
			}
		}
	}
}	
result=search employee_type_legal_entity_type_links by employee_type+legal_entity_type
if (result == false) {
		return error 404 }

Processing

Save signed declaration to media storage

Get url for declaration upload.
Use Request a Secret WS
Parameter
Source
action
'GET'
bucket
'EMPLOYEE_REQUESTS'
resource_id
: EMPLOYEE_REQUEST_ID
resource_name
: signed_employee_request
Upload signed declaration to media storage

Create employee request

Create employee request in IL_DB table - employee_request.

1. generate GUID and writte in id column
2. write JSON object with employee request details

Send activation link on email

Generate activation link, which contains Employee request GUID
Send activation URL on user email
1. invoke service - Send message

Updating employee data

To update the data of an existing employee use the endpoint `Create Employee Request v2`.
It is necessary to transfer the same JSON as when creating employee request with the same id of an existing employee.

There are several rules when updating employee data:

position can not be changed
1. in case of failure, return error 422 "employee position can not be changed"
Start_date can not be changed
1. in case of failure, return error 422 "start_date doesn't match"
If specialities.speciality_officio:true, in this object value of speciality can not be changed (with several exceptions in the item b)
1. in case of failure, return error 422 "main speciality can not be changed"
2. there are following exceptions related to speciality changing for legal entity types “PRIMARY CARE” and “MSP“:

Old speciality	New speciality	Status details for existing declarations
pediatrician	family_doctor	patient's declarations aged 0 to 18 remain status “active”
pediatrician	therapist	patient's declarations aged 0 to 18 change status to “terminated”
family_doctor	therapist	patient's declarations aged 18 and older remain status “active”
family_doctor	therapist	patient's declarations aged 0 to 18 change status to “terminated”
family_doctor	pediatrician	patient's declarations aged 0 to 18 remain status “active”
family_doctor	pediatrician	patient's declarations aged 18 and older change status to “terminated”
therapist	family_doctor	patient's declarations aged 18 and older remain status “active”
therapist	pediatrician	patient's declarations aged 18 and older change status to “terminated”

Response structure examples

See on API-specification

Expand

title	Example

Code Block

language	json

{
  "meta": {
    "code": 201,
    "url": "https://example.com/resource",
    "type": "object",
    "request_id": "req-adasdoijasdojsda"
  },
  "data": {
    "division_id": "b075f148-7f93-4fc2-b2ec-2d81b19a9b7b",
    "legal_entity_id": "d290f1ee-6c54-4b01-90e6-d701748f0851",
    "position": "P8",
    "start_date": "2017-03-02T10:45:16.000Z",
    "end_date": "2018-03-02T10:45:16.000Z",
    "status": "NEW",
    "employee_type": "DOCTOR",
    "party": {
      "first_name": "Петро",
      "last_name": "Іванов",
      "second_name": "Миколайович",
      "birth_date": "1991-08-19T00:00:00.000Z",
      "gender": "MALE",
      "no_tax_id": false,
      "tax_id: 3126509816 (string, required) - if no_tax_id=true then passport number, otherwise tax_id": "",
      "email": "email@example.com",
      "documents": [
        {
          "type": "PASSPORT",
          "number": "АА120518",
          "issued_by": "Рокитнянським РВ ГУ МВС Київської області",
          "issued_at": "2017-02-28"
        }
      ],
      "phones": [
        {
          "type": "MOBILE",
          "number": "+380503410870"
        }
      ],
      "working_experience": 10,
      "about_myself": "Закінчив всі можливі курси"
    },
    "doctor": {
      "educations": [
        {
          "country": "UA",
          "city": "Київ",
          "institution_name": "Академія Богомольця",
          "issued_date": "2017-02-28",
          "diploma_number": "DD123543",
          "degree": "MASTER",
          "speciality": "Педіатр"
        }
      ],
      "qualifications": [
        {
          "type": "SPECIALIZATION",
          "institution_name": "Академія Богомольця",
          "speciality": "Педіатр",
          "issued_date": "2017",
          "certificate_number": "2017",
          "valid_to": "2017",
          "additional_info": "додаткова інофрмація"
        }
      ],
      "specialities": [
        {
          "speciality": "THERAPIST",
          "speciality_officio": true,
          "level": "FIRST",
          "qualification_type": "AWARDING",
          "attestation_name": "Академія Богомольця",
          "attestation_date": "2017-02-28",
          "valid_to_date": "2020-02-28",
          "certificate_number": "AB/21331"
        }
      ],
      "science_degree": {
        "country": "UA",
        "city": "Київ",
        "degree": "",
        "institution_name": "Академія Богомольця",
        "diploma_number": "DD123543",
        "speciality": "Педіатр",
        "issued_date": "2017"
      }
    },
    "id": "b075f148-7f93-4fc2-b2ec-2d81b19a9b7b",
    "inserted_at": "2017-05-05T14:09:59.232112",
    "updated_at": "2017-05-05T14:09:59.232112"
  }
}HTTP status codes

HTTP status codes

	Response code	HTTP Status code	Message
1	Базові
2		200	Response
3		401	User authorization error
4		404	Check allowed employee types for legal_entity type: Legal_Entity_Type vs Employee_Type validation rules not found
5		404	search employees by employee_id - not found
6		409	Employee is not active
7		409	employee is <status>
8		409	employee_type and (* tax_id or passport_id) don`t match
9		409	Forbidden to create <employee_type>
10		409	<field> doesn't match
11		422	division_id should be specified
12		422	Check that DRFO in Certificate details is equal to DRFO of the user that creates employee_request in Party failed
13		422	expected 'issued_at' to be a valid ISO 8601 date
14		422	employee position can not be changed
15		422	expected 'birth_date' to be a valid ISO 8601 date
16		422	expected 'email' to be an email address
17		422	Error
18		422	invalid birth_date value
19		422	main speciality can not be changed
20		422	position can not be changed
21		422	start_date doesn't match
22		422	string does not match pattern ...
23		422	value is not allowed in enum
24		422	Validate request using JSON schema failed
25	Специфічні
26

Post-processing processes

N/A

Technical modules where the method is used

Page Properties Report

headings	ID ТМ, Статус
cql	label = "tr-mis"

...

Page Comparison

Versions Compared

Old Version 2

New Version Current

Key

Properties of a REST API method document

Purpose

Logic

Configuration parameters

Dictionaries

Input parameters

Request structure

Headers

Request data validation

Processing

Response structure examples

HTTP status codes

Post-processing processes

Technical modules where the method is used

Properties of a REST API method document

Purpose

Logic

Configuration parameters

Dictionaries

Input parameters

Request structure

Headers

Request data validation

Authorize

Digital signature

Validate DRFO

Validate request (JSON schema)

Validate request (Logic)

Processing

Save signed declaration to media storage

Create employee request

Send activation link on email

Updating employee data

Response structure examples

HTTP status codes

Post-processing processes

Technical modules where the method is used