Документация REST API (Версия 1.1)

MY-DOC API

Общая информация

  • Версия: 1.1.0
  • Базовый URL: https://api.my-doc.kz/api/
  • Формат данных: JSON
  • Кодировка: UTF-8

Авторизация

Передайте токен подписчика в заголовке Authorization (без префикса Bearer).

GET /api/branches
Authorization: <ваш токен>

Ограничения

Ограничение частоты запросов: не более одного запроса к API в 2 секунды.

Коды ответов (HTTP Status Codes)

  • 200 OK — Запрос успешно выполнен (в т.ч. когда ресурс не найден: IsSuccess=false в теле).
  • 401 Unauthorized — Нет заголовка Authorization или токен неверный.
  • 403 Forbidden — У подписчика нет доступных филиалов.
  • 404 Not Found — Данные не найдены или нет прав на просмотр.
  • 405 Method Not Allowed — Метод не поддерживается (заголовок Allow).
  • 500 Internal Server Error — Ошибка БД или сервера.

Часовой пояс

Все временные метки в API передаются и принимаются в часовом поясе Asia/Almaty (UTC+5) без указания смещения в строке.

Формат даты и времени для last_update_time и параметра update_after - YYYY-MM-DD HH:MM:SS.
Суффиксы Z и +05:00 не принимаются

Стандартный формат ответа

{
  "IsSuccess": true,
  "Error": null,
  "Data": { ... },
  "Pagination": { ... }
}

Формат ошибки

{
  "IsSuccess": false,
  "Error": "string",
  "Data": null,
  "Pagination": null
}

1. Филиалы (/branches)

1.1. Получение списка филиалов (Офсетная пагинация)

GET /branches

ПараметрТипОписание
idintegerФильтр по ID филиала
namestringПоиск по наименованию
short_namestringПоиск по краткому наименованию
directorstringПоиск по ФИО директора
binstringПоиск по БИН
pageintegerНомер страницы (по умолчанию 1)
limitintegerКол-во записей (по умолчанию 50)

Пример успешного ответа (200 OK):

{
    "IsSuccess": true,
    "Error": null,
    "Data": [
        {
            "id": 1,
            "name": "Филиал №1",
            "short_name": "Ф1",
            "director": "Иванов И. И.",
            "bin": "123456789012"
        }
    ],
    "Pagination": {
        "TotalCount": 1,
        "Page": 1,
        "Limit": 50,
        "TotalPages": 1
    }
}

1.2. Получение филиала по ID

GET /branches/{id}

Пример ответа (404 Not Found):

{
    "IsSuccess": false,
    "Error": "Данные по фильтру [1] не найдены или у вас нет прав на их просмотр.",
    "Data": null,
    "Pagination": null
}

2. Пациенты (/patients)

2.1. Получение списка пациентов (Курсорная пагинация)

GET /patients

ПараметрТипОписание
idintegerФильтр по ID пациента
branch_idintegerФильтр по ID филиала
fiostringПоиск по ФИО
phonestringПоиск по телефону
iinstringПоиск по ИИН
last_update_timestringФильтр по времени обновления (>=)
cursorstringКурсор пагинации
limitintegerКол-во записей

Пример успешного ответа (200 OK):

{
    "IsSuccess": true,
    "Error": null,
    "Data": [
        {
            "id": 123,
            "branch_id": 1,
            "fio": "Иванов Иван Иванович",
            "is_teen": 0,
            "description": null,
            "dob": "1990-05-15",
            "sex": 1,
            "phone": "+7 777 123 45 67",
            "iin": "900515300123",
            "resident": 1,
            "passport": null,
            "address": null,
            "flat_num": null,
            "createdate": 1736899200,
            "pac_city": null,
            "online_access": 1,
            "send_notice": 1,
            "reg_from": 0,
            "last_update_time": "2026-10-16 12:34:56"
        }
    ],
    "Pagination": {
        "Limit": 50,
        "TotalCount": 1,
        "NextCursor": null,
        "HasMore": false
    }
}

2.1 Добавление пациента (/patients)

Создаёт нового пациента или возвращает существующего, если пациент с таким ИИН уже есть у подписчика. Все обязательные поля проверяются на сервере.

23.1. Создание пациента

POST /patients

Тело запроса — application/json (или application/x-www-form-urlencoded).

Поле Тип Обязательно Описание
branch_id integer Да ID филиала. Должен быть в списке доступных филиалов подписчика.
source integer Да ID источника пациента. Должен быть доступен подписчику (см. /patientsources).
country_id integer Да ID страны (см. /countries). Используется для проверки телефона и префикса.
cl_name string Да ФИО. До 200 символов. Приводится к Title Case.
cl_dob string Да Дата рождения в формате dd.mm.YYYY.
cl_sex string Да Пол: 0 или 1.
cl_phone string Да Телефон — только цифры, полный номер с префиксом (например 77771234567).
cl_resident integer Да 1 — резидент РК, 0 — нерезидент.
cl_iin string Да, если cl_resident = 1 ИИН — 12 цифр.
cl_passport string Да, если cl_resident = 0 Паспорт.
rec_address string Нет Адрес.
rec_client_flat string Нет Квартира.

Пример запроса:

POST /api/patients
Authorization: <ваш токен>
Content-Type: application/json

{
  "branch_id": 4,
  "source": 1,
  "country_id": 1,
  "cl_name": "Иванов Иван Иванович",
  "cl_dob": "15.05.1990",
  "cl_sex": "1",
  "cl_phone": "77771234567",
  "cl_resident": 1,
  "cl_iin": "900515300123",
  "rec_address": "г. Алматы, ул. Абая, 1",
  "rec_client_flat": "12"
}

Пример успешного ответа (200 OK):

{
  "IsSuccess": true,
  "Error": null,
  "Data": { "id": 12345 },
  "Pagination": null
}

Пример ответа (ошибка валидации):

{
  "IsSuccess": false,
  "Error": "ИИН должен содержать 12 цифр; Неверная длина номера для страны [1] с префиксом [7]: ожидается 10 цифр после префикса, передано 9.",
  "Data": null,
  "Pagination": null
}

Пример ответа (недоступный источник):

