انتقل إلى المحتوى
AtlasVialo
المطورون

ضع محرك السعة داخل نظام إدارة النقل لديك.

واجهة REST واحدة لكل ما يفعله Vialo Fleet: تسعير حمولة إضافية على طريق، ومزامنة جولاتك، وحجز الشحنات، وتلقي إشعار بكل تغيير. JSON في الطلب والرد، والمبالغ بالوحدات الصغرى.

Base URL  https://fleet.atlasvialo.com/api/v1

بداية سريعة

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

    في Vialo Fleet افتح التكاملات وأنشئ مفتاح API. يُعرض مرة واحدة فقط.

  2. 2اطلب حكمًا

    أرسل طريقًا وبعض الشحنات إلى POST /evaluate. لا يُحفظ شيء.

  3. 3زامن جولاتك

    أرسل كل جولة من نظامك عبر PUT بمرجعها الخاص، ثم اقرأ الاقتراحات.

  4. 4استمع

    أضف نقطة استقبال Webhook لتعرف بالحجوزات والاستلام والتسليم.

curl -X POST https://fleet.atlasvialo.com/api/v1/evaluate \
  -H "Authorization: Bearer vk_…" \
  -H "Content-Type: application/json" \
  -d @evaluate.json

المصادقة

أرسل المفتاح كرمز Bearer أو في X-Api-Key. يعمل المفتاح لشركة واحدة بصلاحيات المالك الذي أنشأه، ويتوقف عن العمل فور إلغائه.

كل عملية كتابة عدا /evaluate تأخذ ترويسة Idempotency-Key، فلا تحجز إعادة المحاولة مرتين أبدًا.

Authorization: Bearer vk_1a2b3c4d_…
X-Api-Key: vk_1a2b3c4d_…
Idempotency-Key: 6f1e2c8a-…

تقييم شحنة

المحرك عند الطلب: هل هذه الحمولة الإضافية مناسبة لهذه المركبة على هذا الطريق؟

POST/evaluate

حتى 100 شحنة في الطلب. يحمل كل رد الحكم والفحوص الستة والحساب الكامل وموضع الشحنة بين محطاتك وكل موعد وصول. السعر null يعيد أدنى سعر يحقق قواعدك.

الطلب
{
  "currency": "EUR",
  "vehicle": {
    "max_weight_kg": 2000,
    "cost_per_km_minor": 80,
    "cost_per_hour_minor": 4000
  },
  "route": {
    "origin": {
      "lat": 62.3908,
      "lng": 17.3069
    },
    "destination": {
      "lat": 63.8258,
      "lng": 20.263
    },
    "via": [
      {
        "point": {
          "lat": 62.487,
          "lng": 17.326
        },
        "label": "Timrå delivery",
        "service_time_s": 900,
        "load_change": {
          "weight_kg": -1200
        }
      }
    ],
    "depart_from": "2026-10-05T07:00:00+02:00",
    "onboard": {
      "weight_kg": 1500
    }
  },
  "rules": {
    "max_delay_s": 7200,
    "min_profit_minor": 2000
  },
  "loads": [
    {
      "ref": "ORDER-4711",
      "pickup": {
        "lat": 62.6323,
        "lng": 17.9379
      },
      "dropoff": {
        "lat": 63.2909,
        "lng": 18.7153
      },
      "weight_kg": 300,
      "pickup_from": "2026-10-05T08:00:00+02:00",
      "pickup_until": "2026-10-05T14:00:00+02:00",
      "deliver_by": "2026-10-05T18:00:00+02:00",
      "price_minor": 40000
    }
  ]
}
الرد
{
  "results": [
    {
      "ref": "ORDER-4711",
      "verdict": "good",
      "blocked_by": null,
      "arithmetic": {
        "detour_distance_m": 8700,
        "detour_duration_s": 2220,
        "extra_cost_minor": 4560,
        "price_minor": 40000,
        "profit_minor": 35440,
        "profit_per_hour_minor": 57470,
        "min_price_minor": 6560,
        "currency": "EUR"
      },
      "insertion": {
        "pickup_after": 1,
        "dropoff_after": 1
      },
      "depart_at": "2026-10-05T05:00:00.000Z",
      "pickup_eta": "2026-10-05T06:12:40.000Z",
      "gates": [
        {
          "gate": "physical",
          "outcome": "pass",
          "detail": {
            "peak_kg": 600,
            "max_kg": 2000
          }
        },
        "…"
      ],
      "stops": [
        {
          "sequence": 0,
          "kind": "origin",
          "eta": "…",
          "load_after_kg": 1500
        },
        "…"
      ]
    }
  ],
  "route": {
    "base_distance_m": 276000,
    "base_duration_s": 11400,
    "via_stops": 1
  }
}

