المصادقة (Authentication) في واجهة الفوترة

هذا الدليل موجّه للمطوّرين وفِرَق التكامل التقني الذين يربطون أنظمتهم بمنصة فاتورة ضمن الفاتورة الإلكترونية في السعودية. موضوعه الوحيد: كيف تُصادِق طلباتك على واجهات منصة فاتورة (Fatoora API). أي طلب ترسله للهيئة يجب أن يحمل هوية موثوقة، وإلا رُفض على البوابة قبل أن يصل لمنطق العمل.

المصادقة هنا ليست تسجيل دخول باسم مستخدم وكلمة مرور، ولا هي OAuth برموز وصول مؤقتة. واجهات الفوترة في منصة فاتورة تستخدم مصادقة أساسية (Basic Authentication) مبنية على شهادة الختم التشفيري (CSID) وسرّها المرافق. تفهم في هذا الدليل من أين تأتي هذه البيانات، وكيف تبنيها في ترويسة Authorization، ومتى تنتقل من شهادة الامتثال إلى شهادة الإنتاج، وكيف تؤمّن هذه البيانات الحساسة.

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

نقطة محورية نضعها أمامك من البداية حتى لا تضيع وقتك في الاتجاه الخطأ: واجهات الفوترة في منصة فاتورة لا تستخدم OAuth. كثير من المطوّرين يفترضون وجود نقطة نهاية لطلب رمز وصول (Access Token) لأن هذا هو النمط السائد في معظم واجهات الـ API الحديثة. هنا الأمر مختلف. المصادقة تعتمد على شهادة CSID مباشرة في كل طلب عبر ترويسة Basic. أبقِ هذه الحقيقة في ذهنك طوال القراءة.

ما المقصود بالمصادقة في واجهة الفوترة؟

المصادقة (Authentication) هي إثبات أن الجهاز الذي يطرق باب البوابة جهاز معروف ومسجّل لدى الهيئة. كل طلب HTTP يصل لمنصة فاتورة يمرّ أولًا على طبقة تحقق من الهوية. إن لم يحمل الطلب بيانات اعتماد صحيحة، تردّه البوابة برمز الحالة 401 دون أن تنظر في محتوى الفاتورة أصلًا.

من المفيد أن تفصل في ذهنك بين ثلاثة مفاهيم يخلط بينها كثيرون. المصادقة تجيب عن سؤال «من أنت؟». التفويض (Authorization) يجيب عن سؤال «ماذا يحق لك أن تفعل؟». توقيع المستند يجيب عن سؤال «هل هذه الفاتورة سليمة ولم تُعدَّل؟». هذا الدليل يخصّ المصادقة، أي إثبات الهوية على مستوى النقل (Transport Layer).

الفصل بين المصادقة وتوقيع الفاتورة مهم عمليًا. شهادة CSID تلعب دورين منفصلين تمامًا. الدور الأول مصادقة الطلب على البوابة، وهنا تُرسل الشهادة وسرّها في ترويسة Authorization لتثبت أن المُرسِل جهاز مسجّل. الدور الثاني توقيع الفاتورة، وهنا يُستخدم المفتاح الخاص المرتبط بالشهادة لإنشاء الختم التشفيري داخل XML. الدور الأول على مستوى النقل، والثاني على مستوى المستند. لا تخلط بينهما.

هذا يعني أن المفتاح الخاص لا يُرسل أبدًا في ترويسة المصادقة. ما يُرسل في الترويسة هو معرّف الشهادة (الذي يحمل المفتاح العام) مع السرّ المرافق له. المفتاح الخاص يبقى محليًا في نظامك، وتستخدمه لتوقيع تجزئة الفاتورة فقط. أمان هذا المفتاح مسؤوليتك أنت، وأي تسريب له يعني قدرة طرف آخر على انتحال هوية جهازك.

لماذا Basic وليس OAuth؟

