SPAMADIN / المطورون

مسار واضح من
الرسالة إلى القرار.

اربط خادمك بـ Spamadin واحتفظ بالمفتاح عليه. احفظ الرسائل في نظامك قبل طلب تصنيفها.

طوّر باستخدام مساعدك البرمجي

زوّد مساعدك بمرجع التكامل ومواصفة OpenAPI لبناء اتصال من خادم موقعك.

مرجع التكامل · مواصفة OpenAPI · فهرس توثيق الذكاء الاصطناعي

إضافة WordPress

ثبّت Spamadin في WordPress والصق مفتاح API لحسابك في الإعدادات ← Spamadin. استخدم المفتاح نفسه لجميع المواقع في خطتك. يضيف الربط الموقع تلقائيًا ضمن الحد المسموح ويحفظ المفتاح بأمان على خادم WordPress.

تنزيل إضافة WordPress

تُحمى التعليقات ونماذج الاتصال المدعومة افتراضيًا. ندعم Contact Form 7 وWPForms وGravity Forms وFluent Forms وElementor Pro. يمكنك تعديل الحماية وإشارات المتصفح الاختيارية من إعدادات الإضافة.

تبقى التعليقات المزعجة في قائمة الرسائل المزعجة في WordPress، وتُرسل الفحوصات غير المؤكدة أو غير المتاحة إلى المراجعة. تبقى رسائل النماذج المحتجزة خاصةً في الإعدادات ← Spamadin لمدة تصل إلى 30 يومًا. راجعها وتواصل مباشرةً مع المرسلين الحقيقيين؛ لا تُعاد إجراءات النموذج. لا تشارك التصحيحات سوى مرجع الفحص والتصنيف، دون نص الرسالة.

يوقف فصل الإضافة الفحوصات المحلية. احظر الموقع في لوحة Spamadin لإيقاف طلبات API وإتاحة مكانه. إعادة الربط لا ترفع الحظر. يتطلب استبدال مفتاح الحساب تحديث كل التكاملات.

1. أنشئ حسابًا ومفتاحًا

تحقق من بريدك واختر اشتراكًا في لوحة التحكم، وأنشئ مفتاح API واحدًا للحساب. استخدمه في جميع مواقعك. يشغل كل اسم مضيف مسموح مكانًا واحدًا؛ ويُحسب example.com وwww.example.com منفصلين. تُعرض المفاتيح مرة واحدة وتُخزّن باستخدام Argon2id.

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

2. افحص رسالة

صف موقعك عند ربطه. يستخدم Spamadin الذكاء الاصطناعي لتصنيفه وإضافة هذا السياق إلى الفحوصات اللاحقة. عطّل موقعًا في لوحة التحكم لإيقاف طلباته وإتاحة خانة. بعد الانتقال إلى خطة أقل، تبقى أقدم المواقع المفعّلة نشطة ضمن حد الخطة؛ عطّل موقعًا أقدم لتفعيل آخر.

POST /api/v1/check · جسم JSON · Authorization: Bearer YOUR_SERVER_KEY

curl https://spamadin.com/api/v1/check \
  -H 'Authorization: Bearer YOUR_SERVER_KEY' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: 45573012-1f18-4eaf-97a1-29702376ea21' \
  -d '{
    "type": "contact",
    "siteUrl": "https://example.com",
    "content": "هل يمكنكم إرسال عرض سعر لموقعنا الجديد؟",
    "context": { "title": "Website design", "language": "en" },
    "signals": { "elapsedMs": 8500, "honeypotFilled": false }
  }'

الفحوصات الجماعية

أرسل حتى 20 رسالة إلى POST /api/v1/check/bulk باستخدام مفتاح API لحسابك. يمكن أن تنتمي العناصر إلى مواقع مختلفة في الحساب. يحتاج كل عنصر إلى معرّف UUID فريد وكائن submission. تحافظ الاستجابات على الترتيب وتضم حالة كل عنصر ونتيجته. أعد المحاولة بالمعرّف نفسه والبيانات نفسها. تسري حدود المواقع والحظر والرصيد الشهري المشترك على كل عنصر.

{
  "checks": [
    {
      "id": "45573012-1f18-4eaf-97a1-29702376ea21",
      "submission": {
        "type": "contact",
        "siteUrl": "https://example.com",
        "content": "هل يمكنكم إرسال عرض سعر؟"
      }
    }
  ]
}

سياق خاص بالنموذج

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

{
  "formId": "d495b23a-cf83-4c3d-bd63-6973297ec401",
  "type": "contact",
  "siteUrl": "https://example.com",
  "content": "هل يمكنكم إرسال عرض سعر؟"
}

