المطوّرون

واجهة API للموردين

نقطة نهاية واحدة. انشر مصفوفة أسعار، واسترجع ما نُشِر وما احتُجِز. لا SDK لتثبيته ولا تكامل يستدعي جدولة مكالمة بشأنه — إن كان نظامك يملك أرقام اليوم أصلًا، فهذه طلب HTTP واحد.

احصل على مفتاح

افتح بوابة الموردين بالعنوان الذي يُصدر مكتبك عروضه منه. الرابط الذي يصلك يسجّل دخولك، ومفتاحك على تلك الصفحة. تبدأ المفاتيح بـ bfps_ ولا تنتهي صلاحيتها أبدًا؛ ويمكنك تدوير أحدها من الصفحة نفسها.

تعامل معه كأنه كلمة مرور. أي شخص يحوزه يمكنه نشر أسعار باسمك، وسعر خاطئ منسوب إليك أسوأ لك منه لنا.

نشر الأسعار

POST https://bunkerfuelprices.com/api/v1/supplier/prices

curl -X POST https://bunkerfuelprices.com/api/v1/supplier/prices \
  -H "Authorization: Bearer bfps_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prices": [
      { "port": "SGSIN", "grade": "VLSFO", "amount": 784.50 },
      { "port": "SGSIN", "grade": "MGO",   "amount": 1146.00 },
      { "port": "AEFJR", "grade": "VLSFO", "amount": 795.00,
        "minMt": 200, "validHours": 24, "basis": "delivered" }
    ]
  }'

الحقول

الحقل	النوع		ملاحظات
port	string	required	UN/LOCODE، خمسة أحرف — SGSIN وNLRTM وAEFJR. لا اسم الميناء. الرمز غير المعروف يُرفَض لذلك الصف وحده؛ ويُنشَر الباقي.
grade	enum	required	VLSFO · HSFO · MGO · ULSFO · LNG · B24 · B30
amount	number	required	السعر، بالعملة والوحدة أدناه.
currency	USD \| EUR	optional	الافتراضي USD. يُحوَّل EUR بسعر ECB المرجعي الحيّ في اليوم نفسه.
unit	mt \| litre \| m3	optional	الافتراضي mt. تُحوَّل الأرقام لكل لتر باستخدام كثافة الرتبة.
basis	delivered \| ex_wharf \| fob	optional	الافتراضي delivered. لهذا أهمية: سعر تسليم الرصيف (ex-wharf) معروضًا على أنه مُسلَّم (delivered) يُقلّل مما يدفعه المشتري، ونحن لا نقارن إلا ضمن الأساس الواحد.
minMt	number	optional	أدنى كمية ينطبق عليها السعر.
validHours	1–168	optional	المدة التي يظل فيها ساريًا. الافتراضي 24، وبعدها يُوسَم بأنه قديم بدل عرضه على أنه حالي.
taxIncluded	boolean	optional	الافتراضي false. يهمّ أساسًا مراسي اليخوت.

الاستجابة

{
  "accepted": 3,
  "published": 2,
  "held": 1,
  "results": [
    { "port": "SGSIN", "grade": "VLSFO", "ok": true, "published": true,
      "submissionId": "..." },
    { "port": "SGSIN", "grade": "MGO",   "ok": true, "published": true,
      "submissionId": "..." },
    { "port": "AEFJR", "grade": "VLSFO", "ok": true, "published": false,
      "heldForReview": ["38% away from the $795 median across 6 other ports"] }
  ]
}

الصف البعيد عن السوق في موانئ أخرى يُحتجَز لمراجعة شخص بدل نشره. ليس هذا تشكيكًا فيك — بل هو ما يمنع رقمًا كُتب خطأً من أن يصير رقمًا يتصرّف المشتري بناءً عليه، وهو يحمي اسمك أكثر مما يحمي اسمنا. تُطلَق الأسعار المحتجَزة عادة في اليوم نفسه.

الصفوف مستقلة. الصف الخاطئ لا يرفض الدفعة.

اقرأ ما لدينا

curl https://bunkerfuelprices.com/api/v1/supplier/prices \
  -H "Authorization: Bearer bfps_YOUR_KEY"

يعيد آخر مئة عملية إرسال لك مع حالتها، لتتمكن من المطابقة دون الاحتفاظ بسجلّ خاص بما قبلناه.

لوحة الأسعار العامة

مفتوحة، لا تحتاج مفتاحًا، ومفيدة للتحقق من موضع سعرك مقابل بقية السوق قبل نشره.

curl "https://bunkerfuelprices.com/api/v1/prices?grade=VLSFO&limit=50"

الأخطاء والحدود

الحالة	المعنى
200	تمت المعالجة. تحقّق من results — لا يعني رمز 200 أن كل صف قد نُشِر.
400	تعذّر تحليل المحتوى (body). تسمّي الاستجابة الحقل المعنيّ.
401	مفتاح مفقود أو خاطئ أو موقوف.

حتى 200 سعر لكل طلب. انشر بالوتيرة التي تشاء — تنشر معظم المكاتب مرة في الصباح ومرة أخرى إن تحرّك السوق. تكرار نشر الميناء والرتبة نفسيهما يحلّ محل السعر الأسبق بدل تكراره.

ماذا نفعل به

يظهر سعرك في صفحة الميناء بوصفه استرشاديًا، منسوبًا إلى شركتك، مع التاريخ. المشترون الذين يطالعون ذلك الميناء يرون اسمك بجوار رقم بدل فراغ، وتصلك طلبات عروض الأسعار بدل أن تمرّ من دونك.

لسنا موردًا للوقود ولا تاجرًا ولا وسيطًا، ولا نتّخذ أي مركز تداول في أي شحنة، فلا مصلحة لنا في سعرك سوى أن نكون على صواب بشأنه. التفاصيل الكاملة في سياسة البيانات والتسعير. اسحبه في أي وقت من البوابة، أو راسِل data@bunkerfuelprices.com.