Developers

MG Ship API पर निर्माण करें

एक सरल, versioned REST API के साथ रियल-टाइम shipment visibility को अपने खुद के systems में लाएँ।

अवलोकन

MG Ship API एक REST API है जो HTTPS पर JSON लौटाता है। यह आपके systems को shipment visibility data तक programmatic access देता है — listings, पूर्ण shipment records, और tracking timelines — ताकि आप milestones को अपने खुद के TMS, ERP, या customer portal में ला सकें।

हर endpoint नीचे दिए गए versioned base path के अंतर्गत रहता है। API को URL path में versioned किया गया है (v1)। Breaking changes एक नए path (v2) के अंतर्गत आते हैं, जिसमें पिछले version के लिए 12 महीने की deprecation window होती है, इसलिए v1 के विरुद्ध बनाया गया integration काम करता रहता है।

बेस URL

जिस environment के विरुद्ध आप integrate कर रहे हैं उसके लिए base URL चुनें। नीचे दिया गया हर endpoint path इसके सापेक्ष (relative) है। Staging और Test (VPS) development और testing के लिए हैं; Production का उपयोग केवल live keys के साथ करें।

Environment	बेस 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 संग्रह डाउनलोड करें ↓

Authentication

हर request को एक API key के साथ authenticate करें जो Authorization header में Bearer token के रूप में भेजी जाती है। Keys प्रत्येक tenant के लिए API Portal से जारी की जाती हैं, केवल बनाते समय एक बार दिखाई जाती हैं, स्पष्ट scopes रखती हैं (उदाहरण के लिए shipments.read), और इन्हें किसी भी समय rotate या revoke किया जा सकता है।

Keys को server-side रखें — इन्हें कभी भी browser या mobile code में न भेजें। यदि कोई key उजागर हो जाए, तो उसे API Portal से rotate करें और पुरानी key तुरंत काम करना बंद कर देती है।

bash

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

Conventions

Pagination

List endpoints cursor-paginated होते हैं। पेज का आकार तय करने के लिए limit (1–100, default 20) पास करें। जब और results मौजूद होते हैं तो response has_more को true सेट करता है और next_cursor लौटाता है; अगला पेज लाने के लिए इसे cursor query parameter के रूप में वापस पास करें। Cursors opaque होते हैं — इन्हें एक token की तरह मानें, इन्हें खुद से न बनाएँ।

Rate limits

Requests को आपके account tier के आधार पर प्रति मिनट rate-limited किया जाता है। हर response में headers X-RateLimit-Limit, X-RateLimit-Remaining, और X-RateLimit-Reset (window के reset होने तक के सेकंड) शामिल होते हैं। Limit पार करने पर 429 लौटता है, जिसके body में retry_after_seconds value होती है। अनुरोध पर individual keys को एक उच्च ceiling दी जा सकती है।

Tier	Requests / min
Bronze	60
Silver	300
Gold	1,000
Platinum	5,000
Enterprise	Unlimited

Idempotency

Write endpoints (जैसे POST /shipments) के लिए एक Idempotency-Key header आवश्यक है। उसी key के साथ किसी request को पुनः प्रयास करने पर एक duplicate बनाने के बजाय मूल परिणाम लौटाया जाता है, इसलिए एक network retry हमेशा सुरक्षित है। Read-only (GET) endpoints को इसकी आवश्यकता नहीं है।

Endpoints

GET/health

जाँचें कि आपकी key काम करती है और अपना मौजूदा tier तथा rate-limit status देखें। connectivity verify करने के लिए एक lightweight call।

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

एक shipment रजिस्टर करें ताकि platform इसे ट्रैक करना शुरू कर दे। इसके लिए shipments.write scope और एक unique Idempotency-Key header आवश्यक है। यह shipment आपके plan के मासिक quota के विरुद्ध गिना जाता है।

Parameter	Type	Description
`Idempotency-Key`*	string (header)	प्रति request unique; उसी मान के साथ पुनः प्रयास करने पर एक duplicate बनाने के बजाय मूल shipment लौटाया जाता है।
`tracking_number`*	string	AWB / B-L / tracking number।
`carrier_code`*	string	Carrier या airline code (PCS code, IATA airline code, या AfterShip courier slug)।
`mode`*	string	परिवहन mode: 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

अपने shipments को सूचीबद्ध करें, नवीनतम पहले, cursor pagination और वैकल्पिक filters के साथ।

