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

تطبيقات التكنولوجيا المالية نادرًا ما تبدأ من الصفر بعد الآن. عندما يربط المستخدم حسابًا جاريًا بتطبيقك، فمن المرجح أن يكون Plaid في المنتصف، حيث يترجم عمليات تسجيل الدخول المصرفية إلى JSON نظيف يمكن لخلفيتك استخدامه. تدعم واجهة برمجة تطبيقات Plaid ربط الحسابات، وفحص الأرصدة، وسجل المعاملات، والتحقق من الهوية لآلاف التطبيقات بما في ذلك Venmo و Robinhood و Chime.

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

الخدمات المصرفية المفتوحة هي مجال مزدحم، و 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).
• أكثر أخطاء الإنتاج شيوعًا هي ITEM_LOGIN_REQUIRED وINVALID_CREDENTIALS. تخبرك الـ Webhooks عندما يحتاج عنصر (Item) إلى الاهتمام.
• حدود المعدل (Rate limits) هي لكل عنصر ولكل عميل. قم بتجميع عمليات القراءة واستمع إلى الـ Webhooks بدلاً من الاستقصاء (polling).

ما هو Plaid؟

Plaid هي شركة بنية تحتية للتكنولوجيا المالية مقرها الولايات المتحدة وتقع بين تطبيقك وبنك المستخدم. عندما يدخل المستخدم بيانات اعتماده المصرفية في Plaid Link، يتصل Plaid بالبنك (من خلال واجهات برمجة تطبيقات الخدمات المصرفية المفتوحة الرسمية حيثما توفرت، أو مواقع الويب المصرفية التي تم هندستها عكسيًا حيثما لم تتوفر)، ويسحب البيانات المطلوبة، ويعيد تنسيقها، ويسلمك استجابة JSON متسقة بغض النظر عن البنك الذي جاءت منه.

أنت لا ترى أو تخزن أبدًا بيانات اعتماد المستخدم المصرفية. يحتفظ Plaid بالاتصال، والذي يسميه عنصرًا (Item)، ويمنحك access_token يمثل إذنًا للاستعلام عن هذا العنصر. عنصر واحد (Item) يساوي مجموعة واحدة من بيانات الاعتماد في مؤسسة مالية واحدة، وقد يتضمن حسابات متعددة (جارٍ، توفير، بطاقة ائتمان).

يغطي Plaid الحسابات الجارية والتوفير للمستهلكين، وبطاقات الائتمان، والقروض، وحسابات الاستثمار، وبيانات الرواتب. لا يقوم بتحويل الأموال بمفرده؛ لتحويلات ACH، عادة ما تقرن Plaid Auth بمعالج دفع منفصل. يشرح مقالنا عن أفضل واجهات برمجة تطبيقات دفع ACH كيف يبدو هذا الاقتران عادة.

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

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

اشترك في plaid.com وتحقق من بريدك الإلكتروني. ستصل إلى لوحة تحكم Plaid مع ثلاث بيئات مجهزة بالفعل:

• بيئة الاختبار (Sandbox): مؤسسات وهمية، مستخدمون وهميون، بدون تكلفة. استخدم user_good / pass_good لتسجيل الدخول.
• بيئة التطوير (Development): اتصالات بنكية حقيقية، بحد أقصى 100 عنصر (Item) مباشر، مجانية.
• بيئة الإنتاج (Production): اتصالات حقيقية، غير محدودة، فوترة حسب الاستخدام.

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

من لوحة التحكم، انتقل إلى إعدادات الفريق (Team Settings) > المفاتيح (Keys). تحتاج إلى قيمتين:

• client_id: هو نفسه عبر جميع البيئات
• secret: يختلف حسب البيئة (اختبار، تطوير، إنتاج)

قم بتخزين هذه في متغيرات البيئة. لا تقم أبدًا بتضمينها في git.

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

توجد حزمة SDK الرسمية لـ Node.js على github.com/plaid/plaid-node.

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)

يتبع كل تكامل لـ Plaid نفس الخطوات الأربع. تقوم بالخطوتين 1 و 3 على جانب الخادم؛ يتعامل Plaid Link مع الخطوة 2 في متصفح المستخدم أو تطبيق الهاتف المحمول.

الخطوة 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:

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 إلى الواجهة الأمامية الخاصة بك وقم بتمريره إلى Plaid Link SDK. يختار المستخدم بنكه، يسجل الدخول، ويعيد Plaid 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;

قم بتخزين accessToken على جانب الخادم، وربطه بالمستخدم الخاص بك. هذا الرمز طويل الأمد وهو ما تستخدمه لكل استدعاء مستقبلي.

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

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) تُرجع بيانات الرواتب من خلال Plaid Income (/credit/payroll_income/get).

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

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

