Асинхронный импорт
Интерфейс асинхронного импорта — путь для исторических загрузок и любых пакетов, превышающих ограничение пакетной загрузки NDJSON в десять тысяч строк или десять мегабайт. Процесс двухфазный: вы описываете, что собираетесь загрузить, получаете ограниченный по времени URL загрузки, выполняете PUT файла прямо на него, а затем просите платформу подтвердить его. Далее обработчик потоково читает файл строка за строкой, фиксируя ошибки по строкам и сообщая о ходе выполнения через эндпоинт статуса.
Маршруты на этой странице — точки входа в процесс импорта для кредитного домена.
Жизненный цикл
Жизненный цикл включает семь состояний. Большинство рабочих загрузок проходят путь pending_upload → queued → processing → succeeded; остальные состояния отражают сценарии сбоев.
| Состояние | Значение |
|---|---|
pending_upload | Строка импорта существует; ограниченный по времени URL загрузки активен; платформа ещё не видела файл. |
queued | Подтверждение прошло успешно; обработчик ещё не взял файл в работу. |
processing | Обработчик потоково читает файл строка за строкой. |
succeeded | Все строки сохранены. |
partial | Файл обработан полностью, но как минимум одна строка завершилась ошибкой. |
failed | Критическая ошибка остановила обработку до завершения (например, некорректный gzip, отсутствует загруженный файл, внутренняя ошибка обработчика). |
cancelled | Вызывающая сторона отменила импорт; обработчик остановился на следующей границе блока. |
Строка, которая так и не вышла из pending_upload, означает, что URL загрузки был выдан, но подтверждения не последовало; такие строки регулярно удаляются сборщиком мусора после истечения TTL этого URL.
Маршруты кратко
| Метод | Путь | Назначение |
|---|---|---|
POST | /api/v1/monitoring/loan/imports | Начать новый импорт; получить ограниченный по времени URL загрузки. |
POST | /api/v1/monitoring/loan/imports/{id}/commit | Завершить загрузку, поставить задачу обработчику в очередь. |
GET | /api/v1/monitoring/loan/imports/{id} | Прочитать статус, счётчики и сводку ошибок. |
GET | /api/v1/monitoring/loan/imports/{id}?errors=true | Постранично просмотреть ошибки по строкам. |
GET | /api/v1/monitoring/loan/imports | Получить список кредитных импортов вызывающей стороны. |
DELETE | /api/v1/monitoring/loan/imports/{id} | Отменить выполняющийся импорт. |
POST /api/v1/monitoring/loan/imports
Начинает новый импорт. Возвращает id импорта, ограниченный по времени URL загрузки и заголовки загрузки, которые ваш клиент должен повторить при PUT файла.
Тело запроса
| Поле | Тип | Обязательное | Ограничение |
|---|---|---|---|
kind | enum | да | Один из шести видов. |
filename | string | да | 1-255 символов; только для отображения. |
sizeBytes | integer | да | Положительное целое; совпадает с размером файла, который вы собираетесь загрузить. |
portfolioId | строка UUID | null | нет | Необязательное переопределение; строки в теле по-прежнему содержат собственный. |
idempotencyKey | string | null | нет | Предпочтителен заголовок; поле тела — запасной вариант. |
dryRun | boolean | нет | true выполняет проверку без постановки в очередь. |
metadata | object | null | нет | Дословная сквозная передача. |
rowCountDeclared | integer | null | нет | Справочное — улучшает отображение хода выполнения. |
Если переданы и HTTP-заголовок Idempotency-Key, и поле тела, приоритет имеет заголовок.
Ответ — 202 Accepted
{
"importId": "1234abcd-5678-90ef-1234-567890abcdef",
"uploadUrl": "https://<upload-host>/...?<signature>",
"headers": { "<header-name>": "<header-value>" },
"s3Key": "imports/abc.../...",
"reused": false,
"statusUrl": "/api/v1/monitoring/loan/imports/1234abcd-5678-90ef-1234-567890abcdef",
"commitUrl": "/api/v1/monitoring/loan/imports/1234abcd-5678-90ef-1234-567890abcdef/commit"
}| Поле | Примечания |
|---|---|
importId | Идентификатор платформы, который вы указываете во всех последующих вызовах. |
uploadUrl | Ограниченный по времени URL для загрузки через PUT. |
headers | Набор HTTP-заголовков, которые должен содержать ваш PUT. |
s3Key | Ключ хранилища, под которым будет находиться файл. |
reused | true, если ответ — результат дедупликации по ранее использованному Idempotency-Key. |
statusUrl / commitUrl | Вспомогательные URL для последующих этапов жизненного цикла. |
Коды состояния
| Статус | Конверт | Условие |
|---|---|---|
202 Accepted | как выше | Строка импорта создана. |
400 Bad Request | errors[] (path/message) | Ошибка проверки тела. |
400 Bad Request | { error, code: "UNKNOWN_KIND", allowed: [...] } | kind не является одним из шести кредитных видов. |
409 Conflict | { error, code: "IDEMPOTENCY_KEY_REUSED", importId, mismatchedFields } | Idempotency-Key уже использован для импорта с другими параметрами. |
Загрузка файла
Получив uploadUrl, выполните PUT файла прямо на него. Повторите каждый заголовок из набора headers в ответе; подпись URL распространяется на них, иначе загрузка будет отклонена.
curl -X PUT "$UPLOAD_URL" \
-H "<header-name>: <header-value>" \
--data-binary @your-file.ndjsonЗагрузка идёт прямо в хранилище и не проходит через API. Формат файла — тот же формат NDJSON, что описан на странице пакетной загрузки NDJSON, без ограничения на число строк.
POST /api/v1/monitoring/loan/imports/{id}/commit
После завершения PUT вызовите commit, чтобы сообщить платформе, что загрузка завершена. Платформа проверяет наличие файла, переводит строку импорта из pending_upload в queued и ставит задачу обработчику в очередь.
Запрос
Тело отсутствует. Idempotency-Key подразумевается — повторный commit для строки не в состоянии pending_upload ничего не делает и возвращает текущее состояние.
Ответы
200 OK:
{ "importId": "1234abcd-...", "status": "queued" }| Статус | Конверт | Условие |
|---|---|---|
200 OK | { importId, status } | Подтверждение прошло успешно, или строка уже миновала pending_upload (идемпотентно). |
404 Not Found | стандартный | Импорт не существует или принадлежит другой организации. |
409 Conflict | { error, code: "COMMIT_FAILED" } | Платформа не нашла загруженный файл — обычно загрузки не было или она ещё не завершилась. Повторите commit после завершения загрузки. |
GET /api/v1/monitoring/loan/imports/{id}
Читает текущий статус, счётчики и сводку ошибок импорта. Это эндпоинт опроса, который ваш клиент вызывает для отслеживания хода выполнения.
Запрос
| Параметр | Расположение | Обязательный | Примечания |
|---|---|---|---|
id | path | да | UUID импорта в платформе. |
errors | query | нет | true переключает в режим постраничного вывода ошибок (см. ниже). |
Ответ — режим по умолчанию
{
"importId": "1234abcd-...",
"kind": "actual_payment",
"domain": "loan",
"status": "succeeded",
"filename": "payments-2025-full-year.ndjson",
"sizeBytes": 524288000,
"portfolioId": "ddf63d12-...",
"rowCountDeclared": 1500000,
"rowCountProcessed": 1500000,
"rowCountSucceeded": 1499987,
"rowCountFailed": 13,
"createdAt": "2026-05-20T10:00:00Z",
"startedAt": "2026-05-20T10:00:15Z",
"completedAt": "2026-05-20T10:18:42Z",
"dryRun": false,
"errorSummary": {
"totals": { "validation_error": 9, "fk_violation": 4 },
"samples": [
{ "rowNumber": 12, "errorCode": "validation_error", "errorMessage": "..." },
{ "rowNumber": 1041, "errorCode": "fk_violation", "errorMessage": "..." }
]
}
}errorSummary — небольшая встроенная сводка: итоги по кодам ошибок и до десяти примеров строк. Для полного списка ошибок по строкам переключитесь в режим постраничного вывода ошибок.
Ответ — ?errors=true&limit=&offset=
{
"items": [
{
"rowNumber": 12,
"errorCode": "validation_error",
"errorMessage": "interestRateApr must be >= 0",
"rawRow": "{\"id\":\"...\",\"interestRateApr\":\"-0.05\",...}",
"createdAt": "2026-05-20T10:01:14Z"
}
],
"limit": 20,
"offset": 0
}| Поле | Примечания |
|---|---|
rowNumber | Номер строки в загруженном NDJSON, начиная с 1. |
errorCode | Распространённые значения: parse_error (строка не является корректным JSON), validation_error (схема отклонила строку), portfolio_mismatch (portfolioId строки не совпадает с привязкой импорта) и processor_error (непредвиденный сбой обработчика). Сводный список см. в разделе ошибки и коды состояния. |
errorMessage | Понятное человеку описание сбоя. |
rawRow | Исходная строка NDJSON, сохранённая дословно для отладки. |
limit по умолчанию 20, максимум 100. offset по умолчанию 0. Пагинация обходит сохранённый список ошибок в порядке rowNumber, поэтому стабильный курсор — offset += limit.
Коды состояния
| Статус | Условие |
|---|---|
200 OK | Строка существует в вашей организации. |
400 Bad Request | limit или offset некорректны при ?errors=true. |
404 Not Found | Строка не найдена или принадлежит другой организации. |
GET /api/v1/monitoring/loan/imports
Возвращает список кредитных импортов вызывающей стороны, начиная с самых новых.
Запрос
| Параметр | Расположение | Обязательный | Ограничение |
|---|---|---|---|
status | query | нет | Одно из семи состояний жизненного цикла. |
kind | query | нет | Один из шести кредитных видов. |
limit | query | нет | 1-100; по умолчанию 20. |
offset | query | нет | Неотрицательное; по умолчанию 0. |
Ответ
{
"items": [
{
"importId": "...",
"kind": "actual_payment",
"status": "succeeded",
"filename": "...",
"createdAt": "...",
"completedAt": "...",
"rowCountSucceeded": 1499987,
"rowCountFailed": 13
}
],
"limit": 20,
"offset": 0
}DELETE /api/v1/monitoring/loan/imports/{id}
Отменяет выполняющийся импорт. Обработчик останавливается на следующей границе блока; уже сохранённые строки остаются. Отмена строки в конечном состоянии (succeeded, partial, failed или cancelled) ничего не делает и возвращает существующее состояние.
Ответы
200 OK:
{ "importId": "1234abcd-...", "status": "cancelled" }| Статус | Условие |
|---|---|
200 OK | Отмена применена, или строка уже была в конечном состоянии. |
404 Not Found | Строка не найдена или принадлежит другой организации. |
Виды
Поле kind в запросе на начало импорта определяет схему, по которой проверяется каждая строка, и сущность, которая получает строки. Шесть видов взаимно однозначно соответствуют сущностям:
| Вид | Сущность | Схема |
|---|---|---|
borrower | borrowers | Как у POST /borrowers. |
loan | loans | Как у POST /loans. |
scheduled_repayment | scheduled_repayments | Схема планового погашения. |
actual_payment | actual_payments | Как у POST /payments. |
collateral | collateral | Схема залога. |
collateral_valuation | collateral_valuations | Схема оценки залога. |
kind, которого нет в этом списке, возвращает 400 UNKNOWN_KIND с перечнем допустимых значений в ответе, поэтому опечатку можно исправить без проб и ошибок.
Когда использовать этот интерфейс
Используйте асинхронный импорт, если:
- Вы загружаете исторический архив — типичные исторические загрузки содержат миллионы строк.
- Ваш пакет превышает любое из ограничений пакетной загрузки NDJSON (10 000 строк или 10 MB).
- Вам нужна возможность отменить загрузку посередине — у пакетной загрузки NDJSON нет интерфейса отмены, потому что сам запрос и есть загрузка.
- Ваш клиент допускает опрос — push-уведомления о завершении импорта нет.
Для небольших операционных пакетов, которые умещаются в один синхронный запрос, проще использовать пакетную загрузку NDJSON.