Simpleforms Public API

https://api.simpleforms.ru/

API позволяет клиентам взаимодействовать с системой, получать данные, управлять задачами и интегрировать Simpleforms с другими приложениями.

Ключ API можно получить в разделе “Настройки компании” (раздел доступен пользователям с ролью Администратор).

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

Аутентификация осуществляется через заголовок X-API-Key. Этот заголовок обязателен для всех запросов.

GET /api/projects HTTP/1.1
Host: example.com
X-API-Key: your_api_key_here

Формат дат

Все даты в запросах и ответах должны быть в формате RFC 3339 (например, 2017-07-21T17:32:28Z), где время указывается в UTC с суффиксом Z.

Проекты (Projects)

Список проектов

GET /api/projects

Получить постраничный список проектов.

Параметры запроса:

pageSize (integer, optional): Количество элементов на одной странице результатов. По умолчанию: 10.
pageIndex (integer, optional): Индекс страницы результатов. По умолчанию: 0.
api-version (string, required): Версия API в формате 'major.minor'. Пример: "1.0".
status (integer, optional): Статус проекта. По умолчанию: <не указано>. Возможные значения:
- 0: initial
- 1: inprogress
- 2: archive
- 3: temporary
- 4: testing
- 5: insettings
- 6: changestatuses
deadlineFrom (string, optional): Плановая дата завершения проекта 'от' UTC. Формат: RFC 3339. Пример: 2017-07-21T17:32:28Z. По умолчанию: <не указано>
deadlineTo (string, optional): Плановая дата завершения проекта 'до' UTC. Формат: RFC 3339. Пример: 2017-07-21T17:32:28Z. По умолчанию: <не указано>

Пример ответа (200 OK):

{
  "data": [
    {
      "id": "uuid", // Идентификатор проекта
      "name": "string", // Название проекта
      "number": 0, // Номер проекта
      "currentCount": 0, // Текущее количество целевых анкет
      "count": 0, // Заданное количество целевых анкет
      "status": 0, // Статус проекта
      "deadline": "2017-07-21T17:32:28Z" // Плановая дата завершения проекта
    }
  ],
  "totalCount": 0, // Всего записей
  "totalPages": 0 // Всего страниц
}

Коды ошибок:

400 Bad Request: Неверный запрос. Возвращается объект ProblemDetails:
{ "type": "string", "title": "string", "status": 400, "detail": "string", "instance": "string" }
401 Unauthorized: Отсутствует или неверный API-ключ.
403 Forbidden: Недостаточно прав для доступа.

Информация по проекту

GET /api/projects/{id}

Получить информацию по проекту.

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

id (string, required): Идентификатор проекта (UUID).

Параметры запроса:

api-version (string, required): Версия API в формате 'major.minor'. Пример: "1.0".

Пример ответа (200 OK):

{
  "id": "uuid", // Идентификатор проекта
  "name": "string", // Название проекта
  "number": 0, // Номер проекта
  "currentCount": 0, // Текущее количество целевых анкет
  "count": 0, // Заданное количество целевых анкет
  "status": 0, // Статус проекта
  "deadline": "2017-07-21T17:32:28Z" // Плановая дата завершения проекта
}

Коды ошибок:

400 Bad Request: Неверный формат идентификатора. Возвращается объект ProblemDetails.
401 Unauthorized: Отсутствует или неверный API-ключ.
403 Forbidden: Недостаточно прав для доступа.
404 Not Found: Проект с указанным идентификатором не найден.

Глобальные заказы (GlobalOrders)

Список глобальных заказов

GET /api/globalorders

Получить постраничный список заказов.

Параметры запроса:

pageSize (integer, optional): Количество элементов на одной странице результатов. По умолчанию: 10.
pageIndex (integer, optional): Индекс страницы результатов. По умолчанию: 0.
api-version (string, required): Версия API в формате 'major.minor'. Пример: "1.0".
status (integer, optional): Статус заказа. По умолчанию: <не указано>. Возможные значения:
- 0: initial
- 1: inprogress
- 2: archive
- 3: insettings
projectId (string, optional): Идентификатор проекта (UUID). По умолчанию: <не указано>

Пример ответа (200 OK):

{
  "data": [
    {
      "id": "uuid", // Идентификатор заказа
      "projectId": "uuid", // Идентификатор проекта
      "currentCount": 0, // Текущее количество целевых анкет
      "count": 0, // Заданное количество целевых анкет
      "status": 0, // Статус заказа
      "isOwn": true, // Признак собственного заказа
      "isCawi": true, // Признак CAWI заказа
      "partner": "string", // Партнер
      "partnerId": "uuid" // Идентификатор партнера
    }
  ],
  "totalCount": 0, // Всего записей
  "totalPages": 0 // Всего страниц
}

