Перейти к содержимому

Обзор

API для скриптов и сторонних систем салона. Здесь только те ручки, которыми мы предлагаем пользоваться снаружи: работы и их разметка, визиты, мастера, статистика, выгрузка архивом.

Как войти

Токен выдаётся в кабинете (POST /api/v2/me/tokens) или оператором и ставится заголовком:

Authorization: Bearer pcat_…

Значение показывается один раз. Токеном нельзя выдать другой токен, сменить пароль или почту — такие ручки в эту схему не входят и отвечают 403.

Права и салоны

У токена есть объём — список салонов, где он работает, — и набор политик. На каждом запросе действует пересечение: политики токена ∩ права человека в салоне пути. Понизили человека в правах — токен сузился сразу; вернули — снова работает. Салон вне объёма отвечает так, будто его нет.

Порядок отказов

Код Когда
401 unauthenticated токена нет, он неизвестен, отозван или истёк
404 салон вне объёма токена, или членство в салоне выключено
423 salon_blocked салон заблокирован
402 salon_expired у салона кончился оплаченный срок
403 policy не хватает политики; её название — в теле ответа
422 validation тело или параметры не прошли схему; detail — массив, см. ниже
422 invalid запрос разобран, но так нельзя: detail — готовая фраза для человека
429 запросов слишком много — подождите и повторите

Ошибка всегда приходит объектом с полем reason — по нему и ветвитесь, а не по тексту.

У 422 две формы. validation — не прошла схема: detail массивом, у каждого элемента loc (где), msg (текст) и for_user. Показывайте msg тех элементов, где for_user: true — их писали для людей; у остальных текст сгенерирован и годится разве что в журнал. invalid — и всё прочее: detail строкой, готовой к показу.

Пределы

Ограничения частоты есть, и числа мы не публикуем: они меняются. Обычной работе они не мешают — запрашивайте данные по делу, а не опросом по кругу, и не отправляйте запросы пачками без пауз. Упёрлись — придёт 429: повторите позже, а не сразу. Поток запросов, который не унимается, может на время потерять доступ к API целиком.

Что мы обещаем

Эта схема — публичный контракт: поля в ответах мы добавляем, но не убираем и не переименовываем, ручки не исчезают без новой версии пути. Остальные ручки приложения контрактом не являются и меняются без предупреждения.

Токен автоматизации: Authorization: Bearer pcat_…

Security scheme type: http