REST API method / Метод REST API (настанова) (remove the link block before publishing the document)
Properties of a REST API method document
Purpose
The process is initiated by Legal Entity's side and involves the signature previously signed contract request.
Contract must be 2 time signed: from legal_entity and NHS sides. There is a particular order who must signed first - NHS side. After that legal entity owner or admin can either sign contract request (will be created contract) or terminate contract request.
Logic
This WS is designed to sign contract request from MSP side. Contract request's status must be in status ='NHS_SIGNED'. EDRPOU in DS certeficate = contractor_owner_id.lega_entity.edrpou and suranme in DS=contractor_owner_id.party_id.last_name Method receives signed message (pkcs7) including signed content, digital signature of first signer, digital stamp of first signer, digital signature of second signer and signer public key in signed_content property. All signature fields will be validated (including signer certificate authority). This service will store signed copy of Contract Request in Media Content Storage (will update previous version of file),created contract records and linked employees_divisions if signature is all checks is passed. Object that need to be signed is returned by Get Contract request by ID, urgent, type='signed_content'. In response will be receive a link to download a file in pkcs7 format (signed by NHS side). This data must be signed.
In DS EDRPOU/DRFO must be equal to contractor_legal_entity.edrpou
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 | id |
| String |
|
|
| 2 |
Invoke service 'Get Partially Signed Contract Reqeust by ID'. In the response will be received link to download file in PKCS7 format, which contains data (json + printout form + signature of responsible person from NHS side + digital stamp from NHS side).
This PKCS7 file must be signed and decode in base64.
Request structure
See on API-specification (посилання на сторінку з API-специфікацією)
Description of the REST API request structure, example
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
Check employee
Contract_request can be signed by owner or admin with necessary scopes in equal legal_entity_id and same id as was perviously input in contract_request.
Extract legal_entity_id (client_id) from token. Take contract_request_id.
Check client_id=contractor_legal_entity_id (contractor_side)
Validate that contract_request hasn't been signed by contractor_side already
Check status<>'SIGNED'.
In case of error return 422 error ('The contract was already signed by contractor')
Digital signature
Decode content that is encrypted in an electronic digital signature.
Use Digital signature WS. Method checks digital signature and returns result.
Validate DRFO or EDRPOU
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:
Get client_id from token
Find prn.legal_entities by client_id
Check EDRPOU or DRFO matches prm.legal_entities.EDRPOU
Check if EDRPOU in Certificate details exists and not empty
Check if Certificate_details.EDRPOU=prm.legal_entities.EDRPOU
in case validation from a. didn't pass - Check that DRFO in Certificate details exists and not empty
Convert DRFO and prm.legal_entities.EDRPOU to uppercase
Compare DRFO and prm.legal_entities.EDRPOU as Cyrillic letters
Convert DRFO to Cyrillic and compare as Cyrillic letters
Check if Certificate_details.DRFO=prm.legal_entities.EDRPOU
In case validation fails - generate 422 error
Check that SURNAME in Certificate details is equal to LAST_NAME in Party
Get party.last_name using contractor_owner_id from contract_request (employees.employee_id=contractor_owner_id and client_id=employee.legal_entity_id –> parties.id)
Convert prm.parties.LAST_NAME and Certificate details.SURNAME to uppercase
Compare prm.parties.LAST_NAME and Certificate details.SURNAME as Cyrillic letters
In case validation fails - generate 422 error
Validate DRFO
Get parties.tax_id using party_users.party_id by user_id.
Compare DRFO in Certificate with party.tax_id
Convert DRFO and TAX_ID to uppercase
Compare DRFO and TAX_ID as Cyrillic letters
Convert DRFO to Cyrillic and compare as Cyrillic letters
In case validation fails - generate 422 error
Validate Status
Check contract_request.status='NHS_SIGNED'
in case of error return 422 Error 'Incorrect status for signing'
Check signed content
Check decoded signed content with previously created on IL.db
SELECT data
FROM contract_requests
WHERE id = {:id}
In case if they are not equal - generate 422 error (message: "Signed content does not match the previously created content")
Actualize data:
Invoke service 'Get Contract Reqeust by ID'. In the response will be received printout form and json. Compare it with previously created on IL.db
In case if they are not equal - generate 422 error (message: "Signed content does not match the previously created content")
Validate 1st Signature
Get client_id from token
Find prm.legal_entities by nhs_signer_id → prm.employee→ legal_entity
Check EDRPOU or DRFO matches prn.legal_entities.EDRPOU
Check if EDRPOU in Certificate details exists and not empty
Check if Certificate_details.EDRPOU=prm.legal_entities.EDRPOU
in case validation from a. didn't pass - Check that DRFO in Certificate details exists and not empty
Convert DRFO and prn.legal_entities.EDRPOU to uppercase
Compare DRFO and prn.legal_entities.EDRPOU as Cyrillic letters
Convert DRFO to Cyrillic and compare as Cyrillic letters
Check if Certificate_details.DRFO=prn.legal_entities.EDRPOU
In case validation fails - generate 422 error
Check that SURNAME in Certificate details is equal to LAST_NAME in Party
Get party.last_name using nhs_signer_id from contract_request (employees.employee_id=nhs_signer_id –> parties.id)
Convert prm.parties.LAST_NAME and Certificate details.SURNAME to uppercase
Compare prm.parties.LAST_NAME and Certificate details.SURNAME as Cyrillic letters
In case validation fails - generate 422 error
Validate DRFO
Get parties.tax_id using party_users.party_id by user_id.
Compare DRFO in Certificate with party.tax_id
Convert DRFO and TAX_ID to uppercase
Compare DRFO and TAX_ID as Cyrillic letters
Convert DRFO to Cyrillic and compare as Cyrillic letters
In case validation fails - generate 422 error
Validate Digital Stamp
Check that EDRPOU in Certificate details is equal to EDROU in legal entity by nhs_signer_id → prm.employee→ legal_entity
Check if EDRPOU in Certificate details exists and not empty
Check if Certificate_details.EDRPOU=prm.legal_entities.EDRPOU
In case validation fails - generate 422 error
Validate request
Validate request using JSON schema
In case validation fails - generate 422 error
Check contract request status
If status is not APPROVED - returned error 'Incorrect status'
Capitation only: Validate contractor_employee_divisions
Employees from employee_divisions has employee_type='DOCTOR', status='APPROVED', division is not null
in case of error return 422 error view $employee ('Employee must be an active DOCTOR with linked division')
Check divisions belongs to legal_entity and divisions.status='active'
in case of error return 422 error view $divisions ('Division must be active and within current legal_entity')
Check employee belongs to division
in case of error return 422 error view $employee ('Employee must be within current division')
Validate start_date
start_date>now()
in case of error return 422 error $start_date ('Start date must be greater than create date')
Check whether all id is resolved and valid. For
contractor_legal_entity_id and nhs_legal_entity_id in status='active' and nhs_verified = true (prm.legal_entities)
contractor_owner_id and nhs_signer_id in status = 'APPROVED' (prm.employees)
Search contract_number in contracts.contract_number. if found none or one contract in status='VERIFIED' - validation passed.
In case found contract(s), but in status='TERMINATED' show an error 422 ('There is no active contract with such contract_number')
Reimbursement only: validate that medical_program_id is a valid ID of an ACTIVE medical_program with type 'medication'
in case of error return "Medical program is not active"
Processing
Save signed contract to media storage
Get url for declaration upload
Upload signed contract to media storage.
Parameter | Source |
|---|---|
action | 'GET' |
bucket | 'CONTRACTS' |
resource_id | : CONTRACT_ID |
resource_name | : CONTRACT_NAME |
timestamp | :TIMESTAMP |
Update contract request
update contract_request.status='SIGNED'
update contract_request.contract_id=contract.id
UPDATE contract_requests SET status = 'SIGNED' WHERE id = {:id}
Create Contract
If status='SIGNED'
Create a new record in PRM.contracts with status='VERIFIED'
set is_suspended=false, is_active=true
for each division from array contract_divisions create a new row in contract_divisions
capitation only: for each employee from array create a new row in PRM.contract_employees
Check parent_contract_id
Search parent_contract_id in contracts.id.
Get contract.id by parent_contract_id and status='VERIFIED'
fetch all records in contract_employees by contract_id and end_date is null
set for those records end_date=$contract_request.start_date
In case active contract found - terminate by changing status to TERMINATED.
Check parent contracts
Find there is no contracts
for same contractor_legal_entity_id
within same period [start_date, end_date]
status = VERIFIED
id_form
medical_program_id
In case there is such contract change its' status to 'TERMINATE' and fetch all records in contract_employees by contract_id and end_date is null
set for those records end_date=$contract_request.start_date
Add status to event manager
After status was changed (status = SIGNED) - add new status to event_manager
field | value |
|---|
field | value |
|---|---|
|
|
| Contract_request |
| $.id |
| $.status |
| $.update_at |
| $. |
Deactivate Medical Program Provision
If contract update operation (Sign Contract Request by MSP api with contract_number) (according to link):
define medical programs that are not present in the new contract.
deactivate all active medical program provision for defined programs within contract number and current legal entity:
set is_active = false
set deactivate_reason = AUTO_CONTRACT_TERMINATION
set updated_at, updated by
Note: Status of medical program provision entities for the programs remained in the new contract should not be changed.
Dictionaries
CONTRACT_PAYMENT_METHOD
CONTRACT_TYPE
REIMBURSEMENT_CONTRACT_TYPE
Response structure examples
See on API-specification (посилання на сторінку з API-специфікацією)
Description of the REST API response structure, example
HTTP status codes
Response code | HTTP Status code | Message | Internal name | Description | |
|---|---|---|---|---|---|
| 1 | Базові | ||||
| 2 | 200 | ||||
| 3 | 401 | Unauthorized | Помилка підтвердження | ||
| 4 | 1000 | 404 | Composition not found | COMPOSITION_NOT_FOUND_404 | Не знайдено медичний висновок |
| 5 | 422 | Division must be active and within current legal_entity | |||
| 6 | 422 | Employee must be an active DOCTOR with linked division | |||
| 7 | 422 | Employee must be within current division | |||
| 8 | 422 | Incorrect status for signing | |||
| 9 | 422 | Signed content does not match the previously created content | |||
| 10 | 422 | Start date must be greater than create date | |||
| 11 | 422 | The contract was already signed by contractor | |||
| 12 | 422 | There is no active contract with such contract_number | |||
| 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