REST API method / Метод REST API (настанова) (remove the link block before publishing the document)

Properties of a REST API method document

Document type	Метод REST API
Document title	[Document status] REST API [Назва методу] [ID методу]
Guideline ID	GUI-0011
Author	@
Document version	1
Document status	DRAFT
Date of creation	ХХ.ХХ.ХХХХ (дата фінальної версії документа – RC або PROD)
Date of update	ХХ.ХХ.ХХХХ (дата зміни версії)
Method API ID	API-010-001-004-0375
Microservices (namespace)	MPI
Component	Master Patient Index
Component ID	COM-010-001
Link на API-специфікацію	https://ehealthmisapi1.docs.apiary.io/#reference/public.-medical-service-provider-integration-layer/person-requests
Resource	`{{host}}/api/person_requests`
Scope	person_request:write
Protocol type	REST
Request type	POST
Sync/Async	Sync
Public/Private	Public

...

GENDER
DOCUMENT_TYPE
ADDRESS_TYPE
COUNTRY
SETTLEMENT_TYPE
STREET_TYPE
PHONE_TYPE
AUTHENTICATION_METHOD
CONFIDANT_PERSON_TYPE
PREFERRED_WAY_COMMUNICATION
DOCUMENT_RELATIONSHIP_TYPE

Input parameters

Description of input parameters

	Input parameter	Mandatory	Type	Description	Example
1	composition_id	M	String ($uuid) (path)	Composition object ID	89678f60-4cdc-4fe3-ae83-e8b3ebd35c59
2

Request structure

See on API-specification

...

Verify the validity of access token
1. Return (401, 'Invalid access token') in case of validation fails
Verify that token is not expired
1. in case of error - return (401, 'Invalid access token')
Check user scopes in order to perform this action (scope = 'person_request:write')
- Return (403, 'Your scope does not allow to access this resource. Missing allowances: person_request:write') in case of invalid scope(s)
validate client_id belongs to legal_entity with type in ('MSP', 'OUTPATIENT', 'EMERGENCY', 'PRIMARY_CARE')
1. Return (401, 'Invalid legal entity type') in case of validation fails
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):
1. 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):
1. in case of error - return 403 ("Access denied. Party is deceased")
~~validate user belongs to employee with type in "Doctor, Specialist, Receptionist, Assistant"~~
1. ~~in case error return 409~~

Headers

	Key	Value	Description	Example
1	Content-Type	application/json	Тип контенту	Content-Type:application/json
2	Authorization	Bearer {{access_token}}	Перевірка користувача	Authorization:Bearer {{access_token}}
3	api-key	{{secret}}	Секретний ключ	api-key:{{secret}}

Request data validation

Validate request

Validate request using JSON schema

Check presence of extra parameters
- In case of error - return 422 ('schema does not allow additional properties')
Check presence of required parameters
- In case of error - return 422 ('required property %{property} was not present')

...

title	JSON Schema

...

api-key:{{secret}}

Request data validation

Validate request

Validate request using JSON schema

Check presence of extra parameters
- In case of error - return 422 ('schema does not allow additional properties')
Check presence of required parameters
- In case of error - return 422 ('required property %{property} was not present')

Expand

title	JSON Schema

Code Block