تختار منصة فاتورة المصادقة الأساسية لأنها مبنية على شهادة جهاز ثابتة لا على جلسة مستخدم متغيّرة. في نموذج OAuth، تطلب رمز وصول قصير العمر ثم تستخدمه حتى ينتهي، ثم تجدّده. هذا النمط مناسب للتطبيقات التي يسجّل فيها مستخدمون بشريون دخولهم. لكن إصدار الفواتير عملية آلية بين جهاز ونظام حكومي، فالأنسب لها هوية جهاز دائمة محمولة في شهادة رقمية.

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

لمن يحتاج فهم منوال OAuth بالتفصيل، سواء لمقارنته أو لأن جزءًا آخر من نظامه يستخدمه، أفردنا له دليلًا مستقلًا بعنوان «OAuth». لكن للفواتير نفسها، اعتمد على Basic مع CSID كما يشرح هذا الدليل.

من أين تأتي بيانات الاعتماد؟ CSID الامتثال مقابل CSID الإنتاج

الصورة الكاملة لمصدر بيانات الاعتماد

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

في المرحلة الأولى، تطلب شهادة امتثال (Compliance CSID) عبر بوابة الهيئة باستخدام رمز تحقق لمرة واحدة (OTP) تحصل عليه من منصة فاتورة. تردّ عليك واجهة الامتثال بمعرّف شهادة وسرّ مرافق. هذه البيانات للاختبار فقط، أي لتنفيذ سلسلة فواتير تجريبية تثبت أن نظامك يبني الفاتورة ويوقّعها بشكل سليم. تفاصيل هذه الشهادة في دليل شهادة Compliance CSID.

بعد اجتياز اختبارات الامتثال بنجاح، تطلب شهادة إنتاج (Production CSID، وتختصر PCSID). هذه هي الشهادة التي تشغّل بها الفواتير الحقيقية ذات الأثر الضريبي. تردّ عليك واجهة الإنتاج بمعرّف شهادة وسرّ جديدين تمامًا. ما يخص بيئة الإنتاج مشروح في دليل شهادة PCSID للإنتاج.

الخلاصة التي يجب أن تثبت في تصميم نظامك: لديك زوجان من بيانات الاعتماد، زوج للمحاكاة وزوج للإنتاج، وكل زوج معرّف شهادة مع سرّ. لا تخلط بينهما أبدًا. إرسال فاتورة بإنتاج إلى بيئة المحاكاة يعني أنها لم تُعتمد ضريبيًا فعليًا، وقد تظنّ أن كل شيء يعمل بينما لا أثر لما أرسلت. لفهم الفرق بين البيئتين على مستوى البنية، راجع دليلَي بيئة المحاكاة (Sandbox) وبيئة الإنتاج (Production).

دور شهادة CSID نفسها

شهادة CSID هي معرّف الختم التشفيري الذي تصدره الهيئة لكل جهاز إصدار فواتير. تحمل المفتاح العام للجهاز، وتُربط بالرقم الضريبي للمنشأة. الشهادة هي ما يثبت للبوابة أن الجهاز معتمد، وهي نفسها التي تُستخدم في بناء ترويسة المصادقة. شرح هذه الشهادة وكيفية توليدها في دليل شهادة CSID: معرّف الختم التشفيري.

انتبه إلى تسمية الشهادة بدقة: CSID وليس CCSI أو أي ترتيب آخر للأحرف. الاختصار يعني Cryptographic Stamp Identifier، أي معرّف الختم التشفيري. الخطأ في كتابة الاختصار شائع، وقد يربكك عند البحث في وثائق الهيئة.

بناء ترويسة Authorization خطوة بخطوة

المصادقة الأساسية في بروتوكول HTTP بسيطة في جوهرها: تأخذ اسم المستخدم وكلمة المرور، تصلهما بنقطتين، ترمّز الناتج بـ Base64، ثم تضعه في ترويسة Authorization مسبوقًا بكلمة Basic. الجديد هنا أن «اسم المستخدم» هو معرّف شهادة CSID، و«كلمة المرور» هي السرّ المرافق لها.

الصيغة العامة على هذا النحو:

Authorization: Basic base64( CSID + ":" + secret )

أي أنك تأخذ معرّف الشهادة، تضيف إليه نقطتين رأسيتين، ثم السرّ، ثم ترمّز السلسلة كلها بـ Base64. لاحظ أن النقطتين الرأسيتين جزء من المدخل قبل الترميز، لا بعده. إن وضعت الترميز ثم النقطتين، نتج طلب غير صالح يردّه الخادم برمز 401.

