API التوثيق

1. سجّل مجانًا، ثم أنشئ مفتاحًا من صفحة «API Key» في لوحة التحكم.
2. ضع المفتاح في ترويسة الطلب X-Access-Key، ثم استدعِ واجهة لقطات الشاشة:

curl "https://glanceshot.com/v1/screenshot?url=https://example.com&full_page=true" \
  -H "X-Access-Key: $GLANCESHOT_KEY" \
  -o screenshot.png

يتطلب كل طلب API Key، ويمكن تمريره بإحدى الطرق التالية:

• ترويسة الطلب X-Access-Key: gls_… (موصى بها للاستدعاءات من الخادم)
• معامل الاستعلام access_key=gls_… (للاستخدام من الخادم فقط، ولا تضعه في صفحات الويب)
• رابط URL موقّع (عند الحاجة إلى تضمين العنوان في صفحة ويب، دون كشف API Key أو secret)

تظهر قيمة API Key مرة واحدة فقط عند إنشائه، لذا احفظها بأمان. إذا تسرّب المفتاح، يمكنك تعطيله من لوحة التحكم.

معلمات خاصة بلقطات الشاشة:

معلمات مشتركة بين لقطات الشاشة وPDF:

التقاط تطبيقات الصفحة الواحدة (React وVue وغيرها):تُشغَّل JavaScript في متصفح حقيقي قبل التقاط الصفحة. تنتظر الاستراتيجية الافتراضية networkidle اكتمال جلب البيانات. إذا كان المحتوى يُعرض بعد انتهاء الطلبات باستخدام مؤقتات أو رسوم متحركة، فأضف wait_for_selector لتحديد عنصر يدل على جاهزية المحتوى. وإذا لم تجد عنصرًا مناسبًا، فاستخدم delay لإضافة وقت انتظار.

تُحتسب كل عملية PDF بمقدار 2 من الحصة. تُمرَّر الصفحة كاملةً مرة واحدة قبل الطباعة لتفعيل المحتوى ذي التحميل الكسول. إضافةً إلى المعلمات المشتركة، تتوفر المعلمات التالية:

curl -X POST "https://glanceshot.com/v1/pdf" \
  -H "X-Access-Key: $GLANCESHOT_KEY" \
  -H "Content-Type: application/json" \
  -d '{"html": "<h1>التقرير ربع السنوي</h1><p>نص التقرير…</p>", "paper": "a4"}' \
  -o report.pdf

افتراضيًا (response_type=binary)، يُرجع الملف مباشرةً، وتكون قيمة Content-Type مطابقةً لصيغته. ترويسات الاستجابة:

• X-Request-Id: معرّف هذا الطلب؛ يُرجى تزويدنا به عند استكشاف المشكلات
• X-Glanceshot-Cache: ‏HIT أو MISS
• X-Glanceshot-Truncated: true: اقتُطعت الصفحة الكاملة لتجاوز ارتفاعها 20,000 بكسل
• X-Glanceshot-Format-Changed: webp: يُحوَّل PNG تلقائيًا إلى WebP إذا تجاوز 5 MB (لا يحدث التحويل عند تحديد format=png صراحةً)

عند تعيين response_type=json، يُرجع عنوان الملف والبيانات الوصفية:

curl -X POST "https://glanceshot.com/v1/screenshot" \
  -H "X-Access-Key: $GLANCESHOT_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com", "response_type": "json"}'

# الاستجابة
{
  "url": "https://glanceshot.com/i/3f/3f9c….png",
  "cache_hit": false,
  "duration_ms": 1284,
  "format": "png",
  "width": 1280,
  "height": 800,
  "request_id": "req_01j…"
}

هل تريد وضع عنوان لقطة الشاشة مباشرةً في <img src> دون كشف API Key؟ لا يتضمن URL الموقّع أي API Key، بل يكتفي بالمعرّف العلني key_id، وتُحسب التوقيعات على خادمك باستخدام secret المرتبط بالمفتاح. يمكنك الاطلاع على معرّف المفتاح وsecret في صفحة API Key بلوحة التحكم:

