الحماية من الروبوتات

خمس عمليات كتابة عامّة هي التي يستغلّها الروبوتات فعلًا: فهي ترسل بريدًا أو تنشئ سجلًّا أو الاثنين معًا. هذه الخمس تحمل فحص Cloudflare Turnstile فوق مفتاح الواجهة.

عمليات الكتابة الخمس المحميّة

ولا شيء غيرها يحتاج رمزًا. وعمليات القراءة لا تحتاجه أبدًا.

متى يُطلب الرمز

• نداء بمفتاح قابل للنشر (pk_…، أي من متصفّح) ← الرمز مطلوب.
• نداء بمفتاح سرّي (sk_…، أي من خادمك) ← الفحص متجاوَز، فقد أثبتّ هويّتك بوصفك الموقع.
• الموقع بلا إعداد Turnstile ← الفحص متوقّف تمامًا، وهذا ما يجعل التطوير المحلي يعمل.

الحصول على مفتاح الموقع

يحتاج Turnstile إلى مفتاح موقع في المتصفّح (وهو شيء غير مفتاح موقعك في Wzgate). اضبطه لكل موقع في الإعدادات ← المواقع ← اربط موقعك ← الحماية من الروبوتات، واقرأه من الواجهة حتى لا يُثبّته كودك:

const { data } = await (
  await fetch(`${API}/public/company-profile`, { headers: siteHeaders() })
).json();

const turnstileSiteKey = data.site?.turnstileSiteKey ?? null;

وnull تعني أن هذا الموقع بلا فحص روبوتات — اعرض النموذج بلا أداة.

إرسال الرمز

اعرض أداة Turnstile، وخذ الرمز الذي تنتجه، وضعه على الطلب في X-Turnstile-Token:

export async function submitLead(body: unknown, turnstileToken?: string) {
  const res = await fetch(`${API}/public/leads`, {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      ...siteHeaders(),
      ...(turnstileToken ? { 'X-Turnstile-Token': turnstileToken } : {}),
    },
    body: JSON.stringify(body),
  });

  const payload = await res.json();
  if (!res.ok) throw new Error(payload.code ?? 'LEAD_FAILED');
  return payload.data;
}

ولا يجوز وضع الرمز في جسم الطلب: تتحقّق الواجهة من الأجسام بصرامة، والحقل غير المعلن خطأ 400.

الرفوض

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

ومثل مفاتيح الواجهة، يُطرح فحص الروبوتات في وضع المراقبة أولًا — يُسجَّل غياب الرمز وتُخدَم الكتابة — ويُعلن في سجلّ التغييرات قبل إلزامه. أرسل الرمز الآن ولن ترى للتحويل أثرًا.