Required parameters are marked with "*"

Якщо інформації по відповідному параметру немає, потрібно зазначити: “API paragraph not found”.

Purpose*

This method is used to create Declaration Request (as part of Declaration creation process) via new api. This method allows you to create a declaration only for an existing person.

Specification*

Logic*

To create declaration request based on active declaration in reorganized legal entity, parent_declaration_id must be passed in request.

Global and configuration parameters

Invoke Global parameters to get following parameters:

Filters

А точно ли это фильтры, а не Input Parameters ?

Request structure*

See on Apiary

{
  "person_id": "4d0d790c-cbf1-44f5-ab21-ba8db67da161",
  "employee_id": "1a8b10ea-ba09-40f2-8f9e-55608e9208c6",
  "division_id": "d290f1ee-6c54-4b01-90e6-d701748f0851",
  "authorize_with": "cc949559-5dfe-420f-ac05-065e443b2cc6",
  "parent_declaration_id": "8c7753fc-a647-435f-8e43-4ff4546431f6"
}

Authorize*

1. Verify the validity of access token

   1. in case error return 401 

2. Check users scopes (declaration_request:write) to perform this action

   1. in case error return 403 - forbidden

Request to process the request using a token in the headers

Headers*

• Content-Type:application/json

• Authorization:Bearer c2778f3064753ea70de870a53795f5c9

• api-key:uXhEczJ56adsfh3Ri9SUkc4en

Validate request (JSON schema)*

 {
  "$schema": "http://json-schema.org/declaration_request_new/schema#",
  "type": "object",
  "properties": {
    "person_id": {
      "type": "string"
    },
    "employee_id": {
      "type": "string"
    },
    "division_id": {
      "type": "string"
    },
    "authorize_with": {
      "type": "string"
    }
  },
  "required": [
    "person_id",
    "employee_id",
    "division_id"
  ]
}

Validation data request*

Validate Legal Entity Type

Validate legal entity from token:  legal_entities.type should be in DECLARATION_REQUEST_LEGAL_ENTITY_TYPES("MSP,PRIMARY_CARE,MSP_PHARMACY") and legal_entities.status =='active' 

Validate doctor

Get employee details

Invoke Get employee details

Validate Response $.data.employee_type == DOCTOR

Take the doctor_id and the division_id from the token

Validate person 

• validate person_id UUID

  • in case error return 422

• search person by person_id in MPI 

  • in case error return 404, "Such person doesn't exist"

• validate person.auth_method != NA

  • in case error return 422, "Person must have authentication method"

• validate person.status = ‘active’ and is_active =true

  • in case error return 404, "Such person doesn't exist"

Validate person verification status

• validate patient's verification_status is not equal to NOT_VERIFIED.

  • in case of error return 409, "Patient is not verified"

Validate authorize_with

The person can pass the id of his auth_method which he wants to confirm the create declaration request. The necessary auth method can be found by making Get person's auth methods

1. validate auth_method.id is UUID

   1. in case error return 422

2. search auth method in MPI.person_authentication_method

   1. in case error return 422, "such authentication method doesn't exist"

3. search auth method of this person where  MPI.person_authentication_method.person_id = $.person.id

   1. in case error return 422, "such authentication method does not belong to this person"

4. validate that auth_method.type = NA

   1. in case error return 422, "Сannot be confirmed by a method with type= NA. Use a different method."

5. validate that this method is active ( authentication_method.ended_at > now() and is_active = true)

This field is optional and set in il.declaration_reques.authentication_method_current.

If person request doesn't have this field, then choose that method which is returned from mpi as person's default method

Calculate patient age

Calculate patient age

age = MONTHS_BETWEEN (now(), $.mpi.person.birth_date) / 12

Check that doctor speciality meets the patient age requirements

1. Get doctor's speciality_officio (speciality object where speciality_officio == true)

2. Check age requirements according to global parameters

Validate confidant person

