Версия: Последняя

Auth API

Лицензия

API доступно только при наличии модуля "IQChannels – API. Auth.C" или "IQChannels – API. Auth.B" или "IQChannels – iSimpleCorporate" или "IQChannels – iSimpleRetail"

Auth API — это протокол авторизации клиента, который использует сервер чата для авторизации клиента во внешней системе (CRM/ДБО или другой учетной системе).

Для авторизации юридических и физических лиц используется единое API, при этом минимальный атрибутный состав API будет обрабатываться только при наличие соответствующего модуля (например companyList обрабатывается только при наличии модуля "IQChannels – API. Auth.B" или "IQChannels – iSimpleCorporate").

Протокол авторизации

Получение токена. Браузер или мобильное приложение получают или генерируют токен клиента для авторизации в чате. Токен — это любая строка. Например, это может быть токен текущей сессии.
Передача токена в SDK. При инициализации SDK чата (виджета, мобильных SDK) браузер или мобильное приложение передает в него токен клиента.
Запрос авторизации по токену. SDK чата отправляет запрос на авторизацию клиента на сервер чата.
Запрос карточки клиента. Сервер чата получает токен и отправляет этот токен в сервис авторизации для авторизации клиента и получение его карточки. Сервисом авторизации может выступать CRM, ДБО и т.д.
Возврат карточки клиента. Сервис авторизации проверяет токен клиента и возвращает карточку клиента или ошибку.
Сохранение информации о клиенте. Сервер чата сохраняет карточку клиента локально.
Возврат сессии авторизации в чате. Сервер чата создает сессию авторизации клиента в чате и возвращает ее в SDK.
Авторизация клиента в SDK завершена.

Запрос

Запросы можно отправлять с помощью одного из HTTP методов к REST-сервису: GET или POST.

При этом в случае с методом GET - токен содержится в URL-запроса, при использовании метода POST - токен передается в параметре header.

Пример запроса GET

http://[host]:[port]/rest/chat/client/id/{token}

Входные параметры в URL


Параметр	Обязательность	Описание
token	да	Токен клиента

Пример запроса POST

http://[host]:[port]/rest/chat/client/id/


Элемент	Обязательность	Где передается	Описание
token	да	header	Токен клиента

Ответ

Response

В случае успешного ответа сервер возвращает статус 200 с ответом в формате application/json.

Поле	Тип	Обязательное	Комментарий
`client`	Client	нет	Информация о клиенте
`companyList`	List Company	нет	Список организаций, к которым относится текущий клиент. (Только для модулей "IQChannels – API. Auth.B" и "IQChannels – iSimpleCorporate")

`errorCode`	String	нет	Код ошибки
`errorText`	String	нет	Текст ошибки

Client

Поле	Тип	Обязательное	Комментарий
`id`	String	да	Идентификатор клиента в CRM (Master ID)
`contract`	String	нет	Номер генерального соглашения, соглашений может быть несколько, передавать через запятую
`telSysClientId`	String	нет	Идентификатор клиента в системе телефонии
`name`	String	да	ФИО клиента
`surname`	String	да	Фамилия
`firstname`	String	да	Имя
`patronymic`	String	нет	Отчество
`type`	String (0 или 1)	да	Код типа клиента (физическое лицо \ юридическое лицо).
`enabled`	String	да	Обслуживание организации разрешено - "true", иначе - "false"
`birthDate`	String (YYYY-MM-DD)	нет	Дата рождения
`extRef`	String	нет	Идентификатор клиента в АБС
`cardRef`	String	нет	Идентификатор клиента в карточный системе (ДКБО ID)
`bankBranch`	Branch	нет	Информация о подразделении клиента
`actionList`	List ActionList	нет	Список кнопок-ссылок в формате: name - value
`inn`	String	нет	ИНН клиента.
`shortName`	String	нет	Краткое наименование клиента.
`accountNumbers`	String	нет	Номера счета клиента. Данное поле не сохраняется в карточке клиента и храниться только в рамках открытого обращения
`positionStream`	Boolean	нет	Новый портфель, значение для PositionStream (true/false)
`betaUser`	Boolean	нет	Флаг бета пользователя (true/false)
`lvlClient`	String	нет	Сервисный уровень клиента, приоритет обслуживания
`timezone`	String	нет	Часовой пояс на устройстве клиента
`osVersion`	String	нет	Версия ОС устройства
`device`	String	нет	Тип устройства
`deviceVersion`	String	нет	Версия приложения
`contacts`	Contacts	нет	Информация о контактах клиента для информирования оператора и выстраивания омниканальных связей
`secretWord`	String	нет	Кодовое слово, которое операторы или бот используют для ручной идентификации клиента
`group`	Group	нет	Информация о группах клиентов для версии iQPro.

Branch

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

Поле	Тип	Обязательное	Комментарий
`id`	Long	нет	Идентификатор подразделения \ филиала во внешней системе
`extRef`	String	нет	Идентификатор в главной учетной системе (например АБС)
`bik`	String	нет	БИК подразделения (для банка)
`name`	String	нет	Наименование подразделения \ филиала

Company

Информация об организации.

Поле	Тип	Обязательное	Комментарий
`id`	Integer	да	Идентификатор организации во внешней системе
`name`	String	нет	Наименование организации
`type`	String	нет	Код типа организации
`enabled`	String	нет	Обслуживание организации разрешено - "true", иначе - "false"
`extRef`	String	нет	Код организации в главной учетной системе (например АБС)
`inn`	String	нет	ИНН
`kpp`	String	нет	КПП
`resident`	Boolean	нет	Признак "Нерезидент"
`phone`	String	нет	Телефоны
`shortName`	String	нет	Сокращенное наименование
`internationalName`	String	нет	Международное наименование
`ogrn`	String	нет	ОГРН
`ogrnDate`	String (YYYY-MM-DD)	нет	Дата ОГРН
`internationalAddress`	String	нет	Полный международный адрес компании

