> For the complete documentation index, see [llms.txt](https://wiki.qolio.ru/qolio-or-baza-znanii/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://wiki.qolio.ru/qolio-or-baza-znanii/integracii/podklyuchenie-po-api/poluchenie-ocenok-operatorov-po-api.md). # Получение оценок операторов по API ## Введение В данной статье мы расскажем, как можно получить информацию об оценках пользователя за определенный промежуток времени: оператор, месяц, оценка, количество оценённых звонков Для начала, вам нужно понимать, как работает авторизация и какие базовые принципы используются в API. Это можно посмотреть в этой статье: [Доступ через API](/qolio-or-baza-znanii/integracii/podklyuchenie-po-api/dostup-cherez-api.md) Для получения всех необходимых данных вам придется делать 2 типа запросов: * Получение ресурсов - например, список пользователей, для того, чтобы сопоставить их ID с результатами в аналитике, список форм оценок и так далее * Получение необходимых данных из аналитики ## Получение ресурсов Для получение списка данных, вам понадобится работать со страницами списков. Вот как это работает ### Пагинация Все ресурсы в системе (кроме отельных виджетов аналитики) отображаются использую страницы данных. Для управления переходами по страницам используются следующие параметры GET запроса: * `page[number]` - номер страницы. * `page[size]` - размер страницы, по умолчанию - 25, максимальное значение 100 (для каких-то ресурсов 500). При ответе данных со списком ресурсов к ответу добавляется поле `meta`, в котором хранятся данные о пагинации, которая используется при выполнении данного запроса: ```json "meta": { "page": 1, "total-pages": 10, "total-count": 97 } ``` Пример запроса в пагинацией: получение 2ой страницы оценок с размером 10 записей на страницу: ```bash GET /api/v1/reviews?page[number]=2&page[size]=10 ``` Ответ запроса с пагинацией: ```json { "data": [ { "id": "544b74c2-5095-441a-96ab-2d8ac1a574f0", "type": "reviews", // ... } // тело ответа, основные данные ресурсов ], "meta": { "page": 1, "total-pages": 10, "total-count": 97 } } ``` #### Список пользователей Все пользователи, которые используют Qolio имеют свой ID внутри системы. У каждого оператора есть роль, которая связана с правами.Для получения списка пользователей, которые общаются с клиентами и являются операторами в системе, можно использовать фильтр with\_role\_permissions со значением can\_perform\_client\_interactions.По умолчанию, система возвращает только активных пользователей. Если вы хотите получить информацию обо всех пользователях, в том числе и неактивными, вы можете применить фильтр with\_inactive со значением true.Пример запроса всех операторов в системе:GET /api/v1/users?filters\[with\_role\_permissions]=can\_perform\_client\_interactions\&filters\[with\_inactive]=true​Пример ответа: ```json { "data": [ { "id": "8583a9f9-ed5f-431c-896c-c47e8d2bda3e", "type": "users", "attributes": { "email": "alex@dealapp.io", "name": "Alex@dealapp.io ", "first-name": null, "last-name": "Alex@dealapp.io", "phone-number": null, "accepted-invitation": false, "integration-uid": "6017104", "avatar-url": null, "active": true, "collisions-on-create": {}, "invitation-sent": false, "last-active-at": null, "prefered-locale": "ru" }, "relationships": { "role": { "data": { "id": "239f9770-373e-434e-928c-1b34189e7c1e", "type": "roles" } }, "unit": { "data": { "id": "e64c5668-eb91-4582-b121-fe14a0e29791", "type": "units" } }, "level": { "data": null }, "origin-integration": { "data": { "id": "9e0323e9-17a2-4780-89e9-1fd7be6941e4", "type": "integrations" } } } } ] } ``` Возможные фильтры: **Фильтры для ресурса users** | Фильтр | Значение | | ----------------------- | ------------------------------------------------------------------------------ | | with\_inactive | вернуть всех пользователей | | active | true / false | | units\_ids | ID отделов внутри Qolio через запятую | | roles\_ids | ID ролей внутри Qolio через запятую | | levels\_ids | ID уровней сотрудников внутри Qolio через запятую | | integration\_uids | ID во внешней системе (operator\_id при передаче данных по API) | | invitation\_status | no\_invitation\_sent / invitation\_sent / invitation\_accepted / user\_blocked | | with\_role\_permissions | | ### Список форм оценок (чек-листов) Список форм оценок необходим для получения ID чек-листов, по которым будет возвращаться аналитика. Endpoint `/api/v2/checklist/definitions` возвращает данные сразу со вложенными ресурсами - списком критериев (questions) и группами. Критерии соединены с группами с помощью ресурса `question-to-group-bindings` Пример запроса: ```json GET /api/v2/checklist/definitions ``` Пример ответа: ```json { "data": [ { "id": "544b74c2-5095-441a-96ab-2d8ac1a574f0", "type": "reviews", "attributes": { "created-at": "2021-07-28T13:39:06.624Z" }, "relationships": { "reviewer": { "data": { "id": "be067ee8-07e6-434a-8c4a-2f397548b894", "type": "users" } }, "client": { "data": null }, "checklist": { "data": { "id": "b699e10c-8194-4055-a691-2ecdb8ddf1a0", "type": "checklists" } }, "operator": { "data": { "id": "c0e8ef30-7238-4855-ad3e-bba651d64b91", "type": "users" } }, "phone-call": { "data": null }, "text-communication": { "data": null }, "client-interaction": { "data": { "id": "d5f27009-3e1d-4eaa-a3eb-69b6237cf49f", "type": "client-interactions" } }, "tasks": { "data": [] }, "comments": { "data": [] } } } ], "included": [ { "id": "82ff2d3c-4bbe-4983-9675-c2d05f259808", "type": "checklists", "attributes": { "metadata": {}, "score": 0, "max-score": 100, "comment": "", "checklist-definition-data": { "name": "unary", "is-weighted": false, "is-groupable": false, "question-groups": [ { "id": "a1e424a1-f942-4e8a-be3e-c813ce9b1dc7", "name": "Критерии без группы" } ], "rating-calculation": "sum" }, "deleted-at": null }, "relationships": { "review": { "data": { "id": "1066f843-b5db-4409-90aa-18c21b82f7d2", "type": "reviews" } }, "checklist-definition": { "data": { "id": "3f62891e-0550-481b-8a20-edc3fefb6a6c", "type": "checklist-definitions" } }, "answers": { "data": [ { "id": "84557aa7-ba5c-4dd7-82b8-8149b48b9126", "type": "checklist-answers" } ] } } } ] } ``` ### Список оценок При необходимости можно получить список всех оценок оператора с оценками. Сейчас это можно сделать через endpoint `/api/v1/reviews`. Чтобы получить вложенный ресурс со значением оценки, вы можете использовать include параметр для ресурса `checklist`, в котором будет хранится значение оценки в полях `score`. В итоге запрос, который будет вытаскивать оценки за март со значениями оценок будет выглядеть следующим образом: ```json GET /api/v1/reviews?include=checklist&filters[review_time_from]=2021-03-01T00:00:00&filters[review_time_to]=2021-03-31T23:59:59 ``` Пример ответа: ```json { "data": [ { "id": "544b74c2-5095-441a-96ab-2d8ac1a574f0", "type": "reviews", "attributes": { "created-at": "2021-07-28T13:39:06.624Z" }, "relationships": { "reviewer": { "data": { "id": "be067ee8-07e6-434a-8c4a-2f397548b894", "type": "users" } }, "client": { "data": null }, "checklist": { "data": { "id": "b699e10c-8194-4055-a691-2ecdb8ddf1a0", "type": "checklists" } }, "operator": { "data": { "id": "c0e8ef30-7238-4855-ad3e-bba651d64b91", "type": "users" } }, "phone-call": { "data": null }, "text-communication": { "data": null }, "client-interaction": { "data": { "id": "d5f27009-3e1d-4eaa-a3eb-69b6237cf49f", "type": "client-interactions" } }, "tasks": { "data": [] }, "comments": { "data": [] } } } ], "included": [ { "id": "82ff2d3c-4bbe-4983-9675-c2d05f259808", "type": "checklists", "attributes": { "metadata": {}, "score": 0, "max-score": 100, "comment": "", "checklist-definition-data": { "name": "unary", "is-weighted": false, "is-groupable": false, "question-groups": [ { "id": "a1e424a1-f942-4e8a-be3e-c813ce9b1dc7", "name": "Критерии без группы" } ], "rating-calculation": "sum" }, "deleted-at": null }, "relationships": { "review": { "data": { "id": "1066f843-b5db-4409-90aa-18c21b82f7d2", "type": "reviews" } }, "checklist-definition": { "data": { "id": "3f62891e-0550-481b-8a20-edc3fefb6a6c", "type": "checklist-definitions" } }, "answers": { "data": [ { "id": "84557aa7-ba5c-4dd7-82b8-8149b48b9126", "type": "checklist-answers" } ] } } } ] } ``` **Список фильтров для ресурса reviews**
НазваниеЗначениеЗначение
review_symbolic_time_rangeНазвание периода времени создания оценки. Возможные значения: today yesterday / last_seven_days / last_thirty_days / this_week / previous_week / this_month и др.
review_time_fromС какого времени создавалась оценка
review_time_toПо какое время создавалась оценка
client_interaction_symbolic_time_rangeНазвание периода времени создания коммуникации, по которой совершалась оценка. Возможные значения: today yesterday / last_seven_days / last_thirty_days / this_week / previous_week / this_month и др.
client_interaction_time_fromС какого времени создания коммуникации, по которой совершалась оценка
client_interaction_time_toПо какое время создания коммуникации, по которой совершалась оценка
checklist_definition_color_zonesВ какую цветовую зону попала оценка
client_interaction_directionНаправление коммуникации (incoming / outcoming)
communication_typeтип коммуникации (phone_call / video / chat / email / ticket / other)
has_tasksУ оценки есть теги
has_commentsУ оценки есть комментарии
units_idsОтдел оценки (список через запятую)
operators_idsСписок ID операторов через запятую
reviewers_idsСписок ID пользователей, которые создали оценку
checklist_definitions_idsСписок ID форм оценок через запятую
comments_rating_flagsС флагами комментария
## Получение аналитики В Qolio есть возможность получать результаты аналитики по API при этом используется endpoint `/api/v1/analytics/widgets` и в параметрах передаются данные о необходимой аналитике и фильтрам. Фильтры используются те же что и для ресурса reviews. Чтобы передать название аналитики, которое нужно вернуть используется параметр `widget_names`, в него передаются названия виджетов через запятую. Возможные варианты названий виджетов будут рассмотрены далее. ### Средняя оценка по формам оценки (чек-листам) Название виджета - checklist\_definition\_average\_score\_by\_operators В этом виджете мы рекомендуем всегда использовать фильтр checklist\_definitions\_ids так как у разных форм оценок могут быть шкалы с разными значениями и средняя оценка по ним будет неинформативной **Список фильтров для виджета "Средняя оценка по сотруднику"** client\_interaction\_time\_to | Название | | ------------------------------------------ | | client\_interaction\_time\_from | | client\_interaction\_symbolic\_time\_range | | client\_interaction\_direction | | units\_ids | | operators\_ids | | checklist\_definitions\_ids | Пример запроса: ```json GET /api/v1/analytics/widgets?widget_names=checklist_definition_average_score_by_operators&filters[client_interaction_symbolic_time_range]=this_month ``` Пример ответа: ``` { "checklist_definition_average_score_by_operators": [ { "value": 0.763636363636364, "name": "Gebo kiersten", "id": "09a1866a-77be-4a61-adae-c46d2102794d" }, { "value": 15.589002267573695, "name": "Hibbits félicie", "id": "0b76341c-ccb5-4fde-86c7-2b19c30f53d7" } ] } ``` В этих данных * `id` ID пользователя внутри qolio * `name` имя пользователя * `value` средняя оценка