معايير DCSA لواجهات برمجة التطبيقات للوصول إلى بيانات الشحن العالمية

معايير DCSA API: جعل البيانات متاحة في صناعة الشحن العالمية

تطبيق واجهات برمجة تطبيقات DCSA الآن: إعطاء الأولوية لنقاط نهاية الحجز والأحداث والتتبع واعتماد حمولات موحدة في غضون 12 أسبوعًا لتقليل اللمسات اليدوية بحوالي 40٪ وتقديم تحديثات شبه فورية لكل مستخدم.

ابدأ بثلاث خطوات عملية: قم بتعيين الواجهات الحالية، واكشف عن طبقة واجهة برمجة تطبيقات رفيعة للأنظمة القديمة التي لا تزال تستخدم EDI، وقم بتجربة موجزات المواقع المستندة إلى الأقمار الصناعية لإثراء سجلات الأحداث. يحافظ هذا النهج على العمليات الحالية مع إنشاء مسار سلس للإشعارات الآلية وتصحيحات وقت الوصول المقدر.

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

اتبع خططًا واضحة: قم بتشغيل تجربة من ثلاثة أجزاء مع ناقل واحد، وشاحنين اثنين، ومحطة؛ وانشر اتفاقيات مستوى الخدمة (SLA) وقواعد الإصدار؛ وقدم حزم تطوير البرامج (SDKs) وعينات الحمولات؛ وجدول نقاط تفتيش التكامل الأسبوعية. تنتج هذه الخطوات الملموسة نتائج قابلة للتكرار اليوم وتجعل البيانات الموحدة متاحة للأنظمة النهائية والتحليلات وتكاملات الشركاء.

معايير DCSA API: جعل البيانات متاحة في الشحن العالمي - مواءمة وصول سفن الحاويات ونشر المنصة للرقمنة

قم بتطبيق معايير DCSA API في غضون 12 شهرًا لمزامنة نشر وقت الوصول المقدر للسفن، وتخصيص الرصيف، ونشر المنصة، وتقليل عمليات التسليم اليدوية وفتح التحديثات التشغيلية التلقائية.

تتطلب واجهات برمجة التطبيقات نشر وقت الوصول المقدر وتحديثات الحالة على فترات زمنية مدتها 15 دقيقة ودعم خطافات الويب المستندة إلى الأحداث للاتصال الفوري بين الناقلين والمحطات والوكلاء. قم بدمج موجزات AIS والأقمار الصناعية بحيث يتم التقاط الموقع والسرعة على طول المسار ونقلها إلى أنظمة الموانئ؛ وقم بتوحيد الحمولات باستخدام طوابع زمنية ISO 8601 و UN/LOCODEs لتجنب أخطاء التعيين أثناء النقل. خطط لثلاثة إصدارات رئيسية سنويًا مع إصدار دلالي ونوافذ نشر واضحة للتوافق مع الإصدارات السابقة لمنح المستخدمين دورات ترقية يمكن التنبؤ بها.

قم بتحسين نوافذ الرصيف من خلال الجمع بين الموجزات التشغيلية من أنظمة تشغيل المحطات وأنظمة تخطيط الناقلين؛ تُظهر التجارب مع Maersk وشركاء المحطات انخفاضًا يصل إلى 20٪ في وقت انتظار الرصيف ومعدل استخدام رصيف أعلى من الجدولة اليدوية. استخدم قواعد إعادة تخصيص الرصيف التلقائية واتصالات الإشعارات لتقليل دقائق خمول الرصيف بين حركات السفن، مما يحسن الإنتاجية أكثر مما يمكن أن تحققه الرسائل المخصصة.

قم بتضمين المقاييس البيئية في كل حمولة واجهة برمجة تطبيقات: استهلاك الوقود، وساعات المحرك المساعدة، وتقديرات الانبعاثات المستمدة من الأقمار الصناعية. قم بتغذية هذه المقاييس الملتقطة في لوحات معلومات إدارة الموانئ والناقلين لقياس كمية ثاني أكسيد الكربون لكل حاوية مكافئة (TEU) وتعيين أهداف قابلة للقياس للتنمية المستدامة. تسمح للمشغلين بمقارنة خيارات التوجيه والرسو من حيث الانبعاثات وتكلفة التشغيل، مما يتيح خيارات استراتيجية تحقق نتائج استدامة أفضل.

قم بإنشاء حوكمة تربط مطابقة المعايير باتفاقيات مستوى الخدمة التعاقدية، وتوضح بروتوكولات الاتصال، وتعين المسؤولية لجودة البيانات. قم بالترويج لمجموعات أدوات المطورين وبيئات العمل الرملية والتوثيق المفتوح لتسريع التطوير وإلحاق المستخدمين الجدد. قم بمراقبة مؤشرات الأداء الرئيسية (KPIs) - دقة وقت الوصول، ومعدل نجاح النقل التلقائي، وانخفاض التدخلات اليدوية - وانشر تقارير ربع سنوية حتى يتمكن أصحاب المصلحة من قياس التقدم وتخطيط المزيد من التكامل.

مخطط تشغيلي: تطبيق واجهات برمجة تطبيقات DCSA لمواءمة بيانات وصول السفن

