API Okdesk

В настоящей документации описаны существующие методы API сервиса Okdesk.

Во всех запросах должен присутствовать параметр api_token (ключ авторизации). Ключ авторизации можно сгенерировать в разделе API настроек вашего аккаунта в сервисе Okdesk.

Компании ¶

Поиск компании

GET`/api/v1/companies/{?api_token,name,phone,id,crm_1c_id,search_string}`

Поиск осуществляется по точному совпадению названия или дополнительного названия компании, телефона и внутреннего ID, по вхождению подстроки в значение идентификатора объекта в 1С или по подстроке

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

При передаче параметра search_string остальные параметры не учитываются
Символ + в поисковой строке можно использовать только в закодированном варианте %2B, иначе он будет воспринят как пробел

Пример URI

GET https://<account>.okdesk.ru/api/v1/companies/?api_token=3e9a214215f493c4&name=Okdesk&phone=+7(499)703-47-20&id=1040&crm_1c_id=35067c4b23a8&search_string=desk

Параметры URI

СкрытьПоказать

api_token: string (обязательное) Пример: 3e9a214215f493c4
Ключ авторизации.
name: string (необязательное) Пример: Okdesk
Имя компании
phone: string (необязательное) Пример: +7(499)703-47-20
Телефон компании
id: integer (необязательное) Пример: 1040
Внутренний ID компании
crm_1c_id: string (необязательное) Пример: 35067c4b23a8
Идентификатор объекта в 1С
search_string: string (необязательное) Пример: desk
Искомая подстрока

Ответ 200

СкрытьПоказать

Заголовки

Content-Type: application/json

Тело

{
  "id": 1040,
  "name": "Okdesk",
  "additional_name": "Help Desk система для сервисных компаний",
  "site": "http://okdesk.ru",
  "email": "info@okdesk.ru",
  "phone": "+7(499)703-47-20",
  "crm_1c_id": "35067c4b23a8",
  "active": true,
  "address": "г. Москва, ул. Хелпдескрешений 11, офис 330",
  "comment": "Okdesk — простая и удобная облачная Help Desk система для автоматизации процессов поддержки в малых и средних сервисных компаниях. Позволяет вести учет заявок в службу поддержки, клиентов и всех взаимодействий с ними, условий предоставления услуг (SLA), договоров, их сроков действия и этапов оплаты.",
  "coordinates": [
    53.2184321,
    44.9998082
  ],
  "observers": [
    {
      "id": 2,
      "name": "Эрдингтон Филлип Витальевич"
    },
    {
      "id": 1,
      "name": "Иванов Иван Викторович"
    }
  ],
  "contacts": [],
  "default_assignee": {
    "id": 1,
    "name": "Иванов Иван Викторович"
  },
  "default_assignee_group": {
    "id": 1,
    "name": "Группа мониторинга",
    "active": true,
    "description": ""
  },
  "category": {
    "id": 3,
    "code": "vipclient",
    "name": "VIP-клиент",
    "color": "#5cb85c"
  },
  "attachments": [
    {
      "id": 8,
      "attachment_file_name": "photo.jpg",
      "description": "Фотография неисправности",
      "attachment_file_size": 4149,
      "is_public": false,
      "created_at": "2016-09-30T09:28:50.499+03:00"
    }
  ],
  "parameters": [
    {
      "code": "attr1",
      "name": "Номер документа",
      "field_type": "ftstring",
      "value": "2368590"
    },
    {
      "code": "attr2",
      "name": "Дата начала сотрудничества",
      "field_type": "ftdate",
      "value": "2019-02-06"
    },
    {
      "code": "attr3",
      "name": "Дата следущего созвона",
      "field_type": "ftdatetime",
      "value": "2019-02-21T14:00:00.000+03:00"
    },
    {
      "code": "attr4",
      "name": "Вип обслуживание",
      "field_type": "ftcheckbox",
      "value": true
    },
    {
      "code": "attr5",
      "name": "Вид деятельности",
      "field_type": "ftselect",
      "value": "Программное обеспечение"
    },
    {
      "code": "attr6",
      "name": "Виды помещений",
      "field_type": "ftmultiselect",
      "value": [
        "Главный офис",
        "Зона отдыха"
      ]
    }
  ]
}

Создание компании

POST`/api/v1/companies/{?api_token}`

Название	Тип	Обязательность	Описание
name	string	обязательный	Название компании
additional_name	string	необязательный	Дополнительное название компании
site	string	необязательный	Сайт компании
email	string	необязательный	Контактный E-mail компании
phone	string	необязательный	Контактный телефон компании
address	string	необязательный	Адрес компании. Внимание! При передаче текстовой части адреса автоматическая подстановка координат адреса (геокодинг) не осуществляется. Для того, чтобы адрес отображался на карте, необходимо дополнительно передать координаты адреса в параметре coordinates. Перевести текстовую часть адреса в координаты можно с помощью сервисов геокодинга, например DaData.ru, Google Geocoding API и т.д.
coordinates	array of float	необязательный	Координаты компании
comment	string	необязательный	Дополнительная информация о компании
observer_ids	array of integer	необязательный	Массив из ID пользователей, являющихся наблюдателями компании
default_assignee_id	integer	необязательный	ID сотрудника, назначенного ответственным по умолчанию для этой компании
default_assignee_group_id	integer	необязательный	ID ответственной группы сотрудника
category_code	string	необязательный	Код категории клиента
crm_1c_id	string	необязательный	Идентификатор объекта в 1С. Необходим для интеграции с 1С, не отображается в web-интерфейсе
custom_parameters	associative array	опционально	Дополнительные атрибуты компании

Создание компании доступно для сотрудников в соответствии с настройками прав доступа. Для ключей, связанных с контактными лицами, данный метод недоступен.

Параметр coordinates - массив из двух вещественных чисел (широта от -90 до 90, долгота от -180 до 180).

Пример URI

POST https://<account>.okdesk.ru/api/v1/companies/?api_token=3e9a214215f493c4

Параметры URI

СкрытьПоказать

api_token: string (обязательное) Пример: 3e9a214215f493c4
Ключ авторизации.

Запрос

СкрытьПоказать

Заголовки

Content-Type: application/json

Тело

{
  "company": {
    "name": "Okdesk",
    "additional_name": "Help Desk система для сервисных компаний",
    "site": "http://okdesk.ru",
    "email": "info@okdesk.ru",
    "phone": "+7(499)703-47-20",
    "address": "г. Москва, ул. Хелпдескрешений 11, офис 330",
    "coordinates": [
      53.2184321,
      44.9998082
    ],
    "comment": "Okdesk — простая и удобная облачная Help Desk система для автоматизации процессов поддержки в малых и средних сервисных компаниях. Позволяет вести учет заявок в службу поддержки, клиентов и всех взаимодействий с ними, условий предоставления услуг (SLA), договоров, их сроков действия и этапов оплаты.",
    "observer_ids": [
      1,
      2
    ],
    "default_assignee_id": 1,
    "default_assignee_group_id": 1,
    "category_code": "client",
    "crm_1c_id": "67067c3a29a8",
    "custom_parameters": {
      "code1": "123456789",
      "code2": "2019-02-15",
      "code3": true
    }
  }
}

Ответ 200

СкрытьПоказать

Заголовки

Content-Type: application/json

Тело

{
  "id": 1040,
  "name": "Okdesk",
  "additional_name": "Help Desk система для сервисных компаний",
  "site": "http://okdesk.ru",
  "email": "info@okdesk.ru",
  "phone": "+7(499)703-47-20",
  "address": "г. Москва, ул. Хелпдескрешений 11, офис 330",
  "comment": "Okdesk — простая и удобная облачная Help Desk система для автоматизации процессов поддержки в малых и средних сервисных компаниях. Позволяет вести учет заявок в службу поддержки, клиентов и всех взаимодействий с ними, условий предоставления услуг (SLA), договоров, их сроков действия и этапов оплаты.",
  "crm_1c_id": "67067c3a29a8",
  "active": true,
  "coordinates": [
    53.2184321,
    44.9998082
  ],
  "observers": [
    {
      "id": 2,
      "name": "Эрдингтон Филлип Витальевич"
    },
    {
      "id": 1,
      "name": "Иванов Иван Викторович"
    }
  ],
  "contacts": [],
  "default_assignee": {
    "id": 1,
    "name": "Иванов Иван Викторович"
  },
  "default_assignee_group": {
    "id": 1,
    "name": "Группа мониторинга",
    "active": true,
    "description": ""
  },
  "category": {
    "id": 2,
    "code": "client",
    "name": "Клиент",
    "color": "#5cb85c"
  },
  "attachments": [],
  "parameters": [
    {
      "code": "code1",
      "name": "Номер документа",
      "field_type": "ftstring",
      "value": "123456789"
    },
    {
      "code": "code2",
      "name": "Дата начала сотрудничества",
      "field_type": "ftdate",
      "value": "2019-02-15"
    },
    {
      "code": "code3",
      "name": "Вип обслуживание",
      "field_type": "ftcheckbox",
      "value": true
    }
  ]
}

Редактирование компании

PATCH`/api/v1/companies/{company_id}{?api_token}`

Название	Тип	Обязательность	Описание
name	string	необязательный	Название компании
additional_name	string	необязательный	Дополнительное название компании
site	string	необязательный	Сайт компании
email	string	необязательный	Контактный E-mail компании
phone	string	необязательный	Контактный телефон компании
address	string	необязательный	Адрес компании. Внимание! При передаче текстовой части адреса автоматическая подстановка координат адреса (геокодинг) не осуществляется. Для того, чтобы адрес отображался на карте, необходимо дополнительно передать координаты адреса в параметре coordinates. Перевести текстовую часть адреса в координаты можно с помощью сервисов геокодинга, например DaData.ru, Google Geocoding API и т.д.
coordinates	array of float	необязательный	Координаты компании
comment	string	необязательный	Дополнительная информация о компании
observer_ids	array of integer	необязательный	Массив из ID пользователей, являющихся наблюдателями компании
default_assignee_id	integer	необязательный	ID сотрудника, назначенного ответственным по умолчанию для этой компании
default_assignee_group_id	integer	необязательный	ID ответственной группы сотрудника
category_code	string	необязательный	Код категории клиента
crm_1c_id	string	необязательный	Идентификатор объекта в 1С. Необходим для интеграции с 1С, не отображается в web-интерфейсе
custom_parameters	associative array	опционально	Дополнительные атрибуты компании

Редактирование компании будет выполнено только в том случае, если связанный с ключом сотрудник имеет права на просмотр компании и редактирование атрибутов компании в соответствии с настройками прав доступа. Для ключей, связанных с контактными лицами, данный метод недоступен.

Параметр coordinates - массив из двух вещественных чисел (широта от -90 до 90, долгота от -180 до 180).

Пример URI

PATCH https://<account>.okdesk.ru/api/v1/companies/4?api_token=3e9a214215f493c4

Параметры URI

СкрытьПоказать

api_token: string (обязательное) Пример: 3e9a214215f493c4
Ключ авторизации.
company_id: integer (обязательное) Пример: 4
ID компании.

Запрос

СкрытьПоказать

Заголовки

Content-Type: application/json

Тело

{
  "company": {
    "name": "Okdesk",
    "additional_name": "Help Desk система для сервисных компаний",
    "site": "http://okdesk.ru",
    "email": "info@okdesk.ru",
    "phone": "+7(499)703-47-20",
    "address": "г. Москва, ул. Хелпдескрешений 11, офис 330",
    "coordinates": [
      53.2184321,
      44.9998082
    ],
    "comment": "Okdesk — простая и удобная облачная Help Desk система для автоматизации процессов поддержки в малых и средних сервисных компаниях. Позволяет вести учет заявок в службу поддержки, клиентов и всех взаимодействий с ними, условий предоставления услуг (SLA), договоров, их сроков действия и этапов оплаты.",
    "observer_ids": [
      1,
      2
    ],
    "default_assignee_id": 1,
    "default_assignee_group_id": 1,
    "category_code": "vipclient",
    "crm_1c_id": "67067c3a29a8",
    "custom_parameters": {
      "code2": "2019-02-22"
    }
  }
}

Ответ 200

СкрытьПоказать

Заголовки

Content-Type: application/json

Тело

{
  "id": 1040,
  "name": "Okdesk",
  "additional_name": "Help Desk система для сервисных компаний",
  "site": "http://okdesk.ru",
  "email": "info@okdesk.ru",
  "phone": "+7(499)703-47-20",
  "address": "г. Москва, ул. Хелпдескрешений 11, офис 330",
  "comment": "Okdesk — простая и удобная облачная Help Desk система для автоматизации процессов поддержки в малых и средних сервисных компаниях. Позволяет вести учет заявок в службу поддержки, клиентов и всех взаимодействий с ними, условий предоставления услуг (SLA), договоров, их сроков действия и этапов оплаты.",
  "crm_1c_id": "67067c3a29a8",
  "active": true,
  "coordinates": [
    53.2184321,
    44.9998082
  ],
  "observers": [
    {
      "id": 2,
      "name": "Эрдингтон Филлип Витальевич"
    },
    {
      "id": 1,
      "name": "Иванов Иван Викторович"
    }
  ],
  "contacts": [],
  "default_assignee": {
    "id": 1,
    "name": "Иванов Иван Викторович"
  },
  "default_assignee_group": {
    "id": 1,
    "name": "Группа мониторинга",
    "active": true,
    "description": ""
  },
  "category": {
    "id": 2,
    "code": "vipclient",
    "name": "VIP-клиент",
    "color": "#5cb85c"
  },
  "attachments": [
    {
      "id": 8,
      "attachment_file_name": "photo.jpg",
      "description": "Фотография неисправности",
      "attachment_file_size": 4149,
      "is_public": false,
      "created_at": "2016-09-30T09:28:50.499+03:00"
    }
  ],
  "parameters": [
    {
      "code": "code1",
      "name": "Номер документа",
      "field_type": "ftstring",
      "value": "123456789"
    },
    {
      "code": "code2",
      "name": "Дата начала сотрудничества",
      "field_type": "ftdate",
      "value": "2019-02-22"
    },
    {
      "code": "code3",
      "name": "Вип обслуживание",
      "field_type": "ftcheckbox",
      "value": true
    }
  ]
}

Получение списка по параметрам

GET`/api/v1/companies/list{?api_token}`

Название	Тип	Обязательность	Описание
category_ids	array of integer	опционально	Массив из ID категорий компаний (для отображения компаний без категорий необходимо передавать в параметре значение “0”). Пример: category_ids[]=1
default_assignee_ids	array of integer	опционально	Массив из ID сотрудников, которые являются ответственными за компании (для отображения компаний без ответственного необходимо передавать в параметре значение “0”). Пример: default_assignee_ids[]=1
default_assignee_group_ids	array of integer	опционально	Массив из ID ответственных групп компаний (для отображения компаний без ответственной группы необходимо передавать в параметре значение “0”). Пример: default_assignee_group_ids[]=1
observer_ids	array of integer	опционально	Массив из ID сотрудников, которые являются наблюдателями компаний (для отображения компаний без наблюдателей необходимо передавать в параметре значение “0”). Пример: observer_ids[]=1
observer_group_ids	array of integer	опционально	Массив из ID групп наблюдателей компаний (для отображения компаний без групп наблюдателей необходимо передавать в параметре значение “0”). Пример: observer_group_ids[]=1
created_since	string	опционально	Дата создания компании в часовом поясе аккаунта (С) Пример: created_since=2019-05-25
created_until	string	опционально	Дата создания компании в часовом поясе аккаунта (По) Пример: created_until=2019-05-25
custom_parameters	associative array	опционально	Ассоциативный массив из пар Код дополнительного атрибута: Значение или набор значений
name	string	опционально	Название компании Пример: name=Okdesk
additional_name	string	опционально	Дополнительное название компании Пример: additional_name=Help Desk система для сервисных компаний
crm_1c_id	string	опционально	Идентификатор объекта в 1С Пример: crm_1c_id=35067c4b23a8
page	associative array	опционально	Ассоциативный массив параметров постраничного вывода списка компаний (подробное описание представлено в таблице ниже).

Название	Тип значения	Обязательность	Описание
size	integer	опционально	Число возвращаемых записей. Не может превышать 100. Пример: page[size]=30
from_id	integer	опционально	ID компании, с которой начинается выборка записей. По умолчанию (если не задан параметр direction) выборка осуществляется в направлении от значения from_id в сторону уменьшения id компании. Пример: page[from_id]=10
direction	string	опционально	Направление выборки. Доступно два значения: reverse, forward. reverse - возвращает записи, ID которых меньше значения from_id, если параметр from_id передан. При отсутствии параметра from_id выборка осуществляется от наибольшого значения id компании. forward - возвращает записи, ID которых больше значения from_id, если параметр from_id передан. При отсутствии параметра from_id выборка осуществляется от наименьшего значения id компании. Пример: page[direction]=forward

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

Метод возвращает не более 100 записей. В случае, когда параметры постраничного вывода не переданы, будет возвращен список последних 100 созданных компаний.