{
  "$schema": "http://json-schema.org/person_request/schema#",
  "definitions": {
    "phone": {
      "type": "object",
      "properties": {
        "type": {
          "type": "string",
          "description": "Dictionary: PHONE_TYPE"
        },
        "number": {
          "type": "string",
          "pattern": "^\\+38[0-9]{10}$"
        }
      },
      "required": [
        "type",
        "number"
      ],
      "additionalProperties": false
    },
    "name": {
      "type": "string",
      "pattern": "^(?!.*[ЫЪЭЁыъэё@%&$^#])[a-zA-ZА-ЯҐЇІЄа-яґїіє0-9№\\\"!\\^\\*)\\]\\[(._-].*$"
    },
    "person_name": {
      "type": "string",
      "pattern": "^(?!.*[ЫЪЭЁыъэё@%&$^#])[А-ЯҐЇІЄа-яґїіє\\'\\-]+(\\s(?!.*[ЫЪЭЁыъэё@%&$^#])[А-ЯҐЇІЄа-яґїіє\\'\\-]+)*$",
      "minLength": 1,
      "maxLength": 255
    },
    "unzr": {
      "type": "string",
      "pattern": "^[0-9]{8}-[0-9]{5}$"
    },
    "tax_id": {
      "type": "string",
      "pattern": "^[0-9]{10}$",
      "minLength": 10,
      "maxLength": 255
    },
    "no_tax_id": {
      "type": "boolean",
      "description": "Status person refused tax_id"
    },
    "gender": {
      "type": "string",
      "description": "Dictionary: GENDER",
      "maxLength": 255
    },
    "address": {
      "type": "object",
      "properties": {
        "type": {
          "type": "string",
          "description": "Dictionary: ADDRESS_TYPE"
        },
        "country": {
          "type": "string"
        },
        "area": {
          "$ref": "#/definitions/name"
        },
        "region": {
          "$ref": "#/definitions/name"
        },
        "settlement": {
          "$ref": "#/definitions/name"
        },
        "settlement_type": {
          "type": "string",
          "description": "settlement type Dictionary: SETTLEMENT_TYPE"
        },
        "settlement_id": {
          "type": "string",
          "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$"
        },
        "street_type": {
          "type": "string",
          "description": "street type Dictionary: STREET_TYPE"
        },
        "street": {
          "$ref": "#/definitions/name"
        },
        "building": {
          "type": "string",
          "pattern": "^[1-9]((?![ЫЪЭЁыъэё])()([А-ЯҐЇІЄа-яґїіє \\/\\'\\-0-9])){0,20}$"
        },
        "apartment": {
          "type": "string"
        },
        "zip": {
          "type": "string",
          "pattern": "^[0-9]{5}$"
        },
        "inserted_by": {
          "type": "string"
        },
        "updated_by": {
          "type": "string"
        },
        "inserted_at": {
          "type": "string"
        },
        "updated_at": {
          "type": "string"
        }
      },
      "required": [
        "type",
        "country",
        "area",
        "settlement",
        "settlement_type",
        "settlement_id",
        "inserted_by",
        "updated_by"
      ],
      "additionalProperties": false
    },
    "series_number_document": {
      "type": "object",
      "properties": {
        "type": {
          "type": "string",
          "enum": [
            "PASSPORT",
            "COMPLEMENTARY_PROTECTION_CERTIFICATE",
            "REFUGEE_CERTIFICATE",
            "TEMPORARY_CERTIFICATE"
          ],
          "description": "Dictionary: DOCUMENT_TYPE"
        },
        "number": {
          "type": "string",
          "pattern": "^((?![ЫЪЭЁ])([А-ЯҐЇІЄ])){2}[0-9]{6}$"
        },
        "issued_by": {
          "type": "string",
          "minLength": 1
        },
        "issued_at": {
          "type": "string",
          "format": "date"
        }
      },
      "required": [
        "type",
        "number"
      ],
      "additionalProperties": false
    },
    "number_document": {
      "type": "object",
      "properties": {
        "type": {
          "type": "string",
          "enum": [
            "BIRTH_CERTIFICATE",
            "TEMPORARY_PASSPORT"
          ],
          "description": "Dictionary: DOCUMENT_TYPE"
        },
        "number": {
          "type": "string",
          "pattern": "^(?![ЫЪЭЁыъэё@%&$^#`~:,.*|}{?!])[A-ZА-ЯҐЇІЄ0-9№\\/()-]+$",
          "minLength": 1,
          "maxLength": 255
        },
        "issued_by": {
          "type": "string",
          "minLength": 1
        },
        "issued_at": {
          "type": "string",
          "format": "date"
        }
      },
      "required": [
        "type",
        "number"
      ],
      "additionalProperties": false
    },
    "id_card": {
      "type": "object",
      "properties": {
        "type": {
          "type": "string",
          "enum": [
            "NATIONAL_ID"
          ],
          "description": "Dictionary: DOCUMENT_TYPE"
        },
        "number": {
          "type": "string",
          "pattern": "^[0-9]{9}$"
        },
        "issued_by": {
          "type": "string",
          "minLength": 1
        },
        "issued_at": {
          "type": "string",
          "format": "date"
        }
      },
      "required": [
        "type",
        "number"
      ],
      "additionalProperties": false
    },
    "document_relationship": {
      "type": "object",
      "properties": {
        "type": {
          "type": "string",
          "description": "Dictionary: DOCUMENT_RELATIONSHIP_TYPE",
          "minLength": 1
        },
        "number": {
          "type": "string",
          "minLength": 1
        },
        "issued_by": {
          "type": "string",
          "minLength": 1
        },
        "issued_at": {
          "type": "string",
          "format": "date"
        }
      },
      "required": [
        "type",
        "number"
      ],
      "additionalProperties": false
    }
  },
  "type": "object",
  "properties": {
    "person": {
      "type": "object",
      "properties": {
        "first_name": {
          "type": "string"
        },
        "last_name": {
          "type": "string"
        },
        "second_name": {
          "type": "string"
        },
        "birth_date": {
          "type": "string"
        },
        "birth_country": {
          "type": "string"
        },
        "birth_settlement": {
          "type": "string"
        },
        "gender": {
          "enum": [
            "MALE",
            "FEMALE"
          ]
        },
        "email": {
          "type": "string"
        },
        "no_tax_id": {
          "type": "boolean"
        },
        "tax_id": {
          "type": "string"
        },
        "secret": {
          "type": "string"
        },
        "documents": {
          "type": "array"
        },
        "addresses": {
          "type": "array"
        },
        "phones": {
          "type": "array"
        },
        "authentication_methods": {
          "type": "array"
        },
        "unzr": {
          "type": "string"
        },
        "emergency_contact": {
          "type": "object",
          "properties": {
            "first_name": {
              "type": "string"
            },
            "last_name": {
              "type": "string"
            },
            "second_name": {
              "type": "string"
            },
            "phones": {
              "type": "array"
            }
          },
          "required": [
            "first_name",
            "last_name",
            "phones"
          ]
        },
        "confidant_person": {
          "type": "array"
        },
        "preferred_way_communication": {
          "enum": [
            "email",
            "phone"
          ]
        }
      },
      "required": [
        "first_name",
        "last_name",
        "birth_date",
        "birth_country",
        "birth_settlement",
        "gender",
        "no_tax_id",
        "tax_id",
        "secret",
        "documents",
        "addresses",
        "emergency_contact"
      ]
    },
    "patient_signed": {
      "type": "boolean"
    },
    "process_disclosure_data_consent": {
      "type": "boolean"
    }
  },
  "required": [
    "person",
    "patient_signed",
    "process_disclosure_data_consent"
  ]
}

