Properties of a REST API method document

...

...

Document type

...

Метод REST API

...

Guideline ID

...

GUI-0011

...

Author

...

@

...

Document version

...

1

...

Document status

...

DRAFT

...

Date of creation

...

ХХ.ХХ.ХХХХ (дата фінальної версії документа – RC або PROD)

...

Date of update

...

ХХ.ХХ.ХХХХ (дата зміни версії)

...

Method API ID

...

API-001-001-001-0001

...

Microservices (namespace)

...

MPI

...

Component

...

Auth

...

Component ID

...

COM-001-001

...

Link на API-специфікацію

...

https://ehealthmisapi1.docs.apiary.io/#reference/public.-medical-service-provider-integration-layer/manage-client-configuration/get-client-details

...

Resource

...

{{host}}//api.ehealth.gov.ua/api/patients/id/encounter_package

...

Scope

...

Protocol type

...

Request type

...

Sync/Async

...

Public/Private

Purpose

Describe the purpose of the API method, add Key points (if necessary)

Logic

Description of the working algorithm of the API method and the interaction of services with each other add Service logic (if necessary)

Configuration parameters

Description of the configuration parameters that are used when processing a request in the system

Dictionaries

Provides a list of links to dictionaries that are available in Confluence

Input parameters

Description of input parameters

...

Input parameter

...

Mandatory

...

Type

...

Description

...

Example

...

composition_id

...

 M

...

String ($uuid) (path)

...

Composition object ID

...

 89678f60-4cdc-4fe3-ae83-e8b3ebd35c59

...

Request structure

See on API-specification (посилання на сторінку з API-специфікацією)

Description of the REST API request structure, example

...

...

Headers

...

Key

...

Value

...

Mandatory

...

Description

...

Example

...

Content-Type

...

application/json

...

M

...

Тип контенту

...

Content-Type:application/json

...

Authorization

...

Bearer c2778f3064753ea70de870a53795f5c9

...

M

...

Перевірка користувача

...

Authorization:Bearer c2778f3064753ea70de870a53795f5c9

...

Request data validation

Describe the process of checking the input data transmitted in the request for compliance with the given rules and restrictions set in the API

Processing

A list of processes related to receiving, changing or transmitting data according to the logic defined in the REST API

Response structure examples

Description of the REST API response structure, example

...

...

HTTP status codes

...

Response code

...

HTTP Status code

...

Message

...

Internal name

...

Description

...

Базові

...

1000

...

404

...

Composition not found

...

COMPOSITION_NOT_FOUND_404

...

Не знайдено медичний висновок

...

401

...

Unauthorized

...

Помилка підтвердження

...

Специфічні

...

Properties of a REST API method document

Purpose

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

Створення направлення

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.

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

6. If quantity was set:

   1. Fill $.quantity.unit as description of corresponding $.quantity.code from $.quantity.system dictionary

   2. Fill $.remaining_quantity = $.quantity.

7. If the service request is based on activity with quantity:

   1. recalculate and set remaining_quantity for the activity as described https://e-health-ua.atlassian.net/wiki/spaces/EH/pages/17348624600

Image Added

Configuration parameters

Description of the configuration parameters that are used when processing a request in the system

Dictionaries

Service Request Dictionaries and configurable parameters

SERVICE

Input parameters

Description of input parameters

Request structure

See on Apiary

See on API-specification (посилання на сторінку з API-специфікацією)

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

Headers

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 Service request

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 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. If $.specimens attribute is set, then check the category is in SPECIMEN_SERVICE_REQUEST_ALLOWED_CATEGORIES chart parameter

      • in case of error - return 422 ("Service request category is not allowed for specimens")

   5. If $.requester_employee has ASSISTANT type, then check the category in ASSISTANT_SERVICE_REQUEST_ALLOWED_CATEGORIES chart parameter

      1. in case of error - return 422 (“Service request category is not allowed for a requester_employee with type ASSISTANT“)

4. Service request code must refer to a valid dictionary

   1. $.code.identifier.type.coding[*].system  == “eHealth/resources”

      1. in case of error return 422 “value is not allowed in enum”

5. 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)

6. Context must be an active encounter

   1. If focus on specimens is set, then context is optional

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

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

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

   5. 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"

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

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

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

9. 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 )

10. 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"

11. Requester_legal_enity must be current legal enity

12. Supporting info must refer to a valid medical events object (Episode of Care, Condition, Observation, Diagnostic report) within specified patient. 

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

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

13. 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"

14. Permitted resources must refer to a valid medical events object (Episode of Care, diagnostic report) within specified patient. 

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

    2. $.permitted_resources.identifier.type.coding[*].code == "episode_of_care", “diagnostic_report”

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

15. 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"

16. Validate expiration_date is in future

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

17. 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"

18. 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:

       1. 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 present in request

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

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

    4. if program in service request is set check if $.activity[].program is not null

       1. in case of error return error msg (“Program should not be present in request for this activity“)

19. 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"

20. Validate performer

    1. If focus on specimens is set, then performer is optional

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

    3. if category = laboratory_procedure,

       1. performer is optional; if is send - performer is real LE with status=Active and is_Active=true, in case error, return 422, "performer is not active legal entity"

    4. else other category and performer is send return 422 error $.performer.identifier.value “Not allowed for this category“

21. 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"

22. 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“

    3. else other category and PerformerType is send return 422 error $.performer_type.coding[0].value "Not allowed for category <category>"

23. Validate quantity as described in PreQualify Service Request

24. Validate based_on as described in PreQualify Service Request

25. 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"

26. Validate specimens as described at PreQualify Service Request

27. Validate focus as described at PreQualify Service Request

Processing

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. Do NOT send sms in case performer is present

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

See on Apiary

See on API-specification (посилання на сторінку з API-специфікацією)

{
  "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"
  }
}

HTTP status codes

Post-processing processes

Description of actions performed on data after processing

Technical modules where the method is used

List of pages describing technical modules where the method is used

...