POST /v1/quotes

نقطة النهاية الرئيسية. تُسعِّر مجموعة اختيارية من الأدوات المخصّصة (ad-hoc) بالإضافة إلى قائمة من عروض الأسعار (quotes) التي تُشير إلى الأدوات عبر id (سواء كانت مخصّصة ضمن المجموعة أو مخزّنة). تُعيد دفعة من النتائج — مُدخل واحد لكل عرض سعر، لكلٍّ منها حالته الخاصة.

نص الطلب (Request body)

{
  "instruments": [ /* optional ad-hoc pool; each item needs an id */ ],
  "quotes": [ /* one or more quotes */ ]
}

حقول عرض السعر (Quote fields)

Field	Required	Description
instrument_id	yes	معرّف أداة مخصّصة ضمن المجموعة أو أداة مخزّنة
input_kind	yes	yield · clean_price · dirty_price · transacted
input_value	yes	العائد (عشري) أو السعر (لكل 100)، أو المبلغ النقدي المُتداوَل
amount_kind	no	nominal أو transacted (حجم الصفقة)
amount_value	no	مطلوب (> 0) عند ضبط amount_kind
settlement_date	no	تاريخ بصيغة ISO؛ القيمة الافتراضية هي تاريخ اليوم
options	no	انظر أدناه

input_kind

Value	You supply	emrgex returns
yield	عائد	السعر + المقاييس
clean_price	سعر نظيف	العائد المحلول + المقاييس
dirty_price	سعر متّسخ	العائد المحلول + المقاييس
transacted	مبلغ نقدي متّسخ (يتطلّب amount_kind: nominal)	يشتقّ السعر، ثم يحلّ العائد

options

Option	Type	Description
round	int (0–12)	تقريب مخرجات المبالغ/المعدّلات إلى N من المنازل العشرية
with_cashflows	bool	تضمين جدول التدفّقات النقدية المخصومة بالكامل
yield_worst	bool	حساب العائد حتى الأسوأ (yield-to-worst) للسندات القابلة للاستدعاء
coupon_type	FIXED/ACCRUAL	تجاوُز آلية القسيمة لكل عرض سعر (سيناريو افتراضي what-if)
index_ratio	number	القيمة الاسمية المعلَنة للمؤشّر (VNA) للسندات المرتبطة بمؤشّر؛ يُضرَب كل مخرَج نقدي في index_ratio/100

الاستجابة — غلاف الدفعة (batch envelope)

{
  "data": [
    {
      "index": 0,
      "id": "MH12034",
      "status": "ok",
      "data": {
        "instrument_id": "MH12034",
        "convention": "NOMINAL · ACT/ACT.DRMH",
        "calculation_code": "ACT/ACT.DRMH|NOMINAL",
        "coupon_type": "ACCRUAL",
        "settlement_date": "2026-06-09T00:00:00Z",
        "metrics": { "yield": 0.1, "dirty_price": 112.547645, "clean_price": 107.853124, "...": "..." },
        "next_coupon": { "date": "...", "interest": 5.75, "total": 5.75, "present_value": 5.7 }
      }
    }
  ],
  "warnings": []
}

• يحمل كل مُدخل إمّا status: "ok" مع حمولة data، أو status: "failed" مع كائن error متوافق مع RFC 7807 — فشل عرض سعر واحد لا يُفشِل الدفعة بأكملها أبدًا.
• يُعيد حلُّ السعر→العائد غير المتقارِب رمز 422 على مستوى المُدخل المعني.

سيناريوهات الإدخال الخمسة

يُغطّي حاصل الضرب input_kind × amount_kind التركيبات المُتداوَلة:

input_kind	amount_kind	Use
yield	nominal	عائد + قيمة اسمية ← السعر والمبلغ النقدي عند التسوية
yield	transacted	عائد + مبلغ نقدي ← القيمة الاسمية الضمنية
clean_price	nominal	سعر + قيمة اسمية ← العائد والمبلغ النقدي
clean_price	transacted	سعر + مبلغ نقدي ← العائد والقيمة الاسمية
transacted	nominal	مبلغ نقدي + قيمة اسمية ← السعر والعائد

انظر الأمثلة للاطّلاع على نصوص الطلبات الكاملة.