استورد مواصفات OpenAPI الخاصة بـ Plaid إلى Apidog وستحصل على كل نقطة نهاية مهيأة مسبقًا بأنواعها، وأمثلة لهياكل البيانات، ورؤوس المصادقة الصحيحة. يمكنك إنشاء مجموعة متغيرات بيئة اختبار (sandbox) (client_id، secret، access_token) والتبديل إلى الإنتاج بنقرة واحدة. تسمح لك الطلبات المتسلسلة بتشغيل linkTokenCreate → sandboxPublicTokenCreate → itemPublicTokenExchange → accountsGet في تدفق واحد، حتى تتمكن من التحقق من المصافحة الكاملة بدون متصفح.

يعتبر خادم Apidog الوهمي مفيدًا عندما يحتاج فريق الواجهة الأمامية إلى استجابات /accounts/get قبل اكتمال تكامل الواجهة الخلفية الخاصة بك. إذا كنت تنتقل من أداة أخرى، فإن دليلنا حول اختبار واجهة برمجة التطبيقات بدون Postman في عام 2026 يغطي عملية الترحيل بالتفصيل. قم بتنزيل Apidog ووجهه إلى مواصفات Plaid للبدء.

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

تأتي أخطاء Plaid مصحوبة بـ error_type، وerror_code، وerror_message قابلة للقراءة. تعامل مع هذه الأربعة في بيئة الإنتاج:

• INVALID_CREDENTIALS: أدخل المستخدم كلمة مرور خاطئة في البنك. اطلب منهم المحاولة مرة أخرى عبر وضع تحديث الرابط (Link update mode).
• ITEM_LOGIN_REQUIRED: ألغى البنك الجلسة (تغيير كلمة المرور، تدوير المصادقة متعددة العوامل). قم بتشغيل الرابط في وضع التحديث لإعادة المصادقة. تعرف على ذلك من خلال webhook، وليس استدعاء فاشل.
• RATE_LIMIT_EXCEEDED: تجاوزت حدًا لكل عنصر (Item) أو لكل نقطة نهاية. تراجع، ثم أعد المحاولة بتقطع (jitter).
• PRODUCT_NOT_READY: لا تزال بيانات المعاملات قيد السحب. أعد المحاولة بعد تشغيل webhook INITIAL_UPDATE.

Webhooks

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

حدود المعدل

يفرض Plaid حدودًا للمعدل لكل عنصر (Item) ولكل نقطة نهاية. على سبيل المثال، يبلغ الحد الأقصى لـ /accounts/balance/get حوالي 5 استدعاءات في الدقيقة لكل عنصر في الإنتاج. تنطبق أيضًا حدود مجمعة على مستوى العميل على نقاط النهاية ذات الاستخدام الكثيف. القاعدة العملية: استقصاء الـ webhooks، وتخزين الأرصدة مؤقتًا لبضع دقائق، وعدم استدعاء Plaid أبدًا من مسار طلب يواجه المستخدم.

تسعير Plaid

يستخدم Plaid تسعيرًا متدرجًا يدفع لكل استدعاء واجهة برمجة تطبيقات في الإنتاج. التقدير التقريبي:

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

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

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

كم تدوم صلاحية access_token؟إلى أجل غير مسمى، حتى يلغي المستخدم الوصول أو يلغي البنك الجلسة. قم بتخزينه مشفرًا ولا تجعله ينتهي صلاحيته من جانبك.

هل يمكنني استخدام Plaid للتحقق من الهوية وحده؟يمكنك استخدام Plaid Identity، ولكن إذا كانت حاجتك الأساسية هي KYC فقد يكون من الأفضل لك استخدام منتج تحقق مخصص. نغطي المقايضات في دليلنا حول كيفية استخدام واجهة برمجة تطبيقات Stripe Identity.

هل يدعم Plaid دولًا خارج الولايات المتحدة؟نعم. يغطي Plaid الولايات المتحدة وكندا والمملكة المتحدة ومعظم دول الاتحاد الأوروبي. يختلف دعم البلدان حسب المنتج؛ تحقق من معلمة رموز البلدان في استدعاء /link/token/create.

ماذا يحدث إذا قام المستخدم بتغيير كلمة مرور حسابه المصرفي؟ينتقل العنصر (Item) إلى حالة ITEM_LOGIN_REQUIRED وتتلقى webhook. قم بتشغيل Plaid Link في وضع التحديث وسيعيد المستخدم المصادقة دون فقدان access_token الخاص به.

هل يمكنني اختبار تدفق الرابط (Link flow) بدون متصفح حقيقي؟نعم. تتجاوز نقطة النهاية /sandbox/public_token/create الرابط بالكامل وتُرجع public_token يمكنك تبادله. استخدمها لاختبارات التكامل التلقائية.

كيف أتعامل مع Plaid في بيئة التطوير المحلية؟احتفظ بـ secret لبيئة الاختبار (sandbox) في ملف .env الخاص بك وقم بربط بيئة التطوير الخاصة بك بـ PlaidEnvironments.sandbox. استخدم النفق (tunneling) (مثل ngrok، Cloudflare Tunnel) لاستقبال الـ webhooks محليًا.