Skip to main content
ستقدم هذه المقالة توضيحًا لواجهة برمجة التطبيقات للتعرف على بروتوكول Cloudflare Turnstile، والتي تتيح للمستخدمين التحقق من صحة Turnstile CAPTCHA دون الحاجة إلى التعرف عليه أو النقر عليه، بل من خلال تقديم مفتاح الموقع فقط لتحقيق فك التشفير التلقائي في الخلفية وإكمال التحقق.

عملية التقديم

لاستخدام واجهة برمجة التطبيقات للتعرف على بروتوكول Cloudflare Turnstile، يجب أولاً الذهاب إلى لوحة تحكم Ace Data Cloud للحصول على رمز API الخاص بك، للاحتفاظ به كنسخة احتياطية. إذا لم تكن قد قمت بتسجيل الدخول أو التسجيل بعد، فسيتم تحويلك تلقائيًا إلى صفحة تسجيل الدخول لدعوتك للتسجيل وتسجيل الدخول، وبعد الانتهاء، سيتم إرجاعك تلقائيًا إلى الصفحة الحالية. يمكن استخدام رمز API واحد لاستدعاء جميع خدمات المنصة، دون الحاجة لتقديم طلب منفصل لكل خدمة. ستمنحك أول مرة تقدم فيها طلبًا رصيدًا مجانيًا لتجربته مجانًا؛ وعند نفاد الرصيد، يمكنك إعادة شحن الرصيد العام في لوحة التحكم.
📘 الوثائق الكاملة: واجهة برمجة التطبيقات للتعرف على بروتوكول Cloudflare Turnstile →

الاستخدام الأساسي

أولاً، يجب أن نفهم طريقة الاستخدام الأساسية، وهي إدخال عنوان URL للموقع الذي يحتاج إلى معالجة CAPTCHA الخاص بـ Turnstile، للحصول على النتيجة المعالجة. يجب أولاً تمرير حقل website_url ببساطة، وموقعنا التجريبي هو: https://react-turnstile.vercel.app، نحتاج إلى الحصول على website_key من صفحة website_url، يجب أولاً فتح هذه الصفحة، ثم الضغط على F12 للدخول إلى وحدة التحكم، والبحث عالميًا في صفحة العناصر عن cf-turnstile، حيث يمكن العثور على عنصر الحاوية الذي يحمل Turnstile، حيث أن السلسلة المقابلة لـ data-sitekey هي قيمة website_key. تتضمن رؤوس الطلب المحددة:
  • accept: نوع الاستجابة التي ترغب في تلقيها، هنا يتم ملؤها بـ application/json، أي بتنسيق JSON.
  • authorization: مفتاح استدعاء واجهة برمجة التطبيقات، يمكن اختياره مباشرة بعد التقديم.
بالإضافة إلى ذلك، تم إعداد جسم الطلب، والذي يتضمن:
  • website_url: عنوان URL للموقع الذي يحتاج إلى معالجة CAPTCHA.
  • website_key: معرف مفتاح الموقع في Cloudflare Turnstile.
  • action: معلمة اختيارية، تحتاج فقط إلى تمريرها إذا كان الموقع المستهدف قد أعد action مخصصًا لمكون Turnstile.
  • cdata: معلمة اختيارية، تحتاج فقط إلى تمريرها إذا كان الموقع المستهدف قد أعد cData مخصصًا لمكون Turnstile.
انقر على زر “Try” لإجراء الاختبار، وهنا حصلنا على النتيجة التالية:
تتضمن النتيجة العائدة عدة حقول، كما يلي:
  • token: نتيجة التحقق من مهمة CAPTCHA الخاصة بـ Cloudflare Turnstile.
  • started_at، finished_at: الوقت الذي بدأت فيه معالجة الطلب وإنتاج النتيجة، طابع زمني Unix (ثوانٍ، نقطة عائمة).
  • elapsed: إجمالي الوقت المستغرق في المعالجة (ثوانٍ).