canonical = رتّب جميع المعلمات، باستثناء signature، ترتيبًا معجميًا حسب أسمائها،
            ونسّق كل عنصر بالشكل k=urlencode(v) (وفق RFC 3986، مع ترميز المسافة إلى %20)، ثم صِل العناصر باستخدام &
signature = hex(HMAC-SHA256(secret, canonical))

يُعدّ التوقيع الصحيح مصادقةً كافية، ويُرفض الطلب إذا كان التوقيع مفقودًا أو غير صحيح. أي تغيير في المعاملات (مثل تغيير url) يُبطل التوقيع. يدخل المعامل الاختياري expires (وقت Unix بالثواني) في حساب التوقيع، وتُعاد signature_expired بعد انتهاء الصلاحية. لتحديث الذاكرة المؤقتة، يكفي تغيير معامل لا يؤثر في النتيجة (مثل v=2) وإعادة التوقيع. يدعم URL الموقّع استدعاء واجهتَي لقطات الشاشة وPDF بطريقة GET فقط، ولا يقبل معاملات الوكيل.

المعرّف key_id علني، ولا يكفي وحده لاستدعاء API. لا تضع API Key (access_key) في URL الموقّع، وإلا فستُعاد invalid_params مباشرةً. إذا سبق أن ضمّنت API Key في صفحة ويب، فعطّله من لوحة التحكم وأنشئ مفتاحًا جديدًا.

import crypto from "node:crypto";

// ترميز RFC 3986 (المسافة هي %20)، ويجب أن يطابق قواعد الخادم
const enc = (v) =>
  encodeURIComponent(v).replace(/[!'()*]/g, (c) => "%" + c.charCodeAt(0).toString(16).toUpperCase());

function signedUrl(params, keyId, secret) {
  const all = { ...params, key_id: keyId };
  const canonical = Object.keys(all).sort().map((k) => `${k}=${enc(String(all[k]))}`).join("&");
  const signature = crypto.createHmac("sha256", secret).update(canonical).digest("hex");
  return `https://glanceshot.com/v1/screenshot?${canonical}&signature=${signature}`;
}

const src = signedUrl({ url: "https://example.com", viewport_width: 1200 }, KEY_ID, SECRET);
// <img src={src} alt="معاينة صفحة الويب" />

للوصول إلى صفحة من بلد أو منطقة محددة (مثل عرض اللغة والمحتوى والأسعار المحلية)، يمكنك تضمين وكيل اشتريته بنفسك في الطلب، وتتحمل أنت تكلفته. تُحمَّل الصفحة وصورها وبرامجها النصية وطلبات API عبر هذا الوكيل. ندعم وكلاء socks5:// وhttp://، مع إمكانية استخدام اسم مستخدم وكلمة مرور.

curl -X POST "https://glanceshot.com/v1/screenshot" \
  -H "X-Access-Key: $GLANCESHOT_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com", "proxy": "socks5://user:pass@203.0.113.10:1080"}' \
  -o screenshot.png

• لا يمكن تضمين proxy إلا في جسم طلب POST. ولا يُسمح به في طلبات GET أو روابط URL الموقّعة أو المهام المجمّعة، لمنع ظهور بيانات دخول الوكيل في الروابط أو سجل المتصفح أو صفحات الويب.
• إذا احتوى اسم المستخدم أو كلمة المرور على رموز خاصة مثل @ أو :، فيجب ترميزها أولًا وفق ترميز URL (مثل كتابة @ بالشكل %40).
• تُخزَّن نتائج الطلبات التي تستخدم وكيلًا بشكل منفصل، ولا تُشارك مع الطلبات التي لا تستخدم وكيلًا أو تستخدم وكيلًا آخر.
• إذا تعذّر الاتصال بالوكيل أو فشلت المصادقة أو تعذّر الوصول إلى الموقع المستهدف، يُعاد proxy_failed ولا تُحتسب رسوم الطلب، ويوضح message السبب بالتحديد.
• يجب أن يكون للوكيل عنوان عام على الإنترنت. وتسري على رابط الموقع المستهدف القيود نفسها المطبّقة دون وكيل؛ فلا يمكن الوصول إلى عناوين الشبكات الداخلية.
• عند الوصول إلى المواقع عبر وكيل، يُرجى الالتزام بشروط استخدام الموقع المستهدف والقوانين المحلية.

لالتقاط صفحات تتطلب تسجيل الدخول، يمكنك إرفاق حالة تسجيل الدخول لحسابك الشخصي بإحدى طريقتين: تمرير cookies وheaders وlocal_storage وsession_storage مباشرةً في الطلب، أو استخدام إضافة Glanceshot للمتصفح لحفظ الحالة في «ملف تسجيل دخول»، ثم تمرير login_profile فقط في الطلب.

curl -X POST "https://glanceshot.com/v1/screenshot"   -H "X-Access-Key: $GLANCESHOT_KEY"   -H "Content-Type: application/json"   -d '{
    "url": "https://app.example.com/dashboard",
    "cookies": "sid=YOUR_SESSION; theme=dark",
    "local_storage": {"token": "YOUR_TOKEN"}
  }' -o screenshot.png