للتوضيح بمثال ملموس، افترض أن معرّف شهادتك هو السلسلة TUlJ... وأن السرّ هو aBcD1234. تبني السلسلة الوسيطة على هذا الشكل قبل الترميز:

TUlJ...:aBcD1234

ثم ترمّزها بـ Base64 وتضعها في الترويسة. الناتج النهائي يبدو كهذا داخل طلب فعلي:

POST /invoices/clearance/single HTTP/1.1
Host: gw-fatoora.zatca.gov.sa
Content-Type: application/json
Accept: application/json
Accept-Language: ar
Accept-Version: V2
Authorization: Basic VFVsSi4uLjphQmNEMTIzNA==
Clearance-Status: 1

تفصيل دقيق يخطئ فيه كثيرون: قيمة معرّف الشهادة نفسها مُرمَّزة بـ Base64 أصلًا لأنها بيانات شهادة ثنائية. هذا يعني أنك ترمّز شيئًا مرمّزًا، أي طبقتا Base64. الطبقة الأولى للشهادة نفسها كما تسلّمتها من الهيئة، والطبقة الثانية لسلسلة «المعرّف:السرّ» كاملة كما تتطلب المصادقة الأساسية. لفهم آلية الترميز نفسها بعمق، راجع دليل ترميز Base64 في الفاتورة الإلكترونية.

أمثلة عملية ببناء الترويسة

في أغلب لغات البرمجة، بناء الترويسة سطر أو سطران. هنا مثال بلغة Python يوضّح الخطوة كاملة:

import base64

csid   = "TUlJ..."        # certificate identifier from ZATCA
secret = "aBcD1234"       # paired secret from ZATCA

raw    = f"{csid}:{secret}"
token  = base64.b64encode(raw.encode()).decode()

headers = {
    "Authorization":  f"Basic {token}",
    "Content-Type":   "application/json",
    "Accept-Version": "V2",
}

والمنطق نفسه بلغة JavaScript على بيئة Node.js:

const csid   = "TUlJ...";
const secret = "aBcD1234";

const raw   = `${csid}:${secret}`;
const token = Buffer.from(raw).toString("base64");

const headers = {
  "Authorization":  `Basic ${token}`,
  "Content-Type":   "application/json",
  "Accept-Version": "V2",
};

لاحظ أن الكود لا يطلب رمز وصول من أي نقطة نهاية قبل الإرسال. تبني الترويسة محليًا من بيانات الاعتماد وترسل الطلب مباشرة. هذا هو الفرق العملي بين Basic وOAuth في تصميم نظامك.

ترويسة Accept-Version ولماذا هي إلزامية

دور ترويسة Accept-Version

بجانب ترويسة المصادقة، تتطلب واجهات منصة فاتورة ترويسة Accept-Version في كل طلب. قيمتها تحدّد إصدار الواجهة الذي يفهمه نظامك. الإصدار الحالي للمرحلة الثانية هو V2. إن أغفلت هذه الترويسة، قد تردّ البوابة الطلب أو تتعامل معه بإصدار افتراضي لا يطابق توقّعاتك.

Accept-Version: V2

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

اجعل ترويسة Accept-Version جزءًا ثابتًا من إعداد عميل HTTP في نظامك، تمامًا كما تثبّت Content-Type. لا تتركها لكل استدعاء على حدة، فنسيانها في نقطة نهاية واحدة سبب شائع لأخطاء يصعب تتبّعها لاحقًا.

الترويسات الأخرى المرافقة

إلى جانب المصادقة والإصدار، يحمل الطلب ترويسات قياسية. Content-Type بقيمة application/json يخبر البوابة أن حمولتك بصيغة JSON. Accept-Language بقيمة ar أو en يحدّد لغة رسائل الخطأ في الاستجابة، وهي ترويسة مفيدة لفِرَق الدعم العربية. بعض نقاط النهاية تضيف ترويسات خاصة بها، مثل Clearance-Status في طلبات المقاصة، لكن المصادقة والإصدار ثابتان في كل طلب.

