Developer

Bangun di atas API MG Ship

Tarik visibilitas pengiriman secara real-time ke dalam sistem Anda sendiri dengan REST API yang sederhana dan berversi.

Ikhtisar

API MG Ship adalah REST API yang mengembalikan JSON melalui HTTPS. API ini memberi sistem Anda akses programatik ke data visibilitas pengiriman — daftar, catatan pengiriman lengkap, dan linimasa pelacakan — sehingga Anda dapat menarik milestone ke dalam TMS, ERP, atau portal pelanggan Anda sendiri.

Setiap endpoint berada di bawah base path berversi di bawah ini. API ini diberi versi pada path URL (v1). Perubahan yang merusak (breaking change) dirilis di bawah path baru (v2) dengan periode penghentian (deprecation) 12 bulan untuk versi sebelumnya, sehingga integrasi yang dibangun terhadap v1 tetap berfungsi.

Base URL

Pilih base URL untuk lingkungan tempat Anda melakukan integrasi. Setiap path endpoint di bawah ini bersifat relatif terhadapnya. Staging dan Test (VPS) untuk pengembangan dan pengujian; gunakan Production hanya dengan kunci live.

Lingkungan	Base URL
Produksi	`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`

Unduh spesifikasi OpenAPI ↓Unduh koleksi Postman ↓

Autentikasi

Autentikasikan setiap permintaan dengan kunci API yang dikirim sebagai token Bearer pada header Authorization. Kunci diterbitkan per tenant dari API Portal, hanya ditampilkan satu kali saat pembuatan, membawa scope eksplisit (misalnya shipments.read), dan dapat dirotasi atau dicabut kapan saja.

Simpan kunci di sisi server — jangan pernah menyertakannya dalam kode browser atau mobile. Jika sebuah kunci terekspos, rotasikan dari API Portal dan kunci lama akan langsung berhenti berfungsi.

bash

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

Konvensi

Paginasi

Endpoint daftar menggunakan paginasi berbasis cursor. Berikan limit (1–100, default 20) untuk menentukan ukuran halaman. Ketika masih ada hasil lain, respons mengatur has_more menjadi true dan mengembalikan next_cursor; kirimkan kembali sebagai parameter kueri cursor untuk mengambil halaman berikutnya. Cursor bersifat opaque — perlakukan sebagai token, jangan menyusunnya sendiri.

Batas laju

Permintaan dibatasi lajunya per menit berdasarkan tier akun Anda. Setiap respons menyertakan header X-RateLimit-Limit, X-RateLimit-Remaining, dan X-RateLimit-Reset (detik hingga jendela direset). Melampaui batas akan mengembalikan 429 dengan nilai retry_after_seconds pada body. Kunci individual dapat diberi batas atas yang lebih tinggi atas permintaan.

Tier	Permintaan / menit
Bronze	60
Silver	300
Gold	1.000
Platinum	5.000
Enterprise	Tak terbatas

Idempotensi

Endpoint penulisan (seperti POST /shipments) memerlukan header Idempotency-Key. Mencoba ulang permintaan dengan kunci yang sama akan mengembalikan hasil asli alih-alih membuat duplikat, sehingga percobaan ulang jaringan selalu aman. Endpoint hanya-baca (GET) tidak memerlukannya.

Endpoint

GET/health

Periksa bahwa kunci Anda berfungsi dan lihat tier saat ini serta status batas laju Anda. Panggilan ringan untuk memverifikasi konektivitas.

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 sebuah pengiriman agar platform mulai melacaknya. Memerlukan scope shipments.write dan header Idempotency-Key yang unik. Pengiriman ini dihitung terhadap kuota bulanan paket Anda.

Parameter	Tipe	Deskripsi
`Idempotency-Key`*	string (header)	Unik per permintaan; mencoba ulang dengan nilai yang sama akan mengembalikan pengiriman asli alih-alih membuat duplikat.
`tracking_number`*	string	Nomor AWB / B-L / pelacakan.
`carrier_code`*	string	Kode carrier atau airline (PCS code, IATA airline code, atau AfterShip courier slug).
`mode`*	string	Mode transportasi: 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

Tampilkan daftar pengiriman Anda, terbaru lebih dulu, dengan paginasi cursor dan filter opsional.

