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

Skip to end of metadata
Go to start of metadata

You are viewing an old version of this page. View the current version.

Compare with Current View Page History

« Previous Version 5 Next »

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

Properties of a REST API method document

Document type

Метод REST API

Document title

[Document status] REST API [Назва методу] [ID методу]

Guideline ID

GUI-0011

Author

@

Document version

1

Document status

DRAFT

Date of creation

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

Date of update

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

Method API ID

API-005-002-002-0043

Microservices (namespace)

IL

Component

Contracts

Component ID

COM-005-002

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

https://uaehealthapi.docs.apiary.io/#reference/public.-contracts/contract-request/private.-create-contract-request-by-nhs

Resource

{{host}}/api/contract_requests/{{contract_type}}/{{id}}

Scope

contract_request:create

Protocol type

REST

Request type

POST

Sync/Async

Sync

Public/Private

Private

Purpose

This WS is designed to update contract by NHS by creating new contract request.

Logic

This WS is designed to update contract by NHS by creating new contract request. Contract request is created with contract number, and parent contract is added to request. NHS Admin can change only fields that are on nhs side.

Request has a similar structure as in Public. Create Contract Request. For Create contract request by NHS, the contract_number in the request is required, it is used to change the existing contract by the NHS.

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

1

contract_type

CAPITATION

REIMBURSEMENT

String

Required

 

2

id

 

String

Contract_request ID. Required

09106b70-18b0-4726-b0ed-6bda1369fd52

Request structure

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

Description of the REST API request structure, example

 Example
{
  "signed_content": "ew0KICAiY29udHJhY3Rvcl9vd25lcl9pZCI6ICJkZjlmNzBlZS00YjEyLTQ3NDAtYjBmNS1iYjVhZWExMTY4NjMiLA0KICAiY29udHJhY3Rvcl9iYXNlIjogItC90LAg0L/RltC00YHRgtCw0LLRliDQt9Cw0LrQvtC90YMg0L/RgNC+INCc0LXQtNC40YfQvdC1INC+0LHRgdC70YPQs9C+0LLRg9Cy0LDQvdC90Y8g0L3QsNGB0LXQu9C10L3QvdGPIiwNCiAgImNvbnRyYWN0b3JfcGF5bWVudF9kZXRhaWxzIjogew0KICAgICJiYW5rX25hbWUiOiAi0JHQsNC90Log0L3QvtC80LXRgCAxIiwNCiAgICAiTUZPIjogIjM1MTAwNSIsDQogICAgInBheWVyX2FjY291bnQiOiAiMzIwMDkxMDI3MDEwMjYiDQogIH0sDQogICJjb250cmFjdG9yX3Jtc3BfYW1vdW50IjogNTAwMDAsDQogICJjb250cmFjdG9yX2RpdmlzaW9ucyI6IFsNCiAgICAiaWQ6IGAyOTIyYTI0MC02M2RiLTQwNGUtYjczMC0wOTIyMmJmZWIyZGRgIg0KICBdLA0KICAiY29udHJhY3Rvcl9lbXBsb3llZV9kaXZpc2lvbnMiOiBbDQogICAgew0KICAgICAgImVtcGxveWVlX2lkIjogIjI5MjJhMjQwLTYzZGItNDA0ZS1iNzMwLTA5MjIyYmZlYjJkZCIsDQogICAgICAic3RhZmZfdW5pdHMiOiAwLjUsDQogICAgICAiZGVjbGFyYXRpb25fbGltaXQiOiAyMDAwLA0KICAgICAgImRpdmlzaW9uX2lkIjogIjI5MjJhMjQwLTYzZGItNDA0ZS1iNzMwLTA5MjIyYmZlYjJkZCINCiAgICB9DQogIF0sDQogICJleHRlcm5hbF9jb250cmFjdG9yX2ZsYWciOiB0cnVlLA0KICAiZXh0ZXJuYWxfY29udHJhY3RvcnMiOiB7DQogICAgImxlZ2FsX2VudGl0eV9pZCI6ICIyOTIyYTI0MC02M2RiLTQwNGUtYjczMC0wOTIyMmJmZWIyZGQiLA0KICAgICJjb250cmFjdCI6IHsNCiAgICAgICJudW1iZXIiOiAiMTIzNDU2NyIsDQogICAgICAiaXNzdWVkX2F0IjogIjIwMTgtMDEtMDEiLA0KICAgICAgImV4cGlyZXNfYXQiOiAiMjAxOS0wMS0wMSINCiAgICB9LA0KICAgICJkaXZpc2lvbnMiOiBbDQogICAgICB7DQogICAgICAgICJpZCI6ICIyOTIyYTI0MC02M2RiLTQwNGUtYjczMC0wOTIyMmJmZWIyZGQiLA0KICAgICAgICAibWVkaWNhbF9zZXJ2aWNlIjogItCf0L7RgdC70YPQs9CwINCf0JzQlCINCiAgICAgIH0NCiAgICBdDQogIH0sDQogICJzdGFydF9kYXRlIjogIjIwMTctMDQtMjAiLA0KICAiZW5kX2RhdGUiOiAiMjAxNy0wNC0yMCIsDQogICJpZF9mb3JtIjogIjUiLA0KICAiY29udHJhY3RfbnVtYmVyIjogIjAwMDAtOUVBWC1YVDdYLTMxMTUiLA0KICAic3RhdHV0ZSI6ImJhc2U2NF9kb2N1bWVudCINCiAgImVxdWlwbWVudF9hZ3JlZW1lbnQiOiJiYXNlNjRfZG9jdW1lbnQiDQp9",
  "signed_content_encoding": "base64"
}

