開発者向け

MG Ship API で構築する

シンプルでバージョン管理された REST API を使って、リアルタイムの貨物可視化データを自社システムに取り込めます。

概要

MG Ship API は、HTTPS 上で JSON を返す REST API です。貨物可視化データ（一覧、貨物レコードの全件、トラッキングのタイムライン）にプログラムからアクセスできるため、マイルストーンを自社の TMS、ERP、または顧客ポータルに取り込めます。

すべてのエンドポイントは、以下のバージョン管理されたベースパス配下に存在します。API は URL パスでバージョン管理されています（v1）。互換性を破壊する変更は新しいパス（v2）として提供され、旧バージョンには 12 か月の非推奨期間が設けられるため、v1 向けに構築した連携はそのまま動作し続けます。

ベース URL

連携対象の環境に応じたベース URL を選択してください。以下のすべてのエンドポイントパスは、このベース URL からの相対パスです。ステージングおよびテスト（VPS）は開発・テスト用です。本番環境は本番用キーでのみ使用してください。

環境	ベース URL
本番環境	`https://api.mglobalship.com/api/v1/external`
ステージング	`https://api.staging.mglobalship.com/api/v1/external`
テスト（VPS）	`https://mgs.aipipis.com/api/v1/external`

OpenAPI 仕様をダウンロード ↓Postman コレクションをダウンロード ↓

認証

すべてのリクエストは、Authorization ヘッダーに Bearer トークンとして送信する API キーで認証します。キーはテナントごとに API Portal から発行され、作成時に一度だけ表示され、明示的なスコープ（例: shipments.read）を持ち、いつでもローテーションまたは失効できます。

キーはサーバー側で保管してください。ブラウザやモバイルのコードに含めて配布してはいけません。キーが漏洩した場合は API Portal からローテーションしてください。古いキーは直ちに無効になります。

bash

curl https://api.staging.mglobalship.com/api/v1/external/health \
  -H "Authorization: Bearer mgs_live_xxxxxxxxxxxxxxxxxxxxxxxx"

規約

ページネーション

一覧系エンドポイントはカーソルベースのページネーションを使用します。limit（1〜100、デフォルト 20）を指定してページサイズを設定します。さらに結果が存在する場合、レスポンスは has_more を true に設定し、next_cursor を返します。これを cursor クエリパラメータとして渡すと次のページを取得できます。カーソルは不透明な値です。トークンとして扱い、自分で構築しないでください。

レート制限

リクエストは、アカウントのティアに基づき 1 分あたりでレート制限されます。すべてのレスポンスには X-RateLimit-Limit、X-RateLimit-Remaining、X-RateLimit-Reset（ウィンドウがリセットされるまでの秒数）の各ヘッダーが含まれます。制限を超えると、本文に retry_after_seconds の値を含む 429 が返されます。個別のキーは、リクエストに応じてより高い上限を付与できます。

ティア	リクエスト / 分
Bronze	60
Silver	300
Gold	1,000
Platinum	5,000
Enterprise	無制限

冪等性

書き込みエンドポイント（POST /shipments など）には Idempotency-Key ヘッダーが必要です。同じキーでリクエストを再試行すると、重複を作成する代わりに元の結果が返されるため、ネットワークの再試行は常に安全です。読み取り専用（GET）エンドポイントでは不要です。

エンドポイント

GET/health

キーが有効に機能するか確認し、現在のティアとレート制限の状況を表示します。接続性を検証するための軽量な呼び出しです。

bash

curl https://api.staging.mglobalship.com/api/v1/external/health \
  -H "Authorization: Bearer mgs_live_..."

json

{
  "status": "ok",
  "tenant_id": 123,
  "tier": "silver",
  "rate_limit": {
    "limit": 300,
    "remaining": 299,
    "reset_seconds": 59
  }
}

POST/shipments

貨物を登録すると、プラットフォームがトラッキングを開始します。shipments.write スコープと一意の Idempotency-Key ヘッダーが必要です。この貨物はプランの月間クォータにカウントされます。

