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

대사

대사 인터페이스를 사용하면 플랫폼이 할당한 UUID가 아니라 자체 호출자 ID로 Waafir에 무엇이 반영되었는지 확인할 수 있습니다. 경로가 두 개뿐일 만큼 의도적으로 최소화되어 있지만, 견고한 연동을 운영 측면에서 떠받치는 핵심입니다. 건전한 일일 데이터 수집은 모두 대사 호출로 마무리됩니다.

호출자 ID로 대사하는 이유

externalId: "L-001"인 대출을 제출하면, 귀사 시스템은 이미 그 이름으로 해당 행을 알고 있습니다. 플랫폼에 "L-001이 있나요?"라고 묻는 것은 자연스러운 다음 단계입니다. 게다가 먼저 플랫폼 UUID로 변환할 필요가 없으므로, 대사 로직을 장부에서 쓰는 것과 같은 식별자로 실행할 수 있습니다.

플랫폼은 externalId가 유효한 행에 대해 포트폴리오 내에서 고유함을 보장하므로, externalId로 조회하면 단일 행만 읽으면 됩니다.

경로

메서드경로용도
GET/api/v1/monitoring/loan/loans/{externalId}?portfolioId=<UUID>호출자 ID로 단일 대출을 조회합니다.
GET/api/v1/monitoring/loan/counts엔터티별 행 합계를 조회하며, 포트폴리오, 날짜, 엔터티로 좁힐 수 있습니다.

GET /api/v1/monitoring/loan/loans/{externalId}

제출한 externalId로 단일 대출을 조회합니다. 취소된(소프트 삭제된) 행은 제외됩니다.

요청

매개변수위치필수제약 조건
externalIdpath예1-255자. URL에 안전하지 않은 문자는 퍼센트 인코딩하세요.
portfolioIdquery예대출을 소유한 포트폴리오의 UUID.

externalId는 포트폴리오 간에는 고유하지 않고 포트폴리오 내에서만 고유하므로 portfolioId가 필수입니다.

응답 — 200 OK

{
  "loan": {
    "id": "7c8d9e0f-1a2b-3c4d-5e6f-7a8b9c0d1e2f",
    "portfolioId": "ddf63d12-1234-5678-9abc-def012345678",
    "borrowerId": "5b6c7d8e-9f0a-1b2c-3d4e-5f6a7b8c9d0e",
    "externalId": "L-001",
    "predecessorLoanId": null,
    "principalAmount": "10000.0000",
    "currencyCode": "USD",
    "interestRateApr": "0.180000",
    "disbursementDate": "2026-01-15",
    "termMonths": 12,
    "repaymentFrequency": "monthly",
    "productType": "Term loan",
    "status": "active",
    "metadata": {},
    "createdAt": "2026-01-15T08:00:00Z",
    "updatedAt": "2026-01-15T08:00:00Z"
  },
  "borrower": {
    "id": "5b6c7d8e-9f0a-1b2c-3d4e-5f6a7b8c9d0e",
    "externalId": "B-001",
    "name": "J***",
    "email": "j***@example.com",
    "phone": "***-***-1234",
    "nationalIdLast4": "1234",
    "countryCode": "KE",
    "dob": "1985-03-20",
    "gender": "female",
    "incomeBand": null,
    "employmentStatus": null
  }
}

응답에는 대출의 차입자가 PII가 마스킹된 상태로 포함됩니다. 이는 투자자 범위의 뷰이며, 차입자 GET 엔드포인트와 같은 마스킹이 적용됩니다. 마스킹 덕분에 호출 시스템에 PII를 노출하지 않고도 "이 대출이 올바른 차입자에 연결되어 있다"는 것을 확인할 수 있습니다. 원본 PII가 필요한 관리자는 UUID 기반 차입자 조회 인터페이스에서 ?unmask=true를 사용하며, 이는 감사 로그에 기록됩니다.

금액 필드는 저장된 전체 정밀도로 표시됩니다(금액은 소수점 이하 네 자리, interestRateApr는 여섯 자리). 클라이언트는 이를 부동소수점으로 파싱하지 말고 불투명한 10진수 문자열로 다루어야 합니다.

상태 코드

상태발생 조건
200 OK귀하의 조직에서 대출을 찾았습니다.
400 Bad RequestportfolioId가 없거나 형식이 잘못되었거나, externalId에 잘못된 퍼센트 인코딩이 포함되어 있습니다.
404 Not Found지정한 포트폴리오에 대출이 유효한 상태로 존재하지 않거나, 포트폴리오가 다른 조직에 속합니다.

