1 Purpose
- 1.1 Key points
  - 1.1.1 Main diffenrences from V1
2 Specification
3 Logic
- 3.1 Create legal entity
- 3.2 Update legal entity
4 Input parameters
5 Filters
6 Dictionaries
7 Request structure
8 Authorize
9 Headers
10 Request data validation
- 10.1 Validate Digital signature
- 10.2 Validate request
- 10.3 Validate residence address
- 10.4 Validate owner
  - - 10.4.1.1 Validate tax_id
  - 10.4.2 Validate birth date
  - 10.4.3 Validate owners position
  - 10.4.4 Validate existing owner
- 10.5 Validate legal entity with EDR
- 10.6 Validate license
11 Processing
- 11.1 Save signed content
12 Refresh EDR data
- 12.1 Search Legal Entity using EDRPOU from Signer Certificate
- 12.2 Update Client in Auth
- 12.3 Update Legal Entity
- 12.4 Generate client and legal entity identifier
- 12.5 Create client and connection in Auth
- 12.6 Create new Legal Entity
- 12.7 Register employee
13 Response structure
14 Post-processing processes
15 HTTP status codes
16 Backward compatibility

Purpose

This WS is designed to create legal entities in eHealth system or update existing ones.

Key points

This is a REST method used by MIS
Legal entity request must be signed with DS
This is a second version of create / update legal entity endpoint. Main differences from version 1 are descriped below

Main diffenrences from V1

Legal entity types and licenses are created/updated one by one, i.e. one legal entity type and one license are accepted in one call
medical_services_providers structure is removed, accreditation parameter is moved to edr_legal_entities table
legal entity type calculation rules are removed
Validation and merge of kveds step is removed
Mithrill AuthAPI call is changed
MIS verification is removed
Suspend contract on name change is removed
Owner employee can be updated

Specification

Link	https://ehealthmisapi1.docs.apiary.io/#reference/public.-medical-service-provider-integration-layer/legal-entities/create/update-legal-entity-v2	Посилання на Apiary або Swagger
Resource	/api/v2/legal_entities	Посилання на ресурс, наприклад: /api/persons/create
Scope	legal_entity:write	Scope для доступу
Components	Legal Entities	Зазначається перелік бізнес компонентів, які використовують цей метод, наприклад: ePrescription
Microservices	API paragraph not found	Перелік мікросервісів, які використовує метод API, наприклад: Auth, ABAC
Protocol type	REST	Тип протоколу, який використовується запитом, наприклад: SOAP \| REST
Request type	PUT	Тип запиту API, наприклад: GET, POST, PATCH…
Sync/Async	Sync	Метод є синхронним чи асинхронним?
Public/Private/Internal	Public

Logic

Search for existing legal entity in PRM DB based on data from request:
1. legal_entities.edrpou = $.edrpou
2. legal_entities.type = $.type
3. legal_entities.status = ‘ACTIVE’ or ‘SUSPENDED’
If such legal entity is not found, proceed to Create legal entity process
If such legal entity is found, proceed to Update legal entity process

Create legal entity

