# Получение оценок операторов по 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**

<table><thead><tr><th>Название</th><th>Значение</th><th data-hidden>Значение</th><th data-hidden></th></tr></thead><tbody><tr><td>review_symbolic_time_range</td><td>Название периода времени создания оценки. Возможные значения: today yesterday / last_seven_days / last_thirty_days / this_week / previous_week / this_month и др.</td><td></td><td></td></tr><tr><td>review_time_from</td><td>С какого времени создавалась оценка</td><td></td><td></td></tr><tr><td>review_time_to</td><td>По какое время создавалась оценка</td><td></td><td></td></tr><tr><td>client_interaction_symbolic_time_range</td><td>Название периода времени создания коммуникации, по которой совершалась оценка. Возможные значения: today yesterday / last_seven_days / last_thirty_days / this_week / previous_week / this_month и др.</td><td></td><td></td></tr><tr><td>client_interaction_time_from</td><td>С какого времени создания коммуникации, по которой совершалась оценка</td><td></td><td></td></tr><tr><td>client_interaction_time_to</td><td>По какое время создания коммуникации, по которой совершалась оценка</td><td></td><td></td></tr><tr><td>checklist_definition_color_zones</td><td>В какую цветовую зону попала оценка</td><td></td><td></td></tr><tr><td>client_interaction_direction</td><td>Направление коммуникации (incoming / outcoming)</td><td></td><td></td></tr><tr><td>communication_type</td><td>тип коммуникации (phone_call / video / chat / email / ticket / other)</td><td></td><td></td></tr><tr><td>has_tasks</td><td>У оценки есть теги</td><td></td><td></td></tr><tr><td>has_comments</td><td>У оценки есть комментарии</td><td></td><td></td></tr><tr><td>units_ids</td><td>Отдел оценки (список через запятую)</td><td></td><td></td></tr><tr><td>operators_ids</td><td>Список ID операторов через запятую</td><td></td><td></td></tr><tr><td>reviewers_ids</td><td>Список ID пользователей, которые создали оценку</td><td></td><td></td></tr><tr><td>checklist_definitions_ids</td><td>Список ID форм оценок через запятую</td><td></td><td></td></tr><tr><td>comments_rating_flags</td><td>С флагами комментария</td><td></td><td></td></tr></tbody></table>

## Получение аналитики

В Qolio есть возможность получать результаты аналитики по API при этом используется endpoint `/api/v1/analytics/widgets` и в параметрах передаются данные о необходимой аналитике и фильтрам. Фильтры используются те же что и для ресурса reviews. Чтобы передать название аналитики, которое нужно вернуть используется параметр `widget_names`, в него передаются названия виджетов через запятую. Возможные варианты названий виджетов будут рассмотрены далее.

### Средняя оценка по формам оценки (чек-листам)

Название виджета - checklist\_definition\_average\_score\_by\_operators

В этом виджете мы рекомендуем всегда использовать фильтр checklist\_definitions\_ids так как у разных форм оценок могут быть шкалы с разными значениями и средняя оценка по ним будет неинформативной

**Список фильтров для виджета "Средняя оценка по сотруднику"**

client\_interaction\_time\_to&#x20;

| Название                                   |
| ------------------------------------------ |
| 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` средняя оценка


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://wiki.qolio.ru/qolio-or-baza-znanii/integracii/podklyuchenie-po-api/poluchenie-ocenok-operatorov-po-api.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.