واجهة API لشحن السيارات الكهربائية وwebhooks: دليل عملي للتكامل

نادرًا ما تبقى بيانات الشحن داخل منصة الشحن. فالإدارة المالية تريد تكاليف الطاقة في نظام المحاسبة، ومديرو الأساطيل يريدون الاستهلاك لكل مركبة إلى جانب بيانات التتبع عن بُعد (telematics)، والإدارة العليا تريد أرقام الشحن في لوحات التقارير نفسها التي تضم كل شيء آخر. ونسخ ملفات CSV كل شهر ينجح لفترة، لكنه لا يتوسع مع نمو العمل.

تحل واجهة برمجة تطبيقات شحن السيارات الكهربائية (API) هذه المشكلة، إذ تتيح للأنظمة الأخرى قراءة بيانات الشحن والتفاعل مع أحداث الشحن تلقائيًا. يشرح هذا الدليل لماذا وأين يجب التكامل، والفرق بين REST API وخطافات الويب (webhooks)، والبيانات المتاحة عادةً، وكيفية تأمين webhooks بتوقيعات HMAC، وكيفية تنفيذ التكامل بأمان. ويتضمن مثالًا عامًا بشيفرة زائفة (pseudo-code) يمكنك تكييفه مع أي لغة برمجة.

لماذا تُدمج بيانات الشحن مع أنظمتك؟

نظام إدارة محطات الشحن (CSMS) هو المصدر الموثوق لبيانات الجلسات والطاقة وحالة الشواحن. وتحتاج الأنظمة الأخرى إلى أجزاء من هذه البيانات:

• أنظمة ERP والمحاسبة: تسجيل تكاليف الشحن لكل موقع أو قسم أو مركز تكلفة دون إدخال يدوي.
• إدارة الأساطيل: إضافة الطاقة لكل مركبة ولكل سائق إلى سجلات المركبات. راجع دليلنا لإدارة شحن الأساطيل لمعرفة كيف يعمل توزيع التكاليف.
• ذكاء الأعمال (BI): دمج بيانات الاستخدام والطاقة مع بيانات الأعمال الأخرى في أداة تقارير واحدة.
• أنظمة إدارة العقارات والمرافق: توزيع طاقة الشحن على المستأجرين أو السكان أو نزلاء الفنادق.
• الإشعارات الداخلية: إبلاغ مسؤول التوزيع عند انتهاء شحن مركبة، أو فتح تذكرة دعم عند تعطل شاحن.

يُلغي التكامل العمل اليدوي المتكرر، ويقلل أخطاء النقل، ويجعل البيانات متاحة بشكل أسرع.

REST API مقابل webhooks

توفّر معظم منصات الشحن طريقتين متكاملتين للتكامل.

عمليًا، تستخدم عمليات التكامل المتينة الطريقتين معًا. فخطافات webhooks تسلّم الأحداث بسرعة، واستدعاء REST دوري يطابق البيانات ويسد أي فجوات، مثلًا إذا كانت نقطة النهاية لديك متوقفة للصيانة.

البيانات المعتادة في واجهة API لشحن السيارات الكهربائية

• الجلسات: وقت البدء والانتهاء، والمحطة، والموصل، والطاقة بوحدة kWh، والمعرّف (البطاقة)، والسائق ورقم لوحة المركبة إن توفّرا.
• المحطات والموصلات: المعرّفات، والموقع، وإصدار OCPP، والحالة الحالية.
• السائقون والبطاقات: أي بطاقة تخص أي سائق، وهل هي نشطة أم محظورة.
• المركبات: أرقام اللوحات والسائقون المرتبطون بها.
• ملخصات الطاقة: الإجماليات لكل محطة أو سائق أو مركبة أو فترة زمنية.

تختلف الموارد وأسماء الحقول وعوامل التصفية بدقة من منصة إلى أخرى، لذا اعتمد دائمًا على وثائق API الرسمية.

أمان webhooks: التوقيعات، وتساوي الأثر، وإعادة المحاولة

نقطة نهاية webhook هي عنوان URL عام، ويمكن لأي شخص يعرفه أن يرسل إليه طلبات. وهناك ثلاث ممارسات تجعل معالجة webhooks آمنة وموثوقة.

1. تحقق من توقيع HMAC

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

• احسب HMAC على جسم الطلب الخام تمامًا كما وصل. فتحليل JSON ثم إعادة تسلسله قد يغيّر المسافات أو ترتيب المفاتيح ويُفسد التوقيع.
• قارن التوقيعات باستخدام دالة ثابتة الزمن لتجنب هجمات التوقيت.
• احفظ السر كما تحفظ كلمة المرور: في مدير أسرار أو متغير بيئة، وليس في الشيفرة المصدرية أبدًا.
• إذا كانت المنصة تُدرج طابعًا زمنيًا ضمن البيانات الموقّعة، فارفض عمليات التسليم القديمة للحد من هجمات إعادة الإرسال.