استخدم UUID جديدًا في Idempotency-Key لكل رسالة. بعد خطأ شبكة أعد المحتوى نفسه بالمفتاح نفسه. إذا اكتمل الفحص تُعاد النتيجة السابقة دون احتساب جديد. تُحفظ المفاتيح مع البيانات الوصفية 30 يومًا؛ لا تُعد رسائل أقدم من ذلك.

الحقل	الغرض	الحد
content	النص الأصلي للرسالة؛ مطلوب	من حرف واحد إلى 12,000 حرف
type	contact أو comment؛ مطلوب	قيمة التعداد المطابقة
siteUrl	رابط الموقع مطلوب. تُسجّل المواقع الجديدة تلقائيًا ضمن حد خطتك.	HTTP(S)، 2,048 حرفًا
context.title / description	سياق الصفحة ذي الصلة من خادمك	200 / 1,000 حرف
context.language / tags	لغة الموقع وما يصل إلى عشرة وسوم للموضوع	35 / 50 حرفًا
signals.elapsedMs	الوقت بين عرض النموذج وإرساله	0–86,400,000 مللي ثانية
signals.honeypotFilled	ما إذا كان حقل مخفي قد عُبئ	قيمة منطقية
signals.userAgent / userIp	بيانات تكامل اختيارية؛ لا تُرسل للنماذج	512 حرفًا / عنوان IP صالح

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

3. احتفظ بالرسائل غير المؤكدة

{
  "id": "c18dd105-5d52-4939-a63e-0d52b2c0606d",
  "verdict": "allow",
  "score": 0,
  "reasons": ["clear_legitimate_context"],
  "degraded": false,
  "latencyMs": 420,
  "charged": true
}

هذا مثال للنتيجة وليس ضمانًا لزمن الاستجابة. الدرجة مؤشر ترتيبي للمخاطر: 0 (سماح)، 50 (مراجعة)، أو 100 (اتفاق قوي على الإزعاج). ليست احتمالًا إحصائيًا معايرًا.

allow: تابع الإشراف أو التسليم المعتاد.
review: احفظ الرسالة في قائمة مراجعة، ولا تحذفها أبدًا.
spam: اعزلها مع إمكانية استعادة النتائج الإيجابية الخاطئة.
degraded: true: تعطل مزود أو أعاد نتيجة غير صالحة. احتفظ بالرسالة للمراجعة. لا يُحتسب هذا الفحص من الحصة.

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

4. أرسل تصحيحًا

POST /api/v1/feedback باستخدام مفتاح Bearer نفسه وبيانات JSON {"id":"CHECK_UUID","label":"legitimate"} أو الوسم spam. تقتصر التصحيحات على فحوص ذلك المفتاح. تُسجل للتقييم ولا تغير تدريبًا مشتركًا أو تسمح لمرسل فورًا.

يمكنك أيضًا تسجيل تصحيح في لوحة التحكم والتواصل مع الدعم بمرجع الفحص. يمكننا تعديل السياق ومستوى الحذر لموقعك. لا ترسل محتوى رسائل خاصة أو كلمات مرور أو مفاتيح API بالبريد الإلكتروني. تبقى مراجع الفحص متاحة لمدة 30 يومًا.

الحدود ومعالجة الأخطاء

الحد الأقصى للجسم: 32 KiB. تُرفض الحقول المجهولة وبيانات JSON غير الصحيحة.
120 طلبًا لكل مفتاح في الدقيقة. تُحد الطلبات المتزامنة لكل عملية؛ ويُعاد 503 عند تجاوزها.
400 إدخال غير صالح، 401 مفتاح غير صالح أو ملغى، 402 اشتراك غير نشط، 409 إعادة معلقة أو مختلفة، 413 جسم كبير، 429 تجاوز معدل أو حصة، 503 سعة غير متاحة مؤقتًا.
أعد الأخطاء المؤقتة بانتظار أُسّي محدود. أعد استخدام Idempotency-Key والتزم بـ Retry-After إن وُجد.
تُشارك الحصة الشهرية بين جميع المفاتيح وتتجدد في اليوم الشهري المقابل لبداية الاشتراك، بما فيه السنوي. في الأشهر الأقصر يُستخدم آخر يوم. لا ترحيل للحصة أو تجاوز تلقائي.

الإبلاغ عن خطأ في التصنيف

أبلغ عن رسالة حقيقية صُنّفت كمزعجة عبر POST /api/v1/reports/false-positive، أو رسالة مزعجة لم تُكتشف عبر POST /api/v1/reports/missed-spam. أرسل معرّف الفحص المُعاد فقط باستخدام مفتاح API لحسابك. لا تُشارك محتويات الرسائل ولا تُستهلك فحوصات. يُعتمد أحدث تصحيح؛ ولا تُعيد البلاغات تدريب النموذج فورًا.

