쿡북
이 쿡북은 대출 포트폴리오를 Waafir 모니터링 API에 연결하는 핀테크 엔지니어를 위한 것입니다. 각 레시피는 하나의 작업을 처음부터 끝까지 세 가지 참조 클라이언트(cURL, TypeScript, Python) 모두로 보여 주므로, 독자가 머릿속으로 언어 간에 옮겨 생각할 필요가 없습니다. 레시피는 정상 경로뿐 아니라 실제 연동에서 마주치는 실패 및 예외 상황 경로에 중점을 둡니다.
대상 독자
Waafir 조직 관리자로부터 개인 액세스 토큰(PAT)을 발급받았고, 일일 대출 테이프 데이터(차입자, 대출, 예정 상환, 실제 납입, 담보, 담보 평가)를 Waafir에 제출하는 코드를 작성하고 있는 분을 대상으로 합니다. 모든 제출은 보낸 그대로 기록된 다음 행으로 저장되며, 이후 해당 포트폴리오에 연결된 모든 데이터룸의 투자자 모니터링 탭을 구동합니다.
레시피 사용 방법
모든 레시피는 같은 형식을 따릅니다. 짧은 도입 설명, 정해진 순서의 세 가지 펜스 코드 블록, 그리고 간단한 검증 단락입니다. 코드 블록은 다음과 같습니다.
- cURL — 셸에 복사하여 붙여 넣어 실행합니다. 가장 중립적이며, 일회성 확인과 CI 점검에 유용합니다.
- TypeScript — 공개 JSON 계약을 대상으로 하는
fetch기반 코드입니다. SDK 설치가 필요 없습니다. - Python — 같은 JSON 계약을 대상으로 하는
requests기반 코드입니다. 표준 라이브러리로 충분하며, Waafir 전용 패키지는 필요 없습니다.
인증
모든 엔드포인트는 Authorization 헤더에 PAT가 필요합니다.
Authorization: Bearer <YOUR_PAT>PAT는 하나의 Waafir 조직으로 범위가 한정되며, 모든 요청에 해당 조직의 신원을 담습니다. 비밀 정보로 취급하고, 유출되면 대시보드에서 교체하세요. 이 레시피 전반에서 API 기본 URL은 https://app.waafir.io입니다. 먼저 샌드박스 테넌트와 연동한다면 스테이징 URL로 바꾸세요.
레시피에서 사용하는 규칙
- cURL 예제의 모든 셸 변수는
${UPPER_CASE_NAME}형식으로 작성되어 있으므로, 한 번export해 두고 여러 레시피에서 재사용할 수 있습니다. - TypeScript와 Python 예제는
BASE_URL과PAT를 환경에서 읽는다고 가정합니다. 사용하는 구성 로더에 맞게 조정하세요. Idempotency-Key헤더는 안전한 재시도를 위한 플랫폼 전반의 규칙입니다. 정확한 의미는 재시도 레시피를 참고하세요.- 모든 쓰기 엔드포인트는 사용자의 자체
external_id값을 받습니다. 호출자가 제공한 식별자가 수집, 대사, 테이프 다운로드 전 과정에서 기준 핸들로 유지됩니다. Waafir의 내부 UUID를 알 필요가 전혀 없습니다.
쿡북에서 다루지 않는 내용
쿡북은 작업 중심입니다. 전체 엔드포인트 정의, 요청 및 응답 스키마, 오류 코드 참조는 쿡북과 함께 제공될 API 참조 섹션을 참고하세요. 포트폴리오가 무엇이며 데이터룸과 어떤 관계인지 같은 제품 개념은 데이터룸과 기본 개념 섹션을 참고하세요.
레시피 목록
- 비동기 NDJSON으로 대출 테이프 대량 가져오기 — 기본 수집 흐름: 직접 업로드, 커밋, 완료까지 폴링.
- 데이터를 커밋하기 전에 드라이런으로 로드 검증하기 —
?dryRun=true를 사용하는 같은 흐름으로, 행이 기록되기 전에 파일에 무엇이 들어 있는지 확인합니다. - 멱등성 키로 안전하게 재시도하기 — 중복 가져오기를 만들지 않고 일시적인 네트워크 장애를 견딥니다.
- 가져오기 후 부분 실패 오류 검사하기 — 가져오기가
partial로 끝났을 때 행별 오류를 페이지 단위로 살펴봅니다. - 진행 중인 가져오기 취소하기 — 일부만 기록된 행 없이 다음 배치 경계에서 오래 실행되는 가져오기를 중지합니다.
- 외부 ID로 데이터 대사하기 — 자체 식별자로 행이 반영되었는지 확인하고 일일 건수를 검증합니다.