API для площадок и сайтов
Через него каталог записи или сайт организации получает список услуг, свободное время и создаёт записи. Тем же ключом пользуется наш виджет записи — отдельного «внутреннего» API у нас нет.
Версия v1. Адрес в путях мы не меняем: у площадки свой цикл выпуска, и переименование ручки означает у неё простой записи.
Ключ и области
Ключ выдаёт сама организация: «Настройки → Интеграции → Выдать ключ». Показывается он один раз — в базе лежит отпечаток, а не ключ. Предъявляется заголовком:
Authorization: Bearer ucrm_<ключ>Организация определяется ключом, а не адресом: один сервер площадки обслуживает сотни организаций и про поддомены знать не обязан. Базовый адрес при этом всё равно принадлежит организации:
https://<адрес-организации>.ucrm.by/api/v1/partnerУ ключа есть области. Пустой набор не пропускает ничего — это защита, а не недоразумение:
booking.read— читать услуги, специалистов и свободное время. Без этого каталог не покажет ваше свободное время.booking.write— создавать и отменять записи. Без этого посетитель каталога сможет только позвонить.reviews.read— читать опубликованные отзывы. Без этого ваши отзывы на площадке останутся её собственными.
Ручки
| Метод | Путь | Область | Зачем |
|---|---|---|---|
| GET | /org | booking.read | Карточка организации, версия API и выданные ключу области. Первый запрос при настройке |
| GET | /services | booking.read | Услуги с ценой и длительностью |
| GET | /branches | booking.read | Точки с адресами. Пусто — точка одна, шага выбора нет |
| GET | /staff?serviceId=… | booking.read | Специалисты под услугу. Пусто, если организация не показывает их наружу |
| GET | /slots?serviceId=…&date=… | booking.read | Свободное время. Только время — без имён и номеров мест |
| POST | /appointments | booking.write | Создать запись. В ответе — её идентификатор |
| DELETE | /appointments/:id | booking.write | Отменить свою запись. Чужая для ключа не существует — 404 |
| GET | /events | booking.read | Групповые занятия: название, время, цена и сколько мест свободно. Фамилий участников здесь нет — это публичная витрина |
| POST | /events/:id/signup | booking.write | Записать человека в группу: имя и телефон. Мест не осталось — ответ 409, а не молчаливая очередь |
| GET | /reviews | reviews.read | Опубликованные отзывы — те же, что на странице записи |
Проверить ключ:
curl -H "Authorization: Bearer ucrm_…" \
https://<адрес-организации>.ucrm.by/api/v1/partner/orgОграничения и отказы
- Тысяча обращений в час на ключ. Хватает на опрос свободного времени раз в минуту по десятку услуг. Лимит на ключ, а не на адрес: у площадки один сервер на всех.
- 401 — ключа нет, он не нашей формы, не найден или отозван. Различать эти случаи снаружи нельзя: иначе перебор ключей получает подсказку.
- 403 — ключ настоящий, но области не выдано. Здесь текст отказа называет область прямо: настраивать интеграцию будет человек, и «не хватает
booking.write» экономит ему день. - 403 на создании записи — у организации приостановлен доступ. Чтение при этом работает: каталог с устаревшим расписанием хуже каталога без записи.
- Отзыв ключа действует сразу. Организация нажимает «Отозвать» — следующий же запрос получает 401.
Чего в API нет
Клиентской базы. Ни списка, ни телефонов, ни истории визитов — ни в одной ручке. Это граница продукта, а не недоделка: ключ, дающий выгрузку базы, однажды утечёт, и объяснять это придётся владельцу организации, а не площадке.
Изменения чужих записей. Ключ отменяет только то, что создал сам. Без этого утёкший ключ означал бы не утечку расписания, а очищенное расписание, где каждая отмена выглядит законной.
Нужна интеграция, которой здесь нет, — напишите на support@ucrm.by. Если она нужна не только вам, мы сделаем её частью продукта, а не отдельной доработкой.
Организациям, которым нужна форма записи на своём сайте, а не интеграция, ключ не требуется вовсе: код вставки лежит в тех же «Настройках → Интеграции». Подробнее — на странице цен: он входит в подписку.