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":[]
                }
            ]
        }
    ]
}