• تستطيع الإضافة قراءة بيانات اعتماد تسجيل الدخول التي لا تستطيع البرامج النصية في الصفحة قراءتها (بما فيها ملفات Cookie من نوع HttpOnly)، وكذلك localStorage وIndexedDB، وهي مناسبة لمعظم المواقع. انتقل إلى صفحة «ملفات تسجيل الدخول» في لوحة التحكم لتثبيت الإضافة وربطها.
• لا يمكن تمرير حالة تسجيل الدخول إلا في جسم طلب POST (تُرفض طلبات GET وعناوين URL الموقّعة)، ولا تُدوّن في السجلات أو سجل استدعاءات API؛ وتُخزّن الطلبات التي تتضمن حالة تسجيل دخول مؤقتًا بشكل منفصل بحسب تلك الحالة، ولا تُشارك مع الآخرين.
• إذا أُرفقت حالة تسجيل الدخول لكن الصفحة أعادت التوجيه إلى صفحة تسجيل الدخول، يُرجع login_expired ولا تُحتسب رسوم (يعني ذلك انتهاء صلاحية تسجيل الدخول؛ أعد المزامنة باستخدام الإضافة).
• للمواقع التي تربط الجلسة بالجهاز أو بعنوان IP ولا يمكن استعادة حالة تسجيل الدخول إليها في السحابة (مثل الخدمات المصرفية عبر الإنترنت)، استخدم خيار «التقاط الصفحة الحالية» في الإضافة لالتقاط لقطة شاشة في متصفحك ثم رفعها.

تُستخدم النتيجة المخزّنة مؤقتًا للطلبات ذات المعلمات المتطابقة (يُعدّ حذف المعلمة وتمرير قيمتها الافتراضية صراحةً متكافئين؛ ولا تدخل معلمات المصادقة والتخزين المؤقت في المقارنة). عند العثور على نتيجة مخزّنة، يُرجع الوضع الثنائي إعادة توجيه 302 إلى عنوان الملف مع Cache-Control، ويتبع المتصفح إعادة التوجيه ويخزّن الملف تلقائيًا؛ أما وضع JSON فيُرجع cache_hit: true.

لا تُحتسب النتائج المسترجعة من الذاكرة المؤقتة من الحصة.تُنفَّذ عملية عرض واحدة فقط للطلبات المتزامنة ذات المعلمات نفسها.