Тип атрибута	Тип значения	Описание
Дата	string	Доступны два типа значения: Код дополнительного атрибута_since - задает левую границу диапазона (С) и Код дополнительного атрибута_until - задает правую границу диапазона (По). Может быть передан один из параметров или оба параметра. Пример: custom_parameters[date_code_since]=2018-01-01 custom_parameters[date_code_until]=2018-12-12
Дата/время	string	Доступны два типа значения: Код дополнительного атрибута_since - задает левую границу диапазона (С) и Код дополнительного атрибута_until - задает правую границу диапазона (По). Может быть передан один из параметров или оба параметра. Пример: custom_parameters[datetime_code_since]=2018-01-01 01:01 custom_parameters[datetime_code_until]=2018-12-12 12:12
Чекбокс	string	Доступны два значения true и false. Пример: custom_parameters[checkbox_code]=true
Значение из списка	array of string	Массив из значений списка. Пример: custom_parameters[list_code][]=list_value
Набор значений из списка	array of string	Массив из значений списка. Пример: custom_parameters[list_code][]=list_value
Строка	string	Значение строкового типа (для отображения компаний с пустым значением атрибута необходимо передавать в параметре #null). Пример: custom_parameters[string_code]=string_value

https://<account>.okdesk.ru/api/v1/companies/list?
  api_token=3e9a214215f493c4&page[size]=3&page[from_id]=10&page[direction]=reverse

Пример URI

GET https://<account>.okdesk.ru/api/v1/companies/list?api_token=3e9a214215f493c4

Параметры URI

СкрытьПоказать

api_token: string (обязательное) Пример: 3e9a214215f493c4
Ключ авторизации.

Ответ 200

СкрытьПоказать

Заголовки

Content-Type: application/json

Тело

[
  {
    "id": 12,
    "name": "ООО «Типография»",
    "additional_name": null,
    "active": true,
    "category": null,
    "parameters": [
      {
        "code": "code1",
        "name": "Номер документа",
        "field_type": "ftstring",
        "value": "987654321"
      },
      {
        "code": "code2",
        "name": "Дата начала сотрудничества",
        "field_type": "ftdate",
        "value": "2020-02-22"
      },
      {
        "code": "code3",
        "name": "Вип обслуживание",
        "field_type": "ftcheckbox",
        "value": false
      }
    ]
  },
  {
    "id": 22,
    "name": "ИП Иванов",
    "additional_name": null,
    "active": true,
    "category": {
      "id": "3",
      "code": "vipclient",
      "name": "VIP client",
      "color": "#FF0000"
    },
    "parameters": [
      {
        "code": "code1",
        "name": "Номер документа",
        "field_type": "ftstring",
        "value": "123456789"
      },
      {
        "code": "code2",
        "name": "Дата начала сотрудничества",
        "field_type": "ftdate",
        "value": "2019-02-22"
      },
      {
        "code": "code3",
        "name": "Вип обслуживание",
        "field_type": "ftcheckbox",
        "value": true
      }
    ]
  },
  {
    "id": 10,
    "name": "Okdesk",
    "additional_name": "Help Desk система для сервисных компаний",
    "active": true,
    "category": {
      "id": "2",
      "code": "partner",
      "name": "Partner",
      "color": "#ffee00"
    },
    "parameters": [
      {
        "code": "code1",
        "name": "Номер документа",
        "field_type": "ftstring",
        "value": "1234"
      },
      {
        "code": "code2",
        "name": "Дата начала сотрудничества",
        "field_type": "ftdate",
        "value": "2021-02-22"
      },
      {
        "code": "code3",
        "name": "Вип обслуживание",
        "field_type": "ftcheckbox",
        "value": true
      }
    ]
  },
  {
    "id": 18,
    "name": "ИП Борисов",
    "additional_name": "Производство мясных деликатесов",
    "active": true,
    "category": {
      "id": "1",
      "code": "client",
      "name": "Client",
      "color": "#00ff00"
    },
    "parameters": [
      {
        "code": "code1",
        "name": "Номер документа",
        "field_type": "ftstring",
        "value": "4321"
      },
      {
        "code": "code2",
        "name": "Дата начала сотрудничества",
        "field_type": "ftdate",
        "value": "2024-02-22"
      },
      {
        "code": "code3",
        "name": "Вип обслуживание",
        "field_type": "ftcheckbox",
        "value": false
      }
    ]
  }
]

Ответ 422

СкрытьПоказать

Заголовки

Content-Type: application/json

Тело

{
  "errors": {
    "created_until": [
      "Неверный формат даты"
    ],
    "observer_ids": {
      "1": [
        "должно иметь тип integer"
      ]
    },
    "page": {
      "size": [
        "должно быть меньше или равно 100"
      ],
      "direction": [
        "должен быть одним из: reverse, forward"
      ],
      "from_id": [
        "должно иметь тип integer"
      ]
    }
  }
}

Получение файла компании

GET`/api/v1/companies/{company_id}/attachments/{attachment_id}{?api_token}`

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

Размер файла (attachment_file_size) измеряется в байтах. Ссылка на файл заявки временная: она работает в течение 30 секунд после создания.

Пример URI

GET https://<account>.okdesk.ru/api/v1/companies/166/attachments/22?api_token=3e9a214215f493c4

Параметры URI

СкрытьПоказать

api_token: string (обязательное) Пример: 3e9a214215f493c4
Ключ авторизации.
company_id: integer (обязательное) Пример: 166
ID компании.
attachment_id: integer (обязательное) Пример: 22
ID файла.

Ответ 200

СкрытьПоказать

Заголовки

Content-Type: application/json

Тело

{
  "id": 22,
  "attachment_file_name": "image.jpg",
  "description": "",
  "attachment_file_size": 7955,
  "is_public": true,
  "created_at": "2019-10-29T17:31:30.675+03:00",
  "attachment_url": "https://static.okdesk.ru/attachments/attachments/000/000/150/original/hqdefault.jpg"
}

Архивация компании

PATCH`/api/v1/companies/{id}/activations{?api_token}`

Название	Тип	Обязательность	Описание
active	boolean	обязательный	Статус активности компании

Архивация компании доступна для сотрудников в соответствии с настройками прав доступа.

Пример URI

PATCH https://<account>.okdesk.ru/api/v1/companies/1040/activations?api_token=3e9a214215f493c4

Параметры URI

СкрытьПоказать

api_token: string (обязательное) Пример: 3e9a214215f493c4
Ключ авторизации.
id: integer (обязательное) Пример: 1040
ID компании.

Запрос

СкрытьПоказать

Заголовки

Content-Type: application/json

Тело

{
  "active": true
}

Ответ 200

СкрытьПоказать

Заголовки

Content-Type: application/json

Тело

{
  "id": 1040,
  "name": "Okdesk",
  "additional_name": "Help Desk система для сервисных компаний",
  "site": "http://okdesk.ru",
  "email": "info@okdesk.ru",
  "phone": "+7(499)703-47-20",
  "address": "г. Москва, ул. Хелпдескрешений 11, офис 330",
  "comment": "Okdesk — простая и удобная облачная Help Desk система для автоматизации процессов поддержки в малых и средних сервисных компаниях. Позволяет вести учет заявок в службу поддержки, клиентов и всех взаимодействий с ними, условий предоставления услуг (SLA), договоров, их сроков действия и этапов оплаты.",
  "crm_1c_id": "67067c3a29a8",
  "active": true,
  "coordinates": [
    53.2184321,
    44.9998082
  ],
  "observers": [
    {
      "id": 2,
      "name": "Эрдингтон Филлип Витальевич"
    },
    {
      "id": 1,
      "name": "Иванов Иван Викторович"
    }
  ],
  "contacts": [],
  "default_assignee": {
    "id": 1,
    "name": "Иванов Иван Викторович"
  },
  "default_assignee_group": {
    "id": 1,
    "name": "Группа мониторинга",
    "active": true,
    "description": ""
  },
  "category": {
    "id": 2,
    "code": "client",
    "name": "Клиент",
    "color": "#5cb85c"
  },
  "attachments": [],
  "parameters": [
    {
      "code": "code1",
      "name": "Номер документа",
      "field_type": "ftstring",
      "value": "123456789"
    },
    {
      "code": "code2",
      "name": "Дата начала сотрудничества",
      "field_type": "ftdate",
      "value": "2019-02-15"
    },
    {
      "code": "code3",
      "name": "Вип обслуживание",
      "field_type": "ftcheckbox",
      "value": true
    }
  ]
}

Договоры ¶

Поиск договора

GET`/api/v1/agreements/{?api_token,search_string}`

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

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

Пример URI

GET https://<account>.okdesk.ru/api/v1/agreements/?api_token=3e9a214215f493c4&search_string=desk

Параметры URI

СкрытьПоказать

api_token: string (обязательное) Пример: 3e9a214215f493c4
Ключ авторизации.
search_string: string (обязательное) Пример: desk
Искомая подстрока

Ответ 200

СкрытьПоказать

Заголовки

Content-Type: application/json

Тело

[
  {
    "id": 1,
    "title": "Договор технического обслуживания №2016-03/1",
    "start_date": "23-04-2018",
    "end_date": "24-04-2018",
    "cost": 322,
    "crm_1c_id": "desktop_1",
    "active": false,
    "company_ids": [
      1
    ],
    "default_assignee": {
      "employee": {
        "id": 1,
        "name": "Иванов Иван Викторович"
      },
      "group": {
        "id": 1,
        "name": "Отдел планирования"
      }
    },
    "observers": {
      "employees": [
        {
          "id": 2,
          "name": "Эрдингтон Филлип Витальевич"
        },
        {
          "id": 1,
          "name": "Иванов Иван Викторович"
        }
      ],
      "groups": [
        {
          "id": 5,
          "name": "Отдел контроля качества"
        }
      ]
    },
    "service_periods": [
      {
        "id": 1,
        "agreement_id": 1,
        "start_date": "23-04-2018",
        "end_date": "24-04-2018",
        "cost": 322,
        "comment": "Комментарий",
        "reminder_date": "24-04-2018",
        "postpay": false,
        "paid": true
      }
    ],
    "parameters": [
      {
        "code": "attr1",
        "name": "Номер документа",
        "field_type": "ftstring",
        "value": "2368590"
      }
    ]
  }
]

Информация о договоре

GET`/api/v1/agreements/{id}{?api_token}`

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

Пример URI

GET https://<account>.okdesk.ru/api/v1/agreements/1?api_token=3e9a214215f493c4

Параметры URI

СкрытьПоказать

api_token: string (обязательное) Пример: 3e9a214215f493c4
Ключ авторизации.
id: integer (обязательное) Пример: 1
ID договора.

Ответ 200

СкрытьПоказать

Заголовки

Content-Type: application/json

Тело

{
  "id": 1,
  "title": "Договор технического обслуживания №2016-03/1",
  "start_date": "23-04-2018",
  "end_date": "24-04-2018",
  "cost": 322,
  "crm_1c_id": "67067c3a29a8",
  "active": true,
  "company_ids": [
    1
  ],
  "default_assignee": {
    "employee": {
      "id": 1,
      "name": "Иванов Иван Викторович"
    },
    "group": {
      "id": 1,
      "name": "Отдел планирования"
    }
  },
  "observers": {
    "employees": [
      {
        "id": 2,
        "name": "Эрдингтон Филлип Витальевич"
      },
      {
        "id": 1,
        "name": "Иванов Иван Викторович"
      }
    ],
    "groups": [
      {
        "id": 5,
        "name": "Отдел контроля качества"
      }
    ]
  },
  "billing_status": "active_now",
  "service_periods": [
    {
      "id": 1,
      "agreement_id": 1,
      "start_date": "23-04-2018",
      "end_date": "24-04-2018",
      "cost": 322,
      "comment": "Комментарий",
      "reminder_date": "24-04-2018",
      "postpay": false,
      "paid": true
    }
  ],
  "parameters": [
    {
      "code": "attr1",
      "name": "Номер документа",
      "field_type": "ftstring",
      "value": "2368590"
    }
  ]
}

Редактирование договора

PATCH`/api/v1/agreements/{id}{?api_token}`

Название	Тип	Обязательность	Описание
title	string	опционально	Название договора
crm_1c_id	string	опционально	Идентификатор объекта в 1С. Необходим для интеграции с 1С, не отображается в web-интерфейсе
active	boolean	опционально	Статус активности договора
default_assignee_id	integer	опционально	ID ответственного по умолчанию
default_assignee_group_id	integer	опционально	ID ответственной группы по умолчанию
observer_ids	array of int	опционально	Массив из ID пользователей, являющихся наблюдателями договора
observer_group_ids	array of int	опционально	Массив из ID групп сотрудников, являющихся наблюдателями договора
company_ids	array	опционально	Массив из ID компаний. Для удаления компаний из договора нужно передавать значение []
custom_parameters	associative array	опционально	Дополнительные атрибуты договора

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

Пример URI

PATCH https://<account>.okdesk.ru/api/v1/agreements/1?api_token=3e9a214215f493c4

Параметры URI

СкрытьПоказать

api_token: string (обязательное) Пример: 3e9a214215f493c4
Ключ авторизации.
id: integer (обязательное) Пример: 1
ID договора.

Запрос

СкрытьПоказать

Заголовки

Content-Type: application/json

Тело

{
  "agreement": {
    "title": "Договор технического обслуживания №2016-03/1",
    "crm_1c_id": "67067c3a29a8",
    "company_ids": [
      1,
      2
    ],
    "observer_ids": [
      1,
      2
    ],
    "active": false,
    "custom_parameters": {
      "code2": "2019-02-15"
    }
  }
}

Ответ 200

СкрытьПоказать

Заголовки

Content-Type: application/json

Тело

{
  "id": 1,
  "title": "Договор технического обслуживания №2016-03/1",
  "start_date": "23-04-2018",
  "end_date": "24-04-2018",
  "cost": 322,
  "crm_1c_id": "67067c3a29a8",
  "active": false,
  "company_ids": [
    1,
    2
  ],
  "default_assignee": {
    "employee": {
      "id": 1,
      "name": "Иванов Иван Викторович"
    },
    "group": {
      "id": 1,
      "name": "Отдел планирования"
    }
  },
  "observers": {
    "employees": [
      {
        "id": 2,
        "name": "Эрдингтон Филлип Витальевич"
      },
      {
        "id": 1,
        "name": "Иванов Иван Викторович"
      }
    ],
    "groups": [
      {
        "id": 5,
        "name": "Отдел контроля качества"
      }
    ]
  },
  "service_periods": [
    {
      "id": 1,
      "agreement_id": 1,
      "start_date": "23-04-2018",
      "end_date": "24-04-2018",
      "cost": 322,
      "comment": "Комментарий",
      "reminder_date": "24-04-2018",
      "postpay": false,
      "paid": true
    }
  ],
  "parameters": [
    {
      "code": "code2",
      "name": "Дата заключения договора",
      "field_type": "ftdate",
      "value": "2019-02-15"
    }
  ]
}

Создание договора

POST`/api/v1/companies/{company_id}/agreements{?api_token}`

Название	Тип	Обязательность	Описание
title	string	обязательный	Название договора
crm_1c_id	string	опционально	Идентификатор объекта в 1С. Необходим для интеграции с 1С, не отображается в web-интерфейсе
default_assignee_id	integer	опционально	ID ответственного по умолчанию
default_assignee_group_id	integer	опционально	ID ответственной группы по умолчанию
observer_ids	array of int	опционально	Массив из ID пользователей, являющихся наблюдателями договора
observer_group_ids	array of int	опционально	Массив из ID групп сотрудников, являющихся наблюдателями договора
custom_parameters	associative array	опционально	Дополнительные атрибуты договора

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

Пример URI

POST https://<account>.okdesk.ru/api/v1/companies/1/agreements?api_token=3e9a214215f493c4

Параметры URI

СкрытьПоказать

api_token: string (обязательное) Пример: 3e9a214215f493c4
Ключ авторизации.
company_id: integer (обязательное) Пример: 1
ID компании.

Запрос

СкрытьПоказать

Заголовки

Content-Type: application/json

Тело

{
  "agreement": {
    "title": "Договор технического обслуживания №2016-03/1",
    "crm_1c_id": "67067c3a29a8",
    "default_assignee_id": 1,
    "default_assignee_group_id": 1,
    "observer_ids": [
      1,
      2
    ],
    "observer_group_ids": [
      5
    ],
    "custom_parameters": {
      "code2": "2019-02-12"
    }
  }
}

Ответ 200

СкрытьПоказать

Заголовки

Content-Type: application/json

Тело

{
  "id": 1,
  "title": "Договор технического обслуживания №2016-03/1",
  "start_date": null,
  "end_date": null,
  "cost": 0,
  "crm_1c_id": "67067c3a29a8",
  "active": true,
  "company_ids": [
    1
  ],
  "default_assignee": {
    "employee": {
      "id": 1,
      "name": "Иванов Иван Викторович"
    },
    "group": {
      "id": 1,
      "name": "Отдел планирования"
    }
  },
  "observers": {
    "employees": [
      {
        "id": 2,
        "name": "Эрдингтон Филлип Витальевич"
      },
      {
        "id": 1,
        "name": "Иванов Иван Викторович"
      }
    ],
    "groups": [
      {
        "id": 5,
        "name": "Отдел контроля качества"
      }
    ]
  },
  "service_periods": [],
  "parameters": [
    {
      "code": "code2",
      "name": "Дата заключения договора",
      "field_type": "ftdate",
      "value": "2019-02-12"
    }
  ]
}

Получение списка договоров компании

GET`/api/v1/companies/{company_id}/agreements{?api_token}`

Метод возвращает список ID договоров, связанных с переданной компанией.

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

Пример URI

GET https://<account>.okdesk.ru/api/v1/companies/1/agreements?api_token=3e9a214215f493c4

Параметры URI

СкрытьПоказать

api_token: string (обязательное) Пример: 3e9a214215f493c4
Ключ авторизации.
company_id: integer (обязательное) Пример: 1
ID компании.

Ответ 200

СкрытьПоказать

Заголовки

Content-Type: application/json

Тело

[
  1,
  4,
  5,
  7
]

Добавление сервисного периода

POST`/api/v1/agreements/{agreement_id}/service_periods{?api_token}`

Название	Тип	Обязательность	Описание
start_date	string	обязательный	Дата начала Пример: start_date=23-04-2018
end_date	string	обязательный	Дата конца Пример: end_date=24-04-2018
cost	float	необязательный	Стоимость
comment	string	необязательный	Комментарий
reminder_date	string	необязательный	Дата напоминания о завершении Пример: reminder_date=24-04-2018
postpay	boolean	необязательный	Признак постоплаты
paid	boolean	необязательный	Признак оплаченности

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

Пример URI

POST https://<account>.okdesk.ru/api/v1/agreements/1/service_periods?api_token=3e9a214215f493c4

Параметры URI

СкрытьПоказать

api_token: string (обязательное) Пример: 3e9a214215f493c4
Ключ авторизации.
agreement_id: integer (обязательное) Пример: 1
ID договора.

Запрос

СкрытьПоказать

Заголовки

Content-Type: application/json

Тело

{
  "service_period": {
    "start_date": "23-04-2018",
    "end_date": "24-04-2018",
    "cost": 322,
    "comment": "Комментарий",
    "reminder_date": "24-04-2018",
    "postpay": false,
    "paid": true
  }
}

Ответ 200

СкрытьПоказать

Заголовки

Content-Type: application/json

Тело

{
  "id": 1,
  "agreement_id": 1,
  "start_date": "23-04-2018",
  "end_date": "24-04-2018",
  "cost": 322,
  "comment": "Комментарий",
  "reminder_date": "24-04-2018",
  "postpay": false,
  "paid": true
}

Изменение сервисного периода

PATCH`/api/v1/agreements/{agreement_id}/service_periods/{id}{?api_token}`

Название	Тип	Обязательность	Описание
start_date	string	необязательный	Дата начала Пример: start_date=23-04-2018
end_date	string	необязательный	Дата конца Пример: end_date=24-04-2018
cost	float	необязательный	Стоимость
comment	string	необязательный	Комментарий
reminder_date	string	необязательный	Дата напоминания о завершении Пример: reminder_date=24-04-2018
postpay	boolean	необязательный	Признак постоплаты
paid	boolean	необязательный	Признак оплаченности

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

Пример URI

PATCH https://<account>.okdesk.ru/api/v1/agreements/1/service_periods/1?api_token=3e9a214215f493c4

Параметры URI

СкрытьПоказать

api_token: string (обязательное) Пример: 3e9a214215f493c4
Ключ авторизации.
agreement_id: integer (обязательное) Пример: 1
ID договора.
id: integer (обязательное) Пример: 1
ID сервисного периода.

Запрос

СкрытьПоказать

Заголовки

Content-Type: application/json

Тело

{
  "service_period": {
    "start_date": "23-04-2018",
    "end_date": "24-04-2018",
    "cost": 322,
    "comment": "Комментарий",
    "reminder_date": "24-04-2018",
    "postpay": false,
    "paid": true
  }
}

Ответ 200

СкрытьПоказать

Заголовки

Content-Type: application/json

Тело

{
  "id": 1,
  "agreement_id": 1,
  "start_date": "23-04-2018",
  "end_date": "24-04-2018",
  "cost": 322,
  "comment": "Комментарий",
  "reminder_date": "24-04-2018",
  "postpay": false,
  "paid": true
}

Удаление сервисного периода

DELETE`/api/v1/agreements/{agreement_id}/service_periods/{id}{?api_token}`

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

Пример URI

DELETE https://<account>.okdesk.ru/api/v1/agreements/1/service_periods/1?api_token=3e9a214215f493c4

Параметры URI

СкрытьПоказать

api_token: string (обязательное) Пример: 3e9a214215f493c4
Ключ авторизации.
agreement_id: integer (обязательное) Пример: 1
ID договора.
id: integer (обязательное) Пример: 1
ID сервисного периода.

Ответ 200

СкрытьПоказать

Заголовки

Content-Type: application/json

Тело

{
  "id": 1,
  "agreement_id": 1,
  "start_date": "23-10-2018",
  "end_date": "24-04-2018",
  "cost": 322,
  "comment": "Комментарий",
  "reminder_date": "24-04-2018",
  "postpay": false,
  "paid": true
}

Заявки ¶

Создание заявки

POST`/api/v1/issues/{?api_token}`

Название	Тип	Обязательность	Описание
title	string	обязательный	Название заявки
description	string	опционально	Описание заявки
company_id	string	опционально	ID компании, привязанной к заявке
contact_id	string	опционально	ID контактного лица, привязанного к заявке
agreement_id	string	опционально	ID договора, привязанного к заявке
assignee_id	string	опционально	ID ответственного за заявку
group_id	string	опционально	ID ответственной группы сотрудника
observer_ids	array of integer	опционально	Массив из ID сотрудников, являющихся наблюдателями заявки
observer_group_ids	array of integer	опционально	Массив из ID групп сотрудников, являющихся наблюдателями заявки
contact_observer_ids	array of integer	опционально	Массив из ID контактных лиц, являющихся наблюдателями заявки
maintenance_entity_id	string	опционально	ID объекта обслуживания, привязанного к заявке
equipment_ids	array	опционально	Массив из ID оборудования, привязанного к заявке
type	string	опционально	Код типа заявки
priority	string	опционально	Код приоритета заявки
deadline_at	string	опционально	Плановая дата решения
start_execution_until	string	опционально	Назначена на (дата/время)
planned_execution_in_minutes	number	опционально	Плановая продолжительность (в минутах)
custom_parameters	associative array	опционально	Дополнительные атрибуты заявки
parent_id	string	опционально	ID родительской заявки
author	associative array	опционально	Автор заявки. Для указания автора необходимо передать 2 параметра: id (ID автора, string, обязательный) и type (Тип автора, string, обязательный, допустимые значения: employee и contact). Параметр доступен только для ключей, связанных с пользовательской ролью “Администратор”.

Если Тип (type) или Приоритет (priority) пустые, то заявка будет создана с приоритетом и типом, установленными “по умолчанию” в настройках аккаунта.

Параметры “Назначена на”(start_execution_until) и “Плановая продолжительность” (planned_execution_in_minutes) доступны для ключей, связанных с сотрудниками.

Для ключей, связанных с сотрудниками, создание заявки, а также добавление поля “Плановая дата решения” доступно в соответствии с настройками прав доступа. Указать компанию при создании заявки возможно только в том случае, если связанный с ключом сотрудник имеет право на создание заявок по компании в соответствии с настройками прав доступа. Указать контакта при создании заявки возможно только в том случае, если связанный с ключом сотрудник имеет право на создание заявок для переданного контактного лица в соответствии с настройками прав доступа. Указать оборудование при создании заявки возможно только в том случае, если связанный с ключом сотрудник имеет право на создание заявок по оборудованию в соответствии с настройками прав доступа. Указать объект обслуживания возможно только в том случае, если связанный с ключом сотрудник имеет право на создание заявки по объекту обслуживания в соответствии с настройками прав доступа. Указать договор возможно только в том случае, если связанный с ключом сотрудник имеет право на создание заявки по договору в соответствии с настройками прав доступа. Для ключей, связанных с контактными лицами, при создании заявки будут игнорироваться параметры “Ответственный” (будет определяться автоматически по заложенным в аккаунте правилам), “Наблюдатели“ (будут определяться автоматически по заложенным в аккаунте правилам) и “Компания” (будет автоматически подставляться компания, связанная с контактным лицом), а параметры “Контактное лицо”, “Договор”, “Связанное оборудование” и “Объект обслуживания” будут проверяться на соответствие переданных значений с контактным лицом компании.

Название	Тип	Обязательность	Описание
attachment	string	обязательный	Прикрепляемый файл
is_public	string	опционально	Публичность файла
description	string	опционально	Описание файла

Содержание запроса с прикрепленными файлами должно быть в виде multipart/form-data и содержать соответствующий заголовок.

Пример URI

POST https://<account>.okdesk.ru/api/v1/issues/?api_token=3e9a214215f493c4

Параметры URI

СкрытьПоказать

api_token: string (обязательное) Пример: 3e9a214215f493c4
Ключ авторизации.

Запрос с корректными параметрами

СкрытьПоказать

Заголовки

Content-Type: application/json

Тело

{
  "issue": {
    "title": "Не работает ноутбук",
    "description": "Ноутбук перестал запускаться, просьба разобраться",
    "company_id": "33",
    "contact_id": "4",
    "agreement_id": "12",
    "type": "service",
    "priority": "high",
    "maintenance_entity_id": "15",
    "equipment_ids": [
      "6",
      "8"
    ],
    "deadline_at": "2018-05-09 09:15",
    "custom_parameters": {
      "address": "ул. Московская 2",
      "checked": true
    },
    "parent_id": "102",
    "author": {
      "id": "1",
      "type": "contact"
    },
    "observer_ids": [
      2,
      5,
      7
    ],
    "observer_group_ids": [
      4,
      10
    ],
    "contact_observer_ids": [
      56,
      86
    ]
  }
}

Запрос с прикрепленными файлами

СкрытьПоказать

Заголовки

Content-Type: multipart/form-data

Тело

curl  -H "Content-Type: multipart/form-data" -F "issue[title]=Не работает ноутбук" -F "issue[priority]=high"
-F "issue[observer_ids][]=2" -F "issue[observer_ids][]=5" -F "issue[observer_group_ids][]=1"
-F "issue[attachments][0][attachment]=@/home/user/file.jpg" -F "issue[attachments][0][is_public]=true"
-F "issue[attachments][0][description]=Условия гарантии"
-F "issue[attachments][1][attachment]=@/home/user/file.docx" -F "issue[attachments][1][is_public]=false"
https://<account>.okdesk.ru/api/v1/issues/{?api_token}

где @/home/user/file.jpg — это путь к локальному файлу
пример для windows: @"C:/myfile.txt"

Ответ 200

СкрытьПоказать

Заголовки

Content-Type: application/json

Тело

{
  "id": 237
}

Запрос с некорректными параметрами

СкрытьПоказать

Заголовки

Content-Type: application/json

Тело

{
    "issue": {
        "title": "Сломалась розетка",
        "company_id": "-5",
        "type": "unknown",
        "priority": 'high',
        "custom_parameters": {
            "total": "4"
        },
        "parent_id": "102"
    }
}

Ответ 422

СкрытьПоказать

Заголовки

Content-Type: application/json

Тело

{
  "errors": {
    "company_id": "Записи -5 не существует",
    "type": "Записи unknown не существует",
    "custom_parameters_total": "дополнительный параметр total не существует"
  }
}

Смена ответственного за заявку

PATCH`/api/v1/issues/{issue_id}/assignees{?api_token}`

Название	Тип	Обязательность	Описание
assignee_id	string	опционально	ID ответственного за заявку
group_id	string	опционально	ID ответственной группы

Один из параметров (assignee_id, group_id) должен быть обязательно заполнен

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

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

Пример URI

PATCH https://<account>.okdesk.ru/api/v1/issues/763/assignees?api_token=3e9a214215f493c4

Параметры URI

СкрытьПоказать

api_token: string (обязательное) Пример: 3e9a214215f493c4
Ключ авторизации.
issue_id: integer (обязательное) Пример: 763
ID заявки.

Запрос

СкрытьПоказать

Заголовки

Content-Type: application/json

Тело

{
  "assignee_id": "1",
  "group_id": "4"
}

Ответ 200

СкрытьПоказать

Заголовки

Content-Type: application/json

Тело

{
  "id": 153,
  "title": "Требуется мастер на выезд",
  "description": "",
  "created_at": "2016-03-15T18:05:17.568+03:00",
  "completed_at": "2016-05-19T10:54:09.987+03:00",
  "deadline_at": "2019-09-24T14:35:00.000+03:00",
  "source": "from_employee",
  "spent_time_total": 0,
  "start_execution_until": "2016-03-16T09:05:17.568+03:00",
  "planned_execution_in_hours": 12,
  "planned_reaction_at": "2016-04-11T11:00:00.000+03:00",
  "reacted_at": "2016-04-10T18:43:44.951+03:00",
  "updated_at": "2016-08-23T09:39:35.428+03:00",
  "delayed_to": null,
  "company_id": 40,
  "group_id": 3,
  "coexecutors": [
    {
      "id": 3,
      "name": "Артамонов Анатолий Маратович",
      "group": {
        "id": 1,
        "name": "Отдел планирования"
      }
    }
  ],
  "service_object_id": null,
  "equipment_ids": [],
  "attachments": [
    {
      "id": 8,
      "attachment_file_name": "photo.jpg",
      "description": "Фотография неисправности",
      "attachment_file_size": 4149,
      "is_public": false,
      "created_at": "2016-09-30T09:28:50.499+03:00"
    }
  ],
  "status_times": {
    "opened": {
      "total": "134 д., 14 ч., 57 м.",
      "on_schedule_total": "36 д., 0 ч., 39 м."
    },
    "completed": {
      "total": "0 д., 0 ч., 0 м.",
      "on_schedule_total": "0 д., 0 ч., 0 м."
    }
  },
  "parameters": [],
  "comments": {
    "count": 5,
    "last_at": "2018-07-05T16:06:10.000+03:00"
  },
  "parent_id": null,
  "child_ids": [],
  "type": {
    "id": 2,
    "code": "service",
    "name": "Обслуживание",
    "available_for_client": true
  },
  "priority": {
    "code": "low",
    "name": "Низкий"
  },
  "status": {
    "code": "opened",
    "name": "Открыта"
  },
  "old_status": {
    "code": "completed",
    "name": "Решена"
  },
  "rate": {
    "id": 3,
    "value": "normal"
  },
  "address": {
    "coordinates": [
      53.2184321,
      44.9998082
    ],
    "value": "г Пенза ул Гагарина д 13"
  },
  "observers": [
    {
      "id": 113,
      "type": "employee",
      "name": "Антонов Петр Захарович"
    },
    {
      "id": 121,
      "type": "employee",
      "name": "Акмаев Артем Викторович"
    }
  ],
  "observer_groups": [
    {
      "id": 5,
      "name": "Отдел контроля качества"
    }
  ],
  "contact": {
    "id": 3020,
    "name": "Егор Егоров"
  },
  "agreement": null,
  "assignee": {
    "id": 1,
    "name": "Иванов Иван Викторович"
  },
  "author": {
    "id": 3020,
    "name": "Егор Егоров"
  }
}

Добавление соисполнителя заявки

POST`/api/v1/issues/{issue_id}/coexecutors{?api_token}`

Название	Тип	Обязательность	Описание
coexecutor_id	integer	обязательный	ID соисполнителя заявки
group_id	integer	опционально	ID группы соисполнителя

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

Пример URI

POST https://<account>.okdesk.ru/api/v1/issues/763/coexecutors?api_token=3e9a214215f493c4

Параметры URI

СкрытьПоказать

api_token: string (обязательное) Пример: 3e9a214215f493c4
Ключ авторизации.
issue_id: integer (обязательное) Пример: 763
ID заявки.

Запрос

СкрытьПоказать

Заголовки

Content-Type: application/json

Тело

{
  "coexecutor_id": 1,
  "group_id": 4
}

Ответ 200

СкрытьПоказать

Заголовки

Content-Type: application/json

Тело

{
  "id": 153,
  "title": "Требуется мастер на выезд",
  "description": "",
  "created_at": "2016-03-15T18:05:17.568+03:00",
  "completed_at": "2016-05-19T10:54:09.987+03:00",
  "deadline_at": "2019-09-24T14:35:00.000+03:00",
  "source": "from_employee",
  "spent_time_total": 0,
  "start_execution_until": "2016-03-16T09:05:17.568+03:00",
  "planned_execution_in_hours": 12,
  "planned_reaction_at": "2016-04-11T11:00:00.000+03:00",
  "reacted_at": "2016-04-10T18:43:44.951+03:00",
  "updated_at": "2016-08-23T09:39:35.428+03:00",
  "delayed_to": null,
  "company_id": 40,
  "group_id": 3,
  "coexecutors": [
    {
      "id": 1,
      "name": "Волков Анатолий Маратович",
      "group": {
        "id": 4,
        "name": "Отдел бухгалтерии"
      }
    }
  ],
  "service_object_id": null,
  "equipment_ids": [],
  "attachments": [
    {
      "id": 8,
      "attachment_file_name": "photo.jpg",
      "description": "Фотография неисправности",
      "attachment_file_size": 4149,
      "is_public": false,
      "created_at": "2016-09-30T09:28:50.499+03:00"
    }
  ],
  "status_times": {
    "opened": {
      "total": "134 д., 14 ч., 57 м.",
      "on_schedule_total": "36 д., 0 ч., 39 м."
    },
    "completed": {
      "total": "0 д., 0 ч., 0 м.",
      "on_schedule_total": "0 д., 0 ч., 0 м."
    }
  },
  "parameters": [],
  "comments": {
    "count": 5,
    "last_at": "2018-07-05T16:06:10.000+03:00"
  },
  "parent_id": null,
  "child_ids": [],
  "type": {
    "id": 2,
    "code": "service",
    "name": "Обслуживание",
    "available_for_client": true
  },
  "priority": {
    "code": "low",
    "name": "Низкий"
  },
  "status": {
    "code": "opened",
    "name": "Открыта"
  },
  "old_status": {
    "code": "completed",
    "name": "Решена"
  },
  "rate": {
    "id": 3,
    "value": "normal"
  },
  "address": {
    "coordinates": [
      53.2184321,
      44.9998082
    ],
    "value": "г Пенза ул Гагарина д 13"
  },
  "observers": [
    {
      "id": 113,
      "type": "employee",
      "name": "Антонов Петр Захарович"
    },
    {
      "id": 121,
      "type": "employee",
      "name": "Акмаев Артем Викторович"
    }
  ],
  "observer_groups": [
    {
      "id": 5,
      "name": "Отдел контроля качества"
    }
  ],
  "contact": {
    "id": 3020,
    "name": "Егор Егоров"
  },
  "agreement": null,
  "assignee": {
    "id": 1,
    "name": "Иванов Иван Викторович"
  },
  "author": {
    "id": 3020,
    "name": "Егор Егоров"
  }
}

Удаление соисполнителя заявки

DELETE`/api/v1/issues/{issue_id}/coexecutors{?api_token}`

Название	Тип	Обязательность	Описание
coexecutor_id	integer	обязательный	ID соисполнителя заявки

Удаление соисполнителя заявки будет выполнено только в том случае, если связанный с ключом пользователь имеет права на просмотр заявки и редактирование соисполнителей заявки в соответствии с настройками прав доступа. Для ключей, связанных с контактными лицами, данный метод недоступен.

Пример URI

DELETE https://<account>.okdesk.ru/api/v1/issues/763/coexecutors?api_token=3e9a214215f493c4

Параметры URI

СкрытьПоказать

api_token: string (обязательное) Пример: 3e9a214215f493c4
Ключ авторизации.
issue_id: integer (обязательное) Пример: 763
ID заявки.

Запрос

СкрытьПоказать

Заголовки

Content-Type: application/json

Тело

{
  "coexecutor_id": 1
}

Ответ 200

СкрытьПоказать

Заголовки

Content-Type: application/json

Тело

{
  "id": 153,
  "title": "Требуется мастер на выезд",
  "description": "",
  "created_at": "2016-03-15T18:05:17.568+03:00",
  "completed_at": "2016-05-19T10:54:09.987+03:00",
  "deadline_at": "2019-09-24T14:35:00.000+03:00",
  "source": "from_employee",
  "spent_time_total": 0,
  "start_execution_until": "2016-03-16T09:05:17.568+03:00",
  "planned_execution_in_hours": 12,
  "planned_reaction_at": "2016-04-11T11:00:00.000+03:00",
  "reacted_at": "2016-04-10T18:43:44.951+03:00",
  "updated_at": "2016-08-23T09:39:35.428+03:00",
  "delayed_to": null,
  "company_id": 40,
  "group_id": null,
  "coexecutors": [],
  "service_object_id": null,
  "equipment_ids": [],
  "attachments": [
    {
      "id": 8,
      "attachment_file_name": "photo.jpg",
      "description": "Фотография неисправности",
      "attachment_file_size": 4149,
      "is_public": false,
      "created_at": "2016-09-30T09:28:50.499+03:00"
    }
  ],
  "status_times": {
    "opened": {
      "total": "134 д., 14 ч., 57 м.",
      "on_schedule_total": "36 д., 0 ч., 39 м."
    },
    "completed": {
      "total": "0 д., 0 ч., 0 м.",
      "on_schedule_total": "0 д., 0 ч., 0 м."
    }
  },
  "parameters": [],
  "comments": {
    "count": 5,
    "last_at": "2018-07-05T16:06:10.000+03:00"
  },
  "parent_id": null,
  "child_ids": [],
  "type": {
    "id": 2,
    "code": "service",
    "name": "Обслуживание",
    "available_for_client": true
  },
  "priority": {
    "code": "low",
    "name": "Низкий"
  },
  "status": {
    "code": "opened",
    "name": "Открыта"
  },
  "old_status": {
    "code": "completed",
    "name": "Решена"
  },
  "rate": {
    "id": 3,
    "value": "normal"
  },
  "address": {
    "coordinates": [
      53.2184321,
      44.9998082
    ],
    "value": "г Пенза ул Гагарина д 13"
  },
  "observers": [
    {
      "id": 113,
      "type": "employee",
      "name": "Антонов Петр Захарович"
    },
    {
      "id": 121,
      "type": "employee",
      "name": "Акмаев Артем Викторович"
    }
  ],
  "observer_groups": [
    {
      "id": 5,
      "name": "Отдел контроля качества"
    }
  ],
  "contact": {
    "id": 3020,
    "name": "Егор Егоров"
  },
  "agreement": null,
  "assignee": {
    "id": 1,
    "name": "Иванов Иван Викторович"
  },
  "author": {
    "id": 3020,
    "name": "Егор Егоров"
  }
}

Добавление наблюдателя заявки

PATCH`/api/v1/issues/{issue_id}/observers{?api_token}`

Название	Тип	Обязательность	Описание
observer_id	integer	обязательный	ID наблюдателя заявки
observer_type	string	обязательный	Тип наблюдателя. Допустимые значения: employee, contact, group.

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

Пример URI

PATCH https://<account>.okdesk.ru/api/v1/issues/763/observers?api_token=3e9a214215f493c4

Параметры URI

СкрытьПоказать

api_token: string (обязательное) Пример: 3e9a214215f493c4
Ключ авторизации.
issue_id: integer (обязательное) Пример: 763
ID заявки.

Запрос

СкрытьПоказать

Заголовки

Content-Type: application/json

Тело

{
  "observer_id": 3,
  "observer_type": "employee"
}

Ответ 200

СкрытьПоказать

Заголовки

Content-Type: application/json

Тело

{
  "id": 153,
  "title": "Требуется мастер на выезд",
  "description": "",
  "created_at": "2016-03-15T18:05:17.568+03:00",
  "completed_at": "2016-05-19T10:54:09.987+03:00",
  "deadline_at": "2019-09-24T14:35:00.000+03:00",
  "source": "from_employee",
  "spent_time_total": 0,
  "start_execution_until": "2016-03-16T09:05:17.568+03:00",
  "planned_execution_in_hours": 12,
  "planned_reaction_at": "2016-04-11T11:00:00.000+03:00",
  "reacted_at": "2016-04-10T18:43:44.951+03:00",
  "updated_at": "2016-08-23T09:39:35.428+03:00",
  "delayed_to": null,
  "company_id": 40,
  "group_id": 3,
  "coexecutors": [
    {
      "id": 3,
      "name": "Артамонов Анатолий Маратович",
      "group": {
        "id": 1,
        "name": "Отдел планирования"
      }
    }
  ],
  "service_object_id": null,
  "equipment_ids": [],
  "attachments": [
    {
      "id": 8,
      "attachment_file_name": "photo.jpg",
      "description": "Фотография неисправности",
      "attachment_file_size": 4149,
      "is_public": false,
      "created_at": "2016-09-30T09:28:50.499+03:00"
    }
  ],
  "status_times": {
    "opened": {
      "total": "134 д., 14 ч., 57 м.",
      "on_schedule_total": "36 д., 0 ч., 39 м."
    },
    "completed": {
      "total": "0 д., 0 ч., 0 м.",
      "on_schedule_total": "0 д., 0 ч., 0 м."
    }
  },
  "parameters": [],
  "comments": {
    "count": 5,
    "last_at": "2018-07-05T16:06:10.000+03:00"
  },
  "parent_id": null,
  "child_ids": [],
  "type": {
    "id": 2,
    "code": "service",
    "name": "Обслуживание",
    "available_for_client": true
  },
  "priority": {
    "code": "low",
    "name": "Низкий"
  },
  "status": {
    "code": "opened",
    "name": "Открыта"
  },
  "old_status": {
    "code": "completed",
    "name": "Решена"
  },
  "rate": {
    "id": 3,
    "value": "normal"
  },
  "address": {
    "coordinates": [
      53.2184321,
      44.9998082
    ],
    "value": "г Пенза ул Гагарина д 13"
  },
  "observers": [
    {
      "id": 12,
      "type": "employee",
      "name": "Антонов Петр Захарович"
    }
  ],
  "observer_groups": [
    {
      "id": 5,
      "name": "Отдел контроля качества"
    }
  ],
  "contact": {
    "id": 3020,
    "name": "Егор Егоров"
  },
  "agreement": null,
  "assignee": {
    "id": 1,
    "name": "Иванов Иван Викторович"
  },
  "author": {
    "id": 3020,
    "name": "Егор Егоров"
  }
}

Удаление наблюдателя заявки

DELETE`/api/v1/issues/{issue_id}/observers{?api_token}`

Название	Тип	Обязательность	Описание
observer_id	integer	обязательный	ID наблюдателя заявки
observer_type	string	обязательный	Тип наблюдателя. Допустимые значения: employee, contact, group.

Удаление наблюдателя заявки будет выполнено только в том случае, если связанный с ключом пользователь имеет права на просмотр заявки и редактирование списка наблюдателей заявки или право на добавление себя в наблюдатели заявки в соответствии с настройками прав доступа. Для ключей, связанных с контактными лицами, данный метод недоступен.

Пример URI

DELETE https://<account>.okdesk.ru/api/v1/issues/763/observers?api_token=3e9a214215f493c4

Параметры URI

СкрытьПоказать

api_token: string (обязательное) Пример: 3e9a214215f493c4
Ключ авторизации.
issue_id: integer (обязательное) Пример: 763
ID заявки.

Запрос

СкрытьПоказать

Заголовки

Content-Type: application/json

Тело

{
  "observer_id": 3,
  "observer_type": "employee"
}

Ответ 200

СкрытьПоказать

Заголовки

Content-Type: application/json

Тело

{
  "id": 153,
  "title": "Требуется мастер на выезд",
  "description": "",
  "created_at": "2016-03-15T18:05:17.568+03:00",
  "completed_at": "2016-05-19T10:54:09.987+03:00",
  "deadline_at": "2019-09-24T14:35:00.000+03:00",
  "source": "from_employee",
  "spent_time_total": 0,
  "start_execution_until": "2016-03-16T09:05:17.568+03:00",
  "planned_execution_in_hours": 12,
  "planned_reaction_at": "2016-04-11T11:00:00.000+03:00",
  "reacted_at": "2016-04-10T18:43:44.951+03:00",
  "updated_at": "2016-08-23T09:39:35.428+03:00",
  "delayed_to": null,
  "company_id": 40,
  "group_id": 3,
  "coexecutors": [
    {
      "id": 3,
      "name": "Артамонов Анатолий Маратович",
      "group": {
        "id": 1,
        "name": "Отдел планирования"
      }
    }
  ],
  "service_object_id": null,
  "equipment_ids": [],
  "attachments": [
    {
      "id": 8,
      "attachment_file_name": "photo.jpg",
      "description": "Фотография неисправности",
      "attachment_file_size": 4149,
      "is_public": false,
      "created_at": "2016-09-30T09:28:50.499+03:00"
    }
  ],
  "status_times": {
    "opened": {
      "total": "134 д., 14 ч., 57 м.",
      "on_schedule_total": "36 д., 0 ч., 39 м."
    },
    "completed": {
      "total": "0 д., 0 ч., 0 м.",
      "on_schedule_total": "0 д., 0 ч., 0 м."
    }
  },
  "parameters": [],
  "comments": {
    "count": 5,
    "last_at": "2018-07-05T16:06:10.000+03:00"
  },
  "parent_id": null,
  "child_ids": [],
  "type": {
    "id": 2,
    "code": "service",
    "name": "Обслуживание",
    "available_for_client": true
  },
  "priority": {
    "code": "low",
    "name": "Низкий"
  },
  "status": {
    "code": "opened",
    "name": "Открыта"
  },
  "old_status": {
    "code": "completed",
    "name": "Решена"
  },
  "rate": {
    "id": 3,
    "value": "normal"
  },
  "address": {
    "coordinates": [
      53.2184321,
      44.9998082
    ],
    "value": "г Пенза ул Гагарина д 13"
  },
  "observers": [],
  "observer_groups": [
    {
      "id": 5,
      "name": "Отдел контроля качества"
    }
  ],
  "contact": {
    "id": 3020,
    "name": "Егор Егоров"
  },
  "agreement": null,
  "assignee": {
    "id": 1,
    "name": "Иванов Иван Викторович"
  },
  "author": {
    "id": 3020,
    "name": "Егор Егоров"
  }
}

Смена плановой даты решения заявки

PATCH`/api/v1/issues/{issue_id}/deadlines{?api_token}`

Название	Тип	Обязательность	Описание
deadline_at	string	обязательный	Плановая дата решения заявки

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

Пример URI

PATCH https://<account>.okdesk.ru/api/v1/issues/763/deadlines?api_token=3e9a214215f493c4

Параметры URI

СкрытьПоказать

api_token: string (обязательное) Пример: 3e9a214215f493c4
Ключ авторизации.
issue_id: integer (обязательное) Пример: 763
ID заявки.

Запрос

СкрытьПоказать

Заголовки

Content-Type: application/json

Тело

{
  "deadline_at": "2019-09-24 14:35"
}

Ответ 200

СкрытьПоказать

Заголовки

Content-Type: application/json

Тело

{
  "id": 153,
  "title": "Требуется мастер на выезд",
  "description": "",
  "created_at": "2016-03-15T18:05:17.568+03:00",
  "completed_at": "2016-05-19T10:54:09.987+03:00",
  "deadline_at": "2019-09-24T14:35:00.000+03:00",
  "source": "from_employee",
  "spent_time_total": 0,
  "start_execution_until": "2016-03-16T09:05:17.568+03:00",
  "planned_execution_in_hours": 12,
  "planned_reaction_at": "2016-04-11T11:00:00.000+03:00",
  "reacted_at": "2016-04-10T18:43:44.951+03:00",
  "updated_at": "2016-08-23T09:39:35.428+03:00",
  "delayed_to": null,
  "company_id": 40,
  "group_id": 3,
  "coexecutors": [
    {
      "id": 3,
      "name": "Артамонов Анатолий Маратович",
      "group": {
        "id": 1,
        "name": "Отдел планирования"
      }
    }
  ],
  "service_object_id": null,
  "equipment_ids": [],
  "attachments": [
    {
      "id": 8,
      "attachment_file_name": "photo.jpg",
      "description": "Фотография неисправности",
      "attachment_file_size": 4149,
      "is_public": false,
      "created_at": "2016-09-30T09:28:50.499+03:00"
    }
  ],
  "status_times": {
    "opened": {
      "total": "134 д., 14 ч., 57 м.",
      "on_schedule_total": "36 д., 0 ч., 39 м."
    },
    "completed": {
      "total": "0 д., 0 ч., 0 м.",
      "on_schedule_total": "0 д., 0 ч., 0 м."
    }
  },
  "parameters": [],
  "comments": {
    "count": 5,
    "last_at": "2018-07-05T16:06:10.000+03:00"
  },
  "parent_id": null,
  "child_ids": [],
  "type": {
    "id": 2,
    "code": "service",
    "name": "Обслуживание",
    "available_for_client": true
  },
  "priority": {
    "code": "low",
    "name": "Низкий"
  },
  "status": {
    "code": "opened",
    "name": "Открыта"
  },
  "old_status": {
    "code": "completed",
    "name": "Решена"
  },
  "rate": {
    "id": 3,
    "value": "normal"
  },
  "address": {
    "coordinates": [
      53.2184321,
      44.9998082
    ],
    "value": "г Пенза ул Гагарина д 13"
  },
  "observers": [
    {
      "id": 113,
      "type": "employee",
      "name": "Антонов Петр Захарович"
    },
    {
      "id": 121,
      "type": "employee",
      "name": "Акмаев Артем Викторович"
    }
  ],
  "observer_groups": [
    {
      "id": 5,
      "name": "Отдел контроля качества"
    }
  ],
  "contact": {
    "id": 3020,
    "name": "Егор Егоров"
  },
  "agreement": null,
  "assignee": {
    "id": 1,
    "name": "Иванов Иван Викторович"
  },
  "author": {
    "id": 3020,
    "name": "Егор Егоров"
  }
}

Запрос с некорректной датой

СкрытьПоказать

Заголовки

Content-Type: application/json

Тело

{
  "deadline_at": "2019/09/24T14:35"
}

Ответ 422

СкрытьПоказать

Заголовки

Content-Type: application/json

Тело

{
  "errors": {
    "deadline_at": [
      "Неверный формат даты"
    ]
  }
}

Ответ 422

СкрытьПоказать

Заголовки

Content-Type: application/json

Тело

{
  "errors": {
    "deadline_at": [
      "Дата должна быть позже относительно текущего времени"
    ]
  }
}

Изменение даты “Отложена до” заявки

PATCH`/api/v1/issues/{issue_id}/delays{?api_token}`

Название	Тип	Обязательность	Описание
delay_to	string	обязательный	Время, до которого откладывается заявка.

Изменение даты “Отложена до” заявки будет выполнено только в том случае, если связанный с ключом пользователь имеет права на просмотр заявки и изменение даты “Отложена до”, а также, если статус заявки является отложенным. Для ключей, связанных с контактными лицами, данный метод недоступен.

Оставшееся время по нормативу (remaining_time_according_to_standard) возвращается только в том случае, когда плановое время решения не было установлено вручную. Считается в минутах.

Пример URI

PATCH https://<account>.okdesk.ru/api/v1/issues/763/delays?api_token=3e9a214215f493c4

Параметры URI

СкрытьПоказать

api_token: string (обязательное) Пример: 3e9a214215f493c4
Ключ авторизации.
issue_id: integer (обязательное) Пример: 763
ID заявки.

Запрос

СкрытьПоказать

Заголовки

Content-Type: application/json

Тело

{
  "delay_to": "2019-09-24 14:35"
}

Ответ 200

СкрытьПоказать

Заголовки

Content-Type: application/json

Тело

{
  "id": 153,
  "title": "Требуется мастер на выезд",
  "description": "",
  "created_at": "2016-03-15T18:05:17.568+03:00",
  "completed_at": "2016-05-19T10:54:09.987+03:00",
  "deadline_at": "2019-09-24T14:35:00.000+03:00",
  "source": "from_employee",
  "spent_time_total": 0,
  "start_execution_until": "2016-03-16T09:05:17.568+03:00",
  "planned_execution_in_hours": 12,
  "planned_reaction_at": "2016-04-11T11:00:00.000+03:00",
  "reacted_at": "2016-04-10T18:43:44.951+03:00",
  "updated_at": "2016-08-23T09:39:35.428+03:00",
  "delayed_to": "2019-09-24T14:35:00.000+03:00",
  "company_id": 40,
  "group_id": 3,
  "coexecutors": [
    {
      "id": 3,
      "name": "Артамонов Анатолий Маратович",
      "group": {
        "id": 1,
        "name": "Отдел планирования"
      }
    }
  ],
  "service_object_id": null,
  "equipment_ids": [],
  "attachments": [
    {
      "id": 8,
      "attachment_file_name": "photo.jpg",
      "description": "Фотография неисправности",
      "attachment_file_size": 4149,
      "is_public": false,
      "created_at": "2016-09-30T09:28:50.499+03:00"
    }
  ],
  "status_times": {
    "opened": {
      "total": "134 д., 14 ч., 57 м.",
      "on_schedule_total": "36 д., 0 ч., 39 м."
    },
    "completed": {
      "total": "0 д., 0 ч., 0 м.",
      "on_schedule_total": "0 д., 0 ч., 0 м."
    }
  },
  "parameters": [],
  "comments": {
    "count": 5,
    "last_at": "2018-07-05T16:06:10.000+03:00"
  },
  "parent_id": null,
  "child_ids": [],
  "remaining_time_according_to_standard": 2400,
  "type": {
    "id": 2,
    "code": "service",
    "name": "Обслуживание",
    "available_for_client": true
  },
  "priority": {
    "code": "low",
    "name": "Низкий"
  },
  "status": {
    "code": "opened",
    "name": "Открыта"
  },
  "old_status": {
    "code": "completed",
    "name": "Решена"
  },
  "rate": {
    "id": 3,
    "value": "normal"
  },
  "address": {
    "coordinates": [
      53.2184321,
      44.9998082
    ],
    "value": "г Пенза ул Гагарина д 13"
  },
  "observers": [
    {
      "id": 113,
      "type": "employee",
      "name": "Антонов Петр Захарович"
    },
    {
      "id": 121,
      "type": "employee",
      "name": "Акмаев Артем Викторович"
    }
  ],
  "observer_groups": [
    {
      "id": 5,
      "name": "Отдел контроля качества"
    }
  ],
  "contact": {
    "id": 3020,
    "name": "Егор Егоров"
  },
  "agreement": null,
  "assignee": {
    "id": 1,
    "name": "Иванов Иван Викторович"
  },
  "author": {
    "id": 3020,
    "name": "Егор Егоров"
  }
}

Запрос с некорректной датой

СкрытьПоказать

Заголовки

Content-Type: application/json

Тело

{
  "delay_to": "2019/09/24T14:35"
}

Ответ 422

СкрытьПоказать

Заголовки

Content-Type: application/json

Тело

{
  "errors": {
    "delay_to": [
      "Неверный формат даты"
    ]
  }
}

Ответ 422

СкрытьПоказать

Заголовки

Content-Type: application/json

Тело

{
  "errors": {
    "delay_to": [
      "не может быть меньше текущего времени"
    ]
  }
}

Запрос с неотложенным статусом

СкрытьПоказать

Заголовки

Content-Type: application/json

Ответ 422

СкрытьПоказать

Заголовки

Content-Type: application/json

Тело

{
  "errors": "Текущий статус заявки не является отложенным"
}

Смена типа заявки

PATCH`/api/v1/issues/{issue_id}/types{?api_token}`

Название	Тип	Обязательность	Описание
code	string	обязательный	Код типа заявки

Метод доступен только для ключей, связанных с сотрудниками, имеющими доступ к действиям “Просмотр карточки заявки”, “Изменение типа заявки” (включая право на установку переданного типа в соответствии с настройкой “Кроме установки типа”).
Для ключей, связанных с контактными лицами, данный метод недоступен.

Пример URI

PATCH https://<account>.okdesk.ru/api/v1/issues/763/types?api_token=3e9a214215f493c4

Параметры URI

СкрытьПоказать

api_token: string (обязательное) Пример: 3e9a214215f493c4
Ключ авторизации.
issue_id: integer (обязательное) Пример: 763
ID заявки.

Запрос

СкрытьПоказать

Заголовки

Content-Type: application/json

Тело

{
  "code": "service"
}

Ответ 200

СкрытьПоказать

Заголовки

Content-Type: application/json

Тело

{
  "id": 153,
  "title": "Требуется мастер на выезд",
  "description": "",
  "created_at": "2016-03-15T18:05:17.568+03:00",
  "completed_at": "2016-05-19T10:54:09.987+03:00",
  "deadline_at": "2019-09-24T14:35:00.000+03:00",
  "source": "from_employee",
  "spent_time_total": 0,
  "start_execution_until": "2016-03-16T09:05:17.568+03:00",
  "planned_execution_in_hours": 12,
  "planned_reaction_at": "2016-04-11T11:00:00.000+03:00",
  "reacted_at": "2016-04-10T18:43:44.951+03:00",
  "updated_at": "2016-08-23T09:39:35.428+03:00",
  "delayed_to": null,
  "company_id": 40,
  "group_id": 3,
  "coexecutors": [
    {
      "id": 3,
      "name": "Артамонов Анатолий Маратович",
      "group": {
        "id": 1,
        "name": "Отдел планирования"
      }
    }
  ],
  "service_object_id": null,
  "equipment_ids": [],
  "attachments": [
    {
      "id": 8,
      "attachment_file_name": "photo.jpg",
      "description": "Фотография неисправности",
      "attachment_file_size": 4149,
      "is_public": false,
      "created_at": "2016-09-30T09:28:50.499+03:00"
    }
  ],
  "status_times": {
    "opened": {
      "total": "134 д., 14 ч., 57 м.",
      "on_schedule_total": "36 д., 0 ч., 39 м."
    },
    "completed": {
      "total": "0 д., 0 ч., 0 м.",
      "on_schedule_total": "0 д., 0 ч., 0 м."
    }
  },
  "parameters": [],
  "comments": {
    "count": 5,
    "last_at": "2018-07-05T16:06:10.000+03:00"
  },
  "parent_id": null,
  "child_ids": [],
  "type": {
    "id": 2,
    "code": "service",
    "name": "Обслуживание",
    "available_for_client": true
  },
  "priority": {
    "code": "low",
    "name": "Низкий"
  },
  "status": {
    "code": "opened",
    "name": "Открыта"
  },
  "old_status": {
    "code": "completed",
    "name": "Решена"
  },
  "rate": {
    "id": 3,
    "value": "normal"
  },
  "address": {
    "coordinates": [
      53.2184321,
      44.9998082
    ],
    "value": "г Пенза ул Гагарина д 13"
  },
  "observers": [
    {
      "id": 113,
      "type": "employee",
      "name": "Антонов Петр Захарович"
    },
    {
      "id": 121,
      "type": "employee",
      "name": "Акмаев Артем Викторович"
    }
  ],
  "observer_groups": [
    {
      "id": 5,
      "name": "Отдел контроля качества"
    }
  ],
  "contact": {
    "id": 3020,
    "name": "Егор Егоров"
  },
  "agreement": null,
  "assignee": {
    "id": 1,
    "name": "Иванов Иван Викторович"
  },
  "author": {
    "id": 3020,
    "name": "Егор Егоров"
  }
}

Запрос с некорректными параметрами

СкрытьПоказать

Заголовки

Content-Type: application/json

Тело

{
  "code": 123
}

Ответ 422

СкрытьПоказать

Заголовки

Content-Type: application/json

Тело

{
  "errors": {
    "code": [
      "должно иметь тип string"
    ]
  }
}

Изменение привязки заявки к клиенту договору объекту обслуживания и оборудованию

PATCH`/api/v1/issues/{issue_id}/related_attributes{?api_token}`

Название	Тип	Обязательность	Описание
company_id	integer	опционально	ID компании
contact_id	integer	опционально	ID контакта
agreement_id	integer	опционально	ID договора
maintenance_entity_id	integer	опционально	ID объекта обслуживания
equipment_ids	array of integer	опционально	Массив ID оборудования

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

Пример URI

PATCH https://<account>.okdesk.ru/api/v1/issues/763/related_attributes?api_token=3e9a214215f493c4

Параметры URI

СкрытьПоказать

api_token: string (обязательное) Пример: 3e9a214215f493c4
Ключ авторизации.
issue_id: integer (обязательное) Пример: 763
ID заявки.

Запрос

СкрытьПоказать

Заголовки

Content-Type: application/json

Тело

{
  "company_id": 1,
  "contact_id": 1,
  "agreement_id": 1,
  "maintenance_entity_id": 1,
  "equipment_ids": [
    1
  ]
}

Ответ 200

СкрытьПоказать

Заголовки

Content-Type: application/json

Тело

{
  "id": 763,
  "title": "Требуется мастер на выезд",
  "description": "",
  "created_at": "2016-03-15T18:05:17.568+03:00",
  "completed_at": "2016-05-19T10:54:09.987+03:00",
  "deadline_at": "2019-09-24T14:35:00.000+03:00",
  "source": "from_employee",
  "spent_time_total": 0,
  "start_execution_until": "2016-03-16T09:05:17.568+03:00",
  "planned_execution_in_hours": 12,
  "planned_reaction_at": "2016-04-11T11:00:00.000+03:00",
  "reacted_at": "2016-04-10T18:43:44.951+03:00",
  "updated_at": "2016-08-23T09:39:35.428+03:00",
  "delayed_to": null,
  "company_id": 1,
  "group_id": 3,
  "coexecutors": [
    {
      "id": 3,
      "name": "Артамонов Анатолий Маратович",
      "group": {
        "id": 1,
        "name": "Отдел планирования"
      }
    }
  ],
  "service_object_id": null,
  "equipment_ids": [
    1
  ],
  "attachments": [
    {
      "id": 8,
      "attachment_file_name": "photo.jpg",
      "description": "Фотография неисправности",
      "attachment_file_size": 4149,
      "is_public": false,
      "created_at": "2016-09-30T09:28:50.499+03:00"
    }
  ],
  "status_times": {
    "opened": {
      "total": "134 д., 14 ч., 57 м.",
      "on_schedule_total": "36 д., 0 ч., 39 м."
    },
    "completed": {
      "total": "0 д., 0 ч., 0 м.",
      "on_schedule_total": "0 д., 0 ч., 0 м."
    }
  },
  "parameters": [],
  "comments": {
    "count": 5,
    "last_at": "2018-07-05T16:06:10.000+03:00"
  },
  "parent_id": null,
  "child_ids": [],
  "type": {
    "id": 2,
    "code": "service",
    "name": "Обслуживание",
    "available_for_client": true
  },
  "priority": {
    "code": "low",
    "name": "Низкий"
  },
  "status": {
    "code": "opened",
    "name": "Открыта"
  },
  "old_status": {
    "code": "completed",
    "name": "Решена"
  },
  "rate": {
    "id": 3,
    "value": "normal"
  },
  "address": {
    "coordinates": [
      53.2184321,
      44.9998082
    ],
    "value": "г Пенза ул Гагарина д 13"
  },
  "observers": [
    {
      "id": 113,
      "type": "employee",
      "name": "Антонов Петр Захарович"
    },
    {
      "id": 121,
      "type": "employee",
      "name": "Акмаев Артем Викторович"
    }
  ],
  "observer_groups": [
    {
      "id": 5,
      "name": "Отдел контроля качества"
    }
  ],
  "contact": {
    "id": 1,
    "name": "Егор Егоров"
  },
  "agreement": {
    "id": 1,
    "title": "Договор об обслуживании"
  },
  "assignee": {
    "id": 1,
    "name": "Иванов Иван Викторович"
  },
  "author": {
    "id": 3020,
    "name": "Егор Егоров"
  }
}

Запрос с некорректными параметрами

СкрытьПоказать

Заголовки

Content-Type: application/json

Тело

{
  "company_id": "один"
}

Ответ 422

СкрытьПоказать

Заголовки

Content-Type: application/json

Тело

{
  "errors": {
    "company_id": [
      "должно иметь тип integer"
    ]
  }
}

Редактирование дополнительных атрибутов заявки

POST`/api/v1/issues/{issue_id}/parameters{?api_token}`

Название	Тип	Обязательность	Описание
custom_parameters	associative array	обязательный	Дополнительные атрибуты заявки

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

Значение дополнительного атрибута типа “Рисунок” должно передаваться в виде строки в формате base64, соблюдая следующие ограничения:

Размер строки (закодированного в base64 изображения) не должен превышать 1 МБ
Формат изображения - PNG
Соотношение сторон изображения - 1.86:1
Строка должна начинаться с URL-схемы data:image/png;base64,

Пример: data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAjAAAAEsCAYAA...jLNtZ4AAAAASUVORK5CYII=

Пример URI

POST https://<account>.okdesk.ru/api/v1/issues/763/parameters?api_token=3e9a214215f493c4

Параметры URI

СкрытьПоказать

api_token: string (обязательное) Пример: 3e9a214215f493c4
Ключ авторизации.
issue_id: integer (обязательное) Пример: 763
ID заявки.

Запрос

СкрытьПоказать

Заголовки

Content-Type: application/json

Тело

{
  "custom_parameters": {
    "address": "ул. Московская 2",
    "checked": true,
    "datetime": "2018-05-09 09:15",
    "multiselect": [
      "five"
    ],
    "select": "one",
    "date": "2018-05-09"
  }
}

Ответ 200

Запрос с некорректной датой

СкрытьПоказать

Заголовки

Content-Type: application/json

Тело

{
  "custom_parameters": {
    "datetime": "Second Tuesday"
  }
}

Ответ 422

СкрытьПоказать

Заголовки

Content-Type: application/json

Тело

{
  "errors": {
    "base": [
      [
        {
          "datetime": "Неверный формат даты/времени у дополнительно параметра Дата и время прибытия инженера"
        }
      ]
    ]
  }
}

Запрос если атрибут обязательный

СкрытьПоказать

Тело

{
  "custom_parameters": {
    "total_sum": ""
  }
}

Ответ 422

СкрытьПоказать

Заголовки

Content-Type: application/json

Тело

{
  "errors": {
    "base": [
      "Дополнительный параметр Сумма не может быть пустым"
    ]
  }
}

Редактирование адреса заявки

PATCH`/api/v1/issues/{issue_id}/addresses{?api_token}`

Название	Тип	Обязательность	Описание
value	string	обязательный	Строковое представление адреса заявки
coordinates	array of float	обязательный	Координаты адреса заявки

Если передается непустое значение хотя бы одного параметра (value, coordinates), то второй параметр обязателен к передаче и не может быть пустым. Если передать пустые значения для обоих параметров, адрес в заявке сбрасывается.

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

Пример URI

PATCH https://<account>.okdesk.ru/api/v1/issues/763/addresses?api_token=3e9a214215f493c4

Параметры URI

СкрытьПоказать

api_token: string (обязательное) Пример: 3e9a214215f493c4
Ключ авторизации.
issue_id: integer (обязательное) Пример: 763
ID заявки.

Запрос

СкрытьПоказать

Заголовки

Content-Type: application/json

Тело

{
  "value": "г Пенза ул Гагарина д 13",
  "coordinates": [
    53.2184321,
    44.9998082
  ]
}

Ответ 200

СкрытьПоказать

Заголовки

Content-Type: application/json

Тело

{
  "id": 153,
  "title": "Требуется мастер на выезд",
  "description": "",
  "created_at": "2016-03-15T18:05:17.568+03:00",
  "completed_at": "2016-05-19T10:54:09.987+03:00",
  "deadline_at": "2019-09-24T14:35:00.000+03:00",
  "source": "from_employee",
  "spent_time_total": 0,
  "start_execution_until": "2016-03-16T09:05:17.568+03:00",
  "planned_execution_in_hours": 12,
  "planned_reaction_at": "2016-04-11T11:00:00.000+03:00",
  "reacted_at": "2016-04-10T18:43:44.951+03:00",
  "updated_at": "2016-08-23T09:39:35.428+03:00",
  "delayed_to": null,
  "company_id": 40,
  "group_id": 3,
  "coexecutors": [
    {
      "id": 3,
      "name": "Артамонов Анатолий Маратович",
      "group": {
        "id": 1,
        "name": "Отдел планирования"
      }
    }
  ],
  "service_object_id": null,
  "equipment_ids": [],
  "attachments": [
    {
      "id": 8,
      "attachment_file_name": "photo.jpg",
      "description": "Фотография неисправности",
      "attachment_file_size": 4149,
      "is_public": false,
      "created_at": "2016-09-30T09:28:50.499+03:00"
    }
  ],
  "status_times": {
    "opened": {
      "total": "134 д., 14 ч., 57 м.",
      "on_schedule_total": "36 д., 0 ч., 39 м."
    },
    "completed": {
      "total": "0 д., 0 ч., 0 м.",
      "on_schedule_total": "0 д., 0 ч., 0 м."
    }
  },
  "parameters": [],
  "comments": {
    "count": 5,
    "last_at": "2018-07-05T16:06:10.000+03:00"
  },
  "parent_id": null,
  "child_ids": [],
  "type": {
    "id": 2,
    "code": "service",
    "name": "Обслуживание",
    "available_for_client": true
  },
  "priority": {
    "code": "low",
    "name": "Низкий"
  },
  "status": {
    "code": "opened",
    "name": "Открыта"
  },
  "old_status": {
    "code": "completed",
    "name": "Решена"
  },
  "rate": {
    "id": 3,
    "value": "normal"
  },
  "address": {
    "coordinates": [
      53.2184321,
      44.9998082
    ],
    "value": "г Пенза ул Гагарина д 13"
  },
  "observers": [
    {
      "id": 113,
      "type": "employee",
      "name": "Антонов Петр Захарович"
    },
    {
      "id": 121,
      "type": "employee",
      "name": "Акмаев Артем Викторович"
    }
  ],
  "observer_groups": [
    {
      "id": 5,
      "name": "Отдел контроля качества"
    }
  ],
  "contact": {
    "id": 3020,
    "name": "Егор Егоров"
  },
  "agreement": null,
  "assignee": {
    "id": 1,
    "name": "Иванов Иван Викторович"
  },
  "author": {
    "id": 3020,
    "name": "Егор Егоров"
  }
}

Запрос если один из параметров пустой

СкрытьПоказать

Тело

{
  "value": null,
  "coordinates": [
    53.2184321,
    44.9998082
  ]
}

Ответ 422

СкрытьПоказать

Заголовки

Content-Type: application/json

Тело

{
  "errors": {
    "address_with_coordinates": [
      "Адрес и координаты должны быть одновременно пустыми (для удаления адреса заявки) или одновременно заполненными (для редактирования адреса заявки)"
    ]
  }
}

Смена статуса заявки

POST`/api/v1/issues/{issue_id}/statuses{?api_token}`

По умолчанию для заявок определены системные статусы со следующими кодами: opened, delayed, completed, closed.
Вы можете расширить набор статусов и возможных переходов между ними в разделе “Настройки/Заявки/Статусы заявок” вашего аккаунта в Okdesk.

Название	Тип	Обязательность	Описание
code	string	обязательный	Код статуса
delay_to	string	опционально	Время, до которого откладывается заявка. Обязательное поле только для статуса delayed. Для остальных статусов данный параметр будет игнорироваться.
comment	string	опционально	Комментарий к статусу. Например, причина перехода в новый статус. Обязательность данного параметра настраивается в разделе “Настройки/Заявки/Статусы заявок”.
comment_public	boolean	опционально	Флаг публичности комментария. Принимает значение true или false
custom_parameters	associative array	опционально	Дополнительные атрибуты заявки, которые доступны пользователю для заполнения при входе в новый или при выходе из текущего статуса.
time_entry	array	опционально	Массив трудозатрат по заявке, которые будут добавлены при смене статуса
assignee_id	string	опционально	ID ответственного за заявку
group_id	string	опционально	ID ответственной группы сотрудника
skip_options	array	опционально	Массив флагов, позволяющих пропустить отправку оповещений (skip_notifications), вебхуков (skip_webhooks), автоматических действий (skip_triggers)

Параметр delay_to является обязательным для перехода в статус delayed
Параметр comment по умолчанию обязателен для статуса delayed
Для смены статуса заявки в настройках вашего аккаунта должен быть разрешен переход из текущего статуса заявки в статус, передаваемый в запросе
Параметр formatted_spent_time передается в формате 2 ч. 30 мин. или 2:30 или 2,5 часа и т.д.

Для сотрудников смена статуса заявки будет выполнена только в том случае, если связанный с ключом сотрудник имеет права на просмотр заявки и смену статуса заявки из текущего в целевой в соответствии с настройками прав доступа. Для ключей, связанных с контактными лицами, доступны не все переходы между статусами. Контактное лицо может перевести заявку только из статуса “Решена” в статус, указанный в параметре “Статус для возобновления заявок”, и в статус “Закрыта”, а также из любого статуса в статус “Закрыта”, если указана соответствующая настройка в разделе “Настройки/Клиентский портал” вашего аккаунта.

Пример URI

POST https://<account>.okdesk.ru/api/v1/issues/763/statuses?api_token=3e9a214215f493c4

Параметры URI

СкрытьПоказать

api_token: string (обязательное) Пример: 3e9a214215f493c4
Ключ авторизации.
issue_id: integer (обязательное) Пример: 763
ID заявки.

Запрос со статусом completed

СкрытьПоказать

Заголовки

Content-Type: application/json

Тело

{
  "code": "completed",
  "comment": "Работы по заявке выполнены в полном объеме",
  "comment_public": true,
  "assignee_id": "1",
  "group_id": "3",
  "custom_parameters": {
    "code1": "123456789",
    "code2": "2019-02-15",
    "code3": true
  },
  "time_entry": [
    {
      "formatted_spent_time": "12h45m",
      "comment": "Добавление трудозатраты при смене статуса",
      "custom_parameters": {
        "code1": "123456789",
        "code2": "2019-02-15",
        "code3": true
      }
    },
    {
      "formatted_spent_time": "1h45m",
      "comment": "Добавление трудозатраты при смене статуса",
      "custom_parameters": {
        "code1": "123456789",
        "code2": "2019-02-15",
        "code3": true
      }
    }
  ],
  "skip_options": [
    "skip_triggers",
    "skip_notifications",
    "skip_webhooks"
  ]
}

Ответ 200

СкрытьПоказать

Заголовки

Content-Type: application/json

Тело

{
  "id": 153,
  "title": "Требуется мастер на выезд",
  "description": "",
  "created_at": "2016-03-15T18:05:17.568+03:00",
  "completed_at": "2016-05-19T10:54:09.987+03:00",
  "deadline_at": "2019-09-24T14:35:00.000+03:00",
  "source": "from_employee",
  "spent_time_total": 0,
  "start_execution_until": "2016-03-16T09:05:17.568+03:00",
  "planned_execution_in_hours": 12,
  "planned_reaction_at": "2016-04-11T11:00:00.000+03:00",
  "reacted_at": "2016-04-10T18:43:44.951+03:00",
  "updated_at": "2016-08-23T09:39:35.428+03:00",
  "delayed_to": null,
  "company_id": 40,
  "group_id": 3,
  "coexecutors": [
    {
      "id": 3,
      "name": "Артамонов Анатолий Маратович",
      "group": {
        "id": 1,
        "name": "Отдел планирования"
      }
    }
  ],
  "service_object_id": null,
  "equipment_ids": [],
  "attachments": [
    {
      "id": 8,
      "attachment_file_name": "photo.jpg",
      "description": "Фотография неисправности",
      "attachment_file_size": 4149,
      "is_public": false,
      "created_at": "2016-09-30T09:28:50.499+03:00"
    }
  ],
  "status_times": {
    "opened": {
      "total": "134 д., 14 ч., 57 м.",
      "on_schedule_total": "36 д., 0 ч., 39 м."
    },
    "completed": {
      "total": "0 д., 0 ч., 0 м.",
      "on_schedule_total": "0 д., 0 ч., 0 м."
    }
  },
  "parameters": [],
  "comments": {
    "count": 5,
    "last_at": "2018-07-05T16:06:10.000+03:00"
  },
  "parent_id": null,
  "child_ids": [],
  "type": {
    "id": 2,
    "code": "service",
    "name": "Обслуживание",
    "available_for_client": true
  },
  "priority": {
    "code": "low",
    "name": "Низкий"
  },
  "status": {
    "code": "opened",
    "name": "Открыта"
  },
  "old_status": {
    "code": "completed",
    "name": "Решена"
  },
  "rate": {
    "id": 3,
    "value": "normal"
  },
  "address": {
    "coordinates": [
      53.2184321,
      44.9998082
    ],
    "value": "г Пенза ул Гагарина д 13"
  },
  "observers": [
    {
      "id": 113,
      "type": "employee",
      "name": "Антонов Петр Захарович"
    },
    {
      "id": 121,
      "type": "employee",
      "name": "Акмаев Артем Викторович"
    }
  ],
  "observer_groups": [
    {
      "id": 5,
      "name": "Отдел контроля качества"
    }
  ],
  "contact": {
    "id": 3020,
    "name": "Егор Егоров"
  },
  "agreement": null,
  "assignee": {
    "id": 1,
    "name": "Иванов Иван Викторович"
  },
  "author": {
    "id": 3020,
    "name": "Егор Егоров"
  }
}

Запрос со статусом delayed

СкрытьПоказать

Заголовки

Content-Type: application/json

Тело

{
  "code": "delayed",
  "delay_to": "2016-05-25 22:15",
  "comment": "Кончились расходные материалы, ждем допоставки.",
  "comment_public": true,
  "custom_parameters": {
    "code1": "123456789",
    "code2": "2019-02-15",
    "code3": true
  },
  "time_entry": [
    {
      "formatted_spent_time": "12h35m",
      "comment": "Добавление трудозатраты при смене статуса",
      "custom_parameters": {
        "code1": "123456789",
        "code2": "2019-02-15",
        "code3": true
      }
    }
  ]
}

Ответ 200

СкрытьПоказать

Заголовки

Content-Type: application/json

Тело

{
  "id": 153,
  "title": "Требуется мастер на выезд",
  "description": "",
  "created_at": "2016-03-15T18:05:17.568+03:00",
  "completed_at": "2016-05-19T10:54:09.987+03:00",
  "deadline_at": null,
  "source": "from_employee",
  "spent_time_total": 0,
  "start_execution_until": "2016-03-16T09:05:17.568+03:00",
  "planned_execution_in_hours": 12,
  "planned_reaction_at": "2016-04-11T11:00:00.000+03:00",
  "reacted_at": "2016-04-10T18:43:44.951+03:00",
  "updated_at": "2016-08-23T09:39:35.428+03:00",
  "delayed_to": "2016-05-25T22:15:00.000+03:00",
  "company_id": 40,
  "group_id": 3,
  "coexecutors": [
    {
      "id": 3,
      "name": "Артамонов Анатолий Маратович",
      "group": {
        "id": 1,
        "name": "Отдел планирования"
      }
    }
  ],
  "service_object_id": null,
  "equipment_ids": [],
  "attachments": [
    {
      "id": 8,
      "attachment_file_name": "photo.jpg",
      "description": "Фотография неисправности",
      "attachment_file_size": 4149,
      "is_public": false,
      "created_at": "2016-09-30T09:28:50.499+03:00"
    }
  ],
  "status_times": {
    "opened": {
      "total": "134 д., 14 ч., 57 м.",
      "on_schedule_total": "36 д., 0 ч., 39 м."
    },
    "completed": {
      "total": "0 д., 0 ч., 0 м.",
      "on_schedule_total": "0 д., 0 ч., 0 м."
    }
  },
  "parameters": [],
  "comments": {
    "count": 5,
    "last_at": "2018-07-05T16:06:10.000+03:00"
  },
  "parent_id": null,
  "child_ids": [],
  "remaining_time_according_to_standard": 2400,
  "type": {
    "id": 2,
    "code": "service",
    "name": "Обслуживание",
    "available_for_client": true
  },
  "priority": {
    "code": "low",
    "name": "Низкий"
  },
  "status": {
    "code": "opened",
    "name": "Открыта"
  },
  "old_status": {
    "code": "completed",
    "name": "Решена"
  },
  "rate": {
    "id": 3,
    "value": "normal"
  },
  "address": {
    "coordinates": [
      53.2184321,
      44.9998082
    ],
    "value": "г Пенза ул Гагарина д 13"
  },
  "observers": [
    {
      "id": 113,
      "type": "employee",
      "name": "Антонов Петр Захарович"
    },
    {
      "id": 121,
      "type": "employee",
      "name": "Акмаев Артем Викторович"
    }
  ],
  "observer_groups": [
    {
      "id": 5,
      "name": "Отдел контроля качества"
    }
  ],
  "contact": {
    "id": 3020,
    "name": "Егор Егоров"
  },
  "agreement": null,
  "assignee": {
    "id": 1,
    "name": "Иванов Иван Викторович"
  },
  "author": {
    "id": 3020,
    "name": "Егор Егоров"
  }
}

Добавление комментария

POST`/api/v1/issues/{issue_id}/comments{?api_token}`

Название	Тип	Обязательность	Описание
content	string	обязательный	Текст комментария. Текст комментария является html-текстом, а значит требуемое форматирование необходимо задавать с использованием html-тегов. Например, для переноса строк необходимо использовать тег <br />
author_id	integer	обязательный	ID пользователя, являющегося автором комментария
author_type	string	опционально	Тип пользователя, являющегося автором комменатрия Допустимые типы: employee (по умолчанию) - сотрудник, contact - контактное лицо
public	boolean	опционально	Флаг публичности комментария. Принимает значение true или false
attachments	array	опционально	Список приложенных файлов

Если параметр public не указан, то по умолчанию созданный комментарий будет приватным.
Контактные лица не могут создавать приватные комментарии.
Если параметр author_type не указан, то по умолчанию автором комментария будет сотрудник.

Для сотрудников добавление комментария к заявке будет выполнено только в том случае, если связанный с ключом сотрудник имеет права на просмотр заявки и добавление комментария в соответствии с настройками прав доступа. Для ключей, связанных с контактными лицами, существует возможность добавить только публичный комментарий. Для ключей пользователей, не связанных с ролью “Администратор” (в том числе контактных лиц), значение параметра author_id будет игнорироваться (комментарий будет добавлен от имени владельца ключа).

Название	Тип	Обязательность	Описание
attachment	string	обязательный	Прикрепляемый файл
description	string	опционально	Описание файла

Содержание запроса с прикрепленными файлами должно быть в виде multipart/form-data и содержать соответствующий заголовок.
Флаг публичности для прикрепляемых файлов будет установлен идентично переданному значению для комментария, к которому прикладываются файлы

Пример URI

POST https://<account>.okdesk.ru/api/v1/issues/254/comments?api_token=3e9a214215f493c4

Параметры URI

СкрытьПоказать

api_token: string (обязательное) Пример: 3e9a214215f493c4
Ключ авторизации.
issue_id: integer (обязательное) Пример: 254
ID заявки.

Запрос

СкрытьПоказать

Заголовки

Content-Type: application/json

Тело

{
  "comment": {
    "content": "В ближайшее время к Вам отправится инженер для решения проблемы.",
    "public": true,
    "author_id": 10,
    "author_type": "employee"
  }
}

Ответ 200

СкрытьПоказать

Заголовки

Content-Type: application/json

Тело

{
  "id": 1,
  "content": "В ближайшее время к Вам отправится инженер для решения проблемы.",
  "public": true,
  "attachments": [],
  "author": {
    "id": 10,
    "name": "Иванов Сергей Петрович",
    "type": "employee"
  }
}

Запрос с прикрепленными файлами

СкрытьПоказать

Заголовки

Content-Type: multipart/form-data

Тело

curl  -H "Content-Type: multipart/form-data" -F "comment[content]=Вот долгожданные файлы отчетов"
-F "comment[public]=true" -F "comment[author_id]=15" -F "comment[author_type]=employee"
-F "comment[attachments][0][attachment]=@/home/user/file.jpg"
-F "comment[attachments][0][description]=Отчет"
-F "comment[attachments][1][attachment]=@/home/user/file.docx"
https://<account>.okdesk.ru/api/v1/issues/{issue_id}/comments/{?api_token}

где @/home/user/file.jpg — это путь к локальному файлу
пример для windows: @"C:/myfile.txt"

Ответ 200

СкрытьПоказать

Заголовки

Content-Type: application/json

Тело

{
  "id": 1,
  "content": "Вот долгожданные файлы отчетов",
  "public": true,
  "attachments": [
    {
      "id": 8,
      "attachment_file_name": "file.jpg",
      "description": "Отчет",
      "attachment_file_size": 4149,
      "is_public": true,
      "created_at": "2018-12-24T09:28:50.499+03:00"
    },
    {
      "id": 9,
      "attachment_file_name": "file.docx",
      "description": null,
      "attachment_file_size": 1142,
      "is_public": true,
      "created_at": "2018-12-24T09:28:50.499+03:00"
    }
  ],
  "author": {
    "id": 15,
    "name": "Иванов Виталий Петрович",
    "type": "employee"
  }
}

Запрос с некорректными параметрами

СкрытьПоказать

Заголовки

Content-Type: application/json

Тело

{
  "comment": {
    "content": "В ближайшее время к Вам отправится инженер для решения проблемы.",
    "public": false,
    "author_id": 22221,
    "author_type": "contact"
  }
}

Ответ 422

СкрытьПоказать

Заголовки

Content-Type: application/json

Тело

{
  "errors": {
    "author_presence": [
      "пользователь не найден"
    ],
    "contact_comment_cannot_be_private": [
      "контактное лицо не может быть автором приватного комментария"
    ]
  }
}

Получение списка комментариев

GET`/api/v1/issues/{issue_id}/comments{?api_token}`

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

Пример URI

GET https://<account>.okdesk.ru/api/v1/issues/254/comments?api_token=3e9a214215f493c4

Параметры URI

СкрытьПоказать

api_token: string (обязательное) Пример: 3e9a214215f493c4
Ключ авторизации.
issue_id: integer (обязательное) Пример: 254
ID заявки.

Ответ 200

СкрытьПоказать

Заголовки

Content-Type: application/json

Тело

[
  {
    "id": 1,
    "content": "В ближайшее время к Вам отправится инженер для решения проблемы.",
    "public": false,
    "published_at": "2018-12-24T14:38:43.442+03:00",
    "attachments": [
      {
        "id": 8,
        "attachment_file_name": "photo.jpg",
        "description": "Фотография",
        "attachment_file_size": 4149,
        "is_public": false,
        "created_at": "2018-12-24T09:28:50.499+03:00"
      }
    ],
    "author": {
      "id": 15,
      "name": "Иванов Виталий Петрович",
      "type": "employee"
    }
  },
  {
    "id": 2,
    "content": "Спасибо, ждем с нетерпением.",
    "public": true,
    "published_at": "2018-12-24T15:57:43.374+03:00",
    "attachments": [],
    "author": {
      "id": 12,
      "name": "Петров Геннадий Ильич",
      "type": "contact"
    }
  }
]

Получение детализированного списка по параметрам

GET`/api/v1/issues/list{?api_token}`

Название	Тип	Обязательность	Описание
company_ids	array of integer	опционально	Массив из ID компаний, которые являются клиентами заявок (для отображения заявок без компании необходимо передавать в параметре значение “0”). Пример: company_ids[]=1&company_ids[]=2
company_category_ids	array of integer	опционально	Массив из ID категорий клиента (для отображения заявок без компании и заявок с компаниями без категорий необходимо передавать в параметре значение “0”). Пример: company_category_ids[]=1
contact_ids	array of integer	опционально	Массив из ID пользователей, которые являются контактными лицами заявок (для отображения заявок без контактного лица необходимо передавать в параметре значение “0”). Пример: contact_ids[]=1&contact_ids[]=2
service_object_ids	array of integer	опционально	Массив из ID объектов обслуживания, которые связаны с заявками (для отображения заявок без объекта обслуживания необходимо передавать в параметре значение “0”) Пример: service_object_ids[]=1
assignee_ids	array of integer	опционально	Массив из ID сотрудников, которые являются ответственными за заявки (для отображения заявок без ответственного необходимо передавать в параметре значение “0”). Пример: assignee_ids[]=1&assignee_ids[]=2
assignee_group_ids	array of integer	опционально	Массив из ID ответственных групп (для отображения заявок без ответственной группы необходимо передавать в параметре значение “0”). Пример: assignee_group_ids[]=1& assignee_group_ids[]=2
agreement_ids	array of integer	опционально	Массив из ID договоров, которые связаны с заявками (для отображения заявок без договоров необходимо передавать в параметре значение “0”) Пример: agreement_ids[]=1
equipment_ids	array of integer	опционально	Массив из ID оборудования, которое связано с заявками (для отображения заявок без оборудования необходимо передавать в параметре значение “0”) Пример: equipment_ids[]=1
status_codes	array of string	опционально	Массив из кодов статусов заявок Пример: status_codes[]=opened& status_codes[]=completed
status_codes_not	array of string	опционально	Массив из кодов статусов заявок, в которых не должна находиться заявка Пример: status_codes_not[]=opened& status_codes_not[]=completed
priority_codes	array of string	опционально	Массив из кодов приоритетов заявок Пример: priority_codes[]=high&priority_codes[]=low
type_codes	array of string	опционально	Массив из кодов типов заявок Пример: type_codes[]=incident
created_since	string	опционально	Дата создания заявки (С) Пример: created_since=22-03-2022 15:30
created_until	string	опционально	Дата создания заявки (По) Пример: created_until=22-06-2022 18:30
overdue	boolean	опционально	Флаг "Просроченные заявки по времени решения". Если значение поля будет равно true, то в выборку попадут только просроченные по времени решения заявки Пример: overdue=true
overdue_reaction	boolean	опционально	Флаг "Просроченные заявки по времени реакции". Если значение поля будет равно true, то в выборку попадут только просроченные по времени реакции заявки Пример: overdue_reaction=true
completed_since	string	опционально	Дата решения заявки (С) Пример: completed_since=22-03-2022 15:30
completed_until	string	опционально	Дата решения заявки (По) Пример: completed_until=22-06-2022 18:30
updated_since	string	опционально	Дата последнего изменения заявки (С) Пример: updated_since=03-12-2023 15:30
updated_until	string	опционально	Дата последнего изменения заявки (По) Пример: updated_until=03-12-2023 18:30
deadline_since	string	опционально	Плановая дата решения заявки (С) Пример: deadline_since=03-12-2023 15:30
deadline_until	string	опционально	Плановая дата решения заявки (По) Пример: deadline_until=06-12-2023 18:00
without_answer	boolean	опционально	Флаг "Заявки без ответа". Если значение поля будет равно true, то в выборку попадут заявки, которые находятся без ответа сотрудника, т.е. после регистрации заявки сотрудник не оставил публичный комментарий или после последнего комментария клиента нет публичного комментария сотрудника. Если значение поля будет равно false, то в выборку попадут заявки, где последний публичный комментарий сотрудника.
author	associative array	опционально	Ассоциативный массив из пар Тип автора: ID автора (для отображения заявок без автора необходимо передавать в параметре employee или contact значение “0”). Допустимые типы: employee - сотрудник, contact - контактное лицо Пример: author[employee][]=1&author[contact][]=1
custom_parameters	associative array	опционально	Ассоциативный массив из пар Код дополнительного атрибута: Значение или набор значений

Название	Тип	Обязательность	Описание
number	integer	опционально	Номер запрашиваемой страницы. Пример: page[number]=2
size	integer	опционально	Число возвращаемых записей. Не может превышать 50. Пример: page[size]=30

Название	Тип	Обязательность	Описание
field	string	опционально	Поле, по которому производится сортировка. Доступные значения: created_at, updated_at. created_at - по дате создания. updated_at - по дате последнего изменения. По умолчанию created_at. Пример: sorting[field]=updated_at
direction	string	опционально	Направление сортировки. Доступно два значения: reverse, forward. forward - возвращает записи в прямом порядке(от меньшего к большему) reverse - возвращает записи в обратном порядке. По умолчанию reverse. Пример: sorting[direction]=forward

Для ключей, связанных с контактными лицами, будут возвращаться только те заявки, которые связаны с компанией контактного лица (при наличии уровня доступа у контактного лица “Отображать заявки компании”), объектами обслуживания (при наличии уровня доступа у контактного лица “Отображать заявки связанных объектов обслуживания”), компаниями под наблюдением (при наличии уровня доступа у контактного лица “Отображать заявки компаний под наблюдением”) и связанные непосредственно с самим контактным лицом.

Тип атрибута	Тип значения	Описание
Дата	string	Доступны два типа значения: Код дополнительного атрибута_since - задает левую границу диапазона (С) и Код дополнительного атрибута_until - задает правую границу диапазона (По). Может быть передан один из параметров или оба параметра. Пример: custom_parameters[date_code_since]=21-01-2023& custom_parameters[date_code_until]=22-12-2023
Дата/время	string	Доступны два типа значения: Код дополнительного атрибута_since - задает левую границу диапазона (С) и Код дополнительного атрибута_until - задает правую границу диапазона (По). Может быть передан один из параметров или оба параметра. Пример: custom_parameters[datetime_code_since]=21-01-2023 01:01& custom_parameters[datetime_code_until]=22-12-2023 12:12
Чекбокс	string	Доступны два значения true и false. Пример: custom_parameters[checkbox_code]=true
Значение из списка	array of string	Массив из значений списка. Пример: custom_parameters[list_code][]=list_value
Набор значений из списка	array of string	Массив из значений списка. Пример: custom_parameters[list_code][]=list_value
Строка	string	Значение строкового типа (для отображения заявок с пустым значением атрибута необходимо передавать в параметре #null). Пример: custom_parameters[string_code]=string_value

Пример URI

GET https://<account>.okdesk.ru/api/v1/issues/list?api_token=3e9a214215f493c4

Параметры URI

СкрытьПоказать

api_token: string (обязательное) Пример: 3e9a214215f493c4
Ключ авторизации.

Ответ 200

СкрытьПоказать

Заголовки

Content-Type: application/json

Тело

[
  {
    "id": 153,
    "title": "Требуется мастер на выезд",
    "created_at": "2022-05-18T12:42:58.685+03:00",
    "completed_at": "2022-05-26T11:21:39.942+03:00",
    "deadline_at": "2022-05-24T16:42:59.000+03:00",
    "delay_to": null,
    "status": {
      "code": "delayed",
      "name": "Отложена",
      "color": "#ffc926"
    },
    "type": {
      "code": "service",
      "name": "Обслуживание"
    },
    "priority": {
      "code": "low",
      "name": "Низкий",
      "color": "#8e9eb3"
    },
    "company": {
      "id": 16,
      "name": "Интеллект+"
    },
    "contact": {
      "id": 1,
      "name": "Елизаров Андрей Валерьевич"
    },
    "service_object": {
      "id": 52,
      "name": "Магазин №13"
    },
    "agreement": {
      "id": 28,
      "title": "Договор об обслуживании"
    },
    "equipments": [
      {
        "id": 120,
        "serial_number": "1101040003532",
        "inventory_number": "51BKB835225",
        "equipment_kind": {
          "code": "laptop",
          "name": "Ноутбук"
        },
        "equipment_manufacturer": {
          "code": "asus",
          "name": "Asus"
        },
        "equipment_model": {
          "code": "x50sm",
          "name": "x50sm"
        }
      }
    ]
  }
]

Ответ 422

СкрытьПоказать

Заголовки

Content-Type: application/json

Тело

{
  "errors": {
    "company_ids": [
      "должно иметь тип integer"
    ],
    "sorting": {
      "direction": [
        "должен быть одним из: forward, reverse"
      ]
    }
  }
}

Оценка заявки

POST`/api/v1/issues/{issue_id}/rates{?api_token}`

Название	Тип	Обязательность	Описание
rate	string	обязательный	Оценка заявки Допустимые значения: bad - Плохо, normal - Нормально, good - Хорошо

Проставление оценки заявки будет выполнено только в том случае, если связанный с ключом пользователь имеет права на просмотр заявки и проставление оценки в соответствии с настройками прав доступа (право на проставление оценки для контактных лиц определяется в подразделе “Заявки \ Оценка заявок” раздела “Настройки” вашего аккаунта, для сотрудников – в подразделе “Роли и права доступа” раздела “Настройки”).

Пример URI

POST https://<account>.okdesk.ru/api/v1/issues/254/rates?api_token=3e9a214215f493c4

Параметры URI

СкрытьПоказать

api_token: string (обязательное) Пример: 3e9a214215f493c4
Ключ авторизации.
issue_id: integer (обязательное) Пример: 254
ID заявки.

Запрос

СкрытьПоказать

Заголовки

Content-Type: application/json

Тело

{
  "issue": {
    "rate": "bad"
  }
}

Ответ 200

СкрытьПоказать

Заголовки

Content-Type: application/json

Тело

{
  "rate": "Заявке №{issue_id} была проставлена оценка Плохо"
}

Получение спецификаций заявки

GET`/api/v1/issues/{issue_id}/services{?api_token}`

Метод доступен только для сотрудников в соответствии с настройками прав доступа. При этом поля “Стоимость” (total), “НДС” (total_vat), “Скидка” (discount) будут доступны, только если у пользователя есть право на просмотр стоимости в спецификации заявок.

Пример URI

GET https://<account>.okdesk.ru/api/v1/issues/153/services?api_token=3e9a214215f493c4

Параметры URI

СкрытьПоказать

api_token: string (обязательное) Пример: 3e9a214215f493c4
Ключ авторизации.
issue_id: integer (обязательное) Пример: 153
ID заявки.

Ответ 200

СкрытьПоказать

Заголовки

Content-Type: application/json

Тело

[
  {
    "id": 1,
    "name": "Доставка в сервис",
    "quantity": 1,
    "discount": 2,
    "total": 600,
    "comment": "",
    "total_vat": 343.83,
    "service": {
      "nomenclature_item_id": 1,
      "code": "timerateservice",
      "unit": "выезд",
      "item_type": "service"
    },
    "price_list": {
      "id": 2,
      "name": "Выездные услуги"
    },
    "performer": {
      "id": 3,
      "name": "Петров Иван Сергеевич"
    }
  },
  {
    "id": 2,
    "name": "Услуги с повременной оплатой",
    "quantity": 3,
    "discount": 2,
    "total": 10290,
    "comment": "Различные биллингуемые услуги с почасовой оплатой",
    "total_vat": 1569.66,
    "service": {
      "nomenclature_item_id": 2,
      "code": "service",
      "unit": "человеко-час",
      "item_type": "service"
    },
    "price_list": {
      "id": 3,
      "name": "Биллингуемые услуги"
    },
    "performer": {
      "id": 1,
      "name": "Елизаров Андрей Валерьевич"
    }
  }
]

Добавление спецификации к заявке

POST`/api/v1/issues/{issue_id}/services{?api_token}`

Название	Тип	Обязательность	Описание
service_id	integer	обязательный	ID строки спецификации из прайс-листа
quantity	number	обязательный	Количество (неотрицательное число)
performer_id	integer	опционально	ID исполнителя
comment	string	опционально	Комментарий
total	number	опционально	Стоимость (неотрицательное число)
discount	integer	опционально	Скидка (целое число от 0 до 100)

Переданный исполнитель (performer_id) должен быть активным сотрудником.
Если одновременно передаются параметры “Стоимость” (total) и “Скидка” (discount), то они должны соответствовать друг другу исходя из стоимости соответствующей строки по прайс-листу.
Переданный ID строки спецификации (service_id) должен соответствовать активной строке прайс-листа.

Для ключей, связанных с контактными лицами, данный метод недоступен.
Метод доступен только для ключей, связанных с сотрудниками, имеющими доступ к действиям “Просмотр карточки заявки”, “Просмотр спецификации заявки” и “Добавление строк в спецификацию заявок”.
Если у пользователя нет права на просмотр стоимости в спецификации заявок, то переданные значения параметров “Стоимость” (total) и “Скидка” (discount) будут игнорироваться.

Пример URI

POST https://<account>.okdesk.ru/api/v1/issues/153/services?api_token=3e9a214215f493c4

Параметры URI

СкрытьПоказать

api_token: string (обязательное) Пример: 3e9a214215f493c4
Ключ авторизации.
issue_id: integer (обязательное) Пример: 153
ID заявки.

Запрос с корректными параметрами

СкрытьПоказать

Заголовки

Content-Type: application/json

Тело

{
  "issue_service": {
    "service_id": 1,
    "quantity": 1,
    "performer_id": 3,
    "comment": "Комментарий",
    "discount": 2,
    "total": 600
  }
}

Ответ 200

СкрытьПоказать

Заголовки

Content-Type: application/json

Тело

{
  "id": 1,
  "name": "Доставка в сервис",
  "quantity": 1,
  "discount": 2,
  "total": 600,
  "comment": "Комментарий",
  "total_vat": 343.83,
  "service": {
    "nomenclature_item_id": 1,
    "code": "timerateservice",
    "unit": "выезд",
    "item_type": "service"
  },
  "price_list": {
    "id": 2,
    "name": "Выездные услуги"
  },
  "performer": {
    "id": 3,
    "name": "Петров Иван Сергеевич"
  }
}

Запрос с некорректными параметрами

СкрытьПоказать

Заголовки

Content-Type: application/json

Тело

{
  "issue_service": {
    "service_id": "wrong_code",
    "performer_id": 103,
    "comment": "Комментарий",
    "discount": 2.1,
    "total": -600
  }
}

Ответ 422

СкрытьПоказать

Заголовки

Content-Type: application/json

Тело

{
  "errors": {
    "service_id": [
      "должно иметь тип integer"
    ],
    "quantity": [
      "отсутствует"
    ],
    "performer_id": [
      "Сотрудник не существует, либо не активирован"
    ],
    "discount": [
      "должно иметь тип integer"
    ],
    "total": [
      "должно быть больше или равно 0"
    ]
  }
}

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

GET`/api/v1/issues/{issue_id}/time_entries{?api_token}`

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

Пример URI

GET https://<account>.okdesk.ru/api/v1/issues/166/time_entries?api_token=3e9a214215f493c4

Параметры URI

СкрытьПоказать

api_token: string (обязательное) Пример: 3e9a214215f493c4
Ключ авторизации.
issue_id: integer (обязательное) Пример: 166
ID заявки.

Ответ 200

СкрытьПоказать

Заголовки

Content-Type: application/json

Тело

{
  "spent_time_total": 4,
  "time_entries": [
    {
      "id": 1,
      "comment": "Упаковка",
      "spent_time": 1,
      "logged_at": "2018-10-16T11:14:00.000+03:00",
      "employee": {
        "id": 1,
        "login": "andrey@okdesk.ru",
        "name": "Елизаров Андрей Валерьевич"
      },
      "parameters": [
        {
          "code": "address",
          "name": "Адрес вызова",
          "field_type": "ftstring",
          "value": "ул. Ленина 44"
        }
      ]
    },
    {
      "id": 2,
      "comment": "Доставка",
      "spent_time": 2,
      "logged_at": "2018-10-16T13:10:00.000+03:00",
      "employee": {
        "id": 2,
        "login": "petrov@okdesk.ru",
        "name": "Петров Иван Сергеевич"
      },
      "parameters": [
        {
          "code": "address",
          "name": "Адрес вызова",
          "field_type": "ftstring",
          "value": "ул. Ленина 44"
        }
      ]
    },
    {
      "id": 3,
      "comment": "Установка",
      "spent_time": 1,
      "logged_at": "2018-10-16T14:10:00.000+03:00",
      "employee": null,
      "parameters": [
        {
          "code": "address",
          "name": "Адрес вызова",
          "field_type": "ftstring",
          "value": "ул. Ленина 44"
        }
      ]
    }
  ]
}

Списание трудозатрат по заявке

POST`/api/v1/issues/{issue_id}/time_entries{?api_token}`

Название	Тип	Обязательность	Описание
employee_id	integer	обязательный	ID сотрудника, от имени которого списываются трудозатраты
formatted_spent_time	string	обязательный	Количество списываемого времени(2 ч. 30 мин. или 2:30 или 2,5 часа и т.д.)
logged_at	string	обязательный	Дата списания
comment	string	опционально	Комментарий
custom_parameters	associative array	опционально	Дополнительные атрибуты трудозатрат

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

Пример URI

POST https://<account>.okdesk.ru/api/v1/issues/166/time_entries?api_token=3e9a214215f493c4

Параметры URI

СкрытьПоказать

api_token: string (обязательное) Пример: 3e9a214215f493c4
Ключ авторизации.
issue_id: integer (обязательное) Пример: 166
ID заявки.

Запрос с корректными параметрами

СкрытьПоказать

Заголовки

Content-Type: application/json

Тело

{
  "time_entries": [
    {
      "employee_id": 1,
      "formatted_spent_time": "60m",
      "logged_at": "2018-10-16 11:14",
      "comment": "Упаковка",
      "custom_parameters": {
        "address": "ул. Ленина 44"
      }
    },
    {
      "employee_id": 2,
      "formatted_spent_time": "120m",
      "logged_at": "2018-10-16 13:10",
      "comment": "Доставка",
      "custom_parameters": {
        "address": "ул. Ленина 44"
      }
    }
  ]
}

Ответ 200

СкрытьПоказать

Заголовки

Content-Type: application/json

Тело

{
  "spent_time_total": 3,
  "time_entries": [
    {
      "id": 1,
      "comment": "Упаковка",
      "spent_time": 1,
      "logged_at": "2018-10-16T11:14:00.000+03:00",
      "parameters": [
        {
          "code": "address",
          "name": "Адрес вызова",
          "field_type": "ftstring",
          "value": "ул. Ленина 44"
        }
      ],
      "employee": {
        "id": 1,
        "login": "andrey@okdesk.ru",
        "name": "Елизаров Андрей Валерьевич"
      }
    },
    {
      "id": 2,
      "comment": "Доставка",
      "spent_time": 2,
      "logged_at": "2018-10-16T13:10:00.000+03:00",
      "parameters": [
        {
          "code": "address",
          "name": "Адрес вызова",
          "field_type": "ftstring",
          "value": "ул. Ленина 44"
        }
      ],
      "employee": {
        "id": 2,
        "login": "petrov@okdesk.ru",
        "name": "Петров Иван Сергеевич"
      }
    }
  ]
}

Запрос с некорректными параметрами

СкрытьПоказать

Заголовки

Content-Type: application/json

Тело

{
  "time_entries": [
    {
      "formatted_spent_time": "60m",
      "comment": "Упаковка",
      "custom_parameters": {
        "address": "ул. Ленина 44"
      }
    }
  ]
}

Ответ 422

СкрытьПоказать

Заголовки

Content-Type: application/json

Тело

{
  "errors": {
    "employee_id": [
      "отсутствует"
    ],
    "logged_at": [
      "отсутствует"
    ]
  }
}

Получение файла заявки

GET`/api/v1/issues/{issue_id}/attachments/{attachment_id}{?api_token}`

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

Пример URI

GET https://<account>.okdesk.ru/api/v1/issues/166/attachments/22?api_token=3e9a214215f493c4

Параметры URI

СкрытьПоказать

api_token: string (обязательное) Пример: 3e9a214215f493c4
Ключ авторизации.
issue_id: integer (обязательное) Пример: 166
ID заявки.
attachment_id: integer (обязательное) Пример: 22
ID файла.

Ответ 200

СкрытьПоказать

Заголовки

Content-Type: application/json

Тело

{
  "id": 22,
  "attachment_file_name": "image.jpg",
  "description": "",
  "attachment_file_size": 7955,
  "is_public": true,
  "created_at": "2019-10-29T17:31:30.675+03:00",
  "attachment_url": "https://static.okdesk.ru/attachments/attachments/000/000/150/original/hqdefault.jpg"
}

Получение чек-листа заявки

GET`/api/v1/issues/{issue_id}/check_lists/items{?api_token}`

Метод доступен только для ключей, связанных с сотрудниками, имеющими доступ к действиям “Просмотр карточки заявки” и “Просмотр чек-листа в заявке”.
Для ключей, связанных с контактными лицами, будут возвращаться только доступные для контактных лиц пункты чек-листа заявки.

Пример URI

GET https://<account>.okdesk.ru/api/v1/issues/166/check_lists/items?api_token=3e9a214215f493c4

Параметры URI

СкрытьПоказать

api_token: string (обязательное) Пример: 3e9a214215f493c4
Ключ авторизации.
issue_id: integer (обязательное) Пример: 166
ID заявки.

Ответ 200

СкрытьПоказать

Заголовки

Content-Type: application/json

Тело

[
    {
        "id": 1001,
        "name": "Проверить герметичность",
        "required": false,
        "visible_for_clients": true,
        "checked_at": "2021-01-27T20:45:00.703+03:00",
        "parameters": [
            {
                "param_type": "quantity",
                "required": true,
                "value": 5
            },
            {
                "param_type": "text",
                "required": true,
                "value": "Утечек не обнаружено"
            },
            {
                "param_type": "string",
                "required": true,
                "value": "51BKB835225"
            },
            {
                "param_type": "files",
                "required": false,
                "value": [
                    {
                        "id": 521,
                        "attachment_file_name": "check_photo.jpeg",
                        "attachment_file_size": 3243,
                        "created_at": "2021-04-23T17:20:27.937+03:00"
                    }
                ]
            }
        ],
        "item_type": "point",
        "parent_id": null,
        "planned_execution_in_hours": 1,
        "position": 1,
        "checked_by_user_id": 2,
        "checked": true
    },
    {
        "id": 1002,
        "name": "Подписать акт досмотра",
        "required": true,
        "required_for_transition_to_status_codes": ["completed", "closed"],
        "required_for_transition_from_status_codes": [],
        "visible_for_clients": false,
        "checked_at": null,
        "parameters": [],
        "item_type": "point",
        "parent_id": null,
        "planned_execution_in_hours": null,
        "position": 2,
        "checked_by_user_id": null,
        "checked": false
    },
]

Создание чек-листа заявки

POST`/api/v1/issues/{issue_id}/check_lists/items{?api_token}`

Название	Тип	Обязательность	Описание
name	string	обязательный	Название пункта чек-листа.
item_type	string	обязательный	Тип пункта чек-листа. Может принимать значение `point` (пункт) или `header` (заголовок).
required_to_status_codes	array of string	опционально	Массив кодов статусов, при входе в которые пункт обязателен к выполнению. Передается только для обязательных пунктов чек-листа.
required_from_status_codes	array of string	опционально	Массив кодов статусов, при выходе из которых пункт обязателен к выполнению. Передается только для обязательных пунктов чек-листа.
visible_for_clients	boolean	опционально	Видимость для клиента.
planned_execution_in_minutes	number	опционально	Плановая продолжительность (в минутах)
parameters	associative array	опционально	Параметры строки чек-листа. Может содержать ключи `files` (параметр выполнения “Фото”), `text` (параметр выполнения “Комментарий”), `string` (параметр выполнения “Строка”), `quantity` (параметр выполнения “Количество”), для которых допустимы значения `required` (обязательный) и `unrequired` (необязательный).
children	array	опционально	Вложенные пункты чек-листа. Передается только для пунктов чек-листа с типом `header`.

Метод доступен только для ключей, связанных с сотрудниками, имеющими доступ к действиям “Просмотр карточки заявки” и “Редактирование чек-листа в заявке”.
Для ключей, связанных с контактными лицами, данный метод недоступен.

Нельзя передавать заголовки на 3 и более уровне вложенности.
Максимальное количество создаваемых пунктов и заголовков - 200.

Пример URI

POST https://<account>.okdesk.ru/api/v1/issues/166/check_lists/items?api_token=3e9a214215f493c4

Параметры URI

СкрытьПоказать

api_token: string (обязательное) Пример: 3e9a214215f493c4
Ключ авторизации.
issue_id: integer (обязательное) Пример: 166
ID заявки.

Запрос с корректными параметрами

СкрытьПоказать

Заголовки

Content-Type: application/json

Тело

{
  "check_list": {
    "items": [
      {
        "name": "Проверить герметичность",
        "item_type": "point",
        "visible_for_clients": true,
        "required_to_status_codes": [
          "completed",
          "closed"
        ],
        "required_from_status_codes": [
          "opened"
        ],
        "planned_execution_in_minutes": 60,
        "parameters": {
          "text": "unrequired",
          "files": "required",
          "quantity": "required"
        }
      },
      {
        "name": "Документы",
        "item_type": "header",
        "children": [
          {
            "name": "Подписать акт досмотра",
            "item_type": "point",
            "visible_for_clients": true,
            "parameters": {
              "text": "required",
              "string": "required"
            }
          }
        ]
      },
      {
        "name": "Проверить уплотнитель",
        "item_type": "point"
      }
    ]
  }
}

Ответ 200

СкрытьПоказать

Заголовки

Content-Type: application/json

Тело

[
  {
    "id": 1584,
    "name": "Проверить герметичность",
    "required": true,
    "visible_for_clients": true,
    "checked_at": null,
    "parameters": [
      {
        "param_type": "quantity",
        "required": true,
        "value": null
      },
      {
        "param_type": "files",
        "required": true,
        "value": []
      },
      {
        "param_type": "text",
        "required": false,
        "value": null
      }
    ],
    "item_type": "point",
    "parent_id": null,
    "planned_execution_in_hours": 1,
    "position": 1,
    "checked": false,
    "checked_by_user_id": null
  },
  {
    "id": 1585,
    "name": "Документы",
    "required": false,
    "visible_for_clients": false,
    "checked_at": null,
    "parameters": [],
    "item_type": "header",
    "parent_id": null,
    "position": 2,
    "checked": false,
    "checked_by_user_id": null
  },
  {
    "id": 1586,
    "name": "Подписать акт досмотра",
    "required": false,
    "visible_for_clients": true,
    "checked_at": null,
    "parameters": [
      {
        "param_type": "text",
        "required": true,
        "value": null
      },
      {
        "param_type": "string",
        "required": true,
        "value": null
      }
    ],
    "item_type": "point",
    "parent_id": 1585,
    "planned_execution_in_hours": null,
    "position": 1,
    "checked": false,
    "checked_by_user_id": null
  },
  {
    "id": 1587,
    "name": "Проверить уплотнитель",
    "required": false,
    "visible_for_clients": false,
    "checked_at": null,
    "parameters": [],
    "item_type": "point",
    "planned_execution_in_hours": 1,
    "parent_id": null,
    "position": 3,
    "checked": false,
    "checked_by_user_id": null
  }
]

Запрос с некорректными параметрами

СкрытьПоказать

Заголовки

Content-Type: application/json

Тело

{
  "check_list": {
    "items": [
      {
        "name": "Проверить герметичность",
        "item_type": "point"
      },
      {
        "name": "Документы",
        "item_type": "header",
        "children": [
          {
            "name": "Подписать акт досмотра",
            "item_type": "incorrect_type"
          }
        ]
      }
    ]
  }
}

Ответ 422

СкрытьПоказать

Заголовки

Content-Type: application/json

Тело

{
  "errors": {
    "items": [
      {},
      {
        "children": [
          {
            "item_type": [
              "должен быть одним из: point, header"
            ]
          }
        ]
      }
    ]
  }
}

Добавление чек-листа по шаблону

POST`/api/v1/issues/{issue_id}/check_lists/templates/{template_id}/items{?api_token}`

Метод доступен только для ключей, связанных с сотрудниками, имеющими доступ к действиям “Просмотр карточки заявки” и “Создание чек-листа в заявке”.
Для ключей, связанных с контактными лицами, данный метод недоступен.

ID шаблона отображается в списке шаблонов при наведении на название шаблона.

Пример URI

POST https://<account>.okdesk.ru/api/v1/issues/166/check_lists/templates/166/items?api_token=3e9a214215f493c4

Параметры URI

СкрытьПоказать

api_token: string (обязательное) Пример: 3e9a214215f493c4
Ключ авторизации.
issue_id: integer (обязательное) Пример: 166
ID заявки.
template_id: integer (обязательное) Пример: 166
ID шаблона.

Ответ 200

СкрытьПоказать

Заголовки

Content-Type: application/json

Тело

[
  {
    "id": 1584,
    "name": "Проверить герметичность",
    "required": true,
    "visible_for_clients": true,
    "checked_at": null,
    "parameters": [
      {
        "param_type": "files",
        "required": true,
        "value": []
      },
      {
        "param_type": "text",
        "required": false,
        "value": null
      }
    ],
    "item_type": "point",
    "parent_id": null,
    "planned_execution_in_hours": 1,
    "position": 1,
    "checked": false,
    "checked_by_user_id": null
  },
  {
    "id": 1585,
    "name": "Документы",
    "required": false,
    "visible_for_clients": false,
    "checked_at": null,
    "parameters": [],
    "item_type": "header",
    "parent_id": null,
    "position": 2,
    "checked": false,
    "checked_by_user_id": null
  },
  {
    "id": 1586,
    "name": "Подписать акт досмотра",
    "required": false,
    "visible_for_clients": true,
    "checked_at": null,
    "parameters": [
      {
        "param_type": "text",
        "required": true,
        "value": null
      },
      {
        "param_type": "string",
        "required": true,
        "value": null
      }
    ],
    "item_type": "point",
    "parent_id": 1585,
    "planned_execution_in_hours": null,
    "position": 1,
    "checked": false,
    "checked_by_user_id": null
  },
  {
    "id": 1587,
    "name": "Проверить уплотнитель",
    "required": false,
    "visible_for_clients": false,
    "checked_at": null,
    "parameters": [],
    "item_type": "point",
    "planned_execution_in_hours": 1,
    "parent_id": null,
    "position": 3,
    "checked": false,
    "checked_by_user_id": null
  }
]

Ответ 404

СкрытьПоказать

Заголовки

Content-Type: application/json

Тело

{
  "errors": "Запись не найдена"
}

Пометка о выполнении строки чек-листа

PATCH`/api/v1/issues/{issue_id}/check_lists/items/{item_id}/check{?api_token}`

Название	Тип	Обязательность	Описание
checked	boolean	обязательный	Признак выполненности
item_parameters	associative array	опционально	Параметры строки чек-листа

Метод доступен только для ключей, связанных с сотрудниками, имеющими доступ к действиям “Просмотр карточки заявки” и “Выполнение чек-листа в заявке”.
Для ключей, связанных с контактными лицами, данный метод недоступен.

Название	Тип	Обязательность	Описание
attachment	string	обязательный	Прикрепляемый файл

Содержание запроса с прикрепленными файлами должно быть в виде multipart/form-data и содержать соответствующий заголовок.
Если в изменяемом пункте чек-листа уже есть прикрепленные файлы, то при прикреплении новых файлов старые будут перезаписаны.

Пример URI

PATCH https://<account>.okdesk.ru/api/v1/issues/166/check_lists/items/1002/check?api_token=3e9a214215f493c4

Параметры URI

СкрытьПоказать

api_token: string (обязательное) Пример: 3e9a214215f493c4
Ключ авторизации.
issue_id: integer (обязательное) Пример: 166
ID заявки.
item_id: integer (обязательное) Пример: 1002
ID пункта чек-листа.

Запрос с корректными параметрами

СкрытьПоказать

Заголовки

Content-Type: application/json

Тело

{
  "check_list_item": {
    "checked": true,
    "item_parameters": {
      "text": "Утечек не обнаружено",
      "string": "51BKB835225",
      "quantity": 5
    }
  }
}

Ответ 200

СкрытьПоказать

Заголовки

Content-Type: application/json

Тело

[
    {
        "id": 1001,
        "name": "Проверить герметичность",
        "required": false,
        "visible_for_clients": true,
        "checked_at": "2021-01-27T20:45:00.703+03:00",
        "parameters": [
            {
                "param_type": "quantity",
                "required": true,
                "value": 5
            },
            {
                "param_type": "text",
                "required": true,
                "value": "Утечек не обнаружено"
            },
            {
                "param_type": "string",
                "required": true,
                "value": "51BKB835225"
            }
        ],
        "item_type": "point",
        "parent_id": null,
        "planned_execution_in_hours": 1,
        "position": 1,
        "checked_by_user_id": 2,
        "checked": true
    },
    {
        "id": 1002,
        "name": "Подписать акт досмотра",
        "required": true,
        "visible_for_clients": false,
        "checked_at": null,
        "parameters": [],
        "item_type": "point",
        "parent_id": null,
        "planned_execution_in_hours": null,
        "position": 2,
        "checked_by_user_id": null,
        "checked": false
    },
]

Запрос с прикрепленными файлами

СкрытьПоказать

Заголовки

Content-Type: multipart/form-data

Тело

curl -X PUT -H "Content-Type: multipart/form-data" -F "check_list_item[checked]=true"
-F "check_list_item[item_parameters][text]=Утечек не обнаружено"
-F "check_list_item[item_parameters][files][0][attachment]=@/home/user/file.jpg"
https://<account>.okdesk.ru/api/v1/issues/12/check_lists/items/1001/check{?api_token}

где @/home/user/file.jpg — это путь к локальному файлу
пример для windows: @"C:/myfile.txt"

Ответ 200

СкрытьПоказать

Заголовки

Content-Type: application/json

Тело

[
    {
        "id": 1001,
        "name": "Проверить герметичность",
        "required": false,
        "visible_for_clients": true,
        "checked_at": "2021-01-27T20:45:00.703+03:00",
        "parameters": [
            {
                "param_type": "text",
                "required": true,
                "value": "Утечек не обнаружено"
            },
            {
                "param_type": "files",
                "required": false,
                "value": [
                    {
                        "id": 521,
                        "attachment_file_name": "check_photo.jpeg",
                        "attachment_file_size": 3243,
                        "created_at": "2021-04-23T17:20:27.937+03:00"
                    }
                ]
            }
        ],
        "item_type": "point",
        "planned_execution_in_hours": 1,
        "parent_id": null,
        "position": 1,
        "checked_by_user_id": 2,
        "checked": true
    },
    {
        "id": 1002,
        "name": "Подписать акт досмотра",
        "required": true,
        "visible_for_clients": false,
        "checked_at": null,
        "parameters": [],
        "item_type": "point",
        "parent_id": null,
        "planned_execution_in_hours": null,
        "position": 2,
        "checked_by_user_id": null,
        "checked": false
    },
]

Запрос с некорректными параметрами

СкрытьПоказать

Заголовки

Content-Type: application/json

Тело

{
  "check_list_item": {
    "checked": 1234
  }
}

Ответ 422

СкрытьПоказать

Заголовки

Content-Type: application/json

Тело

{
  "errors": {
    "checked": [
      "должно иметь тип boolean"
    ]
  }
}

Редактирование заявки

PATCH`/api/v1/issues/{issue_id}{?api_token}`

Название	Тип	Обязательность	Описание
title	string	опционально	Тема заявки
description	string	опционально	Описание заявки

Редактирование заявки будет выполнено только в том случае, если связанный с ключом сотрудник имеет права на просмотр заявки и редактирование атрибутов заявки в соответствии с настройками прав доступа. Для ключей, связанных с контактными лицами, данный метод недоступен.

Параметр title не может передаваться с пустым значением.

Пример URI

PATCH https://<account>.okdesk.ru/api/v1/issues/763?api_token=3e9a214215f493c4

Параметры URI

СкрытьПоказать

api_token: string (обязательное) Пример: 3e9a214215f493c4
Ключ авторизации.
issue_id: integer (обязательное) Пример: 763
ID заявки.

Запрос с корректными параметрами

СкрытьПоказать

Заголовки

Content-Type: application/json

Тело

{
  "issue": {
    "title": "Новая тема",
    "description": "Новое описание"
  }
}

Ответ 200

СкрытьПоказать

Заголовки

Content-Type: application/json

Тело

{
  "id": 153,
  "title": "Новая тема",
  "description": "Новое описание",
  "created_at": "2016-03-15T18:05:17.568+03:00",
  "completed_at": "2016-05-19T10:54:09.987+03:00",
  "deadline_at": "2019-09-24T14:35:00.000+03:00",
  "source": "from_employee",
  "spent_time_total": 0,
  "start_execution_until": "2016-03-16T09:05:17.568+03:00",
  "planned_execution_in_hours": 12,
  "planned_reaction_at": "2016-04-11T11:00:00.000+03:00",
  "reacted_at": "2016-04-10T18:43:44.951+03:00",
  "updated_at": "2016-08-23T09:39:35.428+03:00",
  "delayed_to": null,
  "company_id": 40,
  "group_id": 3,
  "coexecutors": [
    {
      "id": 3,
      "name": "Артамонов Анатолий Маратович",
      "group": {
        "id": 1,
        "name": "Отдел планирования"
      }
    }
  ],
  "service_object_id": null,
  "equipment_ids": [],
  "attachments": [
    {
      "id": 8,
      "attachment_file_name": "photo.jpg",
      "description": "Фотография неисправности",
      "attachment_file_size": 4149,
      "is_public": false,
      "created_at": "2016-09-30T09:28:50.499+03:00"
    }
  ],
  "status_times": {
    "opened": {
      "total": "134 д., 14 ч., 57 м.",
      "on_schedule_total": "36 д., 0 ч., 39 м."
    },
    "completed": {
      "total": "0 д., 0 ч., 0 м.",
      "on_schedule_total": "0 д., 0 ч., 0 м."
    }
  },
  "parameters": [],
  "comments": {
    "count": 5,
    "last_at": "2018-07-05T16:06:10.000+03:00"
  },
  "parent_id": null,
  "child_ids": [],
  "type": {
    "id": 2,
    "code": "service",
    "name": "Обслуживание",
    "available_for_client": true
  },
  "priority": {
    "code": "low",
    "name": "Низкий"
  },
  "status": {
    "code": "opened",
    "name": "Открыта"
  },
  "old_status": {
    "code": "completed",
    "name": "Решена"
  },
  "rate": {
    "id": 3,
    "value": "normal"
  },
  "address": {
    "coordinates": [
      53.2184321,
      44.9998082
    ],
    "value": "г Пенза ул Гагарина д 13"
  },
  "observers": [
    {
      "id": 113,
      "type": "employee",
      "name": "Антонов Петр Захарович"
    },
    {
      "id": 121,
      "type": "employee",
      "name": "Акмаев Артем Викторович"
    }
  ],
  "observer_groups": [
    {
      "id": 5,
      "name": "Отдел контроля качества"
    }
  ],
  "contact": {
    "id": 3020,
    "name": "Егор Егоров"
  },
  "agreement": null,
  "assignee": {
    "id": 1,
    "name": "Иванов Иван Викторович"
  },
  "author": {
    "id": 3020,
    "name": "Егор Егоров"
  }
}

Запрос с некорректными параметрами

СкрытьПоказать

Заголовки

Content-Type: application/json

Тело

{
  "title": ""
}

Ответ 422

СкрытьПоказать

Заголовки

Content-Type: application/json

Тело

{
  "errors": {
    "title": [
      "Не может быть пустым"
    ]
  }
}

Информация о заявке

GET`/api/v1/issues/{issue_id}{?api_token}`

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

Тема;
Описание;
Тип;
Приоритет;
Дата регистрации;
Дата решения;
Плановая дата решения;
Дата последнего изменения;
Отложена до;
Статус;
Предыдущий статус (если заявка находится в статусе с кодом completed);
Оценка;
Дополнительные атрибуты, для которых установлена настройка отображения в клиентском портале;
Ответственный и соисполнители (если установлено соответствующее значение атрибута “Показывать ответственного и соисполнителей заявки в Клиентском портале” в настройках клиентского портала);
Наблюдатели-группы и наблюдатели-сотрудники (если установлено соответствующее значение атрибута “Показывать наблюдателей за заявки в Клиентском портале” в настройках клиентского портала);
Компания;
Контактное лицо;
Список публичных файлов заявки (без пометки приватности/публичности файла);
Количество публичных комментариев и дата добавления последнего публичного комментария;
Способ регистрации заявки;
Оставшееся время по нормативу.

Размер файла (attachment_file_size) измеряется в байтах.

Значение дополнительного атрибута типа “Рисунок” возвращается в виде закодированного в base64 изображения в формате PNG.

Пример URI

GET https://<account>.okdesk.ru/api/v1/issues/153?api_token=3e9a214215f493c4

Параметры URI

СкрытьПоказать

api_token: string (обязательное) Пример: 3e9a214215f493c4
Ключ авторизации.
issue_id: integer (обязательное) Пример: 153
ID заявки.

Ответ 200

СкрытьПоказать

Заголовки

Content-Type: application/json

Тело

{
  "id": 153,
  "title": "Требуется мастер на выезд",
  "description": "",
  "created_at": "2016-03-15T18:05:17.568+03:00",
  "completed_at": "2016-05-19T10:54:09.987+03:00",
  "deadline_at": "2019-09-24T14:35:00.000+03:00",
  "source": "from_employee",
  "spent_time_total": 0,
  "start_execution_until": "2016-03-16T09:05:17.568+03:00",
  "planned_execution_in_hours": 12,
  "planned_reaction_at": "2016-04-11T11:00:00.000+03:00",
  "reacted_at": "2016-04-10T18:43:44.951+03:00",
  "updated_at": "2016-08-23T09:39:35.428+03:00",
  "delayed_to": null,
  "company_id": 40,
  "group_id": 3,
  "coexecutors": [
    {
      "id": 3,
      "name": "Артамонов Анатолий Маратович",
      "group": {
        "id": 1,
        "name": "Отдел планирования"
      }
    }
  ],
  "service_object_id": null,
  "equipment_ids": [],
  "attachments": [
    {
      "id": 8,
      "attachment_file_name": "photo.jpg",
      "description": "Фотография неисправности",
      "attachment_file_size": 4149,
      "is_public": false,
      "created_at": "2016-09-30T09:28:50.499+03:00"
    }
  ],
  "status_times": {
    "opened": {
      "total": "134 д., 14 ч., 57 м.",
      "on_schedule_total": "36 д., 0 ч., 39 м."
    },
    "completed": {
      "total": "0 д., 0 ч., 0 м.",
      "on_schedule_total": "0 д., 0 ч., 0 м."
    }
  },
  "parameters": [],
  "comments": {
    "count": 5,
    "last_at": "2018-07-05T16:06:10.000+03:00"
  },
  "parent_id": null,
  "child_ids": [],
  "remaining_time_according_to_standard": 2400,
  "type": {
    "id": 2,
    "code": "service",
    "name": "Обслуживание",
    "available_for_client": true
  },
  "priority": {
    "code": "low",
    "name": "Низкий"
  },
  "status": {
    "code": "opened",
    "name": "Открыта"
  },
  "old_status": {
    "code": "completed",
    "name": "Решена"
  },
  "rate": {
    "id": 3,
    "value": "normal"
  },
  "address": {
    "coordinates": [
      53.2184321,
      44.9998082
    ],
    "value": "г Пенза ул Гагарина д 13"
  },
  "observers": [
    {
      "id": 113,
      "type": "employee",
      "name": "Антонов Петр Захарович"
    },
    {
      "id": 121,
      "type": "employee",
      "name": "Акмаев Артем Викторович"
    }
  ],
  "observer_groups": [
    {
      "id": 5,
      "name": "Отдел контроля качества"
    }
  ],
  "contact": {
    "id": 3020,
    "name": "Егор Егоров"
  },
  "agreement": null,
  "assignee": {
    "id": 1,
    "name": "Иванов Иван Викторович"
  },
  "author": {
    "id": 3020,
    "name": "Егор Егоров"
  }
}

Удаление заявки

DELETE`/api/v1/issues/{issue_id}{?api_token}`

Удаление заявки доступно для сотрудников в соответствии с настройками прав доступа. Для ключей, связанных с контактными лицами, данный метод недоступен.

Пример URI

DELETE https://<account>.okdesk.ru/api/v1/issues/153?api_token=3e9a214215f493c4

Параметры URI

СкрытьПоказать

api_token: string (обязательное) Пример: 3e9a214215f493c4
Ключ авторизации.
issue_id: integer (обязательное) Пример: 153
ID заявки.

Ответ 200

СкрытьПоказать

Заголовки

Content-Type: application/json

Тело

{
  "result": "Заявка была успешно удалена",
  "issue": {
    "id": 153,
    "title": "Требуется мастер на выезд",
    "description": "",
    "created_at": "2016-09-30T09:28:50.499+03:00",
    "completed_at": null,
    "deadline_at": "2016-09-30T17:28:50.000+03:00",
    "updated_at": "2016-09-30T10:34:22.000+03:00",
    "delayed_to": null,
    "source": "from_email",
    "spent_time_total": 6.5,
    "start_execution_until": "2019-09-01T00:00:00.000+03:00",
    "planned_execution_in_hours": 12.5,
    "planned_reaction_at": "2016-10-22T13:00:00.000+03:00",
    "reacted_at": "2016-10-15T15:31:14.383+03:00",
    "company_id": 86,
    "group_id": 3,
    "service_object_id": 3,
    "parameters": [
      {
        "code": "address",
        "name": "Адрес вызова",
        "field_type": "ftstring",
        "value": "ул. Ленина 44"
      }
    ],
    "parent_id": 102,
    "status": {
      "code": "opened",
      "name": "Открыта"
    },
    "old_status": {
      "code": "completed",
      "name": "Решена"
    },
    "assignee": {
      "id": 4,
      "name": "Петров Иван Сергеевич"
    },
    "author": {
      "id": 44,
      "name": "Елизаров Андрей Валерьевич"
    },
    "agreement": {
      "id": 34,
      "title": "Договор об обслуживании",
      "company_ids": [
        1
      ]
    },
    "contact": {
      "id": 44,
      "name": "Елизаров Андрей Валерьевич"
    },
    "priority": {
      "code": "low",
      "name": "Низкий"
    },
    "type": {
      "code": "service",
      "name": "Обслуживание"
    }
  }
}

Оборудование ¶

Поиск оборудования

GET`/api/v1/equipments/{?api_token,serial_number,inventory_number,search_string}`

Поиск осуществляется по точному совпадению серийного номер или инвентарного номера или по подстроке

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

При передаче параметра search_string остальные параметры не учитываются

Пример URI

GET https://<account>.okdesk.ru/api/v1/equipments/?api_token=3e9a214215f493c4&serial_number=51BKB835225&inventory_number=1101040003532&search_string=desk

Параметры URI

СкрытьПоказать

api_token: string (обязательное) Пример: 3e9a214215f493c4
Ключ авторизации.
inventory_number: string (необязательное) Пример: 1101040003532
Инвентарный номер оборудования
serial_number: string (необязательное) Пример: 51BKB835225
Серийный номер оборудования
search_string: string (необязательное) Пример: desk
Искомая подстрока

Ответ 200

СкрытьПоказать

Заголовки

Content-Type: application/json

Тело

{
  "id": 3,
  "serial_number": "1101040003532",
  "inventory_number": "51BKB835225",
  "maintenance_entity_id": 15,
  "parent_id": 43,
  "equipment_kind": {
    "id": 24,
    "code": "laptop",
    "name": "Ноутбук",
    "description": ""
  },
  "equipment_manufacturer": null,
  "equipment_model": null,
  "company": {
    "id": 45,
    "name": "Интеллект+",
    "additional_name": null,
    "site": "intellectplus.com",
    "email": "intel+@okdesk.ru",
    "phone": "+8412 381312",
    "address": "Москва, Тверская-Ямская д.58",
    "comment": "",
    "attachments": [
      {
        "id": 8,
        "attachment_file_name": "photo.jpg",
        "description": "Фотография неисправности",
        "attachment_file_size": 4149,
        "is_public": false,
        "created_at": "2016-09-30T09:28:50.499+03:00"
      }
    ]
  },
  "parameters": [
    {
      "code": "end_of_service_period",
      "name": "Дата окончания сервисного периода",
      "field_type": "ftdate",
      "value": "2018-03-16"
    },
    {
      "code": "color",
      "name": "Цвет",
      "field_type": "ftstring",
      "value": "black"
    }
  ],
  "agreements": [
    {
      "id": 2,
      "title": "Важный Договор"
    }
  ],
  "attachments": [
    {
      "attachment_file_name": "file.jpg",
      "description": "Описание",
      "is_public": true,
      "id": 575
    }
  ]
}

Создание оборудования

POST`/api/v1/equipments/{?api_token}`

Название	Тип	Обязательность	Описание
equipment_type_code	string	обязательный	Код типа оборудования
equipment_manufacturer_code	string	опционально	Код производителя оборудования
equipment_model_code	string	опционально	Код модели оборудования
serial_number	string	опционально	Серийный номер
inventory_number	string	опционально	Инвентарный номер
comment	string	опционально	Комментарий
company_id	string	опционально	ID компании, привязанной к оборудованию
maintenance_entity_id	string	опционально	ID объекта обслуживания, к которому привязано оборудование
parent_id	string	опционально	ID головного оборудования
custom_parameters	associative array	опционально	Дополнительные атрибуты оборудования
agreement_ids	associative array	опционально	Набор ID договоров оборудования

Если Код типа оборудования (equipment_type_code) или Код производителя оборудования (equipment_manufacturer_code) не соответствует кодам типа и производителя модели оборудования (equipment_model_code), то оборудование не будет создано.
Если ID объекта обслуживания (maintenance_entity_id) не соответствует ID компании (company_id), то оборудование не будет создано.
Если ID договора из массива (agreement_ids) не соответствует ID компании (company_id), то оборудование не будет создано.
Создаваемое и головное оборудование должны быть связаны с одной той же компанией и одним и тем же объектом обслуживания.

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

Пример URI

POST https://<account>.okdesk.ru/api/v1/equipments/?api_token=3e9a214215f493c4

Параметры URI

СкрытьПоказать

api_token: string (обязательное) Пример: 3e9a214215f493c4
Ключ авторизации.

Запрос с корректными параметрами

СкрытьПоказать

Заголовки

Content-Type: application/json

Тело

{
  "equipment": {
    "equipment_type_code": "laptop",
    "equipment_manufacturer_code": "Asus",
    "equipment_model_code": "K53sm",
    "serial_number": "51BKB835225",
    "inventory_number": "11010400003532",
    "comment": "В ноутбуке модели K53SM используется дискретное графическое ядро NVIDIA® GeForce® 630M с видеопамятью объемом 2 гигабайт. Этого будет достаточно для современных компьютерных игр и мультимедийных приложений.",
    "company_id": "4",
    "maintenance_entity_id": "15",
    "parent_id": "74",
    "custom_parameters": {
      "end_of_service_period": "16/03/2018",
      "color": "black"
    },
    "agreement_ids": [
      2
    ]
  }
}

Ответ 200

СкрытьПоказать

Заголовки

Content-Type: application/json

Тело

{
  "id": 3,
  "serial_number": "1101040003532",
  "inventory_number": "51BKB835225",
  "equipment_kind": {
    "id": 24,
    "code": "laptop",
    "name": "Ноутбук",
    "description": null
  },
  "equipment_manufacturer": {
    "id": 1,
    "code": "asus",
    "name": "Asus",
    "description": null
  },
  "equipment_model": {
    "id": 1,
    "code": "k53sm",
    "name": "K53sm",
    "description": null
  },
  "company": {
    "id": 4,
    "name": "Интеллект+",
    "additional_name": null,
    "site": "intellectplus.com",
    "email": "intel+@okdesk.ru",
    "phone": "+8412 381312",
    "address": "Москва, Тверская-Ямская д.58",
    "comment": "",
    "attachments": [
      {
        "id": 8,
        "attachment_file_name": "photo.jpg",
        "description": "Фотография неисправности",
        "attachment_file_size": 4149,
        "is_public": false,
        "created_at": "2016-09-30T09:28:50.499+03:00"
      }
    ]
  },
  "comment": "В ноутбуке модели K53SM используется дискретное графическое ядро NVIDIA® GeForce® 630M с видеопамятью объемом 2 гигабайт. Этого будет достаточно для современных компьютерных игр и мультимедийных приложений.",
  "maintenance_entity_id": 15,
  "parent_id": 74,
  "parameters": [
    {
      "code": "end_of_service_period",
      "name": "Дата окончания сервисного периода",
      "field_type": "ftdate",
      "value": "2018-03-16"
    },
    {
      "code": "color",
      "name": "Цвет",
      "field_type": "ftstring",
      "value": "black"
    }
  ],
  "agreements": [
    {
      "id": 2,
      "title": "Важный Договор"
    }
  ],
  "attachments": [
    {
      "attachment_file_name": "file.jpg",
      "description": "Описание",
      "is_public": true,
      "id": 575
    }
  ]
}

Запрос с некорректными параметрами

СкрытьПоказать

Заголовки

Content-Type: application/json

Тело

{
  "equipment": {
    "equipment_type_code": "laptop",
    "equipment_manufacturer_code": "Siemens",
    "equipment_model_code": "x989",
    "serial_number": "51BKB835225",
    "inventory_number": "11010400003532",
    "company_id": "456",
    "maintenance_entity_id": "77",
    "parent_id": "54",
    "custom_parameters": {
      "package": "premium"
    }
  }
}

Ответ 422

СкрытьПоказать

Заголовки

Content-Type: application/json

Тело

{
  "errors": {
    "equipment_manufacturer": [
      "Записи Siemens не существует"
    ],
    "company": [
      "Записи 456 не существует"
    ],
    "equipment_model_rule": [
      "Код типа оборудования или код производителя оборудования не соответствует модели оборудования"
    ],
    "maintenance_entity_exists_in_company_scope": [
      "для переданной компании не существует объекта обслуживания 22"
    ],
    "custom_parameters": [
      {
        "package": "Значения дополнительного параметра Комплектация отсутствуют в списке значений: premium"
      }
    ]
  }
}

Редактирование оборудования

PATCH`/api/v1/equipments/{id}{?api_token}`

Название	Тип	Обязательность	Описание
equipment_type_code	string	опционально	Код типа оборудования
equipment_manufacturer_code	string	опционально	Код производителя оборудования
equipment_model_code	string	опционально	Код модели оборудования
serial_number	string	опционально	Серийный номер
inventory_number	string	опционально	Инвентарный номер
comment	string	опционально	Комментарий
company_id	string	опционально	ID компании, привязанной к оборудованию
maintenance_entity_id	string	опционально	ID объекта обслуживания, к которому привязано оборудование
parent_id	string	опционально	ID головного оборудования
custom_parameters	associative array	опционально	Дополнительные атрибуты оборудования
agreement_ids	associative array	опционально	Набор ID договоров оборудования

Если Код типа оборудования (equipment_type_code) или Код производителя оборудования (equipment_manufacturer_code) не соответствует кодам типа и производителя модели оборудования (equipment_model_code), то оборудование не будет создано.
Если ID объекта обслуживания (maintenance_entity_id) не соответствует ID компании (company_id), то отправляемые атрибуты оборудования не будут измененены.
Если ID договора из массива (agreement_ids) не соответствует ID компании (company_id), то отправляемые атрибуты оборудования не будут измененены.
При отправке пустого массива в параметре agreement_ids у оборудования убираются все договоры.
При отправке пустой строки или null в параметрах serial_number, inventory_number, comment, company_id, maintenance_entity_id у оборудования сбрасываются значения данных атрибутов.
Изменяемое и головное оборудование должны быть связаны с одной той же компанией и одним и тем же объектом обслуживания.

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

Пример URI

PATCH https://<account>.okdesk.ru/api/v1/equipments/13?api_token=3e9a214215f493c4

Параметры URI

СкрытьПоказать

api_token: string (обязательное) Пример: 3e9a214215f493c4
Ключ авторизации.
id: integer (обязательное) Пример: 13
ID оборудования.

Запрос с корректными параметрами

СкрытьПоказать

Заголовки

Content-Type: application/json

Тело

{
  "equipment": {
    "equipment_model_code": "x50sm",
    "company_id": "4",
    "maintenance_entity_id": "15",
    "custom_parameters": {
      "end_of_service_period": "16/03/2019"
    }
  }
}

Ответ 200

СкрытьПоказать

Заголовки

Content-Type: application/json

Тело

{
  "id": 3,
  "serial_number": "1101040003532",
  "inventory_number": "51BKB835225",
  "equipment_kind": {
    "id": 24,
    "code": "laptop",
    "name": "Ноутбук",
    "description": null
  },
  "equipment_manufacturer": {
    "id": 1,
    "code": "asus",
    "name": "Asus",
    "description": null
  },
  "equipment_model": {
    "id": 4,
    "code": "x50sm",
    "name": "x50sm",
    "description": null
  },
  "company": {
    "id": 4,
    "name": "Интеллект+",
    "additional_name": null,
    "site": "intellectplus.com",
    "email": "intel+@okdesk.ru",
    "phone": "+8412 381312",
    "address": "Москва, Тверская-Ямская д.58",
    "comment": "",
    "attachments": [
      {
        "id": 8,
        "attachment_file_name": "photo.jpg",
        "description": "Фотография неисправности",
        "attachment_file_size": 4149,
        "is_public": false,
        "created_at": "2016-09-30T09:28:50.499+03:00"
      }
    ]
  },
  "comment": "В ноутбуке модели K53SM используется дискретное графическое ядро NVIDIA® GeForce® 630M с видеопамятью объемом 2 гигабайт. Этого будет достаточно для современных компьютерных игр и мультимедийных приложений.",
  "maintenance_entity_id": 15,
  "parent_id": 23,
  "parameters": [
    {
      "code": "end_of_service_period",
      "name": "Дата окончания сервисного периода",
      "field_type": "ftdate",
      "value": "2018-03-16"
    },
    {
      "code": "color",
      "name": "Цвет",
      "field_type": "ftstring",
      "value": "black"
    }
  ],
  "agreements": [
    {
      "id": 2,
      "title": "Важный Договор"
    }
  ],
  "attachments": [
    {
      "attachment_file_name": "file.jpg",
      "description": "Описание",
      "is_public": true,
      "id": 575
    }
  ]
}

Запрос с некорректными параметрами

СкрытьПоказать

Заголовки

Content-Type: application/json

Тело

{
  "equipment": {
    "equipment_model_code": "x989",
    "serial_number": "51BKB835225",
    "inventory_number": "11010400003532",
    "company_id": "456",
    "maintenance_entity_id": "77",
    "parent_id": "89",
    "custom_parameters": {
      "package": "premium"
    }
  }
}

Ответ 422

СкрытьПоказать

Заголовки

Content-Type: application/json

Тело

{
  "errors": {
    "company": [
      "Записи 456 не существует"
    ],
    "equipment_model_rule": [
      "Код типа оборудования или код производителя оборудования не соответствует модели оборудования"
    ],
    "maintenance_entity_exists_in_company_scope": [
      "для переданной компании не существует объекта обслуживания 22"
    ],
    "custom_parameters": [
      {
        "package": "Значения дополнительного параметра Комплектация отсутствуют в списке значений: premium"
      }
    ]
  }
}

Информация об оборудовании

GET`/api/v1/equipments/{id}{?api_token}`

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

Пример URI

GET https://<account>.okdesk.ru/api/v1/equipments/13?api_token=3e9a214215f493c4

Параметры URI

СкрытьПоказать

api_token: string (обязательное) Пример: 3e9a214215f493c4
Ключ авторизации.
id: integer (обязательное) Пример: 13
ID оборудования.

Ответ 200

СкрытьПоказать

Заголовки

Content-Type: application/json

Тело

{
  "id": 7,
  "serial_number": "51BKB835225",
  "inventory_number": "909786543",
  "comment": "Ноутбук Asus K53sm",
  "company": "Интеллект+",
  "maintenance_entity_id": 15,
  "parent_id": 23,
  "parameters": [
    {
      "code": "attr1",
      "name": "Расширенная гарантия",
      "field_type": "ftstring",
      "value": "36 месяцев"
    },
    {
      "code": "attr2",
      "name": "Дата продажи",
      "field_type": "ftdate",
      "value": "2018-07-06"
    },
    {
      "code": "attr3",
      "name": "Принято на ремонт",
      "field_type": "ftdatetime",
      "value": "2018-09-21T14:11:00.000+03:00"
    },
    {
      "code": "attr4",
      "name": "Гарантийный случай",
      "field_type": "ftcheckbox",
      "value": true
    },
    {
      "code": "attr5",
      "name": "Операционная система",
      "field_type": "ftselect",
      "value": "Windows 10"
    },
    {
      "code": "attr6",
      "name": "Диагностика",
      "field_type": "ftmultiselect",
      "value": [
        "Диск",
        "Материнская плата"
      ]
    }
  ],
  "equipment_kind": {
    "id": 24,
    "code": "laptop",
    "name": "Ноутбук",
    "description": ""
  },
  "equipment_manufacturer": {
    "id": 1,
    "code": "asus",
    "name": "Asus",
    "description": ""
  },
  "equipment_model": {
    "id": 4,
    "code": "x50sm",
    "name": "x50sm",
    "description": ""
  },
  "agreements": [
    {
      "id": 2,
      "title": "Важный Договор"
    }
  ]
}

Получение списка по параметрам

GET`/api/v1/equipments/list/{?api_token}`

Название	Тип	Обязательность	Описание
company_ids	array of integer	опционально	Массив из ID компаний (для отображения оборудования без компаний необходимо передавать в параметре значение “0”). Пример: company_ids[]=1
maintenance_entity_ids	array of integer	опционально	Массив из ID Объект обслуживания (для отображения оборудования без объектов обслуживания необходимо передавать в параметре значение “0”). Пример: maintenance_entity_ids[]=1
agreement_ids	array of integer	опционально	Массив из ID договоров (для отображения оборудования без договоров необходимо передавать в параметре значение “0”). Пример: agreement_ids[]=1
created_since	string	опционально	Дата создания оборудования в часовом поясе аккаунта (С) Пример: created_since=2019-05-25
created_until	string	опционально	Дата создания оборудования в часовом поясе аккаунта (По) Пример: created_until=2019-05-25
equipment_kind_codes	array of string	опционально	Массив из кодов типов оборудования. Пример: equipment_kind_codes[]=X
equipment_manufacterer_codes	array of string	опционально	Массив из кодов производителей оборудования. Пример: equipment_manufacturer_codes[]=X
equipment_model_codes	array of string	опционально	Массив из кодов моделей оборудования. Пример: equipment_model_codes[]=X
custom_parameters	associative array	опционально	Ассоциативный массив из пар Код дополнительного атрибута: Значение или набор значений
page	associative array	опционально	Ассоциативный массив параметров постраничного вывода списка оборудования (подробное описание представлено в таблице ниже).

Название	Тип значения	Обязательность	Описание
size	integer	опционально	Число возвращаемых записей. Не может превышать 100. Пример: page[size]=30
from_id	integer	опционально	ID оборудования, с которого начинается выборка записей. По умолчанию (если не задан параметр direction) выборка осуществляется в направлении от значения from_id в сторону уменьшения id оборудования. Пример: page[from_id]=10
direction	string	опционально	Направление выборки. Доступно два значения: reverse, forward. reverse - возвращает записи, ID которых меньше значения from_id, если параметр from_id передан. При отсутствии параметра from_id выборка осуществляется от наибольшого значения id оборудования. forward - возвращает записи, ID которых больше значения from_id, если параметр from_id передан. При отсутствии параметра from_id выборка осуществляется от наименьшего значения id оборудования. Пример: page[direction]=forward

Метод доступен только для ключей, связанных с сотрудниками, имеющими доступ к действиям “Доступ к списку оборудования” и “Просмотр оборудования в списке”.
Для ключей, связанных с контактными лицами, данный метод недоступен.

Метод возвращает не более 100 записей. В случае, когда параметры постраничного вывода не переданы, будет возвращен список последних 100 созданных оборудований.

Тип атрибута	Тип значения	Описание
Дата	string	Доступны два типа значения: Код дополнительного атрибута_since - задает левую границу диапазона (С) и Код дополнительного атрибута_until - задает правую границу диапазона (По). Может быть передан один из параметров или оба параметра. Пример: custom_parameters[date_code_since]=2018-01-01 custom_parameters[date_code_until]=2018-12-12
Дата/время	string	Доступны два типа значения: Код дополнительного атрибута_since - задает левую границу диапазона (С) и Код дополнительного атрибута_until - задает правую границу диапазона (По). Может быть передан один из параметров или оба параметра. Пример: custom_parameters[datetime_code_since]=2018-01-01 01:01 custom_parameters[datetime_code_until]=2018-12-12 12:12
Чекбокс	string	Доступны два значения true и false. Пример: custom_parameters[checkbox_code]=true
Значение из списка	array of string	Массив из значений списка. Пример: custom_parameters[list_code][]=list_value
Набор значений из списка	array of string	Массив из значений списка. Пример: custom_parameters[list_code][]=list_value

https://<account>.okdesk.ru/api/v1/equipments/list?api_token=3e9a214215f493c4&page[size]=3&page[from_id]=10&page[direction]=forward

Пример URI

GET https://<account>.okdesk.ru/api/v1/equipments/list/?api_token=3e9a214215f493c4

Параметры URI

СкрытьПоказать

api_token: string (обязательное) Пример: 3e9a214215f493c4
Ключ авторизации.

Ответ 200

СкрытьПоказать

Заголовки

Content-Type: application/json

Тело

[
  {
    "id": 32,
    "serial_number": "123",
    "inventory_number": "321",
    "parameters": [
      {
        "code": "checkbox_sample",
        "name": "checkbox_sample",
        "field_type": "ftcheckbox",
        "value": true
      }
    ],
    "company": {
      "id": 113,
      "name": "SomeCompany"
    },
    "maintenance_entity": null,
    "parent_id": 39,
    "equipment_kind": {
      "id": 5,
      "code": "some_lind",
      "name": "some_kind",
      "description": ""
    },
    "equipment_manufacturer": null,
    "equipment_model": null,
    "agreements": [
      {
        "id": 2,
        "title": "Важный Договор"
      }
    ]
  }
]

Добавление файла к оборудованию

POST`/api/v1/equipments/{id}/attachments/{?api_token}`

Название	Тип	Обязательность	Описание
attachments	array	обязательный	Список приложенных файлов

Название	Тип	Обязательность	Описание
attachment	string	обязательный	Прикрепляемый файл
description	string	опционально	Описание файла
is_public	boolean	опционально	Публичность файла

Содержание запроса с прикрепленными файлами должно быть в виде multipart/form-data и содержать соответствующий заголовок.
Если параметр is_public не передан, то флаг публичности для прикрепляемых файлов будет установлен идентично значению настройки “Файлы по умолчанию”

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

Пример URI

POST https://<account>.okdesk.ru/api/v1/equipments/3/attachments/?api_token=3e9a214215f493c4

Параметры URI

СкрытьПоказать

api_token: string (обязательное) Пример: 3e9a214215f493c4
Ключ авторизации.
id: integer (обязательное) Пример: 3
ID оборудования.

Запрос с прикрепленными файлами

СкрытьПоказать

Заголовки

Content-Type: multipart/form-data

Тело

curl  -H "Content-Type: multipart/form-data"
-F "equipment[attachments][0][attachment]=@/home/user/file.jpg"
-F "equipment[attachments][0][is_public]=true"
-F "equipment[attachments][0][description]=Описание"
https://<account>.okdesk.ru/api/v1/equipments/{id}/attachments/{?api_token}

где @/home/user/file.jpg — это путь к локальному файлу
пример для windows: @"C:/myfile.txt"

Ответ 200

СкрытьПоказать

Заголовки

Content-Type: application/json

Тело

{
  "id": 3,
  "serial_number": "1101040003532",
  "inventory_number": "51BKB835225",
  "maintenance_entity_id": 15,
  "parent_id": 43,
  "equipment_kind": {
    "id": 24,
    "code": "laptop",
    "name": "Ноутбук",
    "description": ""
  },
  "equipment_manufacturer": null,
  "equipment_model": null,
  "company": {
    "id": 45,
    "name": "Интеллект+",
    "additional_name": null,
    "site": "intellectplus.com",
    "email": "intel+@okdesk.ru",
    "phone": "+8412 381312",
    "address": "Москва, Тверская-Ямская д.58",
    "comment": "",
    "attachments": [
      {
        "id": 8,
        "attachment_file_name": "photo.jpg",
        "description": "Фотография неисправности",
        "attachment_file_size": 4149,
        "is_public": false,
        "created_at": "2016-09-30T09:28:50.499+03:00"
      }
    ]
  },
  "parameters": [
    {
      "code": "end_of_service_period",
      "name": "Дата окончания сервисного периода",
      "field_type": "ftdate",
      "value": "2018-03-16"
    },
    {
      "code": "color",
      "name": "Цвет",
      "field_type": "ftstring",
      "value": "black"
    }
  ],
  "agreements": [
    {
      "id": 2,
      "title": "Важный Договор"
    }
  ],
  "attachments": [
    {
      "attachment_file_name": "file.jpg",
      "description": "Описание",
      "is_public": true,
      "id": 575
    }
  ]
}

Объекты обслуживания ¶

Поиск объекта обслуживания

GET`/api/v1/maintenance_entities/{?api_token,name,comment,search_string}`

Поиск осуществляется по точному совпадению названия объекта обслуживания, комментария или по подстроке

При совпадении названий нескольких объектов обслуживания будут возвращены все подходящие значения под критерии поиска При передаче параметра search_string остальные параметры не учитываются

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

Пример URI

GET https://<account>.okdesk.ru/api/v1/maintenance_entities/?api_token=3e9a214215f493c4&name=Магазин №13&comment=Комментарий&search_string=desk

Параметры URI

СкрытьПоказать

api_token: string (обязательное) Пример: 3e9a214215f493c4
Ключ авторизации.
name: string (необязательное) Пример: Магазин №13
Название объекта обслуживания
comment: string (необязательное) Пример: Комментарий
Дополнительная информация об объекте обслуживания
search_string: string (необязательное) Пример: desk
Искомая подстрока

Ответ 200

СкрытьПоказать

Заголовки

Content-Type: application/json

Тело

[
  {
    "id": 1,
    "name": "Магазин №13",
    "address": null,
    "comment": null,
    "default_assignee_id": 12,
    "default_assignee_group_id": 1,
    "company_id": 1040,
    "active": true,
    "timezone": {
      "code": "Moscow",
      "name": "Москва",
      "gmt": "+03:00"
    },
    "contacts_ids": [
      23,
      24,
      63,
      64,
      65
    ],
    "equipments_ids": [
      8,
      9
    ],
    "coordinates": [
      53.2184321,
      44.9998082
    ],
    "parameters": [
      {
        "code": "attr1",
        "name": "Номер документа",
        "field_type": "ftstring",
        "value": "2368590"
      },
      {
        "code": "attr2",
        "name": "Дата начала сотрудничества",
        "field_type": "ftdate",
        "value": "2019-02-06"
      },
      {
        "code": "attr3",
        "name": "Дата следущего созвона",
        "field_type": "ftdatetime",
        "value": "2019-02-21T14:00:00.000+03:00"
      },
      {
        "code": "attr4",
        "name": "Вип обслуживание",
        "field_type": "ftcheckbox",
        "value": true
      },
      {
        "code": "attr5",
        "name": "Вид деятельности",
        "field_type": "ftselect",
        "value": "Программное обеспечение"
      },
      {
        "code": "attr6",
        "name": "Виды помещений",
        "field_type": "ftmultiselect",
        "value": [
          "Главный офис",
          "Зона отдыха"
        ]
      }
    ],
    "schedule": {
      "id": 1,
      "name": "По рабочим дням с 9:00 до 18:00"
    },
    "observers": [
      {
        "id": 5,
        "name": "Иванов Сергей Петрович"
      },
      {
        "id": 12,
        "name": "Петров Иван Валерьевич"
      }
    ],
    "observer_groups": [
      {
        "id": 23,
        "name": "Механики"
      },
      {
        "id": 3,
        "name": "Водители"
      }
    ],
    "attachments": [
      {
        "attachment_file_name": "file.jpg",
        "description": "Описание",
        "is_public": true,
        "id": 575
      }
    ],
    "agreements": [
      {
        "id": 2,
        "title": "Важный Договор"
      }
    ]
  }
]

Создание объекта обслуживания

POST`/api/v1/maintenance_entities/{?api_token}`

Название	Тип	Обязательность	Описание
name	string	обязательный	Название объекта обслуживания
company_id	integer	обязательный	ID компании
agreement_ids	array of int	необязательный	ID договоров
address	string	необязательный	Адрес объекта обслуживания. Внимание! При передаче текстовой части адреса автоматическая подстановка координат адреса (геокодинг) не осуществляется. Для того, чтобы адрес отображался на карте, необходимо дополнительно передать координаты адреса в параметре coordinates. Перевести текстовую часть адреса в координаты можно с помощью сервисов геокодинга, например DaData.ru, Google Geocoding API и т.д.
coordinates	array of float	необязательный	Координаты объекта обслуживания
timezone	string	необязательный	Часовой пояс объекта обслуживания
comment	string	необязательный	Дополнительная информация об объекте обслуживания
default_assignee_id	integer	необязательный	ID ответственного по умолчанию
default_assignee_group_id	integer	необязательный	ID ответственной группы по умолчанию
schedule_id	integer	необязательный	ID графика работы объекта обслуживания
observer_ids	array of int	необязательный	Массив из ID пользователей, являющихся наблюдателями объекта обслуживания
observer_group_ids	array of int	необязательный	Массив из ID групп сотрудников, являющихся наблюдателями объекта обслуживания
custom_parameters	associative array	опционально	Дополнительные атрибуты объекта обслуживания

Параметр coordinates - массив из двух вещественных чисел (широта от -90 до 90, долгота от -180 до 180). Параметр agreement_ids должен содержать ID договоров, которые связаны с компанией, переданной в company_id.

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

Пример URI

POST https://<account>.okdesk.ru/api/v1/maintenance_entities/?api_token=3e9a214215f493c4

Параметры URI

СкрытьПоказать

api_token: string (обязательное) Пример: 3e9a214215f493c4
Ключ авторизации.

Запрос

СкрытьПоказать

Заголовки

Content-Type: application/json

Тело

{
  "maintenance_entity": {
    "name": "Магазин №13",
    "company_id": 1040,
    "agreement_ids": [
      2
    ],
    "address": "г Пенза ул Гагарина д 13",
    "comment": "Комментарий",
    "default_assignee_id": 12,
    "default_assignee_group_id": 1,
    "timezone": "Moscow",
    "coordinates": [
      53.2184321,
      44.9998082
    ],
    "schedule_id": 1,
    "observer_ids": [
      5,
      12
    ],
    "custom_parameters": {
      "code1": "123456789",
      "code2": "2019-02-15",
      "code3": true
    }
  }
}

Ответ 200

СкрытьПоказать

Заголовки

Content-Type: application/json

Тело

{
  "id": 9,
  "name": "Магазин №13",
  "address": "г Пенза ул Гагарина д 13",
  "comment": "Комментарий",
  "default_assignee_id": 12,
  "default_assignee_group_id": 1,
  "company_id": 1040,
  "active": true,
  "timezone": {
    "code": "Moscow",
    "name": "Москва",
    "gmt": "+03:00"
  },
  "coordinates": [
    53.2184321,
    44.9998082
  ],
  "parameters": [
    {
      "code": "code1",
      "name": "Номер документа",
      "field_type": "ftstring",
      "value": "123456789"
    },
    {
      "code": "code2",
      "name": "Дата начала сотрудничества",
      "field_type": "ftdate",
      "value": "2019-02-15"
    },
    {
      "code": "code3",
      "name": "Вип обслуживание",
      "field_type": "ftcheckbox",
      "value": true
    }
  ],
  "schedule": {
    "id": 1,
    "name": "По рабочим дням с 9:00 до 18:00"
  },
  "observers": [
    {
      "id": 5,
      "name": "Иванов Сергей Петрович"
    },
    {
      "id": 12,
      "name": "Петров Иван Валерьевич"
    }
  ],
  "observer_groups": [],
  "attachments": [],
  "agreements": [
    {
      "id": 2,
      "title": "Важный Договор"
    }
  ]
}

Запрос с некорректными параметрами

СкрытьПоказать

Заголовки

Content-Type: application/json

Тело

{
  "maintenance_entity": {
    "name": "Магазин №13",
    "company_id": 9999999,
    "address": "г Пенза ул Гагарина д 13",
    "comment": "Комментарий",
    "default_assignee_id": 12,
    "default_assignee_group_id": 1
  }
}

Ответ 422

СкрытьПоказать

Заголовки

Content-Type: application/json

Тело

{
  "errors": {
    "company": [
      "Записи 9999999 не существует"
    ]
  }
}

Редактирование объекта обслуживания

PATCH`/api/v1/maintenance_entities/{id}{?api_token}`

Название	Тип	Обязательность	Описание
name	string	необязательный	Название объекта обслуживания
company_id	integer	необязательный	ID компании
agreement_ids	array of int	необязательный	ID договоров
address	string	необязательный	Адрес объекта обслуживания. Внимание! При передаче текстовой части адреса автоматическая подстановка координат адреса (геокодинг) не осуществляется. Для того, чтобы адрес отображался на карте, необходимо дополнительно передать координаты адреса в параметре coordinates. Перевести текстовую часть адреса в координаты можно с помощью сервисов геокодинга, например DaData.ru, Google Geocoding API и т.д.
coordinates	array of float	необязательный	Координаты объекта обслуживания
timezone	string	необязательный	Часовой пояс объекта обслуживания
comment	string	необязательный	Дополнительная информация об объекте обслуживания
default_assignee_id	integer	необязательный	ID ответственного по умолчанию
default_assignee_group_id	integer	необязательный	ID ответственной группы по умолчанию
schedule_id	integer	необязательный	ID графика работы объекта обслуживания
observer_ids	array of int	необязательный	Массив из ID пользователей, являющихся наблюдателями объекта обслуживания
observer_group_ids	array of int	необязательный	Массив из ID групп сотрудников, являющихся наблюдателями объекта обслуживания
custom_parameters	associative array	опционально	Дополнительные атрибуты объекта обслуживания

Параметр name не может передаваться с пустым значением

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

Пример URI

PATCH https://<account>.okdesk.ru/api/v1/maintenance_entities/4?api_token=3e9a214215f493c4

Параметры URI

СкрытьПоказать

api_token: string (обязательное) Пример: 3e9a214215f493c4
Ключ авторизации.
id: integer (обязательное) Пример: 4
ID объекта обслуживания.

Запрос

СкрытьПоказать

Заголовки

Content-Type: application/json

Тело

{
  "maintenance_entity": {
    "name": "Магазин №15",
    "address": "г Пенза ул Гагарина д 15",
    "agreement_ids": [
      2
    ],
    "default_assignee_id": 14,
    "default_assignee_group_id": 1,
    "timezone": "Samara",
    "schedule_id": 1,
    "observer_group_ids": [
      7
    ],
    "coordinates": [
      53.2184321,
      44.9998082
    ],
    "custom_parameters": {
      "code2": "2019-02-15"
    }
  }
}

Ответ 200

СкрытьПоказать

Заголовки

Content-Type: application/json

Тело

{
  "id": 9,
  "name": "Магазин №15",
  "address": "г Пенза ул Гагарина д 15",
  "comment": "Комментарий",
  "default_assignee_id": 14,
  "default_assignee_group_id": 1,
  "company_id": 1040,
  "active": true,
  "timezone": {
    "code": "Samara",
    "name": "Самара",
    "gmt": "+04:00"
  },
  "coordinates": [
    53.2184321,
    44.9998082
  ],
  "parameters": [
    {
      "code": "code1",
      "name": "Номер документа",
      "field_type": "ftstring",
      "value": "123456789"
    },
    {
      "code": "code2",
      "name": "Дата начала сотрудничества",
      "field_type": "ftdate",
      "value": "2019-02-15"
    },
    {
      "code": "code3",
      "name": "Вип обслуживание",
      "field_type": "ftcheckbox",
      "value": true
    }
  ],
  "schedule": {
    "id": 1,
    "name": "По рабочим дням с 9:00 до 18:00"
  },
  "observers": [],
  "observer_groups": [
    {
      "id": 7,
      "name": "Электрики"
    }
  ],
  "attachments": [
    {
      "attachment_file_name": "file.jpg",
      "description": "Описание",
      "is_public": true,
      "id": 575
    }
  ],
  "agreements": [
    {
      "id": 2,
      "title": "Важный Договор"
    }
  ]
}

Запрос с некорректными параметрами

СкрытьПоказать

Заголовки

Content-Type: application/json

Тело

{
  "maintenance_entity": {
    "name": ""
  }
}

Ответ 422

СкрытьПоказать

Заголовки

Content-Type: application/json

Тело

{
  "errors": {
    "name": [
      "не может быть пустым"
    ]
  }
}

Информация об объекте обслуживания

GET`/api/v1/maintenance_entities/{id}{?api_token}`

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

Пример URI

GET https://<account>.okdesk.ru/api/v1/maintenance_entities/153?api_token=3e9a214215f493c4

Параметры URI

СкрытьПоказать

api_token: string (обязательное) Пример: 3e9a214215f493c4
Ключ авторизации.
id: integer (обязательное) Пример: 153
ID объекта обслуживания.

Ответ 200

СкрытьПоказать

Заголовки

Content-Type: application/json

Тело

{
  "id": 1,
  "name": "Сервисный центр `Интеллект+`",
  "address": "г. Самара улица Рябова д. 3",
  "comment": "",
  "default_assignee_id": 12,
  "default_assignee_group_id": 1,
  "company_id": 1,
  "active": true,
  "timezone": {
    "code": "Kaliningrad",
    "name": "Калининград",
    "gmt": "+02:00"
  },
  "contacts_ids": [
    23,
    24,
    63,
    64,
    65
  ],
  "equipments_ids": [
    8,
    9
  ],
  "coordinates": [
    53.2605796,
    49.9179003
  ],
  "parameters": [
    {
      "code": "attr1",
      "name": "Номер документа",
      "field_type": "ftstring",
      "value": "2368590"
    },
    {
      "code": "attr2",
      "name": "Дата начала сотрудничества",
      "field_type": "ftdate",
      "value": "2019-02-06"
    },
    {
      "code": "attr3",
      "name": "Дата следущего созвона",
      "field_type": "ftdatetime",
      "value": "2019-02-21T14:00:00.000+03:00"
    },
    {
      "code": "attr4",
      "name": "Вип обслуживание",
      "field_type": "ftcheckbox",
      "value": true
    },
    {
      "code": "attr5",
      "name": "Вид деятельности",
      "field_type": "ftselect",
      "value": "Программное обеспечение"
    },
    {
      "code": "attr6",
      "name": "Виды помещений",
      "field_type": "ftmultiselect",
      "value": [
        "Главный офис",
        "Зона отдыха"
      ]
    }
  ],
  "schedule": {
    "id": 1,
    "name": "По рабочим дням с 9:00 до 18:00"
  },
  "observers": [
    {
      "id": 5,
      "name": "Иванов Сергей Петрович"
    }
  ],
  "observer_groups": [
    {
      "id": 7,
      "name": "Электрики"
    }
  ],
  "attachments": [
    {
      "attachment_file_name": "file.jpg",
      "description": "Описание",
      "is_public": true,
      "id": 575
    }
  ],
  "agreements": [
    {
      "id": 2,
      "title": "Важный Договор"
    }
  ]
}

Получение списка по параметрам

GET`/api/v1/maintenance_entities/list{?api_token}`

Название	Тип	Обязательность	Описание
company_ids	array of integer	опционально	Массив из ID компаний. Пример: company_ids[]=1
agreement_ids	array of integer	опционально	Массив из ID договоров (для отображения объектов обслуживания без договоров необходимо передавать в параметре значение “0”). Пример: agreement_ids[]=1
default_assignee_ids	array of integer	опционально	Массив из ID ответственных (для отображения объектов обслуживания без ответственного необходимо передавать в параметре значение “0”). Пример: default_assignee_ids[]=1
default_assignee_group_ids	array of integer	опционально	Массив из ID ответственных групп (для отображения объектов обслуживания без ответственной группы необходимо передавать в параметре значение “0”). Пример: default_assignee_group_ids[]=1
created_since	string	опционально	Дата создания объектов обслуживания в часовом поясе аккаунта (С) Пример: created_since=2019-05-25
created_until	string	опционально	Дата создания объектов обслуживания в часовом поясе аккаунта (По) Пример: created_until=2019-05-25
updated_since	string	опционально	Дата изменения объектов обслуживания в часовом поясе аккаунта (С) Пример: updated_since=2019-05-25
updated_until	string	опционально	Дата изменения объектов обслуживания в часовом поясе аккаунта (По) Пример: updated_until=2019-05-25
page	associative array	опционально	Ассоциативный массив параметров постраничного вывода списка объектов обслуживания (подробное описание представлено в таблице ниже).

Название	Тип значения	Обязательность	Описание
size	integer	опционально	Число возвращаемых записей. Не может превышать 100. Пример: page[size]=30
from_id	integer	опционально	ID объекта обслуживания, с которого начинается выборка записей. По умолчанию (если не задан параметр direction) выборка осуществляется в направлении от значения from_id в сторону уменьшения id объекта. Пример: page[from_id]=10
direction	string	опционально	Направление выборки. Доступно два значения: reverse, forward. reverse - возвращает записи, ID которых меньше значения from_id, если параметр from_id передан. При отсутствии параметра from_id выборка осуществляется от наибольшого значения id объекта. forward - возвращает записи, ID которых больше значения from_id, если параметр from_id передан. При отсутствии параметра from_id выборка осуществляется от наименьшего значения id объекта. Пример: page[direction]=forward

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

Метод возвращает не более 100 записей. В случае, когда параметры постраничного вывода не переданы, будет возвращен список последних 100 созданных объектов обслуживания.

https://<account>.okdesk.ru/api/v1/maintenance_entities/list?
  api_token=3e9a214215f493c4&page[size]=3&page[from_id]=10&page[direction]=forward

Пример URI

GET https://<account>.okdesk.ru/api/v1/maintenance_entities/list?api_token=3e9a214215f493c4

Параметры URI

СкрытьПоказать

api_token: string (обязательное) Пример: 3e9a214215f493c4
Ключ авторизации.

Ответ 200

СкрытьПоказать

Заголовки

Content-Type: application/json

Тело

[
  {
    "id": 8,
    "name": "Объект №2",
    "address": "г. Москва",
    "coordinates": [
      55.755831,
      37.617673
    ],
    "company_id": 1,
    "active": true,
    "agreements": [
      {
        "id": 1,
        "title": "Важный Договор"
      }
    ],
    "parameters": [
      {
        "code": "attr1",
        "name": "Номер документа",
        "field_type": "ftstring",
        "value": "2368590"
      }
    ]
  },
  {
    "id": 5,
    "name": "Объект №1",
    "address": "г. Санкт-Петербург",
    "coordinates": [
      59.869778,
      30.278344
    ],
    "company_id": 3,
    "active": true,
    "agreements": [],
    "parameters": [
      {
        "code": "attr1",
        "name": "Номер документа",
        "field_type": "ftstring",
        "value": "1168590"
      }
    ]
  }
]

Добавление файла к объекту обслуживания

POST`/api/v1/maintenance_entities/{id}/attachments/{?api_token}`

Название	Тип	Обязательность	Описание
attachments	array	обязательный	Список приложенных файлов

Название	Тип	Обязательность	Описание
attachment	string	обязательный	Прикрепляемый файл
description	string	опционально	Описание файла
is_public	boolean	опционально	Публичность файла

Содержание запроса с прикрепленными файлами должно быть в виде multipart/form-data и содержать соответствующий заголовок.
Если параметр is_public не передан, то флаг публичности для прикрепляемых файлов будет установлен идентично значению настройки “Файлы по умолчанию”

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

Пример URI

POST https://<account>.okdesk.ru/api/v1/maintenance_entities/153/attachments/?api_token=3e9a214215f493c4

Параметры URI

СкрытьПоказать

api_token: string (обязательное) Пример: 3e9a214215f493c4
Ключ авторизации.
id: integer (обязательное) Пример: 153
ID объекта обслуживания.

Запрос с прикрепленными файлами

СкрытьПоказать

Заголовки

Content-Type: multipart/form-data

Тело

curl  -H "Content-Type: multipart/form-data"
-F "maintenance_entity[attachments][0][attachment]=@/home/user/file.jpg"
-F "maintenance_entity[attachments][0][is_public]=true"
-F "maintenance_entity[attachments][0][description]=Описание"
https://<account>.okdesk.ru/api/v1/maintenance_entities/{id}/attachments/{?api_token}

где @/home/user/file.jpg — это путь к локальному файлу
пример для windows: @"C:/myfile.txt"

Ответ 200

СкрытьПоказать

Заголовки

Content-Type: application/json

Тело

{
  "id": 9,
  "name": "Магазин №13",
  "address": "г Пенза ул Гагарина д 13",
  "comment": "Комментарий",
  "default_assignee_id": 12,
  "default_assignee_group_id": 1,
  "company_id": 1040,
  "active": true,
  "timezone": {
    "code": "Moscow",
    "name": "Москва",
    "gmt": "+03:00"
  },
  "coordinates": [
    53.2184321,
    44.9998082
  ],
  "parameters": [
    {
      "code": "code1",
      "name": "Номер документа",
      "field_type": "ftstring",
      "value": "123456789"
    },
    {
      "code": "code2",
      "name": "Дата начала сотрудничества",
      "field_type": "ftdate",
      "value": "2019-02-15"
    },
    {
      "code": "code3",
      "name": "Вип обслуживание",
      "field_type": "ftcheckbox",
      "value": true
    }
  ],
  "schedule": null,
  "observers": [],
  "observer_groups": [],
  "attachments": [
    {
      "attachment_file_name": "file.jpg",
      "description": "Описание",
      "is_public": true,
      "id": 575
    }
  ],
  "agreements": [
    {
      "id": 2,
      "title": "Важный Договор"
    }
  ]
}

Архивация объекта обслуживания

PATCH`/api/v1/maintenance_entities/{id}/activations{?api_token}`

Название	Тип	Обязательность	Описание
active	boolean	обязательный	Статус активности объекта обслуживания

Архивация объекта обслуживания доступна для сотрудников в соответствии с настройками прав доступа.

Пример URI

PATCH https://<account>.okdesk.ru/api/v1/maintenance_entities/1/activations?api_token=3e9a214215f493c4

Параметры URI

СкрытьПоказать

api_token: string (обязательное) Пример: 3e9a214215f493c4
Ключ авторизации.
id: integer (обязательное) Пример: 1
ID объекта обслуживания.

Запрос

СкрытьПоказать

Заголовки

Content-Type: application/json

Тело

{
  "active": true
}

Ответ 200

СкрытьПоказать

Заголовки

Content-Type: application/json

Тело

{
  "id": 1,
  "name": "Магазин №13",
  "address": null,
  "comment": null,
  "default_assignee_id": 12,
  "default_assignee_group_id": 1,
  "company_id": 1040,
  "active": true,
  "timezone": {
    "code": "Moscow",
    "name": "Москва",
    "gmt": "+03:00"
  },
  "contacts_ids": [
    23,
    24,
    63,
    64,
    65
  ],
  "equipments_ids": [
    8,
    9
  ],
  "coordinates": null,
  "parameters": [
    {
      "code": "attr1",
      "name": "Номер документа",
      "field_type": "ftstring",
      "value": "2368590"
    },
    {
      "code": "attr2",
      "name": "Дата начала сотрудничества",
      "field_type": "ftdate",
      "value": "2019-02-06"
    },
    {
      "code": "attr3",
      "name": "Дата следущего созвона",
      "field_type": "ftdatetime",
      "value": "2019-02-21T14:00:00.000+03:00"
    },
    {
      "code": "attr4",
      "name": "Вип обслуживание",
      "field_type": "ftcheckbox",
      "value": true
    },
    {
      "code": "attr5",
      "name": "Вид деятельности",
      "field_type": "ftselect",
      "value": "Программное обеспечение"
    },
    {
      "code": "attr6",
      "name": "Виды помещений",
      "field_type": "ftmultiselect",
      "value": [
        "Главный офис",
        "Зона отдыха"
      ]
    }
  ],
  "schedule": {
    "id": 1,
    "name": "По рабочим дням с 9:00 до 18:00"
  },
  "observers": [
    {
      "id": 5,
      "name": "Иванов Сергей Петрович"
    },
    {
      "id": 12,
      "name": "Петров Иван Валерьевич"
    }
  ],
  "observer_groups": [
    {
      "id": 23,
      "name": "Механики"
    },
    {
      "id": 3,
      "name": "Водители"
    }
  ],
  "attachments": [
    {
      "attachment_file_name": "file.jpg",
      "description": "Описание",
      "is_public": true,
      "id": 575
    }
  ],
  "agreements": [
    {
      "id": 2,
      "title": "Важный Договор"
    }
  ]
}

Склады ¶

Получение списка складов

GET`/api/v1/warehouses{?api_token}`

Название	Тип	Обязательность	Описание
external_id	string	опционально	Параметр для фильтрации по внешнему id
page	associative array	опционально	Ассоциативный массив параметров постраничного вывода складов (подробное описание представлено в таблице ниже).

Название	Тип значения	Обязательность	Описание
size	integer	опционально	Число возвращаемых записей. Не может превышать 100. Пример: page[size]=30
from_id	integer	опционально	ID склада, с которого начинается выборка записей. По умолчанию (если не задан параметр direction) выборка осуществляется в направлении от значения from_id в сторону уменьшения id склада. Пример: page[from_id]=10
direction	string	опционально	Направление выборки. Доступно два значения: reverse, forward. reverse - возвращает записи, ID которых меньше значения from_id, если параметр from_id передан. При отсутствии параметра from_id выборка осуществляется от наибольшого значения id склада. forward - возвращает записи, ID которых больше значения from_id, если параметр from_id передан. При отсутствии параметра from_id выборка осуществляется от наименьшего значения id склада. Пример: page[direction]=forward

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

Метод возвращает не более 100 записей. В случае, когда параметры постраничного вывода не переданы, будет возвращен список последних 100 созданных записей складов.

https://<account>.okdesk.ru/api/v1/warehouses?
  api_token=3e9a214215f493c4&page[size]=2&page[from_id]=10&page[direction]=reverse

Пример URI

GET https://<account>.okdesk.ru/api/v1/warehouses?api_token=3e9a214215f493c4

Параметры URI

СкрытьПоказать

api_token: string (обязательное) Пример: 3e9a214215f493c4
Ключ авторизации.

Ответ 200

СкрытьПоказать

Заголовки

Content-Type: application/json

Тело

[
  {
    "id": 101,
    "name": "Второй склад",
    "active": true,
    "external_id": "112233",
    "assignee_ids": [
      1,
      2
    ],
    "observer_ids": []
  },
  {
    "id": 100,
    "name": "Первый склад",
    "active": false,
    "external_id": null,
    "assignee_ids": [],
    "observer_ids": [
      1,
      2
    ]
  }
]

Ответ 422

СкрытьПоказать

Заголовки

Content-Type: application/json

Тело

{
  "errors": {
    "page": {
      "size": [
        "должно быть меньше или равно 100"
      ],
      "direction": [
        "должен быть одним из: reverse, forward"
      ],
      "from_id": [
        "должно иметь тип integer"
      ]
    }
  }
}

Информация о складе

GET`/api/v1/warehouses/{warehouse_id}{?api_token}`

Метод доступен только для ключей, связанных с сотрудниками, имеющими доступ к действиям “Доступ к разделу Склады” и “Просмотр карточки склада”. Для ключей, связанных с контактными лицами, данный метод недоступен.

https://<account>.okdesk.ru/api/v1/warehouses/100?api_token=3e9a214215f493c4

Пример URI

GET https://<account>.okdesk.ru/api/v1/warehouses/100?api_token=3e9a214215f493c4

Параметры URI

СкрытьПоказать

api_token: string (обязательное) Пример: 3e9a214215f493c4
Ключ авторизации.
warehouse_id: integer (обязательное) Пример: 100
ID склада.

Ответ 200

СкрытьПоказать

Заголовки

Content-Type: application/json

Тело

{
  "id": 100,
  "name": "Первый склад",
  "active": false,
  "external_id": null,
  "assignee_ids": [],
  "observer_ids": [
    1,
    2
  ]
}

Получение остатков

GET`/api/v1/material_assets/remainders{?api_token}`

Название	Тип	Обязательность	Описание
item_types	array of string	опционально	Массив строк для фильтрации по типу элемента номенклатуры. Допустимые значения: material, product.
page	associative array	опционально	Ассоциативный массив параметров постраничного вывода остатков (подробное описание представлено в таблице ниже).

Название	Тип значения	Обязательность	Описание
size	integer	опционально	Число возвращаемых записей. Не может превышать 100. Пример: page[size]=30
from_id	integer	опционально	ID строки справочника, с которой начинается выборка записей. По умолчанию (если не задан параметр direction) выборка осуществляется в направлении от значения from_id в сторону уменьшения id строки справочника. Пример: page[from_id]=10
direction	string	опционально	Направление выборки. Доступно два значения: reverse, forward. reverse - возвращает записи, ID которых меньше значения from_id, если параметр from_id передан. При отсутствии параметра from_id выборка осуществляется от наибольшого значения id строки справочника. forward - возвращает записи, ID которых больше значения from_id, если параметр from_id передан. При отсутствии параметра from_id выборка осуществляется от наименьшего значения id строки справочника. Пример: page[direction]=forward

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

Метод возвращает не более 100 записей. В случае, когда параметры постраничного вывода не переданы, будет возвращен список последних 100 созданных записей остатков.

https://<account>.okdesk.ru/api/v1/material_assets/remainders?
  api_token=3e9a214215f493c4&page[size]=2&page[from_id]=10&page[direction]=reverse

Пример URI

GET https://<account>.okdesk.ru/api/v1/material_assets/remainders?api_token=3e9a214215f493c4

Параметры URI

СкрытьПоказать

api_token: string (обязательное) Пример: 3e9a214215f493c4
Ключ авторизации.

Ответ 200

СкрытьПоказать

Заголовки

Content-Type: application/json

Тело

[
  {
    "id": 101,
    "code": "item_code2",
    "name": "Гвоздь",
    "active": true,
    "item_type": "product",
    "unit": "кг.",
    "vendor_code": "",
    "quantity": 1.5
  },
  {
    "id": 100,
    "code": "item_code1",
    "name": "Шуруп",
    "active": true,
    "item_type": "product",
    "unit": "кг.",
    "vendor_code": "",
    "quantity": 2.5
  }
]

Ответ 422

СкрытьПоказать

Заголовки

Content-Type: application/json

Тело

{
  "errors": {
    "page": {
      "size": [
        "должно быть меньше или равно 100"
      ],
      "direction": [
        "должен быть одним из: reverse, forward"
      ],
      "from_id": [
        "должно иметь тип integer"
      ]
    }
  }
}

Получение остатков на складе

GET`/api/v1/warehouses/{warehouse_id}/remainders{?api_token}`

Название	Тип	Обязательность	Описание
page	associative array	опционально	Ассоциативный массив параметров постраничного вывода остатков (подробное описание представлено в таблице ниже).

Название	Тип значения	Обязательность	Описание
size	integer	опционально	Число возвращаемых записей. Не может превышать 100. Пример: page[size]=30
from_id	integer	опционально	ID строки справочника, с которой начинается выборка записей. По умолчанию (если не задан параметр direction) выборка осуществляется в направлении от значения from_id в сторону уменьшения id строки справочника. Пример: page[from_id]=10
direction	string	опционально	Направление выборки. Доступно два значения: reverse, forward. reverse - возвращает записи, ID которых меньше значения from_id, если параметр from_id передан. При отсутствии параметра from_id выборка осуществляется от наибольшого значения id строки справочника. forward - возвращает записи, ID которых больше значения from_id, если параметр from_id передан. При отсутствии параметра from_id выборка осуществляется от наименьшего значения id строки справочника. Пример: page[direction]=forward

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

https://<account>.okdesk.ru/api/v1/warehouses/100/remainders?
  api_token=3e9a214215f493c4&page[size]=2&page[from_id]=10&page[direction]=reverse

Пример URI

GET https://<account>.okdesk.ru/api/v1/warehouses/100/remainders?api_token=3e9a214215f493c4

Параметры URI

СкрытьПоказать

warehouse_id: integer (обязательное) Пример: 100
ID склада.
api_token: string (обязательное) Пример: 3e9a214215f493c4
Ключ авторизации.

Ответ 200

СкрытьПоказать

Заголовки

Content-Type: application/json

Тело

[
  {
    "id": 101,
    "code": "item_code2",
    "name": "Гвоздь",
    "active": true,
    "item_type": "product",
    "unit": "кг.",
    "vendor_code": "",
    "quantity": 1.5
  },
  {
    "id": 100,
    "code": "item_code1",
    "name": "Шуруп",
    "active": true,
    "item_type": "product",
    "unit": "кг.",
    "vendor_code": "",
    "quantity": 2.5
  }
]

Ответ 422

СкрытьПоказать

Заголовки

Content-Type: application/json

Тело

{
  "errors": {
    "page": {
      "size": [
        "должно быть меньше или равно 100"
      ],
      "direction": [
        "должен быть одним из: reverse, forward"
      ],
      "from_id": [
        "должно иметь тип integer"
      ]
    }
  }
}

Создание документа учета

POST`/api/v1/material_assets/documents{?api_token}`

Название	Тип	Обязательность	Описание
doc_type	string	обязательный	Тип документа. Допустимые значения: posting - оприходование, writing_off - списание, moving - перемещение
from_warehouse_id	integer	обязательный для документов с типом списание и перемещение	ID склада, с которого происходит списание или перемещение
to_warehouse_id	integer	обязательный для документов с типом оприходование и перемещение	ID склада, на который осуществляется приход или перемещение
external_doc	string	опционально	Внешний документ
accounted_at	string	опционально	Дата учета документа

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

Пример URI

POST https://<account>.okdesk.ru/api/v1/material_assets/documents?api_token=3e9a214215f493c4

Параметры URI

СкрытьПоказать

api_token: string (обязательное) Пример: 3e9a214215f493c4
Ключ авторизации.

Запрос

СкрытьПоказать

Заголовки

Content-Type: application/json

Тело

{
  "document": {
    "doc_type": "writing_off",
    "from_warehouse_id": 11,
    "external_doc": "1475823",
    "accounted_at": "12-01-2023"
  }
}

Ответ 200

СкрытьПоказать

Заголовки

Content-Type: application/json

Тело

{
  "id": 22,
  "accounted_at": "2023-01-12",
  "created_at": "2023-06-23T17:53:00.242+03:00",
  "external_doc": "1475823",
  "number": "000022",
  "doc_type": {
    "code": "writing_off",
    "name": "Списание"
  },
  "status": {
    "code": "drafted",
    "name": "Черновик"
  },
  "author_id": 1,
  "from_warehouse": {
    "id": 11,
    "name": "Склад №11"
  },
  "to_warehouse": null
}

Получение списка документов

GET`/api/v1/material_assets/documents{?api_token}`

Название	Тип	Обязательность	Описание
doc_types	array of string	опционально	Массив типов документов. Допустимые значения: posting - оприходование, writing_off - списание, moving - перемещение. Пример: doc_types[]=posting&doc_types[]=moving
statuses	array of string	опционально	Массив статусов документов. Допустимые значения: drafted - Черновик, waiting_for_approve - Согласование, waiting_for_receive - Ожидает приемки, accounted - Учтен. Пример: statuses[]=drafted&statuses[]=accounted
from_warehouses	array of integer	опционально	Массив из ID складов, с которых произведены списание или перемещение (Со склада). Пример: from_warehouses[]=1&from_warehouses[]=2
to_warehouses	array of integer	опционально	Массив из ID складов, на которые осуществлены приход или перемещение (На склад). Пример: to_warehouses[]=1&to_warehouses[]=2
external_doc	string	опционально	Внешний документ. Пример: external_doc=Внешний
page	associative array	опционально	Ассоциативный массив параметров постраничного вывода списка документов (подробное описание представлено в таблице ниже).

Название	Тип значения	Обязательность	Описание
size	integer	опционально	Число возвращаемых записей. Не может превышать 100. Пример: page[size]=30
from_id	integer	опционально	ID документа, с которого начинается выборка записей. По умолчанию (если не задан параметр direction) выборка осуществляется в направлении от значения from_id в сторону уменьшения id документа. Пример: page[from_id]=10
direction	string	опционально	Направление выборки. Доступно два значения: reverse, forward. reverse - возвращает записи, ID которых меньше значения from_id, если параметр from_id передан. При отсутствии параметра from_id выборка осуществляется от наибольшого значения id документа. forward - возвращает записи, ID которых больше значения from_id, если параметр from_id передан. При отсутствии параметра from_id выборка осуществляется от наименьшего значения id документа. Пример: page[direction]=forward

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

https://<account>.okdesk.ru/api/v1/material_assets/documents?
  api_token=3e9a214215f493c4&page[size]=3&page[from_id]=10&page[direction]=reverse

Пример URI

GET https://<account>.okdesk.ru/api/v1/material_assets/documents?api_token=3e9a214215f493c4

Параметры URI

СкрытьПоказать

api_token: string (обязательное) Пример: 3e9a214215f493c4
Ключ авторизации.

Ответ 200

СкрытьПоказать

Заголовки

Content-Type: application/json

Тело

[
  {
    "id": 22,
    "accounted_at": "2023-01-12",
    "created_at": "2023-06-23T17:53:00.242+03:00",
    "external_doc": "1475823",
    "number": "000022",
    "doc_type": {
      "code": "writing_off",
      "name": "Списание"
    },
    "status": {
      "code": "drafted",
      "name": "Черновик"
    },
    "author_id": 1,
    "from_warehouse": {
      "id": 11,
      "name": "Склад №11"
    },
    "to_warehouse": null
  }
]

Смена статуса документа учета

PATCH`/api/v1/material_assets/documents/{document_id}/statuses{?api_token}`

Название	Тип	Обязательность	Описание
code	string	обязательный	Код статуса документа. Допустимые значения: drafted - Черновик, waiting_for_approve - Согласование, waiting_for_receive - Ожидает приемки, accounted - Учтен.

Смена статуса документа учета будет выполнена только в том случае, если связанный с ключом сотрудник имеет доступ к разделу Склады и просмотру карточки документа учета. Для перевода из статуса “Черновик” в статус “Согласование” проверяется право “Создание и редактирование документа учета ТМЦ”. Для перевода из статуса “Согласование” в “Учтен”, “Ожидает приемки” или “Черновик” проверяется право “Смена статуса документа учета ТМЦ”. Для перевода из статуса “Учтен” в “Черновик” проверяется право “Отмена учтенных документов”. Для ключей, связанных с контактными лицами, данный метод недоступен.

Пример URI

PATCH https://<account>.okdesk.ru/api/v1/material_assets/documents/12/statuses?api_token=3e9a214215f493c4

Параметры URI

СкрытьПоказать

document_id: integer (обязательное) Пример: 12
ID документа.
api_token: string (обязательное) Пример: 3e9a214215f493c4
Ключ авторизации.

Запрос

СкрытьПоказать

Заголовки

Content-Type: application/json

Тело

{
  "code": "waiting_for_approve"
}

Ответ 200

СкрытьПоказать

Заголовки

Content-Type: application/json

Тело

{
  "id": 22,
  "accounted_at": "2023-01-12",
  "created_at": "2023-06-23T17:53:00.242+03:00",
  "external_doc": "1475823",
  "number": "000022",
  "doc_type": {
    "code": "writing_off",
    "name": "Списание"
  },
  "status": {
    "code": "waiting_for_approve",
    "name": "Согласование"
  },
  "author_id": 1,
  "from_warehouse": {
    "id": 11,
    "name": "Склад №11"
  },
  "to_warehouse": null
}

Получение позиций ТМЦ в документе учета

GET`/api/v1/material_assets/documents/{document_id}/items{?api_token}`

Название	Тип	Обязательность	Описание
page	associative array	опционально	Ассоциативный массив параметров постраничного вывода позиций ТМЦ (подробное описание представлено в таблице ниже).

Название	Тип значения	Обязательность	Описание
size	integer	опционально	Число возвращаемых записей. Не может превышать 100. Пример: page[size]=30
from_id	integer	опционально	ID позиции ТМЦ, с которой начинается выборка записей. По умолчанию (если не задан параметр direction) выборка осуществляется в направлении от значения from_id в сторону уменьшения id позиции ТМЦ. Пример: page[from_id]=10
direction	string	опционально	Направление выборки. Доступно два значения: reverse, forward. reverse - возвращает записи, ID которых меньше значения from_id, если параметр from_id передан. При отсутствии параметра from_id выборка осуществляется от наибольшого значения id позиции ТМЦ. forward - возвращает записи, ID которых больше значения from_id, если параметр from_id передан. При отсутствии параметра from_id выборка осуществляется от наименьшего значения id позиции ТЦМ. Пример: page[direction]=forward

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

https://<account>.okdesk.ru/api/v1/material_assets/documents/5/items?
  api_token=3e9a214215f493c4&page[size]=3&page[from_id]=10&page[direction]=reverse

Пример URI

GET https://<account>.okdesk.ru/api/v1/material_assets/documents/12/items?api_token=3e9a214215f493c4

Параметры URI

СкрытьПоказать

document_id: integer (обязательное) Пример: 12
ID документа.
api_token: string (обязательное) Пример: 3e9a214215f493c4
Ключ авторизации.

Ответ 200

СкрытьПоказать

Заголовки

Content-Type: application/json

Тело

[
  {
    "id": 4,
    "nomenclature_item_id": 5,
    "quantity": "2.0",
    "code": "item_code2",
    "name": "Гвоздь",
    "vendor_code": "",
    "item_type": "product",
    "unit": "кг."
  },
  {
    "id": 5,
    "nomenclature_item_id": 6,
    "quantity": "1.5",
    "code": "item_code1",
    "name": "Шуруп",
    "vendor_code": "",
    "item_type": "product",
    "unit": "кг."
  }
]

Добавление позиции ТМЦ в документе учета

POST`/api/v1/material_assets/documents/{document_id}/items{?api_token}`

Название	Тип	Обязательность	Описание
nomenclature_item_id	integer	обязательный	ID номенклатуры
quantity	float	обязательный	Количество

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

Пример URI

POST https://<account>.okdesk.ru/api/v1/material_assets/documents/12/items?api_token=3e9a214215f493c4

Параметры URI

СкрытьПоказать

document_id: integer (обязательное) Пример: 12
ID документа.
api_token: string (обязательное) Пример: 3e9a214215f493c4
Ключ авторизации.

Запрос

СкрытьПоказать

Заголовки

Content-Type: application/json

Тело

{
  "item": {
    "nomenclature_item_id": 6,
    "quantity": 3.2
  }
}

Ответ 200

СкрытьПоказать

Заголовки

Content-Type: application/json

Тело

{
  "id": 6,
  "nomenclature_item_id": 6,
  "quantity": "3.2",
  "code": "item_code1",
  "name": "Шуруп",
  "vendor_code": "",
  "item_type": "product",
  "unit": "кг."
}

Удаление позиции ТМЦ в документе учета

DELETE`/api/v1/material_assets/documents/{document_id}/items/{item_id}{?api_token}`

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

Пример URI

DELETE https://<account>.okdesk.ru/api/v1/material_assets/documents/12/items/6?api_token=3e9a214215f493c4

Параметры URI

СкрытьПоказать

document_id: integer (обязательное) Пример: 12
ID документа.
item_id: integer (обязательное) Пример: 6
ID позиции ТМЦ
api_token: string (обязательное) Пример: 3e9a214215f493c4
Ключ авторизации.

Ответ 200

СкрытьПоказать

Заголовки

Content-Type: application/json

Тело

{
  "result": "Успешно удалено"
}

Интеграция с телефонией ¶

Передача информации о входящем звонке

POST`/api/v1/telephony/messages{?api_token}`

Название	Тип	Обязательность	Описание
telephony_numbers	array of integer	обязательный	Внутренние номера сотрудников, на которые распределился звонок.
search_numbers_count	integer	обязательный	Количество последних цифр входящего номера для поиска соответствия.
phone	string	обязательный	Номер звонящего абонента.

Передача информации пользователям доступна без ограничений только для ключей, связанных с пользователями-администраторами (роль “Администратор”).

Пример URI

POST https://<account>.okdesk.ru/api/v1/telephony/messages?api_token=3e9a214215f493c4

Параметры URI

СкрытьПоказать

api_token: string (обязательное) Пример: 3e9a214215f493c4
Ключ авторизации.

Запрос

СкрытьПоказать

Заголовки

Content-Type: application/json

Тело

{
  "telephony_numbers": [
    123,
    456
  ],
  "search_numbers_count": 7,
  "phone": "1232123"
}

Ответ 200

СкрытьПоказать

Тело

{}

Создание записи о телефонном разговоре

POST`/api/v1/phone_calls{?api_token}`

Название	Тип	Обязательность	Описание
call_id	string	обязательный	Идентификатор звонка во внешней системе
started_at	string	обязательный	Дата/время начала звонка
finished_at	string	обязательный	Дата/время завершения звонка
duration	integer	обязательный	Продолжительность разговора (в секундах)
direction	integer	обязательный	Направление вызова (1 — исходящий, 0 — входящий)
receiver_phone	string	обязательный	Номер принимающего абонента
source_phone	string	обязательный	Номер звонящего абонента
search_numbers_count	integer	обязательный	Количество последних цифр номера внешнего абонента для поиска соответствия в базе клиентов
file_url	string	опционально	Ссылка на скачивание файла с записью телефонного разговора
issue_id	integer	опционально	ID заявки звонка

Метод доступен только для ключей, связанных с пользовательскими ролями “Администратор”.

Пример URI

POST https://<account>.okdesk.ru/api/v1/phone_calls?api_token=3e9a214215f493c4

Параметры URI

СкрытьПоказать

api_token: string (обязательное) Пример: 3e9a214215f493c4
Ключ авторизации.

Запрос с корректными параметрами

СкрытьПоказать

Заголовки

Content-Type: application/json

Тело

{
  "phone_call": {
    "call_id": "test-123",
    "started_at": "2019-02-24 09:16",
    "finished_at": "2019-02-24 09:17",
    "duration": 60,
    "direction": 1,
    "source_phone": "811111111111",
    "receiver_phone": "82222222222",
    "search_numbers_count": 10,
    "file_url": "https://test.com/file.mp3",
    "issue_id": 1
  }
}

Ответ 201

Запрос с некорректными параметрами

СкрытьПоказать

Заголовки

Content-Type: application/json

Тело

{
  "phone_call": {
    "started_at": "2019-02-24 09:17",
    "finished_at": "2019-02-24 09:16",
    "duration": 60,
    "direction": 3,
    "source_phone": "811111111111",
    "receiver_phone": "82222222222",
    "search_numbers_count": -1,
    "file_url": "https://test.com/file.mp3",
    "issue_id": 1
  }
}

Ответ 422

СкрытьПоказать

Заголовки

Content-Type: application/json

Тело

{
    "errors": {
        "search_numbers_count": [
            "должно быть больше 0"
        ],
        "call_id": [
            "отсутствует"
        ],
        "direction": [
            "должен быть одним из: 0, 1"
        ],
        "compare_dates": [
            "Дата завершения телефонного разговора не должна быть раньше даты начала"
        ],
    }
}

Прайс-лист ¶

Метод получения списка прайс-листов

GET`/api/v1/price_lists{?api_token}`

Название	Тип	Обязательность	Описание
page	associative array	опционально	Ассоциативный массив параметров постраничного вывода прайс-листа (подробное описание представлено в таблице ниже).

Название	Тип значения	Обязательность	Описание
size	integer	опционально	Число возвращаемых записей. Не может превышать 100. Пример: page[size]=30
from_id	integer	опционально	ID строки справочника, с которой начинается выборка записей. По умолчанию (если не задан параметр direction) выборка осуществляется в направлении от значения from_id в сторону уменьшения id строки справочника. Пример: page[from_id]=10
direction	string	опционально	Направление выборки. Доступно два значения: reverse, forward. reverse - возвращает записи, ID которых меньше значения from_id, если параметр from_id передан. При отсутствии параметра from_id выборка осуществляется от наибольшого значения id строки справочника. forward - возвращает записи, ID которых больше значения from_id, если параметр from_id передан. При отсутствии параметра from_id выборка осуществляется от наименьшего значения id строки справочника. Пример: page[direction]=forward

Метод доступен только для ключей, связанных с пользовательской ролью “Администратор”.

Метод возвращает не более 100 записей. В случае, когда параметры постраничного вывода не переданы, будет возвращен список последних 100 созданных записей прайс-листа.

https://<account>.okdesk.ru/api/v1/price_lists?
  api_token=3e9a214215f493c4&page[size]=3&page[from_id]=10&page[direction]=reverse

Пример URI

GET https://<account>.okdesk.ru/api/v1/price_lists?api_token=3e9a214215f493c4

Параметры URI

СкрытьПоказать

api_token: string (обязательное) Пример: 3e9a214215f493c4
Ключ авторизации.

Ответ 200

СкрытьПоказать

Заголовки

Content-Type: application/json

Тело

[
  {
    "id": 101,
    "name": "Прайс-лист на обслуживание",
    "allow_without_category": false,
    "allow_without_company": false,
    "inverted_companies": false,
    "company_category_codes": [
      "partner",
      "client",
      "vipclient"
    ],
    "company_ids": [
      441,
      41
    ]
  },
  {
    "id": 100,
    "name": "Прайс-лист на услуги и продукты для всех клиентов",
    "allow_without_category": false,
    "allow_without_company": false,
    "inverted_companies": false,
    "company_category_codes": [],
    "company_ids": []
  }
]

Ответ 422

СкрытьПоказать

Заголовки

Content-Type: application/json

Тело

{
  "errors": {
    "page": {
      "size": [
        "должно быть меньше или равно 100"
      ],
      "direction": [
        "должен быть одним из: reverse, forward"
      ],
      "from_id": [
        "должно иметь тип integer"
      ]
    }
  }
}

Получение прайс-листа

GET`/api/v1/nomenclature/price_lists/{price_list_id}/services{?api_token}`

Название	Тип	Обязательность	Описание
search_string	string	опционально	Искомая подстрока в названии элемента номенклатуры, артикуле или описании элемента номенклатуры.
item_types	array of string	опционально	Массив строк для фильтрации по типу элемента номенклатуры. Допустимые значения: service, work, material, product.
group_id	string	опционально	ID группы в которую входит элемент номенклатуры (для отображения позиций номенклатуры без группы необходимо передавать в параметре значение “0”).
page	associative array	опционально	Ассоциативный массив параметров постраничного вывода прайс-листа (подробное описание представлено в таблице ниже).

Название	Тип значения	Обязательность	Описание
size	integer	опционально	Число возвращаемых записей. Не может превышать 100. Пример: page[size]=30
from_id	integer	опционально	ID строки справочника, с которой начинается выборка записей. По умолчанию (если не задан параметр direction) выборка осуществляется в направлении от значения from_id в сторону уменьшения id строки справочника. Пример: page[from_id]=10
direction	string	опционально	Направление выборки. Доступно два значения: reverse, forward. reverse - возвращает записи, ID которых меньше значения from_id, если параметр from_id передан. При отсутствии параметра from_id выборка осуществляется от наибольшого значения id строки справочника. forward - возвращает записи, ID которых больше значения from_id, если параметр from_id передан. При отсутствии параметра from_id выборка осуществляется от наименьшего значения id строки справочника. Пример: page[direction]=forward

Метод доступен только для ключей, связанных с сотрудниками, имеющими доступ к действию “Доступ к управлению прайс-листами”.

Метод возвращает не более 100 записей. В случае, когда параметры постраничного вывода не переданы, будет возвращен список последних 100 созданных записей прайс-листа.
Символ + в поисковой строке можно использовать только в закодированном варианте %2B, иначе он будет воспринят как пробел

https://<account>.okdesk.ru/api/v1/nomenclature/price_lists/153/services?
  api_token=3e9a214215f493c4&item_types[]=service&item_types[]=work&page[size]=3&page[from_id]=10&page[direction]=reverse

Пример URI

GET https://<account>.okdesk.ru/api/v1/nomenclature/price_lists/154/services?api_token=3e9a214215f493c4

Параметры URI

СкрытьПоказать

api_token: string (обязательное) Пример: 3e9a214215f493c4
Ключ авторизации.
price_list_id: integer (обязательное) Пример: 154
ID прайс-листа.

Ответ 200

СкрытьПоказать

Заголовки

Content-Type: application/json

Тело

[
  {
    "id": 1,
    "nomenclature_item_id": 1,
    "code": "timerateservice",
    "name": "Услуги с повременной оплатой",
    "type": "service",
    "group": {
      "id": 1,
      "code": "group_code",
      "name": "Услуги"
    },
    "unit": "человеко-час",
    "vendor_code": "",
    "price": 1000,
    "nds": 0,
    "visible": true,
    "description": "Различные биллингуемые услуги с почасовой оплатой"
  }
]

Ответ 422

СкрытьПоказать

Заголовки

Content-Type: application/json

Тело

{
  "errors": {
    "item_types": {
      "0": [
        "должен быть одним из: service, product, material, work"
      ]
    },
    "page": {
      "size": [
        "должно быть меньше или равно 100"
      ],
      "direction": [
        "должен быть одним из: reverse, forward"
      ],
      "from_id": [
        "должно иметь тип integer"
      ]
    }
  }
}

Добавление строки прайс-листа

POST`/api/v1/nomenclature/price_lists/{price_list_id}/services{?api_token}`

Название	Тип	Обязательность	Описание
nomenclature_item_id	integer	обязательный	ID элемента справочника номенклатуры
price	number	обязательный	Цена
nds	integer	обязательный	Ставка НДС, %

Пример URI

POST https://<account>.okdesk.ru/api/v1/nomenclature/price_lists/154/services?api_token=3e9a214215f493c4

Параметры URI

СкрытьПоказать

api_token: string (обязательное) Пример: 3e9a214215f493c4
Ключ авторизации.
price_list_id: integer (обязательное) Пример: 154
ID прайс-листа.

Запрос с корректными параметрами

СкрытьПоказать

Заголовки

Content-Type: application/json

Тело

{
  "service": {
    "nomenclature_item_id": 2,
    "price": 1000,
    "nds": 0
  }
}

Ответ 200

СкрытьПоказать

Заголовки

Content-Type: application/json

Тело

{
  "id": 1,
  "nomenclature_item_id": 2,
  "code": "timerateservice",
  "name": "Услуги с повременной оплатой",
  "type": "service",
  "group": {
    "id": 1,
    "code": "group_code",
    "name": "Услуги"
  },
  "unit": "человеко-час",
  "vendor_code": "",
  "price": 1000,
  "nds": 0,
  "visible": true,
  "description": "Различные биллингуемые услуги с почасовой оплатой"
}

Запрос с некорректными параметрами

СкрытьПоказать

Заголовки

Content-Type: application/json

Тело

{
  "service": {
    "price": "wrong"
  }
}

Ответ 422

СкрытьПоказать

Заголовки

Content-Type: application/json

Тело

{
  "errors": {
    "nomenclature_item_id": [
      "отсутствует"
    ],
    "price": [
      "должно иметь тип float или должно иметь тип integer"
    ]
  }
}

Редактирование строки прайс-листа

PATCH`/api/v1/nomenclature/price_lists/{price_list_id}/services/{id}{?api_token}`

Название	Тип	Обязательность	Описание
price	number	опционально	Цена
nds	integer	опционально	Ставка НДС, %
visible	boolean	опционально	Статус активности. Принимает значение true или false

Пример URI

PATCH https://<account>.okdesk.ru/api/v1/nomenclature/price_lists/154/services/12?api_token=3e9a214215f493c4

Параметры URI

СкрытьПоказать

api_token: string (обязательное) Пример: 3e9a214215f493c4
Ключ авторизации.
price_list_id: integer (обязательное) Пример: 154
ID прайс-листа.
id: integer (обязательное) Пример: 12
ID строки прайс-листа.

Запрос с корректными параметрами

СкрытьПоказать

Заголовки

Content-Type: application/json

Тело

{
  "service": {
    "price": 2000,
    "nds": 5,
    "visible": false
  }
}

Ответ 200

СкрытьПоказать

Заголовки

Content-Type: application/json

Тело

{
  "id": 1,
  "nomenclature_item_id": 2,
  "code": "timerateservice",
  "name": "Услуги с повременной оплатой",
  "type": "service",
  "group": {
    "id": 1,
    "code": "group_code",
    "name": "Услуги"
  },
  "unit": "человеко-час",
  "vendor_code": "",
  "price": 2000,
  "nds": 5,
  "visible": false,
  "description": "Различные биллингуемые услуги с почасовой оплатой"
}

Запрос с некорректными параметрами

СкрытьПоказать

Заголовки

Content-Type: application/json

Тело

{
  "service": {
    "price": "100",
    "nds": 200,
    "visible": 1
  }
}

Ответ 422

СкрытьПоказать

Заголовки

Content-Type: application/json

Тело

{
  "errors": {
    "price": [
      "должно иметь тип float или должно иметь тип integer"
    ],
    "nds": [
      "должно быть меньше или равно 100"
    ],
    "visible": [
      "должно иметь тип boolean"
    ]
  }
}

Метод получения доступного набора строк прайс-листа для заявки и пользователя

GET`/api/v1/issues/{issue_id}/available_services{?api_token}`

Название	Тип	Обязательность	Описание
search_string	string	опционально	Подстрока для фильтрации по названию элемента номенклатуры или артикулу элемента номенклатуры.
item_types	array of string	опционально	Массив строк для фильтрации по типу элемента номенклатуры. Допустимые значения: service, work, material, product.
page	associative array	опционально	Ассоциативный массив параметров постраничного вывода прайс-листа (подробное описание представлено в таблице ниже).

Название	Тип значения	Обязательность	Описание
size	integer	опционально	Число возвращаемых записей. Не может превышать 100. Пример: page[size]=30
from_id	integer	опционально	ID строки справочника, с которой начинается выборка записей. По умолчанию (если не задан параметр direction) выборка осуществляется в направлении от значения from_id в сторону уменьшения id строки справочника. Пример: page[from_id]=10
direction	string	опционально	Направление выборки. Доступно два значения: reverse, forward. reverse - возвращает записи, ID которых меньше значения from_id, если параметр from_id передан. При отсутствии параметра from_id выборка осуществляется от наибольшого значения id строки справочника. forward - возвращает записи, ID которых больше значения from_id, если параметр from_id передан. При отсутствии параметра from_id выборка осуществляется от наименьшего значения id строки справочника. Пример: page[direction]=forward

Метод доступен только для ключей, связанных с сотрудниками, имеющими доступ к действиям “Просмотр карточки заявки” и “Добавление строк в спецификацию заявок”.

https://<account>.okdesk.ru/api/v1/issues/1/available_services?
  api_token=3e9a214215f493c4&item_types[]=work&page[size]=3&page[from_id]=10&page[direction]=reverse&search_string=first

Пример URI

GET https://<account>.okdesk.ru/api/v1/issues/763/available_services?api_token=3e9a214215f493c4

Параметры URI

СкрытьПоказать

api_token: string (обязательное) Пример: 3e9a214215f493c4
Ключ авторизации.
issue_id: integer (обязательное) Пример: 763
ID заявки.

Ответ 200

СкрытьПоказать

Заголовки

Content-Type: application/json

Тело

[
  {
    "price_list_id": 3,
    "price_list_name": "Прайс-лист на обслуживание",
    "id": 1,
    "nomenclature_item_id": 1,
    "code": "timerateservice",
    "name": "Услуги с повременной оплатой",
    "item_type": "service",
    "unit": "человеко-час",
    "price": 1000,
    "nds": 0,
    "vendor_code": "",
    "description": "Различные биллингуемые услуги с почасовой оплатой",
    "group": {
      "id": 1,
      "code": "group_code",
      "name": "Услуги"
    }
  }
]

Ответ 422

СкрытьПоказать

Заголовки

Content-Type: application/json

Тело

{
  "errors": {
    "page": {
      "size": [
        "должно быть меньше или равно 100"
      ],
      "direction": [
        "должен быть одним из: reverse, forward"
      ],
      "from_id": [
        "должно иметь тип integer"
      ]
    }
  }
}

Номенклатура ¶

Получение списка групп номенклатуры

GET`/api/v1/nomenclature/groups{?api_token,search_string,code}`

Название	Тип	Обязательность	Описание
search_string	string	опционально	Искомая подстрока в названии группы номенклатуры
code	string	опционально	Строка фильтрации по коду группы номенклатуры
page	associative array	опционально	Ассоциативный массив параметров постраничного вывода списка групп (подробное описание представлено в таблице ниже).

Название	Тип значения	Обязательность	Описание
size	integer	опционально	Число возвращаемых записей. Не может превышать 100. Пример: page[size]=30
from_id	integer	опционально	ID строки справочника, с которой начинается выборка записей. По умолчанию (если не задан параметр direction) выборка осуществляется в направлении от значения from_id в сторону уменьшения id строки справочника. Пример: page[from_id]=10
direction	string	опционально	Направление выборки. Доступно два значения: reverse, forward. reverse - возвращает записи, ID которых меньше значения from_id, если параметр from_id передан. При отсутствии параметра from_id выборка осуществляется от наибольшого значения id строки справочника. forward - возвращает записи, ID которых больше значения from_id, если параметр from_id передан. При отсутствии параметра from_id выборка осуществляется от наименьшего значения id строки справочника. Пример: page[direction]=forward

Метод доступен только для ключей, связанных с сотрудниками, которым доступно право “Доступ к управлению прайс-листами”.

Метод возвращает не более 100 записей. В случае, когда параметры постраничного вывода не переданы, будет возвращен список последних 100 созданных групп.
Символ + в поисковой строке можно использовать только в закодированном варианте %2B, иначе он будет воспринят как пробел

https://<account>.okdesk.ru/api/v1/nomenclature/groups?
  api_token=3e9a214215f493c4&page[size]=3&page[from_id]=10&page[direction]=reverse

Пример URI

GET https://<account>.okdesk.ru/api/v1/nomenclature/groups?api_token=3e9a214215f493c4&search_string=группа&code=group1

Параметры URI

СкрытьПоказать

api_token: string (обязательное) Пример: 3e9a214215f493c4
Ключ авторизации.
search_string: string (необязательное) Пример: группа
Искомая подстрока.
code: string (необязательное) Пример: group1
Код группы.

Ответ 200

СкрытьПоказать

Заголовки

Content-Type: application/json

Тело

[
  {
    "id": 101,
    "code": "group1",
    "name": "Дочерняя группа",
    "active": true,
    "group": {
      "id": 100,
      "code": "group2",
      "name": "Родительская группа"
    }
  }
]

Ответ 422

СкрытьПоказать

Заголовки

Content-Type: application/json

Тело

{
  "errors": {
    "page": {
      "size": [
        "должно быть меньше или равно 100"
      ],
      "direction": [
        "должен быть одним из: reverse, forward"
      ],
      "from_id": [
        "должно иметь тип integer"
      ]
    }
  }
}

Добавление группы номенклатуры

POST`/api/v1/nomenclature/groups{?api_token}`

Название	Тип	Обязательность	Описание
code	string	обязательный	Код группы
name	string	обязательный	Название группы
parent_id	integer	опционально	ID родительской группы

Пример URI

POST https://<account>.okdesk.ru/api/v1/nomenclature/groups?api_token=3e9a214215f493c4

Параметры URI

СкрытьПоказать

api_token: string (обязательное) Пример: 3e9a214215f493c4
Ключ авторизации.

Запрос с корректными параметрами

СкрытьПоказать

Заголовки

Content-Type: application/json

Тело

{
  "nomenclature_group": {
    "code": "group_code",
    "name": "Услуги с повременной оплатой",
    "parent_id": 99
  }
}

Ответ 200

СкрытьПоказать

Заголовки

Content-Type: application/json

Тело

{
  "id": 100,
  "code": "group_code",
  "name": "Услуги с повременной оплатой",
  "active": true,
  "group": {
    "id": 99,
    "code": "parent_group_code",
    "name": "Родительская группа"
  }
}

Запрос с некорректными параметрами

СкрытьПоказать

Заголовки

Content-Type: application/json

Тело

{
  "nomenclature_group": {
    "code": true,
    "parent_id": "incorrect_id"
  }
}

Ответ 422

СкрытьПоказать

Заголовки

Content-Type: application/json

Тело

{
  "errors": {
    "code": [
      "должно иметь тип string"
    ],
    "name": [
      "отсутствует"
    ],
    "parent_id": [
      "должно иметь тип integer"
    ]
  }
}

Получение группы номенклатуры по ID

GET`/api/v1/nomenclature/groups/{id}{?api_token}`

Пример URI

GET https://<account>.okdesk.ru/api/v1/nomenclature/groups/100?api_token=3e9a214215f493c4

Параметры URI

СкрытьПоказать

api_token: string (обязательное) Пример: 3e9a214215f493c4
Ключ авторизации.
id: integer (обязательное) Пример: 100
ID группы.

Ответ 200

СкрытьПоказать

Заголовки

Content-Type: application/json

Тело

{
  "id": 100,
  "code": "group2",
  "name": "Родительская группа",
  "active": true,
  "group": null
}

Редактирования группы номенклатуры

PATCH`/api/v1/nomenclature/groups/{id}{?api_token}`

Название	Тип	Обязательность	Описание
name	string	опционально	Наименование группы
parent_id	integer	опционально	ID родительской группы
active	boolean	опционально	Статус активности. Принимает значение true или false

Пример URI

PATCH https://<account>.okdesk.ru/api/v1/nomenclature/groups/100?api_token=3e9a214215f493c4

Параметры URI

СкрытьПоказать

api_token: string (обязательное) Пример: 3e9a214215f493c4
Ключ авторизации.
id: integer (обязательное) Пример: 100
ID группы.

Запрос с корректными параметрами

СкрытьПоказать

Заголовки

Content-Type: application/json

Тело

{
  "nomenclature_group": {
    "name": "Услуги с повременной оплатой",
    "parent_id": 99,
    "active": false
  }
}

Ответ 200

СкрытьПоказать

Заголовки

Content-Type: application/json

Тело

{
  "id": 100,
  "code": "group_code",
  "name": "Услуги с повременной оплатой",
  "active": false,
  "group": {
    "id": 99,
    "code": "parent_group_code",
    "name": "Родительская группа"
  }
}

Запрос с некорректными параметрами

СкрытьПоказать

Заголовки

Content-Type: application/json

Тело

{
  "nomenclature_group": {
    "active": "1"
  }
}

Ответ 422

СкрытьПоказать

Заголовки

Content-Type: application/json

Тело

{
  "errors": {
    "active": [
      "должно иметь тип boolean"
    ]
  }
}

Получение списка позиций номенклатуры

GET`/api/v1/nomenclature/items{?api_token}`

Название	Тип	Обязательность	Описание
search_string	string	опционально	Искомая подстрока в названии, артикуле или описании позиции номенклатуры
code	string	опционально	Строка фильтрации по коду позиции номенклатуры
item_types	array of string	опционально	Массив типов позиции номенклатуры. Допустимые значения: service, product, material, work. Пример: item_types[]=work&item_types[]=service
group_id	integer	опционально	ID группы для фильтрации по вхождению в группу (для отображения позиций номенклатуры без группы необходимо передавать в параметре значение “0”)
page	associative array	опционально	Ассоциативный массив параметров постраничного вывода списка групп (подробное описание представлено в таблице ниже).

Название	Тип значения	Обязательность	Описание
size	integer	опционально	Число возвращаемых записей. Не может превышать 100. Пример: page[size]=30
from_id	integer	опционально	ID строки справочника, с которой начинается выборка записей. По умолчанию (если не задан параметр direction) выборка осуществляется в направлении от значения from_id в сторону уменьшения id строки справочника. Пример: page[from_id]=10
direction	string	опционально	Направление выборки. Доступно два значения: reverse, forward. reverse - возвращает записи, ID которых меньше значения from_id, если параметр from_id передан. При отсутствии параметра from_id выборка осуществляется от наибольшого значения id строки справочника. forward - возвращает записи, ID которых больше значения from_id, если параметр from_id передан. При отсутствии параметра from_id выборка осуществляется от наименьшего значения id строки справочника. Пример: page[direction]=forward

Метод возвращает не более 100 записей. В случае, когда параметры постраничного вывода не переданы, будет возвращен список последних 100 созданных элементов номенклатуры.
Символ + в поисковой строке можно использовать только в закодированном варианте %2B, иначе он будет воспринят как пробел

https://<account>.okdesk.ru/api/v1/nomenclature/items?
  api_token=3e9a214215f493c4&page[size]=3&page[from_id]=10&page[direction]=reverse

Пример URI

GET https://<account>.okdesk.ru/api/v1/nomenclature/items?api_token=3e9a214215f493c4

Параметры URI

СкрытьПоказать

api_token: string (обязательное) Пример: 3e9a214215f493c4
Ключ авторизации.

Ответ 200

СкрытьПоказать

Заголовки

Content-Type: application/json

Тело

[
  {
    "id": 101,
    "code": "item_code2",
    "name": "Услуги с повременной оплатой",
    "active": true,
    "item_type": "service",
    "unit": "человеко-час",
    "vendor_code": "",
    "description": "",
    "group": {
      "id": 100,
      "code": "group2",
      "name": "Родительская группа"
    }
  },
  {
    "id": 100,
    "code": "item_code1",
    "name": "Доставка в сервис",
    "active": true,
    "item_type": "work",
    "unit": "выезд",
    "vendor_code": "",
    "description": "",
    "group": null
  }
]

Ответ 422

СкрытьПоказать

Заголовки

Content-Type: application/json

Тело

{
  "errors": {
    "page": {
      "size": [
        "должно быть меньше или равно 100"
      ],
      "direction": [
        "должен быть одним из: reverse, forward"
      ],
      "from_id": [
        "должно иметь тип integer"
      ]
    }
  }
}

Добавление позиции в справочник номенклатуры

POST`/api/v1/nomenclature/items{?api_token}`

Название	Тип	Обязательность	Описание
code	string	обязательный	Код позиции номенклатуры
name	string	обязательный	Название позиции номенклатуры
item_type	string	обязательный	Тип позиции номенклатуры. Допустимые значения: service, product, material, work
unit	string	обязательный	Единица измерения позиции номенклатуры
description	string	опционально	Описание позиции номенклатуры
group_id	integer	опционально	ID родительской группы
vendor_code	string	опционально	Артикул позиции номенклатуры

Пример URI

POST https://<account>.okdesk.ru/api/v1/nomenclature/items?api_token=3e9a214215f493c4

Параметры URI

СкрытьПоказать

api_token: string (обязательное) Пример: 3e9a214215f493c4
Ключ авторизации.

Запрос с корректными параметрами

СкрытьПоказать

Заголовки

Content-Type: application/json

Тело

{
  "nomenclature_item": {
    "code": "item_code1",
    "name": "Услуги с повременной оплатой",
    "item_type": "service",
    "unit": "человеко-час",
    "group_id": 99
  }
}

Ответ 200

СкрытьПоказать

Заголовки

Content-Type: application/json

Тело

{
  "id": 100,
  "code": "item_code1",
  "name": "Услуги с повременной оплатой",
  "active": true,
  "item_type": "service",
  "unit": "человеко-час",
  "vendor_code": null,
  "description": null,
  "group": {
    "id": 99,
    "code": "parent_group_code",
    "name": "Родительская группа"
  }
}

Запрос с некорректными параметрами

СкрытьПоказать

Заголовки

Content-Type: application/json

Тело

{
  "nomenclature_item": {
    "code": true,
    "item_type": "incorrect"
  }
}

Ответ 422

СкрытьПоказать

Заголовки

Content-Type: application/json

Тело

{
  "errors": {
    "code": [
      "должно иметь тип string"
    ],
    "name": [
      "отсутствует"
    ],
    "item_type": [
      "должен быть одним из: service, product, material, work"
    ],
    "unit": [
      "отсутствует"
    ]
  }
}

Получение позиции номенклатуры по ID

GET`/api/v1/nomenclature/items/{id}{?api_token}`

Пример URI

GET https://<account>.okdesk.ru/api/v1/nomenclature/items/101?api_token=3e9a214215f493c4

Параметры URI

СкрытьПоказать

api_token: string (обязательное) Пример: 3e9a214215f493c4
Ключ авторизации.
id: integer (обязательное) Пример: 101
ID позиции.

Ответ 200

СкрытьПоказать

Заголовки

Content-Type: application/json

Тело

{
  "id": 101,
  "code": "item_code2",
  "name": "Услуги с повременной оплатой",
  "active": true,
  "item_type": "service",
  "unit": "человеко-час",
  "vendor_code": "",
  "description": "",
  "group": {
    "id": 100,
    "code": "group2",
    "name": "Родительская группа"
  }
}

Редактирование позиции в справочнике номенклатуры

PATCH`/api/v1/nomenclature/items/{id}{?api_token}`

Название	Тип	Обязательность	Описание
name	string	опционально	Название позиции номенклатуры
item_type	string	опционально	Тип позиции номенклатуры. Допустимые значения: service, product, material, work
unit	string	опционально	Единица измерения позиции номенклатуры
description	string	опционально	Описание позиции номенклатуры
group_id	integer	опционально	ID родительской группы
vendor_code	string	опционально	Артикул позиции номенклатуры
active	boolean	опционально	Статус активности. Принимает значение true или false

Пример URI

PATCH https://<account>.okdesk.ru/api/v1/nomenclature/items/100?api_token=3e9a214215f493c4

Параметры URI

СкрытьПоказать

api_token: string (обязательное) Пример: 3e9a214215f493c4
Ключ авторизации.
id: integer (обязательное) Пример: 100
ID позиции номенклатуры.

Запрос с корректными параметрами

СкрытьПоказать

Заголовки

Content-Type: application/json

Тело

{
  "nomenclature_item": {
    "name": "Услуги с повременной оплатой",
    "group_id": 99,
    "active": false
  }
}

Ответ 200

СкрытьПоказать

Заголовки

Content-Type: application/json

Тело

{
  "id": 100,
  "code": "item_code1",
  "name": "Услуги с повременной оплатой",
  "active": false,
  "item_type": "service",
  "unit": "человеко-час",
  "vendor_code": null,
  "description": null,
  "group": {
    "id": 99,
    "code": "parent_group_code",
    "name": "Родительская группа"
  }
}

Запрос с некорректными параметрами

СкрытьПоказать

Заголовки

Content-Type: application/json

Тело

{
  "nomenclature_item": {
    "active": "1"
  }
}

Ответ 422

СкрытьПоказать

Заголовки

Content-Type: application/json

Тело

{
  "errors": {
    "active": [
      "должно иметь тип boolean"
    ]
  }
}

Справочники ¶

Получение списка типов заявок

GET`/api/v1/dictionaries/issues/types/{?api_token,parent_code}`

Для ключей, связанных с контактными лицами, не возвращаются типы заявок с признаком “внутренняя” и будет доступна только ограниченная информация, а именно:

ID элемента;
Название элемента;
Код элемента;
Тип элемента (type - тип заявки, group - группа);
Информация о наличии признака “Доступен для выбора клиентом” у типа заявки;
Информация о наличии признака “По умолчанию” у типа заявки;
Вложенные элементы;

Пример URI

GET https://<account>.okdesk.ru/api/v1/dictionaries/issues/types/?api_token=3e9a214215f493c4&parent_code=service

Параметры URI

СкрытьПоказать

api_token: string (обязательное) Пример: 3e9a214215f493c4
Ключ авторизации.
parent_code: string (необязательное) Пример: service
Код родительской группы.

Ответ 200

СкрытьПоказать

Заголовки

Content-Type: application/json

Тело

[
  {
    "id": 8,
    "name": "Service types",
    "code": "service",
    "type": "group",
    "children": [
      {
        "id": 2,
        "name": "Service",
        "code": "service",
        "default": true,
        "available_for_client": true,
        "inner": false,
        "type": "type"
      },
      {
        "id": 1,
        "name": "Incident",
        "code": "incident",
        "default": false,
        "available_for_client": false,
        "inner": false,
        "type": "type"
      }
    ]
  },
  {
    "id": 3,
    "name": "Inner",
    "code": "inner",
    "default": false,
    "available_for_client": false,
    "inner": true,
    "type": "type"
  }
]

Получение списка приоритетов заявок

GET`/api/v1/issues/priorities/{?api_token}`

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

Название элемента;
Код элемента;
Порядковый номер элемента;
Информация о наличии признака “По умолчанию” у приоритета заявки;
Цвет элемента;

Пример URI

GET https://<account>.okdesk.ru/api/v1/issues/priorities/?api_token=3e9a214215f493c4

Параметры URI

СкрытьПоказать

api_token: string (обязательное) Пример: 3e9a214215f493c4
Ключ авторизации.

Ответ 200

СкрытьПоказать

Заголовки

Content-Type: application/json

Тело

[
  {
    "name": "Низкий",
    "code": "low",
    "position": 1,
    "default": true,
    "color": "#8e9eb3",
    "without_client": true,
    "company_without_category": false,
    "contact_without_company": false,
    "available_for_client": true,
    "company_category_codes": [
      "client"
    ],
    "company_ids": [
      45
    ],
    "employee_role_ids": [
      1
    ]
  },
  {
    "name": "Обычный",
    "code": "normal",
    "position": 2,
    "default": false,
    "color": "#5cb85c",
    "without_client": true,
    "company_without_category": false,
    "contact_without_company": false,
    "available_for_client": true,
    "company_category_codes": [],
    "company_ids": [],
    "employee_role_ids": []
  },
  {
    "name": "Высокий",
    "code": "high",
    "position": 3,
    "default": false,
    "color": "#ea2e49",
    "without_client": true,
    "company_without_category": false,
    "contact_without_company": false,
    "available_for_client": true,
    "company_category_codes": [
      "client"
    ],
    "company_ids": [
      45
    ],
    "employee_role_ids": []
  }
]

Получение списка статусов заявок

GET`/api/v1/issues/statuses/{?api_token}`

Название	Тип	Обязательность	Описание
final	boolean	опционально	Признак финальности статуса. Принимает значение true или false

Для ключей, связанных с контактными лицами, не возвращаются статусы заявок с признаком “Не показывать статус клиенту”

Пример URI

GET https://<account>.okdesk.ru/api/v1/issues/statuses/?api_token=3e9a214215f493c4

Параметры URI

СкрытьПоказать

api_token: string (обязательное) Пример: 3e9a214215f493c4
Ключ авторизации.

Ответ 200

СкрытьПоказать

Заголовки

Content-Type: application/json

Тело

[
  {
    "code": "opened",
    "name": "Открыта",
    "color": "#ff8522",
    "final": false,
    "comment_required": false
  },
  {
    "code": "delayed",
    "name": "Отложена",
    "color": "#ffc926",
    "final": false,
    "comment_required": false
  },
  {
    "code": "completed",
    "name": "Решена",
    "color": "#5cb85c",
    "final": true,
    "comment_required": false
  },
  {
    "code": "closed",
    "name": "Закрыта",
    "color": "#8e9eb3",
    "final": true,
    "comment_required": false
  }
]

Схема дополнительных атрибутов заявок

GET`/api/v1/issues/parameters/list{?api_token}`

Название	Тип	Обязательность	Описание
issue_type_codes	array	опционально	Массив кодов типов заявок

Если передан массив кодов типов заявок, то возвращаются доп атрибуты, которые доступны только для переданных типов заявок. Если пользователь передал тип заявки, который от него скрыт (для контактных лиц типы с пометкой “Внутренняя”, для сотрудников типы, скрытые для всех его ролей в настройке права “Просмотр карточки заявки”), то переданный код игнорируется.

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

Пример URI

GET https://<account>.okdesk.ru/api/v1/issues/parameters/list?api_token=3e9a214215f493c4

Параметры URI

СкрытьПоказать

api_token: string (обязательное) Пример: 3e9a214215f493c4
Ключ авторизации.

Ответ 200

СкрытьПоказать

Заголовки

Content-Type: application/json

Тело

[
  {
    "code": "attr_string",
    "name": "Строка",
    "field_type": "ftstring",
    "required": false,
    "issue_type_codes": [
      "service",
      "inner",
      "incident"
    ]
  },
  {
    "code": "city",
    "name": "Город",
    "field_type": "ftselect",
    "required": false,
    "issue_type_codes": [
      "service"
    ],
    "field_type_values": [
      "Царицын",
      "Симбирск",
      "Петроград"
    ]
  }
]

Схема дополнительных атрибутов трудозатрат заявки

GET`/api/v1/time_entries/parameters{?api_token}`

Метод доступен только для ключей, связанных с сотрудниками.

Пример URI

GET https://<account>.okdesk.ru/api/v1/time_entries/parameters?api_token=3e9a214215f493c4

Параметры URI

СкрытьПоказать

api_token: string (обязательное) Пример: 3e9a214215f493c4
Ключ авторизации.

Ответ 200

СкрытьПоказать

Заголовки

Content-Type: application/json

Тело

[
  {
    "code": "attr_string",
    "name": "Строка",
    "field_type": "ftstring",
    "required": false,
    "visible_on_time_entry_form": true,
    "visible_on_time_entries_list": true
  },
  {
    "code": "attr_date",
    "name": "Дата",
    "field_type": "ftdate",
    "required": false,
    "visible_on_time_entry_form": true,
    "visible_on_time_entries_list": true
  },
  {
    "code": "attr_datetime",
    "name": "Дата/время",
    "field_type": "ftdatetime",
    "required": false,
    "visible_on_time_entry_form": true,
    "visible_on_time_entries_list": true
  },
  {
    "code": "attr_checkbox",
    "name": "Чекбокс",
    "field_type": "ftcheckbox",
    "required": false,
    "visible_on_time_entry_form": true,
    "visible_on_time_entries_list": true
  },
  {
    "code": "attr_select",
    "name": "Значение из списка",
    "field_type": "ftselect",
    "required": false,
    "visible_on_time_entry_form": true,
    "visible_on_time_entries_list": true,
    "field_type_values": [
      "value_1",
      "value_2"
    ]
  },
  {
    "code": "attr_multiselect",
    "name": "Набор значений из списка",
    "field_type": "ftmultiselect",
    "required": false,
    "visible_on_time_entry_form": true,
    "visible_on_time_entries_list": true,
    "field_type_values": [
      "value_1",
      "value_2"
    ]
  },
  {
    "code": "attr_text",
    "name": "Текст",
    "field_type": "fttext",
    "required": false,
    "visible_on_time_entry_form": true,
    "visible_on_time_entries_list": true
  }
]

Схема дополнительных атрибутов оборудования

GET`/api/v1/equipments/parameters{?api_token}`

Название	Тип	Обязательность	Описание
equipment_kind_codes	array	опционально	Массив кодов типов оборудования Пример: equipment_kind_codes[]=X

Если передан массив кодов типов оборудования, то возвращаются доп атрибуты, которые доступны только для переданных типов оборудования.

Метод доступен только для ключей, связанных с сотрудниками. Для сотрудника требуется наличие его роли в параметре “Доступен для сотрудников с ролью”.

Пример URI

GET https://<account>.okdesk.ru/api/v1/equipments/parameters?api_token=3e9a214215f493c4

Параметры URI

СкрытьПоказать

api_token: string (обязательное) Пример: 3e9a214215f493c4
Ключ авторизации.

Ответ 200

СкрытьПоказать

Заголовки

Content-Type: application/json

Тело

[
  {
    "code": "attr_string",
    "name": "Строка",
    "field_type": "ftstring",
    "required": false,
    "equipment_kind_codes": [
      "laptor"
    ]
  },
  {
    "code": "attr_date",
    "name": "Дата",
    "field_type": "ftdate",
    "required": false,
    "equipment_kind_codes": [
      "laptor"
    ]
  },
  {
    "code": "attr_datetime",
    "name": "Дата/время",
    "field_type": "ftdatetime",
    "required": false,
    "equipment_kind_codes": [
      "laptor"
    ]
  },
  {
    "code": "attr_checkbox",
    "name": "Чекбокс",
    "field_type": "ftcheckbox",
    "required": false,
    "equipment_kind_codes": [
      "laptor"
    ]
  },
  {
    "code": "attr_select",
    "name": "Значение из списка",
    "field_type": "ftselect",
    "required": false,
    "equipment_kind_codes": [
      "laptor"
    ],
    "field_type_values": [
      "value_1",
      "value_2"
    ]
  },
  {
    "code": "attr_multiselect",
    "name": "Набор значений из списка",
    "field_type": "ftmultiselect",
    "required": false,
    "equipment_kind_codes": [
      "laptor"
    ],
    "field_type_values": [
      "value_1",
      "value_2"
    ]
  },
  {
    "code": "attr_text",
    "name": "Текст",
    "field_type": "fttext",
    "required": false,
    "equipment_kind_codes": [
      "laptor"
    ]
  }
]

Получение списка типов оборудования

GET`/api/v1/equipments/kinds/{?api_token}`

Название	Тип	Обязательность	Описание
search_string	string	опционально	Искомая подстрока в названии или коде типа оборудования
page	associative array	опционально	Ассоциативный массив параметров постраничного вывода списка типов оборудования (подробное описание представлено в таблице ниже).

Название	Тип значения	Обязательность	Описание
size	integer	опционально	Число возвращаемых записей. Не может превышать 100. Пример: page[size]=30
from_id	integer	опционально	ID типа оборудования, с которого начинается выборка записей. По умолчанию (если не задан параметр direction) выборка осуществляется в направлении от значения from_id в сторону уменьшения id типа. Пример: page[from_id]=10
direction	string	опционально	Направление выборки. Доступно два значения: reverse, forward. reverse - возвращает записи, ID которых меньше значения from_id, если параметр from_id передан. При отсутствии параметра from_id выборка осуществляется от наибольшого значения id типа. forward - возвращает записи, ID которых больше значения from_id, если параметр from_id передан. При отсутствии параметра from_id выборка осуществляется от наименьшего значения id типа. Пример: page[direction]=forward

Метод доступен только для ключей, связанных с сотрудниками, которым доступно право “Доступ к просмотру и редактированию справочников типов, производителей и моделей оборудования”.

Метод возвращает не более 100 записей. В случае, когда параметры постраничного вывода не переданы, будет возвращен список последних 100 созданных типов оборудования.

https://<account>.okdesk.ru/api/v1/equipments/kinds/?
  api_token=3e9a214215f493c4&page[size]=3&page[from_id]=10&page[direction]=forward&search_string=special

Пример URI

GET https://<account>.okdesk.ru/api/v1/equipments/kinds/?api_token=3e9a214215f493c4

Параметры URI

СкрытьПоказать

api_token: string (обязательное) Пример: 3e9a214215f493c4
Ключ авторизации.

Ответ 200

СкрытьПоказать

Заголовки

Content-Type: application/json

Тело

[
  {
    "id": 5,
    "code": "005",
    "name": "somewhatspecialequipment",
    "description": "somewhat special equipment",
    "visible": true,
    "equipment_name_format": "{{{TYPE}}} {{{VENDOR}}} {{{MODEL}}} {{{SN}}} {{{INV}}}",
    "parameters": [
      {
        "name": "Some_parameter 3",
        "field_type": "ftcheckbox"
      }
    ]
  },
  {
    "id": 8,
    "code": "008",
    "name": "specialequipment",
    "description": "special equipment",
    "visible": true,
    "equipment_name_format": "{{{TYPE}}} {{{VENDOR}}} {{{MODEL}}} {{{SN}}} {{{INV}}}",
    "parameters": [
      {
        "name": "Some_parameter 2",
        "field_type": "ftcheckbox"
      }
    ]
  },
  {
    "id": 10,
    "code": "010",
    "name": "veryspecialequipment",
    "description": "very special equipment",
    "visible": true,
    "equipment_name_format": "{{{TYPE}}} {{{VENDOR}}} {{{MODEL}}} {{{SN}}} {{{INV}}}",
    "parameters": [
      {
        "name": "Some_parameter 1",
        "field_type": "ftcheckbox"
      },
      {
        "name": "Some_parameter 2",
        "field_type": "ftcheckbox"
      }
    ]
  }
]

Создание типа оборудования

POST`/api/v1/equipments/kinds/{?api_token}`

Название	Тип	Обязательность	Описание
name	string	обязательный	Название типа оборудования
code	string	обязательный	Код типа оборудования
description	string	необязательный	Описание типа оборудования
parameter_codes	array of string	необязательный	Массив из кодов связанных допополнительных атрибутов оборудования
equipment_name_format	string	необязательный	Шаблон названия оборудования

Пример URI

POST https://<account>.okdesk.ru/api/v1/equipments/kinds/?api_token=3e9a214215f493c4

Параметры URI

СкрытьПоказать

api_token: string (обязательное) Пример: 3e9a214215f493c4
Ключ авторизации.

Запрос

СкрытьПоказать

Заголовки

Content-Type: application/json

Тело

{
  "equipment_kind": {
    "code": "sample_code",
    "name": "sample_name",
    "description": "sample_text",
    "equipment_name_format": "{{{SN}}} {{{INV}}}",
    "parameter_codes": [
      "001",
      "002"
    ]
  }
}

Ответ 200

СкрытьПоказать

Заголовки

Content-Type: application/json

Тело

{
  "id": 57,
  "code": "sample_code",
  "name": "sample_name",
  "description": "sample_text",
  "visible": true,
  "equipment_name_format": "{{{SN}}} {{{INV}}}",
  "parameters": [
    {
      "name": "Parameter 1",
      "field_type": "ftstring"
    },
    {
      "name": "Parameter 2",
      "field_type": "ftstring"
    }
  ]
}

Редактирование типа оборудования

PATCH`/api/v1/equipments/kinds/{kind_id}{?api_token}`

Название	Тип	Обязательность	Описание
name	string	необязательный	Название типа оборудования
description	string	необязательный	Описание типа оборудования
parameter_codes	array of string	необязательный	Массив из кодов связанных допополнительных атрибутов оборудования
visible	boolean	необязательный	Признак включенности
equipment_name_format	string	необязательный	Шаблон названия оборудования

Пример URI

PATCH https://<account>.okdesk.ru/api/v1/equipments/kinds/57?api_token=3e9a214215f493c4

Параметры URI

СкрытьПоказать

api_token: string (обязательное) Пример: 3e9a214215f493c4
Ключ авторизации.
kind_id: integer (обязательное) Пример: 57
ID редактируемого типа оборудования

Запрос

СкрытьПоказать

Заголовки

Content-Type: application/json

Тело

{
  "equipment_kind": {
    "name": "changed_name",
    "description": "changed_text",
    "visible": false,
    "equipment_name_format": "{{{SN}}} {{{INV}}}",
    "parameter_codes": [
      "001",
      "003"
    ]
  }
}

Ответ 200

СкрытьПоказать

Заголовки

Content-Type: application/json

Тело

{
  "id": 57,
  "code": "code",
  "name": "changed_name",
  "description": "changed_text",
  "visible": false,
  "equipment_name_format": "{{{SN}}} {{{INV}}}",
  "parameters": [
    {
      "name": "Parameter 1",
      "field_type": "ftstring"
    },
    {
      "name": "Parameter 3",
      "field_type": "ftcheckbox"
    }
  ]
}

Получение списка производителей оборудования

GET`/api/v1/equipments/manufacturers/{?api_token}`

Название	Тип	Обязательность	Описание
search_string	string	опционально	Искомая подстрока в названии или коде производителя оборудования
page	associative array	опционально	Ассоциативный массив параметров постраничного вывода списка производителей оборудования (подробное описание представлено в таблице ниже).

Название	Тип значения	Обязательность	Описание
size	integer	опционально	Число возвращаемых записей. Не может превышать 100. Пример: page[size]=30
from_id	integer	опционально	ID производителя оборудования, с которого начинается выборка записей. По умолчанию (если не задан параметр direction) выборка осуществляется в направлении от значения from_id в сторону уменьшения id производителя. Пример: page[from_id]=10
direction	string	опционально	Направление выборки. Доступно два значения: reverse, forward. reverse - возвращает записи, ID которых меньше значения from_id, если параметр from_id передан. При отсутствии параметра from_id выборка осуществляется от наибольшого значения id производителя. forward - возвращает записи, ID которых больше значения from_id, если параметр from_id передан. При отсутствии параметра from_id выборка осуществляется от наименьшего значения id производителя. Пример: page[direction]=forward

Метод возвращает не более 100 записей. В случае, когда параметры постраничного вывода не переданы, будет возвращен список последних 100 созданных производителей оборудования.

https://<account>.okdesk.ru/api/v1/equipments/manufacturers/?
  api_token=3e9a214215f493c4&page[size]=3&page[from_id]=11&page[direction]=forward&search_string=special

Пример URI

GET https://<account>.okdesk.ru/api/v1/equipments/manufacturers/?api_token=3e9a214215f493c4

Параметры URI

СкрытьПоказать

api_token: string (обязательное) Пример: 3e9a214215f493c4
Ключ авторизации.

Ответ 200

СкрытьПоказать

Заголовки

Content-Type: application/json

Тело

[
  {
    "id": 5,
    "code": "005",
    "name": "manufacturer 5",
    "description": "somewhat special manufacturer",
    "visible": true
  },
  {
    "id": 8,
    "code": "008",
    "name": "manufacturer 8",
    "description": "special manufacturer",
    "visible": true
  },
  {
    "id": 10,
    "code": "010",
    "name": "manufacturer 10",
    "description": "very special manufacturer",
    "visible": true
  }
]

Создание производителя оборудования

POST`/api/v1/equipments/manufacturers/{?api_token}`

Название	Тип	Обязательность	Описание
name	string	обязательный	Название производителя оборудования
code	string	обязательный	Код производителя оборудования
description	string	необязательный	Описание производителя оборудования

Пример URI

POST https://<account>.okdesk.ru/api/v1/equipments/manufacturers/?api_token=3e9a214215f493c4

Параметры URI

СкрытьПоказать

api_token: string (обязательное) Пример: 3e9a214215f493c4
Ключ авторизации.

Запрос

СкрытьПоказать

Заголовки

Content-Type: application/json

Тело

{
  "equipment_manufacturer": {
    "code": "sample_code",
    "name": "sample_name",
    "description": "sample_text"
  }
}

Ответ 200

СкрытьПоказать

Заголовки

Content-Type: application/json

Тело

{
  "id": 57,
  "code": "sample_code",
  "name": "sample_name",
  "description": "sample_text",
  "visible": true
}

Редактирование производителя оборудования

PATCH`/api/v1/equipments/manufacturers/{manufacturer_id}{?api_token}`

Название	Тип	Обязательность	Описание
name	string	необязательный	Название производителя оборудования
description	string	необязательный	Описание производителя оборудования
visible	boolean	необязательный	Признак включенности

Пример URI

PATCH https://<account>.okdesk.ru/api/v1/equipments/manufacturers/57?api_token=3e9a214215f493c4

Параметры URI

СкрытьПоказать

api_token: string (обязательное) Пример: 3e9a214215f493c4
Ключ авторизации.
manufacturer_id: integer (обязательное) Пример: 57
ID редактируемого производителя оборудования

Запрос

СкрытьПоказать

Заголовки

Content-Type: application/json

Тело

{
  "equipment_manufacturer": {
    "name": "changed_name",
    "description": "changed_text",
    "visible": false
  }
}

Ответ 200

СкрытьПоказать

Заголовки

Content-Type: application/json

Тело

{
  "id": 57,
  "code": "code",
  "name": "changed_name",
  "description": "changed_text",
  "visible": false
}

Получение списка моделей оборудования

GET`/api/v1/equipments/models/{?api_token}`

Название	Тип	Обязательность	Описание
search_string	string	опционально	Искомая подстрока в названии или коде модели оборудования
page	associative array	опционально	Ассоциативный массив параметров постраничного вывода списка моделей оборудования (подробное описание представлено в таблице ниже).

Название	Тип значения	Обязательность	Описание
size	integer	опционально	Число возвращаемых записей. Не может превышать 100. Пример: page[size]=30
from_id	integer	опционально	ID модели оборудования, с которого начинается выборка записей. По умолчанию (если не задан параметр direction) выборка осуществляется в направлении от значения from_id в сторону уменьшения id модели. Пример: page[from_id]=10
direction	string	опционально	Направление выборки. Доступно два значения: reverse, forward. reverse - возвращает записи, ID которых меньше значения from_id, если параметр from_id передан. При отсутствии параметра from_id выборка осуществляется от наибольшого значения id модели. forward - возвращает записи, ID которых больше значения from_id, если параметр from_id передан. При отсутствии параметра from_id выборка осуществляется от наименьшего значения id модели. Пример: page[direction]=forward

Метод возвращает не более 100 записей. В случае, когда параметры постраничного вывода не переданы, будет возвращен список последних 100 созданных моделей оборудования.

https://<account>.okdesk.ru/api/v1/equipments/models/?
  api_token=3e9a214215f493c4&page[size]=3&page[from_id]=10&page[direction]=forward&search_string=special

Пример URI

GET https://<account>.okdesk.ru/api/v1/equipments/models/?api_token=3e9a214215f493c4

Параметры URI

СкрытьПоказать

api_token: string (обязательное) Пример: 3e9a214215f493c4
Ключ авторизации.

Ответ 200

СкрытьПоказать

Заголовки

Content-Type: application/json

Тело

[
  {
    "id": 5,
    "code": "005",
    "name": "somewhatspecialequipment",
    "description": "somewhat special equipment",
    "visible": true,
    "equipment_kind": {
      "code": "002",
      "id": 2,
      "name": "sample_kind"
    },
    "equipment_manufacturer": {
      "code": "001",
      "id": 1,
      "name": "sample_manufacturer"
    }
  },
  {
    "id": 8,
    "code": "008",
    "name": "specialequipment",
    "description": "special equipment",
    "visible": true,
    "equipment_kind": {
      "code": "002",
      "id": 2,
      "name": "sample_kind"
    },
    "equipment_manufacturer": {
      "code": "002",
      "id": 2,
      "name": "second_sample_manufacturer"
    }
  },
  {
    "id": 10,
    "code": "010",
    "name": "veryspecialequipment",
    "description": "very special equipment",
    "visible": true,
    "equipment_kind": {
      "code": "003",
      "id": 4,
      "name": "another_sample_kind"
    },
    "equipment_manufacturer": {
      "code": "001",
      "id": 1,
      "name": "sample_manufacturer"
    }
  }
]

Создание моделей оборудования

POST`/api/v1/equipments/models/{?api_token}`

Название	Тип	Обязательность	Описание
name	string	обязательный	Название модели оборудования
code	string	обязательный	Код модели оборудования
equipment_kind_id	integer	обязательный	ID типа оборудования
equipment_manufacturer_id	integer	обязательный	ID производителя оборудования
description	string	необязательный	Описание модели оборудования

Пример URI

POST https://<account>.okdesk.ru/api/v1/equipments/models/?api_token=3e9a214215f493c4

Параметры URI

СкрытьПоказать

api_token: string (обязательное) Пример: 3e9a214215f493c4
Ключ авторизации.

Запрос

СкрытьПоказать

Заголовки

Content-Type: application/json

Тело

{
  "equipment_model": {
    "code": "model_code",
    "name": "model_name",
    "description": "sample",
    "equipment_kind_id": 1,
    "equipment_manufacturer_id": 1
  }
}

Ответ 200

СкрытьПоказать

Заголовки

Content-Type: application/json

Тело

{
  "id": 57,
  "code": "model_code",
  "name": "model_name",
  "description": "sample",
  "visible": true,
  "equipment_kind": {
    "code": "001",
    "id": 1,
    "name": "sample_kind"
  },
  "equipment_manufacturer": {
    "code": "001",
    "id": 1,
    "name": "sample_manufacturer"
  }
}

Редактирование модели оборудования

PATCH`/api/v1/equipments/models/{model_id}{?api_token}`

Название	Тип	Обязательность	Описание
name	string	необязательный	Название модели оборудования
description	string	необязательный	Описание модели оборудования
visible	boolean	необязательный	Признак включенности
equipment_kind_id	integer	необязательный	ID типа оборудования
equipment_manufacturer_id	integer	необязательный	ID производителя оборудования

Пример URI

PATCH https://<account>.okdesk.ru/api/v1/equipments/models/57?api_token=3e9a214215f493c4

Параметры URI

СкрытьПоказать

api_token: string (обязательное) Пример: 3e9a214215f493c4
Ключ авторизации.
model_id: integer (обязательное) Пример: 57
ID редактируемой модели оборудования

Запрос

СкрытьПоказать

Заголовки

Content-Type: application/json

Тело

{
  "equipment_model": {
    "name": "changed_name",
    "description": "changed_text",
    "visible": false,
    "equipment_kind_id": 2,
    "equipment_manufacturer_id": 3
  }
}

Ответ 200

СкрытьПоказать

Заголовки

Content-Type: application/json

Тело

{
  "id": 57,
  "code": "model code",
  "name": "changed_name",
  "description": "changed_text",
  "visible": false,
  "equipment_kind": {
    "code": "002",
    "id": 2,
    "name": "sample_kind"
  },
  "equipment_manufacturer": {
    "code": "003",
    "id": 3,
    "name": "some_manufacturer"
  }
}

Получение списка часовых поясов

GET`/api/v1/timezones{?api_token}`

Метод доступен только для ключей, связанных с пользовательской ролью “Администратор”.

Пример URI

GET https://<account>.okdesk.ru/api/v1/timezones?api_token=3e9a214215f493c4

Параметры URI

СкрытьПоказать

api_token: string (обязательное) Пример: 3e9a214215f493c4
Ключ авторизации.

Ответ 200

СкрытьПоказать

Заголовки

Content-Type: application/json

Тело

[
  {
    "code": "Kaliningrad",
    "name": "Калининград",
    "gmt": "+02:00"
  },
  {
    "code": "Moscow",
    "name": "Москва",
    "gmt": "+03:00"
  },
  {
    "code": "Samara",
    "name": "Самара",
    "gmt": "+04:00"
  },
  {
    "code": "Irkutsk",
    "name": "Иркутск",
    "gmt": "+08:00"
  }
]

Другое ¶

Создание ссылки на логин

POST`/api/v1/login_link{?api_token}`

Генерация новой одноразовой ссылки на аутентификацию пользователя

Название	Тип	Обязательность	Описание
user_login	string	необязательный	Логин пользователя
user_type	string	необязательный	Тип пользователя. Допустимые типы: employee - сотрудник, contact - контактное лицо
user_id	integer	необязательный	ID пользователя
expire_after	integer	необязательный	Время действия ссылки в минутах. Если время действия ссылки не указано, то оно будет равно 30 дням.
one_time	boolean	необязательный	Тип ссылки (одноразовая/многоразовая). Если параметр не передан, то генерируется одноразовая ссылка на логин.

При отсутствии параметра user_login или одного из параметров user_type, user_id ссылка на логин будет сгенерирована для связанного с ключом пользователя.

Генерация ссылок на аутентификацию пользователей доступна без ограничений только для ключей, связанных с пользователями-администраторами (роль “Администратор”). В остальных случаях доступна генерация ссылки на авторизацию только связанного с ключом пользователя.

Пример URI

POST https://<account>.okdesk.ru/api/v1/login_link?api_token=3e9a214215f493c4

Параметры URI

СкрытьПоказать

api_token: string (обязательное) Пример: 3e9a214215f493c4
Ключ авторизации.

Запрос

СкрытьПоказать

Заголовки

Content-Type: application/json

Тело

{
  "user_login": "employee@okdesk.ru",
  "expire_after": 60,
  "one_time": false
}

Ответ 200

СкрытьПоказать

Заголовки

Content-Type: application/json

Тело

{
  "login_link": "http://<account>.okdesk.ru/login?token=430379fd78be7c71623cad7590b8a23d",
  "user_id": 56,
  "user_type": "employee",
  "roles": [
    "Администратор"
  ],
  "user_first_name": "Иван",
  "user_last_name": "Иванов",
  "user_patronymic": "Иванович",
  "user_position": "Главный Администратор",
  "user_email": "example@example.com",
  "user_custom_parameters": [
    {
      "code": "code2",
      "name": "Date",
      "field_type": "ftdate",
      "value": "2024-01-25"
    }
  ]
}

Создание API-ключа пользователя

POST`/api/v1/api_key{?api_token}`

Генерация нового API-ключа для пользователя

Название	Тип	Обязательность	Описание
user_type	string	обязательный	Тип пользователя (контакт или сотрудник)
id	integer	обязательный	ID пользователя

Метод доступен только для ключей, связанных с пользовательской ролью “Администратор”.

Пример URI

POST https://<account>.okdesk.ru/api/v1/api_key?api_token=3e9a214215f493c4

Параметры URI

СкрытьПоказать

api_token: string (обязательное) Пример: 3e9a214215f493c4
Ключ авторизации.

Запрос

СкрытьПоказать

Заголовки

Content-Type: application/json

Тело

{
  "user_type": "employee",
  "id": 1
}

Ответ 200

СкрытьПоказать

Заголовки

Content-Type: application/json

Тело

{
  "api_key": "12345ghy8be7c71623cad7590b8a5q3"
}

Запрос

СкрытьПоказать

Заголовки

Content-Type: application/json

Тело

{
  "user_type": "employee",
  "id": 12
}

Ответ 422

СкрытьПоказать

Заголовки

Content-Type: application/json

Тело

{
  "errors": "Запрошенный пользователь деактивирован"
}

Получение API-ключа пользователя

GET`/api/v1/api_key{?api_token}&user_type={user_type}&id={id}`

Метод доступен только для ключей, связанных с пользовательской ролью “Администратор”.

Пример URI

GET https://<account>.okdesk.ru/api/v1/api_key?api_token=3e9a214215f493c4&user_type=employee&id=2

Параметры URI

СкрытьПоказать

api_token: string (обязательное) Пример: 3e9a214215f493c4
Ключ авторизации.
id: integer (обязательное) Пример: 2
Внутренний ID пользователя
user_type: string (обязательное) Пример: employee
Тип пользователя

Ответ 200

СкрытьПоказать

Заголовки

Content-Type: application/json

Тело

{
  "api_key": "430379fd78be7c71623cad7590b8a23d"
}

Ответ 422

СкрытьПоказать

Заголовки

Content-Type: application/json

Тело

{
  "errors": "Запрошенный пользователь деактивирован"
}

Получение API-ключа пользователя по логину и паролю

POST`/api/v1/users/sign_in`

Название	Тип	Обязательность	Описание
login	string	обязательный	Логин пользователя (контакт или сотрудник)
password	string	обязательный	Пароль

Пример URI

POST https://<account>.okdesk.ru/api/v1/users/sign_in

Запрос с корректными параметрами

СкрытьПоказать

Заголовки

Content-Type: application/json

Тело

{
  "login": "user",
  "password": "Password"
}

Ответ 200

СкрытьПоказать

Заголовки

Content-Type: application/json

Тело

{
  "api_key": "430379fd78be7c71623cad7590b8a23d"
}

Запрос с некорректными параметрами

СкрытьПоказать

Заголовки

Content-Type: application/json

Тело

{
  "login": "user"
}

Ответ 422

СкрытьПоказать

Заголовки

Content-Type: application/json

Тело

{
  "errors": {
    "password": [
      "отсутствует"
    ]
  }
}

Компании ¶

Поиск компании

GET/api/v1/companies/{?api_token,name,phone,id,crm_1c_id,search_string}

Ограничения прав доступа ¶

Обратите внимание ¶

Пример URI

Заголовки

Тело

Создание компании

POST/api/v1/companies/{?api_token}

Допустимые параметры запроса: ¶

Ограничения прав доступа ¶

Обратите внимание ¶

Пример URI

Заголовки

Тело

Заголовки

Тело

Редактирование компании

PATCH/api/v1/companies/{company_id}{?api_token}

Допустимые параметры запроса: ¶

Ограничения прав доступа ¶

Обратите внимание ¶

Пример URI

Заголовки

Тело

Заголовки

Тело

Получение списка по параметрам

GET/api/v1/companies/list{?api_token}

Допустимые параметры запроса: ¶

Допустимые параметры постраничного вывода: ¶

Ограничения прав доступа ¶

Обратите внимание ¶

Допустимые значения дополнительных атрибутов: ¶

Пример запроса с параметрами постраничного вывода списка компаний: ¶

Пример URI

Заголовки

Тело

Заголовки

Тело

Получение файла компании

GET/api/v1/companies/{company_id}/attachments/{attachment_id}{?api_token}

Ограничения прав доступа ¶

Обратите внимание ¶

Пример URI

Заголовки

Тело

Архивация компании

PATCH/api/v1/companies/{id}/activations{?api_token}

Допустимые параметры запроса: ¶

Ограничения прав доступа ¶

Пример URI

Заголовки

Тело

Заголовки

Тело

Договоры ¶

Поиск договора

GET/api/v1/agreements/{?api_token,search_string}

Ограничения прав доступа ¶

Пример URI

Заголовки

Тело

Информация о договоре

GET/api/v1/agreements/{id}{?api_token}

Ограничения прав доступа ¶

Пример URI

Заголовки

Тело

Редактирование договора

PATCH/api/v1/agreements/{id}{?api_token}

Допустимые параметры запроса: ¶

Ограничения прав доступа ¶

Пример URI

Заголовки

Тело

Заголовки

Тело

Создание договора

GET`/api/v1/companies/{?api_token,name,phone,id,crm_1c_id,search_string}`

Ограничения прав доступа

Обратите внимание

POST`/api/v1/companies/{?api_token}`

Допустимые параметры запроса:

Ограничения прав доступа

Обратите внимание

PATCH`/api/v1/companies/{company_id}{?api_token}`

Допустимые параметры запроса:

Ограничения прав доступа

Обратите внимание

GET`/api/v1/companies/list{?api_token}`

Допустимые параметры запроса:

Допустимые параметры постраничного вывода:

Ограничения прав доступа

Обратите внимание

Допустимые значения дополнительных атрибутов:

Пример запроса с параметрами постраничного вывода списка компаний:

GET`/api/v1/companies/{company_id}/attachments/{attachment_id}{?api_token}`

Ограничения прав доступа

Обратите внимание

PATCH`/api/v1/companies/{id}/activations{?api_token}`

Допустимые параметры запроса:

Ограничения прав доступа

GET`/api/v1/agreements/{?api_token,search_string}`

Ограничения прав доступа

GET`/api/v1/agreements/{id}{?api_token}`

Ограничения прав доступа

PATCH`/api/v1/agreements/{id}{?api_token}`

Допустимые параметры запроса:

Ограничения прав доступа

POST`/api/v1/companies/{company_id}/agreements{?api_token}`

Допустимые параметры запроса:

Ограничения прав доступа

GET`/api/v1/companies/{company_id}/agreements{?api_token}`

Обратите внимание

Ограничения прав доступа

POST`/api/v1/agreements/{agreement_id}/service_periods{?api_token}`

Допустимые параметры запроса:

Ограничения прав доступа

PATCH`/api/v1/agreements/{agreement_id}/service_periods/{id}{?api_token}`

Допустимые параметры запроса:

Ограничения прав доступа

DELETE`/api/v1/agreements/{agreement_id}/service_periods/{id}{?api_token}`

Ограничения прав доступа

POST`/api/v1/issues/{?api_token}`

Допустимые параметры запроса:

Обратите внимание

Ограничения прав доступа

Допустимые параметры прикрепляемых файлов:

Обратите внимание

PATCH`/api/v1/issues/{issue_id}/assignees{?api_token}`

Допустимые параметры запроса:

Обратите внимание

Ограничения прав доступа

Обратите внимание