Импорт через интеграции и API

Используйте импорт для подготовленного набора записей, а не для аварийного восстановления системы. Он применяет обычные проверки полей, прав и бизнес-правил.

Подготовить настройку

В интеграциях выберите загрузку файлов. Для публичного API сначала создайте настройку POST /api/v1/import-definitions: источник, тип, формат, режим и сопоставление колонок. Поддерживаются CSV и JSON. Excel в браузерном переносе данных — отдельный сценарий; публичный import endpoint не принимает XLSX.

Режим	Поведение
CREATE_ONLY	Добавить новые; ранее связанные записи пропустить
UPDATE_ONLY	Обновить уже связанные; неизвестные пропустить
UPSERT	Создать новые и обновить связанные

У каждой строки нужен устойчивый внешний идентификатор. В настройке API укажите resolver: {"externalIdField":"externalId"} — имя колонки с этим идентификатором. Повторная загрузка находит запись по связи с источником и externalId, не автоматически по номеру заявки. Смена идентификатора или источника может создать другую запись.

Проверить до записи

Загрузка кнопками интерфейса

1. На вкладке «Загрузка из файлов» нажмите «Настроить загрузку».
2. Укажите название, вид записей, CSV или JSON, режим и столбец уникального номера источника.
3. Через «Добавить поле» сопоставьте заголовок с полем системы. При необходимости выберите преобразование: пробелы по краям, число, да / нет. «Убрать» удаляет только строку сопоставления. Смена вида записей очищает сопоставление — настройте его заново.
4. Сохраните настройку, затем нажмите «Выбрать файл». Здесь файл ограничен 5 МБ; CSV — UTF-8 с запятой, JSON — массив записей. Ограничения публичного API ниже отличаются.
5. Раскройте «Соответствие полей файла», нажмите «Проверить файл». При ошибках исправьте файл и снова выберите его.
6. После проверки без ошибок станет доступна «Загрузить в NGENSIA». Подтвердите запись и сверьте все счётчики. Интерфейс показывает до первых 50 ошибок, а не обещает отсутствие остальных.

Новый файл отменяет подтверждение предыдущей проверки. Этот экран не является расширенным «Переносом данных»: выбора листа XLSX, проекта миграции и кнопки повтора только ошибок здесь нет.

Через API

{
  "definitionId": "DEFINITION_ID",
  "content": "externalId,subject\nexternal-1,Учебное обращение",
  "dryRun": true
}

Отправьте тело в POST /api/v1/imports/run. Пример предполагает настроенное сопоставление subject и все нужные обязательные поля. Сначала изучите ошибки проверки, исправьте файл, затем запускайте без dryRun.

Успешный dryRun не гарантирует успешную запись: он не выполняет канонические команды изменения, поэтому часть прав и бизнес-проверок применяется только в настоящем запуске. Обязательно проверьте его результат по строкам.

Проверить результат

Сохраните ID запуска. GET /api/v1/import-runs/RUN_ID возвращает результат и сведения о строках. Сверьте succeeded, failed и skipped; HTTP 201 не означает, что все строки успешно загружены.

Каждая строка обрабатывается в отдельной транзакции. Ошибка одной строки не отменяет уже успешно обработанные. Перед повтором всего файла проверьте режим, источник и внешние ID — универсальный Idempotency-Key для imports/run не предусмотрен.

Ограничения

• До 10 000 строк, content до 10 MiB; общий HTTP JSON также ограничен 10 MiB.
• Для управления настройкой нужны imports:write и import.manage, для запуска — imports:write и import.execute, для результата — imports:read и import.manage.
• Импорт связанных объектов требует продуманного порядка и проверки ссылок; успешная загрузка файла не доказывает полную миграцию.

Связанные статьи

• Справочник импорта
• Экспорт
• Ошибки и повторы