Specification

Apiary

Purpose

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- Contract: Reimbursment version Data model

Input parameters

Input is signed data in PKCS7 format. The data must be unpacked and validated using JSON schema (capitation contract) or JSON schema (reimbursement contract)

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.

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

Authorize

1. 1. Verify the validity of access token
      1. in case of error return 401 ('Access denied')
   2. Check user scope contract_request:create in order to perform this action
      1. in case of error generate 401 response ('Invalid scopes')

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 prn.legal_entities by client_id
3. Check EDRPOU or DRFO matches prn.legal_entities.EDRPOU
   1. Check if  EDRPOU in Certificate details exists and not empty
      1. Check if  Certificate_details.EDRPOU=prn.legal_entities.EDRPOU
   2. in case validation from a. didn't pass - Check that DRFO in Certificate details exists and not empty
      1. Convert DRFO and prn.legal_entities.EDRPOU to uppercase
      2. Compare DRFO and prn.legal_entities.EDRPOU as Cyrillic letters
      3. Convert DRFO to Cyrillic and compare as Cyrillic letters
      4. Check if  Certificate_details.DRFO=prn.legal_entities.EDRPOU 
4. In case validation fails - generate 422 error
5. 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

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 contractor_legal_entity is active or suspended
   • in case error return 403 - ('Client is not active')

Validate request

1. Validate contract_type: legal entities with types in capitation_contract_le_types can create only capitation contracts when reimbursement_contract_le_types 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. Check previous_request status not in ('SIGNED')
      1. in case error return 422 ('In case contract exists new contract request should be created')
   3. Check that contractor_legal_entity_id of 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')
3. Validate contractor_divisions
   1. Check divisions belongs to legal_entity and divisions.status='active'
      1. in case of error return 422  error view $divisions ('Division must be active and within current legal_entity')
   2. Validate each division in array present exactly one time
      1. in case of error return 422  error view $divisions ('Division duplicates')
4. For capitation contract: Validate contractor_employee_divisions 
   1. Employees from employee_divisions has employee_type='DOCTOR', status='APPROVED'
      1. in case of error return 422  error view $employee ('Employee must be an active DOCTOR')
   2. Check contractor_employee_divisions.division_id is present in contractor_divisions.id
      1. in case of error return 422 error $divisions ('The division is not belong to contractor_divisions')
   3. Check employee present in divisions for one time: count(employee_id)=1 by contractor_employee_divisions.division_id 
      1. in case of error return 422 error $divisions ('Employee in division duplicates)
5. For capitation contract: Validate external_contractors
   1. Check external_contractors.divisions.id is present in contractor_divisions.id
      1. in case of error return 422 error $divisions ('The division is not belong to contractor_divisions')
   2. Check external_contractors.contract.expires_at>start_date
      1. in case of error return 422 error $contract.expires_at ('Expires date must be greater than contract start_date')
   3. Set 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 counterparty of this division_id.
6. For capitation contract: Validate external_contractor_flag:
   1. If external_contractors is not null then external_contractor_flag must be true
   2. If external_contractors is null then external_contractor_flag must be set to false 
      1. in case of error return 422 error $external_contractor_flag ('Invalid external_contractor_flag').

      If external_contractors wasn't sent in request then set external_contractor_flag to false.

7. Validate start_date
   1. 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')
8. Validate end_date
   1. the year in $end_date must be equal to year in $start_date
      1. in case of error return 422 error $end_date ('The year of start date and end date must be equal')
   2. the $end_date must be greater than the $start_date
      1. in case of error return 422 ('The end date must be greater than the start date')
9. Valide 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
   2. In case of error return 422 Error ('Contractor owner must be an active OWNER or ADMIN and within current legal entity in contract request')
10. If in request was sent contract_number check format contract_number:
    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. 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')
    3. check if contract is not in status 'TERMINATED'
       1. in case of error return 409 error ('Can not update terminated contract')
    4. employee_divisions, start_date, end_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 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. in case it is reimbursement contract, check medical_program_id is the same
       1. in case of error 409 ('Submitted medical_program_id does not correspond to previously created content`)
11. Validate id_from is from dictionary CONTRACT_TYPE
    1. in case of error return 422 error ('Invalid contract type')
12.  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 and program_id( in case of reimbursement contract)
    1. in case of error return 422 error ('There is an active contract. Contract number must be sent in request')
13. For reimbursement contracts: Validate program with submitted id exists
    1. in case of error return 422 error ('Reimbursement program with such id does not exist ')
14. For reimbursement contracts: Validate program with submitted id is an active program
    1. in case of error return 409 error ('Reimbursement program is not active')
15. For reimbursement contracts: Validate program with submitted id has 'medication' type
    1. in case of error return 409 error ('Program with such id is not a reimbursement program')
16. Validate contractor_payment_details:
    1. if payer_account not like ^UA[0-9]{22}$ or ^UA[0-9]{27}$ -> MFO must be required

Determine parent contract (optional)

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

1. find contract that matches transmitted '$contract_number':
   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

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
• medical_program_id

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

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	: INITIAL_CONTRACT_REQUEST
   timestamp	:TIMESTAMP

2. Upload signed contract request to media storage