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

Пакетная загрузка NDJSON

Интерфейс пакетной загрузки NDJSON принимает до десяти тысяч строк в одном синхронном HTTP-запросе, проверяет каждую строку по тем же схемам, что и маршруты для отдельных записей, и возвращает отчёт об ошибках на уровне строк. Используйте его для пакетов на конец дня, которые с запасом умещаются в один HTTP-запрос; для исторических загрузок или более крупных пакетов используйте асинхронный импорт.

Формат передачи — JSON с разделением переводом строки: один корректный JSON-объект на строку, без завершающей запятой, без окружающего массива, без открывающего или закрывающего конверта. Пустые строки между объектами допускаются и пропускаются.

Маршруты

Для каждой сущности есть отдельный маршрут. Схема, применяемая к каждой строке, соответствует сущности в URL.

МетодПутьСущность
POST/api/v1/monitoring/loan/bulk/borrowersborrower
POST/api/v1/monitoring/loan/bulk/loansloan
POST/api/v1/monitoring/loan/bulk/scheduled-repaymentsscheduled_repayment
POST/api/v1/monitoring/loan/bulk/actual-paymentsactual_payment
POST/api/v1/monitoring/loan/bulk/collateralcollateral
POST/api/v1/monitoring/loan/bulk/collateral-valuationscollateral_valuation

Каждая строка в теле запроса должна быть корректным JSON-объектом, удовлетворяющим схеме сущности, как описано на странице отдельных записей. Схемы идентичны; различается только конверт передачи.

Запрос

POST /api/v1/monitoring/loan/bulk/loans HTTP/1.1
Authorization: Bearer <PAT>
Content-Type: application/x-ndjson
Idempotency-Key: <opaque-key>

Заголовки и параметры запроса:

ИмяРасположениеОбязательныйПримечания
AuthorizationheaderдаBearer PAT.
Content-TypeheaderнетРекомендуется application/x-ndjson; application/json тоже принимается.
Idempotency-KeyheaderнетНастоятельно рекомендуется для рабочих пакетов.
?dryRun=truequeryнетВыполняет проверку, пропускает запись.
?portfolioId=<UUID>queryдаПривязка пакета к арендатору; если параметр отсутствует или некорректен, возвращается 400 portfolio_id_required.

Интерфейс пакетной загрузки читает portfolioId только из строки запроса; одноимённое поле в теле каждой строки на уровне пакетной обёртки игнорируется. Каждая строка тела должна ссылаться на один и тот же портфель.

Тело — это сама полезная нагрузка NDJSON в кодировке UTF-8, завершённая одним переводом строки. Строки сверх десяти тысяч или тела больше десяти мегабайт отклоняются — см. ограничения размера.

Контракт для каждой строки

Каждая строка проверяется по схеме сущности независимо. К каждой строке применяются те же правила, что и при записи отдельной записи:

  • Каждая строка должна содержать собственные UUID id и portfolioId. Идентификаторы, задаваемые вызывающей стороной, служат ключом дедупликации для строки.
  • Весь пакет использует общий Idempotency-Key уровня запроса. См. идемпотентность ниже.
  • metadata задаётся для каждой строки. Строка может содержать собственные сквозные метаданные; платформа сохраняет их дословно.
  • Правила для валют, дат, перечислений и денежных сумм идентичны правилам для отдельных записей. Строка, не прошедшая проверку, отображается в отчёте об ошибках по строкам как запись с code: "validation_failed".

Строка, не прошедшая проверку, не прерывает пакет — ошибка отображается как запись в errors[], а обработка остальных строк продолжается.

Ответ

200 OK возвращается для каждого пакета, где сам запрос удалось разобрать, независимо от того, сколько отдельных строк прошло успешно или с ошибкой. Тело ответа содержит полный отчёт по строкам:

{
  "totalRows": 4,
  "succeeded": 3,
  "failed": 1,
  "bronzeSubmissionId": "1a2b3c4d-5e6f-7890-abcd-ef0123456789",
  "reused": false,
  "errors": [
    {
      "rowNumber": 2,
      "code": "fk_violation",
      "message": "borrowerId references a borrower that does not exist in this portfolio"
    }
  ]
}
ПолеТипОписание
totalRowsintegerКоличество непустых строк в теле.
succeededintegerКоличество сохранённых строк.
failedintegertotalRows - succeeded.
bronzeSubmissionIdUUIDid единственной записи об отправке для всего тела NDJSON. Отсутствует в ответе на ?dryRun=true.
reusedbooleanПрисутствует и равно true только когда Idempotency-Key совпал с более ранним пакетом и ответ был восстановлен; иначе отсутствует.
dryRunbooleanПрисутствует и равно true только в ответе на ?dryRun=true; иначе отсутствует.
errors[].rowNumberintegerНомер строки в теле запроса, начиная с 1.
errors[].codeenumvalidation_failed | unique_violation | fk_violation | check_violation | db_error.
errors[].messagestringПонятное человеку описание; для validation_failed ошибки проверки сведены в одно предложение.

Ошибка для строки содержит только rowNumber, code и message. Массива fieldErrors и поля rawRow для строки нет — исходный NDJSON сохраняется дословно в записи об отправке, а не возвращается обратно.

succeeded, равное 0, — не ответ с ошибкой: пакет был разобран и платформа обработала каждую строку; отчёт сообщает, что ничего не сохранилось. Действительно неудачный пакет (некорректный NDJSON во всём теле, слишком большое тело, неизвестный портфель) возвращает 4xx согласно таблице ниже.

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

