Яндекс Трекер API: вебхуки, повторные запросы и синхронизация без дублей

Рабочая интеграция с Яндекс Трекером редко ограничивается созданием задачи по API. Через несколько недель появляются повторы, комментарии начинают ходить по кругу, статусы расходятся, а удалённая система не понимает, какая запись считается основной. Причина обычно находится в модели обмена, а не в одном запросе.

Надёжная схема разделяет два направления. CRM или внутренняя система создаёт и обновляет задачи через API Трекера. Изменения из Трекера уходят наружу через HTTP-запросы триггеров или контролируемый опрос. Между ними работает журнал соответствий и очередь событий.

Какие идентификаторы связывают две системы

Ключ задачи вида QUEUE-123 уникален внутри Трекера и подходит для обращений к API. Во внешней системе у записи есть собственный ID. Интеграция хранит пару идентификаторов и служебные данные: время последней синхронизации, версию, источник изменения и состояние обработки.

Одного поиска по заголовку недостаточно. Две заявки от одного клиента могут иметь одинаковую тему, а изменение текста разрушит связь. Внешний ID лучше хранить в отдельном поле задачи или в реестре интеграции, доступном транзакционно перед созданием новой задачи.

Почему повторный запрос нельзя считать исключением

Сеть может оборваться после того, как Трекер создал задачу, но до получения ответа интеграцией. Следующая попытка выглядит как новый запрос и создаёт дубль. Аналогичная ситуация возникает при повторной доставке события, ручном перезапуске очереди или истечении таймаута.

Обработчик строят идемпотентным: одно бизнес-событие имеет устойчивый ключ, а его повтор приводит к чтению уже сохранённого результата. До вызова API интеграция проверяет журнал, после успешного ответа атомарно сохраняет ключ задачи. Если ответ потерян, выполняется поиск по внешнему ID, а не слепое создание.

API, триггеры и вебхуки решают разные задачи

API Трекера позволяет получать и изменять задачи, очереди, комментарии и другие объекты. Запросы выполняются с OAuth- или IAM-токеном и идентификатором организации; права соответствуют пользователю, от имени которого работает интеграция [1].

Для передачи изменений из Трекера во внешнюю систему настраивают действие триггера с HTTP-запросом. Документация поддерживает методы GET, POST, PUT и DELETE, заголовки, JSON-тело и варианты авторизации [2]. Получатель должен быстро проверить запрос, поставить событие в свою очередь и вернуть успешный ответ. Тяжёлую обработку лучше выполнять асинхронно.

Защита от циклов комментариев и статусов

Если комментарий из CRM добавляется в Трекер, а каждый новый комментарий Трекера отправляется обратно в CRM, интеграция способна бесконечно копировать собственное сообщение. Для защиты сохраняют источник изменения и ID исходного события. Комментарии, созданные техническим пользователем интеграции с уже известным ID, повторно не экспортируют.

Для статусов заранее составляют таблицу соответствий. В одной системе может быть «На проверке», а в другой — только «В работе». Нужно решить, какое состояние является владельцем, допускается ли обратный переход и что делать со статусом, у которого нет аналога.

Очередь событий и повторные попытки

Полученное событие сначала сохраняют, затем обрабатывают. Повтор выполняют с увеличивающейся задержкой для временных ошибок сети и ответов 5xx. Ошибки доступа 401 и 403 требуют проверки токена и прав, а неверные данные 4xx отправляются в очередь разбора с понятным описанием.

После нескольких неудачных попыток событие не должно исчезать. Его переводят в отдельное состояние, уведомляют ответственного и оставляют возможность безопасного повторного запуска. В журнале нужны ID события, задача, направление обмена, попытка, код ответа и сокращённое сообщение об ошибке.

Что в этой схеме называют вебхуком

В разговоре исходящий HTTP-запрос из Трекера часто называют вебхуком. В интерфейсе и документации Яндекс Трекера это действие триггера или автодействия «HTTP-запрос». Триггер реагирует на изменение задачи, подставляет значения полей и обращается к заданному URL. Это важно для диагностики: искать историю доставки нужно в истории срабатывания автоматизации, а не в отдельном реестре вебхуков.

API решает обратную задачу: внешняя система сама обращается к Трекеру, чтобы прочитать или изменить объект. Поэтому двусторонняя интеграция обычно состоит из двух независимых каналов. Для каждого задают собственную очередь, права, журнал и правила повторов. Отказ исходящего запроса из Трекера не должен блокировать приём заявок из CRM, а недоступность API Трекера — уничтожать уже принятые внешние события.

