メインコンテンツまでスキップ

注文の統合とSWAT APIによる配達証明

APIとの最も基本的な統合は1時間以内に完了できます。このクイックリファレンスガイドでは、以下を実現するために必要な手順を説明します。

  • さらなる最適化のためにSWATシステムに予約（注文）を送信する
  • 注文の配達証明を受け取る

このガイドには、現場での運用フローに大きな影響を与える可能性のあるライブ運用中に注文を挿入できる、より複雑なシナリオは含まれていません。さらに、このガイドでは、すべてのプロジェクト構成が事前に実装されていることを前提としています（たとえば、SWATサポートチームによって）。このガイドでは、必要なフィールドの最小限のセットのみを扱いますが、SWATサポートチームと一緒に統合を構築する前にデータマッピングを実施することをお勧めします。このガイドでは、単一の車両旅行シナリオで単一の集荷と複数の降車を想定しています。

認証​

SWAT APIバックエンドは基本認証をサポートしています。カスタマーサポートチームが関連するユーザー名とパスワードのペアを提供します。

注文（予約）の送信​

SWATバックエンドへの注文データのアップロードは、単一のAPIを呼び出すことで実行できます。これにより、最適化のために注文を検証、ジオコード、処理、準備するために必要なすべての手順が内部的に実行されます。APIリクエストでは、注文に対して多数のパラメーターを指定する必要があります。

  • 予約データ
  • 配達業務の開始時刻と日付（たとえば、その日の最初の集荷時刻）。
  • 注文をアップロードするプロジェクト識別子（SWATサポートチームから提供）。顧客ごとに1つのプロジェクトを持つことをお勧めします。したがって、独立した運用を分割する方法として使用されます。
  • シミュレーションテンプレートID。運用の複雑さに応じて、最も単純なケースでは、プロジェクトのすべての注文で値は一定になります。ルートの最適化や配達設定が毎日異なる場合に、複数のテンプレートが役立ちます。

アップロードと処理には、アップロードする注文の量に応じて時間がかかる場合があります。多数（5000件以上）の注文をアップロードする必要がある場合は、注文ペイロードのすべてのパラメーターに同じ値を保持しながら、複数のPOSTリクエストを実行することをお勧めします。

基本的なペイロードの例には、2つの注文が含まれています。2番目の注文には、降車のWGS84座標は含まれていません。代わりに、座標に0の値を設定しますが、data.dropoff_addressを提供します。これにより、APIが自動ジオコーディングを実行します。

ヒント

実際には、フォールバックの次の順序で解決されます：予約内の集荷/降車の緯度/経度->予約内の*_postal_code（シンガポールの場合）->booking.dataフィールド内の降車/集荷住所。明示的に設定された緯度と経度が他のすべてよりも優先されます。プロジェクトのジオコーダーを構成する必要があり、正常な解決のデフォルトのしきい値は0.99のジオコーディング品質です。 オプションで、ジオコーディングプロセスの品質を向上させるために、住所に加えてdropoff/pickup_cityまたはdropoff/pickup_countryを設定できます。

運用場所が使用されている場合、予約に明示的に緯度と経度が設定されていない限り、運用場所の座標が最初に考慮されます。予約に緯度と経度が設定されている場合は、運用場所オブジェクトの場所座標が上書きされます。

予約のアップロード

POST {base_url}/api/v2/microservices/logisticsapi

