كيفية استخدام واجهة برمجة تطبيقات Plaid: دليل المطور 2026

تطبيقات التكنولوجيا المالية اليوم غالبًا ما تعتمد على مزودي الطرف الثالث مثل Plaid لربط الحسابات المصرفية وتحويل بيانات الاعتماد إلى JSON قابل للاستهلاك. Plaid يدعم ربط الحسابات، فحص الرصيد، سجل المعاملات، والتحقق من الهوية لآلاف التطبيقات (Venmo, Robinhood, Chime وغيرها).

جرّب Apidog اليوم

في هذا الدليل ستتعلم، كمطور، كيفية تنفيذ Plaid خطوة بخطوة: من استخراج المفاتيح، إلى تدفق توليد رموز الربط (Link token flow)، وأهم المنتجات التي يجب تفعيلها، وكيفية التعامل مع الأخطاء الأكثر شيوعًا في الإنتاج. ستجد أيضًا خطوات عملية لاختبار كل مرحلة باستخدام Apidog لتقليل التخمين في تكوين الطلبات. للمزيد من التفاصيل التقنية، راجع التوثيق الرسمي لـ Plaid أثناء التنفيذ.

إذا كنت في طور المقارنة بين مزودي الخدمات المصرفية المفتوحة، اطلع على ملخصنا لأفضل واجهات برمجة تطبيقات الخدمات المصرفية المفتوحة. هنا سنركز على Plaid فقط.

TL;DR

• Plaid يربط تطبيقك بأكثر من 12,000 بنك في أمريكا الشمالية وأوروبا.
• تتوفر ثلاث بيئات: sandbox (مجانية بالكامل)، development (100 عنصر حي مجانًا)، production (دفع حسب الاستخدام).
• تدفق الربط: إنشاء link_token (خادم)، تشغيل Plaid Link (عميل)، تبادل public_token بـ access_token (خادم)، استدعاء نقاط النهاية.
• المنتجات الأساسية: Auth، Balance، Transactions، Identity، Investments، Liabilities، Income — فعّل ما تحتاجه لكل عنصر.
• الأخطاء الأكثر شيوعًا: ITEM_LOGIN_REQUIRED و INVALID_CREDENTIALS. استخدم الـ webhooks لمتابعة الحالة.
• حدود المعدل لكل عنصر ولكل عميل. اعتمد على webhooks بدل الاستقصاء المباشر.

ما هو Plaid؟

Plaid هو وسيط تقني بين تطبيقك والبنوك. عندما يدخل المستخدم بيانات البنك عبر Plaid Link، يقوم Plaid بجلب البيانات وتحويلها إلى JSON موحد، دون أن تتعامل أنت مباشرة مع بيانات الاعتماد.

أنت تتعامل مع عنصر (Item) لكل اتصال ببنك. تحصل على access_token يسمح لك بجلب بيانات الحسابات، الأرصدة، وهكذا. عنصر واحد قد يشمل عدة حسابات (جاري، توفير، بطاقة ائتمان).

Plaid يدعم حسابات الأفراد، البطاقات، القروض، الاستثمارات، والرواتب. لا ينفذ عمليات تحويل أموال – لعمليات ACH ستحتاج إلى ربط Plaid Auth مع مزود دفع خارجي. راجع مقالنا حول أفضل واجهات برمجة تطبيقات دفع ACH لمعرفة تفاصيل الربط.

المصادقة والإعداد

الخطوة 1: إنشاء حساب مطور Plaid

1. سجّل في plaid.com وفعل بريدك الإلكتروني.
2. ستجد ثلاث بيئات:
   • Sandbox: بيانات وهمية، مجانية. استخدم user_good/pass_good.
   • Development: اتصال حقيقي، حتى 100 عنصر مجاني.
   • Production: غير محدود، فوترة حسب الاستخدام.

الخطوة 2: احصل على مفاتيحك

1. من لوحة التحكم: Team Settings > Keys.
2. ستحتاج:
   • client_id: ثابت لكل البيئات.
   • secret: يختلف حسب البيئة.
3. خزنها في متغيرات بيئة، لا ترفعها أبدًا إلى git.

الخطوة 3: تثبيت حزمة SDK

npm install plaid

الخطوة 4: تهيئة العميل

import { Configuration, PlaidApi, PlaidEnvironments } from 'plaid';

const config = new Configuration({
  basePath: PlaidEnvironments.sandbox,
  baseOptions: {
    headers: {
      'PLAID-CLIENT-ID': process.env.PLAID_CLIENT_ID,
      'PLAID-SECRET': process.env.PLAID_SECRET,
    },
  },
});

const client = new PlaidApi(config);

عند الترقية للبيئة التالية استبدل PlaidEnvironments.sandbox بـ development أو production.

نقاط النهاية الأساسية

تدفق رمز الربط (Link token)

1. إنشاء link_token (خادم):

const response = await client.linkTokenCreate({
  user: { client_user_id: 'user_123' },
  client_name: 'Your App',
  products: ['auth', 'transactions'],
  country_codes: ['US'],
  language: 'en',
});

const linkToken = response.data.link_token;

curl -X POST https://sandbox.plaid.com/link/token/create \
  -H 'Content-Type: application/json' \
  -d '{
    "client_id": "YOUR_CLIENT_ID",
    "secret": "YOUR_SANDBOX_SECRET",
    "user": { "client_user_id": "user_123" },
    "client_name": "Your App",
    "products": ["auth", "transactions"],
    "country_codes": ["US"],
    "language": "en"
  }'

2. فتح Plaid Link (عميل): أرسل link_token للواجهة الأمامية، مرره إلى SDK. بعد تسجيل المستخدم دخوله، ستحصل على public_token في onSuccess.
3. تبادل public_token (خادم):

