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

개요

모든 대출 도메인 엔드포인트는 이 페이지의 규약을 공유합니다. 이 페이지를 먼저 읽으세요. 각 인터페이스 페이지는 내용을 반복하지 않고 이 페이지를 참조합니다.

기본 URL 및 버전 관리

모든 대출 도메인 경로는 /api/v1/monitoring/loan/ 아래에 마운트됩니다. v 뒤의 정수는 메이저 버전입니다. 메이저 버전 변경은 호환성을 깨는 변경이며, 명시적인 지원 중단 공지 후에만 이루어집니다. 메이저 버전 내의 마이너 변경은 추가만 이루어지며(새로운 선택 필드, 새 엔드포인트, 새 열거형 값), 이해하지 못하는 필드를 무시하는 연동을 깨뜨리지 않습니다.

프로덕션 호스트는 https://app.waafir.io입니다. 전체 URL을 만들려면 이 레퍼런스 사이트의 경로 앞에 호스트를 붙이세요. 예: https://app.waafir.io/api/v1/monitoring/loan/borrowers.

인증

모든 요청에는 Bearer 토큰이 담긴 Authorization 헤더가 포함됩니다.

Authorization: Bearer <PAT>

<PAT>는 Waafir 컨트롤 플레인이 단일 조직에 대해 발급한 개인 액세스 토큰입니다. 토큰의 조직이 모든 읽기와 쓰기의 테넌트 범위를 결정합니다. 토큰이 이미 조직을 고정하므로 URL이나 본문에는 조직 매개변수가 없습니다.

조직 간 요청에는 403 Forbidden이 아니라 404 Not Found가 반환됩니다. 403을 반환하면 id를 통해 다른 테넌트 리소스의 존재가 노출됩니다. 404 방식에서는 알 수 없는 id와 다른 테넌트의 id가 똑같이 처리됩니다.

Authorization 헤더가 없거나, 알 수 없는 토큰 또는 폐기된 토큰을 사용한 요청에는 401 Unauthorized가 반환됩니다.

연동 보장 사항

모든 변경 경로는 아래의 보장 사항을 따릅니다. 각 항목은 클라이언트 코드가 의존해도 되는 것이며, 여기서 한 번 읽어 두면 견고한 연동을 한 번에 구현할 수 있습니다.

호출자 지정 ID

모든 엔터티의 요청 본문에는 호출자가 UUID로 지정하는 id 필드가 있습니다. 플랫폼은 ID를 대신 생성하지 않습니다. 이것이 이 목록에 있는 다른 모든 규약의 기반입니다. 멱등성, 대사, 재전송은 모두 호출자가 직접 정한 식별자로 행을 지정할 수 있다는 전제에 의존합니다.

같은 id로 행을 다시 POST하면 409 ID_CONFLICT와 함께 id를 가리키는 fieldErrors 항목을 받습니다. ID는 신중하게 정하세요. 생성된 UUIDv4를 권장하지만, 형식이 올바른 UUID라면 무엇이든 사용할 수 있습니다.

id 외에도 모든 엔터티에는 externalId가 있습니다. 이는 최대 255자의 자유 형식 문자열로, 자체 시스템에서 행을 지정할 때 사용합니다. externalId는 유효한 행에 대해 포트폴리오 내에서 고유하며, 이 덕분에 호출자 ID 기반 대사가 가능합니다.

Idempotency-Key 헤더

모든 변경 경로는 선택적인 Idempotency-Key HTTP 헤더를 읽습니다. 이 헤더가 있으면 플랫폼은 내부 아카이브와 대조하여 중복을 제거합니다. 같은 키를 가진 두 번째 요청은 본문이 조금 다르더라도 첫 번째와 동일한 응답을 반환합니다. 클라이언트는 이를 통해 요청 도달 여부를 확신할 수 없는 일시적인 네트워크 장애를 견딜 수 있습니다.

