API и выгрузки: превращаем Трекер из сайта в платформу

Что даёт API

Всё, что ты делаешь в Трекере мышкой, можно делать скриптом. Правило простое: есть кнопка, есть и запрос к API. Создать задачу, поменять статус, найти всё просроченное, добавить комментарий: для каждого действия есть свой HTTP-запрос.

Зачем это нужно, когда руки и так справляются:

• Пачки. Завести 40 однотипных задач по списку из таблицы: руками час, скриптом секунды.
• Выгрузки. Вытащить все закрытые задачи за месяц в CSV и построить отчёт в любимой табличке.
• Боты. Научить Telegram-бота заводить задачи из чата. Именно так живёт наш Гермес, о нём в конце модуля.

Технически это обычный REST: шлёшь HTTP-запросы на https://api.tracker.yandex.net, актуальная версия v3, ответы приходят в JSON. Подойдёт любой язык, в примерах будет Python с библиотекой requests.

Получаем доступ по шагам

API должно понимать, кто ты и в какой организации работаешь. Для этого нужны две вещи: OAuth-токен (это про «кто ты») и ID организации (это про «где»).

1. Открой oauth.yandex.ru и нажми Создать приложение

   Входи тем же Яндекс ID, которым ходишь в Трекер. «Приложение» звучит громко, на деле это просто запись «такой-то скрипт имеет такие-то права».

2. Укажи название, выбери вариант Для доступа к API или отладки

   Название любое понятное, например «Отчёты Котолавки». Почта для связи: твоя рабочая.

3. В разделе доступов добавь права Трекера: tracker:read для чтения, tracker:write для создания и изменения задач

   Правило минимума: скрипту-выгрузке хватит tracker:read. Права на запись выдавай, только если скрипт реально что-то создаёт.

4. Сохрани приложение, скопируй его ClientID и перейди по ссылке https://oauth.yandex.ru/authorize?response_type=token&client_id=<твой_ClientID>

   Яндекс спросит подтверждение и покажет токен: длинную строку символов. Это и есть ключ для скриптов, скопируй его в надёжное место.

5. Узнай ID организации: в Трекере открой Администрирование → Организации и скопируй значение поля с идентификатором

   Если организация облачная (Yandex Cloud Organization), в запросах вместо заголовка X-Org-ID используется X-Cloud-Org-ID. Какой у вас случай, видно там же в настройках: облачный идентификатор из букв и цифр, обычный из цифр.

В каждом запросе к API эти две вещи едут в заголовках:

Authorization: OAuth <твой_токен>
X-Org-ID: <ID_организации>        # для облачных организаций: X-Cloud-Org-ID

Читаем задачи: первый скрипт

Начнём с чтения, оно безопасное: ничего не сломаешь. Задача: получить все открытые задачи очереди и напечатать их номера и названия. Для поиска задач в API есть эндпоинт POST /v3/issues/_search: шлёшь ему фильтр, получаешь JSON-список задач.

# list_tasks.py: открытые задачи очереди KOT
import os
import requests

# токен и ID организации берём из переменных окружения, не из кода
TOKEN = os.environ["TRACKER_TOKEN"]
ORG_ID = os.environ["TRACKER_ORG_ID"]

headers = {
    "Authorization": f"OAuth {TOKEN}",
    "X-Org-ID": ORG_ID,  # у облачных организаций: "X-Cloud-Org-ID"
}

resp = requests.post(
    "https://api.tracker.yandex.net/v3/issues/_search",
    headers=headers,
    params={"perPage": 100},          # задач на страницу ответа
    json={
        "filter": {
            "queue": "KOT",           # ключ очереди
            "resolution": "empty()",  # ещё не решённые, то есть открытые
        },
        "order": "+status",           # сортировка по статусу
    },
)
resp.raise_for_status()  # если что-то не так, упадём с понятной ошибкой

issues = resp.json()
for issue in issues:
    print(f'{issue["key"]:10} {issue["summary"]}')

print(f"Всего открытых задач: {len(issues)}")

Запускаешь python list_tasks.py и видишь в терминале свой Трекер без браузера:

Создаём задачу скриптом

