1 Purpose
2 Key points
3 Specification
4 Input parameters
5 Service logic
- 5.1 Errors mapping
- 5.2 Errors
  - 5.2.1 Business logic errors
  - 5.2.2 Schema validation errors
    - 5.2.2.1 Required property missing
    - 5.2.2.2 Value in the field is not allowed by enum
    - 5.2.2.3 Value in the field does not correspond to regular expression
    - 5.2.2.4 Number of items in list

Purpose

This WS is designed to show user login sign-up that is used to create person and persons user in the system.

Key points

Applications must redirect users to this endpoint to perform patient and user registration process.
After person and its user is created in the system, method reditects to ‘Accept scopes’ page to obtain oAuth Code Grant (which is later exchanged to Access Token).
User will see rendered registration page, which structure differ by a list of requested scopes and security measures applied by DevOps team.
For security purposes, set X-Frame-Options: deny header will be set to disallow opening this page in an iframe.
In case of error (except invalid redirect_uri or client_id) and VITE_REDIRECT_ERRORS config param = true - user will be redirected to the redirect_uri with error and description according to RFC 6749: The OAuth 2.0 Authorization Framework

Specification

Input parameters

Input parameter	M/O	Type	Description

Input parameter	M/O	Type	Description
client_id	M	String	Client id issued after legal entity or PIS registration. Used to identify the context of the MSP/Pharmacy/PIS
redirect_uri	M	String	URL where user will be redirected after registration and authentification. This url will receive `code` and `state`parameters in query string
scope	M	String	List of scopes that is required in application business logic, separated by space. Different login forms will be shown based on scopes that you requested
user_data	M	Base 64 String	Encoded signed content with person registration data
state	O	String	Randomly generated, opaque, and non-guessable string generated by client that will be transferred to client with grant code

Service logic

Render sign-up page based on input parameters and configuration parameters:
1. proceed to ‘Approve person details’ page.
In case of error and VITE_REDIRECT_ERRORS config param = true - redirect user to redirect_uri with error, error_description and state (RFC 6749: The OAuth 2.0 Authorization Framework)

Errors mapping

BE error	Error to redirect	Error description to redirect

BE error	Error to redirect	Error description to redirect
message: user_data missing	`invalid_request`	user_data missing
message: Invalid signed content.	`invalid_request`	Invalid signed content.
message: Invalid signature	`invalid_request`	Invalid signature
message: Invalid access token	`access_denied`	Invalid access token
message: JWT is invalid.	`invalid_request`	JWT is invalid.
message: Unable to authenticate signer.	`access_denied`	Unable to authenticate signer
message: expected true but got false for attribute patient_signed	`access_denied`	expected true but got false for attribute patient_signed
message: expected true but got false for attribute process_disclosure_data_consent	`access_denied`	expected true but got false for attribute process_disclosure_data_consent
message: It is impossible to uniquely identify the person.	`access_denied`	It is impossible to uniquely identify the person.
message: Relationship not confirmed.	`access_denied`	Relationship not confirmed
message: Submitted document type is not allowed.	`access_denied`	Submitted document type is not allowed
message: Submitted document type '#{type}' is not allowed.	`access_denied`	Submitted document type '#{type}' is not allowed
message: User is blocked.	`access_denied`	User is blocked.
message: Person not found.	`access_denied`	Person not found.
message: Person who initiates registration of patient must be submitted as confidant person.	`access_denied`	Person who initiates registration of patient must be submitted as confidant person
message: Person with cumulative verification status NOT_VERIFIED can not be submitted as confidant.	`access_denied`	Person with cumulative verification status NOT_VERIFIED can not be submitted as confidant
message: Person with cumulative verification status VERIFICATION_NEEDED can not be submitted as confidant.	`access_denied`	Person with cumulative verification status VERIFICATION_NEEDED can not be submitted as confidant
message: Confidant person must have active authentication method with type "OTP" where ended_at is equal to or greater than current date.	`access_denied`	Confidant person must have active authentication method with type "OTP" where ended_at is equal to or greater than current date
message: Only THIRD_PERSON authentication method can be created for person.	`access_denied`	Only THIRD_PERSON authentication method can be created for person
message: Person who initiates registration of patient must be submitted as THIRD_PERSON.	`access_denied`	Person who initiates registration of patient must be submitted as THIRD_PERSON
message: Applicant user not found.	`access_denied`	Applicant user not found.
message: Applicant user is blocked.	`access_denied`	Applicant user is blocked.
message: Applicant person not found.	`access_denied`	Applicant person not found.
message: Incorrect applicant person age for such an action.	`access_denied`	Incorrect applicant person age for such an action.
type: validation_failed message: Validation failed. You can find validators description at our API Manifest: Nebo #15 API Manifest · Apiary .	`invalid_request`	Validation failed