Validate confidant person

...

issued_at, issued_by is mandatory for documents
Validate dates
1. issued_at <= now() and issued_at => birth_date
  1. in case `issued_at > now()` show error 422, "Document issued date should be in the past"
  2. in case `issued_at < person.birth_date` show error 422, "Document issued date should greater than person.birth_date "
2. expiration_date > now()
  1. in case error show 422, "Document expiration_date should be in future"
  2. expiration_date is mandatory for document_type
    - NATIONAL_ID
    - COMPLEMENTARY_PROTECTION_CERTIFICATE
    - PERMANENT_RESIDENCE_PERMIT
    - REFUGEE_CERTIFICATE
    - TEMPORARY_CERTIFICATE
    - TEMPORARY_PASSPORT
  3. in case error return 422, "expiration_date is mandatory for document_type $.documents.type"
Validate documents_type.number according to json schema
1. PASSPORT - `^((?![ЫЪЭЁ])([А-ЯҐЇІЄ])){2}[0-9]{6}$`
2. NATIONAL_ID - `^[0-9]{9}$`
3. BIRTH_CERTIFICATE - `^((?![ЫЪЭЁыъэё@%&$^#`~:,.*|}{?!])[A-ZА-ЯҐЇІЄ0-9№\\/()-]){2,25}$`
4. COMPLEMENTARY_PROTECTION_CERTIFICATE - `^((?![ЫЪЭЁ])([А-ЯҐЇІЄ])){2}[0-9]{6}$`
5. REFUGEE_CERTIFICATE - `^((?![ЫЪЭЁ])([А-ЯҐЇІЄ])){2}[0-9]{6}$`
6. TEMPORARY_CERTIFICATE - `^(((?![ЫЪЭЁ])([А-ЯҐЇІЄ])){2}[0-9]{4,6}|[0-9]{9}|((?![ЫЪЭЁ])([А-ЯҐЇІЄ])){2}[0-9]{5}\\/[0-9]{5})$`
7. TEMPORARY_PASSPORT - `^((?![ЫЪЭЁыъэё@%&$^#`~:,.*|}{?!])[A-ZА-ЯҐЇІЄ0-9№\\/()-]){2,25}$`
if unzr exists and is not null, check pattern match "^[0-9]{8}-[0-9]{5}$"
1. in case error return 422, msg 'string does not match pattern \"%{pattern}\"'
if documents.type=NATIONAL_ID
1. check if unzr exists in request, in case error return 422, msg "unzr is mandatory for document type NATIONAL_ID"
Document numbersmaxLength < 25

...

If person <prm.global_parameters.no_self_auth_age years, then person.auth_methods.type = third_person. Validate that third_person has auth method.type = OTP
if third_person.auth_method.type = OFFLINE - error `THIRD PERSON can't have OFFLINE self auth method type`
if third_person.auth_method.type doesn't have active auth method - error `THIRD PERSON doesn't have active valid authentication methods`
If third person >= prm.global_parameters.no_self_auth_age years
1. in case error return 422, msg "Incorrect person age for such an action"

...

Person.auth_methods.type = third_persont.id. But on get Person request or Person display third_person.auth_method.phone_number.

...

Each link is generated for one one-page document in .pdf, .jpg, .png, .bmp format. Document should be no more than 20 MB. For each type of documents, if couple of rules worked - only one single link is generated.

~~Validate flag no_tax_id, if $.person_request.person.no_tax_id = true:~~
1. ~~Generate URL with type person.no_tax_id~~
~~Validate if $.person_request.person.tax_id is not empty and $.person_request.person.no_tax_id = false then~~
1. ~~If (GetBirthDateFromTaxId($.tax_id) != $.birth_date) or (GetGenderFromTaxId($.tax_id) != $.gender) or CheckValidity($.tax_id) = false (i.e. invalid checksum) then~~
  - ~~Generate URL with type person.tax_id~~
Validate block confidant person. If person.confidant is not null:
1. Generate URL's with type confidant_person.{confidant_person.type}.{$.person_request.person.confidant_person.[:].documents_relationship.[:].type}
2. Generate URL's with type confidant_person.{confidant_person.type}.{$.person_request.person.confidant_person.[:].documents_person.[:].type}
Validate block of person documents. If one of the documents has document.type = BIRTH_CERTIFICATE_FOREIGN and there is no same document in {$.person_request.person.confidant_person.[:].documents_relationship.[:]}
and age < no_self_auth_age then
1. Generate URL with type person.{$.person_request.person.documents.[with type BIRTH_CERTIFICATE_FOREIGN].type}
Validate block of person documents. If one of the documents has document.type = PERMANENT_RESIDENCE_PERMIT and age >= no_self_auth_age then
1. Generate URL with type person.{$.person_request.person.documents.[with type PERMANENT_RESIDENCE_PERMIT].type}
Validate authentication_method. If authentication method = OFFLINE or third_person (and this third_person.auth_method = OFFLINE) -
1. Generate URL's with type person.{$.person_request.person.documents.[:].type} (or Generate URL's with type third_person.{$.third_person.documents.[:].type})
Validate unzr. If $.person_request.person.unzr is not empty and first 8 digits of $.person_request.person.unzr != $.person_request.person.birth_date then
1. Generate URL with type person.{$.person_request.person.unzr}

Invoke Media Content Storage to generate upload URL for each document obtained by executing logic above

...

Update person’s data with empty value of the second name is possible by setting second_name = null.

Authorize

Verify the validity of access token
Check user scope person_request:write in order to perform this action

Request data validation

Validate request

...

Each link is generated for one one-page document in jpeg format. Document should be no more than 10MB. For each type of documents only one single link is generated.

~~Validate flag no_tax_id, if $.person_request.person.no_tax_id = true:~~
1. ~~Generate URL with type person.no_tax_id~~
~~Validate if $.person_request.person.tax_id is not empty and $.person_request.person.no_tax_id = false then~~
1. ~~If (GetBirthDateFromTaxId($.tax_id) != $.birth_date) or (GetGenderFromTaxId($.tax_id) != $.gender) or CheckValidity($.tax_id) = false (i.e. invalid checksum) then~~
  - ~~Generate URL with type person.tax_id~~
Validate block confidant person. If person.confidant is not null:
1. Generate URLs with type confidant_person.{confidant_person.type}.{$.person_request.person.confidant_person.[:].documents_relationship.[:].type}
2. Generate URLs with type confidant_person.{confidant_person.type}.{$.person_request.person.confidant_person.[:].documents_person.[:].type}
Validate block of person documents. If one of the documents has document.type = BIRTH_CERTIFICATE_FOREIGN and there is no same document in {$.person_request.person.confidant_person.[:].documents_relationship.[:]}
and age < no_self_auth_age then
1. Generate URL with type person.{$.person_request.person.documents.[with type BIRTH_CERTIFICATE_FOREIGN].type}
Validate block of person documents. If one of the documents has document.type = PERMANENT_RESIDENCE_PERMIT and age >= no_self_auth_age then
1. Generate URL with type person.{$.person_request.person.documents.[with type PERMANENT_RESIDENCE_PERMIT].type}
Validate authentication_method. If authentication method = OFFLINE or third_person (and this third_person.auth_method = OFFLINE) -
1. Generate URLs with type person.{$.person_request.person.documents.[:].type} (or Generate URL's with type third_person.{$.third_person.documents.[:].type})
Validate unzr. If $.person_request.person.unzr is not empty and first 8 digits of $.person_request.person.unzr != $.person_request.person.birth_date then
1. Generate URL with type person.{$.person_request.person.unzr}

Code Block
{ "documents":[ { "type":"person.no_tax_id", "url": "https://storage.googleapis.com/..." } ] }

Save documents to DB.

Generate verification code

...

	Response code	HTTP Status code	Message
1	Базові
2		201	Response
3		401	Invalid access token
4		401	Invalid legal entity type
5		403	Access denied. Party is not verified
6		403	Your scope does not allow to access this resource. Missing allowances: person_request:write
7		409	Invalid legal entity type
8		409	Such person can't be updated. Deduplication update score is lower than system value (less changes should be made)
9		409	Such person exists. Update this person
10		422	Confidant person is mandatory for children
11		422	Cannot be confirmed by a method with type= NA. Use a different method.
12		422	Document expiration_date should be in future
13		422	Document issued date should be in the past
14		422	Document issued date should greater than person.birth_date
15		422	Expiration_date is mandatory for document_type $.documents.type
16		422	Incorrect person age for such an action
17		422	Required property %{property} was not present
18		422	Required property patient_signed was not present
19		422	Schema does not allow additional properties
20		422	String does not match pattern ...
21		422	Such person doesn't exist
22		422	Such a phone already exists more N times
23		422	Such authentication method doesn't exist
24		422	Such authentication method does not belong to this person
25		422	This phone number is present more then $.global_parameters.phone_number_auth_limit times in the system
26		422	Unverified phone number
27		422	Unzr is mandatory for document type NATIONAL_ID
28		422	Unzr or birthdate are not correct
29		422	Value is not allowed in enum
30	Специфічні
31		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

List of pages describing technical modules where the method is used

Название	ID ТМ	Статус
/wiki/spaces/ESOZ/pages/17378181218	TM0112
/wiki/spaces/YK/pages/17837688354

...

Versions Compared

Old Version 3

New Version 4

Key

Properties of a REST API method document

Input parameters

Request structure

Headers

Request data validation

Validate request

Request data validation

Validate request

Validate confidant person

Authorize

Request data validation

Validate request

Generate verification code

Post-processing processes

Technical modules where the method is used

Page Comparison

Versions Compared

Old Version 3

New Version 4

Key

Properties of a REST API method document

Input parameters

Request structure

Headers

Request data validation

Validate request

Request data validation

Validate request

Validate confidant person

Authorize

Request data validation

Validate request

Generate verification code

Post-processing processes

Technical modules where the method is used