Коды ошибок:

400 Bad Request: Неверный запрос. Возвращается объект ProblemDetails.
401 Unauthorized: Отсутствует или неверный API-ключ.
403 Forbidden: Недостаточно прав для доступа.

Информация по глобальному заказу

GET /api/globalorders/{id}

Получить информацию по заказу.

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

id (string, required): Идентификатор заказа (UUID).

Параметры запроса:

api-version (string, required): Версия API в формате 'major.minor'. Пример: "1.0".

Пример ответа (200 OK):

{
  "id": "uuid", // Идентификатор заказа
  "projectId": "uuid", // Идентификатор проекта
  "currentCount": 0, // Текущее количество целевых анкет
  "count": 0, // Заданное количество целевых анкет
  "status": 0, // Статус заказа
  "isOwn": true, // Признак собственного заказа
  "isCawi": true, // Признак CAWI заказа
  "partner": "string", // Партнер
  "partnerId": "uuid" // Идентификатор партнера
}

Коды ошибок:

400 Bad Request: Неверный формат идентификатора. Возвращается объект ProblemDetails.
401 Unauthorized: Отсутствует или неверный API-ключ.
403 Forbidden: Недостаточно прав для доступа.
404 Not Found: Заказ с указанным идентификатором не найден.

Локальные заказы (LocalOrders)

Список локальных заказов

GET /api/globalorders/{id}/localorders

Получить постраничный список заданий.

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

id (string, required): Идентификатор заказа (UUID).

Параметры запроса:

pageSize (integer, optional): Количество элементов на одной странице результатов. По умолчанию: 10.
pageIndex (integer, optional): Индекс страницы результатов. По умолчанию: 0.
api-version (string, required): Версия API в формате 'major.minor'. Пример: "1.0".
status (integer, optional): Статус задания. По умолчанию: <не указано>. Возможные значения:
- 0: initial
- 1: inprogress
- 2: archive
- 3: isready
term (string, optional): Строка для поиска. По умолчанию: <не указано>

Пример ответа (200 OK):

{
  "data": [
    {
      "id": "uuid", // Идентификатор задания
      "globalOrderId": "uuid", // Идентификатор заказа
      "count": 0, // Заданное количество целевых анкет
      "status": 0, // Статус задания
      "interviewer": "string", // Интервьюер
      "currentCount": 0 // Текущее количество целевых анкет
    }
  ],
  "totalCount": 0, // Всего записей
  "totalPages": 0 // Всего страниц
}

Коды ошибок:

400 Bad Request: Неверный запрос. Возвращается объект ProblemDetails.
401 Unauthorized: Отсутствует или неверный API-ключ.
403 Forbidden: Недостаточно прав для доступа.
404 Not Found: Заказ с указанным идентификатором не найден.

Информация по локальному заказу

GET /api/localorders/{id}

Получить информацию по заданию.

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

id (string, required): Идентификатор задания (UUID).

Параметры запроса:

api-version (string, required): Версия API в формате 'major.minor'. Пример: "1.0".

Пример ответа (200 OK):

{
  "id": "uuid", // Идентификатор задания
  "globalOrderId": "uuid", // Идентификатор заказа
  "count": 0, // Заданное количество целевых анкет
  "status": 0, // Статус задания
  "interviewer": "string", // Интервьюер
  "currentCount": 0 // Текущее количество целевых анкет
}

Коды ошибок:

400 Bad Request: Неверный формат идентификатора. Возвращается объект ProblemDetails.
401 Unauthorized: Отсутствует или неверный API-ключ.
403 Forbidden: Недостаточно прав для доступа.
404 Not Found: Задание с указанным идентификатором не найдено.

Отчеты (Reports)

Список отчетов

GET /api/reports

Получить постраничный список отчетов.

Параметры запроса:

