ডেভেলপার

তৈরি করুন MG Ship API-এর উপর

একটি সহজ, ভার্সনড REST API ব্যবহার করে রিয়েল-টাইম শিপমেন্ট ভিজিবিলিটি আপনার নিজস্ব সিস্টেমে নিয়ে আসুন।

ওভারভিউ

MG Ship API হলো একটি REST API যা HTTPS-এর উপর JSON রিটার্ন করে। এটি আপনার সিস্টেমকে শিপমেন্ট ভিজিবিলিটি ডেটায় প্রোগ্রামেটিক অ্যাক্সেস দেয় — লিস্টিং, সম্পূর্ণ শিপমেন্ট রেকর্ড এবং ট্র্যাকিং টাইমলাইন — যাতে আপনি মাইলস্টোনগুলো আপনার নিজস্ব TMS, ERP বা কাস্টমার পোর্টালে নিয়ে আসতে পারেন।

প্রতিটি এন্ডপয়েন্ট নিচের ভার্সনড বেস পাথের অধীনে থাকে। API-টি URL পাথে ভার্সন করা হয় (v1)। ব্রেকিং পরিবর্তনগুলো একটি নতুন পাথের অধীনে আসে (v2), যেখানে আগের ভার্সনের জন্য ১২ মাসের ডিপ্রিকেশন উইন্ডো থাকে, ফলে v1-এর বিপরীতে তৈরি কোনো ইন্টিগ্রেশন কাজ করতে থাকে।

বেস URL

আপনি যে এনভায়রনমেন্টের সাথে ইন্টিগ্রেট করছেন তার জন্য বেস URL বেছে নিন। নিচের প্রতিটি এন্ডপয়েন্ট পাথ এর সাপেক্ষে রিলেটিভ। Staging এবং Test (VPS) ডেভেলপমেন্ট ও টেস্টিংয়ের জন্য; Production শুধুমাত্র লাইভ key দিয়ে ব্যবহার করুন।

এনভায়রনমেন্ট	বেস 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 key দিয়ে অথেন্টিকেট করুন। key প্রতি tenant অনুযায়ী API Portal থেকে ইস্যু করা হয়, তৈরির সময় শুধু একবারই দেখানো হয়, সুনির্দিষ্ট স্কোপ বহন করে (উদাহরণস্বরূপ shipments.read), এবং যেকোনো সময় রোটেট বা রিভোক করা যায়।

key সর্বদা সার্ভার-সাইডে রাখুন — কখনো ব্রাউজার বা মোবাইল কোডে পাঠাবেন না। কোনো key এক্সপোজ হলে, API Portal থেকে এটি রোটেট করুন এবং পুরোনো key সঙ্গে সঙ্গে কাজ করা বন্ধ করে দেয়।

bash

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

কনভেনশন

Pagination

List এন্ডপয়েন্টগুলো cursor-paginated। একটি পেজের আকার নির্ধারণ করতে limit পাস করুন (১–১০০, ডিফল্ট ২০)। আরও রেজাল্ট থাকলে রেসপন্স has_more কে true সেট করে এবং next_cursor রিটার্ন করে; পরবর্তী পেজ আনতে এটিকে cursor কোয়েরি প্যারামিটার হিসেবে ফেরত পাঠান। Cursor অপাক — এগুলোকে একটি টোকেন হিসেবে গণ্য করুন, নিজে তৈরি করবেন না।

Rate limit

রিকোয়েস্টগুলো আপনার অ্যাকাউন্ট tier-এর ভিত্তিতে প্রতি মিনিটে rate-limited হয়। প্রতিটি রেসপন্সে X-RateLimit-Limit, X-RateLimit-Remaining এবং X-RateLimit-Reset (উইন্ডো রিসেট হতে কত সেকেন্ড) হেডারগুলো থাকে। লিমিট অতিক্রম করলে বডিতে একটি retry_after_seconds মান সহ 429 রিটার্ন করে। অনুরোধে আলাদা key-কে আরও উচ্চ সিলিং দেওয়া যেতে পারে।

Tier	রিকোয়েস্ট / মিনিট
Bronze	৬০
Silver	৩০০
Gold	১,০০০
Platinum	৫,০০০
Enterprise	আনলিমিটেড

Idempotency

Write এন্ডপয়েন্ট (যেমন POST /shipments) এর জন্য একটি Idempotency-Key হেডার প্রয়োজন। একই key দিয়ে কোনো রিকোয়েস্ট পুনরায় চেষ্টা করলে একটি ডুপ্লিকেট তৈরি না করে মূল ফলাফলটি রিটার্ন করে, তাই একটি নেটওয়ার্ক রিট্রাই সর্বদা নিরাপদ। রিড-অনলি (GET) এন্ডপয়েন্টের এটির প্রয়োজন নেই।

এন্ডপয়েন্ট

GET/health

