Octane
واجهة السحب

قائمة المعاملات

يعيد GET /transactions معاملات الوقود بحالة CONFIRMED وEXTERNAL لنطاق تاريخ حتى 31 يومًا، 100 سجل في الصفحة، مع شرح كل حقل.

GET /api/v1/integration/transactions

يعيد معاملات الوقود بحالة CONFIRMED وEXTERNAL الخاصة بالمستدعي والمنشأة ضمن نطاق تاريخ، الأحدث أولًا، مع ترقيم صفحات بالمؤشر. يُستنتج حساب العميل من مفتاح API.

معاملات الاستعلام

المعاملالنوعمطلوبالوصف
fromتاريخ ووقت ISO 8601نعمبداية النطاق على created_at (شاملة).
toتاريخ ووقت ISO 8601نعمنهاية النطاق على created_at. يمتد النطاق حتى 31 يومًا كحد أقصى.
corporate_group_idعدد صحيحلاحصر النتائج في مجموعة شركات واحدة. يجب أن تنتمي إلى حسابك.
corporate_idعدد صحيح أو قائمة مفصولة بفواصللاحصر النتائج في شركة أو أكثر. يجب أن تنتمي إلى حسابك، وإلى المجموعة إذا أُعطي corporate_group_id أيضًا.
statusقائمة من CONFIRMED، EXTERNALلاتصفية حسب الحالة. تُعاد الحالتان عند الحذف.
limitعدد صحيحلاحجم الصفحة. الافتراضي 50، والأقصى 100.
cursorنصلامؤشر معتم من pagination.next_cursor في الصفحة السابقة. كرر المرشحات نفسها عند تمريره.

مرر عدة حالات كقائمة مفصولة بفواصل، مثل status=CONFIRMED,EXTERNAL.

أي المعاملات تُعاد؟

  • معاملات CONFIRMED وEXTERNAL فقط. لا تُعاد معاملات PENDING وVOID وCANCELED أبدًا. المعاملة التي تُلغى بعد جلبها تختفي ببساطة من النتائج اللاحقة للنطاق نفسه. راجع اكتشاف المعاملات الملغاة.
  • معاملات الاسترداد (للتكرار أو الفروق أو النزاعات المحلولة) تُعاد، مع correction_reference_id يشير إلى المعاملة الأصلية.
  • تسويات الرصيد اليدوية التي يجريها محاسبو أوكتين لا تُعاد أبدًا.

مثال طلب

curl -G "https://prod-app.octanetech-api.com/api/v1/integration/transactions" \
  -H "X-API-Key: $OCTANE_API_KEY" \
  --data-urlencode "from=2026-09-01T00:00:00Z" \
  --data-urlencode "to=2026-09-30T23:59:59Z" \
  --data-urlencode "corporate_id=67,68" \
  --data-urlencode "status=CONFIRMED" \
  --data-urlencode "limit=100"

مثال استجابة

{
  "data": [
    {
      "id": 185432,
      "status": "CONFIRMED",
      "created_at": "2026-09-20T08:59:36.340Z",
      "confirmed_at": "2026-09-20T09:00:02.110Z",
      "correction_reference_id": null,
      "corporate": { "id": 67, "name": "Acme Logistics" },
      "corporate_group": { "id": 9, "name": "Acme Group" },
      "fuel": {
        "type": { "id": 2, "name": "Benzine 92" },
        "liters": 18.5,
        "price_per_liter": 13.75,
        "amount": 254.38
      },
      "odometer_reading": 120450,
      "distance_traveled": 312,
      "fuel_consumption": 5.93,
      "station": {
        "id": 164,
        "name": "Misr Petroleum - Ring Road",
        "provider": { "id": 7, "name": "Misr Petroleum" },
        "is_external": false
      },
      "vehicle": {
        "id": 4,
        "code": "V-004",
        "number_plate": "ABC 1234",
        "chassis_number": "JTDBR32E720123456",
        "brand": "Toyota",
        "model": "Hilux",
        "year": 2021,
        "department": { "id": 3, "name": "Distribution" }
      },
      "driver": { "id": 31, "name": "Ahmed Mostafa" },
      "fees": {
        "total_fees": 1.06,
        "total_vat": 0.13,
        "total_amount": 255.435000
      },
      "images": {
        "pump": "https://storage.example/pump.jpg?X-Amz-Expires=3600&...",
        "odometer": "https://storage.example/odometer.jpg?X-Amz-Expires=3600&...",
        "expires_at": "2026-09-20T10:00:02Z"
      }
    }
  ],
  "pagination": {
    "limit": 100,
    "has_more": true,
    "next_cursor": "eyJ0IjoiMjAyNi0wOS0yMFQwODo1OTozNi4zNDBaIiwiaWQiOjE4NTQzMn0"
  }
}