パラメータ	型	説明
`Idempotency-Key`*	string (header)	リクエストごとに一意の値。同じ値で再試行すると、重複を作成する代わりに元の貨物が返されます。
`tracking_number`*	string	AWB / B-L / トラッキング番号。
`carrier_code`*	string	キャリアまたは航空会社コード（PCS コード、IATA 航空会社コード、または AfterShip の courier スラッグ）。
`mode`*	string	輸送モード: sea、air、または courier。

bash

curl -X POST https://api.staging.mglobalship.com/api/v1/external/shipments \
  -H "Authorization: Bearer mgs_live_..." \
  -H "Idempotency-Key: a1b2c3d4-e5f6-7890" \
  -H "Content-Type: application/json" \
  -d '{
    "tracking_number": "160-12345675",
    "carrier_code": "pcs",
    "mode": "air"
  }'

json

{
  "object": "shipment",
  "id": 12346,
  "tracking_number": "160-12345675",
  "carrier_code": "pcs",
  "mode": "air",
  "status": "pending",
  "awb_number": "160-12345675",
  "_links": {
    "self": "/api/v1/external/shipments/12346",
    "tracking": "/api/v1/external/shipments/12346/tracking"
  }
}

GET/shipments

貨物を新しい順に一覧表示します。カーソルページネーションと任意のフィルターに対応しています。

パラメータ	型	説明
`limit`	integer	1〜100、デフォルト 20。
`cursor`	string	前のページから取得した不透明なカーソル。
`status`	string	貨物ステータスでフィルター（例: in_transit）。
`q`	string	貨物フィールド全体を対象とした全文検索。
`mode`	string	air、sea、rail、または road。
`carrier_code`	string	キャリアでフィルター（例: maersk）。
`po`	string	発注番号でフィルター。

bash

curl "https://api.staging.mglobalship.com/api/v1/external/shipments?status=in_transit&limit=20" \
  -H "Authorization: Bearer mgs_live_..."

json

{
  "object": "list",
  "data": [
    {
      "object": "shipment",
      "id": 12345,
      "tracking_number": "MAEU1234567",
      "carrier_code": "maersk",
      "mode": "sea",
      "status": "in_transit",
      "origin": { "country": "CN", "city": "Shanghai", "port_code": "CNSHA" },
      "destination": { "country": "MY", "city": "Port Klang", "port_code": "MYPKG" },
      "po_number": "PO-2026-001",
      "estimated_arrival": "2026-04-30T14:00:00+08:00",
      "_links": {
        "self": "/api/v1/external/shipments/12345",
        "tracking": "/api/v1/external/shipments/12345/tracking"
      }
    }
  ],
  "has_more": false,
  "next_cursor": null,
  "_links": { "self": "/api/v1/external/shipments" }
}

GET/shipments/{id}

単一の貨物を、貨物の詳細情報とマイルストーン履歴の全件付きで取得します。

パラメータ	型	説明
`id`*	integer	貨物 ID（パスパラメータ）。

bash

curl https://api.staging.mglobalship.com/api/v1/external/shipments/12345 \
  -H "Authorization: Bearer mgs_live_..."

json

{
  "object": "shipment",
  "id": 12345,
  "tracking_number": "MAEU1234567",
  "carrier_code": "maersk",
  "mode": "sea",
  "status": "in_transit",
  "origin": { "country": "CN", "city": "Shanghai", "port_code": "CNSHA" },
  "destination": { "country": "MY", "city": "Port Klang", "port_code": "MYPKG" },
  "po_number": "PO-2026-001",
  "container_no": "MAEU123456789",
  "estimated_arrival": "2026-04-30T14:00:00+08:00",
  "vessel_name": "MSC GULSUN",
  "voyage_number": "2026W0105",
  "cargo": {
    "weight_kg": 18000.5,
    "volume_cbm": 45.25,
    "pieces": 120,
    "description": "Electronics",
    "hs_code": "8471.30",
    "container_size": "40HQ",
    "declared_value": { "amount": 499900, "currency": "USD" }
  },
  "milestones": [
    {
      "object": "milestone",
      "status_code": "PICKED_UP",
      "status_text": "Picked up",
      "location": "Shanghai",
      "occurred_at": "2026-04-22T08:15:00+08:00",
      "source": "maersk_direct_api"
    }
  ],
  "_links": {
    "self": "/api/v1/external/shipments/12345",
    "tracking": "/api/v1/external/shipments/12345/tracking"
  }
}