{
  "id": "c18dd105-5d52-4939-a63e-0d52b2c0606d"
}

الخصوصية افتراضيًا

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

فحوصات اختيارية غير مرئية للنماذج

استدعِ POST /api/v1/form-token من خادمك مع siteUrl وtype واختياريًا formId محفوظ. تنتهي صلاحية الرموز بعد 30 دقيقة. لا يستهلك إصدار الرمز فحصًا لمكافحة الرسائل المزعجة، ويتطلب وصولًا نشطًا للموقع.

أرسل الرمز المستلم في signals.formToken واستخدم idempotencyKey المستلم كترويسة Idempotency-Key. في الفحوصات المجمعة، استخدمه كـ id للعنصر. يجب أن تحافظ إعادة المحاولة على الطلب الأصلي دون أي تغيير. استخدم رمزًا جديدًا لكل إرسال جديد.

حمّل /spamadin-behavior.js على موقعك واربطه بالنموذج. تستدعي نقطة إصدار الرموز التابعة للأصل نفسه خدمة Spamadin من خادمك، وتعيد فقط الاستجابة العامة لرمز النموذج. لا تكشف مفتاح API مطلقًا، ولا تضمّن رموزًا مشتركة في الصفحات المخزنة مؤقتًا.

SpamadinBehavior.attach(document.querySelector("#contact-form"), {
  tokenEndpoint: "/form-evidence/token"
});

يضيف السكربت حقلًا مخفيًا باسم spamadin_evidence يحتوي على token وidempotencyKey وإشارات المتصفح. تحقّق من الحقل على خادمك، واربط browser بـ signals.browser، ومرّر token في signals.formToken. تستخدم الإشارات version 1 وjsExecuted وfocusCount وeditCount وpasteCount وkeyboardUsed وpointerUsed واختياريًا firstInteractionMs. يمكن لخادمك أيضًا إرسال honeypotFilled وعنوان IP للزائر.

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

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

التعرّف على التكرار

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

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

مشاركة مثال تدريب مصحّح

أرسل POST /api/v1/training بالمفتاح الأصلي وcheckId والتصنيف المصحّح وكائن الإرسال الأصلي دون تغيير، مع ضبط إقراري المشاركة على true. يجب أن يكون الفحص مكتملًا وعمره أقل من 30 يومًا. المشاركة اختيارية ولا تستهلك فحصًا ولا تعيد تدريب نموذج فورًا. نفّذ الطلب من خادمك ووفّر الإشعارات المطلوبة والصلاحية القانونية قبل مشاركة محتوى الزوار.

{
  "checkId": "c18dd105-5d52-4939-a63e-0d52b2c0606d",
  "label": "legitimate",
  "submission": {
    "type": "contact",
    "siteUrl": "https://example.com",
    "content": "هل يمكنكم إرسال عرض سعر؟"
  },
  "consent": {
    "authorizedToShare": true,
    "useForSpamImprovement": true
  }
}

يسرد GET /api/v1/training مراجع الأمثلة التي شاركها حسابك. استخدم ?after=EXAMPLE_UUID للصفحة التالية أو ?id=EXAMPLE_UUID لاسترجاع مثال مختصر. اسحب المثال بطلب DELETE إلى المسار نفسه مع معرّفه. تتيح لوحة الحساب سحب الأمثلة حتى بعد إلغاء المفتاح.

تنتهي صلاحية الأمثلة بعد 90 يومًا. الحدود: 500 مثال أو 2 MiB من البيانات المشفّرة لكل حساب، و16 KiB من نص الرسالة الأصلي لكل مثال، و24 KiB من المحتوى والسياق المخفّفين قبل الضغط. تبقى الطلبات محدودة بـ32 KiB. يعيد الحساب الممتلئ 429، ويعيد عدم توفّر السعة أو التشفير مؤقتًا 503. لا يُحفَظ مثال عندما يرفض أحد الحدود الطلب. لا تكرّر المحاولة بلا نهاية ولا ترسل مرفقات خاصة. الحجب بأفضل جهد وليس إخفاءً كاملًا للهوية.

لا تزور API عناوين URL المرسلة مطلقًا. تساعد عناوين IP الاختيارية في رصد كثافة الإرسال لفترة قصيرة ولكل موقع، ولا تؤثر معلومات وكيل المستخدم في التصنيف. لا يُرسل أي منهما إلى النماذج. استخدم إضافة WordPress أو اربط أنظمة إدارة المحتوى الأخرى عبر API الخادم.

أنشئ حسابك ↗

مسار واضح منالرسالة إلى القرار.