API 레퍼런스
이 섹션은 Waafir 대출 도메인 API의 레퍼런스 매뉴얼입니다. 대출 도메인 API는 핀테크 기업이 투자자 모니터링을 위해 포트폴리오 데이터를 Waafir로 전송하는 HTTP 인터페이스입니다.
/api/v1/monitoring/loan/ 아래의 모든 경로, 요청 및 응답 스키마, 모든 상태 코드, 공통 개발자 경험 규약, 그리고 예상되는 오류 엔벨로프를 문서화합니다.
이 레퍼런스는 빠짐없이 다루지만 서술형 안내서는 아닙니다. 처음 연동하면서 cURL, TypeScript, Python 예제를 나란히 제공하는 엔드투엔드 단계별 가이드가 필요하다면, 이 레퍼런스와 함께 '쿡북'을 읽으세요. 두 문서는 함께 읽도록 설계되었습니다.
API 적용 범위
대출 도메인 API는 네 가지 수집 방식과 대사 인터페이스를 제공합니다.
- 단일 레코드 CRUD: 행 하나당 HTTP 호출 한 번입니다. 신규 대출 한 건, 상환 한 건, 상태 전환 한 번과 같은 소량의 운영성 쓰기에 사용합니다.
- 대량 NDJSON: 동기 호출 한 번에 최대 1만 행을 보냅니다. HTTP 요청 하나에 들어가는 일일 마감 배치에 사용합니다.
- 비동기 가져오기: 파일을 직접 업로드한 뒤 비동기로 처리합니다. 과거 데이터 적재나 1만 행을 초과하는 모든 배치에 사용합니다.
- 대사: 제출한 행을 자체 호출자 ID로 다시 읽고, 엔터티별 행 수를 조회합니다. 오늘 데이터를 제출하기 전에 어제 제출한 데이터가 문제없이 반영되었는지 확인할 때 사용합니다.
각 방식은 별도 페이지에서 설명합니다. 페이지 순서는 대부분의 연동 담당자가 읽는 순서와 같습니다. 먼저 개요를 읽고, 처음 사용할 수집 방식, 대사, 그리고 오류 레퍼런스 순으로 읽으세요.
여섯 가지 대출 도메인 엔터티
모든 경로는 다음 엔터티 중 하나 이상을 대상으로 합니다. 전체 스키마는 경로별로 문서화되어 있으며, 이 목록은 카탈로그입니다.
borrower: 대출을 받는 자연인 또는 법인입니다. 읽을 때 마스킹되는 선택적 PII 필드가 있습니다.loan: 대출 계약 자체입니다. 원금, 통화, APR, 기간, 상환 주기, 상태를 포함합니다.scheduled_repayment: 계약상 상환 일정으로, 납입 기일마다 한 행입니다.actual_payment: 실제로 받은 상환으로, 상각과 부분 상환을 포함합니다.collateral: 대출에 대해 제공된 담보입니다.collateral_valuation: 담보 행에 대한 특정 시점의 평가로, 여러 평가 방법을 지원합니다.
모든 엔터티는 귀하의 조직에 속한 포트폴리오에 속합니다. 포트폴리오는 쓰기마다 지정하며, 조직은 개인 액세스 토큰에서 결정되므로 요청 본문에 나타나지 않습니다.
인증 요약
모든 요청에는 Authorization: Bearer <PAT>가 포함되며, 여기서 <PAT>는 Waafir 컨트롤 플레인이 발급한 개인 액세스 토큰입니다. 토큰은 조직 범위로 한정됩니다. 조직 A에 발급된 토큰으로는 조직 B의 데이터를 읽거나 쓸 수 없으며, 조직 간 읽기에는 다른 테넌트 리소스의 존재가 노출되지 않도록 403 Forbidden 대신 404 Not Found가 반환됩니다.
전체 인증 및 권한 부여 모델은 개요에서 다룹니다.
이 레퍼런스 사용 방법
페이지를 순서대로 읽거나, 필요한 인터페이스로 바로 이동하세요.
- 개요: 모든 대출 도메인 경로가 따르는 공통 규약입니다. 인증, 연동 보장 사항(호출자 지정 ID, 멱등성, 드라이 런), 오류 엔벨로프, 금액 및 날짜 규칙, 취소 의미 체계, 그리고 모든 제출이 기록되는 방식을 다룹니다.
- 단일 레코드 CRUD: 단일 행 POST, GET, PATCH 및 취소 경로 전체입니다.
- 대량 NDJSON: 행 단위 오류 보고를 제공하는 동기식 대량 수집입니다.
- 비동기 가져오기: 2단계 업로드, 상태 폴링, 오류 페이지 조회로 이루어진 수명 주기입니다.
- 대사: 호출자 ID 기반 재조회와 엔터티별 행 수입니다.
- 오류 및 상태 코드: 대출 도메인 인터페이스가 반환하는 모든 상태 코드, 오류 엔벨로프, 명명된 오류 코드를 정리한 카탈로그입니다.
포트폴리오의 엔드투엔드 온보딩, 일일 대사 실행, 일부 실패한 가져오기에서의 복구와 같은 작업 중심 가이드는 이 레퍼런스와 함께 제공되는 '쿡북'을 참고하세요. '쿡북'은 각 작업을 세 가지 언어로 안내하며, 각 경로가 무엇을 받고 무엇을 반환하는지에 대해서는 이 레퍼런스가 기준 문서입니다.
이 레퍼런스에서 다루지 않는 내용
- 온보딩 및 토큰: 조직을 등록하고, 포트폴리오를 만들고, 개인 액세스 토큰을 발급하는 방법입니다. 이러한 절차는 플랫폼 관리 문서와 '쿡북'의 시작하기 레시피에서 다룹니다.
- 투자자용 분석: 차트 팩, 대출 테이프 내보내기, 대출 테이프 다운로드 인터페이스입니다. 이들은 별도의 경로로 제공되며 여기서는 다루지 않습니다.
- Webhook 및 예약된 테이프 전송: 여기서는 다루지 않습니다.