GET/shipments/{id}/weather

貨物の出発地および目的地における現在／予報の天候（Open-Meteo）を取得します。オンデマンドのエンリッチメントで、約30分キャッシュされます。位置を解決できない区間（leg）は null になります。

パラメータ	型	説明
`id`*	integer	貨物 ID（パスパラメータ）。

bash

curl https://api.staging.mglobalship.com/api/v1/external/shipments/12345/weather \
  -H "Authorization: Bearer mgs_live_..."

json

{
  "object": "weather",
  "shipment_id": 12345,
  "origin": {
    "label": "Singapore, SG",
    "lat": 1.29,
    "lng": 103.85,
    "observed_at": "2026-06-25T12:00:00+00:00",
    "temperature_c": 29.4,
    "wind_mps": 2.7,
    "condition_id": 803,
    "condition_main": "Clouds",
    "severity": "low",
    "summary": "Clouds",
    "alerts_count": 0
  },
  "destination": {
    "label": "New York, US",
    "lat": 40.71,
    "lng": -74.0,
    "observed_at": "2026-06-25T12:00:00+00:00",
    "temperature_c": 17.1,
    "wind_mps": 0.5,
    "condition_id": 803,
    "condition_main": "Clouds",
    "severity": "low",
    "summary": "Clouds",
    "alerts_count": 0
  },
  "_links": {
    "self": "/api/v1/external/shipments/12345/weather",
    "shipment": "/api/v1/external/shipments/12345"
  }
}

GET/shipments/{id}/risk

貨物の出発地および目的地付近（過去 7 days 以内、100 km 圏内）の紛争／騒乱イベントを取得します。プロバイダーの結果をキャッシュするオンデマンドのエンリッチメントです。

パラメータ	型	説明
`id`*	integer	貨物 ID（パスパラメータ）。

bash

curl https://api.staging.mglobalship.com/api/v1/external/shipments/12345/risk \
  -H "Authorization: Bearer mgs_live_..."

json

{
  "object": "geopolitical_risk",
  "shipment_id": 12345,
  "origin": {
    "label": "Singapore, SG",
    "lat": 1.29,
    "lng": 103.85,
    "observed_at": "2026-06-25T12:00:00+00:00",
    "severity": "high",
    "radius_km": 100,
    "since_days": 7,
    "summary": "High: 1 violence_civilians event",
    "events_count": 1,
    "top_events": [
      {
        "occurred_on": "2026-06-21",
        "type": "violence_civilians",
        "sub_type": "Attack",
        "location": "Singapore",
        "fatalities": 0,
        "distance_km": 12.0,
        "description": "High: 1 violence_civilians event"
      }
    ]
  },
  "destination": null,
  "_links": {
    "self": "/api/v1/external/shipments/12345/risk",
    "shipment": "/api/v1/external/shipments/12345"
  }
}

GET/shipments/{id}/tracking

貨物のコンパクトなトラッキングタイムライン（順序付けされたマイルストーンイベント）を取得します。

パラメータ	型	説明
`id`*	integer	貨物 ID（パスパラメータ）。

bash

curl https://api.staging.mglobalship.com/api/v1/external/shipments/12345/tracking \
  -H "Authorization: Bearer mgs_live_..."

json

