واجهة REST البرمجية

أنشئ مفتاحًا من الإعدادات ← مفاتيح الواجهة البرمجية. يُعرض المفتاح بصيغته النصية مرة واحدة فقط ولا يمكن استعادته بعدها؛ ولا يُخزَّن منه بصيغة مقروءة سوى بادئته. أرسله كرمز bearer مع كل طلب.

curl https://api.namesight.app/v1/usage \
  -H "Authorization: Bearer ns_live_..."

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

يُدفع مقابل كل فحص بالأرصدة، سواء بدأته من هنا أو من تطبيق الويب. تكلفة الفحص هي مجموع الوحدات التي يشغّلها: 100 رصيد مع الوحدات الخمس الافتراضية، وأقل عند استبعاد إحداها. تمنحك خطتك رصيدًا شهريًا، والأرصدة غير المستهلكة تُرحَّل.

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

• الرصيد غير كافٍ ← 429 مع مستند مشكلة يوضّح مقدار العجز
• خطة بلا وصول إلى الواجهة البرمجية ← 402 مع رابط للترقية
• إنفاق الأرصدة معطَّل لمساحة العمل ← 403

يدرج POST /v1/scans فحصًا في الطابور ويردّ برمز 202 فورًا. الفحص غير متزامن: تحمل الاستجابة قيمة scanId لا النتيجة.

curl -X POST https://api.namesight.app/v1/scans \
  -H "Authorization: Bearer ns_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "lumina labs",
    "regions": ["TR", "EM", "US"],
    "niceClasses": [9, 41],
    "tlds": ["com", "io"],
    "modules": ["trademark", "domain", "social"]
  }'

{ "scanId": "scn_...", "totalJobs": 12, "creditsSpent": 100, "balance": 1900 }

استعلم دوريًا عن GET /v1/scans/{id} حتى تصبح قيمة status هي completed أو completed_partial. ينتهي الفحص المعتاد في أقل من دقيقة؛ استعلم مرة كل ثانية تقريبًا ووسّع الفاصل الزمني كلما طال الانتظار، كي لا يستنزف الفحص الطويل حدّ معدّل طلباتك.

curl https://api.namesight.app/v1/scans/scn_... \
  -H "Authorization: Bearer ns_live_..."

كل مدخلة في checks هي إجابة مصدر واحد عن هدف واحد، ولها حكمها الخاص، ورابط sourceUrl الذي قُرئت منه، وطابع الوقت fetchedAt. أما كائن summary فيظهر بعد انتهاء الفحص ويحمل الدرجة، ونطاق المخاطرة، وحصيلة العلامات التجارية.

أربع نقاط نهاية مرجعية تصف ما يمكن أن يتضمنه طلب الفحص. وهي تحتاج نطاق reference:read ولا تكلّف شيئًا.

تُرسَل الأخطاء بوصفها مستندات مشكلة وفق معيار RFC 9457 بنوع المحتوى application/problem+json. يحدّد حقل type نوع الإخفاق، ويشرحه detail، ويحمل بعضها بيانات إضافية مثل upgradeUrl.

{
  "type": "https://namesight.app/errors/quota-exceeded",
  "title": "Quota exceeded",
  "status": 429,
  "detail": "Not enough credits (balance 0, need 100). Top up or switch off a module to continue."
}

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

x-ratelimit-limit: 60
x-ratelimit-remaining: 58
x-ratelimit-reset: 41

بعد بدء الفحص وقراءته، يستطيع المفتاح إعادة تشغيله، وإعادة محاولة المصادر التي لم تُجب، وحذفه، ومشاركة تقريره، وعرض مشاريع مساحة العمل، وتوليد أفكار أسماء. كلٌّ منها يحتاج النطاق المبيَّن.