{
  "IsSuccess": false,
  "Error": "Источник с ID [999] недоступен для вашего подписчика.",
  "Data": null,
  "Pagination": null
}

Пример ответа (нет прав на филиал):

{
  "IsSuccess": false,
  "Error": "Нет прав на создание пациента в этом филиале.",
  "Data": null,
  "Pagination": null
}

Пример ответа (страна не найдена):

{
  "IsSuccess": false,
  "Error": "Страна с ID [999] не найдена.",
  "Data": null,
  "Pagination": null
}

Правила валидации

  • branch_id — обязателен, должен быть в списке доступных филиалов подписчика.
  • source — обязателен, должен быть в patientsources для подписчика.
  • country_id — обязателен, должен существовать в /countries.
  • cl_name — обязателен, до 200 символов, Title Case.
  • cl_dob — обязателен, dd.mm.YYYY, конвертируется в YYYY-MM-DD для БД.
  • cl_sex — обязателен, 0 или 1.
  • cl_phone — обязателен, только цифры, полный номер с префиксом. Проверяется по country_phone_mask страны.
  • cl_resident = 1 → cl_iin обязателен, 12 цифр.
  • cl_resident = 0 → cl_passport обязателен.

Дубли по ИИН: если пациент с таким ИИН уже есть у подписчика — возвращается его id (без создания нового). Телефон проверяется по префиксу и маске страны из /countries.


3. Источники пациентов (/patientsources)

3.1. Получение списка источников (Офсетная пагинация)

GET /patientsources

Не привязан к филиалам. Доступные параметры: id, name, page, limit.

Пример успешного ответа (200 OK):

{
    "IsSuccess": true,
    "Error": null,
    "Data": [
        {
            "id": 5,
            "name": "Инстаграм"
        }
    ],
    "Pagination": { "TotalCount": 1, "Page": 1, "Limit": 50, "TotalPages": 1 }
}

4. Услуги (/services)

4.1. Получение списка услуг (Офсетная пагинация)

GET /services

ПараметрТипОписание
idintegerID услуги
cat_idintegerID категории услуги
branch_idintegerID филиала
namestringНазвание услуги (частичное совпадение)
statusintegerСтатус услуги (1/0)
pageintegerНомер страницы
limitintegerКол-во записей

Пример успешного ответа (200 OK):

{
    "IsSuccess": true,
    "Error": null,
    "Data": [
        {
            "id": 101,
            "branch_id": 1,
            "cat_id": 3,
            "is_set": 0,
            "name": "Консультация терапевта",
            "is_action": 0,
            "cost": "5000",
            "solary_cost": "1500",
            "duration": 30,
            "isonline": 1,
            "onlinename": "Консультация терапевта (онлайн)",
            "description": "Первичная консультация",
            "iflimittime": 0,
            "period_from": 0,
            "period_to": 0,
            "daysaccess": 0,
            "time_aval_from": 0,
            "time_aval_to": 0,
            "show_onsite": 1,
            "show_mydoc": 1,
            "use_in_analitycs": 1,
            "agree_id": 0,
            "send_notice": 1,
            "status": 1
        }
    ],
    "Pagination": { "TotalCount": 1, "Page": 1, "Limit": 50, "TotalPages": 1 }
}

5. Категории услуг (/servicecategories)

5.1. Получение списка категорий (Офсетная пагинация)

GET /servicecategories

Доступные параметры: id, branch_id, name, page, limit.

Пример успешного ответа (200 OK):

{
    "IsSuccess": true,
    "Error": null,
    "Data": [
        { "id": 3, "branch_id": 1, "name": "Терапия" }
    ],
    "Pagination": { "TotalCount": 1, "Page": 1, "Limit": 50, "TotalPages": 1 }
}

6. Осмотры (/patient-seeing)

6.1. Получение списка осмотров (Курсорная пагинация)

GET /patient-seeing

Возвращает список осмотров с деталями (вложенный массив details).

ПараметрТипОписание
idintegerФильтр по ID осмотра
patient_idintegerФильтр по ID пациента
user_idintegerФильтр по ID врача
branch_idintegerФильтр по ID филиала
statusintegerФильтр по статусу
create_datestringФильтр по дате создания (>=)
last_update_timestringФильтр по времени обновления (>=)
cursorstringКурсор пагинации
limitintegerКол-во записей

Пример успешного ответа (200 OK):

{
    "IsSuccess": true,
    "Error": null,
    "Data": [
        {
            "id": 55,
            "patient_id": 123,
            "user_id": 7,
            "create_date": 1736899200,
            "status": 1,
            "token": "abc123",
            "branch_id": 1,
            "last_update_time": "2026-10-16 12:34:56",
            "details": [
                {
                    "detail_id": 10,
                    "group_num": 1,
                    "group_name": "Общий осмотр",
                    "data": "..."
                }
            ]
        }
    ],
    "Pagination": { "Limit": 50, "TotalCount": 1, "NextCursor": null, "HasMore": false }
}

7. Журнал записей (/journal)

7.1. Получение списка записей (Курсорная пагинация)

GET /journal

Возвращает список приёмов с деталями. Курсорная пагинация по last_update_time | id.

ПараметрТипОписание
idintegerФильтр по ID записи
patient_idintegerФильтр по ID пациента
branch_idintegerФильтр по ID филиала
master_idintegerФильтр по ID мастера
statusintegerФильтр по статусу (ожидание-1|пришел-2|не пришел-3|подтвердил-4|есть предоплата-5)
rec_statusintegerФильтр: 1 - активная, 0 - удалена
daystringФильтр по дню (timestamp или YYYY-MM-DD)
reg_fromintegerФильтр по IDисточнику пациента
dateaddstringФильтр по дате добавления
last_update_timestringФильтр по времени обновления (>=)
Обновление поля при изменени:
Пациента, Дня записи, Времени записи,Врача, Законного представителя,
Статуса, Параметра уведомления СМС,
Источника записи, Комментария, при Удалении записи
cursorstringКурсор пагинации

Описание раздела [details]

