비동기 가져오기
비동기 가져오기 인터페이스는 과거 데이터 적재와 대량 NDJSON의 1만 행 또는 10메가바이트 제한을 넘는 모든 배치를 위한 경로입니다. 흐름은 2단계로 이루어집니다. 업로드할 내용을 기술하고, 유효 기간이 있는 업로드 URL을 받아 파일을 그 URL로 직접 PUT한 다음, 플랫폼에 커밋을 요청합니다. 그 후 워커가 파일을 한 행씩 스트리밍 처리하면서 행별 오류를 기록하고, 상태 엔드포인트를 통해 진행 상황을 보고합니다.
여기에 소개된 경로는 가져오기 흐름으로 들어가는 대출 도메인 진입점입니다.
수명 주기
수명 주기에는 일곱 가지 상태가 있습니다. 대부분의 프로덕션 적재는 pending_upload → queued → processing → succeeded를 거치며, 나머지 상태는 실패 유형을 나타냅니다.
| 상태 | 의미 |
|---|---|
pending_upload | 가져오기 행이 존재하고, 유효 기간이 있는 업로드 URL이 활성 상태입니다. 플랫폼은 아직 파일을 확인하지 못했습니다. |
queued | 커밋에 성공했습니다. 워커가 아직 파일을 가져가지 않았습니다. |
processing | 워커가 파일을 한 행씩 스트리밍 처리하고 있습니다. |
succeeded | 모든 행이 저장되었습니다. |
partial | 파일은 모두 처리되었지만 하나 이상의 행이 실패했습니다. |
failed | 치명적인 오류로 인해 완료 전에 처리가 중단되었습니다(예: 잘못된 gzip 형식, 업로드된 파일 누락, 워커 내부 오류). |
cancelled | 호출자가 가져오기를 취소했습니다. 워커는 다음 청크 경계에서 멈췄습니다. |
pending_upload에서 벗어나지 않는 행은 발급되었지만 커밋되지 않은 업로드 URL을 나타냅니다. 이러한 행은 URL의 TTL이 만료된 뒤 주기적으로 가비지 컬렉션됩니다.
경로 한눈에 보기
| 메서드 | 경로 | 용도 |
|---|---|---|
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 string | null | 아니요 | 선택적 재정의 값. 본문의 각 행은 여전히 자체 값을 가집니다. |
idempotencyKey | string | null | 아니요 | 헤더 사용을 권장하며, 본문 필드는 대체 수단입니다. |
dryRun | boolean | 아니요 | true이면 대기열에 넣지 않고 검증만 실행합니다. |
metadata | object | null | 아니요 | 그대로 패스스루. |
rowCountDeclared | integer | null | 아니요 | 참고용 값으로, 진행 상황 보고를 개선합니다. |
둘 다 지정된 경우 Idempotency-Key HTTP 헤더가 본문 필드보다 우선합니다.
응답 — 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 | PUT 업로드용 유효 기간이 있는 URL. |
headers | PUT에 반드시 포함해야 하는 HTTP 헤더 맵. |
s3Key | 파일이 저장될 스토리지 키. |
reused | 응답이 이전 Idempotency-Key의 중복 제거 결과이면 true. |
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을 받으면 파일을 그 URL로 직접 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는 암묵적으로 적용됩니다. pending_upload가 아닌 행에 대한 두 번째 커밋은 아무 작업도 하지 않고 현재 상태를 반환합니다.
응답
200 OK:
{ "importId": "1234abcd-...", "status": "queued" }| 상태 | 엔벨로프 | 발생 조건 |
|---|---|---|
200 OK | { importId, status } | 커밋에 성공했거나, 행이 이미 pending_upload를 지났습니다(멱등). |
404 Not Found | 표준 | 가져오기가 존재하지 않거나 다른 조직에 속합니다. |
409 Conflict | { error, code: "COMMIT_FAILED" } | 플랫폼이 업로드된 파일을 찾을 수 없습니다. 보통 업로드가 이루어지지 않았거나 아직 끝나지 않은 경우입니다. 업로드가 완료된 후 커밋을 다시 시도하세요. |
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는 오류 코드별 합계와 최대 10개의 샘플 행으로 구성된 작은 내장 요약입니다. 전체 행별 목록이 필요하면 오류 페이지 조회 모드로 전환하세요.
응답 — ?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 | ?errors=true일 때 limit 또는 offset의 형식이 잘못되었습니다. |
404 Not Found | 행을 찾을 수 없거나 조직 간 요청입니다. |
GET /api/v1/monitoring/loan/imports
호출자의 대출 가져오기를 최신순으로 나열합니다.
요청
| 매개변수 | 위치 | 필수 | 제약 조건 |
|---|---|---|---|
status | query | 아니요 | 일곱 가지 수명 주기 상태 중 하나. |
kind | query | 아니요 | 여섯 가지 대출 종류 중 하나. |
limit | query | 아니요 | 1-100. 기본값 20. |
offset | query | 아니요 | 0 이상. 기본값 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은 요청 자체가 적재이므로 취소 인터페이스가 없습니다.
- 클라이언트가 폴링을 감수할 수 있습니다. 가져오기가 완료되어도 푸시 알림은 없습니다.
단일 동기 요청에 들어가는 소규모 운영 배치에는 대량 NDJSON이 더 간단한 방법입니다.