Пакетная загрузка NDJSON
Интерфейс пакетной загрузки NDJSON принимает до десяти тысяч строк в одном синхронном HTTP-запросе, проверяет каждую строку по тем же схемам, что и маршруты для отдельных записей, и возвращает отчёт об ошибках на уровне строк. Используйте его для пакетов на конец дня, которые с запасом умещаются в один HTTP-запрос; для исторических загрузок или более крупных пакетов используйте асинхронный импорт.
Формат передачи — JSON с разделением переводом строки: один корректный JSON-объект на строку, без завершающей запятой, без окружающего массива, без открывающего или закрывающего конверта. Пустые строки между объектами допускаются и пропускаются.
Маршруты
Для каждой сущности есть отдельный маршрут. Схема, применяемая к каждой строке, соответствует сущности в URL.
| Метод | Путь | Сущность |
|---|---|---|
POST | /api/v1/monitoring/loan/bulk/borrowers | borrower |
POST | /api/v1/monitoring/loan/bulk/loans | loan |
POST | /api/v1/monitoring/loan/bulk/scheduled-repayments | scheduled_repayment |
POST | /api/v1/monitoring/loan/bulk/actual-payments | actual_payment |
POST | /api/v1/monitoring/loan/bulk/collateral | collateral |
POST | /api/v1/monitoring/loan/bulk/collateral-valuations | collateral_valuation |
Каждая строка в теле запроса должна быть корректным JSON-объектом, удовлетворяющим схеме сущности, как описано на странице отдельных записей. Схемы идентичны; различается только конверт передачи.
Запрос
POST /api/v1/monitoring/loan/bulk/loans HTTP/1.1
Authorization: Bearer <PAT>
Content-Type: application/x-ndjson
Idempotency-Key: <opaque-key>Заголовки и параметры запроса:
| Имя | Расположение | Обязательный | Примечания |
|---|---|---|---|
Authorization | header | да | Bearer PAT. |
Content-Type | header | нет | Рекомендуется application/x-ndjson; application/json тоже принимается. |
Idempotency-Key | header | нет | Настоятельно рекомендуется для рабочих пакетов. |
?dryRun=true | query | нет | Выполняет проверку, пропускает запись. |
?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"
}
]
}| Поле | Тип | Описание |
|---|---|---|
totalRows | integer | Количество непустых строк в теле. |
succeeded | integer | Количество сохранённых строк. |
failed | integer | totalRows - succeeded. |
bronzeSubmissionId | UUID | id единственной записи об отправке для всего тела NDJSON. Отсутствует в ответе на ?dryRun=true. |
reused | boolean | Присутствует и равно true только когда Idempotency-Key совпал с более ранним пакетом и ответ был восстановлен; иначе отсутствует. |
dryRun | boolean | Присутствует и равно true только в ответе на ?dryRun=true; иначе отсутствует. |
errors[].rowNumber | integer | Номер строки в теле запроса, начиная с 1. |
errors[].code | enum | validation_failed | unique_violation | fk_violation | check_violation | db_error. |
errors[].message | string | Понятное человеку описание; для 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-запрос — пакеты обычно завершаются за несколько секунд, но крупный пакет с большим числом проверок внешних ключей в базе данных может занять больше времени.
Выбирайте асинхронный импорт, если:
- Ваш пакет превышает любое из ограничений размера.
- Вы загружаете исторический архив платежей, плановых погашений или заёмщиков — типичные исторические загрузки достигают миллионов строк.
- Вы хотите сохранить возможность отменить выполняющуюся загрузку.