আপনার key কাজ করছে কিনা যাচাই করুন এবং আপনার বর্তমান tier ও rate-limit স্ট্যাটাস দেখুন। কানেক্টিভিটি যাচাই করার একটি হালকা কল।

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 slug)।
`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

আপনার শিপমেন্টগুলো তালিকাভুক্ত করুন, সবচেয়ে নতুনগুলো প্রথমে, cursor pagination ও ঐচ্ছিক ফিল্টার সহ।

প্যারামিটার	টাইপ	বিবরণ
`limit`	integer	১–১০০, ডিফল্ট ২০।
`cursor`	string	আগের কোনো পেজ থেকে আসা অপাক cursor।
`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 (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

শিপমেন্টের উৎস ও গন্তব্যে বর্তমান/পূর্বাভাস আবহাওয়া (Open-Meteo) পান। অন-ডিমান্ড এনরিচমেন্ট, প্রায় ৩০ মিনিট ক্যাশ করা; কোনো লেগের অবস্থান নির্ণয় করা না গেলে সেটি null হয়।

প্যারামিটার	টাইপ	বিবরণ
`id`*	integer	শিপমেন্ট id (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

শিপমেন্টের উৎস ও গন্তব্যের কাছে (গত 7 days-এ 100 km-এর মধ্যে) সংঘাত / নাগরিক অস্থিরতার ঘটনাগুলো পান। ক্যাশ করা প্রোভাইডার ফলাফল সহ অন-ডিমান্ড এনরিচমেন্ট।

প্যারামিটার	টাইপ	বিবরণ
`id`*	integer	শিপমেন্ট id (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

একটি শিপমেন্টের কমপ্যাক্ট ট্র্যাকিং টাইমলাইন (ক্রমানুসারে মাইলস্টোন ইভেন্ট) পান।

প্যারামিটার	টাইপ	বিবরণ
`id`*	integer	শিপমেন্ট id (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

পোল করার পরিবর্তে, কিছু ঘটলে নোটিফিকেশন পেতে webhook-এ সাবস্ক্রাইব করুন — উদাহরণস্বরূপ যখন কোনো শিপমেন্ট কোনো এক্সসেপশনে পড়ে। আপনি API Portal-এ এন্ডপয়েন্ট URL কনফিগার করেন এবং ইভেন্ট টাইপ নির্বাচন করেন, এবং আমরা প্রতিটি ইভেন্টের জন্য আপনার URL-এ একটি JSON পেলোড POST করি।

প্রতিটি ডেলিভারি সাইন করা থাকে যাতে আপনি যাচাই করতে পারেন এটি আমাদের কাছ থেকে এসেছে। আমরা সিগনেচার পাঠাই X-MGS-Signature হেডারে, ইভেন্ট টাইপ X-MGS-Event-এ, এবং একটি ইউনিক ডেলিভারি id X-MGS-Delivery-Id-এ (আপনার হ্যান্ডলারকে idempotent করতে এটি পুনঃব্যবহার করুন)। ডেলিভারিগুলো ২৪ ঘণ্টা ধরে এক্সপোনেনশিয়াল ব্যাকঅফ সহ রিট্রাই করা হয়।

X-MGS-Signature-এর রূপ t=<timestamp>,v1=<signature>, যেখানে signature হলো "<timestamp>.<raw-request-body>" স্ট্রিংয়ের hex HMAC-SHA256, যা আপনার এন্ডপয়েন্ট সিক্রেট দিয়ে keyed। যাচাই করতে: t ও v1 আলাদা করুন, timestamp, একটি লিটারাল ডট এবং হুবহু raw বডির উপর HMAC পুনরায় গণনা করুন, এবং তুলনা করুন। মিল না হলে বা timestamp খুব পুরোনো হলে রিজেক্ট করুন।

http

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

এরর

এররগুলো স্ট্যান্ডার্ড HTTP স্ট্যাটাস কোড এবং একটি সামঞ্জস্যপূর্ণ JSON এনভেলপ ব্যবহার করে। error অবজেক্ট সর্বদা একটি স্থিতিশীল code এবং একটি মানুষ-পাঠযোগ্য message বহন করে; কিছু এরর কনটেক্সট ফিল্ড যুক্ত করে। প্রতিটি রেসপন্সে একটি request_id থাকে — সাপোর্টের সাথে যোগাযোগের সময় এটি উল্লেখ করুন।

স্ট্যাটাস	Code	কখন
400	`validation_error`	রিকোয়েস্ট বডিটি অনুপস্থিত বা অবৈধ (অথবা Idempotency-Key হেডারটি অনুপস্থিত)।
401	`auth.token_invalid`	অনুপস্থিত বা অবৈধ API key।
402	`shipment.overage_payment_required`	শিপমেন্ট কোটা শেষ হয়ে গেছে; প্রথমে বকেয়া ওভারেজ পরিশোধ করুন।
403	`auth.insufficient_scope`	key-এর প্রয়োজনীয় স্কোপ নেই, যেমন shipments.read।
403	`auth.tenant_suspended`	tenant অ্যাকাউন্টটি সক্রিয় নয়।
404	`shipment.not_found`	অনুরোধকৃত রিসোর্সটি বিদ্যমান নেই।
409	`shipment.duplicate`	এই ট্র্যাকিং নম্বর ও ক্যারিয়ার সহ একটি শিপমেন্ট ইতিমধ্যে বিদ্যমান।
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-এ স্কোপড key তৈরি ও পরিচালনা করুন।

API key-এ যান →

Webhook সেট আপ করুন

পরিবর্তনের জন্য পোল করার পরিবর্তে ইভেন্টে সাবস্ক্রাইব করুন।

Webhook কনফিগার করুন →

ব্যবহার মনিটর করুন

আপনার rate limit-এর বিপরীতে রিকোয়েস্ট ভলিউম ট্র্যাক করুন।

ব্যবহার দেখুন →