...
...
...
...
...
...
...
...
...
...
...
...
Required parameters are marked with "*"
...
Purpose*
Необхідно зазначити призначення методу.
Наприклад: This method allows to receive active person declarations issued by the current legal entity (based on access_token)
Specification*
...
Link
...
Посилання на Apiary або Swagger
...
Resource
...
Наприклад: /api/persons/create
...
Scope
...
Зазначається потрібний scope
...
Components
...
Зазначається перелік бізнес компонентів, які використовують цей метод, наприклад: ePrescription
...
Microservices
...
Перелік мікросервісів, які використовує метод API. Наприклад: Auth, ABAC
...
Protocol type
...
Тип протоколу, який використовується запитом, наприклад: SOAP | REST | JSON
...
Request type
...
Тип HTTP методу, який використовується запитом, наприклад: POST | GET…
...
Sync/Async
...
Метод є синхронним чи асинхронним?
Logic*
Потрібно по пунктах описати логіку методу API або додати діаграму
Preconditions
Які передумови мають бути виконані системою/користувачем. Наприклад:
створений запис в MedicationRequest;
рецепт відпущений (COMPLETED)
Global and configuration parameters
Потрібно вказати глобальні та конфігураційні параметри.
Наприклад:
...
Variable
...
Values
...
Description
...
CARE_PLAN_<category>_ICD10_AM_CONDITIONS_ALLOWED
...
Values that matches with dictionaryeHealth/ICD10_AM/condition_codes
Example: “E10.32, E11.92”
...
Allowed diagnoses for specified care plan category. Diagnoses should match with eHealth/ICD10_AM/condition_codes dictionary, <category> - is a value from dictionary eHealth/care_plan_categories in uppercase
(Example: CARE_PLAN_CLASS_1_ICD10_AM_CONDITIONS_ALLOWED)
Input parameters
Потрібно вказати вхідні параметри, наприклад:
...
Input parameter
...
Values
...
Type
...
Description
...
Example
...
asyncJobId
...
String
...
Async Job Object ID
Filters
Потрібно вказати фільтри. Наприклад:
...
Filter
...
Values
...
Type
...
Description
...
Example
...
id
...
String
...
7f93-4fc2-b2ec-2d81b19a9b7b (string, required)
...
d290f1ee-6c54-4b01-90e6-d701748f0851
Request structure*
See on Apiary
Example:
...
Table of Contents | ||||
---|---|---|---|---|
|
Purpose
This WS is designed to change status of contract request to DECLINED by NHS ADMIN SIGNER. NHS employee can change status of contract request through Admin portal. If NHS Admin wants to decline contract request he/she need to enter a reason
Specification
Page Properties | ||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
|
Logic
Contract request only in status IN_RPOCESS could be declined. To decline contract next fields must be signed by NHS employee and sent by same NHS employee in base64 format (all fields below are required): In DS EDRPOU/DRFO must be equal to contractor_legal_entity.edrpou
Code Block |
---|
{
"id":"09106b70-18b0-4726-b0ed-6bda1369fd52",
"contractor_legal_entity": {
"id": "df9f70ee-4b12-4740-b0f5-bb5aea116863",
"name": "Клініка Ноунейм",
"edrpou": "32323454"
},
"next_status": "DECLINED",
"status_reason": "Не відповідає попереднім домовленостям",
"text": "consent_text"
}
|
Input parameters
Input parameter | Values | Type | Description | Example |
---|---|---|---|---|
id | String |
|
Request structure
See on Apiary
Example:
Expand | ||
---|---|---|
| ||
|
Authorize
Request to process the request using a token in the headers
Headers
Content-Type:application/json
Authorization:Bearer c2778f3064753ea70de870a53795f5c9
Validation data request
Validate request
Check that all fields are present in signed content
"id"
"contractor_legal_entity":
"id"
"name"
"edrpou"
"next_status"
"status_reason"
"text"
Check next_status='DECLINED'
Validate contract request id.
Check contract_requests.id = $.id
in case error return 404 ("Contract request with id=$id doesn't exist")
Validate contractor_legal_entity_id
Legal_entities.id = $.contractor_legal_entity.id and Legal_entities.status='ACTIVE' and is_active=true,
in case error return 422 ("Legal entity in contract request should be active")
$contractor_legal_entity.edrpou in request=prm.legal_entities.edrpou
$contractor_legal_entity.name in request=prm.legal_entities.name
Validate token
Verify the validity of access token
Return 401 in case validation fails
Check if token is not expired
in case error return 401 - "Token is expired"
Validate user
extract user_id from token
extract client_id from token
Check if user is active
in case error return 403 - (user is not active)
check nhs_legal_entity is active
in case error return 403 - (Client is not active)
Check user role = "NHS ADMIN SIGNER"
in case error return 403 "User is not allowed to perform this action"
Validate scopes
Check user scopes in order to perform this action (scope = 'contract_requests:update')
Return 403 in case invalid scope(s) "Your scope does not allow to access this resource. Missing allowances: contract_requests:update"
Validate EDRPOU
Check that EDRPOU in Certificate details exists and not empty
in case of error return 422 error ('Invalid EDRPOU in DS')
Check that EDRPOU in Certificate details is equal to EDPOU in legal entity
Get client_id from token.
Find prm.legal_entities id by client_id
Compare EDRPOU in Certificate with legal_entities.edrpou
In case validation fails - generate 422 error
Check that SURNAME in Certificate details is equal to LAST_NAME in Party
Get user_id → user_parties.party_id → parties.last_name and compare to surname from DS
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 contract request status
Check contract_request.status=IN_PROCESS
in case error return 422 - "Incorrect status of contract_request to modify it"
Digital signature
Decode content that is encrypted in an electronic digital signature.
Use Digital signature WS. Method checks digital signature and returns result.
Processing
Save signed contract request to media storage
Get url for contract request upload.
Parameter | Source |
---|---|
action | 'GET' |
bucket | 'CONTRACT_REQUEST' |
resource_id | : CONTRACT_REQUEST_ID |
resource_name | : CONTRACT_REQUEST_DECLINED |
timestamp | :TIMESTAMP |
Upload signed declaration to media storage
Add status to event manager
After status was changed (status = APPROVED, DECLINED, TERMINATED, NHS_SIGNED or SIGNED) - add new status to event_manager
field | value |
---|---|
|
|
| Contract_request |
| $.id |
| $.status |
| $.update_at |
| $. |
Response structure
See on Apiary
Example:
Expand | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
Authorize*
Вимоги до авторизації: яким чином надається доступ до використання методу
Request to process the request using a token in the headers
Headers*
Наприклад:
Content-Type:application/json
Authorization:Bearer c2778f3064753ea70de870a53795f5c9
api-key:uXhEczJ56adsfh3Ri9SUkc4en
Validate request*
Наприклад:
Validate request using JSON schema
In case validation failed - generate 422 error
Code Block |
---|
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"verification_code": {
"type": "string"
}
},
"required": [
"verification_code"
],
"additionalProperties": false
}
|
Validation data request*
Валідація даних
Parameters that are used when processing the request
Configuration parameters
Наприклад: Доступ до методу визначається скоупом covid_certificate:get . Дозвіл на даний скоуп визначається адміністратором Системи шляхом конфігурування скоупів в контексті клієнтів і ролей.
Dictionaries
Потрібно вказати словники, які використовує метод API
Processing*
Потрібно описати процеси, які відбуваються з даними
1. Using global parameters
Потрібно викликати глобальні параметри (Global parameters), щоб отримати наведені нижче параметри
Response structure*
See on Apiary
Example:
Code Block | |||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
{
"data
|
Post-processing processes*
Що має відбутися в ЦБД після опрацювання та відправлення відповіді, тощо
HTTP status codes
...
HTTP status code
...
Message
...
What caused the error
Backward compatibility
Сумісність з попередніми версіями методу
Purpose
This WS is designed to change status of contract request to DECLINED by NHS ADMIN SIGNER. NHS employee can change status of contract request through Admin portal. If NHS Admin wants to decline contract request he/she need to enter a reason.
Design
TBD
Specification
json schema
Request
status_reason
Validation
Validate token
Verify the validity of access token
Return 401 in case validation fails
Check if token is not expired
in case error return 401 - "Token is expired"
Validate user
extract user_id from token
extract client_id from token
Check if user is active
in case error return 403 - (user is not active)
check nhs_legal_entity is active
in case error return 403 - (Client is not active)
Check user role = "NHS ADMIN SIGNER"
in case error return 403 "User is not allowed to perform this action"
Validate scopes
Check user scopes in order to perform this action (scope = 'contract_requests:update')
Return 403 in case invalid scope(s) "Your scope does not allow to access this resource. Missing allowances: contract_requests:update"
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
Check that EDRPOU in Certificate details exists and not empty
in case of error return 422 error ('Invalid EDRPOU in DS')
Check that EDRPOU in Certificate details is equal to EDPOU in legal entity
Get client_id from token.
Find prm.legal_entities id by client_id
Compare EDRPOU in Certificate with legal_entities.edrpou
In case validation fails - generate 422 error
Check that SURNAME in Certificate details is equal to LAST_NAME in Party
Get user_id → user_parties.party_id → parties.last_name and compare to surname from DS
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 request
Check that all fields are present in signed content
"id"
"contractor_legal_entity":
"id"
"name"
"edrpou"
"next_status"
"status_reason"
"text"
Check next_status='DECLINED'
Validate contract request id.
Check contract_requests.id = $.id
in case error return 404 ("Contract request with id=$id doesn't exist")
Validate contractor_legal_entity_id
Legal_entities.id = $.contractor_legal_entity.id and Legal_entities.status='ACTIVE' and is_active=true,
in case error return 422 ("Legal entity in contract request should be active")
$contractor_legal_entity.edrpou in request=prm.legal_entities.edrpou
$contractor_legal_entity.name in request=prm.legal_entities.name
Validate contract request status
Check contract_request.status=IN_PROCESS
in case error return 422 - "Incorrect status of contract_request to modify it"
Response
mapping
...
field
...
value
...
status
...
DECLINED
...
status_reason
...
$.status_reason
...
updated_at
...
now()
...
updated_by
...
$.user_id
...
nhs_signer_id
...
$.user_id
...
nhs_legal_entity_id
...
$.client_id
Save signed contract request to media storage
Get url for contract request upload.
...
...
...
Upload signed declaration to media storage
Add status to event manager
After status was changed (status = APPROVED, DECLINED, TERMINATED, NHS_SIGNED or SIGNED) - add new status to event_manager
...
field
...
value
...
event_type
...
StatusChangeEvent
...
entity_type
...
Contract_request
...
entity_id
...
$.id
...
properties.status.new_value
...
$.status
...
event_time
...
$.update_at
...
changed_by
...
|
Expand | ||
---|---|---|
| ||
|
Response mapping
field | value |
---|---|
status | DECLINED |
status_reason | $.status_reason |
updated_at | now() |
updated_by | $.user_id |
nhs_signer_id | $.user_id |
nhs_legal_entity_id | $.client_id |
Post-processing processes
API paragraph not found
HTTP status codes
HTTP status code | Message | What caused the error |
---|---|---|
200 |
|
|