pageSize (integer, optional): Количество элементов на одной странице результатов. По умолчанию: 10.
pageIndex (integer, optional): Индекс страницы результатов. По умолчанию: 0.
api-version (string, required): Версия API в формате 'major.minor'. Пример: "1.0".
isFailed (boolean, optional): Флаг, указывающий, завершено ли формирование отчета с ошибкой. По умолчанию: <не указано>
isCompleted (boolean, optional): Флаг, указывающий, завершено ли формирование отчета успешно. По умолчанию: <не указано>
createdOnUtcFrom (string, optional): Дата/время создания запроса для формирования отчета 'от' UTC. Формат: RFC 3339. Пример: 2017-07-21T17:32:28Z. По умолчанию: <не указано>
createdOnUtcTo (string, optional): Дата/время создания запроса для формирования отчета 'до' UTC. Формат: RFC 3339. Пример: 2017-07-21T17:32:28Z. По умолчанию: <не указано>

Пример ответа (200 OK):

{
  "data": [
    {
      "id": "uuid", // Идентификатор отчёта
      "isFailed": false, // Отчёт сформирован с ошибкой
      "isCompleted": true, // Отчёт сформирован успешно
      "createdOnUtc": "2017-07-21T17:32:28Z", // Дата/время создания запроса отчёта
      "type": 0, // Тип отчёта
      "name": "string" // Название отчёта
    }
  ],
  "totalCount": 0, // Всего записей
  "totalPages": 0 // Всего страниц
}

Коды ошибок:

400 Bad Request: Неверный запрос. Возвращается объект ProblemDetails.
401 Unauthorized: Отсутствует или неверный API-ключ.
403 Forbidden: Недостаточно прав для доступа.

Информация по отчету

GET /api/reports/{id}

Получить информацию по отчету.

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

id (string, required): Идентификатор отчета (UUID).

Параметры запроса:

api-version (string, required): Версия API в формате 'major.minor'. Пример: "1.0".

Пример ответа (200 OK):

{
  "links": ["string"], // Ссылки, полученные в результате генерации отчёта
  "id": "uuid", // Идентификатор отчёта
  "isFailed": false, // Отчёт сформирован с ошибкой
  "isCompleted": true, // Отчёт сформирован успешно
  "createdOnUtc": "2017-07-21T17:32:28Z", // Дата/время создания запроса отчёта
  "type": 0, // Тип отчёта
  "name": "string" // Название отчёта
}

Коды ошибок:

400 Bad Request: Неверный формат идентификатора. Возвращается объект ProblemDetails.
401 Unauthorized: Отсутствует или неверный API-ключ.
403 Forbidden: Недостаточно прав для доступа.
404 Not Found: Отчет с указанным идентификатором не найден.

Создание отчетов

Создание отчета по анкетам в формате DocX

POST /api/reports/surveyReport/toWord

Создать отчет по анкетам в формате DocX, возвращает идентификатор.

Параметры запроса:

api-version (string, required): Версия API в формате 'major.minor'. Пример: "1.0".

Тело запроса:

includeServiceData (boolean, optional): Включать служебные данные. По умолчанию: true
geolocationFormat (integer, optional): Формат геолокации. Значения определяются системой. По умолчанию: <координаты>
includeIncompleteSurveys (boolean, optional): Включать незавершенные анкеты. По умолчанию: true
includeQuestionDuration (boolean, optional): Включать длительность вопросов. По умолчанию: false
questionTiming (string, optional): Время заполнения. По умолчанию: <не указано>
locale (string, optional): Язык выгрузки. По умолчанию: <не указано>
objectId (string, required): Идентификатор сущности (UUID).
entityType (integer, optional): Тип сущности. Значения определяются системой. По умолчанию: <проект>
includeScreenerSurveys (boolean, optional): Включать нецелевые анкеты. По умолчанию: true
includeDeclinedSurveys (boolean, optional): Включать забракованные анкеты. По умолчанию: true
includeCommercialSecret (boolean, optional): Включать анкеты с коммерческой тайной. По умолчанию: true
timeZone (string, optional): Часовой пояс в формате ±HH:MM:SS[.fffffff]. Пример: "-05:00:00". По умолчанию: <не указано>
startReportDate (string, optional): Начало периода выгрузки. Формат: RFC 3339. Пример: 2017-07-21T17:32:28Z. По умолчанию: <не указано>
endReportDate (string, optional): Конец периода выгрузки. Формат: RFC 3339. Пример: 2017-07-21T17:32:28Z. По умолчанию: <не указано>
startNumber (integer, optional): Начало диапазона номеров анкет. По умолчанию: <не указано>
endNumber (integer, optional): Конец диапазона номеров анкет. По умолчанию: <не указано>

Пример тела запроса:

