https://e-health-ua.atlassian.net/wiki/spaces/EN/pages/17591304241 (remove the link block before publishing the document)

1 Properties of a REST API method document
2 Purpose
3 Logic
- 3.1 Service logic
  - 3.1.1 Calculate declaration start/end date
  - 3.1.2 Generate human readable declaration number
  - 3.1.3 Generate printout form
  - 3.1.4 Generate seed
  - 3.1.5 Prepare data_to_be_signed
    - 3.1.5.1 Structure
    - 3.1.5.2 Legal entity
    - 3.1.5.3 Accreditation
    - 3.1.5.4 License
    - 3.1.5.5 Employee
    - 3.1.5.6 Party
    - 3.1.5.7 Division
  - 3.1.6 Person
    - 3.1.6.1 Document
  - 3.1.7 Authentication method
  - 3.1.8 Emergency contact
  - 3.1.9 Confidant person
  - 3.1.10 Common
    - 3.1.10.1 Phone
    - 3.1.10.2 Address
- 3.2 Cancel existing active declaration requests
- 3.3 Save declaration request
4 Configuration parameters
5 Dictionaries
6 Input parameters
7 Request structure
8 Headers
9 Request data validation
10 Processing
11 Response structure examples
12 HTTP status codes
13 Post-processing processes
14 Technical modules where the method is used

Properties of a REST API method document

Document type	Метод REST API
Document title	[DRAFT] PIS. Create Declaration request [API-005-011-001-0463]
Guideline ID	GUI-0011
Author	@
Document version	1
Document status	DRAFT
Date of creation	ХХ.ХХ.ХХХХ (дата фінальної версії документа – RC або PROD)
Date of update	ХХ.ХХ.ХХХХ (дата зміни версії)
Method API ID	API-005-011-001-0463
Microservices (namespace)	IL
Component	Declaration Request
Component ID	COM-005-011
Link на API-специфікацію	PIS API · Apiary
Resource	{{host}}/api/pis/declaration_requests
Scope	declaration_request:write_pis
Protocol type	REST
Request type	POST
Sync/Async	Sync
Public/Private	Public

Purpose

Method to create declaration request via patient information system

Logic

Service logic

Calculate declaration start/end date

start_date - date when declaration was originated (current date)
end_date - is calculated based on config parameter declaration_term, patient age and doctor speciality
1. if selected doctor is PEDIATRICIAN and patient becomes adult (config adult_age) earlier than calculated end_date (start_date + declaration_term) - then end_date must be set as date when patient becomes adult minus 1 day

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
Search declaration_number in declaration_requests.declaration_number
1. if this number already reserved - generate new declaration_number and repeat this steps
2. if this number free - assign declaration_number to declaration_request

Generate printout form

Prepare data for declaration request printout form

Call MAN service to render printout form
Get template id from config (DECLARATION_REQUEST_PRINTOUT_FORM_TEMPLATE_ID)
Prepare printout content based on declaration request data
Render printout form and save to declaration request

