Методы API. Исполнители и записи

Обновлено: 06.10.2026 Автор: команда BOTFARM

Методы API для исполнителей и записей — команды, которыми связка Альбато без панели магазина ведёт исполнителей, их график и отсутствия, подтверждает, завершает, отменяет и переносит записи на услуги. Это третья часть справочника. Ниже — правила запросов, методы с примерами и ограничения токена.

Перед началом

Отправляйте запросы на адрес https://домен-магазина/api/v2/… с API-токеном в заголовке X-Service-Token. API-токен — секретный ключ, по которому магазин узнаёт связку и проверяет её права. Токен выпускают в разделе «Подключения» на вкладке «Альбато» и отмечают флажками нужные права — подробнее в статье «API-токены». Методам исполнителей нужны права группы «Точки и исполнители», методам записей — группы «Заказы и записи на услуги».

Тело запроса передаётся в формате JSON (текст из пар «поле — значение») с заголовком Content-Type: application/json. Магазин определяется по токену, storeId передавать не нужно. Если исполнителя или записи с указанным ID нет в магазине токена, API отвечает кодом 403, а не 404.

Время передавайте в формате ISO 8601 с часовым поясом: 2026-10-01T09:00:00Z или 2026-10-01T12:00:00+03:00. В адресе запроса знак + кодируйте как %2B, иначе время не распознается.

📘 Общие правила запросов и коды ответов описаны в статье «Методы API. Заказы и клиенты». Об изменениях исполнителей и записей магазин сообщает вебхуками: вебхук — автоматический запрос, который магазин отправляет на адрес из настроек, когда происходит событие. Поля событий описаны в статье «События вебхуков».

Связка — сценарий в Альбато. Заказы и клиенты описаны в первой части справочника «Методы API. Заказы и клиенты», товары и остатки — во второй, «Методы API. Товары и остатки».

Исполнители

Список исполнителей

GET /api/v2/admin/servicePerformers?limit=50

Права: «Точки и исполнители» → «Чтение».

id — ID одного исполнителя. Ответ — объект без обёртки.
enabled — true, чтобы получить только активных исполнителей, false — только выключенных.
goodId — исполнители, привязанные к услуге с этим ID.
search — часть имени, телефона или адреса почты.
externalId, externalSource — точное совпадение ID во внешней системе и её названия.
limit, offset — размер страницы и сдвиг. Без limit придут все исполнители.

{
  "count": 1,
  "rows": [
    {
      "id": 12,
      "fullName": "Анна Иванова",
      "phone": "+79990001122",
      "email": "anna@example.com",
      "timezone": "Europe/Moscow",
      "color": "#FF8800",
      "enabled": true,
      "sortOrder": 0,
      "externalId": "1c-000123",
      "externalSource": "1c",
      "createdAt": "2026-09-01T09:00:00.123456Z"
    }
  ]
}

Добавить исполнителя

POST /api/v2/admin/servicePerformers

Права: «Точки и исполнители» → «Создание».

fullName — имя исполнителя. Обязательное поле.
phone, email, bio — телефон, адрес электронной почты и описание.
timezone — часовой пояс в формате Europe/Moscow, по умолчанию московский. В нём задаётся график.
color — цвет в календаре записей: #RRGGBB.
enabled, sortOrder — активен ли исполнитель (по умолчанию true) и порядок в списках.
externalId, externalSource — ID во внешней системе и её название. Пара должна быть уникальной, повтор завершится ошибкой.

POST https://myshop.ru/api/v2/admin/servicePerformers
X-Service-Token: ваш_токен
Content-Type: application/json

{
  "fullName": "Анна Иванова",
  "phone": "+79990001122",
  "timezone": "Europe/Moscow",
  "externalId": "1c-000123",
  "externalSource": "1c"
}

Ответ — код 201 и созданный исполнитель, после него уходит событие «Новый исполнитель».

⚠️ Важно: клиенты не смогут записаться к новому исполнителю, пока его не привяжут к услугам и точкам. Привязка и загрузка фото выполняются только в панели, через API их сделать нельзя.

Изменить исполнителя

PUT /api/v2/admin/servicePerformers?id=12

Права: «Точки и исполнители» → «Редактирование».

Меняются только переданные поля, например {"phone": "+79990001133", "enabled": false}. Не передавайте null в timezone, enabled и sortOrder: такой запрос завершится ошибкой. Ответ — исполнитель с новыми значениями. Событие «Изменение исполнителя» уходит после каждого успешного вызова.