2. اجعل المعالجات متساوية الأثر

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

3. استجب بسرعة وتعامل مع إعادة المحاولة

أعِد حالة نجاح (رمز 2xx) بسرعة، ونفّذ العمل الثقيل في مهمة خلفية. فالمعالجات البطيئة قد تتجاوز المهلة وتتسبب في إعادة التسليم. راجع وثائق المنصة لمعرفة سلوك إعادة المحاولة لديها، واستخدم استدعاءات REST المجدولة لمطابقة أي بيانات فائتة.

مثال على التدفق بشيفرة زائفة

يوضح المثال التالي معالج webhook عامًا يتحقق من التوقيع، ويزيل التكرارات، ويضع حدث "انتهاء الجلسة" في قائمة الانتظار للمعالجة. واسم الترويسة وأسماء الأحداث وحقول الحمولة مجرد عناصر نائبة؛ استخدم القيم الواردة في وثائق API الخاصة بمنصتك.

function handle_webhook(request):    raw_body  = request.raw_body            # بايتات، قبل أي تحليل لـ JSON    received  = request.header(SIGNATURE_HEADER)   # راجع وثائق API    secret    = env("WEBHOOK_SECRET")    expected  = hex(hmac_sha256(key = secret, message = raw_body))    if not constant_time_equals(expected, received):        return response(status = 401)    event = json_parse(raw_body)    event_key = event.id or (event.session_id + ":" + event.type)    if processed_events.contains(event_key):        return response(status = 200)       # مكرر، تمت معالجته بالفعل    processed_events.add(event_key)    queue.push(event)                       # العمل الثقيل يُنفَّذ لاحقًا    return response(status = 200)function worker(event):    if is_session_stopped(event):        cost_center = lookup_cost_center(event.driver, event.vehicle)        erp.post_energy(cost_center, event.energy_kwh, event.ended_at)function nightly_reconciliation():    sessions = api.get_sessions(date = yesterday)   # REST API، مفتاح API    for session in sessions:        if not erp.has_session(session.id):            erp.post_energy(...)

توفّر معظم لغات البرمجة دالة HMAC-SHA256 ودالة مقارنة ثابتة الزمن في مكتبتها القياسية أو في حزمة تشفير معروفة. استخدمها بدلًا من كتابة دوالك الخاصة.

التكامل مع Üreticy

توفّر Üreticy واجهة REST API بمفاتيح API تُنشئها وتديرها من لوحة التحكم، وwebhooks موقّعة بـ HMAC لأحداث مثل بدء الجلسة وانتهاء الجلسة. وتصف وثائق API العامة الموارد وأنواع الأحداث والحمولات وترويسة التوقيع المستخدمة للتحقق.

ولأن Üreticy تدير شواحن OCPP 1.6J و2.0.1 و2.1 في لوحة تحكم واحدة، يمكن لتكامل واحد أن يغطي مجموعة شواحن متنوعة. تعرّف على المزيد في صفحة واجهة API للشحن وwebhooks.

نصائح للتنفيذ

1. ابدأ بحالة استخدام واحدة. مثل تسجيل الطاقة الشهرية لكل مركز تكلفة في نظام ERP.
2. استخدم مفاتيح API منفصلة لكل تكامل. يتيح لك ذلك إلغاء تكامل واحد دون التأثير في غيره.
3. امنح الحد الأدنى من الصلاحيات اللازمة. فتكامل التقارير لا ينبغي أن يكون قادرًا على تغيير الإعدادات.
4. اختبر بجلسات حقيقية. قارن نتائج API مع لوحة التحكم والتقارير المُصدَّرة قبل التشغيل الفعلي.
5. سجّل كل عملية تسليم webhook. دوّن الوقت ونوع الحدث ونتيجة التحقق من التوقيع لتسهيل استكشاف الأعطال.
6. خطّط لتدوير المفاتيح. اعرف كيف تستبدل مفاتيح API وأسرار webhooks دون توقف الخدمة.
7. راقب التكامل. فعّل تنبيهًا عندما لا تصل أي webhooks لفترة غير معتادة، أو عندما تكشف التسوية عن فجوات.

عند مقارنة منصات الشحن، تستحق جودة API وwebhooks مكانًا في قائمة التقييم. راجع كيف تختار برنامج OCPP للاطلاع على قائمة تقييم كاملة.

الأسئلة الشائعة

اربط جلسات الشحن بأنظمة ERP أو الأساطيل أو أدوات ذكاء الأعمال عبر REST API وwebhooks موقّعة بـ HMAC. اكتشف واجهة API للشحن من Üreticy أو اقرأ وثائق API.