Parameter	Tipe	Deskripsi
`limit`	integer	1–100, default 20.
`cursor`	string	Cursor opaque dari halaman sebelumnya.
`status`	string	Filter berdasarkan status pengiriman, mis. in_transit.
`q`	string	Pencarian teks penuh di seluruh field pengiriman.
`mode`	string	air, sea, rail, atau road.
`carrier_code`	string	Filter berdasarkan carrier, mis. maersk.
`po`	string	Filter berdasarkan nomor purchase order.

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}

Ambil satu pengiriman beserta detail kargo lengkap dan riwayat milestone-nya.

Parameter	Tipe	Deskripsi
`id`*	integer	ID pengiriman (parameter path).

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 terkini/prakiraan (Open-Meteo) di titik asal dan tujuan pengiriman. Pengayaan on-demand, di-cache ~30 menit; sebuah leg bernilai null bila posisinya tidak dapat ditentukan.

Parameter	Tipe	Deskripsi
`id`*	integer	ID pengiriman (parameter path).

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 kejadian konflik / kerusuhan sipil di dekat titik asal dan tujuan pengiriman (dalam radius 100 km selama 7 days terakhir). Pengayaan on-demand dengan hasil provider yang di-cache.

Parameter	Tipe	Deskripsi
`id`*	integer	ID pengiriman (parameter path).

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 linimasa pelacakan ringkas (event milestone yang terurut) untuk sebuah pengiriman.

Parameter	Tipe	Deskripsi
`id`*	integer	ID pengiriman (parameter path).

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

Alih-alih melakukan polling, berlanggananlah webhook untuk diberi tahu ketika sesuatu terjadi — misalnya ketika sebuah pengiriman mengalami eksepsi. Anda mengonfigurasi URL endpoint dan memilih tipe event di API Portal, dan kami melakukan POST payload JSON ke URL Anda untuk setiap event.

Setiap pengiriman ditandatangani agar Anda dapat memverifikasi bahwa ia berasal dari kami. Kami mengirimkan tanda tangan pada header X-MGS-Signature, tipe event pada X-MGS-Event, dan id pengiriman unik pada X-MGS-Delivery-Id (gunakan kembali untuk membuat handler Anda idempoten). Pengiriman dicoba ulang dengan backoff eksponensial selama 24 jam.

X-MGS-Signature memiliki bentuk t=<timestamp>,v1=<signature>, di mana signature adalah HMAC-SHA256 heksadesimal dari string "<timestamp>.<raw-request-body>" yang di-key dengan secret endpoint Anda. Untuk memverifikasi: pisahkan t dan v1, hitung ulang HMAC atas timestamp, sebuah titik literal, dan raw body yang persis, lalu bandingkan. Tolak jika tidak cocok atau jika timestamp terlalu lama.

http

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

Kesalahan

Kesalahan menggunakan kode status HTTP standar dan amplop JSON yang konsisten. Objek error selalu membawa code yang stabil dan message yang dapat dibaca manusia; beberapa error menambahkan field konteks. Setiap respons menyertakan request_id — sertakan saat menghubungi dukungan.

Status	Kode	Kapan
400	`validation_error`	Body permintaan hilang atau tidak valid (atau header Idempotency-Key tidak ada).
401	`auth.token_invalid`	Kunci API hilang atau tidak valid.
402	`shipment.overage_payment_required`	Kuota pengiriman habis; selesaikan kelebihan pemakaian yang tertunggak terlebih dahulu.
403	`auth.insufficient_scope`	Kunci tidak memiliki scope yang diperlukan, mis. shipments.read.
403	`auth.tenant_suspended`	Akun tenant tidak aktif.
404	`shipment.not_found`	Sumber daya yang diminta tidak ada.
409	`shipment.duplicate`	Pengiriman dengan nomor pelacakan dan carrier ini sudah ada.
429	`rate_limit_exceeded`	Batas laju tercapai; 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"
}

Mulai

Buat kunci API

Hasilkan dan kelola kunci ber-scope di API Portal.

Buka kunci API →

Siapkan webhook

Berlangganan event alih-alih melakukan polling untuk perubahan.

Konfigurasikan webhook →

Pantau penggunaan

Lacak volume permintaan Anda terhadap batas laju Anda.

Lihat penggunaan →