Кастомные таблицы

Кастомные таблицы - это пользовательские таблицы организации, которые можно создавать в интерфейсе Skailer. Примеры: «Бонусы начисленные», «Бонусы выплаченные», «Реквизиты выплат» и т.п. API позволяет прочитать конфигурацию таблиц и выгрузить из них строки с фильтрацией.

Получить список кастомных таблиц

GET /api/v1/custom-fields/tables

Возвращает все кастомные таблицы организации для сотрудников.

Поля ответа (каждая таблица):

Поле	Тип	Описание
id	integer	ID таблицы
slug	string	Уникальный slug таблицы
title	string	Название таблицы
table_type	string	Тип таблицы (см. ниже)
is_historical	boolean	Является ли таблица исторической
table_fields	array	Список полей таблицы

Типы таблиц (table_type):

Значение	Описание
custom	Пользовательская кастомная таблица
employee_positions	Системная таблица позиций
employee_employments	Системная таблица трудоустройств
employee_compensations	Системная таблица компенсаций
employee_additional_compensations	Системная таблица доп. компенсаций

Поля каждого поля таблицы (table_fields):

Поле	Тип	Описание
id	integer	ID поля
slug	string	Slug поля (используется в cells при записи)
title	string	Название поля
field_type	string	Тип значения: text, number, date, datetime, select, switch, employee_reference и др.
options	array	Опции для полей типа select
is_mandatory	boolean	Обязательность
is_archived	boolean	Архивировано ли поле

Пример ответа:

[
  {
    "id": 15,
    "slug": "accrued_bonuses",
    "title": "Бонусы начисленные",
    "table_type": "custom",
    "is_historical": true,
    "table_fields": [
      {
        "id": 101,
        "slug": "bonus_amount",
        "title": "Сумма",
        "field_type": "number",
        "options": []
      },
      {
        "id": 102,
        "slug": "bonus_currency",
        "title": "Валюта",
        "field_type": "select",
        "options": [
          { "id": 1, "title": "RUB" },
          { "id": 2, "title": "USD" }
        ]
      }
    ]
  }
]

---

Поиск строк в кастомной таблице

POST /api/v1/custom-fields/tables/{table_id}/rows/search

Поиск и выгрузка строк из указанной таблицы. Поддерживает фильтрацию, пагинацию и сортировку.

Параметры запроса:

Поле	Тип	Описание
page_number	integer	Номер страницы (по умолчанию 1)
employee_ids	array[integer]	Фильтр по сотрудникам
position_ids	array[integer]	Фильтр по должностям
department_ids	array[integer]	Фильтр по отделам
division_ids	array[integer]	Фильтр по дивизионам
location_ids	array[integer]	Фильтр по локациям
employee_lifecycle_statuses	array[string]	Статусы: hired, employed, terminated, on_leave, on_parental_leave
date_effective_from	string (date)	Строки с датой начала не раньше этой даты
date_effective_to	string (date)	Строки с датой начала не позже этой даты
field_filters	array	Произвольные фильтры по значениям полей таблицы
sorting	object	Сортировка
text	string	Текстовый поиск

Поля ответа (каждая строка):

Поле	Тип	Описание
id	integer	ID строки
employee_id	integer	ID сотрудника
date_effective_from	string	Дата начала действия строки
is_current	boolean	Является ли строка текущей
cells	array	Заполненные ячейки с их значениями и конфигурацией

Пример запроса - выгрузка бонусов за квартал:

{
  "page_number": 1,
  "date_effective_from": "2024-01-01",
  "date_effective_to": "2024-03-31",
  "employee_lifecycle_statuses": ["employed"]
}

---

Типичный сценарий интеграции

Задача: выгрузить начисленные бонусы сотрудников за период для payroll-системы.

1. Получить список таблиц:

   GET /api/v1/custom-fields/tables

   Найти таблицу с нужным slug, запомнить её id и id нужных полей.

2. Выгрузить строки за период:

   POST /api/v1/custom-fields/tables/{table_id}/rows/search

   С фильтром date_effective_from / date_effective_to.

3. Использовать slug поля из конфигурации, чтобы интерпретировать значения в cells.

Совет: конфигурацию таблиц (шаг 1) можно кешировать - она меняется редко. Строки (шаг 2) запрашивайте при каждой синхронизации.

---

Запись строк в таблицы

Для добавления, обновления и удаления строк в таблицах конкретного сотрудника используйте методы, описанные в разделе Сотрудники → Строки в кастомных таблицах.