Purpose

Method to create declaration request via patient information system

Specification

Apiary

Validations

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

...

• 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 Check confidant person relationship 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 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

• 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')

Service logic

Calculate declaration start/end date

1. start_date - date when declaration was originated (current date)

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

1. Use algorithm to generate declaration_number

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

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

1. Call MAN service to render printout form

2. Get template id from config (DECLARATION_REQUEST_PRINTOUT_FORM_TEMPLATE_ID)(PIS_DECLARATION_REQUEST_PRINTOUT_FORM_TEMPLATE_ID)

3. Prepare printout content based on declaration request data

4. Render printout form and save to declaration request

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

...

    %{
      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

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

Legal entity

Preload legal entity object from PRM.legal_entities

Accreditation

License

Employee

Preload employee object from PRM.employees

Party

Division

Preload division object from PRM.divisions

Person

Preload person object from MPI.persons

Document

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/PCABEH/pages/1751344746517628660189/PIS.+Create+Declaration+request_EN#Validaterequest#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)

...

Emergency contact

Confidant person

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

...

Common

Phone

Address

Cancel existing active declaration requests

1. Find all active declaration requests for the same patient (declaration_requests.mpi_id)

   1. Active - means declaration requests in statuses (NEW, APPROVED)

2. Update status for found declaration requests to CANCELED

3. Update status_reason for found declaration requests to request_cancelled

Save declaration request

IL.declaration_requests