Параметры задач в запросах к API и ответах

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

В этой документации описаны стандартные параметры задачи, которые доступны в Трекере по умолчанию, а также стандартные объекты, которые могут содержаться в задаче:

• Параметры задачи в запросах к API
• Параметры задачи в ответах на запросы

Помимо стандартных параметров, задачи могут содержать:

• Пользовательские глобальные поля, созданные в организации.
• Локальные поля, специфичные для конкретной очереди.

Глобальные поля

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

Дополнительные глобальные поля может создать администратор Трекера. Как добавить в Трекер глобальное поле.

Список всех глобальных полей можно посмотреть на странице Настройки Трекера.

Локальные поля

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

Как использовать локальные поля, читайте в разделе Локальные поля задач.

Как использовать локальные поля в API

• Идентификатор локального поля включает шестнадцатеричный префикс и ключ поля: 603fb94c38bbe658********--myfield.

  Например, чтобы изменить значение локального поля задачи через API, в теле HTTP-запроса на редактирование задачи укажите идентификатор поля: 603fb94c38bbe658********--КЛЮЧ_ПОЛЯ: "НОВОЕ_ЗНАЧЕНИЕ_ЛОКАЛЬНОГО_ПОЛЯ". Как редактировать задачу с помощью API

• Убедитесь, что локальное поле принадлежит указанной очереди.

• Соблюдайте типы данных согласно схеме поля:

  • Для строковых полей используйте строки
  • Для числовых полей используйте числа
  • Для массивов пользователей используйте объекты с полем id

• Чтобы получить список локальных полей очереди, используйте запрос Получить список локальных полей очереди

Форматы значений локальных полей

Формат значения в теле запроса на создание и редактирование задачи зависит от типа поля и может отличаться от отображения и ввода в интерфейсе Трекера. Формат значения в ответе API тоже может отличаться от формата в запросе, поэтому он указан отдельно. Названия классов типов для запросов к API перечислены в разделе Параметры тела запроса запроса на создание локального поля.

Если в значении типа «Дата» указать время, оно не учитывается. Для типа «Дата и время» передайте, например, "2026-11-01T12:30:00.000+03:00".

Несколько значений. Для полей, в которых разрешено несколько значений (параметр container при создании поля), передайте массив элементов того же формата: ["user1", "user2"]. При редактировании задачи для такого поля можно использовать операторы set, add, remove — подробнее. Значение null очищает поле.

Выпадающий список. В поле передается значение из списка values, заданного при создании поля. Для списка с множественным выбором передайте массив таких значений.

Пример тела запроса с полями типов, которых нет в примерах создания и редактирования задачи:

{
    "603fb94c38bbe658********--durationField": "P1W2D",
    "603fb94c38bbe658********--moneyField": {"code": "USD", "amount": 12.34},
    "603fb94c38bbe658********--dateField": "2026-11-01",
    "603fb94c38bbe658********--dateTimeField": "2026-11-01T12:30:00.000+03:00"
}

Продолжительность

Передайте строку в формате ISO 8601 PnWnDTnHnMnS: недели (W), дни (D), часы (H), минуты (M) и секунды (S). Любую часть можно опустить, недели и дни можно указывать вместе. Например, "P1W2D" или "PT1H30M".

Недели и дни считаются по рабочему календарю: неделя — 5 рабочих дней, день — 8 часов. Годы и месяцы указать нельзя. В ответе API значение возвращается строкой в том же формате.

Деньги

В запросе можно передать:

• Число — сумму в валюте по умолчанию: 12.34
• Строку с кодом валюты и суммой: "USD 12.34"
• Объект с полем amount (сумма) и полем code (код валюты по ISO 4217) либо country (код страны)

Сумма округляется до минимальной единицы валюты: 12.3456 → 12.35 для USD.

Пример значения в запросе:

{"code": "USD", "amount": 12.34}

В ответе код валюты находится в поле unit, а сумма возвращается строкой:

{"unit": "USD", "amount": "12.34"}

Деньги и ставка

Передайте число или объект с теми же полями, что у типа «Деньги», и полем rate (ставка). Если ставку не указать, применяется значение по умолчанию. Сумма сохраняется без округления.

Пример значения в запросе:

{"code": "USD", "amount": 12.34, "rate": 0.5}

В ответе код валюты находится в поле unit, а значения amount и rate возвращаются строками:

{"unit": "USD", "amount": "12.34", "rate": "0.5"}