مسار الطلب من الامتثال إلى الإنتاج على مستوى المصادقة

بيانات الاعتماد التي تستخدمها تتغيّر بحسب المرحلة التي يمرّ بها تكاملك. في مرحلة الامتثال، تبني ترويسة Authorization من شهادة الامتثال وسرّها، وترسل الطلبات إلى عنوان بيئة المحاكاة. الهدف اجتياز سلسلة الفواتير التجريبية التي تتحقق من سلامة بناء فاتورتك وتوقيعها.

بعد نجاح الامتثال، تستبدل بيانات الاعتماد بشهادة الإنتاج وسرّها، وتحوّل وجهة الطلبات إلى عنوان بيئة الإنتاج. الترويسة نفسها بنيتها لم تتغيّر، فهي Basic مع معرّف وسرّ، لكن القيم مختلفة تمامًا والوجهة مختلفة. هذا هو جوهر الانتقال من الاختبار إلى التشغيل الحي على مستوى المصادقة.

خطأ التشغيل الأكثر شيوعًا هنا تركيب بيانات اعتماد بيئة في عنوان البيئة الأخرى. مثلًا إرسال شهادة إنتاج إلى عنوان المحاكاة، أو العكس. النتيجة رفض بالمصادقة برمز 401 رغم أن البيانات «صحيحة» في حد ذاتها، لأنها صحيحة لبيئة وليست للبيئة التي خاطبتها. اجعل وجهة العنوان وبيانات الاعتماد مقترنتين في إعداد واحد لتتجنّب هذا الخلط.

دورة حياة بيانات الاعتماد بعد الإنتاج

بيانات اعتماد الإنتاج ليست أبدية. لشهادة CSID مدة صلاحية، وعند اقترابها من الانتهاء تجدّدها عبر الهيئة فتحصل على معرّف وسرّ جديدين. صمّم نظامك ليقرأ بيانات الاعتماد من مصدر مركزي قابل للتحديث، لا أن تكتبها داخل الكود. بهذا يكون التجديد تحديث قيمة في مكان واحد، لا إعادة نشر للنظام كله.

راقب رموز الحالة 401 في سجلّاتك. ارتفاع مفاجئ في هذا الرمز على بيئة الإنتاج مؤشر محتمل على انتهاء صلاحية الشهادة أو على تغيّر السرّ دون تحديثه في نظامك. التقاط هذا مبكرًا يوفّر عليك انقطاعًا في إصدار الفواتير قد يمتد لساعات قبل أن تكتشف السبب.

تأمين بيانات الاعتماد

لماذا التأمين هنا أهم من OAuth

في نموذج OAuth، رمز الوصول قصير العمر، فحتى لو تسرّب فمدة استغلاله محدودة. أما في المصادقة الأساسية، فبيانات الاعتماد ثابتة لا تنتهي تلقائيًا قبل تجديد الشهادة. هذا يجعل تسريبها أخطر، لأن من يحصل عليها يستطيع انتحال هوية جهازك حتى تنتبه وتعيد إصدار الشهادة. لذلك التأمين الصارم ليس اختياريًا.

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

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

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

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

المصادقة موحّدة عبر الواجهات الأربع

تتعامل منصة فاتورة مع أربع واجهات برمجية تغطّي دورة الربط: واجهة الامتثال (Compliance)، وواجهة الإصدار والإنتاج (Onboarding)، وواجهة المقاصة (Clearance)، وواجهة الإبلاغ (Reporting). الخبر المريح للمطوّر أن آلية المصادقة واحدة في كلها: ترويسة Basic مبنية على شهادة CSID وسرّها. تتعلّم البناء مرة واحدة وتطبّقه في كل نقطة نهاية.

ما يختلف بين الواجهات ليس المصادقة، بل أي زوج بيانات اعتماد تستخدمه. واجهتا الامتثال والإصدار تُستدعيان عند تهيئة الجهاز لمرة واحدة، وتستخدمان شهادة الامتثال أولًا ثم تنتجان شهادة الإنتاج. واجهتا المقاصة والإبلاغ تُستدعيان مع كل فاتورة في التشغيل اليومي، وتستخدمان شهادة الإنتاج. تفاصيل واجهتي التشغيل في دليلَي المقاصة (Clearance) والإبلاغ (Reporting).

