| 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 або додати діаграму
Preconditions
Які передумови мають бути виконані системою/користувачем. Наприклад:
створений запис в MedicationRequest;
рецепт відпущений (COMPLETED)
Global and configurable 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”
...
(Example: CARE_PLAN_CLASS_1_ICD10_AM_CONDITIONS_ALLOWED)
Input parameters
Потрібно вказати вхідні параметри запиту. Наприклад, для GET /patients/composition/job/{{asyncJobId}} вхідний параметр:
...
Input parameter
...
Values
...
Type
...
Description
...
Example
...
asyncJobId
...
String
...
Async Job Object ID
Filters
Потрібно вказати фільтри. Наприклад, для GET /api/medication_requests/{{id}}/dispenses?status=PROCESSED фільтр:
...
Filter
...
Values
...
Type
...
Description
...
Example
...
status
...
String
...
Optional
...
PROCESSED
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
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*
Що має відбутися в ЦБД після опрацювання та відправлення відповіді, тощо
...
| Table of Contents | ||||
|---|---|---|---|---|
|
Purpose
This method allows to create new contract record in DB through the NHS IT system
Specification
| Page Properties | ||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
|
Logic
WS sets all data for creating contract
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
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 | ||
|---|---|---|
| ||
|
HTTP status codes
HTTP status code | Message | What caused the error |
|---|---|---|
|
|
|
201 |
|
|
Backward compatibility
...