التوثيق

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

بداية سريعة

1. أضف الوكيل إلى صفحة التسجيل

يجمع إشارات الجهاز ويضع رمز زائر قصير العمر في حقل مخفي اسمه attrelix_visitor داخل كل نموذج في الصفحة. ويوفّر أيضًا window.attrelix.token() لتطبيقات الصفحة الواحدة.

<script src="https://attrelix.com/v1.js?v=0bbe74b52d" data-key="pk_live_…" async></script>

// single-page apps: wait for the token before you submit
const visitor = await window.attrelix.token();

2. افحص التسجيل من خادمك

أرسل البريد وعنوان IP للعميل ورمز الزائر مع مفتاحك السري. اختياري: external_id (معرّف المستخدم لديك) وuser_agent وcard_fingerprint (مثل card.fingerprint من Stripe).

curl https://attrelix.com/v1/check \
  -H "Authorization: Bearer $ATTRELIX_SECRET" \
  -H "Content-Type: application/json" \
  -d '{"email":"jdoe+7@gmail.com","ip":"203.0.113.9","visitor":"vt1.…"}'

# Python
r = requests.post("https://attrelix.com/v1/check", timeout=3,
    headers={"Authorization": f"Bearer {SECRET}"},
    json={"email": email, "ip": ip, "visitor": form["attrelix_visitor"]})
decision = r.json().get("decision", "allow") if r.ok else "allow"

3. تصرّف وفق القرار

allow: امنح الأرصدة المجانية. review: اطلب شيئًا يكلّف المزرعة مالًا — بطاقة أو رقم هاتف — أو امنح أرصدة أقل. block: ارفض الحساب أو الأرصدة. وإذا فشل الاستدعاء فاسمح: لا تحجب مستخدمين حقيقيين بسببنا أبدًا.

المفاتيح والرموز

• المفتاح العام (pk_live_…): عام بطبيعته. يوضع في صفحتك ولا يستطيع سوى جمع الإشارات، من المصادر التي تسمح بها في لوحة التحكم.
• المفتاح السري (sk_live_…): للخادم فقط. يشغّل الفحوص ويقرأ النتائج. لا نخزّن إلا بصمته: انسخه عند إنشائه.
• رمز الزائر: موقّع منا، صالح 15 دقيقة ولفحص واحد، ومرتبط بمشروعك. الرمز المستخدم مرتين، أو الآتي من شبكة غير شبكة التسجيل، يرفع الدرجة.

POST /v1/check

جسم الطلب (JSON). أرسل واحدًا على الأقل من email أو ip أو visitor.

الاستجابة

قيمة decision هي allow أو review أو block. وscore من 0 إلى 100: مجموع نقاط الأسباب بحد أقصى. لكل سبب رمز ثابت يمكنك تسجيله أو عرضه.

{
  "id": "chk_3fJ8kQ2mN7pX1aZb",
  "decision": "block",
  "score": 100,
  "reasons": [
    { "code": "linked_accounts_10", "points": 45, "detail": "14" },
    { "code": "alias_of_existing", "points": 30, "detail": "3 variants of jdoe@gmail.com" },
    { "code": "datacenter_ip", "points": 25, "detail": "aws" }
  ],
  "email":   { "normalized": "jdoe@gmail.com", "disposable": false, "relay": false, "mx": "yes", … },
  "network": { "ip": "3.88.0.1", "type": "datacenter", "provider": "aws", "signups_24h": 2 },
  "device":  { "id": "dev_9c1e…", "token": "valid", "browser": "Firefox 144", "flags": ["canvas_noise"] },
  "linked":  { "accounts": 14, "by_device": 12, "by_card": 0, "cluster": "cl_7q2f…" },
  "latency_ms": 38
}

الأخطاء

تأتي الأخطاء بصيغة JSON: {"error": code, "message": text}.

احتساب الدرجة

تُجمع النقاط بحد أقصى 100. الافتراضي: مراجعة من 50 وحظر من 80 — وكلاهما قابل للتعديل. صندوق البريد المؤقت وحده يكفي للمراجعة؛ ولا تبلغها أي إشارة جهاز أو شبكة بمفردها.

مصادر البيانات

نطاقات البريد المؤقت: مشروع disposable-email-domains (CC0) ومشروع disposable/disposable-email-domains (MIT)، تُحدَّث يوميًا. نطاقات مراكز البيانات: القوائم المنشورة من AWS وGoogle Cloud وOracle Cloud وDigitalOcean وLinode. Tor: قائمة عُقد الخروج من Tor Project، تُحدَّث كل ساعة.

الآن: 98,644 نطاق بريد مؤقت و21,665 نطاق عناوين.