قم بتطبيق عملية موحدة لمصالحة حالة الوصول باستخدام واجهات برمجة تطبيقات DCSA Event و Voyage و Port Call مع اتفاقية مستوى خدمة مدتها 24 ساعة لمواءمة وصول السفن بين الناقلين والموانئ والمحطات.

التقط بيانات الوصول من ثلاثة مصادر رئيسية: قوائم الشحن للناقلين عبر DCSA Voyage API، وأنظمة المحطات عبر Port Call API، وموجزات AIS. استخدم خطافات الويب لواجهة برمجة تطبيقات الأحداث للحصول على تحديثات سريعة وتراجع إلى الاستقصاء الدوري على فترات 5 دقائق عندما تفشل خطافات الويب. قم بوضع علامة على كل سجل باستخدام حقل SOURCE (مصدر) و capture_timestamp للحفاظ على الأصالة ودعم مسارات التدقيق.

قم بتطبيع الحمولات الواردة إلى نموذج تشغيلي واحد باستخدام هذه الحقول الأساسية المحددة: vessel_imo، voyage_id، eta_utc، ata_utc، berth، status_code، bunker_onboard_mt، estimated_fuel_burn_mt، customs_status، و event_origin. قم بتحويل جميع الأوقات إلى التوقيت العالمي المنسق (UTC)، وتقريبها إلى أقرب دقيقة، وقم بتعيين رموز الحالة المتباينة إلى تصنيف وصول ذي 7 حالات (مخطط له، تم تحديث وقت الوصول المقدر، قيد التشغيل، وصل، بجانب، رصيف، غادر).

استخدم قواعد مطابقة حتمية: مطابقة تامة لـ vessel_imo + voyage_id إذا كانت متاحة؛ وإلا، قم بالمطابقة بناءً على vessel_imo + نافذة وقت الوصول المقدر ±72 ساعة باستخدام دالة تسجيل ترجح Event API = 0.5، AIS = 0.3، رسائل المحطة = 0.2. قم بتمييز عدم التطابق بنتيجة <0.6 على أنها اختلافات للمراجعة البشرية. حدد حدًا للاختلاف قدره 60 دقيقة لوقت الوصول المقدر مقابل وقت الوصول الفعلي؛ وعامل الأوقات الأكبر على أنها استثناءات تشغيلية قد تزيد من استهلاك الوقود ووقت احتجاز الجمارك.

قم بدمج معالجة الاستثناءات في واجهات المستخدم وواجهات الآلة في وقت واحد. قم بدفع الاستثناءات عالية الخطورة إلى فرق عمليات الناقلين عبر إشعارات واجهة برمجة التطبيقات وإلى مخططي المحطات عبر لوحات معلومات واجهة المستخدم. قدم للمستخدمين إجراءات تصحيحية مقترحة: إعادة التوجيه إلى رصيف بديل، وطلب تعديل فوري لوقود السفينة، أو تخليص وثائق الجمارك المسبق. سجل قرارات المشغل ووقت الحل للتحليل اللاحق.

قم بقياس الأداء باستخدام مؤشرات الأداء الرئيسية المستهدفة التالية: discrepancy_rate (معدل الاختلاف) (<5٪ في غضون 6 أشهر)، mean_time_to_align (متوسط وقت المواءمة) (<4 ساعات)، SLA_adherence (الالتزام باتفاقية مستوى الخدمة) (≥98٪)، bunker_variance (تباين وقود السفينة) (±3٪ من المبلغ المبلغ عنه على متن السفينة)، و economic_impact_estimate (تقدير التأثير الاقتصادي) لكل وصول. استخدم الأشهر الثلاثة الماضية كخط أساس وقم بتشغيل تجربة في أكتوبر على مسار رئيسي بين آسيا وأوروبا مع 500 وصول تم التقاطها للتحقق من المدخرات ودقة النموذج.

قم بتطبيق قواعد التحويل التي تقلل من الأحداث المكررة وتحسن استخدام واجهات النظام: تجاهل التكرارات في غضون دقيقتين من نفس المصدر، ودمج الأحداث التي تشترك في نفس vessel_imo+event_origin+timestamp، وتخزين الحمولات الخام لضمان النسب. قم بتسمية السجلات بمصفوفة events_history حتى يتمكن المحللون من فهم أنماط التوقيت التي أدت إلى اختلافات على طول الرحلة.

قم بحوكمة تدفقات البيانات باستخدام عقود واجهة برمجة التطبيقات المصدرة، ورموز OAuth2 لكل شريك، وحدود المعدل المعدلة لتناسب ذروة العمليات (يوصى بها 1200 استدعاء/دقيقة لاشتراكات الأحداث)، وسياسات الاحتفاظ (خام لمدة 12 شهرًا، مجمعة لمدة 36 شهرًا). احتفظ بسجل مخطط الصناعة الذي يمكن للشركاء من خلاله الاتفاق على معاني الحقول وتقليل جهود التعيين إلى ما بعد التكامل الأولي.

