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

العنوان الأساسي: 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.

جلسة المتسوق

يقبل البحث والاقتراحات الحقل session: رقم عشوائي لزيارة متسوق واحد (أبقِه نفسه طوال الزيارة). لا تضع فيه اسمًا أو بريدًا إلكترونيًا. تستخدم التحليلات والمرادفات المقترحة عمليات البحث التي تحمله فقط، لذا أرسله من خادمك أيضًا.

curl --get "https://api.seekgist.com/v1/search" \
  --data-urlencode "q=white sneakers" \
  --data-urlencode "session=$SHOPPER_SESSION_ID" \
  -H "Authorization: Bearer $SEEKGIST_PUBLIC_KEY"

وفي جسم JSON (POST /v1/search) هو الحقل "session".

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

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

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

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

الحدود لكل مفتاح في كل ثانية. يحمل كل رد 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 وصلك من قبل. وتتحقق حزم التطوير من التوقيع والوقت عنك: verifyWebhook (JavaScript)، وSeekGist\Webhook::verify (PHP)، وverify_webhook (Python). تُعاد محاولة الإرسال الفاشل بفواصل متزايدة لمدة 3 أيام، ثم يُعلَّم بالحالة dead.

الإصدارات

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