Доступ через API

Сервис Qolio построен на основе клиент-серверной архитектуры и ничего не мешает получить доступ к информации вашего аккаунта через API.
API можно использовать для множества кейсов, таких как:
  • Получение результатов проверок для операторов
  • Автоматическая добавление и настройка пользователей
Главный API endpoint находится по адресу: https://api.prod1.dealapp.io.
Принцип Построения
API построен на основе спецификаций JSON API (https://jsonapi.org/). Вы можете подчеркнуть дополнительные знание по этому подходу в следующих статьях:
Параметры GET запросов, которые могут приходится для получения информации:
Типы данных: в API используются простые типы данных - string, integer, float.

Авторизация

Авторизация происходит через JWT токены, которые можно получить по запросу на endpoint /auth/sign_in. На этот запрос вам прийдет ответ с установленными headers с названиями:
  • uid
  • access-token
  • client
Установив эти три значения в свои последующие запросы, вы сможете использовать остальные запросы на API.
Тут вы можете увидеть пример работы с авторизацией с помощью утилиты curl:
curl -i -H "Content-Type: application/json" -X POST --data '{"email": "[email protected]", "password":"secret123"}' https://api.prod1.dealapp.io/auth/sign_in | grep -i 'client\:\|uid\:\|access-token\:' > headers.txt
curl -X GET -H @headers.txt 'https://api.prod1.dealapp.io/api/v1/client_interactions?include=operator&page[number]=1' | jq
Далее вы можете использовать /auth/validate_token endpoint c GET параметрами uid, access-token и client для того, чтобы проверить эти значения.
Все запросы, которые вы далее будете делать с помощью этих токенов будут иметь тот же уровень доступа, что и пользователь, которого вы использовали для получения этих токенов.

Пагинация

Все ресурсы в системе (кроме отельных виджетов аналитики) отображаются использую страницы данных. Для управления переходами по страницам используются следующие параметры GET запроса:
  • page[number] - номер страницы
  • page[size] - размер страницы, по умолчанию - 25, максимальное значение 100 (для каких-то ресурсов 500).
При ответе данных со списком ресурсов к ответу добавляется поле meta, в котором хранятся данные о пагинации, которая используется при выполнении данного запроса:
"meta": {
"page": 1,
"total-pages": 10,
"total-count": 97
}
Пример запроса в пагинацией: получение 2ой страницы оценок с размером 10 записей на страницу:
GET /api/v1/reviews?page[number]=2&page[size]=10
Ответ запроса с пагинацией:
{
"data": [
{
"id": "544b74c2-5095-441a-96ab-2d8ac1a574f0",
"type": "reviews",
// ...
}
// тело ответа, основные данные ресурсов
],
"meta": {
"page": 1,
"total-pages": 10,
"total-count": 97
}
}

Основные запросы

Список коммуникаций (звонки, email, chat и другие)
GET /api/v1/client_interactions
{
"data": [
{
"id": "95e2821e-319a-4989-8a04-519c3174a69b",
"type": "client-interactions",
"attributes": {
"client-interaction-type": "phone_call",
"title": "79872972207",
"duration": 6,
"direction": "outcoming",
"score": 4.5,
"created-at": "2020-06-19T13:20:46.733Z",
"started-at": "2020-06-18T12:21:12.000Z",
"source": null,
"status": null,
"nps": null,
"client-feedback": null,
"integration-uid": "521",
"communication-id": null,
"communication-type": "phone_call",
"text-communication-parts-count": 0,
"client-phone-number": "79872972207",
"email": "",
"metadata": {},
"media-url": "1899"
},
"relationships": {
"operator": {
"data": {
"id": "0b187321-51fa-49ae-9f99-9c64e1f4d963",
"type": "users"
}
},
"client": {
"data": {
"id": "91c41c0f-83d6-438c-823f-9b6a70eabdc0",
"type": "clients"
}
},
"reviews": {
"data": []
},
"text-communication-parts": {
"data": []
}
}
}
],
"meta": {
"page": 1,
"total-pages": 1,
"total-count": 1
}
}
Информацию о коммуникации (звонки, email, chat и другие)
GET /api/v1/client_interactions/:id
Список оценок
GET /api/v1/reviews
Пример запроса: получение оценки по определенному оператору за 1-ю неделю марта
curl -X GET -H @headers.txt 'https://api.prod1.dealapp.io/api/v1/reviews?filters\[operators_ids\]=8804dbdf-fa59-4658-94eb-28283ecada38&filters\[time_from\]=2020-06-01T00:00:00+03:00&filters\[time_to\]=2020-06-08T00:00:00+03:00'
{
"data": [
{
"id": "1329ae64-ad5d-4ea9-a32e-a21bb9433869",
"type": "reviews",
"attributes": {
"created-at": "2020-06-19T13:36:54.852Z",
"started-at": "2020-06-18T12:21:12.000Z"
},
"relationships": {
"reviewer": {
"data": {
"id": "8804dbdf-fa59-4658-94eb-28283ecada38",
"type": "users"
}
},
"client": {
"data": {
"id": "91c41c0f-83d6-438c-823f-9b6a70eabdc0",
"type": "clients"
}
},
"checklist": {
"data": {
"id": "4270707c-bf84-443d-a58e-28a917e566a2",
"type": "checklists"
}
},
"phone-call": {
"data": {
"id": "95e2821e-319a-4989-8a04-519c3174a69b",
"type": "phone-calls"
}
},
"text-communication": {
"data": {
"id": "95e2821e-319a-4989-8a04-519c3174a69b",
"type": "text-communications"
}
},
"client-interaction": {
"data": {
"id": "95e2821e-319a-4989-8a04-519c3174a69b",
"type": "client-interactions"
}
},
"custom-communication": {
"data": null
},
"tasks": {
"data": []
},
"comments": {
"data": [
{
"id": "94b03628-5c38-4704-871d-cdc5d04b85ca",
"type": "comments"
}
]
}
}
}
],
"meta": {
"page": 1,
"total-pages": 1,
"total-count": 1
}
}

Как узнать больше про запросы

Вы можете использовать devtools для работы того, чтобы найти больше запросов, которые будут вам полезны