Pembangun

Bina dengan API MG Ship

Tarik kebolehlihatan penghantaran masa nyata ke dalam sistem anda sendiri dengan API REST yang ringkas dan berversi.

Gambaran keseluruhan

API MG Ship ialah API REST yang memulangkan JSON melalui HTTPS. Ia memberikan sistem anda akses programatik kepada data kebolehlihatan penghantaran — senarai, rekod penghantaran penuh, dan garis masa penjejakan — supaya anda boleh menarik pencapaian penting ke dalam TMS, ERP, atau portal pelanggan anda sendiri.

Setiap titik akhir terletak di bawah laluan asas berversi di bawah. API ini berversi dalam laluan URL (v1). Perubahan yang memecahkan keserasian dihantar di bawah laluan baharu (v2) dengan tempoh penamatan 12 bulan untuk versi terdahulu, jadi integrasi yang dibina berdasarkan v1 terus berfungsi.

URL Asas

Pilih URL asas untuk persekitaran yang anda integrasikan. Setiap laluan titik akhir di bawah adalah relatif kepadanya. Staging dan Test (VPS) adalah untuk pembangunan dan pengujian; gunakan Production hanya dengan kunci langsung.

Persekitaran	URL Asas
Production	`https://api.mglobalship.com/api/v1/external`
Staging	`https://api.staging.mglobalship.com/api/v1/external`
Test (VPS)	`https://mgs.aipipis.com/api/v1/external`

Muat turun spesifikasi OpenAPI ↓Muat turun koleksi Postman ↓

Pengesahan

Sahkan setiap permintaan dengan kunci API yang dihantar sebagai token Bearer dalam pengepala Authorization. Kunci dikeluarkan setiap penyewa dari API Portal, ditunjukkan hanya sekali semasa penciptaan, membawa skop eksplisit (contohnya shipments.read), dan boleh diputar atau dibatalkan pada bila-bila masa.

Simpan kunci di sebelah pelayan — jangan sekali-kali menghantarnya dalam kod pelayar atau mudah alih. Jika sesuatu kunci terdedah, putarkannya dari API Portal dan kunci lama akan berhenti berfungsi serta-merta.

bash

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

Konvensyen

Penomboran halaman

Titik akhir senarai dinombor halaman menggunakan kursor. Hantar limit (1–100, lalai 20) untuk menentukan saiz halaman. Apabila lebih banyak hasil wujud, respons menetapkan has_more kepada true dan memulangkan next_cursor; hantarkannya semula sebagai parameter pertanyaan cursor untuk mendapatkan halaman seterusnya. Kursor adalah legap — anggapkannya sebagai token, jangan binanya sendiri.

Had kadar

Permintaan dihadkan kadar setiap minit berdasarkan tahap akaun anda. Setiap respons menyertakan pengepala X-RateLimit-Limit, X-RateLimit-Remaining, dan X-RateLimit-Reset (saat sehingga tetingkap ditetapkan semula). Melebihi had memulangkan 429 dengan nilai retry_after_seconds dalam badan. Kunci individu boleh diberikan siling yang lebih tinggi atas permintaan.

Tahap	Permintaan / min
Bronze	60
Silver	300
Gold	1,000
Platinum	5,000
Enterprise	Tanpa had

Keidempotenan

Titik akhir tulis (seperti POST /shipments) memerlukan pengepala Idempotency-Key. Mencuba semula permintaan dengan kunci yang sama akan mengembalikan hasil asal dan bukannya mencipta pendua, jadi percubaan semula rangkaian sentiasa selamat. Titik akhir baca sahaja (GET) tidak memerlukannya.

Titik akhir

GET/health

Semak bahawa kunci anda berfungsi dan lihat tahap semasa serta status had kadar anda. Panggilan ringan untuk mengesahkan kesambungan.

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

Daftarkan sesuatu penghantaran supaya platform mula menjejakinya. Memerlukan skop shipments.write dan pengepala Idempotency-Key yang unik. Penghantaran ini dikira terhadap kuota bulanan pelan anda.

Parameter	Jenis	Penerangan
`Idempotency-Key`*	string (header)	Unik bagi setiap permintaan; mencuba semula dengan nilai yang sama akan mengembalikan penghantaran asal dan bukannya mencipta pendua.
`tracking_number`*	string	Nombor AWB / B-L / penjejakan.
`carrier_code`*	string	Kod pembawa atau syarikat penerbangan (PCS code, IATA airline code, atau AfterShip courier slug).
`mode`*	string	Mod pengangkutan: sea, air, atau 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