Удалить исполнителя

DELETE /api/v2/admin/servicePerformers?id=12

Права: «Точки и исполнители» → «Удаление».

Ответ: {"ok": true, "id": 12}. Исполнитель пропадает из свободного времени для записи, но уже созданные записи к нему не отменяются — перенесите или отмените их отдельно. После удаления уходит событие «Удаление исполнителя».

График работы

График — недельный шаблон: для каждого дня недели задаются интервалы работы по времени исполнителя. Дни обозначаются числами: 0 — воскресенье, 1 — понедельник и так далее до 6 — субботы. Перерыв на обед задаётся двумя интервалами в один день. Выходные и отпуска на конкретные даты оформляются отсутствиями.

Получить график

GET /api/v2/admin/servicePerformers/12/schedule

Права: «Точки и исполнители» → «Чтение».

{
  "performerId": 12,
  "schedule": [
    {"dayOfWeek": 1, "intervals": [{"timeFrom": "09:00", "timeTo": "13:00"}, {"timeFrom": "14:00", "timeTo": "18:00"}]},
    {"dayOfWeek": 2, "intervals": [{"timeFrom": "10:00", "timeTo": "16:00"}]}
  ]
}

Если связке удобнее плоский список, добавьте ?format=list: придёт {"count": …, "rows": […]}, где каждая строка — один интервал с полями dayOfWeek, timeFrom и timeTo.

Задать график

PUT /api/v2/admin/servicePerformers/12/schedule

Права: «Точки и исполнители» → «Редактирование».

PUT https://myshop.ru/api/v2/admin/servicePerformers/12/schedule
X-Service-Token: ваш_токен
Content-Type: application/json

{
  "schedule": [
    {"dayOfWeek": 1, "intervals": [{"timeFrom": "09:00", "timeTo": "13:00"}, {"timeFrom": "14:00", "timeTo": "18:00"}]},
    {"dayOfWeek": 3, "intervals": [{"timeFrom": "10:00", "timeTo": "16:00"}]}
  ]
}

Метод заменяет весь график. Дни, которых нет в запросе, станут нерабочими, а пустой список schedule удалит график целиком.
Время пишите с ведущим нулём: 09:00, а не 9:00. Конец интервала должен быть позже начала, поэтому работа через полночь не поддерживается. Максимум — 23:59.
Интервалы одного дня не должны пересекаться, иначе ответ 400 с текстом overlap.
Существующие записи не проверяются и не отменяются. Событий смена графика не создаёт.

Отсутствия исполнителя

Список отсутствий

GET /api/v2/admin/servicePerformers/12/absences?from=2026-10-01T00:00:00Z&to=2026-11-01T00:00:00Z

Права: «Точки и исполнители» → «Чтение».

Возвращает отсутствия, пересекающиеся с периодом, по возрастанию даты начала. Параметры from и to необязательны и принимают только дату со временем. Постраничного перебора нет.

Добавить отсутствие

POST /api/v2/admin/servicePerformers/12/absences

Права: «Точки и исполнители» → «Создание».

POST https://myshop.ru/api/v2/admin/servicePerformers/12/absences
X-Service-Token: ваш_токен
Content-Type: application/json

{
  "startAt": "2026-10-01T00:00:00+03:00",
  "endAt": "2026-10-08T00:00:00+03:00",
  "reason": "Отпуск"
}

Поля startAt и endAt обязательны, конец должен быть позже начала. Флажка «весь день» нет: чтобы закрыть целый день, укажите полночь этого дня и полночь следующего с часовым поясом исполнителя.

Если на это время у исполнителя есть записи на подтверждении или подтверждённые, отсутствие не создастся. Ответ — 409 со списком конфликтов:

{
  "error": "conflicts",
  "conflicts": [
    {"bookingId": 501, "startAt": "2026-10-02T07:00:00Z", "endAt": "2026-10-02T08:00:00Z", "status": "confirmed"}
  ]
}

Чтобы создать отсутствие и отменить эти записи, повторите запрос с параметром ?force=true. Записи получат статус «Отменено магазином», а по каждой записи уйдёт событие «Отмена записи». В ответе будет список отменённых записей cancelledBookingIds. Записи, которые ждут оплаты, конфликтом не считаются и не отменяются.

Ответ — код 201 и созданное отсутствие, затем уходит событие «Новое отсутствие исполнителя».

Удалить отсутствие

