外部IDでデータを照合する
このレシピでは、取り込みの送信結果を最終確認する方法を紹介します。呼び出し元が指定した独自の識別子で特定の行が登録されたことを確認し、エンティティごとの集計件数が送信した内容と一致することを検証します。どちらの読み取りも組織にスコープが限定されており、他のテナントのデータが公開されることはありません。
照合が重要な理由
今日、1,200件の支払いを含むNDJSONファイルをWaafirに送信したとします。インポートは rowCountSucceeded: 1200 で succeeded となりました。これは1つのシグナルです。照合のための読み取りでは、さらに確かなシグナルが2つ得られます。
- 呼び出し元IDによる抜き取り確認:チームが重視する支払いを1件選び、お客様独自の
external_idで検索して、値が送信した内容と一致することを確認します。正規のハンドルはWaafirの内部UUIDではなく、お客様の識別子です。 - エンティティごとの集計件数:その日の有効な行についてのWaafirの件数が、お客様の信頼できる情報源の件数と一致することを確認します。「今日は1,200件の支払いを送信し、件数APIでも今日作成されたのは1,200件。照合完了」という具合です。
これらの読み取りはキャッシュの影響を受けない(ローン単位の検索では Cache-Control: private, no-store)ため、レスポンスには最新の書き込みが反映されます。インポート直後に照合すると、登録されたばかりの状態が返されます。
2つのエンドポイント
GET /api/v1/monitoring/loan/loans/{externalId}?portfolioId=…:お客様独自のexternal_idによる単一ローンの照合です。ローンの本文に加えて、マスクされた借り手の情報も返されるため、2回目のリクエストを行わなくても、ローンが想定どおりの借り手に紐づいていることを確認できます。GET /api/v1/monitoring/loan/counts?date=YYYY-MM-DD&portfolioId=…&entity=…:エンティティごとの行数です。entityを指定しない場合は、ローン領域の6つのエンティティすべての件数が返されます。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 が返された場合、そのポートフォリオにおいて、そのローンがお客様の組織から参照できないことを常に意味します。ローンがまったく存在しない可能性も、別の組織に存在する可能性もありますが、レスポンスはその区別を意図的に示しません。