이 헤더는 전송 시 대소문자를 구분하지 않습니다(Idempotency-Key, idempotency-key, IDEMPOTENCY-KEY 모두 사용 가능). 값은 불투명한 문자열로 취급됩니다. 논리적 작업마다 안정적인 값을 선택하세요. 일반적으로 UUIDv4에 경로 구분자를 붙여 사용합니다.

?dryRun=true

모든 변경 경로는 ?dryRun=true 쿼리 매개변수를 받습니다. 드라이 런 요청은 검증과 테넌트 검사를 실행하고 검증된 입력을 반환하지만, 아무것도 기록하지 않으며 행도 저장하지 않습니다. 실제로 쓰기 전에 본문이 올바르게 파싱되는지 확인할 때 사용하세요.

드라이 런이 성공하면 응답 형태는 { "dryRun": true, "validatedInput": <body> }이고 상태는 200 OK입니다. 드라이 런 중의 검증 실패는 실제 쓰기와 같은 400 형태를 반환하며, 차이는 부수 효과뿐입니다.

fieldErrors 검증 엔벨로프

검증에 실패하면 구조화된 엔벨로프와 함께 400 Bad Request가 반환됩니다.

{
  "error": "Validation failed",
  "fieldErrors": [
    { "path": "interestRateApr", "message": "interestRateApr must be >= 0" },
    { "path": "termMonths", "message": "termMonths must be > 0" }
  ]
}

path는 문제가 있는 필드까지의 점 표기 경로이고, message는 사람이 읽을 수 있는 설명입니다. 이 엔벨로프는 모든 경로에서 동일하므로, 클라이언트 측 처리기 하나로 모든 검증 실패를 일관되게 표시할 수 있습니다.

대소문자를 구분하지 않는 열거형과 "혹시 이것을 찾으셨나요" 힌트

도메인 열거형(대출 상태, 결제 수단, 상환 주기, 통화 코드 등)은 전송 시 대소문자를 가리지 않고 받습니다. 플랫폼은 저장하기 전에 표준 소문자 형식으로 정규화합니다.

일치하지 않으면 400이 반환되며, fieldErrors 항목에 문제가 된 값과 가장 가까운 허용 값이 제시됩니다.

{
  "error": "Validation failed",
  "fieldErrors": [
    {
      "path": "status",
      "message": "got 'restruktured', did you mean 'restructured'?"
    }
  ]
}

제안 값은 작은 편집 거리 지표로 계산되므로, 글자 순서 바뀜이나 한 글자 오타를 안정적으로 감지합니다.

metadata JSONB 패스스루

모든 엔터티는 객체 타입의 선택적 metadata 필드를 받습니다. 플랫폼은 이 객체를 그대로 저장합니다. 키를 제거하거나 값을 변환하지 않습니다. 내부 ID, 원천 시스템, 추출 타임스탬프, 캠페인 코드처럼 플랫폼이 이해할 필요가 없는 클라이언트 측 컨텍스트를 첨부할 때 사용하세요.

metadata를 받지 않는 인터페이스가 두 가지 있습니다. 대출 상태 전환 경로와 상환 취소 경로입니다. 그 이유는 해당 경로의 설명에 적혀 있습니다.

호출자 ID 기반 대사

모든 엔터티는 제출한 externalId로 포트폴리오 범위 내에서 지정할 수 있습니다. 대사 인터페이스(GET /loans/{externalId} 및 GET /counts)는 이를 활용해 플랫폼이 할당한 UUID 없이도 쓰기 결과를 확인할 수 있게 합니다. 정확한 형태는 대사 페이지를 참고하세요.

금액 표현

금액은 전송 시 소수점 이하 최대 네 자리의 10진수 숫자 문자열로 표현합니다. IEEE-754 이진 부동소수점은 10진 센트 단위를 정확히 표현할 수 없으므로 JavaScript number는 거부됩니다.

{ "amount": "100.50", "currencyCode": "USD" }