ПараметрТипОписание
detail_idintegerID детали
service_idintegerID услуги
costfloatСтоимость с учетом скидки
serv_costfloatФиксированная стоимость услуги
sal_valuefloatСумма вычета (используется для расчета ЗП сотрудника)
durationintДлительность услуги в секундах
detail_statusintСтатус 1 - активная, 0 - удалена

Пример успешного ответа (200 OK):

{
    "IsSuccess": true,
    "Error": null,
    "Data": [
        {
            "id": 55,
            "patient_id": 123,
            "dateadd": 1736899200,
            "day": 1736899200,
            "timefrom": 1736900000,
            "timeto": 1736901800,
            "send_notice": 1,
            "comment": "Первичный приём",
            "master_id": 7,
            "status": 1,
            "rec_status": 1,
            "token": "abc123",
            "branch_id": 1,
            "reg_from ": 2,
            "last_update_time": "2026-10-16 12:34:56",
            "details": [
                {
                    "detail_id": 10,
                    "service_id": 101,
                    "cost": 5000,
                    "serv_cost": 1500,
                    "sal_value": 500,
                    "duration": 30,
                    "detail_status": 1
                }
            ]
        }
    ],
    "Pagination": { "Limit": 50, "TotalCount": 1, "NextCursor": null, "HasMore": false }
}

8. Журнал изменений (/journaldatalog)

8.1. Получение списка записей (Курсорная пагинация)

GET /journaldatalog

Курсорная пагинация по id.

ПараметрТипОписание
idintegerФильтр по ID записи
branch_idintegerФильтр по ID филиала
jr_idintegerФильтр по ID записи журнала
author_idintegerФильтр по ID автора
operation_typeintegerТип операции: 14 - Создание, 15 - Изменение, 16 - Удаление
operation_dateintegerДата операции (timestamp)
operation_date_fromintegerДата операции от (>=)
operation_date_tointegerДата операции до (<=)
id_fromintegerФильтр «начиная с ID» (>=)
cursorstringКурсор пагинации

Описание раздела [data]

ПараметрТипОписание
v1integerID пациента
v2integerДень записи в формате unix-timestamp
v3integerВремя начала записи в секундах от начала суток
v4integerВремя завершения записи в секундах от начала суток
v5integerОбщая продолжительность приема в секундах
v6stringКомментарий
v7stringКод цвета ячейки
v8intID врача
v9intСтатус
v10intОтправка СМС
v11stringЗаконный представитель
v12intИсточник пациента

Пример успешного ответа (200 OK):

{
    "IsSuccess": true,
    "Error": null,
    "Data": [
        {
            "id": 1000,
            "jr_id": 55,
            "author_id": 7,
            "operation_type": 15,
            "operation_date": 1736899200,
            "branch_id": 1,
            "data":[
                {
                    "v1":149008,
                    "v2":1790708400,
                    "v3":52200,
                    "v4":54000,
                    "v5":1800,
                    "v6":"",
                    "v7":"ffffff",
                    "v8":123,
                    "v9":1,
                    "v10":1,
                    "v11":"",
                    "v12":1
                }
            ]
        }
    ],
    "Pagination": { "Limit": 50, "TotalCount": 1, "NextCursor": null, "HasMore": false }
}

9. Платежи (/journalpayments)

9.1. Получение списка платежей (Курсорная пагинация)

GET /journalpayments

Курсорная пагинация по last_update_time | id.

ПараметрТипОписание
idintegerФильтр по ID платежа
branch_idintegerФильтр по ID филиала
parent_idintegerID родительской записи используется для перемещений и возвратов
operation_typestringТип операции (income, expense, refund)
record_idintegerID записи журнала
stock_movement_idintegerID движения товара
is_productinteger0 — услуга, 1 — продукт
shift_idintegerID кассовой смены
cash_idintegerID кассы (тип платежа опледеляется настройкой Кассы)
master_idintegerID мастера
client_idintegerID клиента
user_idintegerID автора
cbitem_typestringСтатья платежей (определяется справочником /cashbox-items)
statusinteger0 — удалена, 1 — нормальная
datestringДень привязки записи
date_fromstringДень привязки от (>=)
date_tostringДень привязки до (<=)
commentstringПоиск по комментарию
check_idintegerПоиск по ID чека. (наличие при успешной пробивке фискального чека)
last_update_timestringФильтр по времени обновления (>=)

Пример успешного ответа (200 OK):

{
    "IsSuccess": true,
    "Error": null,
    "Data": [
        {
            "id": 501,
            "parent_id": 0,
            "operation_type": "income",
            "record_id": 55,
            "stock_movement_id": 0,
            "is_product": 0,
            "shift_id": 12,
            "cash_id": 3,
            "master_id": 7,
            "client_id": 123,
            "user_id": 7,
            "cbitem_type": "6",
            "money": "5000.00",
            "comment": null,
            "status": 1,
            "date": 1736899200,
            "date_added": 1736899300,
            "branch_id": 1,
            "check_id" : 777,
            "last_update_time": "2026-10-16 12:34:56"
        }
    ],
    "Pagination": { "Limit": 50, "TotalCount": 1, "NextCursor": null, "HasMore": false }
}

10. Кассы (/cashboxes)

10.1. Получение списка касс (Офсетная пагинация)

GET /cashboxes

ПараметрТипОписание
idintegerФильтр по ID кассы
branch_idintegerФильтр по ID филиала
cashtypeintegerФильтр по типу кассы. 0 - Наличный, 1 - Безналичный
namestringПоиск по наименованию
pageintegerНомер страницы
limitintegerКол-во записей

Пример успешного ответа (200 OK):

{
    "IsSuccess": true,
    "Error": null,
    "Data": [
        { "id": 3, "branch_id": 1, "name": "Основная касса", "comment": "Приём наличных", "cashtype":1 }
    ],
    "Pagination": { "TotalCount": 1, "Page": 1, "Limit": 50, "TotalPages": 1 }
}

11. Статьи ДДС (/cashboxitems)

11.1. Получение списка статей (Офсетная пагинация)

GET /cashboxitems

ПараметрТипОписание
idintegerФильтр по ID статьи
branch_idintegerФильтр по ID филиала
typeinteger0 — расход, 1 — доход
namestringПоиск по наименованию
pageintegerНомер страницы
limitintegerКол-во записей

