Required parameters are marked with "*"

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

Purpose*

This method must be used to register new Service Request in the eHealth.

Specification*

Logic*

This method must be used to register new Service Request in the eHealth. Method receives signed message (pkcs7) that consists of signed content, digital signature and signer public key. All signature fields will be validated (including signer certificate authority). Service will store signed copy of Service Request in Media Content Storage if all checks is passed.

Signed content consists of JSON object with Service Request data.

It can be processed in both sync and async methods depends on Server decision.

Input parameters

Request structure*

See on Apiary

Example:

{
  "signed_data": "ew0KICAicGVyaW9kIjogew0KIC..."
}

Authorize*

• Verify the validity of access token

  • Return (401, 'unauthorized') in case of validation fails

• Verify that token is not expired

  • in case of error - return (401, 'unauthorized')

• Check user scopes in order to perform this action (scope = 'service_request:write')

  1. Return (403, 'invalid scopes') in case of invalid scope(s)

Request to process the request using a token in the headers

Headers*

Наприклад:

• Content-Type:application/json

• Authorization:Bearer mF_9.B5f-4.1JqM

• api-key:aFBLVTZ6Z2dON1V

Request data validation*

Validate digital signature

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

1. Ensure that digital signature is valid

2. Validate that requester of service request is a current user

2.1. Get token metadata

• Extract user_id, client_id, client_type

2.2. Determine the party_id associated with this user_id

SELECT pu.party_id FROM party_users pu
WHERE pu.user_id = :user_id;

2.3. Determine employees related to this party_id in current MSP

WHERE pu.user_id = :user_id;
AND e.legal_entity_id = :client_id;

2.4 Ensure that $.requester.identifier.value matches with user employees

1. Validate that DS belongs to the requester of encounter

3.1. Determine the party_id associated with requester ($.requester.identifier.value)

SELECT p.tax_id FROM employees e, parties p WHERE e.party_id = p.id
AND e.id = :requester;

Validate request using JSON Schema

Return 422 with the list of validation errors in case validation fails

Validate Legal Entity Type

Validate legal entity from token:  legal_entities.type should be in me_allowed_transactions_le_types and legal_entities.status =='active' 

Validate service request

1. Validate that service request ID is unique

   1. $.id must be unique

      1. in case of error return 409 - "Service request with such id already exists"

2. Requisition is a common identifier for the group of service requests and it must matches with one of the patient's encounter number

   1. $.requisition must match with patient's encounter of care number

      1. in case of error return 409 - "Incorrect requisition number"

3. Service request category must refer to a valid dictionary

   1. $.category.coding[*].system  == "ehealth/SNOMED/service_request_categories" 

      1. in case of error return 409 "Incorrect service request category"

   2. in case service was defined as a code (not a service_group) validate service_request.category=service.category from $code.identifier.value

      1. in case error return 422, "Category mismatch"

   3. if category in (hospitalization, transfer_of_care), do not validate service_request.category=service.category from $code.identifier.value

4. Patient must be active

   1. $.patient.identifier.type.coding[*].system == "eHealth/resources"

   2. $.patient.identifier.type.coding[*].code == "patient"

   3. $.patient.identifier.value refer to active MPI (is_active == true and status == 'active')

   4. check if patients.preperson == true

      1. check PREPERSON_SERVICE_REQUEST_ALLOWED_CATEGORIES (values from dictionary: eHealth/SNOMED/service_request_categories) configuration according allowed categories for prepersons

         1. in case of error return 422 (Category of service request is not allowed for prepersons)

5. Context must be an active encounter

   1. $.context.identifier.type.coding[*].system == "eHealth/resources"

   2. $.context.identifier.type.coding[*].code == "encounter"

   3. $.context.identifier.value refer to existing encounter (status == 'finished')

   4. if category = transfer_of_care,

      1. validate encounter.hospitalization.Discharge_Disposition='transfer_general', in case error return 422, "Context is not valid for service request with type $type"