All other errors not mapped in list above must be redirected with error = server_error without description

Errors

Business logic errors

Error	Translation

Error	Translation
message: user_data missing	Відсутні дані для реєстрації
message: Invalid signed content.	Підписаний контент некоректний або прострочений.
message: Invalid signature	Підписаний контент некоректний або прострочений.
message: Invalid access token	Не вдалося автентифікувати користувача
message: JWT is invalid.	Підписаний контент некоректний або прострочений.
message: Unable to authenticate signer	Не вдалося ідентифікувати підписанта
message: expected true but got false for attribute patient_signed	Користувач повинен погодитись з підписанням даних
message: expected true but got false for attribute process_disclosure_data_consent	Користувач повинен погодитись з передачею даних в ЕСОЗ
message: It is impossible to uniquely identify the person.	Не вдалося ідентифікувати персону. Зверніться до служби підтримки
message: Relationship not confirmed	Звʼязок між авторизованою особою і довіреною особою не підтверджено
message: Submitted document type is not allowed	Некоректний тип документу
message: User is blocked.	Користувача заблоковано
message: Person not found.	Не вдалося ідентифікувати персону. Зверніться до служби підтримки
message: Person who initiates registration of patient must be submitted as confidant person	Особа що створює запит на реєстрацію має бути вказана як законний представник
message: Person with cumulative verification status NOT_VERIFIED can not be submitted as confidant	Особа яка вказана як законний представник не верифікована
message: Person with cumulative verification status VERIFICATION_NEEDED can not be submitted as confidant	Особа яка вказана як законний представник потребує верифікації
message: Confidant person must have active authentication method with type "OTP" where ended_at is equal to or greater than current date	Не коректний метод авторизації особи що вказана як законний представник
message: Only THIRD_PERSON authentication method can be created for person	Дозволена авторизація тільки через законного представника
message: Person who initiates registration of patient must be submitted as THIRD_PERSON	Не коректний ідентифікатор особи що автенторизує дії
message: Applicant user not found.	Користувача довіреної особи не знайдено
message: Applicant user is blocked.	Користувача довіреної особи заблоковано
message: Applicant person not found.	Персону довіреної особи не знайдено
message: Incorrect applicant person age for such an action.	Для вказаного віку довіреної особи авторизація в системі не дозволена

Schema validation errors

Required property missing

Error structure

"invalid": [
            {
                "entry": "$.person.birth_date",
                "entry_type": "json_data_property",
                "rules": [
                    {
                        "description": "required property birth_date was not present",
                        "params": {
                            "property": "birth_date"
                        },
                        "raw_description": "required property %{property} was not present",
                        "rule": "required"
                    }
                ]
            }
        ]

Translation

Обовʼязковий атрибут "%{property}" відсутній

Value in the field is not allowed by enum

Error structure

"invalid": [
            {
                "entry": "$.person.confidant_person.documents_relationship.[0].type",
                "entry_type": "json_data_property",
                "rules": [
                    {
                        "description": "value is not allowed in enum",
                        "params": {
                            "values": [
                                "BIRTH_CERTIFICATE",
                                "BIRTH_CERTIFICATE_FOREIGN",
                                "CONFIDANT_CERTIFICATE",
                                "COURT_DECISION",
                                "DOCUMENT"
                            ]
                        },
                        "raw_description": "value is not allowed in enum",
                        "rule": "inclusion"
                    }
                ]
            }
        ]

Translation

Недопустиме значення для поля "%{property}"

Value in the field does not correspond to regular expression

Error structure

        "invalid": [
            {
                "entry": "$.person.documents.[0].number",
                "entry_type": "json_data_property",
                "rules": [
                    {
                        "description": "string does not match pattern \"^((?![ЫЪЭЁ])([А-ЯҐЇІЄ])){2}[0-9]{6}$\"",
                        "params": {
                            "pattern": "^((?![ЫЪЭЁ])([А-ЯҐЇІЄ])){2}[0-9]{6}$"
                        },
                        "raw_description": "string does not match pattern \"%{pattern}\"",
                        "rule": "format"
                    }
                ]
            }
        ]