{
    "simulation_clone_parameters": {
        "start_time": "{{date_of_service}}T00:00:00+07:00",
        "end_time": "{{date_of_service}}T12:00:00+07:00",
        "project_id": {{project_id}}
    },
    "bookings": [
        {
            "uid": "aa082b4c-e8b3-4caf-a9f2-aba007bdde63", //注文のUUID（顧客生成）
            "demand": {
                "parcel": 1 // 注文を実行するために車両に必要な容量を設定します。
            },
            "pickup_location_name": "Hub",
            "pickup_location_lat": 13.81722301, // あるいは、郵便番号を使用できます
            "pickup_location_lon": 100.5124416,
            "min_pickup_time": "{{date_of_service}}T10:00:00+07:00",
            "max_pickup_time": "{{date_of_service}}T12:00:00+07:00",
            "pickup_service_time": 0,
            "dropoff_location_name": "Grocery shop",
            "dropoff_location_lat": 13.8353723,
            "dropoff_location_lon": 100.5732801,
            "min_dropoff_time": "{{date_of_service}}T14:00:00+07:00",
            "max_dropoff_time": "{{date_of_service}}T20:00:00+07:00",
            "dropoff_service_time": 300 //300秒または5分
        },
        {
            "uid": "aa082b4c-e8b3-4caf-a9f2-aba007bdde66", //注文のUUID（顧客生成）
            "demand": {
                "parcel": 1
            },
            "pickup_location_name": "Hub",
            "pickup_location_lat": 13.81722301,
            "pickup_location_lon": 100.5124416,
            "min_pickup_time": "{{date_of_service}}T10:00:00+07:00",
            "max_pickup_time": "{{date_of_service}}T12:00:00+07:00",
            "pickup_service_time": 0,
            "dropoff_location_name": "Grocery shop",
            "min_dropoff_time": "{{date_of_service}}T14:00:00+07:00",
            "max_dropoff_time": "{{date_of_service}}T20:00:00+07:00",
            "dropoff_service_time": 300, //300秒または5分
            "data": {
                "external_id": "EXSS2407120009254",
                "customer_name": "Best customer",
                "customer_phone": "956123123123",
                "pickup_customer_name": "Awesome customer",
                "dropoff_customer_name": "Customer to deliver to",
                "dropoff_customer_phone": "2434234234234",
                "dropoff_address": "255 Some Ave, Some city, some country, 00000",
                "dropoff_country": "Some country",
                "dropoff_city": "Some city",
                "remarks": "s60"
            }
        }
    ]
}

アップロードが成功すると、APIは作成されたbooking_idのリストとともにHTTP 200を返します。

注文の配達予定時刻と割り当てられた車両/ドライバーの取得​

消費者のニーズに応じて、注文の配達予定時刻（集荷と降下の両方）を取得するには2つの方法があります。

ETAと配達予定時刻によるリアルタイム更新​

消費アプリケーションが配達または集荷情報をほぼリアルタイムで取得する必要がある場合、それを実現する最善の方法は、vehicle_arrivalまたはvehicle_arrival_grouped Webhookメッセージを購読することです。これらのメッセージには、単一の注文またはその車両のすべての注文について、数分ごとに配達予定時刻と更新されたETA情報の両方が含まれています。消費者が購読できるメッセージの範囲はシミュレーションであり、構成されたWebhookを持つシミュレーション内のすべてのライブ車両がオンラインになるとすぐに更新を送信することを意味します。

APIを介した配達予定時刻のプル​

配達予定時刻は、Webhookサブスクリプションを使用せずにオンデマンドでプルすることもできます。

ヒント

各予約は少なくとも2つのノードで構成されているため、配達予定タイムスタンプは予約レベルではなく、予約の各ノードで維持されます。これにより、部分的な配達や部分的な集荷など、予約内の柔軟な管理ノードをサポートする柔軟性が確保されます。

次のAPIを使用して、ノードから予約の配達予定時刻を取得できます。

配達予定時刻
GET {{base_url}}/api/v2/node?booking={{booking_id}}&simulation={{simulation_id}}
or
GET {{base_url}}/api/v2/node?booking_uid={{booking_uid}}&simulation={{simulation_id}}
配達予定時刻の例
{
    "meta": {
//....
    },
    "objects": [
        {
        //...
            "booking_uid": "8e251e2b-e57b-11ed-8252-040903d1bd82",
            "id": 3585579,
            "node_type": "pickup",
            "scheduled_ts": "2023-05-09T20:32:20.700000+00:00", 
            "uid": "a347f610-2c8f-4a77-8d8a-15d5db86e8a6",
        //..
        },
        {
            "booking_uid": "8e251e2b-e57b-11ed-8252-040903d1bd82",
            "id": 3585604,
            "node_type": "dropoff",
            "scheduled_ts": "2023-05-09T20:59:40.510000+00:00",
            "uid": "581bc301-21e8-49ad-8ab0-9463ff4ca9f1",
        //..
        }
    ]
}

割り当てられた車両/ドライバーの取得​