Headers

Key

Value

Mandatory

Description

Example

1

Content-Type

application/json

M

Тип контенту

Content-Type:application/json

2

Authorization

Bearer c2778f3064753ea70de870a53795f5c9

M

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

Authorization:Bearer c2778f3064753ea70de870a53795f5c9

3

Request data validation

Verify role

Extract from token:

  1. Validate client_id (is_blocked=false)

    1. in case of error return 403 Error ('Client is blocked')

  2. Check legal_entity is active

    • in case error return 403 - ('Client is not active')

  3. Check legal_entity.type = 'NHS'

    1. in case error return 403 forbidden

Digital signature

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

Validate EDRPOU

  1. Check that EDRPOU in Certificate details exists and not empty

    1. in case of error return 422 error ('Invalid EDRPOU in DS')

  2. Check that EDRPOU in Certificate details is equal to EDPOU in legal entity

    1. Get client_id from token.

    2. Find prm.legal_entities id by client_id

    3. Compare EDRPOU in Certificate with legal_entities.edrpou

    4. In case validation fails - generate 422 error

  3. Check that SURNAME in Certificate details is equal to LAST_NAME in Party

    1. Get user_id → user_parties.party_id → parties.last_name and compare to surname from DS

      1. Convert prm.parties.LAST_NAME and Certificate details.SURNAME to uppercase

      2. Compare prm.parties.LAST_NAME and Certificate details.SURNAME as Cyrillic letters

      3. In case validation fails - generate 422 error

Validate DRFO

  1. Get parties.tax_id using party_users.party_id by user_id.

  2. Compare DRFO in Certificate with party.tax_id

    1. Convert DRFO and TAX_ID to uppercase

    2. Compare DRFO and TAX_ID as Cyrillic letters

    3. Convert DRFO to Cyrillic and compare as Cyrillic letters

  3. In case validation fails - generate 422 error

Validations

  1. contract request number structure XXXX-1234-5678-C , where:

    1. XXXX - series: numbers + only some letters (A, E, H, K, M, P, T, X)

    2. 1234-5678 - randomly generated numbers and letters A, E, H, K, M, P, T, X. 

  2. contract_number is in request

    1. in case error return 409, "Contract number should be in payload"

  3. check there is a contract with such contract_number 

    1. in case of error return 422 error ('Contract with such contract number does not exist')

  4. contrat status = VARIFIED

    1. in case of error return 409 error ('Can not update terminated contract')

  5. Contract.is_suspended = false

    1. in case error 409, "suspended contract should be updated by contractor_owner"

  6. Check only next fields are different from contract

    1. nhs_signer_id

    2. nhs_signer_base

    3. nhs_contract_price (for capitation contracts only)

    4. nhs_payment_method

    5. issue_city

    6. Misc

    7. assignee_id

      1. in case error return 422, "Not allowed to change field $.field"

  7. Validate end_date:

    1. if $contract_number and $end_date is passed in request:

      1. the year of $end_date must be greater or equal then the $start_date

        1. in case of error return 422 ('The year of end_date should be one year greater or equal to start_date')

      2. the $end_date should be equal or greater than today and less than or equal to three month from $end_date the previous contract

        1. in case of error return 422 ('The end_date may be equal or greater than today and less than or equal to three month from end_date the previous contract')

    2. if $contract_number w/o $end_date is passed in request:

      1. $end_date is taken from the previous contract