موصل أنظمة إدارة النقل

جولاتك ومركباتك بمراجعك الخاصة.

PUT/tms/vehicles/{ref}

أنشئ أو حدّث مركبة بمرجعك: السعة والتكلفة لكل كيلومتر ولكل ساعة والتجهيزات.

الطلب
{
  "label": "Truck 07",
  "max_weight_kg": 24000,
  "cost_per_km_minor": 172,
  "cost_per_hour_minor": 4800,
  "tags": [
    "tail-lift"
  ]
}
الرد
{
  "id": "9c1e…",
  "external_ref": "TRUCK-07",
  "created": true
}
PUT/tms/tours/{ref}

أنشئ جولة بمحطاتها وتغيرات الحمولة والمواعيد النهائية. إرسالها مجددًا يستبدلها ما دام لا يوجد حجز.

الطلب
{
  "vehicle_ref": "TRUCK-07",
  "origin": {
    "point": {
      "lat": 62.3908,
      "lng": 17.3069
    },
    "label": "Sundsvall depot"
  },
  "destination": {
    "point": {
      "lat": 63.8258,
      "lng": 20.263
    },
    "label": "Umeå depot"
  },
  "depart_from": "2026-10-05T07:00:00+02:00",
  "onboard": {
    "weight_kg": 1500
  },
  "stops": [
    {
      "point": {
        "lat": 62.487,
        "lng": 17.326
      },
      "label": "Customer A",
      "service_time_s": 900,
      "load_change": {
        "weight_kg": -1000
      },
      "latest_arrival": "2026-10-05T10:00:00+02:00"
    }
  ]
}
الرد
{
  "trip_id": "4f2a…",
  "external_ref": "TOUR/2026-10-05/17",
  "replaced": null,
  "base_distance_m": 276000,
  "base_duration_s": 11400
}
GET/tms/tours/{ref}/suggestions

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

الرد
{
  "trip_id": "4f2a…",
  "external_ref": "TOUR/2026-10-05/17",
  "suggestions": [
    {
      "offer_id": "b71d…",
      "package_id": "0e9c…",
      "pickup_label": "Härnösand",
      "dropoff_label": "Örnsköldsvik",
      "weight_kg": 300,
      "price_minor": 40000,
      "min_price_minor": 6560,
      "profit_minor": 35440,
      "profit_per_hour_minor": 57470,
      "detour_duration_s": 2220,
      "currency": "EUR",
      "acceptance_likelihood": 0.82,
      "insertion": {
        "pickup_after": 1,
        "dropoff_after": 1
      },
      "expires_at": "…"
    }
  ]
}
DELETE/tms/tours/{ref}

ألغِ جولة لا حجوزات عليها.

الرد
{
  "cancelled": true,
  "trip_id": "4f2a…"
}

العروض والحجز

اقرأ العروض المرتبة لرحلة، أو احجز أحدها، أو اقترح سعرك.

GET/trips/{id}/offers

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

الرد
{
  "offers": [
    {
      "id": "b71d…",
      "package_id": "0e9c…",
      "reward_minor": 40000,
      "profit_minor": 35440,
      "profit_per_hour_minor": 57470,
      "acceptance_likelihood": 0.82,
      "…": "…"
    }
  ],
  "rejects": [
    {
      "package_id": "77aa…",
      "blocked_by": "sla",
      "…": "…"
    }
  ]
}
POST/offers/{id}/accept

احجز عرضًا. تُعاد كل الفحوص على الخطة الحالية، ولا يمكن حجز الشحنة إلا مرة واحدة.

الطلب
{
  "confirm_tracking": true
}
الرد
{
  "accepted": true,
  "assignment_id": "a3d0…",
  "trip_id": "4f2a…",
  "package_id": "0e9c…",
  "agreed_price_minor": 40000
}
POST/offers/{id}/quote

اقترح سعرك على عرض. إن كان دون قواعدك يُرفض قبل إرساله.

الطلب
{
  "price_minor": 42000,
  "message": "We pass Härnösand around 08:15.",
  "confirm_tracking": true
}
الرد
{
  "conversation_id": "c19f…",
  "quote_id": "q2b8…",
  "profit_minor": 37440,
  "min_quote_minor": 6560
}

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

اعثر على أي مركبة أو رحلة أو شحنة بالمعرّف الذي يستخدمه نظامك.