DCSA API	الحقول الرئيسية الملتقطة	الإجراء	اتفاقية مستوى الخدمة / الهدف
Event API	event_type, timestamp, location, vessel_imo, voyage_id	التقاط في الوقت الفعلي، خطاف ويب أولاً، إلغاء الازدواج لمدة دقيقتين	تسليم خطاف الويب <30 ثانية؛ جرب مرتين
Voyage API	voyage_id, eta_utc, planned_port_calls, cargo_manifest	تعبئة سجل الرحلة الأساسي، تمييز عدم تطابق قوائم الشحن	مزامنة كل 4 ساعات؛ تحديثات في غضون ساعة
Port Call API	port_call_id, berth, alongside_time, berthed_time, customs_status	مواءمة حالة جانب الميناء، عرض احتجازات الجمارك	تحديث <15 دقيقة بعد الحدث المحلي
Reference Data API	locations, terminals, carrier_codes	حل الأسماء/المعرفات، تقليل أخطاء التعيين	تحديث أسبوعي؛ إصلاحات عاجلة في غضون 24 ساعة
Location / AIS	lat, lon, sog, cog, timestamp	تكملة وقت الوصول المقدر/الفعلي، تقدير استهلاك الوقود	تأخير البث <60 ثانية

قم بتشغيل تجربة لمدة ثلاثة أشهر بهذه الخطوات: نشر التكاملات على مسار رئيسي في أكتوبر، واستيعاب 500 وصول سابق وحالي لتدريب نموذج المصالحة، وتكرار القواعد لتقليل النتائج الإيجابية الخاطئة إلى أقل من 8٪، وقياس التأثير الاقتصادي شهريًا. قم بإبلاغ النتائج لشركاء الجمارك لتقصير نوافذ التخليص ولفرق العمليات لتقليل وقت الانتظار الذي يؤدي إلى استهلاك وقود السفن. استخدم الدروس المستفادة من التجربة للتوسع على مستوى الصناعة وتوسيع نطاق الواجهات حتى يرى المستخدمون بيانات وصول متوافقة تتجاوز العزلة المحلية.

تحديد مجموعة نقاط النهاية الحرجة لمواءمة وصول السفن: واجهات برمجة تطبيقات DCSA والحمولات المطلوبة

قم بتطبيق مجموعة نقاط النهاية الدنيا هذه لمواءمة وصول السفن: Port Call (voyage/eta)، Event Notifications (webhook)، Transport/Movement، Booking، Equipment/Container، Terminal Interface، Reference/Location، و Party APIs.

حساب Port Call: قم بتضمين voyageId، vesselIMO، vesselName، voyageNumber، portCode (UN/LOCODE)، scheduledArrival (ISO‑8601)، estimatedArrival (وقت الوصول المقدر)، scheduledDeparture (وقت المغادرة المجدول)، berthingWindowStart (بداية نافذة الرسو)، berthingWindowEnd (نهاية نافذة الرسو)، berthCode (رمز الرصيف)، draftMeters (أمتار الغاطس)، nextPortCode (رمز الميناء التالي)، و sequenceVersion (إصدار التسلسل). استخدم حقولًا رقمية لـ TEU والغاطس، وقم بتوفير sourceSystem (نظام المصدر) و lastUpdatedBy (آخر من قام بالتحديث). على سبيل المثال: scheduledArrival: "2026-03-10T14:00:00Z". أرسل لقطة رحلة كاملة عند المزامنة الأولى وتغييرات لاحقة.

حساب Event Notifications: eventType (نوع الحدث)، eventTimestamp (الطابع الزمني للحدث)، relatedId (معرف الرحلة، رقم الحاوية، مرجع الحجز)، locationCode (رمز الموقع)، statusCode (رمز الحالة)، details (التفاصيل)، sequenceNumber (رقم التسلسل)، و idempotencyKey (مفتاح عدم التكرار). أرسل طلبات POST بتنسيق application/vnd.api+json JSON:API إلى نقاط نهاية المشتركين مع إعادة المحاولة/التراجع ونوافذ أسية. قم بتمييز الأحداث على أنها تلقائية أو يدوية وتضمين eventProvenance (أصل الحدث) لتحديد النظام الذي أنشأ الحدث.

حساب Transport/Movement: transportId (GUID)، shipmentId (معرف الشحنة)، bookingReference (مرجع الحجز)، carrierBookingReference (مرجع حجز الناقل)، billOfLadingNumber (رقم بوليصة الشحن)، originUNLOC (UNLOC المصدر)، destinationUNLOC (UNLOC الوجهة)، mode (الوضع)، containers:[{containerNumber (رقم الحاوية)،sizeType (نوع وبيانات الحاوية)،status (الحالة)}], cargoType (نوع الحمولة)، weightKg (الوزن بالكيلوجرام)، loadedOnVoyageId (تم التحميل على معرف الرحلة)، و currentStatusTimestamp (الطابع الزمني للحالة الحالية). قم بتوفير manifestReference (مرجع قائمة الشحن) و estimatedOnboardTime (الوقت المقدر على متن السفينة) عند توفرها للمساعدة في تخطيط المحطات.