Processing

Search pending contract requests

  1. Find there is no contract request 

  • for same contractor_legal_entity_id

  • within same period [start_date, end_date]

  • status in ('NEW', 'IN_PROCESS','APPROVED', 'NHS_SIGNED', 'PENGIND_NHS_SIGN')

  • id_form

  • type

  • medical_program_id (for reimbursement contracts)

In case there is such contract request change its' status to 'TERMINATE'

Save contract request

  1. status=APPROVED

  2. parent_contract_id=contract_id

  3. update fields from request, other fields should be taken from contract.

Mapping for request

contract request

old contract

edited fields by nhs

other

contractor_legal_entity_id

contractor_legal_entity_id

 

 

contractor_owner_id

contractor_owner_id

 

 

contractor_base

contractor_base

 

 

contractor_payment_details

contractor_payment_details

 

 

contractor_rmsp_amount

contractor_rmsp_amount

 

 

start_date

start_date

 

 

end_date

end_date

 

 

nhs_legal_entity_id

 

 

token.client_id

nhs_signer_id

 

nhs_signer_id

 

nhs_signer_base

 

nhs_signer_base

 

contractor_signed

 

 

false

issue_city

 

issue_city

 

status

 

 

APPROVED

status_reason

 

 

null

nhs_contract_price

 

nhs_contract_price

 

nhs_payment_method

 

nhs_payment_method

 

contract_number

contract_number

 

 

id_form

id_form

 

 

contractor_divisions

 

 

SELECT id 
from contract_divisions 
where contract_id=parent_contract_id;

misc

 

misc

 

assignee_id

 

assignee_id

 

type

type

 

 

medical_program_id

medical_program_id

 

 

Save signed contract request to media storage

  1. Get url for contract request upload.

     

    Parameter

    Source

    action

    'GET'

    bucket

    'CONTRACT_REQUEST'

    resource_id

    : CONTRACT_REQUEST_ID

    resource_name

    : CONTRACT_REQUEST_APPROVED

    timestamp

    :TIMESTAMP

     

  2. Upload signed contract request to media storage

Event manager

After contract request was created by NHS as change to existed contract this change should be shown in event manager

 

field

value

example

field

value

example

event_type

ContractRequestCreateEvent

 

entity_type

{$.contract.type}ContractRequest

CapitationContractRequest/ReimbursementContractRequest

entity_id

$.id

 

properties.contract.old_value

$.parent_id

 

event_time

$.update_at

 

changed_by

$.user_id

 

inserted_at

now()

 

updated_at

now()

 

Response structure examples

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

Description of the REST API response structure, example

