단일 레코드 CRUD
단일 레코드 CRUD 인터페이스는 소량 처리 경로로, 행 하나당 HTTP 호출 한 번을 사용합니다. 신규 대출 한 건, 일일 배치에 포함되지 못한 상환 한 건, 상태 전환과 같은 운영성 쓰기와 플랫폼 UUID 기반 재조회에 사용합니다. 일일 마감 배치에는 대량 NDJSON을, 과거 데이터 적재에는 비동기 가져오기를 사용하세요.
이 페이지의 모든 경로는 개요에 문서화된 규약을 따릅니다. Bearer 토큰 인증, 연동 보장 사항, fieldErrors 엔벨로프, 취소 의미 체계, 그리고 모든 제출이 기록되는 방식입니다. 아래의 경로별 설명에는 경로 고유의 형태만 적었으므로, 경로 공통 동작은 개요를 다시 참고하세요.
경로 한눈에 보기
| 메서드 | 경로 | 용도 |
|---|---|---|
POST | /api/v1/monitoring/loan/borrowers | 차입자 생성 |
GET | /api/v1/monitoring/loan/borrowers/{id} | UUID로 차입자 조회(PII 마스킹 적용) |
POST | /api/v1/monitoring/loan/loans | 대출 생성 |
POST | /api/v1/monitoring/loan/payments | 실제 상환 생성 |
GET | /api/v1/monitoring/loan/payments/{id} | UUID로 실제 상환 조회 |
PATCH | /api/v1/monitoring/loan/loans/{loanRef}/status | 대출을 새 상태로 전환 |
POST | /api/v1/monitoring/loan/payments/{id}/cancel | 상환 소프트 삭제 |
모든 변경 경로는 Idempotency-Key 헤더와 ?dryRun=true 쿼리 매개변수를 받으며, 검증 실패 시 구조화된 fieldErrors 엔벨로프를 반환합니다.
POST /api/v1/monitoring/loan/borrowers
portfolioId로 식별되는 포트폴리오에 차입자를 생성합니다.
요청
POST /api/v1/monitoring/loan/borrowers HTTP/1.1
Authorization: Bearer <PAT>
Content-Type: application/json
Idempotency-Key: <opaque-key>본문:
| 필드 | 타입 | 필수 | 제약 조건 |
|---|---|---|---|
id | UUID 문자열 | 예 | 호출자가 지정하는 플랫폼 식별자. |
portfolioId | UUID 문자열 | 예 | 소속 포트폴리오. 귀하의 조직에 존재해야 합니다. |
externalId | 문자열 | 예 | 1-255자. 유효한 행에 대해 (portfolio, externalId)별로 고유. |
name | string | null | 아니요 | 차입자 성명. 원본 그대로 저장되며, 투자자용 읽기에서는 마스킹됩니다. |
email | string | null | 아니요 | RFC 5322 이메일. 원본 그대로 저장되며, 투자자용 읽기에서는 마스킹됩니다. |
phone | string | null | 아니요 | 자유 형식 전화번호. 원본 그대로 저장되며, 투자자용 읽기에서는 마스킹됩니다. |
nationalIdLast4 | string | null | 아니요 | 정확히 네 자리 숫자. 앞자리는 절대 반환되지 않습니다. |
countryCode | string | null | 아니요 | ISO-3166 두 글자 코드(대문자). |
dob | date string | null | 아니요 | YYYY-MM-DD. |
gender | enum | null | 아니요 | male | female | non_binary | other | undisclosed(대소문자 구분 안 함). |
incomeBand | string | null | 아니요 | 자유 형식. |
employmentStatus | string | null | 아니요 | 자유 형식. |
metadata | object | null | 아니요 | 그대로 패스스루. |
응답
새로 쓰면 201 Created, 멱등 재전송이면 200 OK가 반환됩니다.
{
"id": "5b6c7d8e-9f0a-1b2c-3d4e-5f6a7b8c9d0e",
"externalId": "BORROWER-001",
"bronzeSubmissionId": "1a2b3c4d-5e6f-7890-abcd-ef0123456789",
"reused": false
}| 상태 | 엔벨로프 | 발생 조건 |
|---|---|---|
200 OK | { id, externalId, bronzeSubmissionId, reused: true } | Idempotency-Key가 이전 요청과 일치했습니다. 새로운 쓰기는 없습니다. |
201 Created | { id, externalId, bronzeSubmissionId, reused: false } | 새 행이 삽입되었습니다. |
400 Bad Request | fieldErrors | 본문 필드 중 하나에서 검증 실패. |
404 Not Found | { error, code: "PORTFOLIO_NOT_FOUND" } | portfolioId가 존재하지 않거나 다른 조직에 속합니다. |
409 Conflict | { error, code: "ID_CONFLICT", fieldErrors: [...] } | 같은 id를 가진 유효한 차입자가 이미 존재합니다. |
cURL
curl -X POST https://app.waafir.io/api/v1/monitoring/loan/borrowers \
-H "Authorization: Bearer $WAAFIR_PAT" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: 5b6c7d8e-9f0a-1b2c-3d4e-5f6a7b8c9d0e" \
-d '{
"id": "5b6c7d8e-9f0a-1b2c-3d4e-5f6a7b8c9d0e",
"portfolioId": "ddf63d12-1234-5678-9abc-def012345678",
"externalId": "BORROWER-001",
"gender": "female",
"countryCode": "KE"
}'GET /api/v1/monitoring/loan/borrowers/{id}
플랫폼 UUID로 차입자를 조회합니다. PII 필드는 기본적으로 마스킹됩니다. 관리자는 ?unmask=true로 원본 PII를 요청할 수 있으며, 이때 감사 로그 항목이 기록됩니다.
요청
| 매개변수 | 위치 | 필수 | 제약 조건 |
|---|---|---|---|
id | path | 예 | 차입자의 플랫폼 UUID. |
unmask | query | 아니요 | true이면 원본 PII를 반환합니다. 관리자 전용. 기본값은 마스킹. |
응답
마스킹된 차입자 레코드와 함께 200 OK가 반환됩니다.
{
"id": "5b6c7d8e-9f0a-1b2c-3d4e-5f6a7b8c9d0e",
"portfolioId": "ddf63d12-1234-5678-9abc-def012345678",
"externalId": "BORROWER-001",
"name": "J***",
"email": "j***@example.com",
"phone": "***-***-1234",
"nationalIdLast4": "1234",
"countryCode": "KE",
"dob": "1985-03-20",
"gender": "female",
"incomeBand": null,
"employmentStatus": null,
"metadata": {}
}| 상태 | 발생 조건 |
|---|---|
200 OK | 행이 귀하의 조직에 존재합니다. 호출자가 관리자이고 동시에 ?unmask=true이면 PII가 원본으로 반환되고, 그렇지 않으면 마스킹됩니다. |
400 Bad Request | id가 올바른 형식의 UUID가 아닙니다. |
404 Not Found | 행이 존재하지 않거나, 취소되었거나, 다른 조직에 속합니다. |
PII 마스킹은 name, email, phone, nationalIdLast4에 적용됩니다. nationalIdLast4 필드는 쓰기 시점에 이미 마지막 네 자리만 저장하지만, 관리자가 아닌 읽기에서는 읽기 시 마스킹으로 이 네 자리도 가려집니다.
관리자가 아닌 호출자가 ?unmask=true를 전달해도 403을 받지 않습니다. 응답은 여전히 마스킹된 형태의 200이며, 거부된 마스킹 해제 시도에 대한 감사 로그 항목이 기록됩니다. 마스킹된 형태가 안전한 기본값이므로 플랫폼은 역할 검사를 오류로 노출하지 않습니다. 보안 팀이 이러한 시도를 확인할 수 있는 것은 감사 추적 덕분입니다.
관리자 호출자가 ?unmask=true를 전달하면 원본 PII를 받으며, 해당 요청은 마스킹 해제를 기록하는 별도의 감사 로그 항목을 남깁니다. 응답에는 Cache-Control: private, no-store가 포함되어 중간 서버가 원본 PII 페이로드를 캐시하지 못하도록 합니다.
POST /api/v1/monitoring/loan/loans
같은 포트폴리오에 있는 기존 차입자에 대해 대출을 생성합니다.
요청
| 필드 | 타입 | 필수 | 제약 조건 |
|---|---|---|---|
id | UUID 문자열 | 예 | 호출자가 지정하는 플랫폼 식별자. |
portfolioId | UUID 문자열 | 예 | 소속 포트폴리오. |
borrowerId | UUID 문자열 | 예 | 같은 포트폴리오의 유효한 차입자. |
externalId | 문자열 | 예 | 1-255자. 유효한 행에 대해 포트폴리오 내에서 고유. |
predecessorLoanId | UUID string | null | 아니요 | 채무 재조정 시 설정하며, 대체되는 대출을 가리킵니다. |
principalAmount | 10진수 문자열 | 예 | 소수점 이하 최대 네 자리. |
currencyCode | 문자열 | 예 | ISO-4217 세 글자 코드. 대소문자 구분 안 함. |
interestRateApr | 10진수 문자열 | 예 | 소수점 이하 최대 여섯 자리. >= 0이어야 합니다. |
disbursementDate | 날짜 문자열 | 예 | YYYY-MM-DD. |
termMonths | 정수 | 예 | > 0이어야 합니다. |
repaymentFrequency | enum | 예 | monthly | weekly | biweekly | quarterly | bullet(대소문자 구분 안 함). |
productType | string | null | 아니요 | 자유 형식. 예: "Term loan", "Overdraft". |
status | enum | 예 | pending | active | paid_off | restructured | written_off | defaulted(대소문자 구분 안 함). |
metadata | object | null | 아니요 | 그대로 패스스루. |
응답
201 Created(멱등 재전송 시 200 OK)와 함께 { id, externalId, bronzeSubmissionId, reused }가 반환됩니다.
| 상태 | 엔벨로프 | 발생 조건 |
|---|---|---|
200 OK | { ..., reused: true } | 멱등 재전송. |
201 Created | { ..., reused: false } | 새 대출이 삽입되었습니다. |
400 Bad Request | fieldErrors | 검증 실패(예: 음수 interestRateApr, 형식이 잘못된 currencyCode). |
404 Not Found | { error, code: "PORTFOLIO_NOT_FOUND" } | 포트폴리오가 없거나 조직 간 요청입니다. |
409 Conflict | { error, code: "ID_CONFLICT" } | 같은 id를 가진 유효한 대출이 이미 존재합니다. |
422 Unprocessable Entity | { error, code: "REFERENCED_ENTITY_NOT_FOUND", fieldErrors: [{ path: "borrowerId", ... }] } | borrowerId가 같은 포트폴리오의 유효한 차입자로 확인되지 않습니다. |
cURL
curl -X POST https://app.waafir.io/api/v1/monitoring/loan/loans \
-H "Authorization: Bearer $WAAFIR_PAT" \
-H "Content-Type: application/json" \
-d '{
"id": "7c8d9e0f-1a2b-3c4d-5e6f-7a8b9c0d1e2f",
"portfolioId": "ddf63d12-1234-5678-9abc-def012345678",
"borrowerId": "5b6c7d8e-9f0a-1b2c-3d4e-5f6a7b8c9d0e",
"externalId": "LOAN-001",
"principalAmount": "10000.00",
"currencyCode": "USD",
"interestRateApr": "0.18",
"disbursementDate": "2026-01-15",
"termMonths": 12,
"repaymentFrequency": "monthly",
"status": "active"
}'POST /api/v1/monitoring/loan/payments
기존 대출에 대한 실제 상환을 기록합니다. 수령한 상환, 부분 상환, 상각에 사용합니다. 채무 재조정은 상환이 아니라 predecessorLoanId를 설정한 새 대출로 모델링합니다.
요청
| 필드 | 타입 | 필수 | 제약 조건 |
|---|---|---|---|
id | UUID 문자열 | 예 | 호출자가 지정하는 플랫폼 식별자. |
portfolioId | UUID 문자열 | 예 | 소속 포트폴리오. |
loanId | UUID 문자열 | 예 | 같은 포트폴리오의 유효한 대출. |
externalId | 문자열 | 예 | 1-255자. 유효한 행에 대해 포트폴리오 내에서 고유. |
paymentDate | 날짜 문자열 | 예 | YYYY-MM-DD. |
amount | 10진수 문자열 | 예 | 수령한 상환 총액. |
currencyCode | 문자열 | 예 | ISO-4217. |
principalPaid | 10진수 문자열 | 아니요 | 기본값은 "0". |
interestPaid | 10진수 문자열 | 아니요 | 기본값은 "0". |
feesPaid | 10진수 문자열 | 아니요 | 기본값은 "0". |
writeOffAmount | 10진수 문자열 | 아니요 | 기본값은 "0". 아래의 채무 면제 규칙을 참고하세요. |
paymentNotes | string | null | 아니요 | writeOffAmount > 0이면 "Forgiven"(대소문자 구분 안 함)이어야 합니다. |
paymentMethod | enum | null | 아니요 | cash | bank_transfer | card | mobile_money | check | other. |
metadata | object | null | 아니요 | 그대로 패스스루. |
채무 면제 규칙. writeOffAmount > 0이면 paymentNotes는 대소문자 구분 없이 "Forgiven"과 같아야 합니다. 플랫폼은 API 경계에서 요청을 실패 처리하므로, 잘못된 상환은 아무것도 기록되기 전에 거부됩니다.
응답
201 Created(멱등 재전송 시 200 OK)와 함께 { id, externalId, bronzeSubmissionId, reused }가 반환됩니다.
| 상태 | 엔벨로프 | 발생 조건 |
|---|---|---|
200 OK | { ..., reused: true } | 멱등 재전송. |
201 Created | { ..., reused: false } | 새 상환이 삽입되었습니다. |
400 Bad Request | fieldErrors | 검증 실패(금액 형식 오류, 열거형 불일치, 필수 필드 누락). |
404 Not Found | { error, code: "PORTFOLIO_NOT_FOUND" } | 포트폴리오가 없거나 조직 간 요청입니다. |
409 Conflict | { error, code: "ID_CONFLICT" } | 같은 id를 가진 유효한 상환이 이미 존재합니다. |
422 Unprocessable Entity | { error, code: "REFERENCED_ENTITY_NOT_FOUND", fieldErrors: [{ path: "loanId", ... }] } | loanId가 같은 포트폴리오의 유효한 대출로 확인되지 않습니다. |
400 Bad Request | { error, code: "CHECK_VIOLATION", fieldErrors: [...] } | 상환 저장 시 채무 면제 규칙에 의해 거부되었습니다(드문 경우이며, 같은 형태는 검증 단계에서 먼저 거부됩니다). |
GET /api/v1/monitoring/loan/payments/{id}
플랫폼 UUID로 실제 상환을 조회하며, 취소된(소프트 삭제된) 행도 포함됩니다. 쓰기 결과를 확인하거나 취소된 레코드를 살펴볼 때 사용합니다.
요청
| 매개변수 | 위치 | 필수 | 제약 조건 |
|---|---|---|---|
id | path | 예 | 상환의 플랫폼 UUID. |
응답
전체 상환 레코드와 함께 200 OK가 반환됩니다. 취소된 행에는 deletedAt 값이 채워지고, 유효한 행은 deletedAt: null입니다. 조직 간 UUID나 알 수 없는 UUID에는 404 Not Found가 반환됩니다. id가 올바른 형식의 UUID가 아니면 400 Bad Request가 반환됩니다.
PATCH /api/v1/monitoring/loan/loans/{loanRef}/status
대출을 새 상태로 전환합니다. {loanRef} 경로 세그먼트에는 대출의 플랫폼 UUID와 externalId 중 어느 것이든 사용할 수 있습니다. externalId를 전달할 때는 외부 ID가 포트폴리오 간에 고유하지 않으므로 ?portfolioId=<UUID>도 함께 지정해야 합니다.
요청
PATCH /api/v1/monitoring/loan/loans/LOAN-001/status?portfolioId=ddf63d12-1234-5678-9abc-def012345678 HTTP/1.1
Authorization: Bearer <PAT>
Content-Type: application/json
Idempotency-Key: <opaque-key>본문:
| 필드 | 타입 | 필수 | 제약 조건 |
|---|---|---|---|
status | enum | 예 | active | paid_off | defaulted | written_off | restructured 중 하나(대소문자 구분 안 함). |
effectiveDate | 날짜 문자열 | 예 | YYYY-MM-DD. |
reason | string | null | 아니요 | 1-500자. 감사 로그에 기록됩니다. |
상태 전환 매트릭스
플랫폼은 전환 매트릭스를 적용합니다. 유효하지 않은 전환에는 422 INVALID_STATUS_TRANSITION이 반환되며, fieldErrors에 전환 전후 상태가 명시됩니다.
| 이전 상태 | 허용되는 대상 상태 |
|---|---|
pending | active |
active | paid_off, defaulted, written_off, restructured |
paid_off | (종료 상태) |
defaulted | written_off, restructured |
written_off | (종료 상태) |
restructured | (종료 상태) |
대출을 restructured로 전환한 뒤에는, predecessorLoanId를 설정하여 대체 대출에 대해 POST /loans를 호출하는 것이 자연스러운 다음 단계입니다. 두 쓰기는 의도적으로 원자적이지 않습니다. 대체 대출의 POST가 실패하면 이전 대출은 restructured 상태로 남으며, 다음에 조회할 때 대사 인터페이스가 이 불일치를 드러냅니다.
응답
성공 시 200 OK가 반환됩니다.
{
"id": "7c8d9e0f-1a2b-3c4d-5e6f-7a8b9c0d1e2f",
"externalId": "LOAN-001",
"status": "restructured",
"bronzeSubmissionId": "9d8c7b6a-5432-1098-7654-321098765432",
"reused": false
}| 상태 | 엔벨로프 | 발생 조건 |
|---|---|---|
200 OK | { id, externalId, status, bronzeSubmissionId, reused } | 전환이 적용되었습니다(또는 reused: true인 멱등 재전송). |
400 Bad Request | fieldErrors | 본문 검증 실패, externalId로 조회할 때 portfolioId 누락, 형식이 잘못된 열거형. |
404 Not Found | { error, code: "NOT_FOUND" } | UUID로 대출을 찾을 수 없거나, (portfolioId, externalId)가 확인되지 않습니다. |
422 Unprocessable Entity | { error, code: "INVALID_STATUS_TRANSITION", fieldErrors: [...] } | 전환 전후 상태 조합이 전환 매트릭스에 없습니다. fieldErrors[].message에 허용되는 대상 상태가 나열됩니다. |
409 Conflict | { error, code: "IDEMPOTENCY_CONFLICT" } | 이 Idempotency-Key는 이미 다른 전환에 사용되었습니다. 이전 쓰기는 그대로 유지되므로 새 전환은 새 키로 보내세요. |
지정한 effectiveDate는 제출과 함께 기록되고 감사 로그에도 남지만, 응답 본문에는 나타나지 않습니다. 이 경로는 의도적으로 metadata를 받지 않습니다. 전환 자체가 감사 이벤트이며, 선택적인 reason 필드가 사람이 읽을 수 있는 컨텍스트를 담습니다.
POST /api/v1/monitoring/loan/payments/{id}/cancel
이전에 기록된 상환을 소프트 삭제합니다. 취소 엔드포인트는 대출 도메인의 유일한 되돌리기 인터페이스입니다. PATCH /loans/{id}/adjust는 없으며, 앞으로도 제공되지 않습니다.
요청
POST /api/v1/monitoring/loan/payments/7c8d9e0f-1a2b-3c4d-5e6f-7a8b9c0d1e2f/cancel HTTP/1.1
Authorization: Bearer <PAT>
Content-Type: application/json본문(선택):
| 필드 | 타입 | 필수 | 제약 조건 |
|---|---|---|---|
reason | string | null | 아니요 | 1-500자. 취소 감사 이벤트에 기록됩니다. |
빈 본문도 허용되며, Content-Type 헤더를 완전히 생략해도 됩니다.
응답
성공 시 200 OK가 반환됩니다.
{
"id": "7c8d9e0f-1a2b-3c4d-5e6f-7a8b9c0d1e2f",
"deletedAt": "2026-03-15T11:02:33Z",
"bronzeSubmissionId": "9d8c7b6a-5432-1098-7654-321098765432",
"reused": false,
"alreadyCancelled": false
}같은 상환에 대해 두 번째로 호출하면 응답 형태는 동일하지만 alreadyCancelled: true가 되고, deletedAt은 최초 취소 시각이 됩니다. reused 플래그는 멱등성 상태를 나타내고, alreadyCancelled는 이번 호출로 행이 변경되었는지를 나타냅니다.
| 상태 | 엔벨로프 | 발생 조건 |
|---|---|---|
200 OK | { id, deletedAt, bronzeSubmissionId, reused, alreadyCancelled } | 최초 또는 이후의 취소. |
400 Bad Request | fieldErrors | id가 올바른 형식의 UUID가 아니거나, reason이 500자를 초과합니다. |
404 Not Found | { error, code: "NOT_FOUND" } | 상환이 존재하지 않거나 다른 조직에 속합니다. |
감사의 완전성을 위해 모든 취소(두 번째 취소 포함)마다 제출 기록이 작성됩니다. 행은 첫 번째 호출에서만 변경됩니다.
소프트 삭제와 externalId 재사용
고유성 제약은 유효한 행에만 적용되므로, 취소된 상환의 externalId는 이후 쓰기에서 재사용할 수 있습니다. 잘못된 제출을 바로잡는 표준 절차는 다음과 같습니다.
- 원래 행에 대해
POST /api/v1/monitoring/loan/payments/{id}/cancel을 호출합니다. - 수정된 필드로 새 행을 만들기 위해
POST /api/v1/monitoring/loan/payments를 호출합니다. 같은externalId를 재사용할 수 있지만,id는 다른 값을 지정해야 합니다.
이는 의도된 설계입니다. 취소는 비파괴적이며(원래 행은 감사를 위해 보존됩니다), externalId를 재사용하면 대사를 위한 운영상의 호출자 ID 공간을 촘촘하게 유지할 수 있습니다.