Ihre Daten anhand der externen ID abgleichen
Dieses Rezept zeigt, wie Sie den Kreis bei einer Übermittlung schließen: Bestätigen Sie anhand Ihrer eigenen, vom Aufrufer gelieferten Kennung, dass eine bestimmte Zeile angekommen ist, und prüfen Sie, ob die Gesamtzählungen pro Entität dem entsprechen, was Sie übermittelt haben. Beide Lesezugriffe sind auf die Organisation beschränkt und legen nie Daten eines anderen Mandanten offen.
Warum der Abgleich wichtig ist
Sie haben Waafir heute eine NDJSON-Datei mit 1.200 Zahlungen gesendet. Der Import endete mit succeeded und rowCountSucceeded: 1200. Das ist ein Signal. Die Abgleich-Lesezugriffe liefern Ihnen zwei stärkere:
- Stichprobe anhand der Aufrufer-ID – wählen Sie eine Zahlung, die für Ihr Team wichtig ist, rufen Sie sie über Ihre eigene
external_idab und bestätigen Sie, dass die Werte mit Ihrer Übermittlung übereinstimmen. Ihre Kennung ist der maßgebliche Bezug, nicht die interne UUID von Waafir. - Gesamtzählungen pro Entität – bestätigen Sie, dass die Anzahl der aktiven Zeilen des Tages bei Waafir mit der Zählung in Ihrem führenden System übereinstimmt. „Ich habe heute 1.200 Zahlungen übermittelt; laut counts wurden heute 1.200 angelegt. Abgeglichen.“
Die Lesezugriffe sind cache-sicher (Cache-Control: private, no-store bei der Abfrage einzelner Kredite), sodass die Antwort den neuesten Schreibvorgang widerspiegelt. Ein Abgleich unmittelbar nach einem Import liefert den gerade angekommenen Stand.
Die beiden Endpunkte
GET /api/v1/monitoring/loan/loans/{externalId}?portfolioId=…– Abgleich eines einzelnen Kredits anhand Ihrer eigenenexternal_id. Gibt den Kreditdatensatz samt maskiertem Kreditnehmerkontext zurück, sodass Sie ohne zweite Anfrage prüfen können, ob der Kredit dem erwarteten Kreditnehmer zugeordnet ist.GET /api/v1/monitoring/loan/counts?date=YYYY-MM-DD&portfolioId=…&entity=…– Zeilenzählungen pro Entität. Ohneentitywerden Zählungen für alle sechs Entitäten der Kreditdomäne zurückgegeben, mitentitynur für diese eine. Der Parameterdateergänzt neben der Gesamtzählung eineonDate-Zählung.
Beide Endpunkte geben 404 zurück, sowohl für fehlende Zeilen als auch für Zeilen, die in einer anderen Organisation existieren – Waafir bestätigt oder bestreitet nie die Existenz von Daten eines anderen Mandanten.
Das Rezept
# 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)Was Sie überprüfen sollten
Bei der Antwort für einen einzelnen Kredit sollte jedes Feld, das Sie unter Ihrer external_id übermittelt haben, unverändert zurückkommen: principalAmount, currencyCode, interestRateApr, disbursementDate, termMonths, repaymentFrequency, productType, status, metadata. Der Kreditnehmerabschnitt ist gemäß der PII-Richtlinie von Waafir maskiert – name, email, phone und nationalIdLast4 sind bei diesem Endpunkt standardmäßig maskiert; Felder ohne PII (countryCode, dob, gender, incomeBand, employmentStatus) werden unverändert durchgereicht.
Bei der Antwort mit den Zählungen sind die Summen auf Ihre Organisation beschränkt und schließen vorläufig gelöschte (soft-deleted) Zeilen aus. Mit ?date=YYYY-MM-DD enthält der Eintrag jeder Entität neben der Gesamtsumme eine onDate-Zählung – die an diesem Datum angelegten Zeilen. Die onDate-Zählung ist Ihr Signal, dass die Übermittlung übereinstimmt.
Ein 404 beim Endpunkt für einzelne Kredite bedeutet immer, dass der Kredit für Ihre Organisation in diesem Portfolio nicht sichtbar ist. Er existiert möglicherweise gar nicht, oder er existiert unter einer anderen Organisation; die Antwort unterscheidet dies absichtlich nicht.