يمكننا أن نرى أننا حصلنا على نتيجة التحقق من CAPTCHA الخاص بـ Turnstile، ثم يمكننا استخدامها في POST أو محاكاة تقديمها إلى الموقع المستهدف، للاستخدام مرة واحدة، وصلاحيتها 120 ثانية، يُنصح باستخدامها خلال 60 ثانية. عادةً ما يتم إرسال هذا الرمز كمعلمة cf-turnstile-response معًا إلى الموقع المستهدف، ورمز Python لاستدعاء التحقق من الرمز كما يلي:
إذا كنت ترغب في توليد رمز التكامل المقابل، يمكنك نسخه مباشرة، على سبيل المثال، رمز CURL كما يلي:
رمز التكامل بلغة Python كما يلي:

الوضع غير المتزامن (async)

بشكل افتراضي، تكون واجهة برمجة التطبيقات متزامنة وتنتظر: ستظل الطلبات تنتظر حتى تكتمل معالجة الرمز. إذا كنت تقوم بتدوير حل متعدد (multi-solver rotation) وترغب في “الحصول على task_id على الفور بعد تقديم المهمة، ثم الانتقال إلى جدولة حل آخر، والعودة لاحقًا لقراءة النتيجة”، يمكنك تمرير async: true في جسم الطلب. بعد تمرير async: true، ستعيد الواجهة على الفور task_id، دون الانتظار:
إذا كنت بحاجة إلى التحقق من التقدم، يمكنك استخدام task_id للاستعلام عن POST /captcha/tasks (يوصى بذلك كل 3~5 ثوانٍ). لن تؤدي هذه الواجهة إلى بدء أو دفع معالجة المهمة؛ حتى إذا لم يتم الاستعلام، أو انقطع الاتصال، أو خرجت من العميل، ستستمر الخادم في المعالجة:
أثناء المعالجة، ستعيد status: processing؛ وعند الانتهاء من المعالجة، ستعيد status: ready والرمز:
توضيح الفوترة: في الوضع غير المتزامن، لا يتم احتساب رسوم لإنشاء المهام أو قراءة حالة “قيد المعالجة”؛ يتم احتساب الرسوم مرة واحدة عند قراءة العميل للنتيجة الناجحة لأول مرة (متوافقة مع السلوك الحالي وسعر الوضع المتزامن). ستقوم الخادم بدفع المهام بشكل مستقل، ولكن لن يتم خصم الرسوم مقدمًا لمجرد أن الخلفية قد أكملت المهمة. إذا لم تنجح المهمة خلال 120 ثانية، ستنتهي إلى HTTP 504 timeout، ولن يتم احتساب الرسوم. /captcha/tasks لا تتحمل مسؤولية دفع المهام.
ملاحظة: لا يدعم Cloudflare Turnstile استخدام وكيل خاص (Bring Your Own Proxy)، لذا لا تقبل هذه الواجهة معلمة proxy؛ إذا تم تمريرها، ستعيد 400 invalid_proxy.

معالجة الأخطاء

عند استدعاء واجهة برمجة التطبيقات، إذا واجهت خطأ، ستعيد الواجهة رمز الخطأ والمعلومات المقابلة. على سبيل المثال:
  • 400 token_mismatched:طلب غير صالح، ربما بسبب معلمات مفقودة أو غير صالحة.
  • 400 invalid_proxy:طلب غير صالح، الوكيل غير مدعوم لهذا النوع من كابتشا.
  • 401 invalid_token:غير مصرح، توكن التفويض غير صالح أو مفقود.
  • 429 too_many_requests:طلبات كثيرة جداً، لقد تجاوزت حد المعدل.
  • 500 api_error:خطأ في خادم داخلي، حدث خطأ ما على الخادم.

أمثلة على استجابة الخطأ

الاستنتاج

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