أساسيات الواجهة البرمجية

العنوان الأساسي: https://api.seekgist.com. يبدأ كل مسار بـ /v1. القائمة الكاملة لنقاط الوصول في مرجع الواجهة البرمجية.

المفاتيح

أرسل المفتاح بإحدى هذه الطرق:

Authorization: Bearer sg_pub_...
X-SeekGist-Key: sg_pub_...
GET /v1/suggest?q=lab&key=sg_pub_...        (public keys only)

• يُرفض المفتاح السري داخل الرابط برمز 401.
• يمكنك ربط المفتاح العام بموقعك فقط عبر allowed_origins.
• لكل مفتاح صلاحيات، مثل search أو catalog:write. إذا نقصت صلاحية فالرد 403 insufficient_scope.
• يخبرك GET /v1/whoami بالمتجر والصلاحيات المرتبطة بالمفتاح. تستخدمه الإضافات في زر «اختبار الاتصال».

الأخطاء

لكل خطأ الشكل نفسه (RFC 9457، وContent-Type: application/problem+json):

{
  "type": "https://seekgist.com/docs/errors/invalid_request",
  "title": "Invalid request",
  "status": 422,
  "code": "invalid_request",
  "detail": "Some fields are not valid.",
  "request_id": "req_4f1c0d9a8b7e6f5a4b3c",
  "errors": [{ "field": "upsert.3.price", "code": "greater_than_equal", "message": "Input should be >= 0" }]
}

اعتمد في برنامجك على code لأنه لا يتغير أبدًا. واذكر request_id عندما تطلب المساعدة.

إعادة المحاولة الآمنة

أرسل Idempotency-Key: <قيمة فريدة من 8 إلى 255 حرفًا> مع طلبات الكتابة (POST وPUT وPATCH وDELETE). إذا انقطع الاتصال وأرسلت الطلب نفسه مرة أخرى بالمفتاح نفسه، يصلك الرد الأول مع Idempotent-Replayed: true ولا يتكرر أي شيء.

• تُحفظ هذه المفاتيح 24 ساعة لكل متجر.
• المفتاح نفسه مع محتوى مختلف يعطي 422 idempotency_key_reuse.
• المفتاح نفسه أثناء تنفيذ الطلب الأول يعطي 409 idempotency_in_progress.

الاستخدام والفوترة

• يُحتسب البحث فقط: أي طلب /v1/search للصفحة الأولى (page=1). الصفحة الثانية وما بعدها مجانية.
• الاقتراحات أثناء الكتابة لا تُحتسب أبدًا.
• يحمل كل رد بحث ترويسة مثل هذه (limit=-1 تعني عدم وجود حد ثابت):

X-SeekGist-Usage: searches=1234, limit=150000, billed=1, period="2026-10"

حدود عدد الطلبات

الحدود لكل مفتاح في كل ثانية. يحمل كل رد RateLimit-Limit وRateLimit-Remaining. إذا تجاوزت الحد يصلك 429 rate_limited مع Retry-After.

القوائم

ترد القوائم بالشكل {"data": [...], "next_cursor": "...", "total": 123}. أعد إرسال next_cursor في ?cursor= لتحصل على الصفحة التالية. يظهر total عندما يكون حسابه سهلًا.

المهام الطويلة

إعادة الفهرسة والاستيراد والمزامنة والترجمة والتصدير ترد برمز 202 ومعها job. استدعِ GET /v1/jobs/{id} حتى تصبح status إحدى القيم succeeded أو failed أو canceled.

اللغات

تأخذ lang وlocale وtarget_locale رمزًا من حرفين (en أو ar). يجب أن يكون من لغات متجرك (يعرضها GET /v1/settings في locales)، وإلا فالرد 422 unsupported_locale. القيمة lang=auto تجعل SeekGist يكتشف اللغة بنفسه.

خطافات الويب

تُوقَّع خطافات الويب وفق معيار Standard Webhooks. تحقّق من التوقيع قبل أن تثق بأي رسالة:

import base64, hashlib, hmac, time
 
def verify(secret: str, headers: dict, body: bytes) -> bool:
    key = base64.b64decode(secret.removeprefix("whsec_"))
    msg_id, ts = headers["webhook-id"], headers["webhook-timestamp"]
    if abs(time.time() - int(ts)) > 300:
        return False
    mac = hmac.new(key, f"{msg_id}.{ts}.".encode() + body, hashlib.sha256).digest()
    expected = "v1," + base64.b64encode(mac).decode()
    return any(hmac.compare_digest(expected, s) for s in headers["webhook-signature"].split())

ارفض أي طابع زمني يبعد عن الوقت الحالي أكثر من 5 دقائق، وتجاهل أي webhook-id وصلك من قبل. تُعاد محاولة الإرسال الفاشل بفواصل متزايدة لمدة 3 أيام، ثم يُعلَّم بالحالة dead.

الإصدارات

الإصدار /v1 يتوسع فقط: نقاط وصول جديدة، وحقول اختيارية جديدة، وقيم جديدة في الردود. يجب أن يتجاهل برنامجك الحقول التي لا يعرفها. أي تغيير يكسر التوافق سيأتي في /v2.