ЕСОЗ - публічна документація

[DRAFT] Get Person Declaration [API-005-004-001-0058]

Owned by Kateryna Yakovleva

Last updated: Nov 25, 2024 by Anastasiia Prokhorova (SoE eHealth)

10 min read

Сторінка знаходиться в процесі розробки. Інформація на ній може бути застарілою.

https://e-health-ua.atlassian.net/wiki/spaces/EN/pages/17591304241 (remove the link block before publishing the document)

1 Properties of a REST API method document
2 Purpose
3 Logic
4 Configuration parameters
5 Dictionaries
6 Input parameters
7 Request structure
8 Headers
9 Request data validation
- 9.1 Authorize
10 Processing
11 Response structure examples
12 HTTP status codes
13 Post-processing processes
14 Technical modules where the method is used

Properties of a REST API method document

Document type	Метод REST API
Document title	[DRAFT] Get Person Declaration [API-005-004-001-0058]
Guideline ID	GUI-0011
Author	@
Document version	1
Document status	DRAFT
Date of creation	ХХ.ХХ.ХХХХ (дата фінальної версії документа – RC або PROD)
Date of update	ХХ.ХХ.ХХХХ (дата зміни версії)
Method API ID	API-005-004-001-0058
Microservices (namespace)	IL
Component	Declarations
Component ID	COM-005-004
Link на API-специфікацію	https://ehealthmisapi1.docs.apiary.io/#reference/public.-medical-service-provider-integration-layer/persons/get-person-declaration
Resource	{{host}}/api/persons/{{id}}/declaration
Scope	declaration:read
Protocol type	REST
Request type	GET
Sync/Async	Sync
Public/Private	Public

Purpose

This method allows to receive active person declarations issued by current legal entity (based on access_token). It can be used to check if Patient has active declarations in other Legal Entities

Logic

N/A

Configuration parameters

N/A

Dictionaries

PHONE_TYPE
+DOCUMENT_TYPE
+DOCUMENT_RELATIONSHIP_TYPE
EMPLOYEE_TYPE
COUNTRY
EDUCATION_DEGREE
QUALIFICATION_TYPE
SPECIALITY_TYPE
SPEC_QUALIFICATION_TYPE
+DIVISION_TYPE
+ADDRESS_TYPE
SETTLEMENT_TYPE
STREET_TYPE
GENDER

Input parameters

	Input parameter	Mandatory	Type	Description	Example

	Input parameter	Mandatory	Type	Description	Example
1	id		String		`b075f148-7f93-4fc2-b2ec-2d81b19a9b7b`
2

Request structure

See on API-specification

Headers

Request data validation

Authorize

Request to process the request using a token in the headers

Validate mandatory query params
1. person_id (id)
Verify the validity of access token
Check user scopes in order to perform this action
Get legal_entity_id and division_id from current context

Processing

Search ACTIVE (declarations.active = true) person declaration using person_id in OPS_DB.declarations

In case found more than one - get newest declaration (TOP 1 order by inserted_at desc)

Response structure examples

See on API-specification

If no records found - return empty list
If record found and declarations.division_id = context.division_id - return short declaration details

