Для разработчиков

API Floowa

REST API на JSON, личные API-токены и подписанные вебхуки. Справочник открыт для всех; чтобы попробовать, нужен аккаунт Floowa.

Открыть справочник API Обзор интеграций

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

Администратор создаёт токен в разделе Настройки → Доступ к API, выбирает права по функциям и срок действия (30, 90 или 365 дней либо бессрочно). Токен показывается только один раз.

Authorization: Bearer <token>
Accept: application/json

Базовый URL: https://www.floowa.de/api/v1

  • Каждый запрос выполняется в компании владельца токена и никогда не может больше, чем позволяют токен и собственные права владельца.
  • API входит во все тарифы; методы подключённых модулей доступны, как только модуль активен.
  • Сообщения об ошибках приходят на языке заголовка Accept-Language (иначе на английском).

Ограничения и поведение

Лимит запросов 120 запросов в минуту на токен; сверх этого API отвечает HTTP 429.
Списки Списки выдаются постранично; через per_page можно получить до 100 записей на страницу.
Безопасный повтор С заголовком Idempotency-Key повторный запрос в течение 24 часов возвращает тот же ответ, а не создаёт дубликат.
Версия API Каждый ответ содержит заголовок Floowa-Api-Revision с датой последнего изменения API.

Вебхуки и подпись

Каждая доставка – это POST с JSON на ваш HTTPS-адрес с заголовками X-Floowa-Event, X-Floowa-Delivery и X-Floowa-Signature.

Подпись имеет вид t=<метка времени>,v1=<подпись>. v1 – это HMAC-SHA256 от «<метка времени>.<исходное тело>» с вашим ключом подписи. Сравнивайте за постоянное время и отбрасывайте старые метки времени.

Если ваш сервер не отвечает статусом 2xx, Floowa повторяет попытку через 1, 5 и 30 минут и через 2 часа. После 20 неудачных попыток подряд вебхук отключается.

Пример доставки

{
    "id": "8f2c3a1e-5b7d-4c1a-9e2f-0a1b2c3d4e5f",
    "event": "absence.requested",
    "created_at": "2026-10-28T09:15:00+01:00",
    "data": {
        "id": "01a1…",
        "employee_id": "01a0…",
        "absence_type_id": "01a0…",
        "start_date": "2026-11-02",
        "end_date": "2026-11-06",
        "half_day_start": false,
        "half_day_end": false,
        "days": 5,
        "status": "pending"
    }
}

Проверка подписи (PHP)

$header = $_SERVER["HTTP_X_FLOOWA_SIGNATURE"] ?? "";
parse_str(str_replace(",", "&", $header), $parts);
$body = file_get_contents("php://input");
$expected = hash_hmac("sha256", $parts["t"] . "." . $body, $secret);

if (! hash_equals($expected, $parts["v1"] ?? "") || abs(time() - (int) $parts["t"]) > 300) {
    http_response_code(400);
    exit;
}

Все события простыми словами

Событие Когда Техническое имя
Сотрудник создан Сотрудник создаётся – вручную, импортом или через API. employee.created
Сотрудник изменён Меняются учётные данные сотрудника. employee.updated
Сотрудник удалён Сотрудник удаляется. employee.deleted
Отсутствие запрошено Кто-то подаёт заявку на отпуск или другое отсутствие. absence.requested
Отсутствие одобрено Заявка одобряется или отсутствие вносится напрямую. absence.approved
Отсутствие отклонено Заявка отклоняется. absence.rejected
Отсутствие отменено Заявка или отсутствие отзывается. absence.cancelled
Время записано Появляется запись времени – при отметке прихода, при внесении задним числом или на терминале. time_entry.created
Время изменено Запись времени меняется, например при отметке ухода. time_entry.updated
Время удалено Запись времени удаляется. time_entry.deleted
Месяц закрыт Месяц закрывается в подготовке зарплаты. payroll.closed
Месяц открыт снова Закрытый месяц снова открывается для исправлений. payroll.reopened
Смена опубликована Смена публикуется вместе с графиком. shift.published
Смена изменена Опубликованная смена меняется. shift.changed
Смена отменена Опубликованная смена удаляется. shift.deleted

Журнал изменений

Все изменения API с датой и пометкой о несовместимых изменениях. В машиночитаемом виде – GET /api/v1/changelog.

