{
    "openapi": "3.1.0",
    "info": {
        "title": "API Державного реєстру лікарських засобів України",
        "version": "1.0.0",
        "description": "Дані реєстру у форматі JSON:API. Значення ті самі, що на сайті. Анонімний доступ обмежений за частотою, ключ у заголовку X-Api-Key дає вищий ліміт."
    },
    "servers": [
        { "url": "/api/v1" }
    ],
    "security": [
        {},
        { "apiKey": [] }
    ],
    "paths": {
        "/registrations": {
            "get": {
                "summary": "Перелік реєстраційних посвідчень і пошук",
                "operationId": "listRegistrations",
                "parameters": [
                    { "name": "filter[q]", "in": "query", "description": "Текст пошуку", "schema": { "type": "string", "maxLength": 200 } },
                    { "name": "filter[field]", "in": "query", "description": "Де шукати текст", "schema": { "type": "string", "enum": ["all", "name", "inn", "number", "composition", "atc"], "default": "all" } },
                    { "name": "filter[state]", "in": "query", "description": "Чинні, архівні або всі", "schema": { "type": "string", "enum": ["current", "archive", "any"], "default": "any" } },
                    { "name": "filter[name]", "in": "query", "description": "Назва, ідентифікатор із довідника names", "schema": { "type": "string" } },
                    { "name": "filter[inn]", "in": "query", "description": "МНН, ідентифікатор із довідника inns", "schema": { "type": "string" } },
                    { "name": "filter[atc]", "in": "query", "description": "Код АТС, ідентифікатор із довідника atc", "schema": { "type": "string" } },
                    { "name": "filter[manufacturer]", "in": "query", "description": "Виробник, ідентифікатор із довідника manufacturers", "schema": { "type": "string" } },
                    { "name": "filter[applicant]", "in": "query", "description": "Заявник, ідентифікатор із довідника applicants", "schema": { "type": "string" } },
                    { "name": "filter[country]", "in": "query", "description": "Країна виробника, ідентифікатор із довідника countries", "schema": { "type": "string" } },
                    { "name": "filter[dispensing]", "in": "query", "description": "За рецептом або без рецепта", "schema": { "type": "string", "enum": ["rx", "otc"] } },
                    { "name": "filter[month]", "in": "query", "description": "Рік і місяць початку дії картки", "schema": { "type": "string", "pattern": "^[0-9]{6}$", "examples": ["202102"] } },
                    { "name": "filter[emergency_use]", "in": "query", "description": "1: лише для екстреного застосування", "schema": { "type": "string", "enum": ["1"] } },
                    { "name": "filter[emergency_registration]", "in": "query", "description": "1: лише екстрена державна реєстрація", "schema": { "type": "string", "enum": ["1"] } },
                    { "$ref": "#/components/parameters/pageNumber" },
                    { "$ref": "#/components/parameters/pageSize" }
                ],
                "responses": {
                    "200": {
                        "description": "Сторінка посвідчень. Якщо за запитом нічого не знайдено, може містити схожі назви, тоді meta.approximate дорівнює true.",
                        "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/RegistrationList" } } }
                    },
                    "400": { "$ref": "#/components/responses/Error" },
                    "429": { "$ref": "#/components/responses/Error" }
                }
            }
        },
        "/registrations/{rp}": {
            "get": {
                "summary": "Одне посвідчення",
                "operationId": "getRegistration",
                "parameters": [
                    { "$ref": "#/components/parameters/rp" }
                ],
                "responses": {
                    "200": {
                        "description": "Посвідчення зі значеннями найновішої картки",
                        "content": { "application/vnd.api+json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Registration" } } } } }
                    },
                    "404": { "$ref": "#/components/responses/Error" },
                    "429": { "$ref": "#/components/responses/Error" }
                }
            }
        },
        "/registrations/{rp}/versions": {
            "get": {
                "summary": "Усі картки посвідчення, найновіші першими",
                "operationId": "listRegistrationVersions",
                "parameters": [
                    { "$ref": "#/components/parameters/rp" },
                    { "$ref": "#/components/parameters/pageNumber" },
                    { "$ref": "#/components/parameters/pageSize" }
                ],
                "responses": {
                    "200": {
                        "description": "Сторінка карток",
                        "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/VersionList" } } }
                    },
                    "404": { "$ref": "#/components/responses/Error" },
                    "429": { "$ref": "#/components/responses/Error" }
                }
            }
        },
        "/versions/{unid}": {
            "get": {
                "summary": "Одна картка",
                "operationId": "getVersion",
                "parameters": [
                    { "name": "unid", "in": "path", "required": true, "description": "Ідентифікатор картки: 32 символи (UNID документа в реєстрі), його віддає перелік /registrations/{rp}/versions у полі id", "schema": { "type": "string", "pattern": "^[0-9A-Fa-f]{32}$" } }
                ],
                "responses": {
                    "200": {
                        "description": "Картка",
                        "content": { "application/vnd.api+json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Version" } } } } }
                    },
                    "404": { "$ref": "#/components/responses/Error" },
                    "429": { "$ref": "#/components/responses/Error" }
                }
            }
        },
        "/directories/{collection}": {
            "get": {
                "summary": "Довідник: назви, МНН, коди АТС, виробники, заявники, країни",
                "operationId": "listDirectory",
                "parameters": [
                    { "$ref": "#/components/parameters/collection" },
                    { "name": "filter[state]", "in": "query", "description": "current: лише значення, що мають чинні картки", "schema": { "type": "string", "enum": ["current", "any"], "default": "any" } },
                    { "$ref": "#/components/parameters/pageNumber" },
                    { "$ref": "#/components/parameters/pageSize" }
                ],
                "responses": {
                    "200": {
                        "description": "Сторінка значень",
                        "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/TermList" } } }
                    },
                    "400": { "$ref": "#/components/responses/Error" },
                    "404": { "$ref": "#/components/responses/Error" },
                    "429": { "$ref": "#/components/responses/Error" }
                }
            }
        },
        "/directories/{collection}/{slug}": {
            "get": {
                "summary": "Одне значення довідника",
                "operationId": "getDirectoryTerm",
                "parameters": [
                    { "$ref": "#/components/parameters/collection" },
                    { "name": "slug", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[a-z0-9-]+$" } }
                ],
                "responses": {
                    "200": {
                        "description": "Значення",
                        "content": { "application/vnd.api+json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Term" } } } } }
                    },
                    "404": { "$ref": "#/components/responses/Error" },
                    "429": { "$ref": "#/components/responses/Error" }
                }
            }
        },
        "/changes": {
            "get": {
                "summary": "Картки в порядку, у якому вони дійшли до сайту",
                "description": "Без параметрів починає з початку. Читайте links.next, доки meta.has_more не стане false, збережіть останній links.next і викликайте його наступного разу.",
                "operationId": "listChanges",
                "parameters": [
                    { "name": "since", "in": "query", "description": "Дата й час ISO 8601", "schema": { "type": "string", "format": "date-time" } },
                    { "name": "after", "in": "query", "description": "Ідентифікатор останньої прочитаної картки. Його дає links.next", "schema": { "type": "string", "pattern": "^[0-9A-F]{32}$" } },
                    { "name": "page[size]", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 500, "default": 500 } }
                ],
                "responses": {
                    "200": {
                        "description": "Змінені картки. meta.removed містить ідентифікатори карток, що зникли з публічної частини реєстру.",
                        "content": {
                            "application/vnd.api+json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "data": { "type": "array", "items": { "$ref": "#/components/schemas/Version" } },
                                        "links": { "type": "object", "properties": { "next": { "type": "string", "format": "uri" } } },
                                        "meta": {
                                            "type": "object",
                                            "properties": {
                                                "has_more": { "type": "boolean" },
                                                "removed": { "type": "array", "items": { "type": "string" } }
                                            }
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "400": { "$ref": "#/components/responses/Error" },
                    "429": { "$ref": "#/components/responses/Error" }
                }
            }
        }
    },
    "components": {
        "securitySchemes": {
            "apiKey": { "type": "apiKey", "in": "header", "name": "X-Api-Key" }
        },
        "parameters": {
            "rp": { "name": "rp", "in": "path", "required": true, "description": "Номер посвідчення малими літерами через дефіс, як-от ua-1234-01-01", "schema": { "type": "string", "pattern": "^[a-z0-9-]+$" } },
            "collection": { "name": "collection", "in": "path", "required": true, "schema": { "type": "string", "enum": ["names", "inns", "atc", "manufacturers", "applicants", "countries"] } },
            "pageNumber": { "name": "page[number]", "in": "query", "schema": { "type": "integer", "minimum": 1, "default": 1 } },
            "pageSize": { "name": "page[size]", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25 } }
        },
        "responses": {
            "Error": {
                "description": "Помилка у форматі JSON:API. Відповідь 429 містить заголовок Retry-After.",
                "content": {
                    "application/vnd.api+json": {
                        "schema": {
                            "type": "object",
                            "properties": {
                                "errors": {
                                    "type": "array",
                                    "items": {
                                        "type": "object",
                                        "properties": {
                                            "status": { "type": "string" },
                                            "title": { "type": "string" },
                                            "detail": { "type": "string" }
                                        }
                                    }
                                }
                            }
                        }
                    }
                }
            }
        },
        "schemas": {
            "Manufacturer": {
                "type": "object",
                "properties": {
                    "name": { "type": "string" },
                    "role": { "type": ["string", "null"], "description": "Роль у виробництві, якщо вона зазначена" },
                    "country": { "type": ["string", "null"] }
                }
            },
            "PageMeta": {
                "type": "object",
                "properties": {
                    "current_page": { "type": "integer" },
                    "last_page": { "type": "integer" },
                    "per_page": { "type": "integer" },
                    "total": { "type": "integer" }
                }
            },
            "Registration": {
                "type": "object",
                "properties": {
                    "id": { "type": "string", "examples": ["ua-1234-01-01"] },
                    "type": { "const": "registrations" },
                    "attributes": {
                        "type": "object",
                        "properties": {
                            "number": { "type": "string", "examples": ["UA/1234/01/01"] },
                            "title": { "type": "string" },
                            "inn": { "type": ["string", "null"] },
                            "form": { "type": ["string", "null"] },
                            "composition": { "type": ["string", "null"] },
                            "atc_codes": { "type": "array", "items": { "type": "string" } },
                            "manufacturers": { "type": "array", "items": { "$ref": "#/components/schemas/Manufacturer" } },
                            "applicant": { "type": ["string", "null"] },
                            "applicant_country": { "type": ["string", "null"] },
                            "status": { "type": "integer", "enum": [4, 6, 7, 8, 9], "description": "4 чинна, 6 тимчасова заборона, 7 замінена, 8 термін закінчився, 9 реєстрацію припинено" },
                            "status_label": { "type": "string" },
                            "is_current": { "type": "boolean" },
                            "valid_from": { "type": ["string", "null"], "format": "date" },
                            "valid_to": { "type": ["string", "null"], "format": "date" },
                            "is_unlimited": { "type": "boolean" },
                            "is_until_law": { "type": "boolean" },
                            "early_stop": { "type": "boolean" },
                            "stop_date": { "type": ["string", "null"], "format": "date" },
                            "is_emergency": { "type": "boolean" },
                            "is_emergency_registration": { "type": "boolean" },
                            "dispensing_kind": { "type": ["string", "null"], "enum": ["rx", "otc", "mixed", null] },
                            "first_valid_from": { "type": ["string", "null"], "format": "date" },
                            "versions_count": { "type": "integer" },
                            "last_modified_at": { "type": ["string", "null"], "format": "date-time" }
                        }
                    },
                    "links": {
                        "type": "object",
                        "properties": {
                            "self": { "type": "string", "format": "uri" },
                            "versions": { "type": "string", "format": "uri" },
                            "html": { "type": "string", "format": "uri" }
                        }
                    }
                }
            },
            "RegistrationList": {
                "type": "object",
                "properties": {
                    "data": { "type": "array", "items": { "$ref": "#/components/schemas/Registration" } },
                    "meta": {
                        "allOf": [
                            { "$ref": "#/components/schemas/PageMeta" },
                            { "type": "object", "properties": { "approximate": { "type": "boolean" } } }
                        ]
                    }
                }
            },
            "Version": {
                "type": "object",
                "properties": {
                    "id": { "type": "string", "description": "Ідентифікатор картки" },
                    "type": { "const": "versions" },
                    "attributes": {
                        "type": "object",
                        "properties": {
                            "registration": { "type": "string" },
                            "number": { "type": "string" },
                            "version_key": { "type": "string" },
                            "status": { "type": "integer", "enum": [4, 6, 7, 8, 9] },
                            "status_label": { "type": "string" },
                            "previous_version": { "type": ["string", "null"] },
                            "title": { "type": "string" },
                            "inn": { "type": ["string", "null"] },
                            "synonym": { "type": ["string", "null"] },
                            "form": { "type": ["string", "null"] },
                            "composition": { "type": ["string", "null"] },
                            "atc_codes": { "type": "array", "items": { "type": "string" } },
                            "pharm_group": { "type": ["string", "null"] },
                            "dispensing": { "type": ["string", "null"] },
                            "dispensing_kind": { "type": ["string", "null"], "enum": ["rx", "otc", "mixed", null] },
                            "shelf_life": { "type": ["string", "null"] },
                            "valid_from": { "type": ["string", "null"], "format": "date" },
                            "valid_to": { "type": ["string", "null"], "format": "date" },
                            "is_unlimited": { "type": "boolean" },
                            "is_until_law": { "type": "boolean" },
                            "early_stop": { "type": "boolean" },
                            "stop_date": { "type": ["string", "null"], "format": "date" },
                            "stop_reason": { "type": ["string", "null"] },
                            "order_number": { "type": ["string", "null"] },
                            "order_date": { "type": ["string", "null"], "format": "date" },
                            "termination_order_number": { "type": ["string", "null"] },
                            "termination_order_date": { "type": ["string", "null"], "format": "date" },
                            "terminated_on": { "type": ["string", "null"], "format": "date" },
                            "manufacturers": { "type": "array", "items": { "$ref": "#/components/schemas/Manufacturer" } },
                            "applicant": { "type": ["string", "null"] },
                            "applicant_country": { "type": ["string", "null"] },
                            "packages": { "type": "array", "items": { "type": "object" } },
                            "group": { "type": ["string", "null"] },
                            "is_domestic": { "type": "boolean" },
                            "is_immunobiological": { "type": "boolean" },
                            "is_biological": { "type": "boolean" },
                            "is_herbal": { "type": "boolean" },
                            "is_orphan": { "type": "boolean" },
                            "is_homeopathic": { "type": "boolean" },
                            "inn_type": { "type": ["string", "null"], "enum": ["none", "combined", "mono", null] },
                            "advertising": { "type": ["string", "null"] },
                            "is_authenticity_purchase": { "type": "boolean" },
                            "is_emergency": { "type": "boolean" },
                            "is_emergency_registration": { "type": "boolean" },
                            "acted_from": { "type": ["string", "null"], "format": "date", "description": "З якого дня картка діяла" },
                            "acted_to": { "type": ["string", "null"], "format": "date", "description": "До якого дня картка діяла, разом із перехідним періодом" },
                            "listed_to": { "type": ["string", "null"], "format": "date", "description": "До якого дня картка рахувалась у реєстрі" },
                            "modified_at": { "type": ["string", "null"], "format": "date-time" }
                        }
                    },
                    "links": {
                        "type": "object",
                        "properties": {
                            "self": { "type": "string", "format": "uri" },
                            "registration": { "type": "string", "format": "uri" },
                            "html": { "type": "string", "format": "uri" },
                            "instruction": { "type": "string", "format": "uri", "description": "Сторінка з текстом інструкції, якщо вона є" },
                            "instruction_file": { "type": "string", "format": "uri", "description": "Файл інструкції, якщо він є" }
                        }
                    }
                }
            },
            "VersionList": {
                "type": "object",
                "properties": {
                    "data": { "type": "array", "items": { "$ref": "#/components/schemas/Version" } },
                    "meta": { "$ref": "#/components/schemas/PageMeta" }
                }
            },
            "Term": {
                "type": "object",
                "properties": {
                    "id": { "type": "string" },
                    "type": { "type": "string", "enum": ["names", "inns", "atc", "manufacturers", "applicants", "countries"] },
                    "attributes": {
                        "type": "object",
                        "properties": {
                            "name": { "type": "string" },
                            "code": { "type": ["string", "null"], "description": "Код АТС" },
                            "total_count": { "type": "integer", "description": "Посвідчень усього" },
                            "current_count": { "type": "integer", "description": "Посвідчень, чинних зараз" },
                            "last_modified_at": { "type": ["string", "null"], "format": "date-time" }
                        }
                    },
                    "links": {
                        "type": "object",
                        "properties": {
                            "self": { "type": "string", "format": "uri" },
                            "registrations": { "type": "string", "format": "uri" },
                            "html": { "type": "string", "format": "uri" }
                        }
                    }
                }
            },
            "TermList": {
                "type": "object",
                "properties": {
                    "data": { "type": "array", "items": { "$ref": "#/components/schemas/Term" } },
                    "meta": { "$ref": "#/components/schemas/PageMeta" }
                }
            }
        }
    }
}