ЕСОЗ - публічна документація

Create Program medication

By Dmytro Kulibaba (Unlicensed)
5 min

Purpose

This WS allows to create new medication program participant.

 

Specification

Link

API paragraph not found

Resource

/program_medications

Scope

program_medication:write

Components

Drugs and Program medications

Microservices

API paragraph not found

Protocol type

REST

Request type

POST

Sync/Async

Sync

Public/Private/Internal

Internal. NHS Admin

 

Logic

  1. Create new program medication entity: store input into program_medications table (prm). Also, set:

    1. medication_request_allowed = true

    2. is_active = true

    3. inserted_at, updated_at = user_id (from token)

    4. inserted_at, updated_at = current date and time.

Key points

  1. This is a graphQl method used in the Administration panel only.

  2. Only authenticated and authorized NHS employee with an appropriate scope can create a Program medication.

  3. Program medication can be created only for a medical program with type MEDICATION.

 

GraphQl Specification

"Creates a single `ProgramMedication`." createProgramMedication( input: CreateProgramMedicationInput! ): CreateProgramMedicationPayload

 

""" Input for `createProgramMedication` mutation. User must have a scope **program_medication:write** """ input CreateProgramMedicationInput { "Id of medication" medicationId: ID! "Medical program Identifier" medicalProgramId: ID! "Reimbursement information" reimbursement: CreateReimbursementInput! "Factory gate price for package of medications" wholesalePrice: Float "Consumer price for package of medications" consumerPrice: Float "Reimbuersement amount for recommended daily dosage of medication" reimbursementDailyDosage: Float "The estimatied amount which patient should pay for package of medications after reimbursement" estimatedPaymentAmount: Float "Start date of action for this entry" startDate: Date "End date for this entry" endDate: Date "General registry identifier" registryNumber: String "Max Daily dose of medication, limited by WHO." maxDailyDosage: Float } """ Input for `Reimbursement` of `createProgramMedication` mutation. """ input CreateReimbursementInput { "Reimbursement type" type: ReimbursementType! "Reimbursement amount" reimbursementAmount: Float "Percentage of reimbursement." percentageDiscount: Float }
""" Return type for `createProgramMedication` mutation. """ type CreateProgramMedicationPayload { "Created `ProgramMedication`." programMedication: ProgramMedication } """ Program Medication linkes medication and medical program. In order to obtain details user must have a scope **program_medication:read** """ type ProgramMedication implements Node { "The ID of an object." id: ID! "Primary key identifier from the database." databaseId: UUID! "MedicalProgram." medicalProgram: MedicalProgram! "Medication" medication: Medication! "Reimbursement information." reimbursement: Reimbursement! "Factory gate price for package of medications" wholesalePrice: Float "Consumer price for package of medications" consumerPrice: Float "Reimbuersement amount for recommended daily dosage of medication" reimbursementDailyDosage: Float "The estimatied amount which patient should pay for package of medications after reimbursement" estimatedPaymentAmount: Float "Start date of action for this entry" startDate: Date "End date for this entry" endDate: Date "General registry identifier" registryNumber: String "Whether `ProgramMedication` is active or not?" isActive: Boolean! "Whether requesting medications allowed for the `ProgramMedication` or not?" medicationRequestAllowed: Boolean! "Date and time when record was inserted" insertedAt: DateTime! "Date and time when record was updated" updatedAt: DateTime! "Max Daily dose of medication, limited by WHO. Null will be returned, if this field has not been set in register." maxDailyDosage: Float }

 

 

Request structure

See on Apiary

{ "medication_id": "59781de0-2e64-4359-b716-bcc05a32c10f", "medical_program_id": "e1453f4c-1077-4e85-8c98-c13ffca0063e", "reimbursement": { "type": "fixed", "reimbursement_amount": 450 }, "wholesale_price": "148.50", "consumer_price": "150.00", "daily_dosage": "200", "reimbursement_daily_dosage": "10.4858", "estimated_payment_amount": "34.50" }

 

Authorize

  • 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 = 'program_medication:write')

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

Request to process the request using a token in the headers

 

Headers

  • Content-Type:application/json

  • Authorization:Bearer c2778f3064753ea70de870a53795f5c9

 

Request data validation

Validate legal entity

  • Extract client_id from token.

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

    • in case of error - return 403 (“Your scope does not allow to access this resource. Missing allowances: program_medication:write”).

