Экспорт данных заполнения формы по пользователю

Описание

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

Метод возвращает task_id. Для получения результата нужно получить статус задачи и выгрузить итоговый файл.

URL-адрес

Метод: POST

https://example.com/api/v1.1/forms/fill

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

Параметр	Тип	Пример	Обязательный	Описание
id	int	1	Да, если не указан shortname	Идентификатор формы
shortname	string	"form_6Ven2v7O"	Да, если не указан id	Короткое имя формы
db_id	int	3	Да	Идентификатор базы данных для матчинга
file_format	string	"csv"	Нет	Формат файла: csv или json
matching	string	"email"	Нет	Режим матчинга. Если не указан, определяется автоматически по переданному полю
profile_id	string	"507f1f77bcf86cd799439011"	Нет	ID профиля
email	string	"user@example.com"	Нет	Email пользователя
phone	string	"+79001234567"	Нет	Телефон пользователя
field_name	string	"user_field"	Нет	Имя пользовательского поля для матчинга
field_value	string	"value"	Нет	Значение пользовательского поля

к сведению

Хотя бы одно поле матчинга (profile_id, email, phone, field_name + field_value) должно быть указано.

Режимы матчинга

Значение	Описание
email	Поиск по email
phone	Поиск по телефону
profile_id	Поиск по ID профиля
custom	Поиск по пользовательскому полю (field_name + field_value)

Пример запроса

JSON

{
  "id": 1,
  "db_id": 3,
  "email": "user@example.com",
  "matching": "email",
  "file_format": "csv"
}

XML

<xml>
  <id>1</id>
  <db_id>3</db_id>
  <email>user@example.com</email>
  <matching>email</matching>
  <file_format>csv</file_format>
</xml>

Пример ответа

JSON

{
  "data": {
    "task_id": "550e8400-e29b-41d4-a716-446655440000"
  },
  "error": 0,
  "error_text": "Successful operation"
}

XML

<xml>
  <data>
    <task_id>550e8400-e29b-41d4-a716-446655440000</task_id>
  </data>
  <error>0</error>
  <error_text>Successful operation</error_text>
</xml>

Параметры ответа

Параметр	Тип	Описание
error	int	Код ошибки
error_text	string	Текст ошибки
data	object	Объект с данными ответа

Объект data

Параметр	Тип	Описание
task_id	string	Идентификатор асинхронной задачи для получения данных заполнения

Шаг 2. Проверка статуса задачи и получение ссылки

URL-адрес

Метод: POST

https://example.com/api/v1.1/tasks/status

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

Параметр	Тип	Пример	Обязательный	Описание
task_id	string	"550e8400-e29b-41d4-a716-446655440000"	Да	Идентификатор задачи из шага 1

Пример запроса

JSON

{
  "task_id": "550e8400-e29b-41d4-a716-446655440000"
}

XML

<xml>
  <task_id>550e8400-e29b-41d4-a716-446655440000</task_id>
</xml>

Пример ответа

JSON

{
  "data": {
    "status": "completed",
    "progress": 100,
    "result": {
      "form_id": 1,
      "total": 1,
      "url": "abCDefghIklMnop57498257/1_20002_form_export.zip"
    }
  },
  "error": 0,
  "error_text": "Successful operation"
}

XML

<xml>
  <data>
    <status>completed</status>
    <progress>100</progress>
    <result>
      <form_id>1</form_id>
      <total>1</total>
      <url>abCDefghIklMnop57498257/1_20002_form_export.zip</url>
    </result>
  </data>
  <error>0</error>
  <error_text>Successful operation</error_text>
</xml>

Параметры ответа

Параметр	Тип	Описание
status	string	Статус задачи (completed — задача выполнена)
progress	int	Прогресс выполнения в процентах
result	object	Объект с результатами экспорта. См. result
error	int	Код ошибки
error_text	string	Текст ошибки

Объект result

Параметр	Тип	Описание
form_id	int	Идентификатор формы
total	int	Общее количество записей о заполнениях
url	string	Зашифрованный путь к файлу с данными

Шаг 3. Загрузка файла

Для загрузки файла необходимо отправить GET запрос по ссылке, составленной из базового URL платформы, префикса сущности и значения параметра url из ответа шага 2:

https://example.com/api/download/forms/ + значение url

Например:

https://example.com/api/download/forms/abCDefghIklMnop57498257/1_20002_form_export.zip

где:

• https://example.com — домен платформы
• api/download/forms/ — фиксированный префикс для выгрузки данных форм
• abCDefghIklMnop57498257/1_20002_form_export.zip — значение параметра url из ответа шага 2 (зашифрованный путь и имя файла)

Запрос должен содержать заголовок авторизации Authorization: Bearer <token>.