هذا التوحيد يبسّط تصميم عميل HTTP في نظامك. تبني دالة واحدة تأخذ زوج بيانات الاعتماد وتنتج ترويسة Authorization، ثم تستدعيها قبل أي طلب لأي واجهة. لا تكرّر منطق المصادقة في كل نقطة نهاية، بل اجمعه في مكان واحد يقرأ بيانات الاعتماد من مخزن الأسرار ويبني الترويسة. هذا النمط يجعل تجديد الشهادة لاحقًا تغييرًا في موضع واحد لا في كل استدعاء.

شكل الطلب والاستجابة في طلب مصادَق

لتثبيت الصورة، إليك شكل استجابة نموذجية لطلب مقاصة فاتورة نجحت مصادقته. لاحظ أن البوابة تردّ بصيغة JSON تحمل حالة المقاصة ومعرّفات المتابعة:

HTTP/1.1 200 OK
Content-Type: application/json

{
  "clearanceStatus": "CLEARED",
  "clearedInvoice": "<Base64-signed-XML>",
  "validationResults": {
    "status": "PASS",
    "warningMessages": [],
    "errorMessages": []
  }
}

حين تفشل المصادقة قبل أن يصل الطلب لمنطق العمل، يكون الردّ مختلفًا تمامًا. لا تجد فيه حالة مقاصة ولا نتائج تحقق، بل رمز 401 ورسالة موجزة تخصّ الهوية:

HTTP/1.1 401 Unauthorized
Content-Type: application/json

{
  "message": "Authentication failed",
  "code": "invalid-credentials"
}

الفرق بين الردّين يدلّك سريعًا على طبقة المشكلة. ردّ يحمل validationResults يعني أن مصادقتك نجحت والمشكلة في بنية الفاتورة. ردّ 401 يعني أن المشكلة سابقة على ذلك كله، في بيانات اعتمادك أو في بناء الترويسة. ابدأ التشخيص دائمًا من رمز الحالة قبل أن تغوص في جسم الاستجابة.

أخطاء المصادقة الشائعة وكيف تقرؤها

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

السبب الأول خطأ في بناء السلسلة قبل الترميز، مثل نسيان النقطتين الرأسيتين بين المعرّف والسرّ، أو وضع مسافة زائدة. السبب الثاني خلط بيئة، أي إرسال بيانات اعتماد المحاكاة إلى عنوان الإنتاج أو العكس. السبب الثالث استخدام شهادة منتهية الصلاحية. السبب الرابع نسيان ترميز السلسلة بـ Base64 أو ترميزها مرتين بالخطأ.

رمز آخر قد تصادفه هو 403 (ممنوع)، ويعني أن هويتك ثبتت لكن لا يحق لها تنفيذ هذا الإجراء، وهذه مسألة تفويض لا مصادقة. أما الرمز 400 (طلب خاطئ) فغالبًا يخصّ بنية الحمولة لا المصادقة، لكن نسيان ترويسة Accept-Version قد ينتج عنه أحيانًا. اقرأ جسم الاستجابة دائمًا، فهو يحمل رسالة توضّح السبب بدقة، خصوصًا حين تضبط Accept-Language على ar.

كيف يساعدك قيود في المصادقة مع منصة فاتورة

كل ما شرحناه في هذا الدليل، من بناء ترويسة Basic إلى إدارة شهادتي الامتثال والإنتاج وتأمين السرّ، يديره نظام قيود للفاتورة الإلكترونية نيابةً عنك. أنت لا تكتب سطر Base64 ولا تدير ترويسة Authorization يدويًا، بل تصدر فاتورتك من واجهة قيود ويتولّى النظام المصادقة مع الهيئة في الخلفية.

تحديدًا، يقوم قيود بالآتي على مستوى المصادقة والربط:

