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

단일 레코드 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>

본문:

필드타입필수제약 조건
idUUID 문자열예호출자가 지정하는 플랫폼 식별자.
portfolioIdUUID 문자열예소속 포트폴리오. 귀하의 조직에 존재해야 합니다.
externalId문자열예1-255자. 유효한 행에 대해 (portfolio, externalId)별로 고유.
namestring | null아니요차입자 성명. 원본 그대로 저장되며, 투자자용 읽기에서는 마스킹됩니다.
emailstring | null아니요RFC 5322 이메일. 원본 그대로 저장되며, 투자자용 읽기에서는 마스킹됩니다.
phonestring | null아니요자유 형식 전화번호. 원본 그대로 저장되며, 투자자용 읽기에서는 마스킹됩니다.
nationalIdLast4string | null아니요정확히 네 자리 숫자. 앞자리는 절대 반환되지 않습니다.
countryCodestring | null아니요ISO-3166 두 글자 코드(대문자).
dobdate string | null아니요YYYY-MM-DD.
genderenum | null아니요male | female | non_binary | other | undisclosed(대소문자 구분 안 함).
incomeBandstring | null아니요자유 형식.
employmentStatusstring | null아니요자유 형식.
metadataobject | 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 RequestfieldErrors본문 필드 중 하나에서 검증 실패.
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를 요청할 수 있으며, 이때 감사 로그 항목이 기록됩니다.

요청

매개변수위치필수제약 조건
idpath예차입자의 플랫폼 UUID.
unmaskquery아니요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 Requestid가 올바른 형식의 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

같은 포트폴리오에 있는 기존 차입자에 대해 대출을 생성합니다.

요청

필드타입필수제약 조건
idUUID 문자열예호출자가 지정하는 플랫폼 식별자.
portfolioIdUUID 문자열예소속 포트폴리오.
borrowerIdUUID 문자열예같은 포트폴리오의 유효한 차입자.
externalId문자열예1-255자. 유효한 행에 대해 포트폴리오 내에서 고유.
predecessorLoanIdUUID string | null아니요채무 재조정 시 설정하며, 대체되는 대출을 가리킵니다.
principalAmount10진수 문자열예소수점 이하 최대 네 자리.
currencyCode문자열예ISO-4217 세 글자 코드. 대소문자 구분 안 함.
interestRateApr10진수 문자열예소수점 이하 최대 여섯 자리. >= 0이어야 합니다.
disbursementDate날짜 문자열예YYYY-MM-DD.
termMonths정수예> 0이어야 합니다.
repaymentFrequencyenum예monthly | weekly | biweekly | quarterly | bullet(대소문자 구분 안 함).
productTypestring | null아니요자유 형식. 예: "Term loan", "Overdraft".
statusenum예pending | active | paid_off | restructured | written_off | defaulted(대소문자 구분 안 함).
metadataobject | null아니요그대로 패스스루.

응답

201 Created(멱등 재전송 시 200 OK)와 함께 { id, externalId, bronzeSubmissionId, reused }가 반환됩니다.

상태엔벨로프발생 조건
200 OK{ ..., reused: true }멱등 재전송.
201 Created{ ..., reused: false }새 대출이 삽입되었습니다.
400 Bad RequestfieldErrors검증 실패(예: 음수 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를 설정한 새 대출로 모델링합니다.

요청

필드타입필수제약 조건
idUUID 문자열예호출자가 지정하는 플랫폼 식별자.
portfolioIdUUID 문자열예소속 포트폴리오.
loanIdUUID 문자열예같은 포트폴리오의 유효한 대출.
externalId문자열예1-255자. 유효한 행에 대해 포트폴리오 내에서 고유.
paymentDate날짜 문자열예YYYY-MM-DD.
amount10진수 문자열예수령한 상환 총액.
currencyCode문자열예ISO-4217.
principalPaid10진수 문자열아니요기본값은 "0".
interestPaid10진수 문자열아니요기본값은 "0".
feesPaid10진수 문자열아니요기본값은 "0".
writeOffAmount10진수 문자열아니요기본값은 "0". 아래의 채무 면제 규칙을 참고하세요.
paymentNotesstring | null아니요writeOffAmount > 0이면 "Forgiven"(대소문자 구분 안 함)이어야 합니다.
paymentMethodenum | null아니요cash | bank_transfer | card | mobile_money | check | other.
metadataobject | null아니요그대로 패스스루.

채무 면제 규칙. writeOffAmount > 0이면 paymentNotes는 대소문자 구분 없이 "Forgiven"과 같아야 합니다. 플랫폼은 API 경계에서 요청을 실패 처리하므로, 잘못된 상환은 아무것도 기록되기 전에 거부됩니다.

응답

201 Created(멱등 재전송 시 200 OK)와 함께 { id, externalId, bronzeSubmissionId, reused }가 반환됩니다.

상태엔벨로프발생 조건
200 OK{ ..., reused: true }멱등 재전송.
201 Created{ ..., reused: false }새 상환이 삽입되었습니다.
400 Bad RequestfieldErrors검증 실패(금액 형식 오류, 열거형 불일치, 필수 필드 누락).
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로 실제 상환을 조회하며, 취소된(소프트 삭제된) 행도 포함됩니다. 쓰기 결과를 확인하거나 취소된 레코드를 살펴볼 때 사용합니다.

요청

매개변수위치필수제약 조건
idpath예상환의 플랫폼 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>

본문:

필드타입필수제약 조건
statusenum예active | paid_off | defaulted | written_off | restructured 중 하나(대소문자 구분 안 함).
effectiveDate날짜 문자열예YYYY-MM-DD.
reasonstring | null아니요1-500자. 감사 로그에 기록됩니다.

상태 전환 매트릭스

플랫폼은 전환 매트릭스를 적용합니다. 유효하지 않은 전환에는 422 INVALID_STATUS_TRANSITION이 반환되며, fieldErrors에 전환 전후 상태가 명시됩니다.

이전 상태허용되는 대상 상태
pendingactive
activepaid_off, defaulted, written_off, restructured
paid_off(종료 상태)
defaultedwritten_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 RequestfieldErrors본문 검증 실패, 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

본문(선택):

필드타입필수제약 조건
reasonstring | 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 RequestfieldErrorsid가 올바른 형식의 UUID가 아니거나, reason이 500자를 초과합니다.
404 Not Found{ error, code: "NOT_FOUND" }상환이 존재하지 않거나 다른 조직에 속합니다.

감사의 완전성을 위해 모든 취소(두 번째 취소 포함)마다 제출 기록이 작성됩니다. 행은 첫 번째 호출에서만 변경됩니다.

소프트 삭제와 externalId 재사용

고유성 제약은 유효한 행에만 적용되므로, 취소된 상환의 externalId는 이후 쓰기에서 재사용할 수 있습니다. 잘못된 제출을 바로잡는 표준 절차는 다음과 같습니다.

  1. 원래 행에 대해 POST /api/v1/monitoring/loan/payments/{id}/cancel을 호출합니다.
  2. 수정된 필드로 새 행을 만들기 위해 POST /api/v1/monitoring/loan/payments를 호출합니다. 같은 externalId를 재사용할 수 있지만, id는 다른 값을 지정해야 합니다.

이는 의도된 설계입니다. 취소는 비파괴적이며(원래 행은 감사를 위해 보존됩니다), externalId를 재사용하면 대사를 위한 운영상의 호출자 ID 공간을 촘촘하게 유지할 수 있습니다.