دليل تكامل WMS: ‏REST وWebhooks وWebSockets لخريطة مستودع حيّة

ابحث عن «تكامل WMS» وستجد نفسك وسط جدل حول البروتوكولات. أما لخريطة مستودع حيّة فالسؤال المفيد أضيق: كيف يُخرج نظام WMS بياناته، وما مدى الحداثة التي تحتاجها الخريطة؟ قد يوفّر WMS نقاط REST، أو يطلق Webhooks، أو ينشر في طابور رسائل، أو يبثّ عبر socket. ويقبل Spatial Map ثلاثة أنواع من المدخلات: يسحب نقاط REST، ويستورد الملفات، ويستقبل الدفع على شكل كتابات في API جدول. فهل تحتاج إلى Webhooks أو WebSockets؟ قد يُصدرها نظام WMS لديك؛ ويستقبلها Spatial Map كتاباتٍ في API الجداول يرسلها وسيط تملكه أنت.

افتح Integrations → Add integration وستجد ثلاثة خيارات: REST API وUpload file وTable. ثم يضيف الجدول طريقًا رابعًا — واجهة الكتابة الخاصة به — إلى جانب مستطلِع اختياري على الخادم. والفارق الأساسي بينها هو مكان التشغيل.

لا تحتاج إلى موصل خاص بمورّد بعينه — فلا يوجد في Spatial Map أي موصل من هذا النوع. المهم هو نوع الواجهة التي يوفّرها نظام WMS لديك. راجع وثائق التكامل لإصدارك؛ فالأنماط التالية تصحّ على معظم المنتجات.

الوسيط هو أي برنامج صغير يقع بين WMS وSpatial Map: دالة serverless خلف Webhook الخاص بـ WMS، أو مستهلك لطابور الرسائل، أو عملية تُبقي socket نظام RTLS مفتوحًا. ومهمّته لا تتغيّر: تحويل كل حدث إلى صف في جدول وإرسال الصفوف على دفعات.

1. 1
   أنشئ الجدول

   من Tables أنشئ جدولًا لكل نوع من الأشياء (المواقع، أحداث الالتقاط، العمّال) واختر نوعه — Marker / POI أو Asset (mobile) أو Shipment أو Polygon / area وغيرها. لكل حقل API key مثل `bin_code` أو `status`: وهي مفاتيح الـ payload التي يرسلها الوسيط. راجع Tables.

2. 2
   أنشئ مفتاحًا

   في تبويب API & access للجدول، يُنشئ Owner أو Admin مفتاحًا يبدأ بـ `sgv_tbl_` ويُعرض مرة واحدة فقط. المفتاح الواحد يكتب في جدول واحد، لذلك لا يحوي الرابط معرّف الجدول. امنح كل نظام مفتاحه الخاص لتتمكّن من إلغاء أحدها دون تعطيل البقية، وانسخ رابط الأساس الدقيق من التبويب نفسه.

3. 3
   حوّل كل حدث إلى صف

   اختر `entityKey` ثابتًا — رمز الموقع، أو معرّف الحدث، أو معرّف البطاقة. تُحدَّث الصفوف أو تُنشأ (upsert) بحسب هذا المفتاح، فيؤدي التسليم المكرّر إلى الاستبدال لا التكرار.

4. 4
   أرسل دفعات لا أحداثًا منفردة

   خزّن الأحداث لبضع ثوانٍ ثم أرسل `POST /rows/bulk` (صفوف كاملة) أو `PATCH /rows/bulk` (الحقول المتغيّرة فقط) بما يصل إلى 1,000 صف. تُعتمد الصفوف الصالحة حتى لو فشل غيرها؛ وتعود المرفوضة في `errors[]`.

5. 5
   أعد المحاولة للأخطاء الصحيحة

   `429` يعني أن المفتاح تجاوز 60 طلبًا في الدقيقة؛ و`401` يعني أن المفتاح خاطئ أو ملغى؛ و`400` يعني أن صفًا خالف مخطط الجدول (حقل إلزامي أو فريد). احتفظ بالصفوف غير المرسلة وأعد المحاولة في الدورة التالية.

curl -X POST https://app.spatialmap.io/api/v1/public/tables/rows \
  -H "Authorization: Bearer $SPATIALMAP_TABLE_KEY" \
  -H "Content-Type: application/json" \
  -d '{"entityKey":"EV-20261011-0412","payload":{"event_id":"EV-20261011-0412","event_type":"pick","item_id":"B-B86-L2-01","from_bin_code":"B-B86-L2","quantity":2,"worker_id":"W-04","ts":"2026-10-11T09:14:05Z"}}'

curl -X POST https://app.spatialmap.io/api/v1/public/tables/rows/bulk \
  -H "Authorization: Bearer $SPATIALMAP_TABLE_KEY" \
  -H "Content-Type: application/json" \
  -d '{"rows":[
        {"entityKey":"EV-20261011-0413","payload":{"event_id":"EV-20261011-0413","event_type":"pick","item_id":"A-B07-L1-02","from_bin_code":"A-B07-L1","quantity":1,"worker_id":"W-02","ts":"2026-10-11T09:14:09Z"}},
        {"entityKey":"EV-20261011-0414","payload":{"event_id":"EV-20261011-0414","event_type":"move","item_id":"B-B99-L1-03","from_bin_code":"B-B99-L1","to_bin_code":"B-B51-L1","quantity":1,"worker_id":"W-05","ts":"2026-10-11T09:14:11Z"}}
      ]}'