Теперь запись. Создание задачи: POST /v3/issues. Обязательных полей всего два, очередь и название, остальное по вкусу.

# new_task.py: заводим задачу с исполнителем и дедлайном
import os
import requests

headers = {
    "Authorization": f"OAuth {os.environ['TRACKER_TOKEN']}",
    "X-Org-ID": os.environ["TRACKER_ORG_ID"],
}

payload = {
    "queue": "KOT",                          # куда: ключ очереди
    "summary": "Сверка остатков склада",     # название, обязательное поле
    "description": "Сверить остатки корма в базе с фактом на складе. "
                   "Расхождения записать в комментарий.",
    "assignee": "maks",                      # логин исполнителя
    "deadline": "2026-07-21",                # дедлайн в формате ГГГГ-ММ-ДД
}

resp = requests.post(
    "https://api.tracker.yandex.net/v3/issues",
    headers=headers,
    json=payload,
)
resp.raise_for_status()

issue = resp.json()
print("Создана задача:", issue["key"], "·", issue["summary"])
# Создана задача: KOT-27 · Сверка остатков склада

В ответ API возвращает созданную задачу целиком, включая её номер. Дальше этот номер можно куда угодно: в лог, в сообщение бота, в письмо. Для запуска по расписанию скрипт вешают на планировщик: cron на сервере или «Планировщик заданий» в Windows.

Выгрузка для отчёта: закрытое за неделю в CSV

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

# weekly_report.py: задачи, закрытые за 7 дней, в CSV
import csv
import os
from datetime import date, timedelta

import requests

headers = {
    "Authorization": f"OAuth {os.environ['TRACKER_TOKEN']}",
    "X-Org-ID": os.environ["TRACKER_ORG_ID"],
}

week_ago = (date.today() - timedelta(days=7)).isoformat()
# язык запросов из модуля 5 работает и в API: поле query
query = f'Queue: KOT AND Resolved: >= "{week_ago}"'

resp = requests.post(
    "https://api.tracker.yandex.net/v3/issues/_search",
    headers=headers,
    params={"perPage": 100},
    json={"query": query, "order": "+resolvedAt"},
)
resp.raise_for_status()
issues = resp.json()

# utf-8-sig, чтобы Excel сразу понял русские буквы
with open("closed_week.csv", "w", newline="", encoding="utf-8-sig") as f:
    writer = csv.writer(f, delimiter=";")
    writer.writerow(["Номер", "Название", "Исполнитель", "Закрыта"])
    for issue in issues:
        writer.writerow([
            issue["key"],
            issue["summary"],
            issue.get("assignee", {}).get("display", "без исполнителя"),
            issue.get("resolvedAt", "")[:10],  # дата без времени
        ])

print(f"Готово: {len(issues)} задач в closed_week.csv")

Файл открывается в любой табличке: Excel, Яндекс Документы, Google Sheets. Дальше сводные, графики, что душе угодно. Один раз написал, и утренний отчёт по понедельникам делается сам.

Как устроен Гермес: тот же API, никакой магии

Всё, что бот Сол (Гермес) делает с нашей очередью TREK, собрано ровно из тех кирпичей, что ты видел выше:

1. Бот регулярно обновляет свой список открытых задач очереди

   Тот самый POST /v3/issues/_search с фильтром по очереди. Список хранится у бота под рукой, чтобы не дёргать API на каждый чих.

2. Читает рабочую Telegram-группу и ловит поручения

   Сообщения вида «сделать X к сроку» распознаёт языковая модель. Это единственная часть, которой нет в Трекере, всё остальное штатное API.

3. Сверяет пойманное поручение со своим списком задач

   Похожая задача уже есть? Значит, дубль не нужен. Именно поэтому в TREK нет пяти задач «подготовить встречу» про одну и ту же встречу.

4. Спрашивает подтверждение и после «да» создаёт задачу

   Тот самый POST /v3/issues. Человек решает, бот исполняет: ни одна задача не появляется без подтверждения.

Мораль всего модуля: API превращает Трекер из сайта, куда ходят люди, в платформу, на которой строят своё. Бот в Telegram, отчёт по расписанию, интеграция с самописной системой склада: всё это один и тот же набор запросов.