6. Occurence is a valid date-time in the future

   1. $.occurrenceDateTime

      1. $.occurrence_date_time - ISO date must be greater current date-time

   2. $.occurrencePeriod.start

      1. $.occurrence_period.start - ISO date must be greater than current date-time

      2. $.occurrence_period.end - ISO date must be greater than current date-time and greater than $.occurrencePeriod.start

   3. in case based_on passed in request

      1. if care plan activity has detail.scheduled_timing.repeat.bounds_period - validate occurence within bounds_period

      2. if care plan activity has detail.scheduled_period - validate occurence within scheduled_period

      3. else - validate occurence within care_plan.period

7. Authored On is a valid date-time in the past

   1. $.authored_on - ISO date must be less than current date-time

8. Requester_employee must be active employee within current legal entity

   1. $.requester_employee.identifier.type.coding[*].system == "eHealth/resources"

   2. $.requester_employee.identifier.type.coding[*].code == "employee"

   3. $.requester_employee.identifier.value refer to active employee within current legal entity (employee.status == approved and employee.is_active == true and employee.legal_entity_id == token.client_id and employee.type=value from list of employee_types in configuration: ALLOWED_SERVICE_REQUEST_REQUESTER_EMPLOYEE_TYPES )

9. Requester is one of current user's employee

   1. in case of error return 422 "User is not allowed to create service request for the employee"

10. Requester_legal_enity must be current legal enity

11. Supporting info must refer to a valid medical events object (Episode of Care) within specified patient. 

    1. $.supporting_info.identifier.type.coding[*].system == "eHealth/resources"

       1. in case of error return 409 "Incorrect supporting info"

12. Reason reference must refer to a valid medical events object (Observation, Condition) within specified patient. 

    1. $.reason_reference.identifier.type.coding[*].system == "eHealth/resources"

    2. $.reason_reference.identifier.type.coding[*].code in ("condition", "observation")

       1. in case of error return 409 "Incorrect reason reference"

13. Permitted Episode of care must refer to a valid medical events object (Episode of Care) within specified patient. 

    1. $.permitted_episodes.identifier.type.coding[*].system == "eHealth/resources"

    2. $.permitted_episodes.identifier.type.coding[*].code == "episode_of_care"

       1. in case of error return 409 "Incorrect permitted episode"

14. Validate that permitted episodes is not specified in case of category "laboratory_procedure"

    1. in case of error 422 "Permitted episodes are not allowed for laboratory category of service request"

15. Validate expiration_date is in future

    1. in case of error return 422 "Expiration date can not be in past"

16. Validate code is an existing service or service group that is allowed to be used in service_request
     Note. For service_request.code pass "service", "service_group"

    1. in case not found or is_active == false return 422 "Service(Service group) not found"

    2. if request_allowed==false return error 422 "Request is not allowed for this service"

    3. in case based_on passed in request

       1. If service_requests.code.identifier.value is service, validate $based_on[].activity.code.identifier.value = service_requests.code.identifier.value

          1. in case error return 409, "Service in care plan activity differ from service in service request"

       2. If service_requests.code.identifier.value is service_group, validate $based_on[].activity.code.identifier.value = service_requests.code.identifier.value

          1. in case error return 409, "Service group in care plan activity differ from service group in service request"

17. If program was specified, validate it is an existing service program (type=service)

    1. in case not found or is_active==false return 422  "Program not found"

    2. in case type!= service return 422 "Invalid program type"

    3. check if medical_programs.medical_program_settings.care_plan_required == true then the request should contain a based_on with care plan and activity that contains the same medical program

       1. in case of error return 422 with msg ("Care plan and activity with the same program should be present in request")

       2. check that program equal to $.activity[].program

          1. in case of error return 422 with msg ("Program from activity should be equal to program from request")

18. If program was specified, validate that service(or service_group) is an active member of the program

    1. Select request_allowed, is_active from PRM.program_services where service_id(or group_id) == $.signed_content.code.identifier.value and program_id=$.program.identifier.value

       1. if not found or is_active==false return 422 "Service is not included in the program"

       2. if request_allowed==false return 422 "Service request is not allowed for this service(service_group) in this programm"

