External API: получение истории бронирований
External API позволяет выгружать данные о бронированиях из UnSpot в ваши системы — BI-дашборды, facility management, расчёт зарплат или СБ. Эта страница описывает endpoint бронирований.
Аутентификация
Создайте API-подключение типа Bookings в разделе Администрирование > Интеграции > External API и скопируйте токен (доступно ролям Владелец и Администратор интеграций). Передавайте его в каждом запросе:
Authorization: Bearer <token>Запросы без действительного токена возвращают 401. При превышении лимита запросов API возвращает 429 с заголовком Retry-After.
Получение бронирований — GET /api/external/v1/bookings
Возвращает бронирования одного типа (столы, парковка или переговорные), у которых время начала попадает в запрошенный период. Сортировка по времени начала, новые сверху.
| Параметр запроса | Тип | Обязателен | Описание |
|---|---|---|---|
bookingType | string | да | DESK, PARKING или MEETING_ROOM |
startDate | integer | да | Unix timestamp (секунды). Бронирования, начинающиеся после этого момента. |
endDate | integer | да | Unix timestamp (секунды). Бронирования, начинающиеся до этого момента. Диапазон не более 92 дней. |
Пример запроса
curl -H "Authorization: Bearer $TOKEN" \
"https://acme.unspot.ru/api/external/v1/bookings?bookingType=DESK&startDate=1751328000&endDate=1751932800"Пример ответа — 200
{
"message": "OK",
"body": {
"items": [
{
"bookingStart": "2026-07-01 09:00:00",
"bookingEnd": "2026-07-01 18:00:00",
"duration": "09:00:00",
"bookingOffice": "Штаб-квартира Москва",
"ownerName": "Анна Иванова",
"ownerEmail": "anna.ivanova@example.com",
"ownerDepartment": "Engineering",
"bookingPlace": "Стол 4.12",
"guestName": null
}
]
}
}| Поле ответа | Описание |
|---|---|
bookingStart / bookingEnd | Период бронирования, Y-m-d H:i:s |
duration | Длительность, HH:MM:SS |
bookingOffice | Название офиса |
ownerName / ownerEmail | Владелец бронирования. Для гостевых бронирований — имя и email гостя. |
ownerDepartment | Отдел владельца (null для гостей) |
bookingPlace | Название стола, парковочного места или переговорной |
guestName | Имя гостя для гостевых бронирований стола/парковки, иначе null |
Ошибки и лимиты
Все ответы External API обёрнуты в конверт {"message": ..., "body": ...}. Ошибки возвращаются в формате:
{ "message": "Date range cannot exceed 92 days", "errors": [] }- 400 —
bookingType must be one of: DESK, PARKING, MEETING_ROOM;startDate cannot be greater than endDate;Date range cannot exceed 92 days. - 401 — отсутствующий или неверный токен.
- 429 — чаще одного запроса в 10 секунд на рабочее пространство; дождитесь
Retry-After.
Совет: для выгрузки длинной истории перебирайте последовательные 92-дневные окна с интервалом 10 секунд между запросами.
