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

외부 ID로 데이터 대사하기

이 레시피는 수집 제출의 확인 절차를 마무리하는 방법을 보여 줍니다. 호출자가 제공한 자체 식별자로 특정 행이 반영되었는지 확인하고, 엔터티별 집계 건수가 제출한 내용과 일치하는지 검증합니다. 두 읽기 모두 조직 범위로 한정되며, 다른 테넌트의 데이터를 절대 노출하지 않습니다.

대사가 중요한 이유

오늘 Waafir에 납입 1,200건이 담긴 NDJSON 파일을 보냈습니다. 가져오기는 rowCountSucceeded: 1200과 함께 succeeded로 끝났습니다. 이것이 하나의 신호입니다. 대사 읽기는 그보다 강력한 두 가지 신호를 제공합니다.

  • 호출자 ID로 표본 확인 — 팀이 중요하게 여기는 납입 건을 골라 자체 external_id로 조회하고, 값이 제출한 내용과 일치하는지 확인합니다. 기준 핸들은 Waafir의 내부 UUID가 아니라 사용자의 식별자입니다.
  • 엔터티별 집계 건수 — 해당 날짜의 실제 행에 대한 Waafir의 건수가 사용자의 기준 원본 건수와 일치하는지 확인합니다. "오늘 납입 1,200건을 제출했고, counts에서 오늘 생성된 건이 1,200건이라고 나온다. 대사 완료."

이 읽기는 캐시에 안전하므로(대출별 조회에 Cache-Control: private, no-store) 응답이 최신 쓰기를 반영합니다. 가져오기 직후 대사하면 방금 반영된 상태가 반환됩니다.

두 개의 엔드포인트

  • GET /api/v1/monitoring/loan/loans/{externalId}?portfolioId=… — 자체 external_id로 단일 대출을 대사합니다. 대출 본문과 함께 마스킹된 차입자 정보를 반환하므로, 두 번째 요청 없이 대출이 예상한 차입자에 연결되어 있는지 확인할 수 있습니다.
  • GET /api/v1/monitoring/loan/counts?date=YYYY-MM-DD&portfolioId=…&entity=… — 엔터티별 행 수입니다. entity가 없으면 여섯 가지 대출 도메인 엔터티 전체의 건수를 반환하고, entity가 있으면 해당 엔터티만 반환합니다. date 매개변수를 지정하면 전체 기간 건수와 함께 onDate 건수가 추가됩니다.

두 엔드포인트 모두 존재하지 않는 행과 다른 조직에 존재하는 행에 대해 404를 반환합니다. Waafir는 다른 테넌트 데이터의 존재 여부를 확인해 주거나 부인하지 않습니다.

레시피

# curl — reconcile a single loan and verify per-entity counts
set -euo pipefail

PAT="${WAAFIR_PAT}"
BASE_URL="${WAAFIR_BASE_URL:-https://app.waafir.io}"
PORTFOLIO_ID="${WAAFIR_PORTFOLIO_ID}"
EXTERNAL_LOAN_ID="L-2026-05-22-1234"
TODAY="2026-05-22"

# Step 1 — single-loan reconciliation. The external_id is URL-encoded
# automatically by curl when passed as a positional path segment.
curl -fsS \
  "${BASE_URL}/api/v1/monitoring/loan/loans/${EXTERNAL_LOAN_ID}?portfolioId=${PORTFOLIO_ID}" \
  -H "Authorization: Bearer ${PAT}" \
  | jq '{loan: {externalId: .loan.externalId, principalAmount: .loan.principalAmount, status: .loan.status, disbursementDate: .loan.disbursementDate}, borrower: {externalId: .borrower.externalId, name: .borrower.name, countryCode: .borrower.countryCode}}'

# Step 2 — full per-entity counts for the portfolio.
curl -fsS \
  "${BASE_URL}/api/v1/monitoring/loan/counts?portfolioId=${PORTFOLIO_ID}&date=${TODAY}" \
  -H "Authorization: Bearer ${PAT}" \
  | jq

# Step 3 — counts for just the payments entity (narrower request).
curl -fsS \
  "${BASE_URL}/api/v1/monitoring/loan/counts?portfolioId=${PORTFOLIO_ID}&date=${TODAY}&entity=actual_payments" \
  -H "Authorization: Bearer ${PAT}" \
  | jq
// TypeScript — reconcile a single loan and verify per-entity counts
const PAT = process.env.WAAFIR_PAT!;
const BASE_URL = process.env.WAAFIR_BASE_URL ?? "https://app.waafir.io";
const portfolioId = process.env.WAAFIR_PORTFOLIO_ID!;
const externalLoanId = "L-2026-05-22-1234";
const today = "2026-05-22";

const auth = { Authorization: `Bearer ${PAT}` };

