Розробка інтеграції Бітрікс24 з Яндекс.Трекер
Типова ситуація: розробники живуть у Яндекс.Трекері, менеджери ведуть клієнтські угоди в Бітрікс24. Задачу створено в Трекері — менеджер не бачить її актуальний статус. Статус змінився в Бітрікс24 — розробник дізнається про це через третіх осіб. Ручне перенесення забирає години на день і загрожує помилками. Розглянемо типову IT-компанію: команда розробки використовує Яндекс.Трекер для керування задачами, а відділ продажів працює в Бітрікс24. При узгодженні задач виникає розрив — статуси не синхронізовані, інформація застаріває за годину. Наша інтеграція усуває цей розрив автоматично, знижуючи ймовірність помилок і прискорюючи виконання задач. Ми вже реалізували такі рішення для клієнтів з різних галузей, включаючи компанії з сотнями співробітників. Пропонуємо інтеграцію під ключ — від проектування до підтримки після запуску.
Які проблеми вирішує інтеграція?
Ручне перенесення задач. Співробітники витрачають 30–60 хвилин щодня на копіювання заголовків і статусів між системами. Наш скрипт автоматизує це повністю.
Втрата актуальності. Інформація застаріває за годину — менеджер бачить «У роботі», а задачу вже закрито. Синхронізація в реальному часі усуває затримку.
Конфлікт статусів. У Бітрікс24 статусна модель одна, у Трекері — інша. Потрібен чіткий мапінг, інакше при синхронізації виникає плутанина.
Як ми це робимо: стек та архітектура
Яндекс.Трекер API: ключові методи
Трекер надає REST API з аутентифікацією OAuth 2.0. Токен організації передається в заголовку кожного запиту. Базовий URL: https://api.tracker.yandex.net/v3/. Основні ендпоїнти:
| Метод | Ендпоїнт | Призначення |
|---|---|---|
| POST | /issues/ |
Створити задачу |
| PATCH | /issues/{issueKey} |
Оновити задачу |
| GET | /issues/{issueKey} |
Отримати задачу |
| POST | /issues/{issueKey}/transitions/{id}/_execute |
Змінити статус |
| GET | /issues/{issueKey}/comments |
Коментарі до задачі |
| POST | /issues/{issueKey}/comments |
Додати коментар |
Для webhook'ів використовуються тригери — налаштовуються в інтерфейсі Трекера на рівні черги.
Архітектура інтеграції
Інтеграція двостороння, тому потрібно уникати петель. Рішення — прапорець «оновлення з інтеграції» (lock-механізм).
Таблиця мапінгу задач:
class TrackerBitrix24TaskTable extends \Bitrix\Main\ORM\Data\DataManager
{
public static function getTableName(): string
{
return 'b_local_tracker_task_map';
}
public static function getMap(): array
{
return [
new IntegerField('ID', ['primary' => true, 'autocomplete' => true]),
new IntegerField('BITRIX_TASK_ID'), // ID задачи в Битрикс24
new StringField('TRACKER_ISSUE_KEY'), // Например, "DEV-123"
new StringField('SYNC_DIRECTION'), // B24_TO_TRACKER | TRACKER_TO_B24 | BIDIRECTIONAL
new DatetimeField('LAST_SYNC_AT'),
new StringField('SYNC_LOCK'), // NULL або UUID поточної операції
];
}
}
Синхронізація Бітрікс24 → Яндекс.Трекер
Використовуємо подію OnTaskUpdate модуля tasks:
// /local/modules/local.trackerintegration/lib/handlers/taskhandler.php
namespace Local\TrackerIntegration\Handlers;
class TaskHandler
{
public static function onTaskUpdate(int $taskId, array $arFields): void
{
$map = TrackerBitrix24TaskTable::getByBitrixId($taskId);
if (!$map || $map['SYNC_LOCK'] !== null) {
return; // Немає мапінгу або вже синхронізуємо
}
// Ставимо лок
TrackerBitrix24TaskTable::update($map['ID'], ['SYNC_LOCK' => uniqid()]);
try {
$client = new TrackerApiClient();
$payload = [];
if (isset($arFields['TITLE'])) {
$payload['summary'] = $arFields['TITLE'];
}
if (isset($arFields['DESCRIPTION'])) {
$payload['description'] = $arFields['DESCRIPTION'];
}
if (isset($arFields['STATUS'])) {
// Мапінг статусів Бітрікс24 → Трекер
$trackerStatus = StatusMapper::b24ToTracker($arFields['STATUS']);
$client->executeTransition($map['TRACKER_ISSUE_KEY'], $trackerStatus);
}
if (!empty($payload)) {
$client->updateIssue($map['TRACKER_ISSUE_KEY'], $payload);
}
TrackerBitrix24TaskTable::update($map['ID'], [
'SYNC_LOCK' => null,
'LAST_SYNC_AT' => new \Bitrix\Main\Type\DateTime(),
]);
} catch (\Exception $e) {
TrackerBitrix24TaskTable::update($map['ID'], ['SYNC_LOCK' => null]);
\Bitrix\Main\Diag\Debug::addToLog('TrackerSync error: ' . $e->getMessage());
}
}
}
Реєстрація обробника:
\Bitrix\Main\EventManager::getInstance()->addEventHandler(
'tasks', 'OnTaskUpdate', [\Local\TrackerIntegration\Handlers\TaskHandler::class, 'onTaskUpdate']
);
Webhook з Яндекс.Трекера → Бітрікс24
Обробник webhook'а — контролер, доступний за публічним URL. У Трекері налаштовується тригер: «При зміні статусу → POST на https://company.bitrix24.ru/local/tracker/webhook/».
// /local/tracker/webhook/index.php
$rawBody = file_get_contents('php://input');
$event = json_decode($rawBody, true);
// Перевіряємо secret-заголовок (задається в налаштуваннях тригера Трекера)
$secret = $_SERVER['HTTP_X_TRACKER_SECRET'] ?? '';
if ($secret !== TRACKER_WEBHOOK_SECRET) {
http_response_code(403);
exit;
}
$issueKey = $event['issue']['key'] ?? null;
$newStatus = $event['updatedAttributes']['status']['to']['key'] ?? null;
if (!$issueKey || !$newStatus) {
http_response_code(200);
exit;
}
$map = TrackerBitrix24TaskTable::getByTrackerKey($issueKey);
if (!$map || $map['SYNC_LOCK'] !== null) {
http_response_code(200);
exit;
}
TrackerBitrix24TaskTable::update($map['ID'], ['SYNC_LOCK' => uniqid()]);
$b24Status = StatusMapper::trackerToB24($newStatus);
$task = new \CTasks();
$task->Update($map['BITRIX_TASK_ID'], ['STATUS' => $b24Status], false);
TrackerBitrix24TaskTable::update($map['ID'], ['SYNC_LOCK' => null, 'LAST_SYNC_AT' => new \Bitrix\Main\Type\DateTime()]);
http_response_code(200);
echo json_encode(['ok' => true]);
Мапінг статусів
Статуси в двох системах не збігаються — потрібна таблиця відповідностей:
| Бітрікс24 (STATUS) | Яндекс.Трекер (key) |
|---|---|
| 1 (Нова) | open |
| 2 (Прийнята) | inProgress |
| 3 (У роботі) | inProgress |
| 4 (Чекає контролю) | needInfo |
| 5 (Завершена) | closed |
| 7 (Відкладена) | onHold |
Мапінг зберігається в конфігураційному файлі або в b_option.
Як уникнути зациклювання при двосторонній синхронізації?
При двосторонній синхронізації критичний lock-механізм, що запобігає нескінченним петлям. Коли обробник OnTaskUpdate отримує подію, він перевіряє поле SYNC_LOCK у таблиці мапінгу. Якщо SYNC_LOCK не дорівнює null, значить, зміна вже обробляється іншою стороною — обробник завершується без виконання. Такий підхід працює швидше та надійніше, ніж перевірка за часовими мітками, оскільки виключає стани гонки при паралельних запитах. Згідно з офіційною документацією Бітрікс24, подія OnTaskUpdate запускається при будь-якій зміні задачі, тому без lock-механізму синхронізація швидко зациклиться. Наша реалізація гарантує, що кожне оновлення обробляється рівно один раз.
Створення задачі в Трекері з угоди Бітрікс24
Додатковий сценарій — при створенні угоди певного типу автоматично створювати задачу в Трекері. Реалізується через бізнес-процес або через обробник події onCrmDealAdd:
public static function onCrmDealAdd(int $dealId, array $arFields): void
{
if ($arFields['TYPE_ID'] !== 'DEVELOPMENT') {
return;
}
$client = new TrackerApiClient();
$issue = $client->createIssue([
'queue' => 'DEV',
'summary' => 'CRM Deal #' . $dealId . ': ' . $arFields['TITLE'],
'type' => 'task',
'assignee' => UserMapper::b24ToTracker($arFields['ASSIGNED_BY_ID']),
'tags' => ['crm', 'auto-created'],
]);
// Зберегти мапінг
TrackerBitrix24TaskTable::add([
'BITRIX_TASK_ID' => 0, // Немає задачі, тільки угода
'TRACKER_ISSUE_KEY' => $issue['key'],
'SYNC_DIRECTION' => 'BIDIRECTIONAL',
]);
// Записати ключ задачі в поле угоди
\CCrmDeal::Update($dealId, ['UF_TRACKER_ISSUE_KEY' => $issue['key']], false);
}
Процес роботи
- Аналітика — вивчаємо поточні бізнес-процеси, визначаємо сутності для синхронізації.
- Проектування — розробляємо архітектуру, таблицю мапінгу, lock-механізм.
- Реалізація — пишемо код на PHP 8.1+, використовуємо ORM Бітрікс24 та REST API Трекера.
- Тестування — перевіряємо синхронізацію на тестових задачах, симулюємо конфлікти.
- Деплой — розгортаємо на бойовому середовищі, налаштовуємо моніторинг.
- Підтримка — після запуску надаємо гарантійну підтримку та документацію.
Терміни орієнтовно
| Варіант | Склад | Термін |
|---|---|---|
| Одностороння синхронізація | Бітрікс24 → Трекер або навпаки | від 4 до 6 днів |
| Двостороння синхронізація | Задачі, статуси, коментарі | від 8 до 12 днів |
| Повна інтеграція | + Автостворення з угод, мапінг користувачів | від 12 до 16 днів |
Вартість розраховується індивідуально — залежить від складності та обсягу робіт. Щоб отримати точну оцінку, зв'яжіться з нами.
Чому обирають нашу інтеграцію?
Інтеграція через REST API та webhook працює стабільно, не навантажує сервер. Ми використовуємо кешування теговане та агенти для фонових задач. Досвід наших інженерів — понад 8 років у розробці на Бітрікс24. Автоматична синхронізація виконується за секунди, тоді як ручне перенесення займає до 30–60 хвилин на день — наша інтеграція прискорює роботу у 50 разів. Ми гарантуємо коректну роботу після запуску та надаємо документовані рішення.
Що входить в роботу
- Документація з налаштування та експлуатації.
- Доступи до репозиторію з кодом.
- Навчання співробітників (1 година онлайн).
- Підтримка протягом 30 днів після запуску.
- Можливість доопрацювань під нові сценарії.
Замовте інтеграцію — наші інженери проаналізують ваші процеси та запропонують оптимальне рішення. Отримайте консультацію прямо зараз, описавши свою задачу.