Rapprocher vos données par identifiant externe
Cette recette montre comment boucler la boucle d'une soumission d'ingestion : confirmer qu'une ligne précise a bien été enregistrée à l'aide de votre propre identifiant fourni par l'appelant, et vérifier que les décomptes agrégés par entité correspondent à ce que vous avez soumis. Les deux lectures sont limitées à votre organisation et n'exposent jamais les données d'un autre tenant.
Pourquoi le rapprochement est important
Vous avez envoyé aujourd'hui à Waafir un fichier NDJSON contenant 1 200 paiements. L'import s'est terminé en succeeded avec rowCountSucceeded: 1200. C'est un premier signal. Les lectures de rapprochement vous en donnent deux plus solides :
- Contrôle ponctuel par identifiant de l'appelant — choisissez un paiement qui compte pour votre équipe, recherchez-le par votre propre
external_idet confirmez que les valeurs correspondent à ce que vous avez soumis. Votre identifiant est la référence canonique, et non l'UUID interne de Waafir. - Décomptes agrégés par entité — confirmez que le décompte des lignes actives du jour chez Waafir correspond au décompte de votre source de référence. « J'ai soumis 1 200 paiements aujourd'hui ; les décomptes indiquent 1 200 créations aujourd'hui. Rapproché. »
Les lectures sont sûres vis-à-vis des caches (Cache-Control: private, no-store sur la recherche par prêt), de sorte que la réponse reflète la dernière écriture. Un rapprochement effectué juste après un import renvoie l'état tout juste enregistré.
Les deux endpoints
GET /api/v1/monitoring/loan/loans/{externalId}?portfolioId=…— rapprochement d'un prêt unique par votre propreexternal_id. Renvoie le corps du prêt ainsi que le contexte masqué de l'emprunteur, ce qui vous permet de vérifier que le prêt est rattaché à l'emprunteur attendu sans seconde requête.GET /api/v1/monitoring/loan/counts?date=YYYY-MM-DD&portfolioId=…&entity=…— décomptes de lignes par entité. Sansentity, il renvoie les décomptes des six entités du domaine des prêts ; avecentity, il ne renvoie que celle-ci. Le paramètredateajoute un décompteonDateà côté du décompte total.
Les deux endpoints renvoient 404 pour les lignes absentes et pour les lignes qui existent dans une autre organisation — Waafir ne confirme ni n'infirme jamais l'existence des données d'un autre tenant.
La recette
# 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)Ce qu'il faut vérifier
Pour la réponse sur un prêt unique, chaque champ que vous avez soumis sous votre external_id doit revenir à l'identique : principalAmount, currencyCode, interestRateApr, disbursementDate, termMonths, repaymentFrequency, productType, status, metadata. La section emprunteur est masquée conformément à la politique de Waafir en matière de PII — name, email, phone et nationalIdLast4 sont masqués par défaut sur cet endpoint ; les champs non PII (countryCode, dob, gender, incomeBand, employmentStatus) sont transmis tels quels.
Pour la réponse des décomptes, les totaux sont limités à votre organisation et excluent les lignes supprimées logiquement. Avec ?date=YYYY-MM-DD, l'entrée de chaque entité comprend un décompte onDate — les lignes créées à cette date — à côté du total. Le décompte onDate est votre signal de correspondance avec la soumission.
Un 404 sur l'endpoint de prêt unique signifie toujours que le prêt n'est pas visible pour votre organisation dans ce portefeuille. Il peut ne pas exister du tout, ou exister sous une autre organisation ; la réponse ne fait volontairement pas la distinction.