قد تتضمن الاستجابات الناجحة أيضًا ترويسة X-Access-Expires-At. راجع انتهاء الوصول.

كائن المعاملة

المستوى الأعلى

الحقلالنوعالوصف
idعدد صحيحمعرّف المعاملة الفريد. ثابت بين واجهة السحب وتسليمات الويب هوك.
statusCONFIRMED أو EXTERNAL
created_atتاريخ ووقتوقت إنشاء المعاملة. ينطبق مرشحا from وto على هذا الحقل.
confirmed_atتاريخ ووقت، قد يكون فارغًاوقت تأكيد المعاملة.
correction_reference_idعدد صحيح، قد يكون فارغًالمعاملات الاسترداد، معرّف المعاملة الأصلية المصحَّحة. null في غير ذلك.
corporateكائنالشركة التي تتبعها المركبة. موجود دائمًا.
corporate_groupكائن، قد يكون فارغًامجموعة الشركة. null عندما لا تكون الشركة ضمن مجموعة.
fuelكائننوع الوقود والكمية والسعر.
odometer_readingعدد صحيح، قد يكون فارغًاقراءة العداد الملتقطة عند المعاملة، إن توفرت.
distance_traveledعدد صحيح، قد يكون فارغًاالمسافة منذ المعاملة السابقة للمركبة، عندما يمكن حسابها.
fuel_consumptionرقم، قد يكون فارغًالترات لكل 100 كم منذ المعاملة السابقة، عندما يمكن حسابها.
stationكائنمكان صرف الوقود.
vehicleكائنالمركبة التي تم تزويدها.
driverكائنالسائق.
feesكائنإجمالي الرسوم وإجمالي الضريبة والإجمالي المحصَّل.
imagesكائنروابط موقّعة لصور المضخة والعداد.

corporate وcorporate_group

الحقلالنوعالوصف
idعدد صحيح
nameنص

fuel

الحقلالنوعالوصف
type.idعدد صحيحمعرّف نوع الوقود.
type.nameنصاسم نوع الوقود، مثل Benzine 92.
litersرقمالكمية المصروفة، منزلتان عشريتان.
price_per_literرقمسعر الوحدة، منزلتان عشريتان.
amountرقممبلغ الوقود قبل الرسوم، منزلتان عشريتان.

station

الحقلالنوعالوصف
idعدد صحيح، قد يكون فارغًامعرّف المحطة. null للمحطات الخارجية.
nameنصاسم المحطة. للمعاملات الخارجية، اسم المحطة الخارجية كما أُدخل.
providerكائن، قد يكون فارغًامزود المحطة (id، name). null للمحطات الخارجية.
is_externalمنطقيtrue عندما تُسجَّل المعاملة في محطة خارج شبكة أوكتين.

vehicle

الحقلالنوعالوصف
idعدد صحيح
codeنص، قد يكون فارغًاكود المركبة الداخلي لديك كما هو مضبوط في أوكتين.
number_plateنص، قد يكون فارغًا
chassis_numberنص، قد يكون فارغًا
brand، modelنص، قد يكون فارغًا
yearعدد صحيح، قد يكون فارغًا
departmentكائن، قد يكون فارغًاقسم المركبة (id، name)، عند تعيينه.