حساب Booking: bookingReference (مرجع الحجز)، shipperPartyId (معرف طرف الشاحن)، consigneePartyId (معرف طرف المرسل إليه)، commodities (السلع)، totalTEU (إجمالي TEU)، containerRequirements (متطلبات الحاوية)، portCutoffTimes:{terminalCutoff (موعد أقصى للمحطة)،gateCutoff (موعد أقصى للبوابة)،docsCutoff (موعد أقصى للمستندات)} مع المنطقة الزمنية، requestedPickupDate (تاريخ الاستلام المطلوب)، و confirmedStatus (الحالة المؤكدة). استخدم هذه القيم لتوجيه أنظمة تحديد المواعيد والمحطات؛ قم بتخزين bookingVersion (إصدار الحجز) للمصالحة.

حساب Equipment/Container: containerNumber (رقم الحاوية)، isoSizeType (نوع وحجم ISO)، tareKg (وزن الحاوية فارغة بالكيلوجرام)، grossKg (الوزن الإجمالي بالكيلوجرام)، currentLocationCode (رمز الموقع الحالي)، lastFreeTime (آخر وقت مجاني)، containerStatus (حالة الحاوية)، و sealInfo (معلومات الختم). اربط هذه السجلات بـ transportId و voyageId حتى ترى أنظمة المحطات والعملاء مصدرًا واحدًا للحقيقة.

حساب Terminal Interface: terminalCode (رمز المحطة)، berthCode (رمز الرصيف)، availableCraneCount (عدد الرافعات المتاحة)، plannedBerthStart (بداية الرصيف المخطط لها)، plannedBerthEnd (نهاية الرصيف المخطط لها)، gateSlots (نوافذ زمنية للبوابة)، yardOccupancyPercent (نسبة إشغال الساحة)، و serviceLevels (مستويات الخدمة). صمم النموذج بحيث يمكن للمحطات نقل تأكيدات الرصيف وتعيينات الفتحات مرة أخرى إلى مجالي Port Call و Booking.

حساب Reference و Party: partyId (الناقل، المحطة، الشاحن، المرسل إليه)، names (الأسماء)، roles (الأدوار)، contactMethods (طرق الاتصال)، و locationList (قائمة المواقع). قم بتوفير UN/LOCODE وشروط دور موحدة لتعزيز المطابقة المتسقة عبر مجموعة الأنظمة المشاركة في الشحن.

قواعد البروتوكول والتنفيذ: اعتماد نوع محتوى JSON:API، وتطلب طوابع زمنية RFC3339، وفرض مفاتيح إلزامية مدرجة أعلاه، ودعم PATCH للتغييرات الجزئية، وإصدار نقاط النهاية. استخدم خطافات الويب لتسليم الأحداث تلقائيًا وقدم واجهة برمجة تطبيقات لسحب للمزامنة الكاملة. إرشادات حدود المعدل: السماح بـ 5 استدعاءات/ثانية لكل عميل لنقاط نهاية المزامنة و 1000 حدث خطاف ويب/دقيقة مع التراجع عند الاستجابات 429.

توصيات تشغيلية: قم بإرسال تحديثات وقت الوصول المقدر بشكل متكرر كلما اقتربت السفينة - على سبيل المثال، كل 15 دقيقة عندما تكون على بعد أكثر من 48 ساعة، وكل 5 دقائق في غضون 6 ساعات، وفورًا عند الوصول الفعلي/الرصيف. قم بتضمين sequenceNumber (رقم التسلسل) و lastProcessedEvent (آخر حدث تم معالجته) في الاستجابات حتى تتمكن الأنظمة المستهلكة من الاستئناف دون تكرارات والحفاظ على عدم التكرار.

المراقبة والتشغيل: اكشف عن مقاييس لـ deliverySuccessRate (معدل نجاح التسليم)، averageLatencyMs (متوسط زمن الاستجابة بالمللي ثانية)، و processingErrors (أخطاء المعالجة) لكل نقطة نهاية. قم بتشغيل قائمة تدقيق التشغيل التي تتضمن التحقق من صحة المخطط، وإعادة محاولة خطاف الويب، والمصادقة (mTLS أو OAuth2)، والاختبارات الشاملة بين أنظمة الناقلين والمحطات والعملاء. قم بتعيين فريق متعدد الوظائف لتطوير ومراقبة هذه العناصر أثناء أول سباق.

إرشادات التعيين ونموذج البيانات: قم بتعيين الحقول المحلية إلى أسماء أساسية (voyageId، portCode، scheduledArrival) في طبقة تكامل؛ احتفظ بمعرفات المصدر الأصلية في مصفوفة sourceRef. استخدم نموذج changeLog يسجل من قام بتغيير ماذا ومتى لتوجيه المصالحة النهائية والإشعارات للعملاء.

الأمان والحوكمة: تطلب نطاقات الرمز المميز لكل نقطة نهاية وتقييد البيانات التي يتم إرجاعها حسب الدور. سجل موافقات وشروطًا تعاقدية لمشاركة البيانات وتضمين إدخالات auditTrail للأحداث المرسلة حتى يتمكن العملاء والمحطات من التحقق من الأصول.

ابدأ التنفيذ من قائمة تحقق ذات أولوية: 1) Port Call و Event webhooks، 2) Transport و Booking sync، 3) Terminal interface و Equipment، 4) Reference و Party consolidation، 5) اختبارات المراقبة والتشغيل. هذا الترتيب يقلل من عمل التكامل مقارنة بالنهج المخصص ويتيح للفريق تحقيق محاذاة وصول مرئية للشحنات في غضون أسابيع.