Пример успешного ответа (200 OK):

{
    "IsSuccess": true,
    "Error": null,
    "Data": [
        { "id": 10, "branch_id": 1, "name": "Оплата услуг", "comment": "Основная статья", "type": 1 }
    ],
    "Pagination": { "TotalCount": 1, "Page": 1, "Limit": 50, "TotalPages": 1 }
}

12. Смены касс (/cashshifts)

12.1. Получение списка смен (Офсетная пагинация)

GET /cashshifts

ПараметрТипОписание
idintegerФильтр по ID смены
cash_idintegerФильтр по ID кассы
open_user_idintegerФильтр по автору открытия
closed_byintegerФильтр по автору закрытия
statusstringСтатус смены (open, closed)
branch_idintegerФильтр по ID филиала
shift_start_fromstringДата открытия от (>=)
shift_start_tostringДата открытия до (<=)
created_fromstringДата создания от (>=)
created_tostringДата создания до (<=)
notesstringПоиск по комментарию
pageintegerНомер страницы
limitintegerКол-во записей

Пример успешного ответа (200 OK):

{
    "IsSuccess": true,
    "Error": null,
    "Data": [
        {
            "id": 12, "cash_id": 3, "open_user_id": 7, "shift_start": 1736899200,
            "shift_end": 1736985600, "initial_amount": "0.00", "final_amount": "125000.00",
            "calculated_amount": "125000.00", "difference": "0.00", "status": "closed",
            "notes": "Смена закрыта без расхождений", "closed_by": 7,
            "created_at": 1736899200, "branch_id": 1
        }
    ],
    "Pagination": { "TotalCount": 1, "Page": 1, "Limit": 50, "TotalPages": 1 }
}

13. График работы (/worktime)

13.1. Получение списка записей графика (Офсетная пагинация)

GET /worktime

ПараметрТипОписание
idintegerФильтр по ID записи
branch_idintegerФильтр по ID филиала
user_idintegerФильтр по ID пользователя
doc_idintegerФильтр по ID документа/врача
is_staffinteger0 — не штат, 1 — штат
daystringДень (timestamp)
pageintegerНомер страницы
limitintegerКол-во записей

Пример успешного ответа (200 OK):

{
    "IsSuccess": true,
    "Error": null,
    "Data": [
        {
            "id": 500, "branch_id": 1, "day": 1736899200, "doc_id": 7,
             "time_from": 1736900000, "time_to": 1736936000,
            "user_id": 7, "date_added": 1736899200, "is_staff": 1
        }
    ],
    "Pagination": { "TotalCount": 1, "Page": 1, "Limit": 50, "TotalPages": 1 }
}

14. Пользователи (/users)

14.1. Получение списка пользователей (Офсетная пагинация)

GET /users

ПараметрТипОписание
idintegerФильтр по ID пользователя
branch_idintegerФильтр по ID филиала
usernamestringПоиск по логину
fullnamestringПоиск по ФИО
pageintegerНомер страницы
limitintegerКол-во записей

Пример успешного ответа (200 OK):

{
    "IsSuccess": true,
    "Error": null,
    "Data": [
        { "id": 7, "fullname": "Иванов Иван Иванович", "username": "ivanov" }
    ],
    "Pagination": { "TotalCount": 1, "Page": 1, "Limit": 50, "TotalPages": 1 }
}

15. Должности (/positions)

15.1. Получение списка должностей (Офсетная пагинация)

GET /positions

ПараметрТипОписание
idintegerФильтр по ID должности
branch_idintegerФильтр по ID филиала
namestringПоиск по наименованию
pageintegerНомер страницы
limitintegerКол-во записей

Пример успешного ответа (200 OK):

{
    "IsSuccess": true,
    "Error": null,
    "Data": [
        { "id": 5, "name": "Врач-терапевт", "description": "Врач общей практики", "branch_id": 1 }
    ],
    "Pagination": { "TotalCount": 1, "Page": 1, "Limit": 50, "TotalPages": 1 }
}

16. Должности пользователей (/userpositions)

16.1. Получение списка привязок (Офсетная пагинация)

GET /userpositions

ПараметрТипОписание
idintegerФильтр по ID записи
user_idintegerФильтр по ID пользователя
pos_idintegerФильтр по ID должности
branch_idintegerФильтр по ID филиала
pageintegerНомер страницы
limitintegerКол-во записей

Пример успешного ответа (200 OK):

{
    "IsSuccess": true,
    "Error": null,
    "Data": [
        { "id": 100, "user_id": 7, "pos_id": "5", "branch_id": 1 }
    ],
    "Pagination": { "TotalCount": 1, "Page": 1, "Limit": 50, "TotalPages": 1 }
}

17. Чеки платежей (/paymentchecks)

17.1. Получение списка чеков (Офсетная пагинация)

GET /paymentchecks

Возвращает список фискальных чеков, привязанных к оплате, с фильтрацией и офсетной пагинацией.

Параметр Тип Описание
id integer Фильтр по ID чека
branch_id integer Фильтр по ID филиала
patient_id integer Фильтр по ID пациента
author_id integer Фильтр по ID автора (сотрудника, создавшего чек)
parent_id integer Фильтр по ID родительского чека (для возвратов)
number string Фильтр по номеру чека (точное совпадение)
type integer Тип чека (2 — приход, 3 — возврат прихода и т.п. согласно настройкам ОФД)
mode integer Режим налогообложения / режим чека
status integer Статус чека (0 — удалён, 1 — активен)
page integer Номер страницы. От 1 до 1000. По умолчанию 1.
limit integer Количество записей на странице. От 1 до 100. По умолчанию 50.

Пример успешного ответа (200 OK):

{
  "IsSuccess": true,
  "Error": null,
  "Data": [
    {
      "id": 123,
      "parent_id": 0,
      "number": "312000000",
      "patient_id": 456,
      "author_id": 5,
      "money": 5000,
      "type": 2,
      "mode": 0,
      "token": "5f83d...c17520b18...",
      "time": 1792510621,
      "url": "http://consumer.oofd.kz?i=312720...",
      "status": 1,
      "branch_id": 6
    }
  ],
  "Pagination": {
    "TotalCount": 1,
    "Page": 1,
    "Limit": 50,
    "TotalPages": 1
  }
}

