التوثيق — الإصدار v1

المصادقة

كل نداء يحمل ثلاث ترويسات. التوقيع على "{timestamp}.{raw_body}" بخوارزمية HMAC-SHA256 وسرّك، ونافذة القبول ٣٠٠ ثانية — فاضبط ساعة خادمك، فهي أكثر أسباب فشل التوقيع.

X-Syriana-Key:       sy_live_xxxxxxxxxxxx
X-Syriana-Timestamp: 1756000000
X-Syriana-Signature: hex(hmac_sha256(secret, "1756000000." + body))

import hashlib, hmac, json, time, requests

KEY, SECRET = "sy_test_...", "...."
BASE = "https://syriana.store"

def call(method, path, payload=None):
    body = json.dumps(payload, ensure_ascii=False) if payload else ""
    ts = str(int(time.time()))
    sig = hmac.new(SECRET.encode(), f"{ts}.{body}".encode(),
                   hashlib.sha256).hexdigest()
    return requests.request(method, BASE + path, data=body.encode(), headers={
        "X-Syriana-Key": KEY,
        "X-Syriana-Timestamp": ts,
        "X-Syriana-Signature": sig,
        "Content-Type": "application/json",
    })

print(call("GET", "/api/v1/ping").json())

شكل الردّ

ثابت لا يتغيّر: النجاح دائماً data وmeta، والفشل دائماً error. الحقول تُضاف ولا تُحذف، فما تبنيه اليوم يبقى يعمل.

{"data": {...}, "meta": {"version": "v1", "page": 1, "total": 201}}
{"error": {"code": "missing_scope", "message": "..."}}

نقاط النهاية

التحقّق

الكتالوج

المحفظة

الطلبات

الإشعارات الصادرة

نرسلها إلى الرابط الذي تسجّله، موقّعة بنفس الخوارزمية في X-Syriana-Signature. أعد 2xx لتأكيد الاستلام؛ وإلّا نعيد المحاولة ست مرّات على مدى ٤ ساعات.

رموز الأخطاء