소수점 이하가 네 자리를 넘거나, 숫자, 맨 앞의 마이너스 기호, 소수점 하나 이외의 문자가 포함된 값에는 400과 fieldErrors 항목이 반환됩니다. 빈 문자열은 거부됩니다.

통화 코드는 ISO-4217 세 글자 코드입니다. 플랫폼은 일반적인 코드 집합을 명시적으로 인식하며, 대문자 세 글자 형태에 맞는 알 수 없는 코드는 받아서 그대로 저장하므로 특수 시장의 코드가 차단되지 않습니다.

날짜 형식

날짜는 전송 시 YYYY-MM-DD 형식의 ISO-8601 달력 날짜 문자열로 표현합니다.

{ "disbursementDate": "2026-01-15" }

시간대 요소는 없습니다. 날짜는 포트폴리오 기준으로 해석되는 달력상의 날짜이며, 플랫폼은 변환하지 않습니다.

취소 의미 체계

API 호출은 행을 지우지 않습니다. 취소나 기타 되돌리기는 대신 행을 취소됨으로 표시합니다. 그 영향은 다음과 같습니다.

  • 취소해도 externalId는 해제되지 않습니다. externalId는 포트폴리오 내 유효한 행 사이에서만 고유합니다. 취소된 행은 더 이상 유효하지 않으므로, 수정된 재제출에서 해당 externalId를 재사용할 수 있습니다.
  • 대사 읽기는 기본적으로 취소된 행을 반환하지 않습니다. GET /loans/{externalId} 및 GET /counts 인터페이스의 기본 응답에서는 소프트 삭제된 행이 제외됩니다.
  • 제출 기록은 어떤 경우에도 보존됩니다. 행이 취소되더라도, 그 행을 만든 제출의 기록은 감사를 위해 그대로 남습니다.

모든 제출이 기록됩니다

성공한 모든 변경은 행이 쓰이기 전에 원본 요청 본문을 기록합니다. 연동에 미치는 영향은 다음과 같습니다.

  • 200/201은 제출이 영구적으로 기록되었음을 의미합니다. 이후 다운스트림 처리에서 문제가 표시되더라도 마찬가지입니다. 감사 추적은 플랫폼이 요청을 승인한 순간부터 시작됩니다.
  • 409 ID_CONFLICT도 보관됩니다. 제출 기록에는 충돌과 시도된 제출이 모두 저장되므로, 나중에 무엇이 전송되었는지 모호함 없이 조사할 수 있습니다.
  • 비동기 가져오기는 커밋 시점에 기록됩니다. 업로드된 NDJSON 파일과 가져오기 자체가 기록이며, 비동기 가져오기에는 행별 기록이 따로 없습니다.

제출 기록은 변경할 수 없습니다. 공개 API로 직접 읽을 수는 없지만, 대사 인터페이스가 신뢰할 수 있는 기준이 되는 이유가 바로 이 기록입니다. 대사에서 보이는 모든 행에는 그에 대응하는 아카이브 항목이 있습니다.

이 레퍼런스의 나머지 구성

이 레퍼런스 사이트의 이후 각 페이지는 수집 방식 하나 또는 대사 인터페이스를 다룹니다. 모든 경로 페이지는 동일한 구조를 따릅니다. 한 문장으로 된 목적 설명, 요청 형태(헤더, 쿼리, 본문), 상태 코드별 응답 형태, 그리고 최소한의 cURL 호출 예시입니다. 필드별 제약 조건은 훑어보기 쉬운 표로 정리되어 있으며, 심화 예제와 3개 언어 코드 샘플은 '쿡북'에 있습니다.

오류 및 상태 코드 페이지는 이 사이트의 모든 경로에서 사용하는 응답 엔벨로프를 정리한 레퍼런스입니다. 연동 전에 한 번 읽어 두고, 예상치 못한 200 이외의 상태를 받을 때마다 다시 참고하세요.