Field

Поле с дополнительной информацией о клиенте.

Поле	Тип	Обязательное	Комментарий
`name`	String	да	Название поля, которое будет отображаться в интерфейсе оператора
`value`	String	да	Значение поля

Contacts

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

Поле	Тип	Обязательное	Комментарий
`phone`	String	нет	Номер телефона
`email`	String	нет	Электронная почта
`telegramUserName`	String	нет	Текстовый идентификатор пользователя в Telegram
`whatsappPhone`	String	нет	Идентификатор пользователя в Whatsapp в формате номера телефона

Group

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

Поле	Тип	Обязательное	Комментарий
`id`	Long	да	Идентификатор группы во внешней системе
`parentGroup`	Group	нет	Информация о родительской группе в случае древовидной структуры
`name`	String	нет	Наименование группы. Если не задано, можно указать вручную в iQChannels
`description`	String	нет	Описание группы
`priority`	Long	нет	Приоритет обращений от клиентов в данной группе по умолчанию

ActionList

Группа кнопок \ ссылок.

Поле	Тип	Обязательное	Комментарий
`name`	String	нет	Название/текст кнопки \ ссылки. Если не указано, то по умолчанию заполняется как “Открыть в CRM”
`type`	Integer	нет	Тип элемента (ссылка \ кнопка). Допустимые значения: * 0 (или не указано) - Ссылка (вертикальная последовательность) * 1 - Кнопка (горизонтальная последовательность)
`value`	String	да	Значение поля - URL ссылка, куда будет вести кнопка \ ссылка

Примеры ответов

Успешный ответ

В случае успешного ответа сервер возвращает статус 200 с ответом в формате application/json:

GET http://127.0.0.1:8080/rest/chat/client/id/a57974242d0146c28056

Успешный ответ:

{
    "client": {
        "id": "1064775",
        "name": "Давыдов Юрий Викторович",
        "surname": "Давыдов",
        "firstname": "Юрий",
        "patronymic": "Викторович",
        "shortName": "Юрий",
        "birthDate": "1976-03-31",
        "type": "0",
        "enabled": "true",
        "extRef": "1",
        "bankBranch": {
            "id": "720987",
            "extRef": "1",
            "bik": "042809888",
            "name": "ЗАО КБ \"ГЛОБАЛЬНЫЙ РАСЧЕТНЫЙ ЦЕНТР\""
        },
        "fieldList": [
            {
                "name": "ИНН",
                "value": "1234567890"
            },
            {
                "name": "Город",
                "value": "Москва"
            }
        ]
    }
}

Успешный ответ со списком компаний

{
    "client": {
        "id": "124625",
        "name": "Царев Алексей Юрьевич",
        "surname": "Царев",
        "firstname": "Алексей",
        "patronymic": "Юрьевич",
        "birthDate": "1973-09-02",
        "type": "2",
        "enabled": "false"
    },
    "companyList": [
        {
            "id": "225760",
            "name": "ООО УралСтройМаш",
            "extRef": "561",
            "inn": "7701028744",
            "kpp": "770001001",
            "resident": "true",
            "phone": "+79093342334",
            "shortName": "ОАО ЛИГА",
            "internationalName": "LIGA JSC",
            "ogrn": "1057703026633",
            "ogrnDate": "2005-02-11"
        },
        {
            "id": "124612",
            "name": "ОАО Капитолий",
            "extRef": "560",
            "inn": "7701058541",
            "kpp": "770001001",
            "resident": "true",
            "phone": "123-34-45",
            "shortName": "ОАО Капитолий",
            "internationalName": "CAPITOLIY JSC",
            "ogrn": "2801283419468",
            "internationalAddress": "",
            "regAddress": ""
        }
    ]
}

Ответ с ошибкой

В случае ошибки сервер возвращает статус не 200, а также может дополнительно возвращать описание ошибки в формате application/json в теле ответа:

{
    "errorCode": "1001",
    "errorText": "Client not found"
}

Частные реализации

Описание сервиса iSimpleBank для авторизации клиентов

Изменения

Версия 1.1

В типе Client добавлено поле shortName.
В типе Client добавлено поле fieldList.
Добавлен тип Field.

Версия 1.2

В типе Client добавлено поле contacts.
В типе Client добавлено поле secretWord.
В типе Client добавлено поле group.
Добавлен тип Contacts.
Добавлен тип Group.

Версия 1.3

Добавлена возможность использовать протокол AUTH с методом POST.
В типе Client добавлено поле accountNumbers.
В типе Client добавлено поле positionStream.
В типе Client добавлено поле betaUser.
В типе Client добавлено поле lvlClient.
В типе Client добавлено поле timezone.
В типе Client добавлено поле osVersion.
В типе Client добавлено поле device.
В типе Client добавлено поле deviceVersion.

Версия 1.4

В типе Client добавлено поле actionList.
Добавлен тип ActionList.

Протокол авторизации​

Запрос​

Ответ​

Response​

Client​

Branch​

Company​

Field​

Contacts​

Group​

ActionList​

Примеры ответов​

Успешный ответ​

Успешный ответ со списком компаний​

Ответ с ошибкой​

Частные реализации​

Изменения​

Версия 1.1​

Версия 1.2​

Версия 1.3​

Версия 1.4​