{
  "includeServiceData": true,
  "geolocationFormat": 0,
  "includeIncompleteSurveys": false,
  "includeQuestionDuration": true,
  "questionTiming": "string",
  "locale": "string",
  "objectId": "uuid",
  "entityType": 0,
  "includeScreenerSurveys": false,
  "includeDeclinedSurveys": true,
  "includeCommercialSecret": false,
  "timeZone": "-05:00:00",
  "startReportDate": "2017-07-21T17:32:28Z",
  "endReportDate": "2017-07-21T17:32:28Z",
  "startNumber": 1,
  "endNumber": 100
}

Пример ответа (200 OK):

{
  "id": "uuid" // Идентификатор созданного отчета
}

Коды ошибок:

400 Bad Request: Неверный запрос. Возвращается объект ProblemDetails.
401 Unauthorized: Отсутствует или неверный API-ключ.
403 Forbidden: Недостаточно прав для доступа.

Создание отчета по анкетам в формате Excel

POST /api/reports/surveyReport/toExcel

Создать отчет по анкетам в формате Excel, возвращает идентификатор.

Параметры запроса:

api-version (string, required): Версия API в формате 'major.minor'. Пример: "1.0".

Тело запроса:

templateVersion (integer, optional): Версия шаблона. По умолчанию: <текущая версия, указанная в проекте>
includeQuestionLog (boolean, optional): Включать лог вопросов. По умолчанию: true
analysisMethod (integer, optional): Метод анализа ответов. Значения определяются системой. По умолчанию: <дихотомия>
includeQuestionText (boolean, optional): Включать текст вопросов. По умолчанию: true
answerExportFormat (integer, optional): Формат выгрузки ответов. Значения определяются системой. По умолчанию: <кодами>
codeIdentification (integer, optional): Тип идентификации кода. Значения определяются системой. По умолчанию: <Id>
otherOptionExport (integer, optional): Обработка варианта "другое". Значения определяются системой. По умолчанию: <Один столбец>
multipleChoiceExport (integer, optional): Обработка множественного выбора. Значения определяются системой. По умолчанию: <Один столбец>
includeServiceData (boolean, optional): Включать служебные данные. По умолчанию: true
geolocationFormat (integer, optional): Формат геолокации. Значения определяются системой. По умолчанию: <координаты>
includeIncompleteSurveys (boolean, optional): Включать незавершенные анкеты. По умолчанию: true
includeQuestionDuration (boolean, optional): Включать длительность вопросов. По умолчанию: false
questionTiming (string, optional): Время заполнения. По умолчанию: <не указано>
locale (string, optional): Язык выгрузки. По умолчанию: <не указано>
objectId (string, required): Идентификатор сущности (UUID).
entityType (integer, optional): Тип сущности. Значения определяются системой. По умолчанию: <проект>
includeScreenerSurveys (boolean, optional): Включать нецелевые анкеты. По умолчанию: true
includeDeclinedSurveys (boolean, optional): Включать забракованные анкеты. По умолчанию: true
includeCommercialSecret (boolean, optional): Включать анкеты с коммерческой тайной. По умолчанию: true
timeZone (string, optional): Часовой пояс в формате ±HH:MM:SS[.fffffff]. Пример: "-05:00:00". По умолчанию: <не указано>
startReportDate (string, optional): Начало периода выгрузки. Формат: RFC 3339. Пример: 2017-07-21T17:32:28Z. По умолчанию: <не указано>
endReportDate (string, optional): Конец периода выгрузки. Формат: RFC 3339. Пример: 2017-07-21T17:32:28Z. По умолчанию: <не указано>
startNumber (integer, optional): Начало диапазона номеров анкет. По умолчанию: <не указано>
endNumber (integer, optional): Конец диапазона номеров анкет. По умолчанию: <не указано>

Пример тела запроса:

{
  "templateVersion": 1,
  "includeQuestionLog": true,
  "analysisMethod": 0,
  "includeQuestionText": false,
  "answerExportFormat": 0,
  "codeIdentification": 0,
  "otherOptionExport": 0,
  "multipleChoiceExport": 0,
  "includeServiceData": true,
  "geolocationFormat": 0,
  "includeIncompleteSurveys": false,
  "includeQuestionDuration": true,
  "questionTiming": "string",
  "locale": "string",
  "objectId": "uuid",
  "entityType": 0,
  "includeScreenerSurveys": false,
  "includeDeclinedSurveys": true,
  "includeCommercialSecret": false,
  "timeZone": "-05:00:00",
  "startReportDate": "2017-07-21T17:32:28Z",
  "endReportDate": "2017-07-21T17:32:28Z",
  "startNumber": 1,
  "endNumber": 100
}