Почему повторная доставка является штатным сценарием

Яндекс Трекер документирует повтор HTTP-запроса, если ответ не пришёл за 10 секунд либо получен код 500. Выполняется до пяти попыток с экспоненциальной задержкой, начиная с 10 секунд [5]. Следовательно, обработчик обязан выдерживать повтор одного и того же события даже при полностью исправной автоматизации.

Типичный дубль возникает так: получатель создаёт заказ или запись в CRM, но отвечает дольше 10 секунд. Трекер считает доставку неудачной и отправляет запрос ещё раз. Увеличение таймаута на стороне приложения проблему не решает. Получатель должен сначала проверить запрос, сохранить событие и вернуть ответ, а тяжёлую обработку выполнить из своей очереди.

Нельзя рассчитывать, что любой ответ 4xx или 5xx будет автоматически повторён одинаково. Документация прямо называет отсутствие ответа и код 500. Поэтому собственный шлюз должен сохранять неуспешные события и иметь отдельный механизм повторов. Поведение проверяют на тестовом триггере, а не предполагают по общим правилам HTTP.

Из чего сделать ключ идемпотентности

Лучший ключ соответствует бизнес-событию, а не сетевой попытке. Для создания задачи это может быть постоянный ID заявки во внешней системе. Для обновления — ID записи вместе с версией изменения. Для исходящего события из Трекера в тело запроса передают ключ задачи, тип изменения, согласованный идентификатор источника и данные, по которым получатель распознает уже применённое состояние.

Если готового ID события нет, обработчик формирует отпечаток из стабильных полей и хранит его вместе с результатом. Использовать только время получения нельзя: повтор придёт позже и будет выглядеть новым. Использовать только ключ задачи тоже нельзя: у одной задачи за день меняются статус, исполнитель и комментарии.

Запись ключа и результата выполняют согласованно. Если сначала создать задачу, а журнал записать отдельным шагом, авария между ними оставит окно для дубля. Практический вариант — сначала зарегистрировать событие со статусом «в обработке», затем выполнить операцию и сохранить результат; зависшие записи проверяются по внешнему ID до повторного создания.

Как должен отвечать приёмник HTTP-запроса

1. Проверить адрес и секрет. Токен или подпись запроса не выводятся в журнал. Секрет передают в настройке авторизации либо в отдельном заголовке.
2. Проверить минимальную структуру. Нужны ключ задачи, тип события и данные, достаточные для построения устойчивого ключа.
3. Сохранить исходное событие. До ответа Трекеру тело помещается в журнал или очередь с датой получения.
4. Распознать повтор. Если ключ уже обработан, вернуть прежний результат без повторного бизнес-действия.
5. Быстро завершить HTTP-запрос. Обогащение из CRM, загрузку файлов и сложные вычисления выполнять после сохранения.

В истории срабатывания триггера Яндекс Трекер показывает результат действия, а для HTTP-запроса — адрес, код и сообщение об ошибке [6]. Эти данные сопоставляют с журналом приёмника по времени и ключу задачи. Если Трекер показывает таймаут, а событие в очереди уже есть, повтор должен завершиться без второй операции.

Таблица соответствия полей должна быть версионируемой

Ключи полей, статусы и пользователи меняются по мере развития процесса. Интеграция хранит не только текущее соответствие, но и его версию. В таблице указывают поле-источник, поле-получатель, формат, направление, владельца, обязательность и поведение при пустом значении. Для статусов отдельно описывают допустимые переходы.

Передавать отображаемое имя вместо ключа рискованно: название можно изменить, локализовать или повторить в другой очереди. В API Трекера используются идентификаторы и ключи ресурсов; общий формат запроса также требует корректный заголовок организации — X-Org-ID для Яндекс 360 или X-Cloud-Org-ID для Yandex Identity Hub [4]. Неверная организация способна выглядеть как отсутствие объекта или прав.

Дата и время в API передаются в UTC [4]. Интеграция хранит исходное значение с часовым поясом и преобразует его только для показа пользователю. Иначе дедлайн возле полуночи может перейти на соседний день, а сравнение версий — ошибочно признать старое состояние новым.

Как разрешать одновременные изменения

