External API: получение информации о сотрудниках
Этот endpoint External API позволяет получать данные о сотрудниках и их текущем статусе из ваших систем — HR-софта, дашбордов, ресепшн- и СБ-инструментов. Возвращает профиль сотрудника, график работы, контакты, закреплённые столы и признак «сейчас в офисе».
Аутентификация
Создайте API-подключение «Запрос данных по пользователям» в разделе Настройка > Интеграции > Настройки API и скопируйте токен (доступно ролям Владелец и Администратор интеграций). Передавайте его в каждом запросе:
Authorization: Bearer <token>Запросы без действительного токена возвращают 401. При превышении лимита — 429 с заголовком Retry-After.
Получение пользователей — GET /api/external/v1/users
Возвращает страницу пользователей или находит одного по идентификатору. Передавайте не более одного из email, externalId, employeeId — их сочетание вернёт 400.
| Параметр запроса | Тип | Описание |
|---|---|---|
email | string | Поиск по точному совпадению почты |
externalId | string | Поиск по внешнему ID, назначенному при синхронизации |
employeeId | string | Поиск по табельному номеру |
limit | integer | Размер страницы. По умолчанию 20, максимум 100. |
offset | integer | Сколько записей пропустить. По умолчанию 0. |
Примеры запросов
curl -H "Authorization: Bearer $TOKEN" \
"https://acme.unspot.ru/api/external/v1/users?limit=100&offset=0"
curl -H "Authorization: Bearer $TOKEN" \
"https://acme.unspot.ru/api/external/v1/users?email=ivan.petrov@example.com"
curl -H "Authorization: Bearer $TOKEN" \
"https://acme.unspot.ru/api/external/v1/users?employeeId=A-7788"Пример ответа — 200
{
"message": "OK",
"body": {
"items": [
{
"firstName": "Иван",
"lastName": "Петров",
"position": "Разработчик",
"department": "Отдел разработки",
"manager": "Сидоров Алексей",
"externalId": "8f1c-...",
"workSchedule": {
"workingHours": "09:00-18:00",
"assignedOffice": "Москва",
"workMode": "hybrid"
},
"contacts": {
"email": "ivan.petrov@example.com",
"phone": "+7 (900) 123-45-67",
"messenger": "Telegram: @ivanpetrov"
},
"assignedDesks": [
{ "name": "12, HS Liana", "days": ["We", "Th"] }
],
"status": {
"inOfficeNow": true,
"schedule": {
"todayStatus": "in office",
"extraStatus": null,
"placeName": "Рабочее место A-12",
"startTime": "2026-07-09T09:00:00Z",
"endTime": "2026-07-09T18:00:00Z"
}
}
}
]
}
}| Поле ответа | Описание |
|---|---|
firstName / lastName / position | Профиль сотрудника |
department | Подразделение из оргструктуры |
manager | ФИО руководителя |
externalId | Внешний ID из синхронизации (null, если не задан) |
workSchedule | workingHours, assignedOffice, workMode (office / remote / hybrid) |
contacts | email, phone, messenger |
assignedDesks | Закреплённые столы: name (стол, этаж, офис) и days (Mo–Fr) |
status.inOfficeNow | true, если сотрудник сейчас в офисе |
status.schedule | Расписание на сегодня: todayStatus (in office / remote / not working / null), extraStatus, placeName, startTime, endTime |
Ошибки и лимиты
- 400 — передано больше одного из
email/externalId/employeeId. - 401 — отсутствующий или неверный токен.
- 429 — чаще одного запроса в 10 секунд на рабочее пространство; дождитесь
Retry-After.
Ошибки возвращаются в формате {"message": "...", "errors": []}.