{
  "object": "tracking",
  "shipment_id": 12345,
  "status": "in_transit",
  "estimated_arrival": "2026-04-30T14:00:00+08:00",
  "last_event_at": "2026-04-23T06:00:00+08:00",
  "events": [
    {
      "object": "milestone",
      "status_code": "PICKED_UP",
      "status_text": "Picked up at origin",
      "location": "Shanghai",
      "occurred_at": "2026-04-22T08:15:00+08:00",
      "source": "maersk_direct_api"
    },
    {
      "object": "milestone",
      "status_code": "DEPARTED_ORIGIN",
      "status_text": "Departed origin port",
      "location": "Shanghai",
      "occurred_at": "2026-04-23T06:00:00+08:00",
      "source": "maersk_direct_api"
    }
  ],
  "_links": {
    "self": "/api/v1/external/shipments/12345/tracking",
    "shipment": "/api/v1/external/shipments/12345"
  }
}

Webhook

ポーリングする代わりに Webhook を購読すると、何かが発生したとき（例: 貨物に例外が発生したとき）に通知を受け取れます。API Portal でエンドポイント URL を設定してイベントタイプを選択すると、各イベントごとに JSON ペイロードを指定の URL へ POST します。

すべての配信は署名されているため、当社から送信されたものであることを検証できます。署名は X-MGS-Signature ヘッダーで、イベントタイプは X-MGS-Event で、一意の配信 ID は X-MGS-Delivery-Id で送信します（これを再利用してハンドラーを冪等にできます）。配信は、24 時間にわたり指数バックオフで再試行されます。

X-MGS-Signature は t=<timestamp>,v1=<signature> という形式で、signature は文字列「<timestamp>.<raw-request-body>」をエンドポイントシークレットでキー付けした HMAC-SHA256 の 16 進値です。検証するには、t と v1 を分離し、タイムスタンプ、リテラルのドット、そして正確な生の本文に対して HMAC を再計算して比較します。一致しない場合、またはタイムスタンプが古すぎる場合は拒否してください。

http

X-MGS-Event: shipment.exception
X-MGS-Delivery-Id: whd_8f3c2a1b
X-MGS-Signature: t=1715241600,v1=4e2c...hex...sha256

エラー

エラーは、標準的な HTTP ステータスコードと一貫した JSON エンベロープを使用します。エラーオブジェクトは常に安定したコードと人間が読めるメッセージを持ち、一部のエラーはコンテキストフィールドを追加します。すべてのレスポンスには request_id が含まれます。サポートに問い合わせる際はこれを伝えてください。

ステータス	コード	発生条件
400	`validation_error`	リクエスト本文が欠落しているか無効です（または Idempotency-Key ヘッダーがありません）。
401	`auth.token_invalid`	API キーがないか、無効です。
402	`shipment.overage_payment_required`	貨物クォータを使い切りました。まず未払いの超過分を精算してください。
403	`auth.insufficient_scope`	キーに必要なスコープがありません（例: shipments.read）。
403	`auth.tenant_suspended`	テナントアカウントが有効ではありません。
404	`shipment.not_found`	要求されたリソースが存在しません。
409	`shipment.duplicate`	このトラッキング番号とキャリアの貨物はすでに存在します。
429	`rate_limit_exceeded`	レート制限に達しました。retry_after_seconds を参照してください。

json

{
  "error": {
    "code": "auth.token_invalid",
    "message": "Token invalid."
  },
  "request_id": "req_9a8b7c6d"
}

json

{
  "error": {
    "code": "rate_limit_exceeded",
    "message": "Rate limit exceeded for Silver tier (300 req/min). Wait 23s.",
    "retry_after_seconds": 23
  },
  "request_id": "req_1f2e3d4c"
}

はじめに

API キーを作成する

API Portal でスコープ付きのキーを生成・管理します。

API キーへ移動 →

Webhook を設定する

変更をポーリングする代わりに、イベントを購読します。

Webhook を設定 →

使用状況を監視する

レート制限に対するリクエスト量を追跡します。

使用状況を表示 →