إعادة المحاولة بأمان: أرسل ترويسة Idempotency-Key (أي سلسلة فريدة) مع POST /v1/scans أو rescan. تكرار يحمل المفتاح نفسه خلال 24 ساعة يعيد الجواب الأول — وتقول الاستجابة Idempotent-Replayed: true — بدل بدء فحص ثانٍ وتحصيل رصيده. المفتاح نفسه مع محتوى مختلف يُرفض بـ 409.

curl -X POST https://api.namesight.app/v1/scans \
  -H "Authorization: Bearer ns_live_..." \
  -H "Idempotency-Key: 4f7c2c1e-order-1187" \
  -H "Content-Type: application/json" \
  -d '{"name":"Lumina Labs","modules":["trademark","domain"]}'

الانتظار دون استطلاع متكرر: GET /v1/scans/{id}?wait=60000 يُبقي الطلب معلّقًا حتى ينتهي الفحص أو تنقضي المهلة (60 ثانية كحدّ أقصى)، ثم يجيب بالفحص كما هو. طلب واحد، خانة واحدة من حدّ المعدّل، ولا حلقة.

التصفّح: GET /v1/scans يعيد items و nextCursor. أعد nextCursor بوصفه cursor للصفحة التالية؛ null تعني الصفحة الأخيرة. status يرشّح بحالة أو أكثر مفصولة بفواصل.

بدل الاستطلاع المتكرر، سجّل نقطة نهاية https واستقبل طلب POST موقّعًا عند انتهاء الفحص. تُدار نقاط النهاية من الإعدادات ← API أو عبر /v1/webhooks بنطاق webhooks:manage؛ يمكن لمساحة العمل الاحتفاظ بعشر. سرّ التوقيع يُعرض مرة واحدة عند الإنشاء وعند التدوير.

كل تسليم يحمل أربع ترويسات: x-namesight-event و x-namesight-delivery (المعرّف نفسه في كل إعادة محاولة لإزالة التكرار) و x-namesight-timestamp (ثواني يونكس) و x-namesight-signature. التوقيع هو v1= يليه HMAC-SHA256 بالست عشري على "<timestamp>.<raw body>" بسرّك. تحقق منه على المحتوى الخام للطلب، وارفض الطوابع الزمنية الأقدم من خمس دقائق.

import { createHmac, timingSafeEqual } from "node:crypto";

// Express-style handler; keep the RAW body — a re-serialised JSON will not match.
app.post("/hooks/namesight", express.raw({ type: "*/*" }), (req, res) => {
  const ts = req.header("x-namesight-timestamp");
  const sig = req.header("x-namesight-signature");            // "v1=<hex>"
  const body = req.body.toString("utf8");
  const expected = "v1=" + createHmac("sha256", process.env.NAMESIGHT_WEBHOOK_SECRET)
    .update(`${ts}.${body}`).digest("hex");
  const fresh = Math.abs(Date.now() / 1000 - Number(ts)) < 300;
  if (!fresh || expected.length !== sig.length || !timingSafeEqual(Buffer.from(expected), Buffer.from(sig))) {
    return res.status(401).end();
  }
  const event = JSON.parse(body);                              // { id, event, createdAt, test, data }
  res.status(202).end();                                       // ack first, work later
  if (!event.test) handleScanCompleted(event.data);            // data.scanId, data.status, data.score, data.url
});

أجب بأي 2xx خلال عشر ثوانٍ ثم نفّذ العمل لاحقًا. أي شيء آخر يُعاد أربع مرات بعد 30 ثانية و 2 و 10 و 60 دقيقة. عشرة تسليمات متتالية تفشل في كل محاولاتها تعطّل نقطة النهاية؛ إعادة تفعيلها تصفّر العدّاد. زر الاختبار يرسل scan.completed اصطناعيًا موسومًا test: true.

يُقدَّم الوصف الكامل المقروء آليًا على /v1/openapi.json. وهو لا يحتاج أي مصادقة، فيمكنك توليد عميل منه قبل أن تحصل على مفتاح.