Okdesk API

Статусы заявок – получение и изменение

Okdesk API: Статусы заявок – получение и изменение1. Справочник статусов заявок (GET /api/v1/issues/statuses)

Описание: Возвращает список всех возможных статусов заявок в вашем аккаунте Okdesk. Этот справочник позволяет получить идентификаторы и названия статусов, настроенных в системе.

• HTTP-метод: GET
• URI: https://<Ваш_домен>.okdesk.ru/api/v1/issues/statuses
• Требования: Необходим действующий API-токен (передается как параметр api_token в URL или в заголовке Authorization). Доступ к этому ресурсу, как правило, имеют пользователи с правами сотрудника/администратора.
• Параметры запроса: Нет обязательных параметров (кроме api_token).
• Пример запроса:

GET https://example.okdesk.ru/api/v1/issues/statuses?api_token=<API_TOKEN>

• Пример ответа: Возвращается JSON-массив объектов со статусами. Каждый объект обычно содержит ID статуса и его название (и возможно дополнительные свойства). Например:

[
  {
    "id": 1,
    "name": "Новая"
  },
  {
    "id": 2,
    "name": "В работе"
  },
  {
    "id": 3,
    "name": "Ожидает ответа"
  },
  ...
]

• В приведенном примере возвращены статусы с их уникальным идентификатором (id) и названием (name).
• Документация: Раздел «Справочник статусов заявок» в официальной документации Okdesk API. (Пример упоминания: справочник статусов доступен через метод GET в API​
• apimonster.ru

2. Текущий статус конкретной заявки (GET /api/v1/issues/{issue_id})

Описание: Позволяет получить детальную информацию о конкретной заявке, включая текущий статус этой заявки. Метод возвращает все основные поля заявки, в том числе статус на момент запроса.

• HTTP-метод: GET
• URI: https://<Ваш_домен>.okdesk.ru/api/v1/issues/{issue_id} (где {issue_id} – идентификатор заявки)​
• github.com

• Требования: Необходим API-токен с правами доступа к указанной заявке. Пользователь, от имени которого выполняется запрос, должен иметь право просмотра данной заявки (например, быть сотрудником техподдержки, ответственным или наблюдателем).
• Параметры:
• issue_id (integer, обязательный) – ID заявки, статус которой нужно получить​
• github.com

• Пример запроса:

GET https://example.okdesk.ru/api/v1/issues/123?api_token=<API_TOKEN>

• Пример ответа: Возвращается JSON-объект с полями заявки. Среди прочего, он содержит информацию о статусе. Например:

{
  "id": 123,
  "title": "Не работает принтер",
  "status_id": 2,
  "status_name": "В работе",
  "assignee_id": 45,
  "...": "..." 
}

• В данном примере ответ включает поля status_id и status_name, которые указывают текущий статус заявки (ID статуса = 2, название = "В работе")​
• apimonster.ru

• . Помимо статуса, возвращаются и другие данные заявки (название, описание, назначенный сотрудник и т.д.).
• Документация: Раздел «Информация о заявке» официальной документации Okdesk (метод получения информации о заявке)​
• github.com

Этот раздел описывает, какие поля возвращаются, включая статус заявки.

3. Обновление статуса заявки (смена статуса) через API (PUT /api/v1/issues/{issue_id})

Описание: Данный маршрут позволяет изменить статус указанной заявки программно. Вы можете перевести заявку в другой статус (например, с “Новая” на “В работе” или “Закрыта”) с помощью вызова к API. При смене статуса могут срабатывать связанные правила (триггеры) Okdesk, аналогично смене статуса через интерфейс.

• HTTP-метод: PUT (в некоторых версиях API может использоваться POST – уточните в документации вашей версии)
• URI: https://<Ваш_домен>.okdesk.ru/api/v1/issues/{issue_id} (где {issue_id} – ID заявки, статус которой нужно изменить).
• Требования: API-токен пользователя с правами на изменение заявок. Обычно доступно для учетных записей сотрудников техподдержки/администраторов; недоступно для клиентов. Пользователь должен иметь право менять статус данной заявки (например, быть ответственным или иметь соответствующую роль).
• Параметры:
• issue_id (integer, в пути запроса) – ID заявки для обновления.
• В теле запроса передаются необходимые данные в формате JSON:
• status_id (integer, обязательный) – новый код/ID статуса, на который нужно перевести заявку​
• apimonster.ru

• available_current_status (array/integer, опционально) – код текущего статуса, который вы ожидаете у заявки перед сменой. Если указан и текущий статус заявки не совпадает ни с одним из указанных значений, запрос не выполнится. Этот параметр служит для контроля последовательности статусов (т.е. чтобы статус не был изменён, если заявка уже перешла в другой статус).
• comment (string, опционально) – комментарий, который будет добавлен к заявке при смене статуса (например, пояснение причины смены статуса, решение проблемы и т.д.). Если передан, этот текст отобразится как комментарий от имени пользователя API.
• Пример запроса:

PUT https://example.okdesk.ru/api/v1/issues/123?api_token=<API_TOKEN>
Content-Type: application/json

{
  "status_id": 5,
  "available_current_status": [2, 3],
  "comment": "Заявка решена удаленно, закрываю через API"
}

• В этом примере заявке #123 присваивается новый статус с ID 5 (предположительно “Закрыта”). Параметр available_current_status содержит список допустимых текущих статусов (IDs 2 и 3), при которых смена разрешена – если заявка сейчас не в одном из этих статусов, запрос вернёт ошибку. Также добавляется комментарий о решении.
• Пример ответа: Успешный запрос возвращает обновлённые данные заявки (либо флаг успеха). Например, ответ может вернуть JSON с новой информацией о заявке, где поля статуса отражают новое состояние:

{
  "id": 123,
  "status_id": 5,
  "status_name": "Закрыта",
  "result": true,
  "...": "..."
}

• Здесь status_id: 5 и status_name: "Закрыта" подтверждают, что заявка переведена в новый статус. Поле result: true условно показывает, что операция выполнена успешно​
• apimonster.ru
• . (Примечание: формат ответа может различаться; в некоторых случаях возвращается весь объект заявки с обновлениями или код 204 No Content.)
• Документация: См. раздел «Изменение статуса заявки» в документации Okdesk API. В официальной документации описано, как выполнить смену статуса через API, включая требуемые поля запроса. (Пример интеграции, подтверждающий наличие метода смены статуса:
• okdesk.ru

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

Дополнительные замечания: Все вышеперечисленные запросы выполняются к домену вашего аккаунта Okdesk (например, yourcompany.okdesk.ru). В каждом запросе необходимо указывать API-токен для аутентификации. Если у токена или учетной записи недостаточно прав, сервер вернет ошибку (например, 403 Forbidden). Также, некоторые статусы могут быть «финальными» (закрывающими заявку) или иметь ограничения переходов – API уважает бизнес-логику Okdesk, поэтому недопустимо менять статус на запрещённый правилами вашего аккаунта​

apimonster.ru

При планировании интеграции убедитесь, что используете корректные ID статусов (их можно получить с помощью справочника статусов, см. п.1) и что пользователь API обладает необходимыми правами.