Waafir
هذه الصفحة ترجمة آلية في انتظار المراجعة البشرية. قد تحتوي على أخطاء.

مطابقة بياناتك بالمعرّف الخارجي

توضّح هذه الوصفة كيفية إكمال الحلقة في عملية إرسال للاستيعاب: التأكد من وصول صف محدد باستخدام المعرّف الذي قدّمته أنت بصفتك المستدعي، والتحقق من أن الأعداد الإجمالية لكل كيان تطابق ما أرسلته. ونطاق كلتا القراءتين مقصور على المؤسسة، ولا تكشفان أبدًا بيانات مستأجر آخر.

لماذا تهم المطابقة

أرسلت إلى Waafir اليوم ملف NDJSON يحتوي على 1,200 دفعة. انتهى الاستيراد بالحالة succeeded مع rowCountSucceeded: 1200. هذه إشارة واحدة. وتمنحك قراءات المطابقة إشارتين أقوى:

  • فحص عيّني بمعرّف المستدعي — اختر دفعة تهمّ فريقك، وابحث عنها بقيمة external_id الخاصة بك، وتأكّد من أن القيم تطابق ما أرسلته. معرّفك هو المرجع المعتمد، لا معرّف UUID الداخلي في Waafir.
  • الأعداد الإجمالية لكل كيان — تأكّد من أن عدد الصفوف الحيّة لليوم لدى Waafir يطابق العدد في مصدر الحقيقة لديك. "أرسلتُ 1,200 دفعة اليوم؛ وتقول الأعداد إن لديّ 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 افتراضيًا في نقطة النهاية هذه؛ أما الحقول غير الشخصية (countryCode وdob وgender وincomeBand وemploymentStatus) فتمرّ كما هي.

في استجابة الأعداد، تقتصر الإجماليات على مؤسستك وتستثني الصفوف المحذوفة حذفًا ناعمًا. ومع ?date=YYYY-MM-DD، يتضمن مُدخل كل كيان عددًا onDate — أي الصفوف التي أُنشئت في ذلك التاريخ — إلى جانب الإجمالي منذ البداية. والعدد onDate هو إشارتك على مطابقة الإرسال.

تعني الاستجابة 404 في نقطة نهاية القرض المنفرد دائمًا أن القرض غير مرئي لمؤسستك في تلك المحفظة. فقد لا يكون موجودًا على الإطلاق، أو قد يكون موجودًا تحت مؤسسة أخرى؛ والاستجابة لا تميّز بين الحالتين عمدًا.