cURL

curl https://app.waafir.io/api/v1/monitoring/loan/loans/L-001?portfolioId=ddf63d12-1234-5678-9abc-def012345678 \
  -H "Authorization: Bearer $WAAFIR_PAT"

GET /api/v1/monitoring/loan/counts

엔터티별 행 수를 조회하며, 포트폴리오나 날짜로 좁히거나 단일 엔터티만 볼 수 있습니다. 소프트 삭제된 행은 제외됩니다.

요청

매개변수위치필수제약 조건
portfolioIdquery아니요UUID. 단일 포트폴리오로 좁힙니다. 생략하면 조직 전체 집계가 반환됩니다.
datequery아니요YYYY-MM-DD. 지정하면 응답에 엔터티별 onDate 건수가 포함됩니다.
entityquery아니요borrowers, loans, scheduled_repayments, actual_payments, collateral, collateral_valuations 중 하나(대소문자 구분 안 함). 지정하면 해당 엔터티만 반환됩니다.

응답 — 200 OK

기본 집계(여섯 가지 엔터티 전체):

{
  "counts": {
    "borrowers": { "total": 1200 },
    "loans": { "total": 3450 },
    "scheduled_repayments": { "total": 41400 },
    "actual_payments": { "total": 32118 },
    "collateral": { "total": 600 },
    "collateral_valuations": { "total": 1840 }
  },
  "date": null,
  "portfolioId": null
}

?date=2026-05-22를 지정하면 각 엔터티에 지정한 날짜에 생성된 행 수인 onDate 건수가 추가됩니다.

{
  "counts": {
    "borrowers": { "total": 1200, "onDate": 0 },
    "loans": { "total": 3450, "onDate": 12 },
    "scheduled_repayments": { "total": 41400, "onDate": 144 },
    "actual_payments": { "total": 32118, "onDate": 1207 },
    "collateral": { "total": 600, "onDate": 0 },
    "collateral_valuations": { "total": 1840, "onDate": 0 }
  },
  "date": "2026-05-22",
  "portfolioId": null
}

?entity=loans를 지정하면 loans 항목만 나타납니다.

상태 코드

상태발생 조건
200 OK쿼리가 파싱되었고 건수가 반환되었습니다.
400 Bad RequestportfolioId, date, entity 중 형식이 잘못된 값이 있습니다.

존재하지 않거나 다른 조직에 속한 portfolioId는 404를 반환하지 않고, 모든 값이 0인 200을 반환합니다. 이는 의도된 동작입니다. 건수 인터페이스는 귀사 데이터를 읽는 것이며, 알 수 없는 포트폴리오는 행이 없는 포트폴리오와 기능적으로 구별되지 않습니다.

cURL

# Full daily reconciliation for one portfolio:
curl "https://app.waafir.io/api/v1/monitoring/loan/counts?portfolioId=ddf63d12-1234-5678-9abc-def012345678&date=2026-05-22" \
  -H "Authorization: Bearer $WAAFIR_PAT"

일반적인 일일 대사

당일 제출을 마친 후의 표준 대사 흐름은 다음과 같습니다.

  1. GET /counts?date=<today>를 호출합니다. 포트폴리오를 지정하고, 각 엔터티의 onDate 건수를 오늘 제출한 건수와 비교합니다. 건수가 제출한 내용과 일치하면 배치가 문제없이 반영된 것입니다.
  2. 불일치가 있으면 해당 행을 개별 조회합니다. GET /loans/{externalId}를 사용합니다. 조회 비용은 낮으며(각각 인덱스 스캔 한 번), 플랫폼이 할당한 UUID를 포함한 표준 행 상태를 반환하므로 이를 이용해 추가로 조사할 수 있습니다.
  3. 행 수준 조사에는 단일 레코드 GET 엔드포인트와 비동기 가져오기의 오류 페이지 조회 엔드포인트를 사용합니다. 이 두 인터페이스가 행별 실패 세부 정보를 제공합니다.

대사 인터페이스는 의도적으로 읽기 전용이며 비용이 낮습니다. 연동의 하트비트이지, 부하를 위한 인터페이스가 아닙니다. 포트폴리오마다 하루에 한두 번 호출하세요. 대사 전용 속도 제한은 없지만, 촘촘한 루프로 폴링하지는 마세요.