2026-11-02 · 2 ноября 2026 г.

  • Новое Настройки нормы времени у сотрудников: ответы содержат effective_weekly_hours (собственные часы в неделю или стандарт компании; null без фиксированной нормы), no_fixed_hours (без фиксированной нормы, например руководство или доверительный рабочий график) и working_time_law_exempt (без проверок закона о рабочем времени, например директора GmbH или руководящие сотрудники). POST и PUT принимают необязательные поля no_fixed_hours и working_time_law_exempt; новый employment_type managing_director (руководство). weekly_hours не изменился. GET /employeesGET /employees/{id}POST /employeesPUT /employees/{id}

2026-10-30 · 30 октября 2026 г.

  • Новое Проверки инвентаря и квалификации, требуемые инвентарём: GET /qualifications возвращает required_inventory_category_ids и новую категорию check (без документа); GET /employees/{id}/qualifications возвращает requirement_reasons (почему квалификация обязательна – подразделение или выданный предмет); GET /inventory-items/{id} содержит inspections с due_on, last_done_on и status (ok, due_soon, overdue). GET /qualificationsGET /employees/{id}/qualificationsGET /inventory-items/{id}
  • Новое Отсутствия: POST /absences/{id}/cancel принимает необязательный reason и отменяет также одобренные отсутствия; ответы содержат cancel_requested_at (открытый запрос сотрудника на отмену) и cancel_reason. POST /absences/{id}/decision решает запрос на отмену (approve = отменить, reject = оставить отсутствие). POST /absences/{id}/cancelGET /absences
  • Изменено Названия проектов должны быть уникальны только в пределах клиента; одинаковое название допустимо у разных клиентов. Проекты без клиента остаются уникальными между собой. POST /time-projectsPUT /time-projects/{id}

2026-10-29 · 29 октября 2026 г.

  • Новое Проектное время по записи: записи принимают customer_id (клиент без проекта) и parts (распределение на несколько проектов/клиентов с minutes или start/end); GET /time-allocations возвращает customer_id, label, started_at/ended_at и kind part, фильтр customer_id. POST /time-entriesPUT /time-entries/{id}GET /time-allocations
  • Новое Подразделения: clock_web и clock_app (true/false, null = как у вышестоящего) определяют, могут ли сотрудники подразделения отмечаться в браузере или приложении. GET /org-unitsPOST /org-unitsPUT /org-units/{id}
  • Удалено несовместимое изменение Свободное распределение по дню PUT /employees/{id}/time-allocations/{date} удалено – передавайте распределение через parts в записи. Существующие свободные распределения привязаны к самой длинной записи дня. PUT /employees/{id}/time-allocations/{date}

2026-10-28 · 28 октября 2026 г.

  • Новое Время по проектам отдельно от присутствия: GET /time-allocations показывает, какому проекту отнесено время дня; PUT /employees/{id}/time-allocations/{date} задаёт свободное распределение дня. time_project_id у записей сохраняется и автоматически создаёт связанное распределение. GET /time-allocationsPUT /employees/{id}/time-allocations/{date}

2026-10-26 · 26 октября 2026 г.

  • Новое Подготовка зарплаты: новый объект surcharges_3b по каждому сотруднику с минутами надбавок по § 3b EStG (night_25, night_40, sunday_50, holiday_125, holiday_150). Поля night и holiday остаются как итоговые суммы. GET /payroll/{month}
  • Изменено несовместимое изменение Подготовка зарплаты: sunday больше не учитывает праздники, но включает 0–4 часа понедельника после смены, начатой в воскресенье. holiday дополнительно включает 24 и 31 декабря с 14 часов. Перерывы вычитаются пропорционально. GET /payroll/{month}
  • Конфиденциальность/безопасность несовместимое изменение Отсутствия: пользователи только с правом чтения видят конфиденциальные типы отсутствия (например, болезнь) как нейтральное отсутствие – absence_type_id, type, note и decision_note равны null, новое поле type_hidden равно true. Отчёт по зарплате объединяет такие дни в столбце type_hidden. GET /absencesGET /reports/payroll
  • Новое Новый эндпоинт GET /changelog и заголовок Floowa-Api-Revision в каждом ответе. GET /changelog

2026-10-23 · 23 октября 2026 г.

  • Новое Первая версия API v1: организация, персонал, документы, квалификации, инвентарь, расчётные листы, учёт времени с табелем и утверждением, проекты и клиенты, отсутствия, праздники, отчёты, подготовка зарплаты, Idempotency-Key и вебхуки.

Давайте начнём. Добро пожаловать в Floowa.

Попробовать 30 дней бесплатно