Waafir
Эта страница переведена машинным способом и ожидает проверки человеком. Возможны неточности.

Асинхронный импорт

Интерфейс асинхронного импорта — путь для исторических загрузок и любых пакетов, превышающих ограничение пакетной загрузки 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 файла.

Тело запроса

ПолеТипОбязательноеОграничение
kindenumдаОдин из шести видов.
filenamestringда1-255 символов; только для отображения.
sizeBytesintegerдаПоложительное целое; совпадает с размером файла, который вы собираетесь загрузить.
portfolioIdстрока UUID | nullнетНеобязательное переопределение; строки в теле по-прежнему содержат собственный.
idempotencyKeystring | nullнетПредпочтителен заголовок; поле тела — запасной вариант.
dryRunbooleanнетtrue выполняет проверку без постановки в очередь.
metadataobject | nullнетДословная сквозная передача.
rowCountDeclaredinteger | 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Ключ хранилища, под которым будет находиться файл.
reusedtrue, если ответ — результат дедупликации по ранее использованному Idempotency-Key.
statusUrl / commitUrlВспомогательные URL для последующих этапов жизненного цикла.

Коды состояния

СтатусКонвертУсловие
202 Acceptedкак вышеСтрока импорта создана.
400 Bad Requesterrors[] (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}

Читает текущий статус, счётчики и сводку ошибок импорта. Это эндпоинт опроса, который ваш клиент вызывает для отслеживания хода выполнения.

Запрос

ПараметрРасположениеОбязательныйПримечания
idpathдаUUID импорта в платформе.
errorsqueryнет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 Requestlimit или offset некорректны при ?errors=true.
404 Not FoundСтрока не найдена или принадлежит другой организации.

GET /api/v1/monitoring/loan/imports

Возвращает список кредитных импортов вызывающей стороны, начиная с самых новых.

Запрос

ПараметрРасположениеОбязательныйОграничение
statusqueryнетОдно из семи состояний жизненного цикла.
kindqueryнетОдин из шести кредитных видов.
limitqueryнет1-100; по умолчанию 20.
offsetqueryнетНеотрицательное; по умолчанию 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 в запросе на начало импорта определяет схему, по которой проверяется каждая строка, и сущность, которая получает строки. Шесть видов взаимно однозначно соответствуют сущностям:

ВидСущностьСхема
borrowerborrowersКак у POST /borrowers.
loanloansКак у POST /loans.
scheduled_repaymentscheduled_repaymentsСхема планового погашения.
actual_paymentactual_paymentsКак у POST /payments.
collateralcollateralСхема залога.
collateral_valuationcollateral_valuationsСхема оценки залога.

kind, которого нет в этом списке, возвращает 400 UNKNOWN_KIND с перечнем допустимых значений в ответе, поэтому опечатку можно исправить без проб и ошибок.

Когда использовать этот интерфейс

Используйте асинхронный импорт, если:

  • Вы загружаете исторический архив — типичные исторические загрузки содержат миллионы строк.
  • Ваш пакет превышает любое из ограничений пакетной загрузки NDJSON (10 000 строк или 10 MB).
  • Вам нужна возможность отменить загрузку посередине — у пакетной загрузки NDJSON нет интерфейса отмены, потому что сам запрос и есть загрузка.
  • Ваш клиент допускает опрос — push-уведомления о завершении импорта нет.

Для небольших операционных пакетов, которые умещаются в один синхронный запрос, проще использовать пакетную загрузку NDJSON.