Validate request

  1. Check medicalProgramId:

    1. exists in DB

      1. in case of error - return 404 ('not_found')

    2. has type = MEDICATION

      1. in case of error - return 409 ('MedicalProgram type should be MEDICATION')

    3. is_active = true

      1. in case of error - return 409 ('Medical program is not active')

  2. Check start_date < end_date

    1. in case of error - return 422 ('must be earlier than the end date')

  3. Validate reimbursement:

    1. If reimbursement type = FIXED, than reimbursementAmount field required

    2. If reimbursement type = PERCENTAGE, percentageDiscount field required

      1. in case of error - return 422 ('can't be blank')

  4. If percentageDiscount submitted in the reimbursement structure:

    1. Check it’s value in range from 0 to 100

      1. in case of error - return 422 ('expected the value to be <= 100')

  5. Validate medicationId:

    1. Check it is active and it’s type is BRAND

      1. in case of error - return 409 ('Medication is not active')

  6. Validate compliance of INNM_DOSAGE.mr_blank_type:

    1. in case when $.medication.type is BRAND :

      1. Check INNM_DOSAGE

        1. There is link of a BRAND to INNM_DOSAGE (in prm.ingredients table) and INNM_DOSAGE exists

          1. in case of error - return 404 ('INNM_DOSAGE of a BRAND not_found')

        2. is_active = true

          1. in case of error - return 409 ('INNM_DOSAGE of a BRAND is not active')

    2. in case when $.medication.type is INNM_DOSAGE:

      1. Check INNM_DOSAGE

        1. INNM_DOSAGE exists

          1. in case of error - return 404 ('INNM_DOSAGE not_found')

        2. is_active = true

          1. in case of error - return 409 ('INNM_DOSAGE is not active')

    3. Check compliance of INNM_DOSAGE of a BRAND to medicalProgram

      1. if INNM_DOSAGE.mr_blank_type = medicalProgram.mr_blank_type
        (i.e prm.medications.mr_blank_type = prm.medical_programs.mr_blank_type)

        1. in case of error - return 422 ('Dosage form of selected Medication does not comply with mr_blank_type requirement of Medical Program')

 

Response structure

See on Apiary

{ "meta": { "code": 201, "url": "https://example.com/resource", "type": "object", "request_id": "6617aeec-15e2-4d6f-b9bd-53559c358f97#17810" }, "data": { "id": "d290f1ee-6c54-4b01-90e6-d701748f0851", "medication": { "id": "09b2bffb-699a-43c0-bc9a-5066d9b9b5a8", "name": "Амідарон", "manufacturer": { "name": "ПАТ \"Київський вітамінний завод\"", "country": "UA" }, "code_atc": [ "М01АЕ01", "C01BD01" ], "form": "PILL", "container": { "numerator_unit": "PILL", "numerator_value": 1, "denumerator_unit": "PILL", "denumerator_value": 1 }, "package_qty": 30, "package_min_qty": 10, "daily_dosage": "12", "certificate": "UA/4514/01/01", "certificate_expired_at": "2021-02-09", "ingredients": [ { "id": "1349a693-4db1-4a3f-9ac6-8c2f9e541982", "name": "Амідарон", "dosage": { "numerator_unit": "MG", "numerator_value": 200, "denumerator_unit": "PILL", "denumerator_value": 1 }, "is_primary": true } ], "is_active": true, "inserted_at": "2017-04-20T19:14:13Z", "inserted_by": "e1453f4c-1077-4e85-8c98-c13ffca0063e", "updated_at": "2017-04-20T19:14:13Z", "updated_by": "2922a240-63db-404e-b730-09222bfeb2dd", "drlz_sku_id": "0404466792737630283703997321" }, "medical_program": { "id": "c7d52544-0bd4-4129-97b0-2d72633e0490", "name": "Доступні ліки", "medical_program_settings": { "care_plan_required": true, "employee_types_to_create_medication_request": [ "SPECIALIST", "DOCTOR" ], "skip_mnn_in_treatment_period": true, "skip_employee_validation": true, "speciality_types_allowed": [ "ENDOCRINOLOGY", "PEDIATRIC_NEUROLOGY" ], "conditions_icd10_am_allowed": [ "A00.0", "A00.1" ], "conditions_icpc2_allowed": [ "A01", "A02" ], "providing_conditions_allowed": [ "INPATIENT", "OUTPATIENT" ], "medication_request_max_period_day": 90, "skip_medication_request_employee_declaration_verify": true, "skip_medication_request_legal_entity_declaration_verify": true, "multi_medication_dispense_allowed": true, "skip_medication_dispense_sign": true, "medication_request_notification_disabled": true, "skip_contract_provision_verify": true, "medication_dispense_period_day": 90 }, "medical_program_settings_text": "Some text", "is_active": true, "medication_dispense_allowed": true, "medication_dispense_allowed_text": "Some text", "medication_request_allowed": true, "medication_request_allowed_text": "Some text", "type": "MEDICATION", "funding_source": "NHS", "mr_blank_type": "F-1", "inserted_at": "2017-04-20T19:14:13Z", "inserted_by": "e1453f4c-1077-4e85-8c98-c13ffca0063e", "updated_at": "2017-04-20T19:14:13Z", "updated_by": "2922a240-63db-404e-b730-09222bfeb2dd" }, "medication_request_allowed": true, "reimbursement": { "type": "fixed", "reimbursement_amount": 450 }, "wholesale_price": "148.50", "consumer_price": "150.00", "daily_dosage": "200", "reimbursement_daily_dosage": "10.4858", "estimated_payment_amount": "34.50", "is_active": true, "inserted_at": "2017-04-20T19:14:13Z", "inserted_by": "e1453f4c-1077-4e85-8c98-c13ffca0063e", "updated_at": "2017-04-20T19:14:13Z", "updated_by": "2922a240-63db-404e-b730-09222bfeb2dd" } }

 

{ "meta": { "code": "409", "url": "https://example.com/resource", "type": "object", "request_id": "6617aeec-15e2-4d6f-b9bd-53559c358f97#17810" }, "error": { "type": "duplicate", "message": "Current medication is already the participant of this program" } }

 

{ "meta": { "code": "422", "url": "https://example.com/resource", "type": "object", "request_id": "6617aeec-15e2-4d6f-b9bd-53559c358f97#17810" }, "error": { "type": "unverified", "message": "This program is inactive" } }

 

HTTP status codes

HTTP status code

Message

What caused the error

HTTP status code

Message

What caused the error

200

Response

 

201

 

 

401

Invalid access token

 

403

Your scope does not allow to access this resource. Missing allowances: program_medication:read

 

404

Not found

  • medicalProgramId exists in DB check fails.

  • INNM_DOSAGE of a BRAND not_found.

409

  • INNM_DOSAGE of a BRAND is not active.

  • Medication is not active.

  • Medical program is not active.

  • MedicalProgram type should be MEDICATION.

 

422

  • must be earlier than the end date.

  • can't be blank.

  • expected the value to be <= 100.

  • Dosage form of selected Medication does not comply with mr_blank_type requirement of Medical Program.

 

Related content

ЕСОЗ - публічна документація