driver

الحقلالنوعالوصف
idعدد صحيح
nameنص
mobile_numberنصموجود فقط عندما تفعّل أوكتين أرقام جوال السائقين على مفتاحك. اسأل مدير حسابك إن احتجته.

لا يُعاد البريد الإلكتروني للسائق أبدًا.

fees

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

الحقلالنوعالوصف
total_feesرقمكل رسوم الخدمة المطبقة على المعاملة، دون الضريبة. منزلتان عشريتان.
total_vatرقمكل ضريبة القيمة المضافة المطبقة على المعاملة. منزلتان عشريتان.
total_amountرقمالإجمالي المخصوم من رصيدك: fuel.amount + total_fees + total_vat. ست منازل عشرية ليطابق كشف حساب أوكتين تمامًا.

تُعاد الرسوم كما هي مسجلة على المعاملة، لمعاملات EXTERNAL كما لمعاملات CONFIRMED. تفصيل أنواع الرسوم الفردية ليس جزءًا من الواجهة.

images

الحقلالنوعالوصف
pumpنص (رابط)، قد يكون فارغًاصورة شاشة المضخة. null عندما لا توجد صورة.
odometerنص (رابط)، قد يكون فارغًاصورة العداد. null عندما لا توجد صورة.
expires_atتاريخ ووقتوقت توقف الروابط عن العمل.

روابط الصور موقّعة مسبقًا وتنتهي بعد ساعة واحدة. نزّل الصور فورًا إن احتجت إلى الاحتفاظ بها؛ ولا تخزّن الروابط. أعد جلب المعاملة للحصول على روابط جديدة.

المعاملات الخارجية

المعاملة بحالة EXTERNAL سُجّلت في محطة خارج شبكة أوكتين. لها شكل المعاملة المؤكدة نفسه، مع هذه الفروق:

  • status هي EXTERNAL.
  • station.is_external هي true، وstation.id وstation.provider هما null، وstation.name هو اسم المحطة الخارجية.
  • تُعاد fees كما هي مسجلة، وقد تكون صفرًا أو غير صفر حسب اتفاقك.

قواعد الدقة

الحقلالدقة
fuel.liters، fuel.price_per_liter، fuel.amountمنزلتان عشريتان
fees.total_fees، fees.total_vatمنزلتان عشريتان
fees.total_amountست منازل عشرية
fuel_consumptionمنزلتان عشريتان

الأخطاء

الحالةالرمزالسبب
400VALIDATION_FAILEDمعامل مفقود أو غير صالح، أو نطاق يتجاوز 31 يومًا، أو limit فوق 100، أو status غير معروفة، أو cursor غير صالح. يحدد كائن fields المعامل المخالف.
404CORPORATE_NOT_FOUNDقيمة corporate_id لا تنتمي إلى حسابك (أو إلى المجموعة المعطاة).
404CORPORATE_GROUP_NOT_FOUNDقيمة corporate_group_id لا تنتمي إلى حسابك.

بالإضافة إلى أخطاء المصادقة والشبكة المشتركة. راجع الأخطاء.

الشبكة وحدود المعدل

تقبل مفاتيح الإنتاج الطلبات من عناوين IP المسجلة فقط، وكل مفتاح محدود بـ 60 طلبًا في الدقيقة. كيفية التعامل مع 403 و429.

ترقيم الصفحات

تُرقَّم نقطة نهاية المعاملات بمؤشر معتم. مرر next_cursor مع المرشحات نفسها حتى تصبح has_more خاطئة. لا سجلات متخطاة ولا مكررة.

في هذه الصفحة

معاملات الاستعلامأي المعاملات تُعاد؟مثال طلبمثال استجابةكائن المعاملةالمستوى الأعلىcorporate وcorporate_groupfuelstationvehicledriverfeesimagesالمعاملات الخارجيةقواعد الدقةالأخطاء