18. Страны (/countries)

18.1. Получение списка стран (Офсетная пагинация)

GET /countries

Возвращает справочник стран. Не привязан к филиалам подписчика — доступен всем авторизованным клиентам.

Параметр Тип Описание
id integer Фильтр по ID страны (точное совпадение)
name string Поиск по наименованию (подстрока)
code string Фильтр по коду страны (точное совпадение, например KZ)
prefix string Фильтр по телефонному префиксу (точное совпадение, например 7)
page integer Номер страницы. От 1 до 1000. По умолчанию 1.
limit integer Количество записей на странице. От 1 до 100. По умолчанию 50.

Пример успешного ответа (200 OK):

{
  "IsSuccess": true,
  "Error": null,
  "Data": [
    {
      "id": 1,
      "flag": "🇰🇿",
      "name": "Казахстан",
      "prefix": "7",
      "code": "KZ",
      "mask": "999 999 9999"
    }
  ],
  "Pagination": {
    "TotalCount": 1,
    "Page": 1,
    "Limit": 50,
    "TotalPages": 1
  }
}

Описание полей ответа

Поле Тип Описание
id integer ID страны
flag string Флаг страны (эмодзи)
name string Наименование страны
prefix string Телефонный префикс страны (например 7 для Казахстана)
code string Двухбуквенный код страны (ISO 3166-1 alpha-2, например KZ)
mask string Маска телефонного номера без префикса. Цифра 9 обозначает обязательную цифру (например 999 999 9999 — 10 цифр после префикса)

19. Услуги для онлайн-записи (/bookingservices)

Возвращает список услуг, на которые можно записаться в выбранном филиале: только онлайн-услуги, у которых есть свободные окна у доступных мастеров и которые не ограничены по времени недоступным периодом.

19.1. Получение списка доступных услуг

GET /bookingservices

Параметр Тип Описание
branch_id integer ID филиала. Обязателен.
service_ids string CSV ID услуг (например 3517,3687). Если передан — возвращаются только эти услуги.
staff_id integer ID мастера. Если передан — возвращаются только услуги, которые оказывает этот мастер.

Пример успешного ответа (200 OK):

{
  "IsSuccess": true,
  "Error": null,
  "Data": {
    "categories": [
      { "id": 22, "name": "УЗИ для взрослых", "branch_id": 1 }
    ],
    "services": [
      {
        "id": 3645,
        "cat_id": 22,
        "branch_id": 1,
        "name": "УЗИ взрослое",
        "cost": 6500,
        "minCost": 5000,
        "maxCost": 6500,
        "duration": 900,
        "isonline": 1,
        "status": 1,
        "slots_count": 39,
        "max_window": 43200,
        "first_date": "2026-10-27"
      }
    ]
  },
  "Pagination": null
}

Если у услуги есть персональные цены у разных мастеров, minCost / maxCost показывают диапазон (например, 5000 – 6500). Если цены одинаковые или персональных нет — оба поля равны базовой cost.

Описание полей ответа

Поле Тип Описание
categories[]arrayКатегории, к которым относятся доступные услуги
categories[].idintegerID категории
categories[].namestringНаименование категории
categories[].branch_idintegerID филиала
services[]arrayДоступные услуги
services[].idintegerID услуги
services[].cat_idintegerID категории
services[].branch_idintegerID филиала
services[].namestringНаименование услуги
services[].costfloatБазовая стоимость услуги (jss_cost)
services[].minCostfloatМинимальная цена (из персональных цен мастеров; если персональных нет — равна cost)
services[].maxCostfloatМаксимальная цена (из персональных цен мастеров; если персональных нет — равна cost)
services[].durationintegerДлительность услуги в секундах
services[].isonlineinteger1 — доступна онлайн
services[].statusinteger1 — активна
services[].slots_countintegerОбщее количество свободных окон
services[].max_windowintegerМаксимальная длительность свободного окна (секунды). Если окно короче duration — услуга не попадает в ответ.
services[].first_datestringПервый доступный день (YYYY-MM-DD)

20. Мастера для онлайн-записи (/bookingstaff)

Возвращает список мастеров, доступных для онлайн-записи в выбранном филиале: только те, у кого есть свободные окна, кто не скрыт в онлайн-записи (Настройка доступа) и кто привязан к подписчику.

20.1. Получение списка доступных мастеров

GET /bookingstaff

Параметр Тип Описание
branch_id integer ID филиала. Обязателен.
service_ids string CSV ID услуг (например 3517,3687). Если передан — возвращаются только мастера, оказывающие эти услуги.

Пример успешного ответа (200 OK):

{
  "IsSuccess": true,
  "Error": null,
  "Data": [
    {
      "id": 222,
      "fullname": "Иванов Иван Иванович",
      "position": "Врач-терапевт",
      "photo": "https://path...",
      "reviews_count": 12,
      "rating": 5,
      "duration": 1200,
      "cost": 5000,
      "sort": "1"
    }
  ],
  "Pagination": null
}

Описание полей ответа

Поле Тип Описание
idintegerID мастера
fullnamestringФИО
positionstringДолжность (одна или несколько через - )
photostring|nullURL фото
reviews_countintegerКоличество отзывов
ratinginteger|nullРейтинг (1–5), null — нет отзывов
durationinteger|nullДлительность услуги у мастера (секунды), null — услуга не передана
costfloat|nullСтоимость услуги у мастера, null — услуга не передана
sortstring|nullЗначение сортировки

Сортировка: сначала мастера с заданной сортировкой (по возрастанию sort), затем — без сортировки (по ФИО).



21. Свободные слоты на день (/bookingavailability)

Возвращает свободные слоты только за выбранный день (или за первый доступный, если datetime не передан) + список всех доступных дней. Если дня нет в свободных окнах — 200 OK с пустым slots[].

21.1. Получение слотов на день

GET /bookingavailability

