Versions Compared

Old Version 1

changes.mady.by.user Yuliia Mazur (UA SoE eHealth)

Saved on

compared with

New Version Current

changes.mady.by.user Yuliia Mazur (UA SoE eHealth)

Saved on

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.
Table of Contents

...

Specification

Apiary

...

Purpose

Цей WS призначений для створення контракту від юридичної особи власником або адміністратором. Перед створенням запиту документи повинні бути завантажені. Тоді запит може бути схвалений або відхилений стороною НСЗУ. Після цього, МІС повинен схвалити запит від їх сторони (актуально лише для договору капітації). Якщо запит було схвалено з обох сторін, його можна підписати.

Використовуючи цей сервіс, можна створити договір реімбурсації, а також договір капітації. Різниця між цими двома типами контрактів описана в Моделі даних договору реімбурсації (див відповідний розділ на публічній сторінці Confluence ).

Вхідні параметри

Вхідні дані - це підписані дані у форматі PKCS7. Дані повинні бути розпаковані та перевірені за допомогою схеми (Capitation Contract_request) або схеми JSON (Reimbursement Contract_request) Для того, щоб змінити підписаний контракт, слід надіслати номер_договору. У цьому випадку start_date та end_date взяті з існуючого контракту і не повинні бути присутніми в payload (за винятком випадків пролонгації контракту.

Для цих випадків перевірки описані нижче). Якщо цей запит на контракт змінюється на інший, ідентифікатор попереднього запиту на контракт (Створити запит на контракт # попередній_запит) повинен бути надісланий як payload.

Авторизація

Перевірити валідність доступу токену:

...

This WS is designed to create contract request from Legal Entity side by Owner or Admin. Before the request is created the documents must have been uploaded. Then request can be approved or declined by NHS side. After that, MSP must approve the request from their side. In case the request was two-side approved, it can be two-side signed. 

Using this endpoint a reimbursement contract could be created as well as a capitation contract. The difference between those two types of contract is described here- Reimbursement version Data model

Input parameters

Input is signed data in PKCS7 format. The data must be unpacked and validated using schema (Capitation Contract_request) or JSON schema (Reimbursement Contract_request)

In order to change signed contract contract_number should be send. In this case start_date and end_date are taken from existing contract and should not be present in payload (except in cases of contract prolongation. For these cases, validations are described below).

In case this contract request is changes for another one, the previous contract request id (Create Contract Request#previous_request) should be send in payload. 

Authorization

  1. Verify the validity of access token

    1. in case of error return 401 ('Invalid access token')

  2. Перевірити набір даних Check user scope contract_request:create перед виконанням дії

    в разі помилки 401 у відповіді

    in order to perform this action

    1. in case of error generate 401 response ('Invalid access token')

  3. Якщо BLOCKIf BLOCK_UNVERIFIED_PARTY_USERS є true, тоді перевірити дані співробітника на свіпадіння наступним умовам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):

    1. в разі неспівпадіння - повернути in case not match - return 403 ("Access denied. Party is not verified")

Цифровий підпис

Розшифруйте вміст, зашифрований електронним цифровим підписом. Використовуйте цифровий підпис WS. Метод перевіряє цифровий підпис і повертає результат.

Валідація цифрового підпису (ЦП)

Нам потрібно перевірити ЦП базуючись на формі власності юридичної особи. ЦП може належати фізичній особі-підприємцю або юридичній особі. Як і попередня версія ЦП, він може містити tax_id у полі EDRPOU, а не в DRFO, перевірка повинна виконуватися, як описано нижче:

...

Взяти client_id з token

...

Знайти prm.legal_entities по client_id

...

Digital signature

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

Validate DS

We need to check DS based on legal entity legal form. DS can belong to individual entrepreneur or to legal entity. As previous version of DS can contain tax_id in EDRPOU field, not in DRFO validation must be done as described below:

  1. Get client_id from token

  2. Find prm.legal_entities by client_id

  3. Check EDRPOU or DRFO matches prm.legal_entities.EDRPOU

    1. Перевірити, що  EDRPOU в деталях Certificate не пусто

      Перевірити, що  Certificate

      Check if  EDRPOU in Certificate details exists and not empty

      1. Check if  Certificate_details.EDRPOU=prm.legal_entities.EDRPOU

      в разі, якщо валідація a. не проходить - Перевірити, що DRFO в деталях Certificate не пусто

      Поміняти DRFO та

    2. in case validation from a. didn't pass - Check that DRFO in Certificate details exists and not empty

      1. Convert DRFO and prm.legal_entities.EDRPOU на великі літериПеревірити та поміняти DRFO та EDRPOU to uppercase

      2. Compare DRFO and prm.legal_entities.EDRPOU на Кирилицю

      3. Перевірити та поміняти DRFO та Cyrillic на Кирилицю

      4. Перевірити, що CertificateEDRPOU as Cyrillic letters

      5. Convert DRFO to Cyrillic and compare as Cyrillic letters

      6. Check if  Certificate_details.DRFO=prm.legal_entities.EDRPOU 

  4. в разі, якщо валідація не проходить - згенерувати помилку 422

  5. Перевірити, що SURNAME в деталях Certificate дорівнює LAST_NAME в Party

    Взяти

    In case validation fails - generate 422 error

  6. 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 та NAME and Certificate details.SURNAME на Кирилицю

      3. в разі, якщо валідація не проходить - згенерувати помилку 422

Валідація DRFO

      1. SURNAME as Cyrillic letters

      2. 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 на великі літериПеревірити та поміняти DRFO та to uppercase

    2. Compare DRFO and TAX_ID на Кирилицю

    3. Перевірити та поміняти DRFO на Кирилицю

  3. в разі, якщо валідація не проходить - згенерувати помилку 422

Перевірка ролей

Завантажити з token:

    1. as Cyrillic letters

    2. Convert DRFO to Cyrillic and compare as Cyrillic letters

  2. In case validation fails - generate 422 error

Verify role

Extract from token:

  1. Validate client_id (is_blocked=false)

    1. в разі помилки згенерувати код 403 in case of error return 403 Error ('Client is blocked')

  2. Перевірити контрагента в договорі Check contractor_legal_entity активний чи призупинений

    в разі помилки згенерувати код

    is active or suspended

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

...

Validate request

  1. Валідація Validate contract_type:  

    юридична особа з типом в

    1. legal entities with types in (MSP,PRIMARY_CARE) може створити тілько договір капітації, юридична особа з типом в (PHARMACY) може створити тілько договір реімбурсації

      в разі помилки

      can create only capitation contracts, legal entities with types in (PHARMACY) can create only reimbursement contracts

      1. in case of error 409 - "Contract type "{contract_type}" is not allowed for legal_entity with type "{legal_entity_type}" "

  2. Валідація Validate previous_request_id 

    1. вибрати select id from contract_request де where id=$.previous_request_id

      1. якщо дані не знайдено згенерувати помилку in case no data found return 422 ("previous_request does not exist")

    2. Перевірити previousCheck previous_request status не рівно not in ('SIGNED')

      1. в разі помилки згенерувати код in case error return 422 ('In case contract exists new contract request should be created')

    3. Перевір contractorCheck that contractor_legal_entity_id попереднього запиту рівний до contractorof previous request is equal to contractor_legal_entity_id поточного запиту

      в разі помилки згенерувати код

      of current request

      1. in case of error return 422 ('Previous request doesn't belong to legal entity')

    4. Для договоду реімбурсації: Перевірити що id_form з $For reimbursement contracts: Check that id_form from $.previous_request_id рівний до id_form для запиту

      в разі помилки згенерувати код

      equal to id_form from request

      1. in case of error return 422 ('Id_form from previous request is not equal to id_form from request')

  3. Валідація Validate contractor_divisions

    1. для договору капітації:

      Превірити, що підрозділ належить до

      in case capitation contracts:

      1. Check divisions belongs to legal_entity та and divisions.status='active'

        1. в разі помилки згенерувати код 422  переглянути in case of error return 422  error view $divisions ('Division must be active and within current legal_entity')

      2. Перевірити, що підрозділ в масиві зустрічається тільки один раз

        в разі помилки згенерувати код 422  переглянути

        Validate each division in array present exactly one time

        1. in case of error return 422  error view $divisions ('Division duplicates')

    2. для договору реімбурсації повернути помилку 422 in case reimbursement contracts return 422 error ('schema does not allow additional properties')

  4. Валідація Validate start_date

    1. перевірити формат validate that start_date in a date format (^(\\d{4}(?!\\d{2}\\b))((-?)((0[1-9]|1[0-2])(\\3([12]\\d|0[1-9]|3[01]))?|W([0-4]\\d|5[0-2])(-?[1-7])?|(00[1-9]|0[1-9]\\d|[12]\\d{2}|3([0-5]\\d|6[1-6])))?)?$)

      1. в разі помилки згенерувати код in case of error return 422 error $start_date ('"expected \"<start_date>" to be a valid ISO 8601 date"')

    2. рік в the year in start_date повинен співпадати з поточним або наступним роком must be equal to current or next year (current+1).

      1. в разі помилки згенерувати код in case of error return 422 error $start_date ('Start date must be within this or next year')

  5. Валідація Validate end_date  (Примітка. Дані валідації дійсні для випадків, коли contract_number не проходить перевірки в запиті. Якщо contract_number перевірено, проводяться валідації з 10.п)

    перевірити формат end_date

    Note. These validations are applied for cases when the contract_number isn't passed in the request. If the contract_number is passed, validations from 10.g are applied)

    1. validate that end_date in a date format (^(\\d{4}(?!\\d{2}\\b))((-?)((0[1-9]|1[0-2])(\\3([12]\\d|0[1-9]|3[01]))?|W([0-4]\\d|5[0-2])(-?[1-7])?|(00[1-9]|0[1-9]\\d|[12]\\d{2}|3([0-5]\\d|6[1-6])))?)?$)

      1. в разі помилки згенерувати код in case of error return 422 error $end_date date ('"expected \"<end_date>" to be a valid ISO 8601 date"')

    2. рік повинен the year in $end_date може бути наступним роком після can be next year after 'start_date' якщо повний період договору не перевищує 1 року.

      $end_date повинна бути більше або рівнятися $start_date

      в разі помилки згенерувати код

      ' if the total period of the contract doesn't exceed 1 year.

    3. the $end_date must be greater or equal than the $start_date

      1. in case of error return 422 ('The end_date should be greater or equal than the start_date')

    4. різниця між the different between $end_date та and $start_date повинна бути не більше ніж 1 рік (365 або 366 днів)

      в разі помилки згенерувати код

      should be no more than one year old (365 or 366 days)

      1. in case of error return 422 ('The difference between end_date and start_date is more than one year')

  6. Валідація Validate contractor_owner_id

    1. Перевірити Check employees.employee_id=contractor_owner_id та and client_id=employee.legal_entity_id та and employee_type в in('OWNER', 'ADMIN') та and status='APPROVED' та and is_active=true

      1. в разі помилки згенерувати код In case of error return 422 Error ('Contractor owner must be an active OWNER or ADMIN and within current legal entity in contract request')

  7. Якщо в напиті було надіслано If in request was sent contract_number:

    1. перевірити структуру номеру договору check 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. перевірити, що договір з даним contractcheck there is a contract with such contract_number 

      1. в разі помилки згенерувати код 422 in case of error return 422 error ('Contract with such contract number does not exist')

    3. перевірити, що договір не в статусі check if contract is not in status 'TERMINATED'

      1. в разі помилки згенерувати код 409 in case of error return 409 error ('Can not update terminated contract')

    4. employee_divisions, start_date, end_date не можуть бути оновлені. Якщо є активний договіп з таким date can't be updated. If there is an active contract with such contract_number зкопіювати copy start_date, end_date та and contractor_legal_entity_id з уже діючого договору. Це не можливо зробити через запит.

      1. в разі помилки згенерувати код 422

      перевірити підтверджений contract_type такий же, що і в діючому договорі з номером from existing contract. It's not allowed in response.

      1. in case of error return 422 error

    5. check submitted contract_type is the same as in existing contract with number =contract_number

      1. в разі помилки згенерувати код in case of error 409 ('Submitted contract_type does not correspond to previously created content`)

    6. для запитів для договорів капітації та реімбурсаціїfor capitation and reimbursement contract requests:

      1. якщо if $contract_number та and $end_date проходять перевірки в запитіis passed in request:

        1. the $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. $endthe $end_date повинна бути меньше $end_date попереднього договору та меньше або дорівнювати даті плюс 3 місяці

          в разі помилки згенерувати код

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

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

      2. якщо if $contract_number w/o $end_date проходять перевірки в запитіis passed in request:

        1. $end_date береться з попереднього договору.

      для договору реімбурсації:

      1. перевірити id_form такий же

        1. в разі помилки повернути is taken from the previous contract.

    7. in case it is reimbursement contract:

      1. check id_form is the same

        1. in case of error 409 ('Submitted id_form does not correspond to previously created content`)

      2. якщо if medical_programs відповідає - перевірити згідно опису в п.13 нижче

    Валідація 

      1. passed - validate them as described at p.13 below

  8. Validate contractor_payment_details:

    1. якщо if payer_account не дорівнює ^UAnot like ^UA[0-9]{22}$ або ^UA$ or ^UA[0-9]{27}$ -> MFO повинен запитуваись

    Валідація 

    1. must be required

  9. Validate id_from з довідника CONTRACT_TYPE (для договору капітації) та REIMBURSEMENT_ is from dictionary CONTRACT_TYPE (для договору реімбурсації) :

    1. в разі помилки згенерувати код 422 in case of error return 422 error ('value is not allowed in enum')

  10. Валідація - відсутні інші активні  Validate there is no other active (VERIFIED) договори, створені даним  contract created by this legal_entity_id за даний in this period (contract_request.start_date <= contract.end_date and contract_request.end_date => contract.start_date) тим самим  by same contract_type та id_form (для договору реімбурсації)

    в разі помилки згенерувати код 422

    and medical_program_id id_form (in case of reimbursement contract)

    1. in case of error return 422 error ('Active contract is found. Contract number must be sent in request')

  11. Для договору капітації: Валідація For capitation contract: Validate external_contractors

    1. Перевірити externalCheck external_contractors.divisions.id наявна для contractoris present in contractor_divisions.id

      1. в разі помилки згенерувати код 422 in case of error return 422 error $divisions ('The division is not belong to contractor_divisions')

    2. Перевірити externalCheck external_contractors.contract.expires_at>start_date

      1. в разі помилки згенерувати код 422 in case of error return 422 error $contract.expires_at ('Expires date must be greater than contract start_date')

    3. Встановити externalSet external_contractors.legal_entity_id='client_id'

    4. division_id з from the external_contractors блоку повинна бути належна до юридичної особи яка включається до договору капітації. В block must be a part of the legal entity that enters into the capitation contract. In the external_contractors.legal_entity_id необхідно вказати юридичну особу must be specify the legal entity that is the counter-party для даного of this division_id.

  12. Для договору капітації: Валідація For capitation contract: Validate external_contractor_flag:

    1. якщо If external_contractors не is not null тоді externalthen external_contractor_flag повинен бути must be trueякщо

    2. If external_contractors не is null тоді externalthen external_contractor_flag повинен бути false 

      в разі помилки згенерувати код 422

      must be set to false 

      1. in case of error return 422 error $external_contractor_flag ('Invalid external_contractor_flag')

    3. якщо external_contractors не був відправлений в запиті тоді встановити externalIf external_contractors wasn't sent in request then set external_contractor_flag до to false.

  13. Для договору реімбурсації: Валідація For reimbursement contracts: Validate medical_programs:

    1. Перевірити, що всі Validate that all medical_programs з with submitted ids існують

      в разі помилки згенерувати код 422 переглянути

      exists

      1. in case of error return 422 error view $medical_programs[...] ('Reimbursement program with such id does not exist')

    2. Перевірити, що Validate that medical_programs з підтвердженим id це активна програма

      в разі помилки згенерувати код 422 переглянути

      with submitted id is an active program

      1. in case of error return 422 error view $medical_programs[...] ('Reimbursement program is not active')

    3. Перевірити, що всі медичні програми з вказаним Validate that all medical program and with MEDICATION type:

      1. в разі помилки згенерувати код 422 переглянути in case of error return 422 error view $medical_programs[...] (‘Program with such id is not a reimbursement program')

    4. Перевірити, що Check that medical_programs з підтвердженим id відповідає до with submitted id correspond to id_form згідно наведеного перелікуis in the allowed list:

      id_formmedical_programs
      PMD_1REIMBURSEMENT_CONTRACT_REQUEST_MEDICAL_PROGRAM_IDS_DOSTUPNI_LIKY
      INSULIN_1REIMBURSEMENT_CONTRACT_REQUEST_MEDICAL_PROGRAM_IDS_INSULIN
      ND_1REIMBURSEMENT_CONTRACT_REQUEST_MEDICAL_PROGRAM_IDS_NETSUKROVYY_DIABET

...

      1. in case of error return 422 error view $medical_programs[...] ('Medical program is not allowed for this action')

...

      1. Note.

...

      1. For id_form=INSULIN_

...

      1. 1 two medical programs must be present.

        1. in case of error return 409 error view $medical_programs ('The composition of medical programs does not correspond to the allowed composition')

Перевірити список медичних програм в масиві на відсутність дублів id:

    1. Validate that list of medical programs in array doesn't contain duplicates ids:

      1. in case of error return 409 error view $medical_programs (‘The list of medical programs contains duplicates')

Визначити первісний договір (опціонально)

...

Determine parent contract (optional)

In case contract request contains parameter '$.contract_number':

  1. знайти договір, що відповідає find contract that matches transmitted '$contract_number', передається:

    якщо відстній договір з зазначеним номером договору, згенерувати помилку 422

    :

    1. if there is no contract with specified contract number, return 422 error ('Contract with such contract number does not exist')

    2. якщо договір в статусі if contract is in 'Terminated' status, згенерувати код return 409 error ('Can not update terminated contract')

  2. встановити set parent_contract_id значення як value as contract.id

Пошук запитів, що очікують на розгляд

  1. Перевірити, що є в наявності  

...

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

В разі, якщо такий запит відсутній - змінити цей статус на In case there is such contract request change its status to 'TERMINATE'

Зберегти запит на договір

...

Save contract request

Insert record to IL.contract_request в статусі in status 'NEW'

встановити set  - contractor_legal_entity_id=$client_id

Зберегти підписаний договір до сховища

Отримати url для завантаженого договору.

...

Параметр

...

Джерело

...

timestamp

...

:TIMESTAMP

...

resource_name

...

Save signed contract request to media storage

...

bucket

...

  1. Get url for contract request upload.

    Parameter
    Source
    action'GET'
    bucket'CONTRACT_REQUEST'
    resource_id:CONTRACT_REQUEST_ID

...

action

...

'GET'

  1. resource_name:INITIAL_CONTRACT_REQUEST

...

  1. Завантажити підписаний договір до сховища.
    timestamp:TIMESTAMP

  2. Upload signed contract request to media storage