Senaraikan penghantaran anda, terbaharu dahulu, dengan penomboran halaman kursor dan penapis pilihan.

Parameter	Jenis	Penerangan
`limit`	integer	1–100, lalai 20.
`cursor`	string	Kursor legap daripada halaman sebelumnya.
`status`	string	Tapis mengikut status penghantaran, cth. in_transit.
`q`	string	Carian teks penuh merentas medan penghantaran.
`mode`	string	udara, laut, kereta api, atau jalan raya.
`carrier_code`	string	Tapis mengikut pembawa, cth. maersk.
`po`	string	Tapis mengikut nombor pesanan belian.

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}

Dapatkan satu penghantaran dengan butiran kargo penuh dan sejarah pencapaian pentingnya.

Parameter	Jenis	Penerangan
`id`*	integer	ID penghantaran (parameter laluan).

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

Dapatkan cuaca semasa/ramalan (Open-Meteo) di asal dan destinasi penghantaran. Pengayaan atas permintaan, di-cache ~30 minit; sesuatu leg bernilai null apabila kedudukannya tidak dapat ditentukan.

Parameter	Jenis	Penerangan
`id`*	integer	ID penghantaran (parameter laluan).

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

Dapatkan peristiwa konflik / kekacauan awam berhampiran asal dan destinasi penghantaran (dalam lingkungan 100 km sepanjang 7 days lepas). Pengayaan atas permintaan dengan keputusan pembekal yang di-cache.

Parameter	Jenis	Penerangan
`id`*	integer	ID penghantaran (parameter laluan).

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

Dapatkan garis masa penjejakan padat (acara pencapaian penting yang tersusun) untuk sesuatu penghantaran.

Parameter	Jenis	Penerangan
`id`*	integer	ID penghantaran (parameter laluan).

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

Daripada melakukan tinjauan berkala, langgan webhook untuk dimaklumkan apabila sesuatu berlaku — contohnya apabila sesuatu penghantaran menemui pengecualian. Anda mengkonfigurasikan URL titik akhir dan memilih jenis acara dalam API Portal, dan kami POST muatan JSON ke URL anda untuk setiap acara.

Setiap penghantaran ditandatangani supaya anda boleh mengesahkan ia datang daripada kami. Kami menghantar tandatangan dalam pengepala X-MGS-Signature, jenis acara dalam X-MGS-Event, dan ID penghantaran unik dalam X-MGS-Delivery-Id (guna semula ia untuk menjadikan pengendali anda idempoten). Penghantaran dicuba semula dengan penangguhan eksponen selama 24 jam.

X-MGS-Signature mempunyai bentuk t=<timestamp>,v1=<signature>, di mana signature ialah HMAC-SHA256 heks bagi rentetan "<timestamp>.<raw-request-body>" yang dikunci dengan rahsia titik akhir anda. Untuk mengesahkan: pisahkan t dan v1, kira semula HMAC ke atas cap masa, satu titik literal, dan badan mentah yang tepat, dan bandingkan. Tolak jika ia tidak sepadan atau jika cap masa terlalu lama.

http

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

Ralat

Ralat menggunakan kod status HTTP standard dan sampul JSON yang konsisten. Objek ralat sentiasa membawa code yang stabil dan message yang boleh dibaca manusia; sesetengah ralat menambah medan konteks. Setiap respons menyertakan request_id — sebutkannya apabila menghubungi sokongan.

Status	Kod	Bila
400	`validation_error`	Badan permintaan hilang atau tidak sah (atau pengepala Idempotency-Key tiada).
401	`auth.token_invalid`	Kunci API hilang atau tidak sah.
402	`shipment.overage_payment_required`	Kuota penghantaran telah habis; selesaikan lebihan penggunaan tertunggak terlebih dahulu.
403	`auth.insufficient_scope`	Kunci tidak mempunyai skop yang diperlukan, cth. shipments.read.
403	`auth.tenant_suspended`	Akaun penyewa tidak aktif.
404	`shipment.not_found`	Sumber yang diminta tidak wujud.
409	`shipment.duplicate`	Penghantaran dengan nombor penjejakan dan pembawa ini sudah wujud.
429	`rate_limit_exceeded`	Had kadar dicapai; lihat 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"
}

Mula bekerja

Cipta kunci API

Jana dan urus kunci berskop dalam API Portal.

Pergi ke kunci API →

Sediakan webhook

Langgan acara dan bukannya melakukan tinjauan berkala untuk perubahan.

Konfigurasikan webhook →

Pantau penggunaan

Jejaki volum permintaan anda berbanding had kadar anda.

Lihat penggunaan →