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

Properties of a REST API method document

Purpose

Method to sign declaration request via patient information system

Logic

Calculate active declarations for doctor

1. Get all employees connected with the same party_id

2. Get all doctor’s specialities where speciality_officio = true

3. Get current limit for each speciality from global parameters

   1. PEDIATRICIAN: pediatrician_declaration_limit

   2. THERAPIST: therapist_declaration_limit

   3. FAMILY_DOCTOR: family_doctor_declaration_limit

4. Get lowest limit

5. Find all active (status active or pending_verification) declarations with all this employees

   1. If number of declarations greater or equal to limit - declaration request status must be set to APPROVED

   2. If number of declarations lower then limit - declaration request status must be set to SIGNED

Save signed declaration to media storage

Signed content must be stored to different buckets depending on the rule above

1. Get url for declaration upload.

Use Request a Secret WS

1. Upload signed declaration to media storage

Update declaration request

1. Change entity status in IL_DB.declaration_requests to SIGNED or APPROVED depending on number of doctor’s declarations

2. Set is_shareable to true

3. Set system_declaration_limit based on value from previous step

4. Set current_declaration_count based on value from previous step

5. Set updated_at - now() (Get current date-time)

6. Set updated_by - user_id (Extract user from token)

7. Set status_reason

   1. if status changed to SIGNED - status reason must be auto_approve (value of DECLARATION_REQUEST_STATUS_REASON) according to status model (where the channel of action PIS and status SIGNED)

   2. if status changed to APPROVED - status reason must be doctor_approval_needed (value of DECLARATION_REQUEST_STATUS_REASON) according to status model (where the channel of action PIS and status APPROVED)

Get active declarations for patient

Search for active declarations using MPI ID

1. If found - terminate them and create new declaration.

   • If not found - create new declaration.

Terminate declaration

In case active declarations found - terminate all by changing status to TERMINATED

Create declaration (optional)

Create new record OPS.declarations:

1. status: active

2. declaration_request_id: declaration_request.id

3. inserted_at: current date time

4. inserted_by: user from token

5. updated_at: current date time

6. updated_by: user from token

Configuration parameters

N/A

Dictionaries

N/A

Input parameters

Request structure

See on API-specification

Headers

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:sign_pis')

  • Return (403, 'Your scope does not allow to access this resource. Missing allowances: declaration_request:sign_pis ') in case of invalid scope(s)

Validate request

• Validate request using JSON schema

  • In case validation failed - generate 422 error

Validate signature

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

Validate signer

This validation must be done in different ways depending on context:

• if request is done by person itself (applicant_person_id and person_id in token are equals) - we must check that signer DRFO matches with person tax_id or document

• if request is done by confidant person (applicant_person_id and person_id in token are different) - we must check that signer DRFO matches with confidant person tax_id or document

Request is done by person

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

2. Check that DRFO in Certificate details is equal to Person’s tax_id

   1. Get person_id from token

   2. Get Person details using person_id

   3. Compare DRFO in Certificate with person.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

   4. In case validation fails - generate 422 error

Request is done by confidant person

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

2. Check that DRFO in Certificate details is equal to Confidant Person’s tax_id

   1. Get applicant_person_id from token

   2. Get Person details using applicant_person_id

   3. Compare DRFO in Certificate with person.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

   4. In case validation fails - generate 422 error

Latin to Cyrillic mapping

Validate declaration request

• Get declaration_request by id

• Validate declaration request status (status = NEW)

  • in case of error - return 409 ('Invalid transition')

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

• Check that person in declaration request is the same as in token (person_id = Request.person_id)

  • in case of error - return 409 ('Invalid person')

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

Validate declaration number

• Check that there are no other declarations with the same number

  • if exists return 422 - message 'Declaration with the same declaration_number already exists in DB'

Check active patient requests

Do not allow to sign 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 sign declaration request when there is unfinished person request')

Check signed content

• Check that signed content matches with generated data_to_be_signed

  • In case they are not equal - return 422 (message: "Signed content does not match the previously created content")

Processing

N/A

Response structure examples

See on API-specification

HTTP status codes

Post-processing processes

N/A

Technical modules where the method is used