مخطّط الحمولة

سبكترا يقبل شكل JSON واحداً على POSTs الـ webhook. أي شيء آخر يُرجع 400 Bad Request مع جسم خطأ مخطّط.

أمر بسيط

{
  "action": "buy",
  "symbol": "BTCUSDT",
  "qty": 1
}

يوجّه شراء market. اتصال الوسيط يُحدّد بأي سرّ وُقِّع به الطلب.

المخطّط الكامل

{
  "action": "buy" | "sell" | "close" | "flatten",
  "symbol": "string",
  "qty":    number,
  "type":   "market" | "limit" | "stop" | "stop_limit"
            | "trailing_stop",      // الافتراضي: market
  "limit_price":   number,           // مطلوب لـ limit / stop_limit
  "stop_price":    number,           // مطلوب لـ stop / stop_limit
  "trail_offset":  number,           // مطلوب لـ trailing_stop
  "tp":     number | { "value": number, "kind": "abs" | "pct" | "atr" },
  "sl":     number | { "value": number, "kind": "abs" | "pct" | "atr" },
  "tif":    "day" | "gtc" | "ioc" | "fok", // الافتراضي: day
  "client_id": "string"              // مفتاح idempotency خاصّك (≤ ٦٤ حرفاً)
}

flatten يتجاهل qty ويُغلق كل شيء للرمز. close يُغلق كمية محدّدة (افتراضي = المركز الكامل).

Idempotency

إن ضُبط client_id، يقوم سبكترا بحذف المكرّرات. إعادة POST لنفس client_id خلال ٢٤ ساعة تُرجع 200 OK بالنتيجة الأصلية بدلاً من وضع أمر مكرّر. موصى به لأي مصدر تنبيه قد يعيد المحاولة من تلقاء نفسه (معظمها يفعل — اضبط client_id فريداً لكل أمر مقصود).

الاستجابة

202 Accepted   →  body: { "order_id": "...", "client_id": "..." }
400 Bad Request →  فشل المخطّط أو قواعد الأعمال (خرق سقف الخسارة، ...)
401 Unauthorized →  توقيع/طابع زمني غير صالح
403 Forbidden  →  IP خارج القائمة، أو سرّ متوقّف
429 Too Many Requests →  حد المعدّل (١ طلب/ث/سرّ افتراضياً)