مواءمة أحداث مكالمة الميناء في جدول زمني وصول أساسي: قواعد التعيين وأسبقية الطابع الزمني

قم بتطبيق مجموعة من خمس خطوات للتعيين وأسبقية الطابع الزمني لإنشاء جدول زمني وصول أساسي واحد لكل سفينة وشحنة: قم بتعيين الأحداث الأولية إلى مراحل أساسية، واختر الطابع الزمني ذي الأولوية الأعلى لكل مرحلة، وأرفق ثقة المصدر، وقم بتمييز التعارضات للمراجعة البشرية.

قم بتعريف المراحل الأساسية على أنها: الاقتراب (السفينة على بعد 24 ميلًا بحريًا من الميناء)، pilotOnBoard (طيار على متن السفينة)، alongside/berth (بجانب/رصيف)، startCargoOps (بدء عمليات الشحن - استلام أول حركة حاوية)، completeCargoOps (استكمال عمليات الشحن)، و departed (مغادر). قم بتعيين أحداث المصدر في هذه المراحل: تقارير موقع AIS، قوائم الركاب من سلطة الطيار/الميناء، أحداث رسو نظام تشغيل المحطة (TOS)، رسائل عمليات الناقل (SOC/COC)، عمليات مسح الحاويات عند بوابة الدخول/الخروج، وإدخالات سجل السفينة. قم بتخزين طابع زمني أساسي واحد لكل مرحلة واحتفظ بقوائم الأحداث الأصلية للتدقيق والمصالحة.

أسبقية الطابع الزمني (من الأعلى إلى الأقل): 1 - سلطة الميناء / طوابع زمنية للطيار لـ pilotOnBoard وتفويضات الرصيف (سلطوية). 2 - طوابع زمنية لنظام تشغيل المحطة لـ alongside/berth و startCargoOps. 3 - مسح بوابات المحطة/الحاويات لاستلام وحركات الحاويات. 4 - رسائل عمليات الناقل (ETA/ATA، SOC/COC) للمعالم المخطط لها والتي أكدها المشغل. 5 - الطوابع الزمنية المشتقة من AIS (عبور الموقف X- ميل بحري، توقف عند الرصيف) للكشف التلقائي. قم دائمًا بالتطبيع إلى UTC ISO 8601 وأرفق معرف المصدر ودرجة الثقة.

حل التعارضات بقواعد حتمية: إذا كان هناك طابع زمني ذو أولوية أعلى، فاستخدمه للمرحلة الأساسية. إذا سبقت البيانات ذات الأولوية الأقل طابعًا زمنيًا ذا أولوية أعلى بأكثر من العتبة T1 = 30 دقيقة للرسو/بجانب الرصيف أو T2 = 120 دقيقة للاقتراب/وقت الوصول المقدر، احتفظ بكلا الطابعين الزمنيين، وقم بتمييز المرحلة الأساسية على أنها "مشبوهة"، وقم بتعيين sourceConfidence (ثقة المصدر) = منخفض. إذا أشار AIS إلى جانب الرصيف قبل TOS بأقل من 30 دقيقة، ففضل TOS ولكن سجل AIS كدليل داعم. في حالة البيانات المفقودة ذات الأولوية الأعلى، قم بترقية المصدر التالي المتاح ولكن سجل سبب الترقية والدقة المتوقعة (%) بناءً على نوع المصدر.

تنفيذ ضوابط الساعة والمنطقة الزمنية: تطلب من جميع المصادر تقديم طوابع زمنية بتنسيق UTC. في حالة وجود انحراف زمني معروف، قم بتطبيق إزاحات خاصة بالمصدر محسوبة من مقارنات تاريخية (قم بتخزين last-offset و stdev). رفض الطوابع الزمنية الأقدم من 7 أيام لمراحل الوصول ما لم تكن مصحوبة بسجل موقع موقع موقع موقع موقع موقع موقع موقع موقّع. طبق تصحيحًا أقصى قدره 60 دقيقة تلقائيًا؛ تتطلب التصحيحات الأكبر مراجعة يدوية.

مخطط الأحداث الأساسية الموصى به (حقول مثال): eventType (نوع الحدث)، canonicalTimestampUTC (الطابع الزمني الأساسي UTC)، sourceType (نوع المصدر)، sourceId (معرف المصدر)، sourceConfidence (ثقة المصدر (0-1))، rawTimestamps (طوابع زمنية خام [قوائم])، berthId (معرف الرصيف)، portUNLocode (رمز UN/LOCODE للميناء)، vesselIMO (IMO للسفينة)، containerCount (عدد الحاويات)، affectedContainers[] (الحاويات المتأثرة)، phaseDurationMinutes (مدة المرحلة بالدقائق). استخدم هذه الحقول لإنتاج نتائج مؤشرات الأداء الرئيسية مثل تقليل تباين وقت الوصول المقدر، وإشعارات مبكرة للعملاء، وتقليل قابل للقياس لوقت الحركة لكل حاوية.