const exchange = await client.itemPublicTokenExchange({
  public_token: publicToken,
});

const accessToken = exchange.data.access_token;
const itemId = exchange.data.item_id;

4. استخدام access_token لاستدعاء نقاط النهاية:

const accounts = await client.accountsGet({ access_token: accessToken });
const balance = await client.accountsBalanceGet({ access_token: accessToken });

نقاط نهاية المنتج التي يجب أن تعرفها

• Auth: أرقام الحسابات والتوجيه لـ ACH (/auth/get).
• Balance: أرصدة لحظية (/accounts/balance/get).
• Transactions: حتى 24 شهر من بيانات المعاملات (/transactions/sync).
• Identity: بيانات صاحب الحساب (اسم، بريد، هاتف، عنوان) (/identity/get). في حالات KYC، قارن مع خدمات KYC الأخرى.
• Investments: مقتنيات ومعاملات الاستثمار (/investments/holdings/get).
• Liabilities: قروض الطلاب، بطاقات الائتمان، الرهون (/liabilities/get).
• Income: بيانات الرواتب (/credit/payroll_income/get).

اختبار واجهة برمجة تطبيقات Plaid باستخدام Apidog

خطوة الربط (Link) تحدث في المتصفح، لكن اختبار نقاط النهاية الخلفية بشكل موثوق يتطلب أدوات متخصصة. Apidog يسهّل عليك ذلك:

• استورد مواصفات OpenAPI الخاصة بـ Plaid إلى Apidog، وستجد كل نقاط النهاية مُهيأة مسبقًا مع الأمثلة والرؤوس الصحيحة.
• أنشئ مجموعة متغيرات بيئة (sandbox, production)، حدد client_id، secret، access_token.
• استخدم التسلسل (chaining) لتشغيل linkTokenCreate → sandboxPublicTokenCreate → itemPublicTokenExchange → accountsGet بدون متصفح.
• استعمل الخادم الوهمي في Apidog لتوفير استجابات جاهزة لـ /accounts/get قبل اكتمال تكاملك الخلفي.
• راجع دليلنا حول اختبار API بدون Postman للترحيل، أو حمّل Apidog وابدأ فورًا.

الأخطاء الشائعة وحدود المعدل

تظهر أخطاء Plaid مع error_type، error_code، error_message. عالج الأخطاء التالية تحديدًا:

• INVALID_CREDENTIALS: كلمة مرور خاطئة. أعد ربط الحساب عبر وضع التحديث.
• ITEM_LOGIN_REQUIRED: جلسة المستخدم منتهية (تغيير كلمة مرور البنك أو مصادقة ثنائية). أعد تشغيل Plaid Link في وضع التحديث، وتابع الـ webhook.
• RATE_LIMIT_EXCEEDED: تجاوزت الحد. استخدم retry مع jitter.
• PRODUCT_NOT_READY: البيانات قيد التحميل. أعد المحاولة بعد webhook INITIAL_UPDATE.

Webhooks

• أرسل عنوان الـ webhook عند إنشاء link_token وسيقوم Plaid بإرسال تحديثات POST.
• أهم webhooks: SYNC_UPDATES_AVAILABLE (معاملات جديدة)، ITEM: LOGIN_REQUIRED (إعادة مصادقة)، ITEM: ERROR (فشل دائم).
• تحقق دائمًا من توقيع JWT قبل أي إجراء.

حدود المعدل

• كل نقطة نهاية لها حد معدل لكل عنصر ولكل عميل.
• مثال: /accounts/balance/get = 5 استدعاءات/دقيقة/عنصر في الإنتاج.
• القواعد العملية: اعتمد على webhooks، خزّن الأرصدة مؤقتًا، لا تستدعي Plaid مباشرة في مسارات المستخدم.

تسعير Plaid

• Sandbox: مجاني وغير محدود.
• Development: مجاني حتى 100 عنصر.
• Production:
  • Auth: حوالي 1.50$ لكل حساب مرة واحدة.
  • Balance/Identity: تسعير لكل استدعاء.
  • Transactions: اشتراك شهري لكل عنصر (~0.30$).
  • Investments/Liabilities/Income: رسوم منفصلة لكل عنصر.

أسعار Plaid تفاوضية عند الأحجام الكبيرة. راجع صفحة المنتجات الرسمية للأرقام الأحدث.

الأسئلة الشائعة

• مدة صلاحية access_token؟ غير محدودة حتى يتم الإلغاء من المستخدم أو البنك. خزّنه مشفرًا.
• هل يمكن استخدام Plaid للتحقق من الهوية فقط؟ نعم، عبر Identity، لكن لغرض KYC راجع أيضًا مقارنة Stripe Identity.
• هل Plaid يدعم دول خارج أمريكا؟ نعم: أمريكا، كندا، المملكة المتحدة، الاتحاد الأوروبي. تحقق من دعم كل منتج عند استدعاء /link/token/create.
• ماذا لو غيّر المستخدم كلمة مرور البنك؟ يتحول العنصر إلى ITEM_LOGIN_REQUIRED وتستقبل webhook. شغّل Plaid Link في وضع التحديث.
• هل يمكن اختبار تدفق Link بدون متصفح؟ نعم، استخدم /sandbox/public_token/create لاسترجاع public_token في اختبارات التكامل.
• كيف أستخدم Plaid في بيئة تطوير محلية؟ ضع بيانات sandbox في .env، اربط التطبيق على PlaidEnvironments.sandbox، واستخدم tunneling (ngrok أو Cloudflare Tunnel) لاستقبال webhooks.