المصادقة | توثيق جسر ألفابت

كل طلب إلى /api/v1 يحمل مفتاح API الخاص بتطبيقك كرمز Bearer:

bash

curl -s "$BRIDGE_URL/api/v1/payments/01a13c8c-8592-70f4-9ef9-d3767e74d54c" \
  -H "Authorization: Bearer pk_test_a1B2c3D4e5F6_..." \
  -H "Accept: application/json"

أرسل المفتاح كاملاً كما ظهر لك. الطلبات والردود بصيغة JSON: أرسل Content-Type: application/json مع أي جسم طلب، وAccept: application/json مع كل طلب.

استدعِ الواجهة البرمجية من خادمك فقط. مفتاح API الموجود في متصفح أو تطبيق جوال يمكن لأي مستخدم أن ينسخه.

المفاتيح التجريبية والفعلية

المفتاح	يبدأ بـ	تذهب الدفعات إلى
تجريبي	`pk_test_`	المحاكي المدمج، بلا أموال حقيقية.
فعلي	`pk_live_`	حساب المزوّد المرتبط بتطبيقك، بأموال حقيقية.

المفتاح يحدد وضع كل ما تفعله به. الدفعة المنشأة بمفتاح تجريبي دفعة تجريبية، ولا يستطيع جلبها أو إلغاءها أو استردادها إلا مفتاح تجريبي، والأمر نفسه في الوضع الفعلي.

الحصول على المفاتيح وتبديلها

ينشئ مالك التطبيق المفاتيح من لوحة تحكم التطبيق، ضمن «مفاتيح API». ويمكن لفريق ألفابت أيضاً إصدار مفاتيح لتطبيقك.
يظهر المفتاح مرة واحدة عند إنشائه. بعدها لا تعرض لوحة التحكم إلا بدايته وآخر أربعة أحرف منه، مثل pk_test_a1B2c3D4e5F6_…wxyz. إن فقدت المفتاح فأنشئ مفتاحاً جديداً.
تبديل المفتاح ينشئ مفتاحاً جديداً ويلغي القديم فوراً. حدّث خوادمك بالمفتاح الجديد قبل التبديل، وإلا فتوقع ردود 401 حتى تفعل.
المفتاح الملغى يرد بـ 401 invalid_api_key.

عندما يُرفض المفتاح

HTTP	`error.code`	المعنى
401	`unauthenticated`	لا توجد ترويسة `Authorization: Bearer …`.
401	`invalid_api_key`	المفتاح غير معروف أو أُلغي أو تم تبديله.
403	`application_disabled`	التطبيق متوقف. تواصل مع ألفابت.
403	`application_pending_review`	لم تفعّل ألفابت التطبيق بعد.
403	`application_suspended`	علّقت ألفابت التطبيق.
403	`ip_not_allowed`	لتطبيقك قائمة عناوين IP مسموحة، وهذا الطلب جاء من عنوان آخر.

القائمة الكاملة في صفحة الأخطاء.

قائمة عناوين IP المسموحة

يمكن لألفابت أن تحصر استخدام مفاتيح تطبيقك بقائمة من عناوين IP أو نطاقاتها لخوادمك. عند ضبط القائمة، يرد أي طلب من عنوان آخر بـ 403 ip_not_allowed. اطلب من ألفابت إضافة العنوان قبل نقل خوادمك.

حد الطلبات

لكل مفتاح 120 طلباً في الدقيقة. بعد ذلك ترد الواجهة بـ 429 rate_limited مع ترويسة Retry-After تذكر عدد الثواني التي يجب انتظارها.

سرّ توقيع إشعارات Webhook

تُوقَّع إشعارات Webhook بسرّ منفصل يبدأ بـ whsec_. هذا السر ليس مفتاح API ولا يُرسل في أي طلب. راجع إشعارات Webhook.