19. Validate performer

    1. if category = transfer_of_care,

       1. performer is sent, in case error return 422, "performer is mandatory for category `transfer_of_care`"

       2. performer is real LE with status=Active and is_Active=true, in case error, return 422, "performer is not active legal entity"

20. validate LocationReference

    1. if category = transfer_of_care,

       1. LocationReference is real division with type in (CLINIC, LICENSED_UNIT,AMBULANT_CLINIC,FAP) and status=Active and is_active=true, in case error return 422, "LocationReference is not an active division"

       2. LocationReference division.legal_entity_id=Performer, in case error return 422, "Division does not belong to performer legal entity"

21. Validate PerformerType

    1. if category = hospitalization

       1. PerformerType is sent, in case error return 422, "PerformerType is mandatory for category hospitalization"

       2. PerformerType is a code from dictionary.SPECIALITY_TYPE and match config file 'SERVICE_REQUEST_HOSPITALIZATION_SPECIALITY_TYPES', in case error return 422, "PerformerType=$PerformerType is forbidden for category hospitalization"

       3. if performer_type value is included in chart variables 'SERVICE_REQUEST_PERFORMER_TYPE_SPECIALITY_TYPES':

          1.  define allowed service codes for service_requests.code.identifier.value using a set of chart variables  'SERVICE_REQUEST_<SPECIALITY_TYPE>_PERFORMER_TYPE_CODES', in case of error return 422 “Service does not correspond to performer's speciality for hospitalization“

    2. if category = transfer_of_care

       1. if service codes for service_requests.code.identifier.value using a set of chart variables 'SERVICE_REQUEST_TRANSFER_OF_CARE_<SPECIALITY_TYPE>_PERFORMER_TYPE_CODES', performer_type field is mandatory

          1. in case error return 422, "PerformerType is mandatory"

       2. PerformerType is a code from dictionary.SPECIALITY_TYPE and match config file 'SERVICE_REQUEST_TRANSFER_OF_CARE_SPECIALITY_TYPES', in case error return 422, "PerformerType=$PerformerType is forbidden for category transfer_of_care"

       3. if performer_type value is included in chart variables 'SERVICE_REQUEST_TRANSFER_OF_CARE_PERFORMER_TYPE_SPECIALITY_TYPES':

          1.  define allowed service codes for service_requests.code.identifier.value using a set of chart variables 'SERVICE_REQUEST_TRANSFER_OF_CARE_<SPECIALITY_TYPE>_PERFORMER_TYPE_CODES', in case of error return 422 “Service does not correspond to performer's speciality for transfer of care“

22. Validate based_on

    1. If submitted, check field has array with two values of Reference type: one is valid Care plan resource, another - Activity resource.

       1. in case of error return 422 with msg ("expected a minimum of %{min} items but got %{actual}")

    2. Verify Care plan:

       1. It should belong to the same person as set in service request

          1. in case of error return 422 with msg ("Care plan with such id is not found")

       2. It should be in active status

          1. in case of error return 422 with msg ("Care plan is not active")

    3. Verify submitted Activity:

       1. It belongs to the Care plan.

       2. It has activity.detail.kind=service_request; activity.detail.product_reference=service_request.code[].value

          1. in case of error return 422 with msg ("Invalid activity kind")

       3. It has scheduled, in_progress status

          1. in case of error return 422 with msg ("Invalid activity status")

       4. If activity.program submitted than $.service_request.program with equal value should be present in request

          1. in case of error return 409 with msg ('Program from activity should be present in request')

       5. if activity.quantity was set, then validate activity.remaining_quantity greater then zero:

          1. in case of error return 409 "The number of available services according to the care plan activity has been exhausted"

23. Validate patient's verification status:

    1. If SR has based_on with valid activity, then skip this validation.

    2. Else check patient's verification_status is not equal to NOT_VERIFIED.

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