Параметр Тип Описание
branch_id integer ID филиала. Обязателен.
service_ids string CSV ID услуг. Обязателен.
staff_id integer ID мастера. Обязателен.
datetime string День в формате YYYY-MM-DD. Опционален: если не передан — берётся первый доступный день.

Пример успешного ответа (200 OK):

{
  "IsSuccess": true,
  "Error": null,
  "Data": {
    "date": "2026-10-27",
    "date_ts": 1793214000,
    "master_id": 222,
    "service_ids": [3517],
    "min_duration": 1200,
    "slots": [
      { "from": 30600, "to": 39600, "from_time": "08:30", "to_time": "11:00" },
      { "from": 50100, "to": 52200, "from_time": "13:55", "to_time": "14:30" }
    ],
    "available_dates": ["2026-10-27", "2026-10-28", "2026-10-29"]
  },
  "Pagination": null
}

Пример ответа (день без слотов):

{
  "IsSuccess": true,
  "Error": null,
  "Data": {
    "date": "2026-12-31",
    "date_ts": 1798664400,
    "master_id": 222,
    "service_ids": [3517],
    "min_duration": 1200,
    "slots": [],
    "available_dates": ["2026-10-27", "2026-10-28"]
  },
  "Pagination": null
}

Пример ответа (неверный формат datetime):

{
  "IsSuccess": false,
  "Error": "datetime должен быть в формате YYYY-MM-DD.",
  "Data": null,
  "Pagination": null
}

Описание полей ответа

Поле Тип Описание
datestring|nullВыбранный день (YYYY-MM-DD), null — нет доступных дней
date_tsinteger|nullUnix timestamp начала дня
master_idintegerID мастера
service_idsinteger[]ID услуг
min_durationinteger|nullМинимальная длительность услуги у мастера (секунды)
slots[]arrayСвободные окна на выбранный день
slots[].fromintegerНачало окна — секунды от начала суток
slots[].tointegerКонец окна — секунды от начала суток
slots[].from_timestringНачало окна в формате H:i
slots[].to_timestringКонец окна в формате H:i
available_dates[]string[]Все доступные дни (YYYY-MM-DD)

Ограничения: service_ids и staff_id обязательны; datetime должен быть в формате YYYY-MM-DD (иначе IsSuccess: false).


21.1 Запись на приём (/appointments)

Создаёт запись на приём. Поддерживает два сценария:

  • Пациент известен — передаётся cl_id, данные пациента не требуются (проверяется принадлежность подписчику).
  • Пациент неизвестен — передаются данные пациента, сервер ищет по ИИН или создаёт нового.

21.1. Создание записи

POST /appointments

Тело запроса — application/json (или application/x-www-form-urlencoded).

Параметры записи (обязательные)
ПолеТипОписание
branch_idintegerID филиала. Должен быть в списке доступных филиалов подписчика.
master_idintegerID мастера. Должен оказывать выбранные услуги.
service_idsstringCSV ID услуг (например 3517,3687).
daystringДень записи в формате YYYY-MM-DD.
time_fromstringВремя начала в формате HH:MM.
country_idintegerID страны (см. /countries). Используется для валидации телефона.
sourceintegerID источника пациента (см. /patientsources).
Сценарий A — пациент известен (cl_id)
ПолеТипОписание
cl_idintegerID пациента. Проверяется по группе филиалов (без branch_id).

Если cl_id передан — поля cl_* не требуются и не проверяются. Пациент должен принадлежать подписчику и иметь mp_online_access = 1.

Сценарий B — пациент неизвестен (создание/поиск)
ПолеТипОбязательноОписание
cl_namestringДаФИО (до 200 символов, Title Case).
cl_dobstringДаДата рождения в формате dd.mm.YYYY.
cl_sexstringДаПол: 0 или 1.
cl_phonestringДаТелефон — только цифры, полный номер с префиксом (например 77771234567).
cl_residentintegerДа1 — резидент РК, 0 — нерезидент.
cl_iinstringДа, если cl_resident = 1ИИН — 12 цифр.
cl_passportstringДа, если cl_resident = 0Паспорт.
rec_addressstringНетАдрес.
rec_client_flatstringНетКвартира.
cl_need_updateintegerНет1 (по умолчанию) — обновить данные найденного пациента, 0 — не обновлять. ИИН не перезаписывается, если уже занят другим пациентом подписчика.

Пример запроса (сценарий B — новый пациент):

POST /api/appointments
Authorization: <ваш токен>
Content-Type: application/json

{
  "branch_id": 1,
  "master_id": 222,
  "service_ids": "10",
  "day": "2026-10-28",
  "time_from": "14:00",
  "country_id": 1,
  "source": 21,
  "cl_name": "Иванов Петр Иванович",
  "cl_dob": "10.01.1980",
  "cl_sex": "1",
  "cl_phone": "77771234578",
  "cl_resident": 1,
  "cl_iin": "800110300456"
}

Пример запроса (сценарий A — известный пациент):

POST /api/appointments
Authorization: <ваш токен>
Content-Type: application/json

{
  "branch_id": 4,
  "master_id": 222,
  "service_ids": "10",
  "day": "2026-10-28",
  "time_from": "14:30",
  "country_id": 1,
  "source": 21,
  "cl_id": 21777
}

Пример успешного ответа (200 OK):

{
  "IsSuccess": true,
  "Error": null,
  "Data": {
    "id": 26,
    "token": "ntTKHFSLqGtTlkw9-YjGz5...yYib",
    "day": "2026-10-28",
    "time_from": "12:00",
    "time_to": "12:05",
    "master_id": 243,
    "patient_id": 21674,
    "is_new_patient": false,
    "total_cost": 2500,
    "duration": 300
  },
  "Pagination": null
}

Пример ответа (время занято):

{
  "IsSuccess": false,
  "Error": "Выбранное время уже занято. Выберите другое.",
  "Data": null,
  "Pagination": null
}

Пример ответа (нет подходящего окна):

{
  "IsSuccess": false,
  "Error": "Выбранное время недоступно (нет подходящего окна).",
  "Data": null,
  "Pagination": null
}

Пример ответа (мастер не оказывает услугу):