• تُحتسب فقط الطلبات الناجحة (2xx) التي لا تستخدم نتيجة مخزّنة مؤقتًا: 1 للقطة الشاشة، و2 لملف PDF.
• لا تُخصم أي حصة عند انتهاء المهلة، أو فشل العرض، أو حدوث خطأ في الموقع المستهدف أو حظره للوصول، أو وجود خطأ في المعلمات، أو فشل المصادقة.
• تُجدَّد الحصة كل شهر تقويمي حسب UTC. تتضمن الخطة المجانية 100 عملية شهريًا، وتُرجع quota_exceeded عند نفادها.
• عند تجاوز حد الطلبات في الثانية أو حد التزامن، تُرجع الاستجابة 429، وتحدّد الترويسة Retry-After مدة الانتظار المقترحة بالثواني.
• المدة القصوى للعرض 30 ثانية؛ والحد الأقصى لتنزيلات الصفحة الواحدة 50 MB؛ والحد الأقصى لحجم الملف الناتج 50 MB.

للاطّلاع على الحدود التفصيلية لكل خطة: الأسعار.

تُرجع جميع استجابات الأخطاء بصيغة JSON:

{
  "error": {
    "code": "render_failed",
    "message": "target responded with an error status",
    "upstream_status": 404,
    "request_id": "req_01j…"
  }
}

أرسل من 1–100 عنوان في طلب واحد، وستُرجع الواجهة معرّف المهمة فورًا (HTTP 202)، ثم تُلتقط الصفحات تباعًا في الخلفية. يناسب ذلك التقاط دفعات من الصفحات دون إبقاء الاتصال مفتوحًا. يمكنك الاستعلام دوريًا عن الحالة، أو تحديد webhook_url لتلقّي إشعار منا عند اكتمال جميع العمليات. تُستخدم طريقة المصادقة نفسها الخاصة بالواجهة المتزامنة (عبر ترويسة الطلب أو معلمة access_key فقط؛ روابط URL الموقّعة غير مدعومة).

curl -X POST "https://glanceshot.com/v1/batch" \
  -H "X-Access-Key: $GLANCESHOT_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "screenshot",
    "urls": ["https://example.com", "https://example.org"],
    "options": { "full_page": true, "format": "webp" },
    "webhook_url": "https://your-app.com/hooks/glanceshot"
  }'

# الاستجابة 202
{
  "id": "bat_01j…",
  "type": "screenshot",
  "status": "queued",
  "total": 2, "succeeded": 0, "failed": 0,
  "created_at": "2026-10-18T09:30:00Z", "completed_at": null,
  "webhook": { "url": "https://your-app.com/hooks/glanceshot", "status": "none", "attempts": 0 },
  "items": [
    { "index": 0, "url": "https://example.com", "status": "pending", "result": null, "error": null },
    { "index": 1, "url": "https://example.org", "status": "pending", "result": null, "error": null }
  ]
}

الاستعلام عن التقدّم: تنتقل حالة المهمة status بالترتيب من queued (في قائمة الانتظار) إلى running (قيد المعالجة)، ثم completed (اكتملت جميع العمليات، سواء نجحت أم فشلت). وتكون حالة كل عنوان pending أو running أو succeeded أو failed. عند النجاح، يظهر عنوان الملف في result؛ وعند الفشل، يظهر رمز الخطأ في error (وهو مطابق لرموز أخطاء الواجهة المتزامنة).

curl "https://glanceshot.com/v1/batch/bat_01j…" -H "X-Access-Key: $GLANCESHOT_KEY"

{
  "id": "bat_01j…",
  "status": "completed",
  "total": 2, "succeeded": 1, "failed": 1,
  "completed_at": "2026-10-18T09:30:12Z",
  "items": [
    {
      "index": 0, "url": "https://example.com", "status": "succeeded", "duration_ms": 1830,
      "result": { "url": "https://glanceshot.com/i/3f/3f9c….webp", "mime": "image/webp", "width": 1280, "height": 2410, "cache_hit": false },
      "error": null
    },
    {
      "index": 1, "url": "https://example.org", "status": "failed", "duration_ms": 640,
      "result": null,
      "error": { "code": "render_failed", "message": "target responded with an error status" }
    }
  ]
}

