External API: получение информации о сотрудниках

Этот endpoint External API позволяет получать данные о сотрудниках и их текущем статусе из ваших систем — HR-софта, дашбордов, ресепшн- и СБ-инструментов. Возвращает профиль сотрудника, график работы, контакты, закреплённые столы и признак «сейчас в офисе».

Аутентификация

Создайте API-подключение типа Users в разделе Администрирование > Интеграции > External API и скопируйте токен (доступно ролям Владелец и Администратор интеграций). Передавайте его в каждом запросе:

Authorization: Bearer <token>

Запросы без действительного токена возвращают 401. При превышении лимита — 429 с заголовком Retry-After.

Получение пользователей — GET /api/external/v1/users

Возвращает страницу пользователей или находит одного по идентификатору. Передавайте не более одного из email, externalId, employeeId — их сочетание вернёт 400.

Примеры запросов

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"
          }
        }
      }
    ]
  }
}

Ошибки и лимиты

• 400 — передано больше одного из email / externalId / employeeId.
• 401 — отсутствующий или неверный токен.
• 429 — чаще одного запроса в 10 секунд на рабочее пространство; дождитесь Retry-After.

Ошибки возвращаются в формате {"message": "...", "errors": []}.