{
  "meta": {
    "code": 200,
    "url": "https://example.com/resource",
    "type": "object",
    "request_id": "6617aeec-15e2-4d6f-b9bd-53559c358f97#17810"
  },
  "data": [
    {
      "id": "b075f148-7f93-4fc2-b2ec-2d81b19a9b7b",
      "declaration_number": "0000-12H4-245D",
      "start_date": "2017-03-02",
      "end_date": "2017-03-02",
      "signed_at": "2017-03-02T00:00:00.000Z",
      "person": {
        "id": "b075f148-7f93-4fc2-b2ec-2d81b19a9b7b",
        "first_name": "Петро",
        "last_name": "Іванов",
        "second_name": "Миколайович",
        "birth_date": "1991-08-19",
        "gender": "FEMALE",
        "tax_id": "3126509816",
        "phones": [
          {
            "type": "MOBILE",
            "number": "+380503410870"
          }
        ],
        "birth_settlement": "Вінниця",
        "birth_country": "Україна",
        "emergency_contact": {
          "first_name": "Петро",
          "last_name": "Іванов",
          "second_name": "Миколайович",
          "phones": [
            {
              "type": "MOBILE",
              "number": "+380503410870"
            }
          ]
        },
        "confidant_person": [
          {
            "relation_type": "PRIMARY",
            "first_name": "Петро",
            "last_name": "Іванов",
            "second_name": "Миколайович",
            "birth_date": "1991-08-19",
            "birth_country": "Україна",
            "birth_settlement": "Вінниця",
            "gender": "MALE",
            "email": "confidant_person@example.com",
            "tax_id": "3126509816",
            "secret": "secret",
            "unzr": "19900101-00099",
            "preferred_way_communication": "email",
            "documents_person": [
              {
                "type": "PASSPORT",
                "number": "АА120518",
                "expiration_date": "2021-02-28",
                "issued_by": "Рокитнянським РВ ГУ МВС Київської області",
                "issued_at": "2017-02-28"
              }
            ],
            "documents_relationship": [
              {
                "type": "BIRTH_CERTIFICATE",
                "number": "АА120518",
                "issued_by": "Рокитнянським РВ ГУ МВС Київської області",
                "issued_at": "2017-02-28"
              }
            ],
            "phones": [
              {
                "type": "MOBILE",
                "number": "+380503410870"
              }
            ]
          }
        ]
      },
      "employee": {
        "id": "d290f1ee-6c54-4b01-90e6-d701748f0851",
        "position": "P1",
        "employee_type": "DOCTOR",
        "status": "APPROVED",
        "start_date": "2017-03-02T10:45:16.000Z",
        "end_date": "2018-03-02T10:45:16.000Z",
        "party": {
          "id": "b075f148-7f93-4fc2-b2ec-2d81b19a9b7b",
          "first_name": "Петро",
          "last_name": "Іванов",
          "second_name": "Миколайович"
        },
        "division_id": "4cffa825-8b5b-4cba-9a38-fb57733e14b2",
        "legal_entity_id": "be3a154c-3e07-496d-9680-f22c443f5d0c",
        "doctor": {
          "educations": [
            {
              "country": "UA",
              "city": "Київ",
              "institution_name": "Академія Богомольця",
              "issued_date": "2017-02-28",
              "diploma_number": "DD123543",
              "degree": "MASTER",
              "speciality": "Педіатр"
            }
          ],
          "qualifications": [
            {
              "type": "SPECIALIZATION",
              "institution_name": "Академія Богомольця",
              "speciality": "Педіатр",
              "issued_date": "2017",
              "certificate_number": "2017",
              "valid_to": "2017",
              "additional_info": "додаткова інофрмація"
            }
          ],
          "specialities": [
            {
              "speciality": "THERAPIST",
              "speciality_officio": true,
              "level": "FIRST",
              "qualification_type": "AWARDING",
              "attestation_name": "Академія Богомольця",
              "attestation_date": "2017-02-28",
              "valid_to_date": "2020-02-28",
              "certificate_number": "AB/21331"
            }
          ],
          "science_degree": {
            "country": "UA",
            "city": "Київ",
            "degree": "",
            "institution_name": "Академія Богомольця",
            "diploma_number": "DD123543",
            "speciality": "Педіатр",
            "issued_date": "2017"
          }
        }
      },
      "division": {
        "id": "d290f1ee-6c54-4b01-90e6-d701748f0851",
        "name": "Бориспільське відділення Клініки Ноунейм",
        "legal_entity_id": "d290f1ee",
        "type": "CLINIC",
        "status": "ACTIVE",
        "mountain_group": false,
        "dls_id": "2872985",
        "dls_verified": true
      },
      "legal_entity": {
        "id": "d290f1ee",
        "name": "Клініка ЦПМСД №1",
        "short_name": "ЦПМСД №1",
        "legal_form": "140",
        "public_name": "ЦПМСД №1",
        "edrpou": "5432345432",
        "status": "ACTIVE",
        "email": "email@example.com",
        "phones": [
          {
            "type": "MOBILE",
            "number": "+380503410870"
          }
        ],
        "addresses": [
          {
            "type": "RESIDENCE",
            "country": "UA",
            "area": "Житомирська",
            "region": "Бердичівський",
            "settlement": "Київ",
            "settlement_type": "CITY",
            "settlement_id": "b075f148",
            "street_type": "STREET",
            "street": "вул. Ніжинська",
            "building": "15",
            "apartment": "23",
            "zip": "02090"
          }
        ]
      },
      "status": "active",
      "scope": "family_doctor",
      "declaration_request_id": "74a6fae6-4207-4e03-a136-f2e70c6b0c02",
      "inserted_at": "2017-03-02T10:45:16.000Z",
      "updated_at": "2017-03-02T10:45:16.000Z",
      "reason": "manual_employee",
      "reason_description": "Згідно постанови 1 від 10.01.2017"
    }
  ],
  "paging": {
    "limit": 20,
    "cursors": {
      "starting_after": "56c31536a60ad644060041af",
      "ending_before": "56c31536a60ad644060041aa"
    },
    "size": 50,
    "has_more": false
  }
}

If record found and declarations.division_id != context.division_id - return 403 Error code

{
  "meta": {
    "code": 403,
    "url": "https://example.com/resource",
    "type": "object",
    "request_id": "6617aeec-15e2-4d6f-b9bd-53559c358f97#17810"
  },
  "error": {
    "type": "forbidden",
    "message": "Active declaration belongs to another msp"
  }
}

HTTP status codes

	Response code	HTTP Status code	Message	Internal name	Description

	Response code	HTTP Status code	Message	Internal name	Description
1	Базові
2		200		Short declaration info if active declaration found AND issued by legal entity that is available for `access_token` scope
3		403		if active declaration found issued by other (not available by access scopes) legal entity
4		404		if active declaration not found
5
6	Специфічні
7

Post-processing processes

N/A

Technical modules where the method is used

ЕСОЗ - публічна документація