• تُطبَّق قواعد الفوترة نفسها الخاصة بالواجهة المتزامنة: يُحتسب 1 لكل لقطة شاشة ناجحة و2 لكل ملف PDF ناجح، ولا تُخصم حصة للنتائج المخزّنة مؤقتًا أو العمليات الفاشلة.
• إذا كانت الحصة قد نفدت عند الإرسال، تُرجع الواجهة quota_exceeded فورًا. وإذا نفدت أثناء المعالجة، تفشل العناوين المتبقية بالرمز quota_exceeded.
• يمكن لكل حساب تشغيل ما يصل إلى 5 مهام دفعية غير مكتملة في الوقت نفسه؛ ويُرجع too_many_batches عند تجاوز هذا الحد.
• تحدّد options.cache_ttl مدة صلاحية ملفات النتائج (الافتراضي يوم واحد). احرص على تنزيلها وحفظها قبل انتهاء صلاحيتها.
• تُعرض قيمة webhook.url في نتائج الاستعلام وإشعارات الاكتمال حتى المسار فقط، دون سلسلة الاستعلام.

عند تحديد webhook_url، نرسل إليه طلب POST بعد اكتمال المهمة بالكامل. يكون جسم الطلب بصيغة JSON: ‏{ "event": "batch.completed", "batch": { … } }، ويطابق batch استجابة واجهة الاستعلام تمامًا. ترويسات الطلب:

• X-Glanceshot-Signature: t=1760779812,v1=5d3f…: ‏t هو وقت الإرسال (بالثواني وفق توقيت Unix)، وv1 هو التوقيع
• X-Glanceshot-Event: batch.completed وX-Glanceshot-Delivery-Attempt: 1 (رقم محاولة التسليم)

v1 = hex(HMAC-SHA256(secret, t + "." + نص الطلب الخام))
secret هو سر التوقيع المرتبط بـ API Key المستخدم عند إرسال المهمة (يمكنك عرضه في صفحة API Key في لوحة التحكم)

• يجب إرجاع رمز حالة 2xx خلال 10 ثوانٍ، وإلا فستُعدّ المحاولة فاشلة. عند الفشل، تُعاد المحاولة بعد 10 ثوانٍ، ثم بعد 1 دقيقة، ثم بعد 5 دقائق (بحد أقصى 4 محاولات إجمالًا).
• في حالات نادرة جدًا، قد تتلقى إشعارات مكررة للمهمة نفسها. استخدم batch.id لتجاهل التكرارات.
• للتحقق من التوقيع، احسبه باستخدام البايتات الخام المستلمة، وتأكد من أن الفرق بين t والوقت الحالي لا يتجاوز بضع دقائق لمنع هجمات إعادة الإرسال.
• يجب أن يكون عنوان رد الاتصال عنوان http(s) متاحًا عبر الإنترنت، ولا يجوز أن يشير إلى شبكة داخلية.

import crypto from "node:crypto";

// يجب أن يحتوي rawBody على البايتات الأصلية المستلمة، دون تحليلها باستخدام JSON.parse ثم إعادة تسلسلها
function verifyGlanceshotWebhook(rawBody, header, secret, toleranceSec = 300) {
  const parts = Object.fromEntries(header.split(",").map((p) => p.split("=")));
  const t = Number(parts.t);
  if (!t || Math.abs(Date.now() / 1000 - t) > toleranceSec) return false; // منع هجمات إعادة الإرسال
  const expected = crypto.createHmac("sha256", secret).update(`${t}.${rawBody}`).digest("hex");
  const got = Buffer.from(parts.v1 ?? "");
  return got.length === expected.length && crypto.timingSafeEqual(Buffer.from(expected), got);
}

// verifyGlanceshotWebhook(req.rawBody, req.headers["x-glanceshot-signature"], GLANCESHOT_SECRET)

لا يتطلب مصادقة، ويُرجع حالة العقدة وحالة مجموعة المتصفحات (الإجمالي، والمشغول، والمتاح).