إرشادات تشغيلية للمتبنين والتحالفات: قم بدمج هذه القواعد في واجهات برمجة تطبيقات الناقلين والمحطات لتمكين الرسائل المتسقة من خلال نقاط النهاية المتوافقة مع DCSA. شارك القواعد المروجة مع الشاحنين والعملاء حتى تتمكن الأنظمة من توسيع سير العمل الآلي وتحسين تخطيط الرصيف. تتبع خمسة مقاييس تبني: نسبة المراحل ذات المصدر الموثوق، متوسط تكرار الترقية، نسبة الأعلام المشبوهة التي تم حلها في غضون 24 ساعة، متوسط الانحراف بين وقت الوصول الأساسي ووقت الوصول المقدر للناقل، وتقليل الإشعارات المبكرة/المتأخرة. رقمنة هذه التعيينات ستزيد من الرؤية عبر الصناعات، وتساعد على تحسين حركات الحاويات، وتجاوز الطوابع الزمنية المجزأة بحيث يتلقى الناقلون والمحطات والشاحنون معلومات شحن مبكرة وموثوقة جنبًا إلى جنب مع إيصالات الحاويات الفردية والنتائج.

التحقق من معرفات الناقلين والحاويات قبل الاستيعاب: أرقام التحقق، وقوائم الرموز، ومعالجة الرفض

قم بالتحقق من أرقام الحاويات ورموز الناقلين عند بوابة واجهة برمجة التطبيقات باستخدام منطق رقم التحقق ISO 6346 وقوائم الرموز الموثوقة قبل أي استيعاب لاحق.

تنسيق الحاوية الدقيق والتحقق من رقم التحقق
- اقبل فقط إدخالات ISO 6346 المكونة من 11 حرفًا: رمز المالك (3 أحرف) + فئة المعدات (حرف واحد، عادة U/J/Z) + الرقم التسلسلي (6 أرقام) + رقم التحقق (رقم واحد).
- قم بحساب رقم التحقق: قم بتعيين قيم الأحرف إلى قيم رقمية (A=10، B=12، C=13 ... Z=38 مع فجوات عند 11، 22، 33)، واضرب قيمة كل حرف في 2^الموضع (الموضع 0 للحرف الأول)، اجمع، خذ المجموع مود 11؛ إذا كان الباقي = 10، فاجعل رقم التحقق = 0. ارفض فورًا عند عدم التطابق.
- ارفض الإدخالات ذات الطول غير الصحيح، أو الأحرف غير ASCII، أو الأصفار البادئة في رمز المالك، أو الأرقام التسلسلية خارج النطاق 000001–999999؛ سجل سبب الفشل الدقيق والمصدر (معرف استدعاء واجهة برمجة التطبيقات أو صف جدول بيانات).
التحقق من رمز الناقل وإدارة قوائم الرموز
- قم بمطابقة معرفات الناقلين مقابل سجل موثوق (BIC للمالكين، SCAC لعمليات الولايات المتحدة أو قائمة الناقلين المتفق عليها). تعامل مع الرموز غير المعروفة على أنها محجوزة حتى يتم حلها.
- قم بتنفيذ عمليات بحث في الوقت الفعلي عند توفر الوصول إلى الإنترنت؛ تراجع إلى لقطة مخبأة موقعة ومختومة زمنيًا إذا كنت غير متصل. اسمح بصلاحية مخبأة لنافذة قابلة للتكوين (افتراضي 24-72 ساعة) وسجل إصدار اللقطة في كل حدث.
- قم بتطبيق التعيين للتحالفات وشركاء تشغيل السفن: احتفظ بجدول أساسي للناقل إلى الناقل التشغيلي يستخدمه APMS والأنظمة النهائية؛ قم بتحديث التعيين عند كل تغيير في التحالف وسجل من قام بتطبيق التجاوز.
شيكات ما قبل الاستيعاب لجداول البيانات والأحمال المجمعة
- قم بتوفير مدقق من جانب العميل (ماكرو Excel أو JS خفيف الوزن) يقوم بتمييز الصفوف قبل التحميل ويعيد ملف CSV للصفوف المرفوضة مع رموز الأخطاء؛ هذا يقلل من التصحيحات اليدوية ويسرع رقمنة جداول البيانات القديمة.
- للاستيعاب المجمع، قم بإجراء فحص سريع مسبق يفصل الصفوف الصالحة، والصفحات اللينة (ناقل غير معروف)، والصفحات الصعبة (عدم تطابق رقم التحقق). استوعب فقط الصفوف الصالحة؛ أعد ملف رفض منظم يمكن لمقدمه إعادة تحميله بعد الإصلاحات.
سياسة معالجة الرفض وتصنيف الأخطاء
1. استخدم رموز أخطاء موحدة حتى تتمكن التكاملات من التصرف تلقائيًا:
  - ERR01 - FORMAT_INVALID (الطول/مجموعة الأحرف)
  - ERR02 - CHECKDIGIT_MISMATCH (عدم تطابق رقم التحقق)
  - ERR03 - CARRIER_UNKNOWN (ناقل غير معروف)
  - ERR04 - MAPPING_OVERRIDE_REQUIRED (تجاوز التعيين مطلوب)