curl -X PATCH https://app.spatialmap.io/api/v1/public/tables/rows/A-B01-L1 \
  -H "Authorization: Bearer $SPATIALMAP_TABLE_KEY" \
  -H "Content-Type: application/json" \
  -d '{"status":"blocked","hold_reason":"Damaged pallet"}'

// relay.mjs (Node 18+) - receives bin-status webhooks from your WMS and
// forwards them in batches to the "Rack Inventory" table. A sketch, not a product.
import http from 'node:http';

const BASE = 'https://app.spatialmap.io/api/v1/public/tables'; // copy yours from API & access
const KEY = process.env.SPATIALMAP_TABLE_KEY;                  // sgv_tbl_... (this table's key)
const pending = new Map();                                     // bin_code -> latest changes

http.createServer((req, res) => {
  let body = '';
  req.on('data', (chunk) => (body += chunk));
  req.on('end', () => {
    try {
      // 1. Verify your WMS's webhook signature here (its docs say how).
      const e = JSON.parse(body);
      // 2. Map the WMS event onto your table's field keys.
      const prev = pending.get(e.bin_code)?.patch ?? {};
      pending.set(e.bin_code, {
        entityKey: e.bin_code,
        patch: { ...prev, status: e.status, sku: e.sku, quantity: e.quantity },
      });
      res.writeHead(202).end();
    } catch {
      res.writeHead(400).end();
    }
  });
}).listen(8080);

// 3. Flush every 5 s: one request instead of one per event (60 requests/min per key).
setInterval(async () => {
  const rows = [...pending.values()].slice(0, 1000);
  if (rows.length === 0) return;
  rows.forEach((r) => pending.delete(r.entityKey));
  try {
    const res = await fetch(BASE + '/rows/bulk', {
      method: 'PATCH', // merge changed fields onto existing bins
      headers: { Authorization: 'Bearer ' + KEY, 'Content-Type': 'application/json' },
      body: JSON.stringify({ rows }),
    });
    if (!res.ok) throw new Error('HTTP ' + res.status); // 401 key, 429 rate limit, 5xx
    const { errors } = await res.json();                 // rows the table rejected
    if (errors?.length) console.warn(errors);
  } catch (err) {
    // put the batch back without losing newer events; retry on the next tick
    rows.forEach((r) => {
      const newer = pending.get(r.entityKey);
      pending.set(r.entityKey, newer ? { ...newer, patch: { ...r.patch, ...newer.patch } } : r);
    });
    console.error(err);
  }
}, 5000);

يضمّ مستودع العرض Acme Warehouse سبعة عشر رفًا فيها 314 موقعًا، مع جداول مثل Rack Inventory (صف لكل موقع، مفتاحه `bin_code` مثل `A-B01-L1`، وحقوله `status` و`sku` و`quantity`) وInventory Items وPick Events وWarehouse Workers. ويستخدم تدفّق WMS نموذجي هنا ثلاثة من المسارات الأربعة.

1. 1
   حالة المواقع بالاستطلاع

   إن كان لدى WMS نقطة لمخزون كل موقع، فافتح Rack Inventory → API & access → Pull from a REST API: الرابط، وفاصل 30 ثانية أو أكثر، وRow key field in the response = `bin_code`، وWhere the items are (JSON path) إن كانت القائمة داخل غلاف، وترويسات المصادقة، وربط الحقول. اضغط Start polling؛ يصل التشغيل الأول خلال دقيقة. الوصفة الكاملة: استطلاع نقطة REST وفق جدول زمني.

2. 2
   الأحداث بالدفع

   وجّه Webhooks «تأكيد الالتقاط» و«حالة الموقع» في WMS إلى وسيطك. تصبح عمليات الالتقاط المؤكدة صفوفًا جديدة في Pick Events (`POST /rows/bulk`)، وتُحدِّث تغييرات الحالة الموقع المطابق في Rack Inventory (`PATCH /rows/bulk`). خطوة بخطوة: دفع الصفوف عبر واجهة الكتابة في الجدول.

3. 3
   اللقطات بالرفع

   يدخل ملف الجرد الدوري الليلي عبر Upload file، ويحدّثه زر Re-import على بطاقة المصدر — دون أي برمجة.

4. 4
   اعرضه على الخريطة

   في المحرّر افتح Data → Manage data links → New link. رابط من نوع Color a shape يلوّن كل موقع بحسب `status` عبر قواعد التنسيق، ورابط Live location marker يضع العمّال عند خطوط العرض والطول الخاصة بهم. راجع نظرة عامة على روابط البيانات.

5. 5
   تحقّق من التدفّق

   يعرض تبويب Health في Integrations كل جدول مع آخر وقت كتبت فيه أنظمتك إليه. وتُحفظ كل كتابة عبر الـ API في History الصف، ويمكن لرابط Historical movement إعادة تشغيلها على الخريطة.

Create new table: اختر ما يصفه كل سجلّ

• Tables — المخطط والسجلات وتبويب API & access.
• Integrations — تكاملات REST API ورفع الملفات وحالة المصادر.
• دفع الصفوف عبر واجهة الكتابة في الجدول — مثال كامل بالمفاتيح وcurl.
• استطلاع نقطة REST وفق جدول زمني — الاستطلاع من الخادم من البداية إلى النهاية.
• نظرة عامة على روابط البيانات — كيف تتحوّل الصفوف إلى علامات وألوان وشارات.
• Spatial Map للمستودعات والتوأم الرقمي للمستودع مقابل WMS.