Waafir
이 페이지는 사람의 검토를 기다리는 기계 번역입니다. 오류가 있을 수 있습니다.

대량 NDJSON

대량 NDJSON 인터페이스는 단일 동기 HTTP 요청으로 최대 1만 행을 받아, 단일 레코드 경로와 같은 스키마로 행마다 검증하고 행 단위 오류 보고서를 반환합니다. 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로 인코딩하고 줄바꿈 하나로 끝나야 합니다. 1만 줄을 넘거나 10메가바이트를 넘는 본문은 거부됩니다. 크기 제한을 참고하세요.

행별 규약

모든 행은 엔터티 스키마에 대해 개별적으로 검증됩니다. 행마다 단일 레코드 쓰기와 같은 규칙이 적용됩니다.

  • 모든 행에는 자체 id UUID와 portfolioId가 있어야 합니다. 호출자가 지정한 ID가 행별 중복 제거 키입니다.
  • 배치 전체가 요청 수준의 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.
bronzeSubmissionIdUUIDNDJSON 본문 전체에 대한 단일 제출 기록의 id. ?dryRun=true 응답에는 없습니다.
reusedbooleanIdempotency-Key가 이전 배치와 일치하여 응답이 재구성된 경우에만 존재하며 값은 true입니다. 그 외에는 없습니다.
dryRunboolean?dryRun=true 응답에만 존재하며 값은 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이 아닌 행은 errors[]에 code: "invalid_json" 항목을 받습니다. 배치 전체는 여전히 200을 반환합니다.
404 Not Found{ error, code: "portfolio_not_found", fieldErrors: [...] }?portfolioId=가 귀하의 조직에 유효한 상태로 존재하지 않습니다.
413 Payload Too Large{ error, code: "batch_too_large", fieldErrors: [...] }크기 제한을 참고하세요.

크기 제한

대량 인터페이스의 페이로드 제한은 다음 중 더 작은 값입니다.

  • 비어 있지 않은 줄 1만 개. 이를 초과하는 행은 처리가 시작되기 전에 거부됩니다.
  • 요청 본문 10메가바이트.

둘 중 하나라도 초과한 요청에는 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을 선택하세요.

  • 배치가 1만 행과 10메가바이트 이내입니다.
  • HTTP 응답에서 행 단위 보고서를 즉시 받고 싶습니다.
  • 오래 걸리는 HTTP 요청을 감수할 수 있습니다. 대량 배치는 보통 몇 초 안에 완료되지만, 데이터베이스 외래 키 조회가 많은 대규모 배치는 더 오래 걸릴 수 있습니다.

다음과 같은 경우 비동기 가져오기를 선택하세요.

  • 배치가 크기 제한 중 하나를 초과합니다.
  • 상환, 예정 상환, 차입자의 과거 아카이브를 적재합니다. 일반적인 과거 데이터 적재는 수백만 행에 이릅니다.
  • 진행 중인 적재를 취소할 수 있는 선택지를 남겨 두고 싶습니다.