If confidant person is required (see https://e-health-ua.atlassian.net/wiki/spaces/PCAB/pages/17513447465/PIS.+Create+Declaration+request_EN#Validate-confidant-person-and-relationship-(optional) ) then preload Confidant person object from MPI in the following structure

Get applicant_person_id from token
Get documents_person from MPI.person_documents
Get documents_relationship from MPI.confidant_person_relationship_documents

Parameter	Description

Parameter	Description
`full_name`
`phones`
`birth_date`
`gender`
`birth_settlement`
`birth_country`
`documents_person`
`tax_id`
`documents_relationship`
`preferred_way_communication`
`email`

    %{
      full_name: get_full_name(confidant_person),
      phones: get_phone(confidant_person),
      birth_date: confidant_person |> Map.get("birth_date") |> convert_date(),
      gender: get_gender(confidant_person),
      birth_settlement: Map.get(confidant_person, "birth_settlement", ""),
      birth_country: Map.get(confidant_person, "birth_country", ""),
      documents_person: get_document(confidant_person, "documents_person", @documents_dict),
      tax_id: Map.get(confidant_person, "tax_id", ""),
      documents_relationship: get_document(confidant_person, "documents_relationship", @relationship_documents_dict),
      preferred_way_communication:
        get_preferred_way_communication(Map.get(confidant_person, "preferred_way_communication") || "––"),
      email: Map.get(confidant_person, "email") || "––"
    }

Generate seed

Get the latest block (hashed value based on previously created declarations to prevent data changes) and save it to declaration request

Prepare data_to_be_signed

Structure

Parameter	Type	Comment

Parameter	Type	Comment
`id`	string (uuid)
`declaration_number`	string
`declaration_id`	string (uuid)
`channel`	string
`seed`	string
`legal_entity`	Legal entity
`employee`	Employee
`division`	Division
`person`	Person

Legal entity

Preload legal entity object from PRM.legal_entities

Parameter	Type	Comment

Parameter	Type	Comment
`id`	string (uuid)
`name`	string
`short_name`	string
`phones`	[Phone]
`legal_form`	string
`edrpou`	string
`public_name`	string
`email`	string
`addresses`	[Address]
`accreditation`	Accreditation
`licenses`	[License]

Accreditation

Parameter	Type	Comment

Parameter	Type	Comment
`category`	string
`expiry_date`	string (date)
`issued_date`	string (date)
`order_date`	string (date)
`order_no`	string

License

Parameter	Type	Comment

Parameter	Type	Comment
`active_from_date`	string (date)
`expiry_date`	string (date)
`id`	string (uuid)
`inserted_at`	string (date)
`inserted_by`	string (uuid)
`is_active`	boolean
`is_primary`	boolean
`issued_by`	string
`issued_date`	string (date)
`issuer_status`	string
`legal_entity_id`	string (uuid)
`license_number`	string
`order_no`	string
`type`	string
`updated_at`	string (date)
`updated_by`	string (uuid)
`what_licensed`	string

Employee

Preload employee object from PRM.employees

Parameter	Type	Comment

Parameter	Type	Comment
`id`	string (uuid)
`party`	Party
`position`	string

Party

Parameter	Type	Comment

Parameter	Type	Comment
`id`	string (uuid)
`first_name`	string
`last_name`	string
`second_name`	string
`tax_id`	string
`phones`	[Phone]

Division

Preload division object from PRM.divisions

Parameter	Type	Comment

Parameter	Type	Comment
`id`	string (uuid)
`name`	string
`legal_entity_id`	string (uuid)
`external_id`	string
`email`	string
`type`	string
`addresses`	[Address]
`phones`	[Phone]

Person

Preload person object from MPI.persons

Parameter	Type	Comment

Parameter	Type	Comment
`id`	string (uuid)
`first_name`	string
`last_name`	string
`second_name`	string
`gender`	string
`birth_date`	string (date)
`birth_country`	string
`birth_settlement`	string
`tax_id`	string
`no_tax_id`	boolean
`unzr`	string
`secret`	string
`documents`	[Document]
`phones`	[Phone]
`email`	string
`addresses`	[Address]
`authentication_methods`	[Authentication method]
`emergency_contact`	Emergency contact
`confidant_person`	Confidant person
`preferred_way_communication`	string
`patient_signed`	boolean
`process_disclosure_data_consent`	boolean

Document

Parameter	Type	Comment

Parameter	Type	Comment
`type`	string
`number`	string
`issued_at`	string (date)
`issued_by`	string
`expiration_date`	string (date)

Authentication method

Only active method must be chosen
Authentication method in an array with one entry

If confidant person is required (see https://e-health-ua.atlassian.net/wiki/spaces/PCAB/pages/17513447465/PIS.+Create+Declaration+request_EN#Validate-confidant-person-and-relationship-(optional)) then put only one authentication method that relates to this confidant person (select auth method where type 'THIRD_PERSON' and value = applicant_user_id from token)

If confidant person is NOT required - select the last added active method (where inserted_at the newest)

Parameter	Type	Comment

Parameter	Type	Comment
`type`	string
`phone_number`	string
`value`	string
`alias`	string

Emergency contact

Parameter	Type	Comment

Parameter	Type	Comment
`first_name`	string
`last_name`	string
`second_name`	string
`phones`	[Phone]

Confidant person

If confidant person is required (see https://e-health-ua.atlassian.net/wiki/spaces/PCAB/pages/17513447465/PIS.+Create+Declaration+request_EN#Validate-confidant-person-and-relationship-(optional) ) then preload Confidant person object from MPI in the following structure

Get applicant_person_id from token
Get documents_person from MPI.person_documents
Get documents_relationship from MPI.confidant_person_relationship_documents

Parameter	Type	Comment

Parameter	Type	Comment
`id`	string (uuid)
`first_name`	string
`last_name`	string
`second_name`	string
`birth_date`	string (date)
`birth_country`	string
`birth_settlement`	string
`secret`	string
`gender`	string
`tax_id`	string
`documents_person`	[Document]
`documents_relationship`	[Document]

Common

Phone

Parameter	Type	Comment

Parameter	Type	Comment
`type`	string
`number`	string

Address

Parameter	Type	Comment

Parameter	Type	Comment
`type`	string
`country`	string
`area`	string
`region`	string
`settlement`	string
`settlement_id`	string (uuid)
`settlement_type`	string
`street`	string
`street_type`	string
`building`	string
`apartment`	string
`zip`	string

Cancel existing active declaration requests

Find all active declaration requests for the same patient (declaration_requests.mpi_id)
1. Active - means declaration requests in statuses (NEW, APPROVED)
Update status for found declaration requests to CANCELED
Update status_reason for found declaration requests to request_cancelled

Save declaration request

IL.declaration_requests

Parameter	Source	Comments

Parameter	Source	Comments
id		Autogenerated
data	start_date end_date person_id Request.division_id Request.employee_id legal_entity_id	https://e-health-ua.atlassian.net/wiki/spaces/PCAB/pages/17513447465/PIS.+Create+Declaration+request_EN#Calculate-declaration-start%2Fend-date https://e-health-ua.atlassian.net/wiki/spaces/PCAB/pages/17513447465/PIS.+Create+Declaration+request_EN#Validate-Person https://e-health-ua.atlassian.net/wiki/spaces/PCAB/pages/17513447465/PIS.+Create+Declaration+request_EN#Validate-legal-entity
status		Const: NEW
inserted_by		Authenticated user (id)
inserted_at		Current date-time
updated_at		Current date-time
authentication_method_current		https://e-health-ua.atlassian.net/wiki/spaces/PCAB/pages/17548050463/Create+declaration+request+v3#Set-auth_method_current
documents		Empty list
printout_content		https://e-health-ua.atlassian.net/wiki/spaces/PCAB/pages/17513447465/PIS.+Create+Declaration+request_EN#Generate-printout-form
updated_by		Authenticated user (id)
declaration_id		Autogenerated
mpi_id	person_id	https://e-health-ua.atlassian.net/wiki/spaces/PCAB/pages/17513447465/PIS.+Create+Declaration+request_EN#Validate-Person
overlimit		null
channel		Const: PIS
declaration_number		https://e-health-ua.atlassian.net/wiki/spaces/PCAB/pages/17513447465/PIS.+Create+Declaration+request_EN#Generate-human-readable-declaration-number
data_legal_entity_id	data.legal_entity_id
data_employee_id	data.employee_id
data_start_date_year		Extract year from data.start_date
data_person_tax_id		null
data_person_first_name		null
data_person_last_name		null
data_person_birth_date		null
data_person_documents		null
authorize_with		null
data_to_be_signed		https://e-health-ua.atlassian.net/wiki/spaces/PCAB/pages/17513447465/PIS.+Create+Declaration+request_EN#Prepare-data_to_be_signed
parent_declaration_id		null
status_reason		null
current_declaration_count		null
system_declaration_limit		null
is_shareable		Const: false
data_division_id	data.division_id

Configuration parameters

N/A

Dictionaries

N/A

Input parameters

	Input parameter	Mandatory	Type	Description	Example

	Input parameter	Mandatory	Type	Description	Example
1
2

Request structure

See on API-specification

Headers

Request data validation

Authorization

Verify the validity of access token
- Return (401, 'Invalid access token') in case of validation fails
Verify that token is not expired
- in case of error - return (401, 'Invalid access token')
Check user scopes in order to perform this action (scope = 'declaration_request:write_pis')
- Return (403, 'Your scope does not allow to access this resource. Missing allowances: declaration_request:write_pis ') in case of invalid scope(s)

Validate request

Validate request using JSON schema
- In case validation failed - generate 422 error

Validate Person

Get person_id from token (x-person-id header)
Validate patient status is active (status = ‘active' & is_active = 'true’)
- in case of error - return 404 ('not found')
Validate verification status (verification_status != ‘NOT_VERIFIED’)
- in case of error - return 409 ('Person is not verified')

Validate confidant person and relationship (optional)

If person is not legally capable - system must ensure that declaration is created by confidant person and there is registered and verified their relationship

Get applicant_person_id from token, compare it to person_id from token:

If equals - check that person must not be authorized by confidant person, so it doesn’t correspond to following rules:
- persons age < no_self_registration_age global parameter;
- persons age between no_self_registration_age and person_full_legal_capacity_age global parameters and person does not have document with type from PIS_PERSON_LEGAL_CAPACITY_DOCUMENT_TYPES config parameter;
- persons age > person_full_legal_capacity_age global parameter and exists at least one active and approved confidant person relationship for person (using following process https://e-health-ua.atlassian.net/wiki/spaces/PCAB/pages/17415995422 with person_id = person from request - expected :ok, :approved response)
  - In case of error - return 409 (‘Request must be authorized by confidant person’)
If not equal - validate relationship with following steps:
- Check that there is registered relationship between person_id and applicant_person_id(MPI.confidant_person_relationships)
- Check that relationship is VERIFIED
  - In case of error - return 409 (‘Can’t confirm relationship’)
- Check that applicant_person_id exists (status = 'active' & is_active = 'true') and has verification_status any but NOT_VERIFIED
  - In case of error - return 409 (‘Confidant person not found or is not verified’)

Validate division

Check that selected division exists and belongs to the same legal entity

Get division by id provided in request (Request.division_id)
- in case of error - return 409 ('Division doesn’t exist')
Check division status is ACTIVE
- In case of error - return 409 ('Invalid division status')

Validate legal entity

Get legal entity by id from division

Check that selected legal entity is active and is of proper type

Check legal entity status is ACTIVE
- In case of error - return 409 ('Invalid legal entity status')
Check legal entity type in (MSP, PRIMARY_CARE) (config DECLARATION_REQUEST_LEGAL_ENTITY_TYPES)
- in case of error - return 409 ('Invalid legal entity type')

Validate doctor (employee)

Check that selected employee exists, is of type doctor and belongs to the same legal entity

Get employee by id provided in request (Request.employee_id)
- in case of error - return 409 ('Employee doesn’t exist')
Check employee status is APPROVED
- In case of error - return 409 ('Invalid employee status')
Check employee type is DOCTOR
- In case of error - return 409 ('Invalid employee type')
Check that employee belongs to the same legal entity (division.legal_entity_id matches with employee.legal_entity_id)
- In case of error - return 409 ('Employee must belongs to the same legal entity')

Check that doctor speciality meets the patient age requirements

Speciality officio	Patient age

Speciality officio	Patient age
FAMILY_DOCTOR	All ages
THERAPIST	Greater or equal to config adult_age
PEDIATRICIAN	Less than config adult_age

Get doctor's speciality_officio (speciality object where speciality_officio == true)
Calculate patient age
Check age requirements according to global parameters
- In case of error - return 409 ('Doctor speciality doesn't match patient's age')

Check active patient requests

Do not create declaration request if there are active patient requests

Search for active person requests (IL.person_requests) by person_id (IL.person_requests.person_id) where status in (NEW, APPROVED)
- If there is at least one active request - return 409 ('It is prohibited to create declaration request when there is unfinished person request')

Processing

N/A

Response structure examples