Translation

Недопустиме значення для поля "%{property}"

Entry	Translation

Entry	Translation
$.person.first_name	Імʼя
$.person.last_name	Прізвище
$.person.second_name	По-батькові
$.person.birth_date	Дата народження
$.person.birth_country	Країна народження
$.person.birth_settlement	Місце народження
$.person.gender	Стать
$.person.email	Адреса електронної пошти
$.person.no_tax_id	Ознака відсутності ІПН
$.person.secret	Кодове слово
$.person.documents	Документи
$.person.documents.[0].type	Тип документу
$.person.documents.[0].number	Номер документу
$.person.documents.[0].issued_by	Місце видачі документу
$.person.documents.[0].issued_at	Дата видачі документу
$.person.documents.[0].expiration_date	Дата закінчення дії документу
$.person.addresses	Адреса
$.person.addresses.[0].type	Тип адреси
$.person.addresses.[0].country	Країна прописки (проживання)
$.person.addresses.[0].area	Область прописки (проживання)
$.person.addresses.[0].region	Район прописки (проживання)
$.person.addresses.[0].settlement	Населений пункт прописки (проживання)
$.person.addresses.[0].settlement_type	Тип населеного пункту прописки (проживання)
$.person.addresses.[0].settlement_id	Ідентифікатор населеного пункту прописки (проживання)
$.person.addresses.[0].street_type	Тип вулиці прописки (проживання)
$.person.addresses.[0].street	Вулиця прописки (проживання)
$.person.addresses.[0].building	Будинок прописки (проживання)
$.person.addresses.[0].apartment	Квартира прописки (проживання)
$.person.addresses.[0].zip	Поштовий індекс прописки (проживання)
$.person.phones	Телефони
$.person.phones.[0].type	Тип телефону
$.person.phones.[0].number	Номер телефону
$.person.authentication_methods	Методи автентифікації
$.person.authentication_methods.[0].type	Тип методу автентифікації
$.person.authentication_methods.[0].value	Значення методу автентифікації
$.person.authentication_methods.[0].alias	Найменування методу автентифікації
$.person.preferred_way_communication	Бажаний спосіб комунікації
$.person.confidant_person	Довірена особа
$.person.confidant_person.person_id	Ідентифікатор довіреної особи
$.person.confidant_person.documents_relationship	Документ що підтверджує звʼязок з довіреною особою
$.person.confidant_person.documents_relationship.[0].type	Тип документу довіреної особи
$.person.confidant_person.documents_relationship.[0].number	Номер документу довіреної особи
$.person.confidant_person.documents_relationship.[0].issued_by	Місце видачі документу довіреної особи
$.person.confidant_person.documents_relationship.[0].issued_at	Дата видачі документу довіреної особи
$.person.emergency_contact	Контактна особа для екстрених випадків
$.person.emergency_contact.first_name	Імʼя контактної особи для екстрених випадків
$.person.emergency_contact.last_name	Прізвище контактної особи для екстрених випадків
$.person.emergency_contact.second_name	По-батькові контактної особи для екстрених випадків
$.person.emergency_contact.phones	Телефони контактної особи для екстрених випадків
$.person.emergency_contact.phones.[0].type	Тип телефону контактної особи для екстрених випадків
$.person.emergency_contact.phones.[0].number	Номер телефону контактної особи для екстрених випадків
$.patient_signed	Ознака підпису запиту пацієнтом
$.process_disclosure_data_consent	Згода з передачею даних в ЕСОЗ

Number of items in list

Error structure

Translation

Entry	Translation

Entry	Translation
$.person.documents	Мінімум один документ особи що реєструється має бути вказаний
$.person.addresses	Мінімум одна адреса має бути вказана
$.person.phones	Мінімум один телефон має бути вказаний
$.person.authentication_methods	Мінімум один метод автентифікації має бути вказаний
$.person.confidant_person.documents_relationship	Мінімум один документ законного представника має бути вказаний
$.person.emergency_contact.phones	Мінімум один телефон контактної особи для екстрених випадків має бути вказаний

E-Health

RC_PIS. Confidant patient sign-up (OAUTH-196)

Purpose

Key points

Specification

Input parameters

Service logic

Errors mapping

Errors

Business logic errors

Schema validation errors

Required property missing

Value in the field is not allowed by enum

Value in the field does not correspond to regular expression

Number of items in list