2. قم بتعريف إجراءات تلقائية لكل رمز:
  - ERR02: رفض صارم، إخطار المرسل، حظر حتى يتم التصحيح.
  - ERR03: حجر صحي ناعم، محاولة البحث من خدمات بديلة لمدة تصل إلى 24 ساعة، ثم التصعيد إلى عمليات الناقل إذا لم يتم حلها بعد.
  - ERR04: قبول فقط مع تجاوز موقع من مستخدم مصرح له؛ سجل مسار التدقيق.
المراقبة ومؤشرات الأداء الرئيسية واتفاقيات مستوى الخدمة
- تتبع معدل الرفض، ومتوسط وقت الإصلاح (MTTR)، ونسبة السجلات المحجوزة التي تم حلها ضمن اتفاقية مستوى الخدمة. الأهداف المستهدفة: معدل الرفض <0.1٪ من حجم الاستيعاب و MTTR <4 ساعات للموانئ/الوصول التشغيلية.
- قم بتجهيز لوحات معلومات تعرض الاتجاهات واكتشاف الارتفاعات بحيث تستطيع العمليات اكتشاف التغييرات في قوائم الناقلين أو أخطاء جداول البيانات الشاملة بشكل أسرع مما يمكن للمراجعة اليدوية.
نقاط التكامل والضمانات التشغيلية
- قم بالتحقق قبل إرسال البيانات إلى أنظمة الجمارك، و APMS، والوقود، والتزويد بالوقود. تتسبب المعرفات غير الصحيحة في عدم تطابق الفواتير (الوقود)، وتأخيرات الجمارك، وسوء توجيه الوصول.
- عندما يرسل نظام خارجي (APMS، نظام المحطة) تحديثات، قم بإرفاق إصدار لقطة التحقق حتى يعرف المستلمون أي قائمة رموز تم استخدامها لاتخاذ القرار.
- استخدم روابط إنترنت آمنة أو أقمار صناعية L-band حيث تكون الاتصال البري غير موثوق به؛ يجب أن يسجل التحقق دون اتصال معرف القائمة المخزنة مؤقتًا حتى يكتمل مزامنة الإنترنت.
الحوكمة والتحديثات وممارسات التطوير
- قم بأتمتة سحب قوائم الرموز الليلية والسماح بالفرض اليدوي للتغييرات الفورية؛ سجل من قام بالتحديثات اليدوية ولماذا. قم بإخطار الفرق النهائية بأي تغيير يؤثر على تعيينات الناقلين أو المواصفات.
- قم بتضمين اختبارات الوحدة لمنطق رقم التحقق في CI/CD ومستودع من نواقل الاختبار الواقعية (أرقام صالحة وغير صالحة) المستخدمة أثناء التطوير وضمان الجودة.
- احتفظ بسجل تغييرات عام حتى يعرف الشركاء متى تغيرت قواعد التحقق أو القوائم الخاصة بك؛ اربط معرف سجل التغييرات في بيانات التعريف للحدث لضمان التتبع (انظر التعيين هنا لآخر 30 تحديثًا).
أمثلة تشغيلية
- سيناريو: جدول بيانات تم تحميله من وكيل يرسل حاليًا 5000 صف. قم بتشغيل فحص مسبق: 4990 صالح، 8 ERR02، 2 ERR03. أعد ملف CSV رفض مع معرفات الصفوف، ورموز الأخطاء، والإصلاحات المقترحة؛ استوعب 4990 فورًا لتلبية مواعيد وصول الوصول.
- سيناريو: يتحالف ناقل يتغير البوادئ بين عشية وضحاها. قم بتطبيق تجاوز التعيين، وقم بتشغيل المصالحة مقابل الوصول الملتقط لآخر 48 ساعة، وقم بتمرير موجز مصحح إلى أنظمة الجمارك و eBOL لتجنب عدم التطابق النهائي.
قائمة تحقق عملية للتنفيذ اليوم
1. نشر التحقق من رقم التحقق عند حافة واجهة برمجة التطبيقات.
2. دمج سجل رموز موثوق واحد مع أوضاع الوقت الفعلي والمخزنة مؤقتًا.
3. إنشاء قوالب CSV رفض لمستخدمي جداول البيانات وأتمتة الفحص المسبق في واجهة التحميل.
4. تعيين تنبيهات مؤشرات الأداء الرئيسية لارتفاعات الرفض والاحتفاظ بمسارات التدقيق لجميع تحديثات القائمة اليدوية.

اتباع هذه الخطوات يقلل من النتائج الإيجابية الخاطئة، ويسرع معالجة الوصول، ويوائم البيانات مع تدفقات الجمارك و APMS، ويحسن دقة الوقود/الفواتير، ويسمح لفرقك بتحقيق استيعاب متسق وقابل للتدقيق مع الاستمرار في استيعاب التغييرات التشغيلية الحقيقية والتعيينات التي تقودها التحالفات.

المصادقة على خدمات DCSA والاتصال بها: تدفقات OAuth، ومفاتيح واجهة برمجة التطبيقات، وخطوات الانتقال من البيئة الرملية إلى الإنتاج

