| Table of Contents | ||||
|---|---|---|---|---|
|
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*
...
Project Name
...
COVID-certificate
...
Project abreviation
...
SVC
...
Developer
...
Розробник методу API. Наприклад, Edenlab
...
Project Manager
...
@Єлизавета Гессен-Дармштадська
...
Tech Lead
...
@Іоанн Воїнов
...
Product Owner
...
@Нікодім Святогорцев
...
Вusiness analyst
...
@Пантелеймон Нікомедійський
...
Status
| Status | ||||
|---|---|---|---|---|
|
...
Version
...
1.0
...
Date of release
...
...
Link
...
...
Resource
...
/api/admin/contracts
...
Scope
...
private_contracts:write
...
Components
...
Зазначається перелік бізнес компонентів, які використовують цей метод, наприклад: ePrescription
...
Microservices
...
Перелік мікросервісів, які використовує метод API. Наприклад: Auth, ABAC
...
Protocol type
...
Тип протоколу, який використовується запитом, наприклад: SOAP | REST
...
Request type
...
POST
...
Sync/Async
...
Метод є синхронним чи асинхронним?
Logic*
Потрібно по пунктах описати логіку методу API або додати діаграму
Filters
Потрібно вказати фільтри. Наприклад, для GET /api/medication_requests/{{id}}/dispenses?status=PROCESSED фільтр:
...
Filter
...
Values
...
Type
...
Description
...
Example
...
start_date
...
string
...
contract start date
...
2017-04-20
...
end_date
...
string
...
contract end date
...
2017-04-20
...
status
...
string
...
contract status
...
VERIFIED
...
contractor_legal_entity_id
...
string
...
56440c03-e218-432a-b417-9574b2b287bd
...
contractor_owner_id
...
string
...
54fea667-62cf-4688-ae9e-31acc19d986d
...
contractor_base
...
string
...
documents which allows to represent clinic
...
на підставі закону про Медичне обслуговування населення
...
contractor_payment_details
...
как заполнять вложенные переменные ??
...
object
...
contractor_rmsp_amount
...
number
...
the amount of population which were served by this MSP
...
50000
...
external_contractor_flag
...
boolean
...
the existence of second appendix
...
true
...
external_contractors
...
как заполнять вложенные переменные ??
...
array
...
nhs_signer_id
...
string
...
da8cc932-7bca-4048-a3ff-9b07f901a860
...
nhs_signer_base
...
string
...
documents which allows to represent nhs
...
на підставі наказу
...
nhs_legal_entity_id
...
string
...
e5f76afb-4d96-4279-bcf1-0308457e6b64
...
nhs_payment_method
...
как заполнять вложенные переменные ??
...
enum
...
is_suspended
...
boolean
...
whether the contract is active or temporary suspended
...
false
...
issue_city
...
string
...
place of contract request
...
Київ
...
nhs_contract_price
...
number
...
contract price
...
50000
...
contract_number
...
string
...
human readable number of contract request
...
0000-9EAX-XT7X-3115
...
status_reason
...
string
...
The reason of terminated status
...
default
...
parent_contract_id
...
string
...
09106b70-18b0-4726-b0ed-6bda1369fd52
...
id_form
...
string
...
PMD
...
nhs_signed_date
...
string
...
Date when contract was signed by NHS
...
2017-04-20
...
type
...
string
...
CAPITATION
...
reason
...
string
...
additional the reason of terminated status
...
не було виконано умов контракту
...
signed_content_location
...
string
...
Location of the signed content in media storage
...
bucket_name/folder_identifier/file_name
...
medical_programs
...
как заполнять вложенные переменные ??
...
array
Request structure*
See on Apiary
Example:
...
| title | Request example |
|---|
...
| Table of Contents | ||||
|---|---|---|---|---|
|
Required parameters are marked with "*"
Якщо інформації по відповідному параметру немає, потрібно зазначити: “APIparagraph not found”.
Purpose*
This method allows to create new contract record in DB through the NHS IT system
Specification*
| Page Properties | ||||||||||||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
|
Logic*
API paragraph not found
Filters
Filter | Values | Type | Description | Example |
|---|---|---|---|---|
start_date | string | contract start date | 2017-04-20 | |
end_date | string | contract end date | 2017-04-20 | |
status | string | contract status | VERIFIED | |
contractor_legal_entity_id | string | 56440c03-e218-432a-b417-9574b2b287bd | ||
contractor_owner_id | string | 54fea667-62cf-4688-ae9e-31acc19d986d | ||
contractor_base | string | documents which allows to represent clinic | на підставі закону про Медичне обслуговування населення | |
contractor_payment_details | как заполнять вложенные переменные ?? | object | ||
contractor_rmsp_amount | number | the amount of population which were served by this MSP | 50000 | |
external_contractor_flag | boolean | the existence of second appendix | true | |
external_contractors | как заполнять вложенные переменные ?? | array | ||
nhs_signer_id | string | da8cc932-7bca-4048-a3ff-9b07f901a860 | ||
nhs_signer_base | string | documents which allows to represent nhs | на підставі наказу | |
nhs_legal_entity_id | string | e5f76afb-4d96-4279-bcf1-0308457e6b64 | ||
nhs_payment_method | как заполнять вложенные переменные ?? | enum | ||
is_suspended | boolean | whether the contract is active or temporary suspended | false | |
issue_city | string | place of contract request | Київ | |
nhs_contract_price | number | contract price | 50000 | |
contract_number | string | human readable number of contract request | 0000-9EAX-XT7X-3115 | |
status_reason | string | The reason of terminated status | default | |
parent_contract_id | string | 09106b70-18b0-4726-b0ed-6bda1369fd52 | ||
id_form | string | PMD | ||
nhs_signed_date | string | Date when contract was signed by NHS | 2017-04-20 | |
type | string | CAPITATION | ||
reason | string | additional the reason of terminated status | не було виконано умов контракту | |
signed_content_location | string | Location of the signed content in media storage | bucket_name/folder_identifier/file_name | |
medical_programs | как заполнять вложенные переменные ?? | array |
Request structure*
See on Apiary
Example:
| Expand | ||
|---|---|---|
| ||
|
Authorize*
Verify the validity of api-key
Return 401 in case validation fails
Verify the validity of token
Return 401 in case validation fails
Check scopes in order to perform this action (scope = 'private_contracts:write')
Return 403 in case invalid scope(s)
Request to process the request using a token in the headers
Headers*
Наприклад:
Content-Type:application/json
api-key:c2778f3064753ea70de870a53795f5c9
Validate request*
API paragraph not found
Request data validation*
Validations
The following attributes must be validated
Validate status
Check that status is one of ('VERIFIED', 'TERMINATED')
in case of error return 422 error $.status ('Invalid contract status')
Validate contractor_legal_entity_id
Check that legal entity exist and is_active = true
in case of error return 409 error $.contractor_legal_entity_id ('Invalid contractor legal entity id')
Validate contractor_owner_id
Check that employee exist
in case of error return 404 error $.contractor_owner_id ('Employee is not found')
Check that contractor_owner_id correspond to contractor_legal_entity_id and employee_type = OWNER and status = APPROVED and is_active = true
in case of error return 422 error $.contractor_owner_id ('Contractor owner must be an active and within current legal entity')
Validate contractor_base
Check that the contractor_base string and maximum length is 255 characters
in case of error return 422 error $.contractor_base ('expected value to have a maximum length of 255 but was %{actual}')
Validate nhs_signer_id
Check that employee exist
in case of error return 404 error $.contractor_owner_id ('Employee is not found')
Check that nhs_signer_id correspond to nhs_legal_entity_id and nhs_legal_entity_id = legal_entities.type = NHS and status = APPROVED and is_active = true
in case of error return 422 error $.contractor_owner_id ('Contractor signer must be an active and within NHS legal entity')
Validate nhs_signer_base
Check that the nhs_signer_base string and maximum length is 255 characters
in case of error return 422 error $.nhs_signer_base ('expected value to have a maximum length of 255 but was %{actual}')
Validate nhs_legal_entity_id
check that legal entity exist and is_active = true and nhs_legal_entity_id=legal_entities.type = NHS
in case of error return 409 error $.contractor_legal_entity_id ('Invalid nhs signer id')
Validate nhs_payment_method
check that nhs_payment_method one of ('BACKWARD', 'FORWARD')
in case of error return 422 error $.nhs_payment_method ('Invalid nhs payment method')
Validate is_suspended
Check that the is_suspended boolean
in case of error return 422 error $.is_suspended ('type mismatch. Expected boolean but got %{actual}')
Validate issue_city
Check that the issue_city string and maximum length is 255 characters
in case of error return 422 error $.issue_city ('expected value to have a maximum length of 255 but was %{actual}')
Validate contract_number
Сheck format contract_number: contract number structure XXXX-1234-5678-C , where:
XXXX - series: numbers + only some letters (A, E, H, K, M, P, T, X)
1234-5678 - randomly generated numbers and letters A, E, H, K, M, P, T, Xin case of error return 422 error $.contract_number ('string does not match pattern \"^\\d{4}-[\\dAEHKMPTX]{4}-[\\dAEHKMPTX]{4}$\"')
check there is a contract with such contract_number already exist
in case of error return 422 error $.contract_number ('Verified contract with such number already exists')
Validate nhs_signer_base
Check that nhs_signer_base string and maximum length is 255 characters
in case of error return 422 error $.nhs_signer_base ('expected value to have a maximum length of 255 but was %{actual}')
Validate type
Check that type is 'GB_CBP'
in case of return 409 error $.type ('Invalid contract type')
Validate contractor_payment_details
Check that MFO in the ^[0-9]{6}$ format
in case of error return error 422 $.contractor_payment_details.MFO ('string does not match pattern \"^[0-9]{6}$\')
Check that payer_account in the ^(UA[0-9]{22}|UA[0-9]{27}|[0-9]+)$ format
in case of error return error 422 $.contractor_payment_details.payer_account ('string does not match pattern \"^(UA[0-9]{22}|UA[0-9]{27}|[0-9]+)$')
Validate id_form
Сheck that value exists in the CONTRACT_TYPE dictionary
in case of error return error 422 $.id_form ('value is not allowed in enum')
Validate parent_contract_id
Check that parent_contract_id exist in contracts.id and correspond to contractor_legal_entity_id
in case of error return error 422 $.parent_contract_id ('Parent contract id should be correspond to contractor legal entity')
Check that id from parent_contract_id is Terminated
in case of error return 409 $.parent_contract_id ("Parent contract should be in Terminated status")
Validate medical_programs
Check that medical_programs exist and medical_programs.type = 'SERVICE'
in case of error return 404 $.medical_programs ('Medical program is not found')
Validate that list of medical programs in array doesn't contain duplicates ids:
in case of error return 409 error view $medical_programs ('The list of medical programs contains duplicates')
Processing*
Set system attributes
id | Generate uuid |
is_active | Const: true |
inserted_at | now() timastamp |
inserted_by | User from token |
updated_at | now() timastamp |
updated_by | User from token |
2. Store to DB
3. Audit log (trigger logic)
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
| Expand | ||
|---|---|---|
| ||
|
Request data validation*
Валідація даних
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:
| Expand | ||
|---|---|---|
| ||
|
Post-processing processes*
Що має відбутися в ЦБД після опрацювання та відправлення відповіді, тощо
HTTP status codes*
HTTP status code | Message | What caused the error |
|---|---|---|
|
|
|
201 |
|
|
Backward compatibility
...