Parameter	Type	Description
`limit`	integer	1–100, default 20।
`cursor`	string	पिछले पेज से opaque cursor।
`status`	string	shipment status के आधार पर filter करें, उदाहरण के लिए in_transit।
`q`	string	shipment fields में full-text search।
`mode`	string	air, sea, rail, या road।
`carrier_code`	string	carrier के आधार पर filter करें, उदाहरण के लिए maersk।
`po`	string	purchase-order number के आधार पर filter करें।

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}

पूर्ण cargo विवरण और इसके milestone इतिहास के साथ एक single shipment प्राप्त करें।

Parameter	Type	Description
`id`*	integer	shipment id (path parameter)।

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

shipment के origin और destination पर वर्तमान/पूर्वानुमान मौसम (Open-Meteo) प्राप्त करें। मांग पर enrichment, ~30 मिनट तक cached; जब किसी leg की position resolve नहीं हो पाती तो वह null होता है।

Parameter	Type	Description
`id`*	integer	shipment id (path parameter)।

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

shipment के origin और destination के पास (पिछले 7 days में 100 km के भीतर) conflict / नागरिक अशांति की घटनाएँ प्राप्त करें। मांग पर enrichment, cached provider परिणामों के साथ।

Parameter	Type	Description
`id`*	integer	shipment id (path parameter)।

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

किसी shipment के लिए compact tracking timeline (क्रमबद्ध milestone events) प्राप्त करें।

Parameter	Type	Description
`id`*	integer	shipment id (path parameter)।

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"
  }
}

Webhooks

polling करने के बजाय, webhooks को subscribe करें ताकि जब कुछ घटित हो तो आपको सूचित किया जा सके — उदाहरण के लिए जब कोई shipment किसी exception से टकराए। आप API Portal में endpoint URLs configure करते हैं और event types चुनते हैं, और हम प्रत्येक event के लिए आपके URL पर एक JSON payload POST करते हैं।

हर delivery signed होती है ताकि आप verify कर सकें कि यह हमसे आई है। हम signature को X-MGS-Signature header में, event type को X-MGS-Event में, और एक unique delivery id को X-MGS-Delivery-Id में भेजते हैं (अपने handler को idempotent बनाने के लिए इसे दोबारा उपयोग करें)। Deliveries को 24 घंटों में exponential backoff के साथ retry किया जाता है।

X-MGS-Signature का स्वरूप t=<timestamp>,v1=<signature> होता है, जहाँ signature आपके endpoint secret के साथ keyed स्ट्रिंग "<timestamp>.<raw-request-body>" का hex HMAC-SHA256 होता है। verify करने के लिए: t और v1 को अलग करें, timestamp, एक literal dot, और सटीक raw body पर HMAC दोबारा compute करें, और तुलना करें। यदि यह मेल न खाए या timestamp बहुत पुराना हो तो reject करें।

http

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

Errors

Errors standard HTTP status codes और एक सुसंगत JSON envelope का उपयोग करते हैं। error object हमेशा एक stable code और एक human-readable message रखता है; कुछ errors context fields जोड़ते हैं। हर response में एक request_id शामिल होता है — support से संपर्क करते समय इसे उद्धृत करें।

Status	Code	कब
400	`validation_error`	Request body अनुपस्थित या अमान्य है (या Idempotency-Key header अनुपस्थित है)।
401	`auth.token_invalid`	API key अनुपस्थित या अमान्य है।
402	`shipment.overage_payment_required`	Shipment quota समाप्त हो गया; पहले बकाया overage का निपटान करें।
403	`auth.insufficient_scope`	Key में आवश्यक scope नहीं है, उदाहरण के लिए shipments.read।
403	`auth.tenant_suspended`	tenant account सक्रिय नहीं है।
404	`shipment.not_found`	अनुरोधित resource मौजूद नहीं है।
409	`shipment.duplicate`	इस tracking number और carrier के साथ एक shipment पहले से मौजूद है।
429	`rate_limit_exceeded`	Rate limit पार हुई; 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 key बनाएँ

API Portal में scoped keys generate और manage करें।

API keys पर जाएँ →

Webhooks सेट अप करें

बदलावों के लिए polling करने के बजाय events को subscribe करें।

Webhooks configure करें →

Usage पर नज़र रखें

अपने rate limit के सापेक्ष अपने request volume को track करें।

Usage देखें →