SWATモデルでは、車両はドライバーと1対1の関係にあり、ドライバーはユーザー名と1対1の関係にあります。予約が車両に割り当てられると、予約の各ノードにassigned_vehicleが入力されます。車両は予約レベルではなくノードレベルで割り当てられ、車両のペイロードを別の車両に転送できるハンドオーバーシナリオをサポートします。

同じ例を使用します。

配達予定時刻
GET {{base_url}}/api/v2/node?booking={{booking_id}}&simulation={{simulation_id}}
or
GET {{base_url}}/api/v2/node?booking_uid={{booking_uid}}&simulation={{simulation_id}}
割り当てられたドライバーの例
{
    "meta": {
//....
    },
    "objects": [
        {
        //...
            "booking_uid": "8e251e2b-e57b-11ed-8252-040903d1bd82",
            "id": 3585579,
            "assigned_vehicle": "/api/v2/vehicle/1733134",            
            "node_type": "pickup",
            "scheduled_ts": "2023-05-09T20:32:20.700000+00:00", 
            "uid": "a347f610-2c8f-4a77-8d8a-15d5db86e8a6",
        //..
        },
        {
            "booking_uid": "8e251e2b-e57b-11ed-8252-040903d1bd82",
            "id": 3585604,
            "assigned_vehicle": "/api/v2/vehicle/1733134",            
            "node_type": "dropoff",
            "scheduled_ts": "2023-05-09T20:59:40.510000+00:00",
            "uid": "581bc301-21e8-49ad-8ab0-9463ff4ca9f1",
        //..
        }
    ]
}

その後、車両APIを使用して、ドライバーAPIを介して車両と割り当てられたドライバーに関する現在の情報を取得できます。

ヒント

サービスの使用状況によっては、車両がドライバーに恒久的に割り当てられている場合、ドライバー名の代わりにvehicle.service_numberを使用することが可能な場合があります。この場合、消費アプリケーションがvehicle_idとvehicle_agent_idを含むメッセージタイプvehicle_arrival_groupedのWebhookを使用している場合は、Webhookがアプリケーションに到着したときに車両APIまたはドライバーAPIを使用して、車両の現在のサービス番号または割り当てられたドライバーを取得します。

注文ステータス（配達証明）の受信​

注文ステータスを取得するには2つの方法があります。1つ目はSWAT APIから注文データをプルする方法、2つ目は予約が変更されるたびに発行されるイベントを購読する方法です。

予約ステータスのリクエスト（予約ステータスのポーリング）​

以下を使用して予約のステータスを取得できます。ここで、booking_uidは予約を送信するために使用された元のuidです。

予約ステータス
GET {base_url}/api/v2/booking?uid=<booking_uid>

レスポンスには、stateフィールドにその状態を含む予約オブジェクトが含まれます。

メッセージングによる予約ステータスの取得​

Webhookを使用して、予約の状態の変更に関するメッセージの受信を開始できます。詳細なドキュメントはこちらにあります。単純なケースでは、構成はSWATサポートチームによって行われ、消費者は以下に示す例に基づいてWebhookの受信を開始します。ここで、booking_uidは元の予約のuidです。

完了した降車の例
{
      "simulation_id": 172571,
      "agent_type": "vehicle",
      "message_type": "node_status",
      "data": {
        "node_uid": "a1d1a6ae-9a0d-40c1-a633-3d6ef05cf7b9",
        "status": "completed",
        "vehicle_id": 17590317,
        "node_id": 48332514,
        "node_type": "dropoff",
        "booking_uid": "e438ab3d-b33a-572d-a114-0a5490e07f40",
        "booking_id": 22151625,
        "action_data": null,
        "is_confirmation": true
      },
      "current_sim_ts": "2024-11-16T18:26:22+00:00",
      "server_ts": "2024-09-10T04:33:23.364180",
      "transmit_to_websocket": false,
      "agent_id": "daae025f-f21d-4c65-b901-45e139283667",
      "user_id": 57638
    }

最終顧客への予約追跡の提供

SWAT APIは、予約の進行状況の可視性のために共有可能な追跡リンクを提供します。

注記

このエンドポイントは認証されておらず、限られた情報セットを提供します。