Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

...

...

...

...

...

...

...

...

...

...

...

...

Table of Contents

Specification

APIARY

Method is used to register new employee or to update an existing one. There is 2 different flows of registration depend on whether the employee has tax_id or doesn't have.

...

Authorize user

  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.
See service specification

Validate DRFO

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

  2. 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)

  1. Validate request using JSON schema

    1. In case validation fails - generate 422 error

new_employee_request_schema.json

Validate request (Logic)

  1. Check employee_type: Employee configurable validation rules and dictionaries

  2. If employee_id is passed in the payload:

    1. search employees by employee_id

      1. if not found - return error 404

      2. else check * employee_type and (* tax_id or passport_id)

        1. If dosn't match, return error 409

        2. If match, check that employee is active

          for (employee_type = OWNER or PHARMACY_OWNER), status = APPROVED and is_active = false

          for (employee_type not OWNER and not PHARMACY_OWNER), status = DISMISSED and is_active = true

          1. if employee is active - create employee request

          2. if employee is not active - return error 409

  3. Check allowed employee types for legal_entity type: Legal_Entity_Type vs Employee_Type validation rules

    1. if not found - return error 404

  4. Validate legal entity type status for current legal entity: status should be active or suspended

  5. 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"

          Jira Legacy
          serverSystem Jira
          serverIdd9171809-9c5e-36f7-ab17-a56a875b6d19
          keyBAT-1392

        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
languagecpp
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 }

Save signed declaration to media storage

Get url for declaration upload.
Use Request a Secret WS

...

Parameter

...

Source

...

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

  1. Generate activation link, which contains Employee request GUID

  2. Send activation URL on user email

    1. invoke service - Send message
      See service specification 

Updating employee data

To update the data of an existing employee use the endpoint `Create Employee Request`.
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:

  1. Position can not be changed

    1. in case of failure, return error 422 "position can not be changed"

  2. 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”

...

patient's declarations aged 0 to 18 change status to “terminated”

...

family_doctor

pediatrician

...

patient's declarations aged 0 to 18 remain status “active”

...

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

...

Table of Contents

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.

Specification

Page Properties

Link

 https://ehealthmisapi1.docs.apiary.io/#reference/public.-medical-service-provider-integration-layer/employee-requests/create-employee-request-v2

Посилання на Apiary або Swagger

Resource

 /api/v2/employee_requests

Посилання на ресурс, наприклад: /api/persons/create

Scope

 employee_request:write

Scope для доступу

Components

Employees

Зазначається перелік бізнес компонентів, які використовують цей метод, наприклад: ePrescription

Microservices

il/api

Перелік мікросервісів, які використовує метод API, наприклад: Auth, ABAC

Protocol type

 REST

Тип протоколу, який використовується запитом, наприклад: SOAP | REST

Request type

 POST

Тип запиту API, наприклад: GET, POST, PATCH…

Sync/Async

 Sync

Метод є синхронним чи асинхронним?

Public/Private/Internal

 Public

Потрібно зазначити тип методу за ступенем доступності

Dummy for employee request

https://ehealthmisapi1.docs.apiary.io/#reference/dummy-methods/dummy-for-employee-request/create-employee-request-v2

Посилання на приклад запиту перед підписанням КЕП

Logic

...

Dictionaries

  • POSITION

  • EMPLOYEE_TYPE

  • GENDER

  • +DOCUMENT_TYPE

  • COUNTRY

  • EDUCATION_DEGREE

  • QUALIFICATION_TYPE

  • PHONE_TYPE

  • SPECIALITY_TYPE

  • SPECIALITY_LEVEL

  • SPEC_QUALIFICATION_TYPE

Request structure

See on Apiary

Example:

Expand
titleRequest example
Code Block
{
  "signed_content": "...",
  "signed_content_encoding": "base64"
}

Authorize

  1. 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

Headers

Content-Type:application/json

Authorization:Bearer c2778f3064753ea70de870a53795f5c9

Request data validation

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

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

  2. 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)

  1. 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”).

  1. 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)

  1. Check employee_type: Employee configurable validation rules and dictionaries

  2. 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>“

  3. Check allowed employee types for legal_entity type: Legal_Entity_Type vs Employee_Type validation rules

    1. if not found - return error 404

  4. Validate legal entity type status for current legal entity: status should be active or suspended

  5. 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
languagecpp
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

  1. 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

  2. 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

  1. Generate activation link, which contains Employee request GUID

  2. 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:

  1. position can not be changed

    1. in case of failure, return error 422 "employee position can not be changed"

  2. Start_date can not be changed

    1. in case of failure, return error 422 "start_date doesn't match"

  3. 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”

patient's declarations aged 0 to 18 change status to “terminated”

family_doctor

pediatrician

patient's declarations aged 0 to 18 remain status “active”

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

Example:

Expand
titleResponse example
Code Block
{
  "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 code

Message

What caused the error

200

Response

 

401

 

 User authorization error

404

409

  • Employee is not active

  • * employee_type and (* tax_id or passport_id) don`t match

422

  1. position can not be changed

  2. main speciality can not be changed

  3. expected 'issued_at' to be a valid ISO 8601 date

  4. expected 'email' to be an email address

  5. value is not allowed in enum

  6. invalid birth_date value

  7. string does not match pattern ...

  8. Error

8. Validate request using JSON schema failed

8. Check that DRFO in Certificate details is equal to DRFO of the user that creates employee_request in Party failed