REST API method / Метод REST API (настанова) (remove the link block before publishing the document)

• Properties of a REST API method document

• Purpose

• Logic

• Configuration parameters

• Dictionaries

• Input parameters

• Request structure

• Headers

• Request data validation

• Processing

• Response structure examples

• HTTP status codes

• Post-processing processes

• Technical modules where the method is used

Properties of a REST API method document

Purpose

This WS allows to mark Composition as entered_in_error.

Key points

1. Only an employee who registered a Composition, employee from the same legal entity, or employee that has an approval to mark the Composition as as entered_in_error are able to perform this action.

2. Request should be signed with DS.

3. Composition is marked as entered-in-error asynchronously.

Logic

Service logic

1. Create job and return it’s id.

2. Update Composition record with following:

   1. status = $.status

   2. status_reason = $.status_reason

   3. explanatory_letter =$.explanatory_letter

   4. updated_at = current datetime

   5. updated_by = user_id from token

3. Send SMS to patient with composition number via template MARK_IN_ERROR_{{COMPOSITION_TYPE}}_COMPOSITION_SMS_TEMPLATE

   1. If $.authorize_with is submitted - use it as patient’s authentication method

   2. If $.authorize_with is not submitted - determine patient's default authentication method as described at Determination of a default authentication method and return person's active auth_methods

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

  • in case of error - 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 = 'composition:mark_in_error')

  • return 403 (“Your scope does not allow to access this resource. Missing allowances: composition:mark_in_error”) in case of invalid scope(s)

• If BLOCK_UNVERIFIED_PARTY_USERS is true, then check party's data match following condition: verification_status != NOT_VERIFIED or (verification_status = NOT_VERIFIED and updated_at > current_date - UNVERIFIED_PARTY_PERIOD_DAYS_ALLOWED):

  • in case not match - return 403 ("Access denied. Party is not verified")

• If BLOCK_DECEASED_PARTY_USERS is true, check that party is not deceased (party_veri

• fication record does not equal to: dracs_death_verification_status = VERIFIED and dracs_death_verification_reason = MANUAL_CONFIRMED):

  • in case of error - return 403 ("Access denied. Party is deceased")

Validate Digital Sign

• Validate request is signed

  • in case of error - return 422 (“Invalid signed content”)

• Check DS is valid and not expired

• Validate that DS belongs to the user

  • Check that DRFO from DS and user's party.tax_id matches

    • in case of error - return 409 (“Does not match the signer drfo“)

Validate legal entity

• Extract client_id from token

• Check legal entity status (status = ACTIVE)

  • In case of error - return 409 ('client_id refers to legal entity that is not active')

• Validate the Composition belongs to the legal entity where the current user works

  • Check $.composition.custodian==token.client_id

    • in case of error - return 409 ("User is not allowed to perform actions with an enity that belongs to another legal entity")

Validate user

Cancelation of a Composition is allowed for a user if he has one of the following active and approved employee that:

• is an attester of the Composition (Composition.attester)

• has a Med_Admin employee type and belong to same legal entity

• has an approval granted by the patient with access_level:write for the Composition resource (approvals.granted_resources) and has a DOCTOR or SPECIALIST employee type

  • in case of error - return 409 ("Employee is not the one who registered the Composition, doesn't have an approval or required employee type")

Validate data consistency

• Ensure that submitted Composition relates to the Patient (from URL)

  • in case of error - return 404 (not found)

Validate status transition

• Check Composition’s status is not entered-in-error

  • in case of error - return 409 ('Composition in status <status> cannot be marked as entered-in-error ')

Validate Composition mark-in-error term

• Get config parameter COMPOSITION_MARK_IN_ERROR_TERM, where Configuration.type=Composition.type and Configuration.category=Composition.catergory

• Validate today >= (Composition.date+COMPOSITION_MARK_IN_ERROR_TERM.min)

• Validate today <= (Composition.date+COMPOSITION_MARK_IN_ERROR_TERM.max)

  • Return 422 ("Difference between Composition date and todays date must be in range of <min value> and <max value> days") in case of error

Validate request

Validate request by schema and return 422 error code with the list of validation errors in case of fails. User fills following fields in the request:

1. Status reason

1.1 Validate value in the field $.status_reason, CodeableConcept type, required.

• Check that value is in allowed values from COMPOSITION_CANCELLATION_REASONS dictionary.

  • in case of error - return 422 ('value is not allowed in enum')

1.2 Validate value in the field $.status_reason corresponds to the config

• Get config parameter COMPOSITION_MARK_IN_ERROR_STATUS_REASON, where Configuration.type=Composition.type and Configuration.category=Composition.catergory

• Check that value is in allowed values from COMPOSITION_MARK_IN_ERROR_STATUS_REASON

  • in case of error - return 422 ('Invalid status reason for such composition type and category')

2. Status

The target status value must be submitted in the order of display in the signed content (media storage)

1. Validate $.status is entered_in_error

   1. in case of error - return 422 ("value is not allowed in enum")

3. explanatory_letter

Validate explanatory_letter is not an empty

1. in case of error - return 422 ("explanatory_letter can not be empty")

Validate content

Signed content must match to the Composition from DB in order to be canceled

1. Render the Composition from DB

2. Exclude $status, $.status_reason, $.explanatory_letter from signed content

3. Compare rendered Composition and signed content

   1. In case both object doesn't match - return 422 ('Signed content doesn't match with previously created Composition')

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