If person age < prm.global_parameters.no_self_auth_age check existence of confidant_person

• in case error return 422 - msg "Confidant person is mandatory for children"

Processing*

Search pending declaration requests

Search declarations in IL_DB.declaration_requests to prevent requests duplication:

where IL.Declaration_request.mpi_id = :($.person.id) and status in ('NEW' or 'APPROVED)
Cancel declaration requests

Change status of all found declarations:

SET   IL_DB.declaration_requests.status = 'CANCELED'
WHERE IL_DB.declaration_requests.id IN (:LIST)

Calculate declaration end/start date

Declaration 

Start date:

start_date = Current_date()

End date:

if (person.age < prm.global_parametrs.adult_age)&(doctor.speciality = PEDIATRICIAN) {
  end_date = min(birth_date + prm.global_parametrs.adult_age - 1d, start_date + declaration_term - 1d);
} else {
  end_date = start_date + declaration_term - 1d;
}

Save declaration request

Insert record to IL.declaration_request in status 'NEW'

Generate upload URL

If auth_method_requests.auth_method_current = OFFLINE

• URL for person.documents

Depending on the payload system generates list of signed urls for document scan-copies upload.

Signed URLs to be expired after some period of time (configurable `SECRETS_TTL`). If it has been expired - new declaration request should be created.

Each link is generated for one one-page document in jpeg format. Document should be no more than 10MB.

Set auth_method_current

Set default auth method of person on IL.auth_method_request.auth_method_current - use function in mpi, that return default auth method.

If auth_method_current = NA - return Error "person authentication method is undefined".

Generate verification code

If auth_method_requests.auth_method_current = OTP 

Invoke Initialize OTP to generate one time password and send it where auth_method_requests.auth_method_current = OTP.

cURL example

curl -X POST \
  http://localhost:4000/verifications \
  -H 'content-type: application/json' \
  -d '{
  "phone_number": "+380936235985"
}'

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

• Add field to ops.declarations and il.declaration_requests - declaration_number 

• Add declaration_number to print out form

Validate uniqueness of human readable declaration number

• generate declaration_number

• Search declaration_number in declaration_requests.declaration_number

• if exists = go to 'generate declaration_number'

• else save declaration_number to declaration_request

Response structure*

See on Apiary

Code 201

{
  "meta": {
    "code": 201,
    "url": "https://example.com/resource",
    "type": "object",
    "request_id": "req-adasdoijasdojsda"
  },
  "data": {
    "id": "b075f148-7f93-4fc2-b2ec-2d81b19a9b7b",
    "start_date": "2017-03-02",
    "end_date": "2017-03-02",
    "person_id": "4d0d790c-cbf1-44f5-ab21-ba8db67da161",
    "employee_id": "1a8b10ea-ba09-40f2-8f9e-55608e9208c6",
    "division_id": "d290f1ee-6c54-4b01-90e6-d701748f0851",
    "declaration_number": "0000-12H4-245D",
    "declaration_id": "8311ab82-e341-4da0-8a95-235ec9885e23",
    "parent_declaration_id": "8c7753fc-a647-435f-8e43-4ff4546431f6",
    "status": "NEW",
    "channel": "MIS",
    "authorize_with": "cc949559-5dfe-420f-ac05-065e443b2cc6"
  },
  "urgent": {
    "authentication_method_current": {
      "type": "OTP",
      "number": "+38093*****74"
    },
    "documents": [
      {
        "type": "PASSPORT",
        "url": "https://storage.ehealth.world"
      }
    ]
  }
}

Code 422

{
  "meta": {
    "code": "422",
    "url": "https://example.com/resource",
    "type": "object",
    "request_id": "req-adasdoijasdojsda"
  },
  "error": {
    "type": "unverified",
    "message": "Person not found"
  }
}

Post-processing processes*

Що має відбутися в ЦБД після опрацювання та відправлення відповіді, тощо

HTTP status codes

Backward compatibility

Сумісність з попередніми версіями методу