Properties of a REST API method document

Document type	Метод REST API
Document title	[DRAFT] REST API Get licenses [API-005-009-003-0187]
Guideline ID	GUI-0011
Author	@Vitalii Lieshchov (SoE eHealth)
Document version	1
Document status	DRAFT
Date of creation	14.10.2024
Date of update	10.03.2025
Method API ID	API-005-009-003-0187
Microservices (namespace)	IL
Link на API-специфікацію	https://ehealthmisapi1.docs.apiary.io/#reference/public.-medical-service-provider-integration-layer/licenses/get-licenses
Resource	{{host}}/api/licenses
Scope	license:read
Protocol type	REST
Request type	GET
Sync/Async	Sync
Public/Private	Public

Purpose

This WS allows to get a list of licenses for a legal entity. Used by legal entity employees to receive full information about primary and additional licenses of legal entity.

Key points

This REST method is used by MIS
Only authenticated and authorized user with appropriate scope can get licenses list
The licenses list includes all licenses of legal entity (primary and additional)

Logic

Extract client_id from token.
Filter active licenses:
1. for current legal entity from token (licenses.legal_entity_id=$.client_id).
2. by search params.
Render found licenses with all fields from DB.

Configuration parameters

N/A

Dictionaries

LICENSE_TYPE

Input parameters

	Input parameter	Mandatory	Type	Description	Example

	Input parameter	Mandatory	Type	Description	Example
1	page	+	Number	Page number	2
2	page_size	+	Number	A limit on the number of objects to be returned, between 1 and 300. Default: 50	300
3	id	-	String	id of license	d290f1ee-6c54-4b01-90e6-d701748f0851
4	license_number	-	String	Number of license	FD12344344
5	type	-	String	Type of license (Dictionary LICENSE_TYPE)	Pharmacy
6	is_primary	-	Boolean	Primary or additional license flag	true

Request structure

See on API-specification

Headers

Request data validation

Authorize

Verify the validity of MIS client secret
- in case of error - return 401 (“Invalid access token”)
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 = 'license:read')
- return 403 (“Your scope does not allow to access this resource. Missing allowances: license:read”) in case of invalid scope(s)

Processing

N/A

Response structure examples

See on API-specification

{
  "meta": {
    "code": 200,
    "url": "https://example.com/resource",
    "type": "object",
    "request_id": "req-adasdoijasdojsda"
  },
  "data": [
    {
      "id": "d290f1ee-6c54-4b01-90e6-d701748f0851",
      "type": "MSP",
      "license_number": "fd123443",
      "issued_by": "Кваліфікацйна комісія",
      "issued_date": "2022-02-28",
      "expiry_date": "2026-02-28",
      "active_from_date": "2022-02-28",
      "what_licensed": "реалізація наркотичних засобів",
      "order_no": "ВА43234",
      "legal_entity_id": "28d9c1be-08f0-403b-aa76-bff228c9904f",
      "is_primary": true
    }
  ],
  "paging": {
    "page_number": 2,
    "page_size": 50,
    "total_entries": 1000,
    "total_pages": 23
  }
}

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	Invalid access token
4		403	Your scope does not allow to access this resource. Missing allowances: license:read
5	Специфічні
6

Post-processing processes

N/A

Technical modules where the method is used

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

[DRAFT] REST API Get licenses [API-005-009-003-0187]

Analytics

Properties of a REST API method document

Purpose

Key points

Logic

Configuration parameters

Dictionaries

Input parameters

Request structure

Headers

Request data validation

Authorize

Processing

Response structure examples

HTTP status codes

Post-processing processes

Technical modules where the method is used

Related content