Конверты ошибок верхнего уровня в этом интерфейсе используют значения code в нижнем регистре, в отличие от кодов в верхнем регистре у маршрутов для отдельных записей. Эти два пространства кодов намеренно разделены.

СтатусКонвертУсловие
200 OKотчёт по строкамПакет обработан; результаты по строкам — в errors[].
400 Bad Request{ error, code: "invalid_body", errors: [...] }Тело запроса не удалось прочитать как текст.
400 Bad Request{ error, code: "portfolio_id_required", fieldErrors: [...] }?portfolioId=<UUID> отсутствует или не является корректным UUID.
400 Bad Request{ error, code: "invalid_json" }Встраивается в отчёт по строкам для каждой строки отдельно — строка, не являющаяся корректным JSON, получает запись code: "invalid_json" в errors[]. Пакет в целом всё равно возвращает 200.
404 Not Found{ error, code: "portfolio_not_found", fieldErrors: [...] }?portfolioId= не существует как действующий портфель в вашей организации.
413 Payload Too Large{ error, code: "batch_too_large", fieldErrors: [...] }См. ограничения размера.

Ограничения размера

Интерфейс пакетной загрузки ограничивает полезную нагрузку меньшим из двух значений:

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

Запрос, превышающий любое из ограничений, получает 413 Payload Too Large:

{
  "error": "batch payload exceeds 10485760 bytes; use the async import endpoint at /api/v1/monitoring/loan/imports",
  "code": "batch_too_large",
  "fieldErrors": [{ "path": "(body)", "message": "max 10485760 bytes" }]
}

Конверт для ограничения по байтам и конверт для ограничения по строкам используют code: "batch_too_large"; причину различают error и fieldErrors[].message. Канонический способ восстановления — перевести ту же нагрузку на асинхронный импорт, при котором файл загружается напрямую и обрабатывается асинхронно без ограничения на число строк.

Идемпотентность

Интерфейс пакетной загрузки выполняет дедупликацию по Idempotency-Key на уровне конверта пакета. Механика:

  • Первый вызов с ключом K. Тело фиксируется как одна отправка, каждая строка обрабатывается, а отчёт по строкам сохраняется вместе с отправкой.
  • Второй вызов с ключом K и тем же телом. Ни второй записи, ни повторной вставки. Платформа возвращает исходный отчёт с reused: true.
  • Второй вызов с ключом K и другим телом. Платформа всё равно возвращает исходный отчёт — первоисточником служит исходная отправка. Повторный POST с исправленным телом должен использовать другой ключ.

Это значит, что клиент, повторяющий запрос после сетевого сбоя, в безопасности, даже если тело второго запроса было обрезано или изменено при передаче, — платформа возвращает результаты по строкам от первой успешной обработки.

Запись об отправке

Каждый пакетный запрос фиксируется как одна отправка, содержащая всё тело NDJSON, а не по одной на строку. Повторно отправленная строка никогда не сохраняется дважды, потому что externalId уникален в пределах портфеля среди действующих строк.

bronzeSubmissionId в ответе — это id записи об отправке; храните его вместе со своей локальной записью об отправке для аудита и сверки.

Пример cURL

cat <<'EOF' > batch.ndjson
{"id":"a1...","portfolioId":"ddf63d12-1234-5678-9abc-def012345678","borrowerId":"b1...","externalId":"L-001","principalAmount":"5000","currencyCode":"USD","interestRateApr":"0.18","disbursementDate":"2026-01-15","termMonths":12,"repaymentFrequency":"monthly","status":"active"}
{"id":"a2...","portfolioId":"ddf63d12-1234-5678-9abc-def012345678","borrowerId":"b2...","externalId":"L-002","principalAmount":"3000","currencyCode":"USD","interestRateApr":"0.20","disbursementDate":"2026-01-15","termMonths":24,"repaymentFrequency":"monthly","status":"active"}
{"id":"a3...","portfolioId":"ddf63d12-1234-5678-9abc-def012345678","borrowerId":"b3...","externalId":"L-003","principalAmount":"7500","currencyCode":"USD","interestRateApr":"0.22","disbursementDate":"2026-01-15","termMonths":18,"repaymentFrequency":"monthly","status":"active"}
EOF

curl -X POST "https://app.waafir.io/api/v1/monitoring/loan/bulk/loans?portfolioId=ddf63d12-1234-5678-9abc-def012345678" \
  -H "Authorization: Bearer $WAAFIR_PAT" \
  -H "Content-Type: application/x-ndjson" \
  -H "Idempotency-Key: nightly-2026-01-15-loans" \
  --data-binary @batch.ndjson

Когда выбирать пакетную загрузку NDJSON, а когда асинхронный импорт

Выбирайте пакетную загрузку NDJSON, если:

  • Ваш пакет умещается в десять тысяч строк и десять мегабайт.
  • Вам нужен немедленный отчёт по строкам в HTTP-ответе.
  • Вы допускаете длительный HTTP-запрос — пакеты обычно завершаются за несколько секунд, но крупный пакет с большим числом проверок внешних ключей в базе данных может занять больше времени.

Выбирайте асинхронный импорт, если:

  • Ваш пакет превышает любое из ограничений размера.
  • Вы загружаете исторический архив платежей, плановых погашений или заёмщиков — типичные исторические загрузки достигают миллионов строк.
  • Вы хотите сохранить возможность отменить выполняющуюся загрузку.