DELETE /api/v2/admin/servicePerformers/12/absences/41

Права: «Точки и исполнители» → «Удаление».

Ответ — код 200 и текст OK. Записи, отменённые при создании отсутствия, не восстанавливаются. После удаления уходит событие «Удаление отсутствия».

Записи на услуги

Запись создаёт клиент на витрине, отдельного метода создания записи в API нет. Через API записи получают, подтверждают, завершают, отменяют и переносят.

Статусы записи

pending_payment — ожидает оплаты: услуга требует предоплаты. Время держится за клиентом 20 минут.
pending_confirmation — на подтверждении: услуга требует подтверждения магазином.
confirmed — подтверждено.
completed — завершено, услуга оказана.
cancelled_by_client — отменено клиентом, в том числе при переносе.
cancelled_by_store — отменено магазином или автоматически, например из-за неоплаты.
no_show — клиент не пришёл.

Режим оказания — поле serviceMode: on_site — на точке, at_client — с выездом, online — онлайн, async — без фиксированного времени. У записей async нет времени начала и конца, вместо них срок dueBy.

Список записей

GET /api/v2/admin/serviceBookings

Права: «Заказы и записи на услуги» → «Чтение».

from, to — записи, пересекающиеся с периодом. Дата со временем или дата 2026-09-20, которая означает полночь по UTC. С этими параметрами записи async в выборку не попадают.
status — статусы через запятую, например pending_confirmation,confirmed.
performerId — записи одного исполнителя.
goodId — записи на одну услугу.
limit, offset — размер страницы, по умолчанию 100, максимум 500, и сдвиг.

Записи отсортированы по времени начала. Фильтров по точке, клиенту и дате изменения нет.

GET https://myshop.ru/api/v2/admin/serviceBookings?from=2026-09-20T00:00:00Z&to=2026-09-21T00:00:00Z&status=pending_confirmation,confirmed
X-Service-Token: ваш_токен

{
  "count": 1,
  "rows": [
    {
      "id": 501,
      "orderId": 9001,
      "goodId": 310,
      "goodCaption": "Стрижка",
      "performerId": 12,
      "performerName": "Анна Иванова",
      "serviceMode": "on_site",
      "status": "pending_confirmation",
      "startAt": "2026-09-20T07:00:00Z",
      "endAt": "2026-09-20T08:00:00Z",
      "dueBy": null,
      "locationId": 3,
      "venue": {"id": 3, "name": "Салон на Ленина", "address": "ул. Ленина, 1"},
      "clientId": 777,
      "clientNotes": "Позвоню заранее",
      "meetingUrl": "",
      "fullValue": 1500,
      "isPayment": false,
      "prepaidAmount": 0,
      "outstandingAmount": 1500,
      "createdAt": "2026-09-16T10:15:30.123456Z"
    }
  ]
}

Поле outstandingAmount — сколько клиенту осталось заплатить: сумма заказа минус предоплата. В записи есть и служебная заметка исполнителя performerNotes, которую клиент не видит.

Получить запись

GET /api/v2/admin/serviceBookings/501

Права: «Заказы и записи на услуги» → «Чтение».

Возвращает ту же запись, что и список, и добавляет контакты клиента: clientName, clientPhone и clientEmail. Это персональные данные: обязанности оператора лежат на владельце магазина — что учесть, описано в статье «Персональные данные», документы проверьте с юристом.

Подтвердить, завершить, отменить, отметить неявку

Команды отправляются запросом POST и отвечают записью с новым статусом. Права: «Заказы и записи на услуги» → «Создание заказов, отправка клиенту и действия с записями». Флажка «Редактирование» для них недостаточно.

POST /api/v2/admin/serviceBookings/501/confirm
POST /api/v2/admin/serviceBookings/501/complete
POST /api/v2/admin/serviceBookings/501/cancel
POST /api/v2/admin/serviceBookings/501/noShow

confirm — «На подтверждении» → «Подтверждено». Уходит событие «Подтверждение записи».
complete — «Подтверждено» → «Завершено». Уходит событие «Завершение записи».
cancel — любой незавершённый статус → «Отменено магазином». Время освобождается, уходит событие «Отмена записи». Причину можно передать в теле: {"reason": "Мастер заболел"}.
noShow — «Подтверждено» → «Не пришёл». Уходит событие «Неявка клиента».

Если переход из текущего статуса невозможен, например запись уже завершена, ответ — 409 invalid_transition. Запись в статусе «Ожидает оплаты» подтвердить нельзя, а отменить можно.