Processing*

Service logic

1. Generate requisition number (see Human readable requisition number) based on encounter id

2. Save signed content to media storage

3. Save data to corresponding collection in DB

4. Save link to the signed content in service request storage

5. If program was specified, change program_processing_status to New

Send SMS notification

If patient's default authentication method determined by Determination of a default authentication method and return person's active auth_methods is OTP or third_person.OTP, send SMS to that patient with requisition number

In order to optimize the costs, only one sms should be sent within one encounter. So that send sms only for the first service request for specific encounter

1. Search for service requests with the same requisition number

   1. if there is at least one service request with such number - do not send sms

   2. if no service requests found - send sms to the patient 

Response structure*

See on Apiary

Example:

{
  "data": {
    "id": "90a9e15b-b71b-4caf-8f2e-ff247e8a5600",
    "requisition": "AX654654T",
    "status": "active",
    "program": {
      "identifier": {
        "type": {
          "coding": [
            {
              "system": "eHealth/resources",
              "code": "medical_program"
            }
          ]
        },
        "value": "9183a36b-4d45-4244-9339-63d81cd08d9c"
      },
      "display_value": "null"
    },
    "program_processing_status": "new",
    "status_history": [
      {
        "status": "closed",
        "status_reason": {
          "coding": [
            {
              "system": "eHealth/service_request_recall_reasons",
              "code": "cured"
            }
          ]
        },
        "inserted_at": "2018-08-02T10:45:16.000Z"
      }
    ],
    "program_processing_status_history": [
      {
        "program_processing_status": "new",
        "inserted_at": "2018-08-02T10:45:16.000Z",
        "inserted_by": "f7bdce4c-9d6e-4b08-913c-97c4b972f9be"
      }
    ],
    "program_service": {
      "identifier": {
        "type": {
          "coding": [
            {
              "system": "eHealth/resources",
              "code": "program_service"
            }
          ]
        },
        "value": "9183a36b-4d45-4244-9339-63d81cd08d9c"
      },
      "display_value": "null"
    },
    "intent": "order",
    "priority": "routine",
    "based_on": [
      {
        "identifier": {
          "type": {
            "coding": [
              {
                "system": "eHealth/resources",
                "code": "care_plan"
              }
            ]
          },
          "value": "9183a36b-4d45-4244-9339-63d81cd08d9c"
        }
      },
      {
        "identifier": {
          "type": {
            "coding": [
              {
                "system": "eHealth/resources",
                "code": "activity"
              }
            ]
          },
          "value": "9183a36b-4d45-4244-9339-63d81cd08d9c"
        }
      }
    ],
    "category": {
      "coding": [
        {
          "system": "eHealth/SNOMED/service_request_categories",
          "code": "409063005"
        }
      ]
    },
    "code": {
      "identifier": {
        "type": {
          "coding": [
            {
              "system": "eHealth/resources",
              "code": "service"
            }
          ]
        },
        "value": "9183a36b-4d45-4244-9339-63d81cd08d9c"
      },
      "display_value": "null"
    },
    "subject": {
      "identifier": {
        "type": {
          "coding": [
            {
              "system": "eHealth/resources",
              "code": "patient"
            }
          ]
        },
        "value": "9183a36b-4d45-4244-9339-63d81cd08d9c"
      },
      "display_value": "null"
    },
    "context": {
      "identifier": {
        "type": {
          "coding": [
            {
              "system": "eHealth/resources",
              "code": "encounter"
            }
          ]
        },
        "value": "9183a36b-4d45-4244-9339-63d81cd08d9c"
      },
      "display_value": "null"
    },
    "occurrence_period": {
      "start": "2018-08-02T10:45:16.000Z",
      "end": "2018-08-02T11:00:00.000Z"
    },
    "requester_employee": {
      "identifier": {
        "type": {
          "coding": [
            {
              "system": "eHealth/resources",
              "code": "employee"
            }
          ]
        },
        "value": "9183a36b-4d45-4244-9339-63d81cd08d9c"
      },
      "display_value": "null"
    },
    "requester_legal_entity": {
      "identifier": {
        "type": {
          "coding": [
            {
              "system": "eHealth/resources",
              "code": "legal_entity"
            }
          ]
        },
        "value": "75a6d991-0bf7-476f-b3cf-bec83f044b2a"
      },
      "display_value": "null"
    },
    "reason_references": [
      {
        "identifier": {
          "type": {
            "coding": [
              {
                "system": "eHealth/resources",
                "code": "condition"
              }
            ]
          },
          "value": "9183a36b-4d45-4244-9339-63d81cd08d9c"
        },
        "display_value": "null"
      }
    ],
    "supporting_info": [
      {
        "identifier": {
          "type": {
            "coding": [
              {
                "system": "eHealth/resources",
                "code": "episode_of_care"
              }
            ]
          },
          "value": "9183a36b-4d45-4244-9339-63d81cd08d9c"
        },
        "display_value": "null"
      }
    ],
    "note": "Some notes",
    "patient_instruction": "Some patient instructions",
    "expiration_date": "2018-08-02T10:45:16.000Z",
    "permitted_resources": [
      {
        "identifier": {
          "type": {
            "coding": [
              {
                "system": "eHealth/resources",
                "code": "episode_of_care"
              }
            ]
          },
          "value": "9183a36b-4d45-4244-9339-63d81cd08d9c"
        },
        "display_value": "null"
      }
    ],
    "used_by_employee": {
      "identifier": {
        "type": {
          "coding": [
            {
              "system": "eHealth/resources",
              "code": "legal_entity"
            }
          ]
        },
        "value": "9183a36b-4d45-4244-9339-63d81cd08d9c"
      },
      "display_value": "null"
    },
    "inserted_at": "2018-08-02T10:45:16.000Z",
    "updated_at": "2018-08-02T10:45:16.000Z",
    "completed_with": {
      "identifier": {
        "type": {
          "coding": [
            {
              "system": "eHealth/resources",
              "code": "diagnostic_report"
            }
          ]
        },
        "value": "9183a36b-4d45-4244-9339-63d81cd08d9c"
      },
      "display_value": "null"
    },
    "used_by_legal_entity": {
      "identifier": {
        "type": {
          "coding": [
            {
              "system": "eHealth/resources",
              "code": "legal_entity"
            }
          ]
        },
        "value": "c5a6d991-0bf7-476f-b3cf-bec83f044b2a"
      },
      "display_value": "null"
    },
    "performer": {
      "identifier": {
        "type": {
          "coding": [
            {
              "system": "eHealth/resources",
              "code": "legal_entity"
            }
          ]
        },
        "value": "c5a6d991-0bf7-476f-b3cf-bec83f044b2a"
      },
      "display_value": "Опанасенко Олексій Володимирович"
    },
    "location_reference": {
      "identifier": {
        "type": {
          "coding": [
            {
              "system": "eHealth/resources",
              "code": "division"
            }
          ]
        },
        "value": "c5a6d991-0bf7-476f-b3cf-bec83f044b2a"
      },
      "display_value": "null"
    },
    "performer_type": {
      "coding": [
        {
          "system": "SPECIALITY_TYPE",
          "code": "DIETETICS"
        }
      ]
    }
  },
  "meta": {
    "code": 201,
    "url": "http://example.com/resource",
    "type": "object",
    "request_id": "req-adasdoijasdojsda"
  }
}

{
  "data": {
    "status": "pending",
    "eta": "2018-08-02T10:45:16.000Z",
    "links": [
      {
        "entity": "job",
        "href": "/Jobs/NBXk9EyErUZv1RhXgyvgg"
      }
    ]
  },
  "meta": {
    "code": 202,
    "url": "http://example.com/resource",
    "type": "object",
    "request_id": "req-adasdoijasdojsda"
  }
}

Post-processing processes*

API paragraph not found

HTTP status codes*