Пример ответа (200 OK):

{
  "id": "uuid" // Идентификатор созданного отчета
}

Коды ошибок:

400 Bad Request: Неверный запрос. Возвращается объект ProblemDetails.
401 Unauthorized: Отсутствует или неверный API-ключ.
403 Forbidden: Недостаточно прав для доступа.

Создание отчета по анкетам в формате Json

POST /api/reports/surveyReport/toJson

Создать отчет по анкетам в формате Json, возвращает идентификатор.

Параметры запроса и тело запроса аналогичны /api/reports/surveyReport/toExcel.

Пример ответа (200 OK):

{
  "id": "uuid" // Идентификатор созданного отчета
}

Коды ошибок:

400 Bad Request: Неверный запрос. Возвращается объект ProblemDetails.
401 Unauthorized: Отсутствует или неверный API-ключ.
403 Forbidden: Недостаточно прав для доступа.

Создание отчета по анкетам в формате SPSS Sav

POST /api/reports/surveyReport/toSpssSav

Создать отчет по анкетам в формате SPSS Sav, возвращает идентификатор.

Параметры запроса:

api-version (string, required): Версия API в формате 'major.minor'. Пример: "1.0".

Тело запроса:

templateVersion (integer, optional): Версия шаблона. По умолчанию: <текущая версия, указанная в проекте>
decimalSeparator (integer, optional): Десятичный разделитель. Значения определяются системой. По умолчанию: <,>
includeQuestionLog (boolean, optional): Включать лог вопросов. По умолчанию: true
operatingSystem (integer, optional): Операционная система. Значения определяются системой. По умолчанию: <Windows>
encoding (integer, optional): Кодировка. Значения определяются системой. По умолчанию: <ASCII>
cyrillicSupport (boolean, optional): Поддержка кириллицы. По умолчанию: true
partnerCodeFormat (integer, optional): Формат кода партнера. Значения определяются системой. По умолчанию: <число (1)>
missingQuestions (string, optional): Пропущенные вопросы. По умолчанию: "99999"
missingValues (string, optional): Пропущенные значения. По умолчанию: "99999"
multipleChoiceInCheck (integer, optional): Множественный выбор в вариантах. Значения определяются системой. По умолчанию: <дихотомия>
multipleChoiceInNet (integer, optional): Множественный выбор в сетке. Значения определяются системой. По умолчанию: <дихотомия>
dateExport (integer, optional): Формат выгрузки даты. Значения определяются системой. По умолчанию: <несколько столбцов (1)>
dateDayPostfix (string, optional): Приписка даты (день). По умолчанию: "DAY"
dateMonthPostfix (string, optional): Приписка даты (месяц). По умолчанию: "MONTH"
dateYearPostfix (string, optional): Приписка даты (год). По умолчанию: "YEAR"
dateHoursPostfix (string, optional): Приписка даты (час). По умолчанию: "HOURS"
dateMinutesPostfix (string, optional): Приписка даты (минуты). По умолчанию: "MINUTES"
otherOptionPostfix (string, optional): Приписка для варианта "другое". По умолчанию: "TEXT"
exportCodesForOther (boolean, optional): Выгружать коды для варианта "другое". По умолчанию: true
durationPostfix (string, optional): Приписка для длительности. По умолчанию: "Time"
postfixSeparator (integer, optional): Разделитель приписок. Значения определяются системой. По умолчанию: <точка (1)>
spssVersion (integer, optional): Версия SPSS. Значения определяются системой. По умолчанию: <от 16 (1)>
integerVariableLength (integer, optional): Длина переменных для чисел. По умолчанию: 8
stringVariableLength (integer, optional): Длина переменных для строк. По умолчанию: 255
codeIdentification (integer, optional): Тип идентификации кода. Значения определяются системой. По умолчанию: <Id>
includeServiceData (boolean, optional): Включать служебные данные. По умолчанию: true
geolocationFormat (integer, optional): Формат геолокации. Значения определяются системой. По умолчанию: <координаты>
includeIncompleteSurveys (boolean, optional): Включать незавершенные анкеты. По умолчанию: true
includeQuestionDuration (boolean, optional): Включать длительность вопросов. По умолчанию: false
questionTiming (string, optional): Время заполнения. По умолчанию: <не указано>
locale (string, optional): Язык выгрузки. По умолчанию: <не указано>
objectId (string, required): Идентификатор сущности (UUID).