API-SUPPORT

API Support Benzuber – протокол для обеспечения взаимодействия между внешней системой партнера и сервисом технической поддержки Benzuber (ТП).

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

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

• Авторизация партнёра;
• Создание нового обращения в ТП;
• Работа с обращением (добавление сообщения/файла);
• Получение списка обращений;
• Работа с обращением (получение сообщения/файла);
• Получение callback сообщений партнёром от ТП об изменениях в обращении (опционально);

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

Базовый URL_BZ – адрес для обращения к серверу BZ. Для начала работы необходимо получить временный_токен, выполнив запрос авторизации. Далее, все запросы выполняются HTTP/HTTPS запросами (GET или POST) вида: URL_BZ + /api/ticket/команда?token=[временный_токен]

HTTP коды ответа:

200 – запрос выполнен успешно
400 - неверные параметры в запросе
401 – ошибка авторизации, доступ запрещен, требуется получить новый временный_токен
404 - не найдено обращение по идентификатору

Авторизация партнера

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

Запрос

(POST) URL_BZ + /api/token/get

Ответ

Content type: application/json

{
  "response": "success",
  "token": 
    {
        "value" : "временный_токен",
        "expiration" : 1598723948
    }
}

Создание нового обращения в ТП;

Запрос для создания нового обращения в ТП

Запрос

(POST) URL_BZ + /api/ticket/create?token=[token]

Ответ

Content type: application/json

{
  "response": "success",
  "id": 139823,
  "description": "описание"
}

Добавление сообщения в обращение

Запрос для добавления текстового сообщения в существующее обращение партнёра

Запрос

(POST) URL_BZ + /api/ticket/post?token=[token]

Ответ

Content type: application/json

{
  "response": "success",
  "messageid": 139823,
  "description": "описание"
}

Добавление файла-вложения в обращение

Запрос для добавления произвольного файла в существующее обращение

Запрос

(POST) URL_BZ + /api/ticket/post?token=[token]

Ответ

Content type: application/json

{
  "response": "success",
  "messageid": 139823,
  "description": "описание"
}

Получение списка обращений;

Запрос для получения списка обращений партнёра

Запрос

(POST) URL_BZ + /api/ticket/list?token=[token]

Ответ

Content type: application/json

{
  "response": "success",
  "tickets": 
    [
        {
            "id": 234324,
            "status": "process",
            "create": 1235325,
            "change": 1243565,
            "unread_self": true,
            "unread_support":  false
        },
        {...}
    ],
  "pagination" : 
    {
        "page": 1,
        "page_max": 5,
        "limit": 10
    }
}

Запрос списка сообщений одного тикета

Запрос для получения спиcка сообщений в обращении

Запрос

(POST) URL_BZ + /api/ticket/get?token=[token]

Ответ

Content type: application/json

{
  "response": "success",
  "ticket": 
    {
        "id": 234324,
        "status": "process",
        "create": 1235325,
        "change": 1243565,
        "unread_self": true,
        "unread_support": false
    },
  "messages":
    [
        {
            "messageid":234,
            "date": 121434,
            "attachment": false,
            "value": "текст сообщения",
            "support": true,
            "unread": false
        },
        {...}
    ],
  "pagination" : 
    {
        "page": 1,
        "page_max": 5,
        "limit": 10
    }
}

Запрос скачивания файла-вложения

Запрос для скачивания файла-вложения в обращении

Запрос

(POST) URL_BZ + /api/ticket/download?token=[token]

Ответ
В случае успешного ответа http-code = 200, в теле ответа содержимое файла.