Skip to content

BITRIX24.md

Latest commit

 

History

History
92 lines (56 loc) · 6.75 KB

BITRIX24.md

File metadata and controls

92 lines (56 loc) · 6.75 KB
Raw

Работа с Bitrix24

Сервис использует входящий webhook Bitrix24 REST API. Реальный URL webhook не хранится в репозитории.

Webhook задаётся одним из способов:

  • переменная окружения BITRIX_WEBHOOK;
  • локальный файл config.local.php, который игнорируется git.

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

https://<portal>.bitrix24.ru/rest/<user-id>/<webhook-code>/

Транспорт

Все запросы выполняются POST-запросами с application/x-www-form-urlencoded.

Код использует curl, если расширение доступно, иначе fallback на file_get_contents() со stream context.

Если Bitrix возвращает QUERY_LIMIT_EXCEEDED, запрос повторяется с паузой. Массовые запросы идут через batch, по 50 команд в одном chunk.

Методы Bitrix24

tasks.task.list

Используется в четырёх местах:

  1. Отчёт «Закрытые часы» — фильтр по >=CLOSED_DATE, <=CLOSED_DATE (окно ±2 месяца) и REAL_STATUS = REPORT_CLOSED_STATUSES (по умолчанию только 5: «условно завершена» ждёт одобрения и в счёт не идёт).
  2. Доска «Задачи» — фильтр по RESPONSIBLE_ID (reportUserIds()) и REAL_STATUS:
    • вкладка «Активные задачи»: статусы 2 (ждёт выполнения), 3 (выполняется), 6 (отложена), без ограничения по датам;
    • вкладка «Закрытые задачи»: статусы 4/5, CLOSED_DATE внутри выбранного месяца.
  3. Проверка задач — CLOSED_DATE внутри месяца, статусы 4/5.
  4. KPI — CREATED_DATE внутри месяца, статусы 4/5, по всему порталу; группировка по CREATED_BY. Дополнительно выбираются DEADLINE, TAGS и DESCRIPTION.

Для доски дополнительно выбираются DEADLINE и GROUP_ID. Пагинация идёт через start, дополнительные страницы — через batch.

tasks.task.result.list

Используется для чтения результата завершённой задачи (отчёт и проверка задач). Главное правило: отчётный месяц определяется датой внутри результата задачи, а не датой закрытия задачи.

task.elapseditem.getlist

Используется для получения списанного времени по задаче (отчёт, проверка задач, KPI). Часы считаются только из MINUTES. Фильтр по пользователям не накладывается — берутся все списания по задаче, поэтому новые сотрудники попадают в отчёт автоматически.

user.get

Используется для отображения ФИО сотрудников по Bitrix user ID (отчёт и доска).

crm.company.list

Используется для получения названия компании по ID из UF_CRM_TASK (отчёт и карточки доски).

sonet_group.get

Необязательный метод. Используется доской «Задачи» для названий проектов (рабочих групп) по GROUP_ID. Названия сначала берутся из объекта group, который отдаёт сам tasks.task.list, — на большинстве порталов этого достаточно. Если у webhook нет права на соцсеть/рабочие группы и названия взять неоткуда, колонки получают имена Проект #<id>, доска продолжает работать.

Правила отчёта «Закрытые часы»

  1. Пользователь выбирает месяц и год.
  2. Сервис смотрит задачи, закрытые в окне ±2 месяца вокруг выбранного (REPORT_CLOSED_WINDOW_MONTHS): работы могли сдать сильно позже или раньше закрытия.
  3. Берутся только полностью завершённые задачи — REAL_STATUS 5 (REPORT_CLOSED_STATUSES). Статус 4 «условно завершена» ждёт одобрения и в отчёт не попадает.
  4. Для каждой задачи читается результат.
  5. В отчёт попадает только задача, где дата в результате находится в выбранном месяце.
  6. По попавшим задачам читаются списания времени.
  7. Время относится к тому сотруднику, кто списал время (USER_ID в elapsed item).
  8. Итоги суммируются по сотрудникам и по задачам.

Подробный разбор шагов, разбор дат в результате и формулы KPI — в README.

Дашборд

Дашборд не ходит в Bitrix при открытии страницы — он читает сохранённый снимок data/dashboard-YYYY-MM.json. Снимок пересоздаётся из свежего отчёта:

  • при каждой выгрузке Excel (report.php);
  • при каждом создании учётов времени в УНФ (unf_time.php);
  • вручную кнопкой «Обновить за этот месяц» (dashboard_refresh.php, POST).

Excel

Файл создаётся без сторонних PHP-библиотек, напрямую как .xlsx ZIP-пакет с XML-частями.

Листы идут в таком порядке:

  • Свод;
  • Все задачи — поля задачи заполняются в каждой строке, чтобы фильтры Excel работали по всем строкам списаний; задачи визуально отделяются рамками и чередующейся заливкой;
  • лист по каждому сотруднику.

1С:УНФ

Создание документов «Учет времени» и «Задание на работу» описано отдельно: docs/ODATA.md.