⚠️ Важно: отмена записи не отменяет заказ и не возвращает предоплату. Автоматически предоплата не возвращается: если клиент уже заплатил, оформите возврат в личном кабинете ЮKassa или Яндекс Пэй за вычетом фактически понесённых расходов (ст. 32 Закона РФ «О защите прав потребителей») или, с согласия клиента, зачтите оплату в другую услугу. Команда, отправленная связкой, вернётся в Альбато событием, поэтому не вызывайте отмену по событию «Отмена записи»: получится цикл.

Перенести запись или сменить исполнителя

PATCH /api/v2/admin/serviceBookings/501

Права: «Заказы и записи на услуги» → «Редактирование, статусы, оплата и доставка».

startAt — новое время начала. Должно быть в будущем и совпадать со свободным временем исполнителя. Время окончания рассчитается само.
performerId — новый исполнитель. Он должен быть активен и привязан к услуге и точке.
venueId — точка для услуг на точке, если у услуги их несколько.
dueBy — новый срок для записей без фиксированного времени, дата со временем: 2026-10-01T00:00:00Z.
meetingUrl — ссылка на встречу для онлайн-услуг, начинается с https:// или http://.
performerNotes — служебная заметка, которую клиент не видит.

PATCH https://myshop.ru/api/v2/admin/serviceBookings/501
X-Service-Token: ваш_токен
Content-Type: application/json

{
  "performerId": 14,
  "startAt": "2026-09-21T08:00:00Z",
  "performerNotes": "Перенос по звонку клиента"
}

⚠️ Важно: если в запросе нет meetingUrl или performerNotes, метод очистит эти поля. Перед изменением прочитайте запись и передайте текущие значения вместе с новыми.

Если выбранное время занято или не совпадает с сеткой записи, ответ — 409 slot_unavailable. Свободное время показывает публичный метод витрины, пример запроса ниже. Отправляйте его без заголовка X-Service-Token: с токеном публичный метод ответит 403.
Завершённые и отменённые записи менять нельзя: 409 booking can no longer be edited. У записи, которая ждёт оплаты, нельзя сменить исполнителя.
Метод не отправляет событий и не уведомляет клиента. Сообщите клиенту о переносе сами.

GET https://myshop.ru/api/v2/services/slots?goodId=310&performerId=14&date=2026-09-21&days=1

Ссылка на онлайн-встречу

PATCH /api/v2/admin/serviceBookings/501/meetingUrl

Права: «Заказы и записи на услуги» → «Редактирование, статусы, оплата и доставка».

Меняет только ссылку: {"meetingUrl": "https://meet.example.com/abc"}. Пустая строка удаляет ссылку. Ответ — запись с новой ссылкой. Событий и уведомлений клиенту нет.

Что по токену недоступно

Эти действия выполняются только в панели, API ответит 403 service token is not allowed on this route:

создание записи от имени магазина;
фото исполнителя, привязка исполнителей к услугам и точкам;
управление точками обслуживания.

Короткие ответы

Почему команда подтверждения записи возвращает 403?

У токена нет нужного флажка: подтверждение, завершение, отмена и неявка относятся к флажку «Создание заказов, отправка клиенту и действия с записями» группы «Заказы и записи на услуги». Если у токена отмечено только «Редактирование», в ответе будет requiredCapability, например bookings.bookings.confirm. Выпустите токен с нужным флажком.

Как закрыть день исполнителю и отменить записи на него?

Добавьте исполнителю отсутствие с параметром ?force=true: в startAt укажите полночь этого дня, в endAt — полночь следующего. Магазин создаст отсутствие, отменит пересекающиеся подтверждённые записи и записи на подтверждении, а по каждой записи отправит событие отмены.

Как узнать о переносе записи сотрудником?

Через вебхуки — никак: перенос в панели или через API событий не создаёт, событие «Перенос записи» приходит только когда запись переносит клиент. Если связке нужно актуальное время, периодически запрашивайте записи на ближайшие дни методом списка с параметрами from и to.

Возвращает ли отмена записи через API предоплату клиенту?

Нет, команда cancel не отменяет заказ и не возвращает предоплату. Возврат оформите в личном кабинете ЮKassa или Яндекс Пэй за вычетом фактически понесённых расходов (ст. 32 Закона РФ «О защите прав потребителей») или, с согласия клиента, зачтите оплату в другую услугу.