{
  "IsSuccess": false,
  "Error": "Одна или несколько услуг недоступны для выбранного мастера/филиала.",
  "Data": null,
  "Pagination": null
}

Пример ответа (пациент в чёрном списке):

{
  "IsSuccess": false,
  "Error": "Пациент в чёрном списке.",
  "Data": null,
  "Pagination": null
}

Пример ответа (нет доступа к онлайн-записи):

{
  "IsSuccess": false,
  "Error": "У пациента нет доступа к онлайн-записи. Обратитесь к администратору.",
  "Data": null,
  "Pagination": null
}

Пример ответа (пациент не найден по cl_id):

{
  "IsSuccess": false,
  "Error": "Пациент с ID [99999] не найден или нет прав на его просмотр.",
  "Data": null,
  "Pagination": null
}

Описание полей ответа

ПолеТипОписание
idintegerID созданной записи в журнале
tokenstringТокен записи
daystringДень записи (YYYY-MM-DD)
time_fromstringВремя начала (HH:MM)
time_tostringВремя окончания (HH:MM)
master_idintegerID мастера
patient_idintegerID пациента
is_new_patientbooleantrue — пациент создан, false — найден существующий
total_costintegerСумма по услугам (целые)
durationintegerОбщая длительность услуг (секунды)

Правила и ограничения

  • Слот должен быть свободен — проверяется по /bookingavailability (TFJR). Время [time_from, time_from + duration] должно полностью попадать в свободное окно мастера.
  • Мастер должен работать в это время.
  • Пересечения с существующими активными записями (rec_status = 1) запрещены.
  • Параллельные запросы на одного мастера и день сериализуются через GET_LOCK (3 сек). При занятости — IsSuccess: false.
  • Black list — проверяется по ФИО/телефону/ИИН в рамках группы филиалов (только для сценария B).
  • ИИН не перезаписывается, если уже занят другим пациентом подписчика (при обновлении существующего).
  • online_access = 0 у существующего пациента — запись не создаётся, возвращается ошибка.

Поля rec_type = 5 (API), comment = 'Api', reccolor = '#907b9f', reg_from = source заполняются автоматически и клиенту передавать их не нужно.


21.2. Отмена записи на приём (/appointments/{id})

Отменяет (soft delete) запись на приём. Запись не удаляется физически — устанавливается js_rec_status = 0. Слот освобождается для новых записей. Можно указать причину отмены (calling_res) и комментарий (comment).

21.2. Отмена записи

DELETE /appointments/{id}

ID записи передаётся в URL. Дополнительные параметры (branch_id, calling_res, comment) — в query-строке. Тело запроса не используется.

Параметр Где Тип Обязательно Описание
id path integer Да ID записи
branch_id query integer Нет ID филиала. Если передан — должен быть в списке доступных филиалов подписчика.
calling_res query integer Нет Причина отмены (код). Сохраняется в calling_res.
comment query string Нет Комментарий к отмене (до 255 символов). Сохраняется в comment.

Пример запроса (с причиной и комментарием):

DELETE /api/appointments/266736?branch_id=1&calling_res=3&comment=Пациент%20не%20может%20прийти
Authorization: <ваш токен>

Пример запроса (минимальный):

DELETE /api/appointments/266736
Authorization: <ваш токен>

Пример успешного ответа (200 OK):

{
  "IsSuccess": true,
  "Error": null,
  "Data": {
    "id": 266736,
    "status": 0,
    "calling_res": 3,
    "comment": "Пациент не может прийти",
    "cancelled_at": "2026-10-27 18:33:13"
  },
  "Pagination": null
}

Пример ответа (повторная отмена, идемпотентно):

{
  "IsSuccess": true,
  "Error": null,
  "Data": {
    "id": 266736,
    "status": 0,
    "calling_res": 3,
    "comment": "Пациент не может прийти",
    "cancelled_at": "2026-10-27 18:33:13"
  },
  "Pagination": null
}

При повторной отмене возвращается cancelled_at первой отмены (из last_update_time). Причина и комментарий при повторной отмене не перезаписываются — возвращаются значения, сохранённые при первой отмене.

Пример ответа (запись не найдена / чужой подписчик):

{
  "IsSuccess": false,
  "Error": "Запись с ID [999999] не найдена или нет прав на её отмену.",
  "Data": null,
  "Pagination": null
}

Пример ответа (нет прав на филиал):

{
  "IsSuccess": false,
  "Error": "Нет прав на отмену записи в этом филиале.",
  "Data": null,
  "Pagination": null
}

Пример ответа (нет id в URL):

{
  "IsSuccess": false,
  "Error": "Параметр id обязателен (DELETE /appointments/{id}).",
  "Data": null,
  "Pagination": null
}

Пример ответа (слишком длинный calling_res):

{
  "IsSuccess": false,
  "Error": "calling_res: не более 255 символов.",
  "Data": null,
  "Pagination": null
}

Пример ответа (слишком длинный comment):

{
  "IsSuccess": false,
  "Error": "comment: не более 255 символов.",
  "Data": null,
  "Pagination": null
}

Описание полей ответа

Поле Тип Описание
idintegerID отменённой записи
statusintegerВсегда 0 — запись отменена
calling_resstring|nullПричина отмены (до 255 символов). null, если не передавалась.
commentstring|nullКомментарий (до 255 символов). null, если не передавался.
cancelled_atstringДата-время отмены (YYYY-MM-DD HH:MM:SS, Asia/Almaty UTC+5). При повторной отмене — дата первой отмены.

Правила и ограничения

  • Soft delete — запись не удаляется физически, устанавливается rec_status = 0. Слот освобождается для новых записей.
  • Идемпотентность — повторный DELETE на уже отменённую запись возвращает 200 IsSuccess: true (без ошибки), с той же датой отмены.
  • Причина отмены — calling_res (строка, до 255 символов). Если не передан — calling_res не изменяется.
  • Комментарий — comment (строка, до 255 символов). Если не передан — comment не изменяется.
  • Неизменяемость при повторной отмене — при повторном DELETE calling_res и comment не перезаписываются.

Поля rec_status = 0, calling_res, comment, last_update_time обновляются автоматически.


21.3 Перенос записи на приём (/appointments/{id})