GET/{vehicles|trips|packages}/by-ref/{ref}

اعثر على معرّف AtlasVialo خلف مرجعك. رمّز المرجع في الرابط.

الرد
{
  "id": "4f2a…",
  "external_ref": "TOUR/2026-10-05/17"
}

Webhooks

أحداث موقّعة تُدفع إلى خادمك وتُعاد حتى تصل.

POST/webhooks

أضف نقطة استقبال HTTPS، لأحداث مختارة إن شئت. يحمل الرد سر التوقيع.

الطلب
{
  "url": "https://tms.example.com/atlasvialo",
  "events": [
    "booking.created",
    "trip.offers_updated"
  ]
}
الرد
{
  "id": "w81c…",
  "url": "https://tms.example.com/atlasvialo",
  "events": [
    "booking.created",
    "trip.offers_updated"
  ],
  "secret": "whsec_…",
  "active": true
}
POST/webhooks/{id}/test

أرسل حدث اختبار موقّعًا الآن وشاهد كيف ردت نقطة الاستقبال.

الرد
{
  "delivered": true,
  "status": 200,
  "error": null
}
GET/webhooks/{id}/deliveries

آخر عمليات التسليم مع الحالة وعدد المحاولات وآخر خطأ.

الرد
{
  "deliveries": [
    {
      "id": "d5e2…",
      "event": "booking.created",
      "status": "delivered",
      "attempts": 1,
      "last_status": 200,
      "created_at": "…"
    }
  ]
}

المؤشرات والتعلم

المسار من الرحلات إلى الحجوزات وما يمنع الشحنات.

GET/metrics/funnel?from=…&to=…

الرحلات المنشورة، والرحلات ذات العروض، والشحنات المقيّمة والممكنة والمحجوزة والمسلّمة، والإيراد وصافي الربح.

الرد
{
  "trips_posted": 42,
  "trips_with_offers": 37,
  "candidates_evaluated": 1180,
  "viable_offers": 214,
  "bookings": 61,
  "delivered": 58,
  "booked_revenue_minor": 1830000,
  "booked_profit_minor": 1412000,
  "rates": {
    "trips_with_offers": 0.881,
    "viable_of_evaluated": 0.181,
    "booked_of_viable": 0.285
  }
}
GET/metrics/insights

الفحوص التي تمنع أكبر قدر من الشحنات، وكم شحنة ممنوعة ستمر لو خُففت قاعدة.

الرد
{
  "blocked": [
    {
      "blocked_by": "sla",
      "reason": "delay_exceeds_max",
      "n": 312
    },
    {
      "blocked_by": "margin",
      "reason": "profit_below_min",
      "n": 140
    }
  ],
  "what_if": [
    {
      "rule": "max_delay_s",
      "change": "+25%",
      "would_pass": 64
    }
  ]
}

التحقق من Webhook

قيمة X-Vialo-Signature هي t=<ثوانٍ يونكس>,v1=<HMAC-SHA256 ست عشري لـ "t.المحتوى الخام" بسر نقطة الاستقبال>. أعد حسابه وقارنه بزمن ثابت وارفض الطوابع الزمنية القديمة. استخدم الحقل id لتجاهل التكرار.

POST https://tms.example.com/atlasvialo
{
  "id": "d5e2…",
  "event": "booking.created",
  "created_at": "2026-10-05T06:01:12.000Z",
  "data": { "trip_id": "4f2a…", "trip_external_ref": "TOUR/2026-10-05/17",
            "package_id": "0e9c…", "agreed_price_minor": 40000, "currency": "EUR" }
}
Node.js
const [t, v1] = header.split(',').map((p) => p.split('=')[1]);
const expected = crypto.createHmac('sha256', secret).update(`${t}.${rawBody}`).digest();
const ok = crypto.timingSafeEqual(Buffer.from(v1, 'hex'), expected)
  && Math.abs(Date.now() / 1000 - Number(t)) < 300;

الأخطاء

تأتي الأخطاء بصيغة JSON مع رمز: 400 طلب غير صالح (مع التفاصيل)، و401 لمفتاح مفقود أو ملغى، و403، و404، و409 للتعارضات مثل external_ref_exists أو tour_has_bookings، و422 عندما يتعذر حساب الطريق.

{
  "error": "tour_has_bookings",
  "trip_id": "4f2a…"
}

تأتي المسافات والأزمنة من موجّه الطرق الخاص بنا. يغطي اليوم السويد، وتُجاب الشحنات خارجها بأنها غير قابلة للتوجيه.