• يدير شهادة الختم التشفيري (CSID) آليًا، من طلب شهادة الامتثال عبر رمز التحقق، إلى توليد شهادة الإنتاج بعد اجتياز الامتثال.
• يبني ترويسة Authorization بصيغة Basic لكل طلب تلقائيًا، فلا تتعامل مع ترميز Base64 ولا مع السرّ مباشرة.
• يفصل بيئة المحاكاة عن بيئة الإنتاج داخليًا، فلا يقع خطأ خلط بيانات الاعتماد بين البيئتين.
• ينفّذ المقاصة الفورية لفواتير B2B والإبلاغ خلال 24 ساعة لفواتير B2C، مع التوقيع التشفيري للفاتورة وتضمين رمز QR.
• يحفظ سلسلة تجزئة الفواتير للتحقق من الامتثال، ويدير تجديد الشهادة عند اقتراب انتهائها.

بهذا تركّز فِرَق التطوير على منطق العمل في نظامك، بينما تبقى طبقة المصادقة مع الهيئة مسؤولية قيود. هذا يلغي الحاجة لبناء وصيانة تكامل مباشر مع منصة فاتورة من الصفر.

الأسئلة الشائعة عن المصادقة في واجهة الفوترة

هل تستخدم واجهات الفوترة في منصة فاتورة بروتوكول OAuth؟

لا. واجهات إصدار الفواتير في منصة فاتورة تستخدم المصادقة الأساسية (Basic Authentication) المبنية على شهادة CSID وسرّها، لا OAuth برموز وصول مؤقتة. تحمل بيانات الاعتماد نفسها في ترويسة Authorization مع كل طلب. لمن يحتاج فهم منوال OAuth بحد ذاته، أفردنا له دليلًا مستقلًا.

من أين أحصل على معرّف CSID والسرّ المطلوبين للمصادقة؟

تتسلّمهما من الهيئة على مرحلتين. في الامتثال تطلب شهادة Compliance CSID عبر رمز تحقق لمرة واحدة، فتحصل على معرّف وسرّ للاختبار. بعد اجتياز الامتثال تطلب شهادة الإنتاج (PCSID) فتحصل على معرّف وسرّ جديدين للتشغيل الحي. كل بيئة بيانات اعتماد منفصلة.

كيف أبني قيمة ترويسة Authorization بالضبط؟

تصل معرّف CSID بالسرّ بنقطتين رأسيتين بينهما، ثم ترمّز السلسلة الناتجة بـ Base64، ثم تضع الناتج في الترويسة مسبوقًا بكلمة Basic. الصيغة: Basic ثم ترميز Base64 لسلسلة «المعرّف:السرّ». النقطتان جزء من المدخل قبل الترميز لا بعده.

ما الغرض من ترويسة Accept-Version؟

تحدّد إصدار الواجهة الذي يفهمه نظامك، وقيمتها للمرحلة الثانية هي V2. وجودها يحمي تكاملك من التغيّرات المستقبلية، إذ يبقى نظامك مربوطًا بالإصدار الذي بنيته عليه. أغفالها قد يؤدي لرفض الطلب أو لاستجابة بإصدار افتراضي غير متوقّع.

لماذا يجب تأمين بيانات الاعتماد بصرامة أكبر من OAuth؟

لأن بيانات الاعتماد الأساسية ثابتة لا تنتهي تلقائيًا قبل تجديد الشهادة، بخلاف رمز الوصول قصير العمر في OAuth. تسريبها يتيح انتحال هوية جهازك مدة أطول. لذلك لا تكتبها في الكود، خزّنها في مخزن أسرار مشفّر، ولا تسجّلها في السجلّات، وأعِد إصدار الشهادة فورًا عند أي شبهة تسريب.

ماذا يعني رمز الحالة 401 في طلب المصادقة؟

يعني أن البوابة لم تقبل بيانات اعتمادك. الأسباب الشائعة: خطأ في بناء السلسلة قبل الترميز، أو خلط بيانات اعتماد بين بيئة المحاكاة والإنتاج، أو شهادة منتهية الصلاحية، أو نسيان ترميز Base64. اقرأ جسم الاستجابة فهو يوضّح السبب، خصوصًا مع ضبط Accept-Language على ar.