// Step 1 — single-loan reconciliation.
const loanRes = await fetch(
    `${BASE_URL}/api/v1/monitoring/loan/loans/${encodeURIComponent(externalLoanId)}?portfolioId=${portfolioId}`,
    { headers: auth },
);
if (loanRes.status === 404) throw new Error(`loan ${externalLoanId} not found in portfolio ${portfolioId}`);
if (!loanRes.ok) throw new Error(`reconcile failed: ${loanRes.status}`);
const loanBody = (await loanRes.json()) as {
    loan: { externalId: string; principalAmount: string; status: string; disbursementDate: string };
    // borrower may be null if a referential-integrity edge case dropped
    // the borrower row; the response is a partial projection in that case.
    borrower: {
        externalId: string;
        name: string;            // masked (e.g. "M*** S. L."), empty when absent
        countryCode: string | null;
    } | null;
};
console.log({
    loan: {
        externalId: loanBody.loan.externalId,
        principalAmount: loanBody.loan.principalAmount,
        status: loanBody.loan.status,
        disbursementDate: loanBody.loan.disbursementDate,
    },
    borrower: loanBody.borrower
        ? {
              externalId: loanBody.borrower.externalId,
              name: loanBody.borrower.name,
              countryCode: loanBody.borrower.countryCode,
          }
        : null,
});

// Step 2 — full per-entity counts.
const countsRes = await fetch(
    `${BASE_URL}/api/v1/monitoring/loan/counts?portfolioId=${portfolioId}&date=${today}`,
    { headers: auth },
);
console.log("counts:", await countsRes.json());

// Step 3 — narrow to a single entity.
const paymentsRes = await fetch(
    `${BASE_URL}/api/v1/monitoring/loan/counts?portfolioId=${portfolioId}&date=${today}&entity=actual_payments`,
    { headers: auth },
);
console.log("payments:", await paymentsRes.json());
# python — reconcile a single loan and verify per-entity counts
import os
import urllib.parse
import requests

PAT = os.environ["WAAFIR_PAT"]
BASE_URL = os.environ.get("WAAFIR_BASE_URL", "https://app.waafir.io")
portfolio_id = os.environ["WAAFIR_PORTFOLIO_ID"]
external_loan_id = "L-2026-05-22-1234"
today = "2026-05-22"

auth = {"Authorization": f"Bearer {PAT}"}

# Step 1 — single-loan reconciliation. external_id can contain hyphens
# and other URL-safe chars; encode defensively in case yours contain slashes.
encoded = urllib.parse.quote(external_loan_id, safe="")
loan = requests.get(
    f"{BASE_URL}/api/v1/monitoring/loan/loans/{encoded}",
    params={"portfolioId": portfolio_id},
    headers=auth,
    timeout=30,
)
if loan.status_code == 404:
    raise SystemExit(f"loan {external_loan_id} not found in portfolio {portfolio_id}")
loan.raise_for_status()
body = loan.json()
print({
    "loan": {
        "externalId": body["loan"]["externalId"],
        "principalAmount": body["loan"]["principalAmount"],
        "status": body["loan"]["status"],
        "disbursementDate": body["loan"]["disbursementDate"],
    },
    "borrower": {
        "externalId": body["borrower"]["externalId"],
        "name": body["borrower"]["name"],
        "countryCode": body["borrower"]["countryCode"],
    },
})

# Step 2 — full per-entity counts.
counts = requests.get(
    f"{BASE_URL}/api/v1/monitoring/loan/counts",
    params={"portfolioId": portfolio_id, "date": today},
    headers=auth,
    timeout=30,
).json()
print("counts:", counts)

# Step 3 — narrow to one entity.
payments = requests.get(
    f"{BASE_URL}/api/v1/monitoring/loan/counts",
    params={"portfolioId": portfolio_id, "date": today, "entity": "actual_payments"},
    headers=auth,
    timeout=30,
).json()
print("payments:", payments)

확인할 사항

단일 대출 응답에서는 external_id로 제출한 모든 필드가 그대로 돌아와야 합니다: principalAmount, currencyCode, interestRateApr, disbursementDate, termMonths, repaymentFrequency, productType, status, metadata. 차입자 섹션은 Waafir의 PII 정책에 따라 마스킹됩니다. 이 엔드포인트에서는 name, email, phone, nationalIdLast4가 기본적으로 마스킹되며, PII가 아닌 필드(countryCode, dob, gender, incomeBand, employmentStatus)는 그대로 전달됩니다.

건수 응답에서 합계는 사용자의 조직으로 범위가 한정되며 소프트 삭제된 행은 제외됩니다. ?date=YYYY-MM-DD를 지정하면 각 엔터티 항목에 전체 기간 합계와 함께 onDate 건수(해당 날짜에 생성된 행)가 포함됩니다. onDate 건수가 제출 내용과 일치하는지 보여 주는 신호입니다.

단일 대출 엔드포인트의 404는 항상 해당 포트폴리오에서 사용자의 조직이 그 대출을 볼 수 없다는 뜻입니다. 대출이 아예 존재하지 않을 수도 있고, 다른 조직에 존재할 수도 있습니다. 응답은 의도적으로 이 둘을 구분하지 않습니다.