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

[DRAFT] Get Declaration by ID [API-005-004-001-0060]

Owned by Kateryna Yakovleva

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

8 min read

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

Document type	Метод REST API
Document title	[Document status] REST API [Назва методу] [ID методу]
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-0060
Microservices (namespace)	IL
Component	Declarations
Component ID	COM-005-004
Link на API-специфікацію	https://ehealthmisapi1.docs.apiary.io/#reference/public.-medical-service-provider-integration-layer/declarations/get-declaration-by-id
Resource	{{host}}/api/declarations/{{id}}
Scope	declaration:read
Protocol type	REST
Request type	GET
Sync/Async	Sync
Public/Private	Public

Purpose

This method allows receiving detailed information about a person’s Declaration by declaration ID

Key points

This is a REST method used by MIS.
Only authenticated and authorized employee with appropriate scope can get declarations details.

Logic

Get data from ops DB:
1. declarations by id
Render a response according to specification.

Configuration parameters

Description of the configuration parameters that are used when processing a request in the system

Dictionaries

Provides a list of links to dictionaries that are available in Confluence

Input parameters

	Input parameter	Mandatory	Type	Description	Example

	Input parameter	Mandatory	Type	Description	Example
1	id		String	Request identifier. Required	d290f1ee-6c54-4b01-90e6-d701748f0851
2

Request structure

See on API-specification

Headers

	Key	Value	Mandatory	Description	Example

	Key	Value	Mandatory	Description	Example
1	Content-Type	application/json	M	Тип контенту	Content-Type:application/json
2	Authorization	Bearer c2778f3064753ea70de870a53795f5c9	M	Перевірка користувача	Authorization:Bearer c2778f3064753ea70de870a53795f5c9
3

Request data validation

Authorize

Verify the validity of access token
- in case of error - return 401 (“Invalid access token”) in case of validation fails
Verify that token is not expired
- in case of error - return 401 (“Invalid access token”)
Check user scopes in order to perform this action (scope = 'declaration:read')
- return 403 (“Your scope does not allow to access this resource. Missing allowances: declaration:read”) in case of invalid scope(s)

Validate declaration

Check that declaration with such ID exists in the system (ops DB)
- in case of error - return 404

Processing

A list of processes related to receiving, changing or transmitting data according to the logic defined in the REST API

Response structure examples

See on API-specification

{
  "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"
  },
  "urgent": {
    "authentication_method_current": {
      "type": "OTP",
      "number": "+38093*****85"
    }
  }
}

HTTP status codes

	Response code	HTTP Status code	Message	Internal name	Description

	Response code	HTTP Status code	Message	Internal name	Description
1	Базові
2		200	Response
3		401	Access token validation failed
4		401	Invalid access token
5		403	Invalid scope
6		403	Your scope does not allow to access this resource. Missing allowances: declaration:read
7	Специфічні
8

Post-processing processes

Description of actions performed on data after processing

Technical modules where the method is used

List of pages describing technical modules where the method is used

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