Save signed content to media storage.
Get detailed data from EDR for active EDR record of legal entity (described at https://e-health-ua.atlassian.net/wiki/spaces/EH/pages/583403122 )
Create or update edr_data record based on logic:
1. If active EDR record of legal entity exists in edr_data table in PRM DB (edr_data.edr_id = $.id of EDR response), update record in edr_data table with following fields from EDR response:
  1. name = names.display
  2. short_name = names.short
  3. public_name = names.name
  4. legal_form = olf_code
  5. kveds = activity_kinds
  6. registration_address = address
  7. updated_by = consumer_id from MIS API token
  8. updated_at = now()
2. If active EDR record of legal entity does not exist in edr_data table in PRM DB (edr_data.edr_id = $.id of EDR response), create new record in edr_data table with following fields from EDR response:
  1. id = generate (uuid)
  2. edr_id = id
  3. name = names.display
  4. short_name = names.short
  5. public_name = names.name
  6. legal_form = olf_code
  7. kveds = activity_kinds
  8. registration_address = address
  9. is_active = true
  10. inserted_by = consumer_id from MIS API token
  11. updated_by = consumer_id from MIS API token
  12. inserted_at = now()
  13. updated_at = now()
Generate legal_entity_id that will be used also as client_id
Create new record in legal_entities table in PRM DB according to received request, also add following fields:
1. id = legal_entity_id
2. name = edr_data.name from created EDR data record
3. public_name = edr_data.public_name from created EDR data record
4. short_name = edr_data.short_name from created EDR data record
5. status = value according to LEGAL_ENTITY_CREATE_STATUS chart parameter (described at Legal Entities configurable parameters )
6. is_active = true
7. inserted_by = consumer_id from MIS API token
8. updated_by = consumer_id from MIS API token
9. inserted_at = now()
10. updated_at = now()
11. created_by_mis_client_id = client_id from MIS API token
12. nhs_unverified_at = now()
13. nhs_verified = false
14. nhs_reviewed = false
15. edr_data_id = edr_data.id from created EDR data record
Create new record in licenses table in PRM DB according to received request, also add following fields:
1. is_primary = true
2. legal_entity_id = legal_entities.id
3. is_active = true
4. inserted_by = consumer_id from MIS API token
5. updated_by = consumer_id from MIS API token
6. inserted_at = now()
7. updated_at = now()
Create employee request for owner according to https://e-health-ua.atlassian.net/wiki/spaces/EH/pages/583402887
Create client details and connection in MITHRIL DB:
1. Generate client record using legal_entities.id in MITHRIL DB.
2. Get consumer_id from MIS API token
3. Create client connection in MITHRIL DB for client and consumer
Create response with following data
1. Legal entity, primary license and edr data details
2. Created employee request id
3. Client connection details

Update legal entity

Save signed content to media storage
Get detailed data from EDR for active EDR record (described at https://e-health-ua.atlassian.net/wiki/spaces/EH/pages/583403122 )
Create or update edr_data record based on logic:
1. If active EDR record of legal entity exists in edr_data table in PRM DB (edr_data.edr_id = $.id of EDR response) and corresponds to legal entity that is being updated (legal_entities.edr_data_id=edr_data.id), update record in edr_data table with following fields from EDR response:
  1. name = names.display
  2. short_name = names.short
  3. public_name = names.name
  4. legal_form = olf_code
  5. kveds = activity_kinds
  6. registration_address = address
  7. updated_by = consumer_id from MIS API token
  8. updated_at = now()
2. If active EDR record of legal entity does not exist in edr_data table in PRM DB (edr_data.edr_id = $.id of EDR response), create new record in edr_data table with following fields from EDR response:
  1. id = generate (uuid)
  2. edr_id = id
  3. name = names.display
  4. short_name = names.short
  5. public_name = names.name
  6. legal_form = olf_code
  7. kveds = activity_kinds
  8. registration_address = address
  9. is_active = true
  10. inserted_by = consumer_id from MIS API token
  11. updated_by = consumer_id from MIS API token
  12. inserted_at = now()
  13. updated_at = now()
If edr_data.state is not in ACTIVE_EDR_STATES chart parameter, update legal entity status in legal_entities table (PRM DB):
1. status = ‘SUSPENDED’
2. status_reason = 'MANUAL_LEGAL_ENTITY_STATUS_UPDATE'
If legal entity status was changed to SUSPENDED:
1. terminate related capitation contract requests
2. suspend related capitation contracts
Update license with following logic:
1. If $.license_id is null then
  1. Check if any attribute has changed comparing request and licenses data. If any, then:
    1. Update license data in licenses table (PRM DB) according to received request for is_primary license record, additionally:
      1. updated_by = consumer_id from MIS API token
      2. updated_at = now()
    2. For legal entity record in legal_entities related to the primary license, update following parameters in PRM DB:
      1. set nhs_reviewed = false
      2. set nhs_verified = false
      3. set nhs_unverified_at = now()
2. If $.license_id is not null then skip license update
Update legal_entities data in PRM DB according to received request, also update following fields:
1. name = edr_data.name from created EDR data record (if edr_data was updated)
2. public_name = edr_data.public_name from created EDR data record (if edr_data was updated)
3. short_name = edr_data.short_name from created EDR data record (if edr_data was updated)
4. updated_by = consumer_id from MIS API token
5. updated_at = now()
6. edr_data_id = edr_data.id from created EDR data record (if edr_data was updated)
Create employee request for owner according to https://e-health-ua.atlassian.net/wiki/spaces/EH/pages/583402887
Update client details and connection in MITHRIL DB:
1. Get consumer_id from MIS API token
2. Create new client connection in MITHRIL DB for client and consumer_id
Create response with following data
1. Legal entity, primary license and edr data details
2. Created employee request id
3. Client connection details
Update accreditation with following logic:
1. if "category": "NO_ACCREDITATION" than check if only required fields are filled, also update following fields:
  1. “issued_date” set null
  2. “expiry_date" set null
  3. “order_date" set null
2. if it is another category- update all fields with the values they were filled with

Input parameters

No

Filters

No

Dictionaries

API paragraph not found

Request structure

Example:

{
  "signed_legal_entity_request": "...",
  "signed_content_encoding": "base64"
}

Authorize

Verify that MIS API token exists in request
- in case of error - return 401 (“Api key is not set")
Verify the validity of MIS API token
- in case of error - return 401 (“Invalid api key”)
Verify that MIS API token is not expired
- in case of error - return 401 (“Invalid api key”)
Check MIS scopes in order to perform this action (scope = 'legal_entity:write')
- return 403 (“Your scope does not allow to access this resource. Missing allowances: legal_entity:write”) in case of invalid scope(s)

Headers

Content-Type:application/json

Authorization:Bearer c2778f3064753ea70de870a53795f5c9

Request data validation

Validate Digital signature

Validate decoded input data is signed
- in case of error - return 422 (“document must contain 1 signature and 0 stamps but contains 0 signatures and 0 stamps”)
Check DS is valid and not expired
Check that Last Name from DS and Owner last_name from request matches
- in case of error - return 422 (“Does not match the signer last name“)
If EDRPOU in Certificate details exists and not empty
- Check that EDRPOU in Certificate details is valid according to ([0-9]{8,10}|[А-ЯЁЇIЄҐ]{2}\d{6}) regular expression
  - in case of error - return 422 (“string does not match pattern")
- Check that EDRPOU in Certificate details is equal to $.edrpou in payload
  - in case of error - return 422 (“EDRPOU does not match legal_entity edrpou“)
If EDRPOU in Certificate details is empty and if DRFO in Certificate details exists and not empty
- Check that DRFO in Certificate details is valid according to ([0-9]{9,10}|[А-ЯЁЇIЄҐ]{2}\d{6}) regular expression
  - in case of error - return 422 (“string does not match pattern")
- Check that DRFO in Certificate details is equal to $.edrpou in payload
  - in case of error - return 422 (“DRFO does not match signer drfo“)
If EDRPOU and DRFO in Certificate details are empty - return 422 (“EDRPOU and DRFO is empty in digital sign“)

Validate request

Validate request using JSON schema
- in case of error - return 422
Validate decoded input data $.signed_legal_entity_request using JSON schema
- in case of error - return 422
Validate uniqueness of object for arrays
- $.phones (one unique $.phones.type per array)
- $.owner.phones (one unique $.owner.phones.type per array)
- $.owner.documents (one unique $.owner.documents.type per array)
  - in case of error - return 422 (“No duplicate values.”)

Validate residence address

Check that $.residence_address.settlement_id exists in uadresses resource
- in case of error - return 422 (“settlement with id = $.residence_address.settlement_id does not exist“)
Check that $.residence_address.settlement corresponds to settlement_name by settlement_id in uadresses resource
- in case of error - return 422 (“invalid settlement value“)
Check that $.residence_address.area corresponds to area_name by settlement_id in uadresses resource
- in case of error - return 422 (“invalid area value“)

Validate owner

Validate tax_id

If $.owner.no_tax_id does not exists in request or exists and equals false, check that $.owner.tax_id is valid according to ^[0-9]{10}$ regular expression
- in case of error - return 422 (“invalid tax_id value“)
If $.owner.no_tax_id equals true, check that $.owner.tax_id is valid according to ([0-9]{9}|[А-ЯЁЇIЄҐ]{2}\d{6}) regular expression
- in case of error - return 422 (“invalid tax_id value”)

Validate birth date

Check that $.owner.birth_date is greater than MIN_BIRTH_DATE chart parameter
- in case of error - return 422 (“invalid birth_date value”)
Check that owners age is greater than MIN_AGE chart parameter
- in case of error - return 422 (“invalid birth_date value”)

Validate owners position

Check that $.owner.position exists in OWNER_POSITIONS chart parameter (described at Legal Entities configurable parameters)
- in case of error - return 422 (“invalid owner position value“)

Validate existing owner

Existing owner must be validated only if $.owner.employee_id is passed in request.

Check that employee with id = $.owner.employee_id exists in PRM DB
- in case of error - return 422 (“Employee not found“)
Check that employee with id = $.owner.employee_id corresponds to Legal entity from payload
- in case of error - return 409 (“Employee doesn't belong to your legal entity“)
Check that employee with id = $.owner.employee_id is an employee with employee_type = ‘OWNER’ or ‘PHARMACY_OWNER’
- in case of error - return 409 (“Invalid employee type”)
Check that employee with id = $.owner.employee_id is an employee with status = ‘APPROVED’ and is_active = true
- in case of error - return 409 (“Invalid employee status“)
Check $.owner.tax_id from request is equal to parties.tax_id for $.owner.employee_id
- in case of error - return 409 (“tax_id doesn't match“)
Check $.owner.tax_id from request is not empty if parties.tax_id for $.owner.employee_id is not empty:
- in case of error - return 422 (“required property tax_id was not present“)
Check $.owner.birth_date from request is equal to parties.birth_date of $.owner.employee_id
- in case of error - return 409 (“birth_date doesn't match“)
If parties.no_tax_id for $.owner.employee_id is true check $.owner.tax_id from request:
- $.owner.tax_id is valid according to ([0-9]{9}|[А-ЯЁЇIЄҐ]{2}\d{6}) regular expression
  - in case of error - return 422 (“string does not match pattern \"^([0-9]{9,10}|[А-ЯЁЇIЄҐ]{2}\\d{6})$\"”)

Validate legal entity with EDR

If new legal entity is created or legal entity with empty edr_data_id is updated
- Check that legal entity $.edrpou exists in EDR
  - in case of error - return 422 (“Provided EDRPOU is not active in EDR”)
- Check that there is only one active record in EDR for legal entity $.edrpou
  - in case of error - return 422 (“More than 1 active entities in EDR“)

Validate license

Check license according to the schema below.

License from request must be validated with related primary license (licenses.is_primary=true where licenses.legal_entity_id=legal_entities.id).

Check if license is needed for legal entity type is performed based on LEGAL_ENTITY_<LEGAL_ENTITY_TYPE>_PRIMARY_LICENSE_TYPES chart parameter (described at Legal Entities configurable parameters )

Processing

Save signed content

Generate RESOURCE_NAME for signed content

Generate RESOURCE_ID for Legal Entity

Invoke Media Content Storage to get upload URL for the document

Parameter	Source

Parameter	Source
action	'PUT'
bucket	'LEGAL_ENTITIES'
resource_id	:RESOURCE_NAME
resource_name	:RESOURCE_ID

Refresh EDR data

Get detailed data from EDR for active EDR record: call EDR data validation using id, received on step EDR Validation.
Create or Update record in prm.edr_data for active EDR record data.

Search Legal Entity using EDRPOU from Signer Certificate

Search Legal Entity in prm.legal_entities using EDRPOU from Signer Certificate where legal_entities.type = Request: $.type and status = active or suspended

If Legal Entity not found go to Generate client and legal entity identifier

If Legal Entity found go to Update Client in Auth

Update Client in Auth

Update Redirect URI

Update Legal Entity

See Service specification

Create/Update licenses

If $.license_id is not null then
1. Check if any attribute has changed comparing request and prm.licenses data. If any, then:
  1. For each record in prm.legal_entities related to the license:
    1. If nhs_reviewed = true reset it to false
    2. If nhs_verified = true
      1. reset it to false
      2. set nhs_verified_change_date to current date
2. Update prm.licenses data according to received request
If $.license_id is null then create new record according to received request
1. link license and edr_data record

Update legal_entities

Update prm.legal_entities data according to received request
1. link to the license if license_id is not null
2. populate updated_by, updated_at
If nhs_reviewed = true reset it to false
If nhs_verified = true reset it to false and set nhs_verified_change_date to current date

Update LE official name

Extract official name from Digital signature.

Update `legal_entities.public_name` in prm with official name from Digital signature
Update `clients.name` in mithril with official name from Digital signature

Update Contract Request

Find contract requests related to current legal entity in status = NEW, APPROVED, PENDING_NHS_SIGN, NHS_SIGNED, set status = 'TERMINATED', status_reason "Legal Entity Data has changed"

Generate client and legal entity identifier

Generate UUID as client identifier and legal entity identifier

Create client and connection in Auth

Invoke Auth API (idempotent PUT) to register new client and generate client secret key
Determine MIS_ID (consumer_id) using api-key
Invoke Put client connection in order to UpSet connection in Mithril for this client and consumer

Create new Legal Entity

See Service specification

Create/Update licenses

If $.license_id is not null then
1. Check if any attribute has changed comparing request and prm.licenses data. If any, then:
  1. For each record in prm.legal_entities related to the license:
    1. If nhs_reviewed = true reset it to false
    2. If nhs_verified = true
      1. reset it to false
      2. set nhs_verified_change_date to current date
2. Update prm.licenses data according to received request
If $.license_id is null then create new record according to received request
1. link license and edr_data record

Populate legal_entities table

Create new record according to received request
1. Link it to the license
2. Link it to edr_data record
Set `nhs_reviewed` and `nhs_verified` to false
Set status = active suspended
Set nhs_verified_change_date to current date

Save LE official name

Extract official name from Digital signature.

Save LE official name to prm DB = legal_entities.public_name
Save LE official name to mithril DB = clients.name

Data sources which are using during creation of prm.legal_entities

Register employee

Create or update new employee request with employee_type == 'OWNER'

Init Create employee request V2

Mapping

Parameter	Source

Parameter	Source
employee_id	Request: $.employee_id
legal_entity_id	Generated previously
employee_type	Const: OWNER
position	Request: $.owner.position
status	Const: ACTIVE
start_date	now()
party	Request: $.owner

Response structure

See on Apiary

Example:

{
  "meta": {
    "code": 200,
    "url": "https://example.com/resource",
    "type": "object",
    "request_id": "req-adasdoijasdojsda"
  },
  "data": {
    "id": "b075f148-7f93-4fc2-b2ec-2d81b19a9b7b",
    "edr": {
      "id": "b075f148-7f93-4fc2-b2ec-2d81b19a9b7b",
      "name": "Клініка Ноунейм",
      "short_name": "Ноунейм",
      "public_name": "Ноунейм",
      "legal_form": "140",
      "edrpou": "54323454",
      "kveds": [
        {
          "name": "Діяльність лікарняних закладів",
          "code": "86.10",
          "is_primary": true
        }
      ],
      "registration_address": {
        "zip": "02090",
        "country": "УКРАЇНА",
        "address": "Волинська обл., місто Луцьк ВУЛИЦЯ КОНЯКІНА буд. 14 кв. 144",
        "parts": {
          "atu": "Волинська обл., місто Луцьк",
          "atu_code": "0710100000",
          "street": "ВУЛИЦЯ КОНЯКІНА",
          "house_type": "буд.",
          "house": "14",
          "building_type": "null",
          "building": "``",
          "num_type": "кв.",
          "num": "144"
        }
      },
      "state": 1
    },
    "edrpou": "32323454",
    "type": "PRIMARY_CARE",
    "residence_address": {
      "type": "RESIDENCE",
      "country": "UA",
      "area": "Житомирська",
      "region": "Бердичівський",
      "settlement": "Київ",
      "settlement_type": "CITY",
      "settlement_id": "b075f148",
      "street_type": "STREET",
      "street": "вул. Ніжинська",
      "building": "15",
      "apartment": "23",
      "zip": "02090"
    },
    "phones": [
      {
        "type": "MOBILE",
        "number": "+380503410870"
      }
    ],
    "email": "email@example.com",
    "website": "www.msp.com.ua",
    "receiver_funds_code": "12345",
    "beneficiary": "Борисов Борис Борисович",
    "accreditation": {
      "category": "SECOND",
      "issued_date": "2017-02-28",
      "expiry_date": "2017-02-28",
      "order_no": "fd123443",
      "order_date": "2017-02-28"
    },
    "license": {
      "id": "b075f148-7f93-4fc2-b2ec-2d81b19a9b7b",
      "type": "MSP",
      "license_number": "fd123443",
      "issued_by": "Кваліфікацйна комісія",
      "issued_date": "2017-02-28",
      "expiry_date": "2017-02-28",
      "active_from_date": "2017-02-28",
      "what_licensed": "реалізація наркотичних засобів",
      "order_no": "ВА43234"
    },
    "archive": [
      {
        "date": "2017-02-28",
        "place": "вул. Грушевського 15"
      }
    ],
    "public_offer": {
      "consent_text": "Consent text",
      "consent": true
    },
    "status": "ACTIVE",
    "nhs_verified": false,
    "nhs_reviewed": false,
    "nhs_comment": "comment"
  },
  "urgent": {
    "security": {
      "secret_key": "secret_key",
      "client_id": "client_id",
      "redirect_uri": "redirect_uri"
    },
    "employee_request_id": "d098aee7-5ab3-4a24-a6ba-811f9cf94c6d"
  }
}

Post-processing processes

API paragraph not found

HTTP status codes

HTTP status code	Message	What caused the error

HTTP status code	Message	What caused the error
200	Response
401	Api key is not set Invalid api key
403	Your scope does not allow to access this resource. Missing allowances: legal_entity:write
409	Employee doesn't belong to your legal entity Invalid employee status Invalid employee type
422	document must contain 1 signature and 0 stamps but contains 0 signatures and 0 stamps More than 1 active entities in EDR Provided EDRPOU is not active in EDR Employee not found invalid owner position value invalid birth_date value invalid tax_id value invalid area value invalid settlement value settlement with id = $.residence_address.settlement_id does not exist No duplicate values. Validate decoded input data $.signed_legal_entity_request using JSON schema failed Validate request using JSON schema failed EDRPOU and DRFO is empty in digital sign DRFO does not match signer drfo EDRPOU does not match legal_entity edrpou string does not match pattern

Backward compatibility

API paragraph not found

E-Health

Create/Update Legal Entity V2

Purpose

Key points

Main diffenrences from V1

Specification

Logic

Create legal entity

Update legal entity

Input parameters

Filters

Dictionaries

Request structure

Authorize

Headers

Request data validation

Validate Digital signature

Validate request

Validate residence address

Validate owner

Validate tax_id

Validate birth date

Validate owners position

Validate existing owner

Validate legal entity with EDR

Validate license

Processing

Save signed content

Refresh EDR data

Search Legal Entity using EDRPOU from Signer Certificate

Update Client in Auth

Update Legal Entity

Generate client and legal entity identifier

Create client and connection in Auth

Create new Legal Entity

Register employee

Response structure

Post-processing processes

HTTP status codes

Backward compatibility