استخدم بيانات اعتماد عميل OAuth 2.0 للتكاملات من آلة إلى آلة، ورمز التفويض مع PKCE لأي تطبيق يتصرف نيابة عن مستخدم؛ قم بتخزين أسرار العميل في مدير الأسرار وتقييد النطاقات بالحد الأدنى المطلوب.

تطلب TLS 1.2+ لجميع المكالمات عبر الإنترنت، والتحقق من صحة الشهادات، وفرض تثبيت TLS لتطبيقات الهاتف المحمول. للعملاء العامين، قم بتنفيذ PKCE ورموز وصول قصيرة العمر مع رموز تحديث يتم تدويرها عند الاستخدام الأول؛ للعملاء السريين، فضل TLS المتبادل إذا كان المزود يدعمه.

قم بتسجيل كل تطبيق في بوابة مطوري DCSA بمعرف عميل فريد وسري أو مفتاح خاص بالبيئة. استخدم بيانات اعتماد البيئة الرملية للتطوير والاختبار، وقم بتمييز الاختبارات التي تلامس تدفقات ebls أو الجمارك، وقم بتوثيق إصدارات واجهة برمجة التطبيقات التي تستدعيها تكاملك حتى تتمكن من توضيح التغييرات التي قد تؤدي إلى تعطيل.

عندما تتلقى رموز بيئة رملية، قم بأتمتة تخزين الرمز المميز والتجديد: اطلب رمزًا جديدًا عند 90٪ من عمر الرمز المميز، وجرب عمليات تبادل الرموز المميزة الفاشلة مع التراجع الأسي، وقم بتسجيل أخطاء الرمز المميز في دفق تدقيق آمن بدلاً من طباعة الأسرار إلى وحدة التحكم. يقلل الوكيل المحلي الذكي الذي يدرج الرموز المميزة ويفرض حدود المعدل من احتكاك التطوير.

استخدم مفاتيح واجهة برمجة التطبيقات فقط لقياسات الاستكشاف منخفضة المخاطر أو تحديد هوية الشريك حيث لا يتوفر OAuth؛ لا تستخدم مفاتيح واجهة برمجة التطبيقات كبديل لمصادقة المستخدم. تعامل مع مفاتيح واجهة برمجة التطبيقات كأسرار، وقم بتدويرها بشكل ربع سنوي، وقم بحظر المفاتيح التي تظهر أنماط استدعاء شاذة.

اتبع قائمة التحقق هذه من البيئة الرملية إلى الإنتاج: 1) أكمل العقد وتسجيل DCSA، 2) اجتياز اختبارات الأمان والتوافق مع واجهة برمجة التطبيقات في البيئة الرملية، 3) وفر جهة اتصال دعم إنتاج واتفاقية مستوى خدمة، 4) قدم سجلات التدقيق وخطة تراجع يدوية، 5) قدم شهادات mTLS إذا لزم الأمر، و 6) جدولة نافذة قطع الإنتاج مع الناقلين والشركاء. إذا كان ناقل مثل hapag-lloyd أو بوابة جمركية يتطلب نافذة نشر في أكتوبر، فقم بالتنسيق مبكرًا وتأكيد من يرسل إيصالات التأكيد النهائية.

قم بتجهيز كل مكالمة إنتاج بمعرفات الارتباط، وتتبع أوقات الطلب/الاستجابة، والتقاط الحالة HTTP والإيصالات على مستوى الأعمال لتدفقات معادلة EDI مثل ebls وتأكيدات الحجز. قم بتمييز الأحداث حسب الشريك، والشاحنين، والناقل، ومكان التشغيل حتى تتمكن الفرق النهائية من التصفية حسب متطلبات الجمارك، أو التقارير البيئية، أو تتبع الوقود.

حافظ على الحد الأدنى من خطوات دليل الترحيل: أتمتة تحميل الشهادات، وتسجيل العملاء، والموافقات على النطاق حيثما أمكن، واحتفظ بقائمة تحقق توضح الشركاء المتصلين ومن لا يزالون بحاجة إلى إلحاق يدوي. يقوم اختبار دخان آلي واحد يستعلم عن حجز ويتحقق من إيصال متتبع بتقليل مخاطر القطع.

أثناء التطوير، قم بمحاكاة سلوك الشريك: قم ببناء قابس يرسل حمولات خطاف ويب واقعية ويتحقق من صحة إقراراتك، بما في ذلك قبول ebls ورسائل الإيصال. قم بتشغيل اختبارات تحميل على البيئة الرملية التي تحاكي حركة مرور العمليات القصوى من الناقلين والشاحنين والبوابات الجمركية حتى تتمكن من ضبط إعادة المحاولة والتزامن.

راقب الاستخدام ومؤشرات الأداء الرئيسية التجارية بعد الانتقال إلى الإنتاج: تتبع معدلات تبادل الرموز المميزة، وفشل مكالمات المصادقة، ومتوسط زمن استجابة المكالمات، وعدد الإيصالات التي لم يتم تسليمها إلى الشركاء. استخدم هذه المقاييس لتحديد أولويات الإصلاحات التي تؤثر بشكل مباشر على الشاحنين والناقلين والصناعات التي تعتمد على تحديثات EDI/EBL في الوقت المناسب وإعداد التقارير البيئية أو المتعلقة بالوقود.