Справочник API Интеграций

Этот документ описывает, как взаимодействовать с API Интеграций Goodbridge для получения данных респондентов по вашим проектам.

Обзор

API Интеграций позволяет пользователям платформы программно экспортировать данные респондентов из своих проектов в JSON формате.

Base URL: https://bk.analysis.goodbridge.kz/integrations

Аутентификация

Все запросы к API Интеграций требуют OAuth2 Bearer Token.

Получите токен доступа (access token) в сервисе аутентификации Goodbridge.
Включите токен в заголовок Authorization ваших HTTP-запросов:

Authorization: Bearer <ваш_токен_доступа>

Примечание: Для использования этого эндпоинта функция Выгрузка данных через API должна быть доступна в тарифном плане вашего рабочего пространства.

Получение данных респондентов

Получение отфильтрованных и разбитых по страницам данных респондентов для конкретного проекта.

Эндпоинт

GET /{project_id}/respondents

Параметры пути

Параметр	Тип	Описание
`project_id`	string	Уникальный ID проекта.

Параметры запроса (Query Parameters)

Параметр	Тип	Обязательно	Описание
`page`	integer	Да	Номер страницы (минимум: 1).
`page_size`	integer	Да	Количество элементов на странице (1-100).
`display_lang_code`	string	Да	Язык отображения данных: `ru`, `kz`, `kk`, `en`, `fr`, `de`, `tr`.
`filters.starttime_ge`	string	Нет	Фильтр респондентов, начавших после этого времени (формат ISO 8601, например, `2023-01-01T12:00:00`).
`filters.endtime_le`	string	Нет	Фильтр респондентов, закончивших до этого времени (формат ISO 8601).
`filters.classificator`	string	Нет	Фильтр по значению классификатора.
`filters.classificator_2`	string	Нет	Фильтр по значению вторичного классификатора.
`filters.lang_code`	string	Нет	Фильтр по языку заполнения формы (`ru`, `kz` и т.д.).
`filters.channel_id`	string	Нет	Фильтр по ID конкретного канала (коллектора).
`sorting.endtime`	string	Нет	Сортировка результатов по времени завершения: `asc` (по возрастанию) или `desc` (по убыванию).

Пример запроса (cURL)

curl -X GET "https://bk.analysis.goodbridge.kz/integrations/PROJ123/respondents?page=1&page_size=20&output_format=json&display_lang_code=ru" \
     -H "Authorization: Bearer ВАШ_ТОКЕН_ДОСТУПА"

Формат ответа

Ответ будет иметь следующую структуру:

{
  "page": 1,
  "page_size": 20,
  "total": 150,
  "respondents": [
    {
      "info": {
        "id": 1001,
        "collector_id": "CHAN789",
        "collector_name": "Веб-опрос",
        "is_manual_input": false,
        "starttime": "2023-10-27T10:00:00Z",
        "endtime": "2023-10-27T10:05:00Z",
        "finish_reason": 1,
        "classificator": null,
        "classificator_2": null,
        "lang": "ru",
        "created_at": "2023-10-27T10:05:01Z",
        "updated_at": "2023-10-27T10:05:01Z"
      },
      "questions": [
        {
          "id": "Q1",
          "title": "Каков ваш уровень удовлетворенности?",
          "type": "scale",
          "answers": [
            {
              "id": "A1_1",
              "label": "Высокий",
              "answer": 9,
              "comment": null,
              "data_type": "number"
            }
          ],
          "sub_questions": [],
          "params": {
            "date_format": null
          }
        }
      ]
    }
  ]
}

Коды ошибок

Код состояния	Описание
`401 Unauthorized`	Неверный или отсутствующий токен аутентификации.
`403 Forbidden`	Токен доступа истек, неактивен или функция `api_export_data` недоступна для вашего тарифа.
`404 Not Found`	Рабочее пространство или проект не найдены.
`422 Unprocessable Entity`	Ошибка валидации (например, отсутствуют обязательные параметры или указаны недопустимые значения).
`429 Too Many Requests`	Превышен лимит запросов.

Получение данных респондента