Изменяет день, время, мастера и состав услуг существующей активной записи. Пациент (cl_id) и филиал (branch_id) не меняются — филиал записи проверяется на принадлежность подписчику.

Логика совпадает с МИС: пересчёт длительности и стоимости, проверка окна мастера (TFJR) и пересечений, сериализация через GET_LOCK, сдвиг уведомлений, актуализация услуг и запись в journalDataLog (operation_type = 15).

21.3.1. Перенос записи

PATCH /appointments/{id}

Тело запроса — application/json (или application/x-www-form-urlencoded). id записи берётся из URL.

Параметры записи (обязательные)
ПолеТипОписание
daystringНовый день записи в формате YYYY-MM-DD.
time_fromstringНовое время начала в формате HH:MM.
master_idintegerID мастера. Должен оказывать выбранные услуги в филиале записи.
service_idsstringCSV ID услуг (например 3517,3687). Полный новый состав услуг записи.

Пациент и филиал не передаются

Пример запроса:

PATCH /api/appointments/26
Authorization: <ваш токен>
Content-Type: application/json

{
  "day": "2026-10-29",
  "time_from": "15:00",
  "master_id": 243,
  "service_ids": "10"
}

Пример успешного ответа (200 OK):

{
  "IsSuccess": true,
  "Error": null,
  "Data": {
    "id": 26,
    "day": "2026-10-29",
    "time_from": "15:00",
    "time_to": "15:05",
    "master_id": 243,
    "patient_id": 21674,
    "duration": 300,
    "total_cost": 2500,
    "updated_at": "2026-10-28 12:34:56",
    "old": {
      "day": "2026-10-28",
      "time_from": "12:00",
      "master_id": 222
    }
  },
  "Pagination": null
}

Пример ответа (запись отменена):

{
  "IsSuccess": false,
  "Error": "Запись отменена, перенос невозможен.",
  "Data": null,
  "Pagination": null
}

Пример ответа (нет подходящего окна):

{
  "IsSuccess": false,
  "Error": "Выбранное время недоступно (нет подходящего окна).",
  "Data": null,
  "Pagination": null
}

Пример ответа (время занято):

{
  "IsSuccess": false,
  "Error": "Выбранное время уже занято. Выберите другое.",
  "Data": null,
  "Pagination": null
}

Пример ответа (мастер не оказывает услугу):

{
  "IsSuccess": false,
  "Error": "Одна или несколько услуг недоступны для выбранного мастера/филиала.",
  "Data": null,
  "Pagination": null
}

Пример ответа (сервис занят, GET_LOCK):

{
  "IsSuccess": false,
  "Error": "Сервис занят, попробуйте позже.",
  "Data": null,
  "Pagination": null
}

Пример ответа (запись не найдена):

{
  "IsSuccess": false,
  "Error": "Запись с ID [26] не найдена или нет прав на её просмотр.",
  "Data": null,
  "Pagination": null
}

Описание полей ответа

ПолеТипОписание
idintegerID записи в журнале
daystringНовый день записи (YYYY-MM-DD)
time_fromstringНовое время начала (HH:MM)
time_tostringНовое время окончания (HH:MM)
master_idintegerID мастера
patient_idintegerID пациента
durationintegerОбщая длительность услуг (секунды)
total_costintegerСумма по услугам (целые)
updated_atstringlast_update_time записи после COMMIT
oldobjectПрежние значения: day, time_from, master_id

Правила и ограничения

  • Запись должна быть активна — при rec_status = 0 возвращается ошибка «Запись отменена, перенос невозможен».
  • Слот должен быть свободен — проверяется по /bookingavailability Время [time_from, time_from + duration] должно полностью попадать в свободное окно мастера.
  • Мастер должен работать в это время (worktime).
  • Пересечения с другими активными записями запрещены; собственная запись исключается.
  • Параллельные запросы на одного мастера и день сериализуются через GET_LOCK('appointment_<master>_<day>', 3). При занятости — IsSuccess: false.
  • Услуги — мастер должен оказывать все выбранные услуги, услуги онлайн.

22. Отзывы (/reviews)

Возвращает список отзывов клиентов о мастерах филиала.

22.1. Получение списка отзывов (Офсетная пагинация)

GET /reviews

ПараметрТипОписание
idintegerID отзыва
master_idintegerID мастера
client_idintegerID клиента
branch_idintegerID филиала
starsintegerОценка (1–5)
statusinteger0 — скрыт, 1 — активен
client_namestringПоиск по имени клиента (подстрока)
reviewstringПоиск по тексту отзыва (подстрока)
day_addedintegerДень добавления (timestamp)
date_added_fromstringДата добавления от (>=)
date_added_tostringДата добавления до (<=)
pageintegerНомер страницы. От 1 до 1000. По умолчанию 1.
limitintegerКоличество записей. От 1 до 100. По умолчанию 50.

Пример успешного ответа (200 OK):

{
  "IsSuccess": true,
  "Error": null,
  "Data": [
    {
      "id": 501,
      "master_id": 222,
      "day_added": 1793214000,
      "date_added": "2026-10-27 14:30:00",
      "client_id": 123,
      "client_name": "Иванов Иван",
      "review": "Отличный врач, всё объяснил",
      "answer": null,
      "stars": 5,
      "status": 1,
      "branch_id": 1
    }
  ],
  "Pagination": { "TotalCount": 1, "Page": 1, "Limit": 50, "TotalPages": 1 }
}

22.2. Получение отзыва по ID

GET /reviews/{id}

Пример ответа (404 Not Found):

{
  "IsSuccess": false,
  "Error": "Отзыв с ID [999] не найден или у вас нет прав на его просмотр.",
  "Data": null,
  "Pagination": null
}

Описание полей ответа

ПолеТипОписание
idintegerID отзыва
master_idintegerID мастера
day_addedintegerДень добавления (unix timestamp)
date_addedstringДата-время добавления
client_idintegerID клиента
client_namestringИмя клиента
reviewstringТекст отзыва
answerstring|nullОтвет мастера/клиники
starsintegerОценка (1–5)
statusinteger0 — скрыт, 1 — активен
branch_idintegerID филиала