Example:

 Response example for CAPITATION
{
  "meta": {
    "code": 200,
    "url": "https://example.com/resource",
    "type": "object",
    "request_id": "6617aeec-15e2-4d6f-b9bd-53559c358f97#17810"
  },
  "data": {
    "id": "09106b70-18b0-4726-b0ed-6bda1369fd52",
    "contract_type": "CAPITATION",
    "contractor_legal_entity": {
      "id": "df9f70ee-4b12-4740-b0f5-bb5aea116863",
      "name": "Клініка Ноунейм",
      "edrpou": "32323454",
      "addresses": [
        {
          "type": "RESIDENCE",
          "country": "UA",
          "area": "Житомирська",
          "region": "Бердичівський",
          "settlement": "Київ",
          "settlement_type": "CITY",
          "settlement_id": "b075f148",
          "street_type": "STREET",
          "street": "вул. Ніжинська",
          "building": "15",
          "apartment": "23",
          "zip": "02090"
        }
      ]
    },
    "contractor_owner": {
      "id": "b075f148-7f93-4fc2-b2ec-2d81b19a9b7b",
      "party": {
        "first_name": "Петро",
        "last_name": "Іванов",
        "second_name": "Миколайович"
      }
    },
    "contractor_base": "на підставі закону про Медичне обслуговування населення",
    "contractor_payment_details": {
      "bank_name": "Банк номер 1",
      "MFO": "351005",
      "payer_account": "32009102701026"
    },
    "contractor_rmsp_amount": 50000,
    "contractor_divisions": [
      {
        "id": "2922a240-63db-404e-b730-09222bfeb2dd",
        "name": "Бориспільське відділення Клініки Ноунейм",
        "addresses": [
          {
            "type": "RESIDENCE",
            "country": "UA",
            "area": "Житомирська",
            "region": "Бердичівський",
            "settlement": "Київ",
            "settlement_type": "CITY",
            "settlement_id": "b075f148",
            "street_type": "STREET",
            "street": "вул. Ніжинська",
            "building": "15",
            "apartment": "23",
            "zip": "02090"
          }
        ],
        "phones": [
          {
            "type": "MOBILE",
            "number": "+380503410870"
          }
        ],
        "email": "email@example.com",
        "working_hours": {
          "mon": [
            [
              "08.00",
              "12.00"
            ],
            [
              "14.00",
              "18.00"
            ]
          ],
          "tue": [
            [
              "08.00",
              "12.00"
            ]
          ],
          "wed": [
            [
              "08.00",
              "12.00"
            ]
          ],
          "thu": [
            [
              "08.00",
              "12.00"
            ]
          ],
          "fri": [
            [
              "08.00",
              "12.00"
            ]
          ]
        },
        "mountain_group": false
      }
    ],
    "contractor_employee_divisions": [
      {
        "employee": {
          "id": "b075f148-7f93-4fc2-b2ec-2d81b19a9b7b",
          "party": {
            "first_name": "Петро",
            "last_name": "Іванов",
            "second_name": "Миколайович"
          },
          "speciality": {
            "speciality": "THERAPIST",
            "speciality_officio": true,
            "level": "FIRST",
            "qualification_type": "AWARDING",
            "attestation_name": "Академія Богомольця",
            "attestation_date": "2017-02-28",
            "valid_to_date": "2020-02-28",
            "certificate_number": "AB/21331"
          }
        },
        "staff_units": 0.5,
        "declaration_limit": 2000,
        "division_id": "2922a240-63db-404e-b730-09222bfeb2dd"
      }
    ],
    "external_contractor_flag": true,
    "external_contractors": [
      {
        "legal_entity": {
          "id": "b075f148-7f93-4fc2-b2ec-2d81b19a9b7b",
          "name": "Клініка Ноунейм"
        },
        "contract": {
          "number": "1234567",
          "issued_at": "2018-01-01",
          "expires_at": "2019-01-01"
        },
        "divisions": [
          {
            "id": "2922a240-63db-404e-b730-09222bfeb2dd",
            "name": "Бориспільське відділення Клініки Ноунейм",
            "medical_service": "Послуга ПМД"
          }
        ]
      }
    ],
    "id_form": "PMD_1",
    "nhs_signer": {
      "id": "b075f148-7f93-4fc2-b2ec-2d81b19a9b7b",
      "party": {
        "first_name": "Петро",
        "last_name": "Іванов",
        "second_name": "Миколайович"
      }
    },
    "nhs_legal_entity": {
      "id": "df9f70ee-4b12-4740-b0f5-bb5aea116863",
      "name": "Клініка Ноунейм",
      "edrpou": "32323454",
      "addresses": [
        {
          "type": "RESIDENCE",
          "country": "UA",
          "area": "Житомирська",
          "region": "Бердичівський",
          "settlement": "Київ",
          "settlement_type": "CITY",
          "settlement_id": "b075f148",
          "street_type": "STREET",
          "street": "вул. Ніжинська",
          "building": "15",
          "apartment": "23",
          "zip": "02090"
        }
      ]
    },
    "nhs_signer_base": "на підставі наказу",
    "nhs_contract_price": 50000,
    "nhs_payment_method": "BACKWARD",
    "status": "APPROVED",
    "status_reason": "Не відповідає попереднім домовленостям",
    "issue_city": "Київ",
    "contract_number": "0000-9EAX-XT7X-3115",
    "contract_id": "df9f70ee-4b12-4740-b0f5-bb5aea116863",
    "parent_contract_id": "22e416c4-5747-41cd-9f73-c3a85cdee885",
    "start_date": "2017-04-20",
    "end_date": "2017-04-20",
    "printout_content": "Contract request content",
    "previous_request_id": "df9f70ee-4b12-4740-b0f5-bb5aea116863",
    "assignee_id": "22e416c4-5747-41cd-9f73-c3a85cdee885",
    "updated_at": "2017-04-20T19:14:13Z",
    "inserted_at": "2017-04-20T19:14:13Z"
  }
}

 

 Response example for REIMBURSEMENT
{
  "meta": {
    "code": 200,
    "url": "https://example.com/resource",
    "type": "object",
    "request_id": "6617aeec-15e2-4d6f-b9bd-53559c358f97#17810"
  },
  "data": {
    "id": "09106b70-18b0-4726-b0ed-6bda1369fd52",
    "contract_type": "REIMBURSEMENT",
    "contractor_legal_entity": {
      "id": "df9f70ee-4b12-4740-b0f5-bb5aea116863",
      "name": "Клініка Ноунейм",
      "edrpou": "32323454",
      "addresses": [
        {
          "type": "RESIDENCE",
          "country": "UA",
          "area": "Житомирська",
          "region": "Бердичівський",
          "settlement": "Київ",
          "settlement_type": "CITY",
          "settlement_id": "b075f148",
          "street_type": "STREET",
          "street": "вул. Ніжинська",
          "building": "15",
          "apartment": "23",
          "zip": "02090"
        }
      ]
    },
    "contractor_owner": {
      "id": "b075f148-7f93-4fc2-b2ec-2d81b19a9b7b",
      "party": {
        "first_name": "Петро",
        "last_name": "Іванов",
        "second_name": "Миколайович"
      }
    },
    "contractor_base": "на підставі закону про Медичне обслуговування населення",
    "contractor_payment_details": {
      "bank_name": "Банк номер 1",
      "MFO": "351005",
      "payer_account": "32009102701026"
    },
    "id_form": "RMB-1",
    "nhs_signer": {
      "id": "b075f148-7f93-4fc2-b2ec-2d81b19a9b7b",
      "party": {
        "first_name": "Петро",
        "last_name": "Іванов",
        "second_name": "Миколайович"
      }
    },
    "nhs_legal_entity": {
      "id": "df9f70ee-4b12-4740-b0f5-bb5aea116863",
      "name": "Клініка Ноунейм",
      "edrpou": "32323454",
      "addresses": [
        {
          "type": "RESIDENCE",
          "country": "UA",
          "area": "Житомирська",
          "region": "Бердичівський",
          "settlement": "Київ",
          "settlement_type": "CITY",
          "settlement_id": "b075f148",
          "street_type": "STREET",
          "street": "вул. Ніжинська",
          "building": "15",
          "apartment": "23",
          "zip": "02090"
        }
      ]
    },
    "nhs_signer_base": "на підставі наказу",
    "nhs_contract_price": 50000,
    "nhs_payment_method": "BACKWARD",
    "status": "APPROVED",
    "status_reason": null,
    "issue_city": "Київ",
    "contract_number": "0000-9EAX-XT7X-3115",
    "contract_id": "df9f70ee-4b12-4740-b0f5-bb5aea116863",
    "parent_contract_id": "22e416c4-5747-41cd-9f73-c3a85cdee885",
    "start_date": "2017-04-20",
    "end_date": "2017-04-20",
    "printout_content": "Contract request content",
    "previous_request_id": "df9f70ee-4b12-4740-b0f5-bb5aea116863",
    "assignee_id": "22e416c4-5747-41cd-9f73-c3a85cdee885",
    "medical_programs": [
      "3914a240-63db-404e-b730-09222bfeb2d0"
    ],
    "updated_at": "2017-04-20T19:14:13Z",
    "inserted_at": "2017-04-20T19:14:13Z"
  }
}

HTTP status codes

Response code

HTTP Status code

Message

Internal name

Description

1

Базові

2

201

  Response

 

3

 401

  • Access denied

  • Invalid scopes

 

4

401

Unauthorized

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

5

403

  1. Client is blocked

  2. Client is not active

  3. Error

  4. forbidden

  1. Check legal_entity.type = 'NHS' failed

6

1000

404

Composition not found

COMPOSITION_NOT_FOUND_404

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

7

409

 

Validation failed

8

422

 

Validation failed

9

422

Invalid EDRPOU in DS

10

422

Not allowed to change field $.field

11

422

The year of end_date should be one year greater or equal to start_date

12

422

The end_date may be equal or greater than today and less than or equal to three month from end_date the previous contract

13

Специфічні

14

422

Only for active MPI record can be created medication request!

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

Generating page properties report...

  • No labels

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