API osTicket
- Общее описание
- /api/tickets.json
- /api/tickets/get.json
- /api/tickets/thread.json
- /api/tickets/getunreaded.json
- /api/tickets/message.json
- /api/tickets/unreaded.json
- /api/tickets/gettopics.json
- /api/tickets/threads.json
Общее описание
Все запросы к API osTicket http post. Ко всем передаются следующие http-заголовки:
X-API-Key - Ключ API-доступа к osticket
User-Login - Логин пользователя osTicket, от имени которого выполняется запрос. Должен быть правильным email.
User-Password - Пароль пользователя. Не используется для специальных API ключей, работающих совместно с авторизацией lk2.
Запрос должен содержать хотя бы один post-параметр. Если параметры по логике запроса не нужны, его следует вызывать с параметром-заглушкой.
{
"param": 1
}
/api/tickets.json
Создает тикет.
- subject - тема сообщения. В нашем интерфейсе традиционно используется как номер заказа но системных ограничений на это нет.
- message - содержимое сообщения
- topicId - id категории заявки. Полный их список задан в системных настройках osTicket. Например "topicId": 103 соответствует категории "Срочная доставка день в день"
- attachments - массив вложенных файлов. Ключ - имя файла. Значение - содержимое файла в виде base64 - строки (data URL).
- returnWorkingNow - булев параметр. Если true - возвращает json в котором кроме номера созданного тикета содержится признак работает ли отдел в текущее время. И сообщение с рабочим временем отдела, которое можно выдать клиенту.
{
"success": true,
"number":"219600",
"is_working_now":false,
"not_working_message":"График работы сервисного отдела ежедневно с 9:00 до 21:00. Мы ответим Вам в рабочие часы. Спасибо за обращение!"
}
- returnJson - булев параметр. Если true возвращает номер и ID созданного тикета в формате JSON. Иначе - просто строковое значение номера тикета (режим совместимости с нативным osTicket)
{
"success": true,
"number": "526252",
"id": 224336
}
Пример запроса:
{
"subject":"777",
"message":"data:text/html;charset=utf-8,<p>Пробное сообщение</p>",
"topicId":103,
"returnJson": true,
"attachments":[
{"logo-color.svg":"data:image/svg+xml;base64,..."},
{"test.log":"data:text/x-log;base64,..."}
]
}
/api/tickets/get.json
Возвращает список тикетов пользователя, переданного в http-заголовке запроса
Все параметры не обязательны.
- size, page - пагинация. Номер страницы начинается с 0. Если не задано - возвращает все тикеты
- search - поиск. Если значение начинается с цифры ищет по вхождению в номер тикета или в поле subject, которое в нашем интерфейсе применяется как номер заказа. Иначе - полнотекстовый поиск по тикету.
- direction - outbound входящие тикеты, inbound - исходящие, пустое значение - все.
- collaborator_visibility - в возвращаемые тикеты включаются те, для которых пользователь является соавтором
- org_visibility - в возвращаемые тикеты включаются созданные другими пользователями организации. Если у пользователя в osTicket нет прав просмотра тикетов других пользователей организации - не влияет на результат.
- unreaded_only - возвращает только непрочитанные тикеты
- subject - фильтрация тикетов по номеру заказа. В отличие от search поиск не по вхождению а по полному соответствию строки.
- updated_from - возвращаются тикеты измененные в указанное время или позднее. Время измененя тикета - это время его создания или последнего сообщения в цепочке его переписки
{
"page":0,
"size":10,
"search":"878",
"direction":"outbound",
"collaborator_visibility": true,
"org_visibility": true,
"unreaded_only": true,
"subject": "171220-41656-1959"
"updated_from": "2022-08-08 23:08:09"
"number":"367871"
"ticket_id":"203300"
}
Пример возвращаемого значения:
- state отличается от status тем что state более обобщенное понятие. Например state: colse значит что тикет закрыт. Но закрыт он может быть как по причине проблема решена так и без объясения причин. Этому соответствует status.
- message здесь возвращается без html-тегов. Полный ткст сообщения можно получить в вызове thread
{
"success": true,
"recordsTotal":26,
"tickets": [
{
"ticket_id":34901,
"subject":"тестовый номер 777",
"status_id":2,
"status":"Проблема решена",
"number":"651265",
"isanswered":0,
"state":"closed",
"created":"2021-02-08 13:35:08",
"message":"Пробное сообщение",
"topic_id":103,
"unreaded":false,
"direction":"outbound",
"reopenable":true,
"user_id": 10,
"user_login": "test@mail.ru",
"user_name": "Иван",
"updated": "2022-05-06 14:28:14"
},
{
"ticket_id":12514,
"subject":"888-888",
"status_id":3,
"status":"Закрыт",
"number":"840372",
"isanswered":0,
"state":"closed",
"created":"2020-12-09 19:15:19",
"message":"Тестовое сообщение",
"topic_id":1,
"unreaded":false,
"direction":"outbound",
"reopenable":false,
"user_id": 12,
"user_login": "test2@mail.ru",
"user_name": "Петр",
"updated": "2022-05-06 14:28:14"
},
]
}
Если в заголовке передан логин пользователя, отсутствующий в osTicket запрос не завершается ошибкой а возвращает следующий ответ:
{
"account_not_found": 1
}
Это можно использовать для авторегистрации пользователей при первом обращении к функционалу osTicket.
/api/tickets/thread.json
Возвращает цепочку переписки данного тикета
{
"ticket_id":34937
}
Пример возвращаемого значения
- id - id сообщения.
- type - 'M' заявка, 'R' ответ
- is_staff - true сообщение от сотрудника, false - от пользователя
- author - имя автора сообщения
- user_login - логин (email) автора сообщения
- created - дата создания сообщения
- title - не используется
- message - текст сообщения
- attachments - вложенные файлы
- size - длина
- url - url для скачивания файла
- name - имя файла
{
"success": true,
"messages": [
{
"id":1074256,
"type":"M",
"is_staff":false,
"author":"Slava",
"user_login":"slava-sh@yandex.ru",
"created":"2023-03-14 23:34:02",
"title":null,
"message":"<p>Новая заявка<\/p>",
"attachments":[
{
"size": 26556,
"url": "https://ticket.kak2c.ru/file.php?key=f-5x9e888ngsiuvsgeuy_ge59gczgnsu&expires=1612828800&signature=ae890af39b6ba9e4659ec5f221b7a4a4d24b5904&id=6866",
"name": "baner-1.jpg"
}
]
},
{
"id":1074257,
"type":"R",
"is_staff":true,
"author":"admin notasoft",
"user_login":"adm1@notasoft.ru",
"created":"2023-03-14 23:54:33",
"title":null,
"message":"<p>Привет!<\/p>",
"attachments":[]
}
]
}
/api/tickets/getunreaded.json
Возвращает количество непрочитанных пользователем сообщений. Учитываются только тикеты владелец которого данный пользователь. Не учитываются тикеты других пользователей организации и те в которых данный пользователь соавтор. Пример возвращаемого результата:
{
"success": true,
"unreadedCount": 2
}
/api/tickets/message.json
Отправка сообщения в ветку тикета (ответа на тикет)
- attachments - массив вложенных файлов. Ключ - имя файла. Значение - содержимое файла в виде base64 - строки (data URL).
- is_resolved - если true, одновременно с ответом тикет закрывается со статусом "проблема решена". Т.о. пользователь может сам закрыть тикет.
{
"attachments": [
{
"p-14334.jpg": "data:image/jpeg;base64,..."
}
],
"is_resolved": true,
"message": "data:text/html;charset=utf-8,<p>Ответ на сообщение</p>",
"ticket_id": 34937
}
Ответ:
{
"success": true,
"message_id":1074273
}
/api/tickets/unreaded.json
Помечает тикет как прочитанный или непрочитанный:
- ticket_id - можно передать как отдельный ID тикета, так и массив id для установки статуса нескольким тикетам за один вызов
- value - true - непрочитан, false - прочитан
{
"ticket_id": 34960,
"value": false
}
Возвращает
{
"success": true
}
/api/tickets/gettopics.json
Возвращает справочник категорий и тем тикетов
[
{
"value": 2,
"label": "Общие вопросы",
"fields": [],
"order": "1",
"isMassSending": false,
"children": [
{
"value": 12,
"label": "Возможности Кактуса",
"fields": [],
"order": 1000000,
"isMassSending": false
},
{
"value": 131,
"label": "Делопроизводство",
"fields": [],
"order": 1000000,
"isMassSending": false
},
{
"value": 16,
"label": "Возможности личного кабинета",
"fields": [],
"order": 1000000,
"isMassSending": false
},
{
"value": 17,
"label": "Доступная отчетность",
"fields": [],
"order": 1000000,
"isMassSending": false
},
{
"value": 19,
"label": "Как вызвать курьера?",
"fields": [],
"order": 1000000,
"isMassSending": false
},
{
"value": 14,
"label": "Тарифы и условия",
"fields": [],
"order": 1000000,
"isMassSending": false
},
{
"value": 13,
"label": "Услуги и их стоимость",
"fields": [],
"order": 1000000,
"isMassSending": false
}
]
},
{
"value": 1,
"label": "Старт работы",
"fields": [],
"order": "2",
"isMassSending": false,
"children": [
{
"value": 23,
"label": "КП Кактус.Доставка",
"fields": [
{
"value": "dogovor",
"label": "Номер договора клиента",
"note_field": "номер_договора_клиента",
"moderatory": false
},
{
"value": "company",
"label": "Юрлицо",
"note_field": "юрлицо",
"moderatory": false
}
],
"order": "1",
"isMassSending": false
},
{
"value": 20,
"label": "КП Кактус.Фулфилмент",
"fields": [
{
"value": "dogovor",
"label": "Номер договора клиента",
"note_field": "номер_договора_клиента",
"moderatory": false
},
{
"value": "company",
"label": "Юрлицо",
"note_field": "юрлицо",
"moderatory": false
}
],
"order": "2",
"isMassSending": false
},
{
"value": 24,
"label": "Условия договора",
"fields": [
{
"value": "dogovor",
"label": "Номер договора клиента",
"note_field": "номер_договора_клиента",
"moderatory": false
},
{
"value": "company",
"label": "Юрлицо",
"note_field": "юрлицо",
"moderatory": false
}
],
"order": "3",
"isMassSending": false
},
{
"value": 25,
"label": "Доп условия",
"fields": [
{
"value": "dogovor",
"label": "Номер договора клиента",
"note_field": "номер_договора_клиента",
"moderatory": false
},
{
"value": "company",
"label": "Юрлицо",
"note_field": "юрлицо",
"moderatory": false
}
],
"order": "4",
"isMassSending": false
},
{
"value": 118,
"label": "Техниче\u0441кие вопросы",
"fields": [],
"order": "5",
"isMassSending": false
},
{
"value": 26,
"label": "Другое",
"fields": [
{
"value": "dogovor",
"label": "Номер договора клиента",
"note_field": "номер_договора_клиента",
"moderatory": false
},
{
"value": "company",
"label": "Юрлицо",
"note_field": "юрлицо",
"moderatory": false
}
],
"order": "6",
"isMassSending": false
}
]
},
...
]
/api/tickets/threads.json
Возвращает цепочку переписки нескольких тикетов
{
"updated_from": "2023-01-01 00:00:00",
"ticket_ids":["203296","195327"]
}
Пример возвращаемого значения, содержимое массива messages для каждого тикета аналогично одноименному массиву, описанному здесь
{
"success": true,
"tickets":[
{
"ticket_id":203296,
"messages":[
{
"id":1074256,
"type":"M",
"is_staff":false,
"author":"Slava",
"created":"2023-03-14 23:34:02",
"title":null,
"message":"<p>Новая заявка</p>",
"attachments":[]
},
{
"id":1074257,
"type":"R",
"is_staff":true,
"author":"admin notasoft",
"created":"2023-03-14 23:54:33",
"title":null,
"message":"<p>Привет!</p>",
"attachments":[]
}
]
},
{
"ticket_id":203297,
"messages": [
{
"id":1074260,
"type":"M",
"is_staff":false,
"author":"Slava",
"created":"2023-03-21 01:43:53",
"title":"Другой вопрос",
"message":"<p>Проверка статусов</p>",
"attachments":[]
}
]
}
]
}