Если менеджер изменил статус в CRM, а исполнитель почти одновременно перевёл задачу в Трекере, простое правило «последний запрос победил» может скрыть важное действие. Для каждого поля назначают владельца либо формулируют разрешённые направления. Например, CRM владеет данными клиента, Трекер — исполнителем, а статус меняется по согласованной таблице переходов.

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

Для критичных полей полезна периодическая сверка. Она получает задачи, изменённые после контрольной точки, сравнивает их с реестром внешней системы и исправляет пропущенные события. Такой проход закрывает разрывы после отключённого триггера, смены токена или временной ошибки, которые онлайн-доставка уже не повторит.

Как устроить очередь и ручной разбор

У события есть понятные состояния: «получено», «в обработке», «выполнено», «ожидает повтора» и «нужен разбор». Временная сетевая ошибка получает следующий срок попытки. Ошибка авторизации останавливает направление обмена и создаёт уведомление. Ошибка данных сохраняет тело ответа и связь с задачей, чтобы сотрудник исправил поле и повторил именно эту операцию.

Ручной повтор использует тот же ключ идемпотентности, что и автоматический. Кнопка «Повторить» не создаёт новое событие, а возвращает существующее в очередь. В журнале остаются номер попытки, код ответа, длительность, сокращённое сообщение и идентификаторы обеих систем.

Как выпускать двустороннюю синхронизацию

Сначала подключают одно направление для одной очереди и ограниченного набора полей. После контрольных задач включают обратную передачу, затем комментарии и вложения. Такой порядок позволяет увидеть источник цикла до того, как он затронет все рабочие очереди.

В тестовый набор обязательно включают потерю ответа после успешного создания, повтор одного HTTP-запроса, два быстрых изменения статуса, комментарий технического пользователя, просроченный токен, неверный заголовок организации и восстановление после остановки очереди. Результат считается корректным, если число бизнес-операций остаётся тем же, а все повторы видны в журнале.

Как ограничить права и безопасно заменить токен

Интеграция работает от отдельного технического пользователя, которому доступны только нужные очереди и действия. Личный токен сотрудника создаёт скрытую зависимость: после увольнения, блокировки аккаунта или изменения роли обмен внезапно остановится. Владелец технической учётной записи, срок пересмотра прав и порядок замены токена фиксируются в эксплуатационной документации.

Новый токен проверяют контрольным чтением и одной безопасной записью до отключения старого. Затем секрет меняют в хранилище конфигурации, перезапускают только процессы интеграции и наблюдают обе очереди. Полные значения токенов не попадают в логи, сообщения об ошибках, историю задач и систему мониторинга.

Для исходящего HTTP-запроса также используют отдельный секрет. Приёмник должен принимать новый и старый секрет в течение короткого согласованного окна, чтобы ротация не теряла события между сохранением настройки триггера и обновлением шлюза. После подтверждения доставки старое значение отзывают, а тестовый запрос и время переключения сохраняют в журнале изменений.

Как принять интеграцию

1. Одна заявка создаёт одну задачу даже при потере ответа и повторе запроса.
2. Изменение статуса передаётся в согласованном направлении и не запускает цикл.
3. Повторное событие распознаётся и отмечается обработанным без дубля.
4. Истёкший токен даёт понятную ошибку и оповещение, очередь сохраняется.
5. Комментарии технического пользователя не возвращаются обратно как новые.
6. После восстановления связи необработанные события догоняются в правильном порядке.

Обзор полей и общей схемы обмена есть в материале «Интеграция Яндекс Трекера с 1С, CRM и другими системами».

Официальные источники

1. Яндекс Трекер: доступ к API — OAuth, IAM и права пользователя.
2. Яндекс Трекер: объекты действий триггера — HTTP-запрос и Webhook.
3. Яндекс Трекер: интеграция со сторонними системами.
4. Яндекс Трекер: общий формат запросов API.
5. Яндекс Трекер: как настроить действие триггера — Официальное поведение HTTP-запроса: таймаут 10 секунд, повтор при коде 500, до пяти попыток с экспоненциальной задержкой..
6. Яндекс Трекер: как настроить триггер — История срабатываний и диагностика действия HTTP-запрос..
7. Яндекс Трекер: создать триггер с помощью API — Формат создания триггера, заголовки организации и версия объекта..
8. Яндекс Трекер: интегрировать с другими системами — Официальная схема входящего API и исходящих HTTP-запросов..