مفتاح API أم تطبيق OAuth؟

هناك طريقتان للوصول إلى بيانات شركة في أهلاً حمد. كلتاهما تستدعي نفس نقاط النهاية بنفس الصلاحيات، والفرق في من يُصدر بيانات الاعتماد وكيف يوافق صاحب البيانات.

استخدم مفتاح API عندما

• تبني تكاملاً لشركتك أنت (برنامج داخلي، أو مزامنة مع نظامك المحاسبي).
• تعمل مع عميل واحد أو عدد قليل جداً من العملاء في مرحلة تجريبية.
• تريد البدء اليوم: المفاتيح وشركات التجربة متاحة الآن.

المفتاح يخص شركة واحدة، ويحمل صلاحيات ثابتة، ويظهر مرة واحدة عند إنشائه. ينشئه مستخدم لديه صلاحية integrations.manage (المدير التنفيذي أو مدير الموارد البشرية افتراضياً). مفاتيح ah_test_ لشركات التجربة وah_live_ للشركات الحقيقية. راجع البدء السريع.

ابنِ تطبيق OAuth عندما

• منتجك (نقاط بيع، محاسبة، بنك، أو أداة موارد بشرية) سيتصل بشركات كثيرة.
• لا تريد أن ينسخ كل عميل مفتاحاً سرياً ويرسله إليك.
• تريد أن يرى العميل تطبيقك باسمه وشعاره، وأن يلغي وصوله بنفسه.

كيف سيعمل

1. تنشئ مؤسسة مطوّر (منفصلة عن شركات العملاء) ثم تطبيقاً فيها: معرّف عميل وسرّ عميل (يظهر مرة واحدة ويُخزَّن مُجزَّأً ويمكن تدويره)، وروابط إعادة توجيه محددة بدقة، والصلاحيات التي تطلبها، وبيانات العرض بالعربية والإنجليزية.
2. تطبيقك في وضع التطوير يتصل فقط بشركات التجربة التي تملكها مؤسستك. الاتصال بشركات حقيقية يتطلب نشر التطبيق بعد مراجعته، أو إذناً صريحاً لعميل تجريبي محدد.
3. تعيد توجيه مستخدم العميل إلى /oauth/authorize. مستخدم لديه صلاحية integrations.manage يختار الشركة، ويرى تطبيقك وصلاحياته، ويوافق.
4. تستبدل رمز التفويض برمز وصول ورمز تحديث عبر /oauth/token (رمز تفويض مع PKCE بطريقة S256). رموز التحديث تتجدد عند كل استخدام.
5. تستدعي /v1 بالترويسة Authorization: Bearer <token> — نفس نقاط النهاية ونفس فحص الصلاحيات ونفس حدّ الطلبات.
6. يرى العميل تطبيقك في صفحة التطبيقات المتصلة ويستطيع إلغاءه بنقرة؛ الإلغاء يوقف رموزك ويعطّل الويب هوك الخاص بهذا الاتصال.

التفاصيل التقنية في دليل OAuth (معاينة).

الانتقال من مفاتيح API إلى OAuth

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