Conciliar sus datos por ID externo
Esta receta muestra cómo cerrar el ciclo de un envío de ingesta: confirmar que una fila concreta se ha registrado mediante su propio identificador proporcionado por el cliente, y verificar que los recuentos agregados por entidad coinciden con lo que envió. Ambas lecturas están limitadas a la organización y nunca exponen datos de otro tenant.
Por qué importa la conciliación
Hoy ha enviado a Waafir un archivo NDJSON con 1.200 pagos. La importación terminó como succeeded con rowCountSucceeded: 1200. Esa es una señal. Las lecturas de conciliación le dan dos más sólidas:
- Comprobación puntual por ID del cliente: elija un pago que le interese a su equipo, búsquelo por su propio
external_idy confirme que los valores coinciden con lo que envió. Su identificador es la referencia canónica, no el UUID interno de Waafir. - Recuentos agregados por entidad: confirme que el recuento de filas activas del día en Waafir coincide con el recuento de su fuente de verdad. «Envié 1.200 pagos hoy; los recuentos dicen que tengo 1.200 creados hoy. Conciliado».
Las lecturas son seguras respecto a la caché (Cache-Control: private, no-store en la consulta por préstamo), por lo que la respuesta refleja la escritura más reciente. Conciliar inmediatamente después de una importación devuelve el estado recién registrado.
Los dos endpoints
GET /api/v1/monitoring/loan/loans/{externalId}?portfolioId=…: conciliación de un único préstamo por su propioexternal_id. Devuelve el cuerpo del préstamo junto con el contexto enmascarado del prestatario, para que pueda verificar que el préstamo está asociado al prestatario esperado sin una segunda solicitud.GET /api/v1/monitoring/loan/counts?date=YYYY-MM-DD&portfolioId=…&entity=…: recuentos de filas por entidad. Sinentitydevuelve los recuentos de las seis entidades del dominio de préstamos; conentitydevuelve solo esa. El parámetrodateañade un recuentoonDatejunto al recuento histórico total.
Ambos endpoints devuelven 404 para las filas inexistentes y para las filas que existen en otra organización: Waafir nunca confirma ni niega la existencia de datos de otro tenant.
La receta
# 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)Qué verificar
En la respuesta de un único préstamo, cada campo que envió bajo su external_id debe volver idéntico: principalAmount, currencyCode, interestRateApr, disbursementDate, termMonths, repaymentFrequency, productType, status, metadata. La sección del prestatario se enmascara según la política de PII de Waafir: name, email, phone y nationalIdLast4 se enmascaran por defecto en este endpoint; los campos que no son PII (countryCode, dob, gender, incomeBand, employmentStatus) se devuelven sin cambios.
En la respuesta de recuentos, los totales se limitan a su organización y excluyen las filas eliminadas lógicamente (soft delete). Con ?date=YYYY-MM-DD, la entrada de cada entidad incluye un recuento onDate —las filas creadas en esa fecha— junto al total histórico. El recuento onDate es su señal de que coincide con el envío.
Un 404 en el endpoint de un único préstamo siempre significa que el préstamo no es visible para su organización en esa cartera. Puede que no exista en absoluto o que exista en otra organización; la respuesta intencionadamente no lo distingue.