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

Сервис Qolio построен на основе клиент-серверной архитектуры и ничего не мешает получить доступ к информации вашего аккаунта через API.

API можно использовать для множества кейсов, таких как:

• Получение результатов проверок для операторов

• Автоматическая добавление и настройка пользователей

Главный API endpoint находится по адресу: https://api.prod1.dealapp.io.

Принцип Построения

API построен на основе спецификаций JSON API (https://jsonapi.org/). Вы можете подчеркнуть дополнительные знание по этому подходу в следующих статьях:

• https://habr.com/ru/company/oleg-bunin/blog/433322/

• https://www.youtube.com/watch?v=iwLhXmqROnw

Параметры 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 для работы того, чтобы найти больше запросов, которые будут вам полезны