Geliştiriciler

MG Ship API'si üzerinde geliştirme yapın

Basit ve sürümlenmiş bir REST API ile gerçek zamanlı sevkiyat görünürlüğünü kendi sistemlerinize aktarın.

Genel bakış

MG Ship API'si, HTTPS üzerinden JSON döndüren bir REST API'sidir. Sistemlerinize sevkiyat görünürlüğü verilerine — listelemeler, eksiksiz sevkiyat kayıtları ve takip zaman çizelgeleri — programatik erişim sağlar; böylece kilometre taşlarını kendi TMS, ERP veya müşteri portalınıza aktarabilirsiniz.

Her uç nokta, aşağıdaki sürümlenmiş temel yol altında yer alır. API, URL yolunda sürümlenir (v1). Geriye dönük uyumsuz değişiklikler, önceki sürüm için 12 aylık bir kullanımdan kaldırma süresiyle yeni bir yol (v2) altında yayınlanır; böylece v1'e göre oluşturulmuş bir entegrasyon çalışmaya devam eder.

Temel URL'ler

Entegre olduğunuz ortam için temel URL'yi seçin. Aşağıdaki her uç nokta yolu buna görelidir. Staging ve Test (VPS) geliştirme ve test içindir; Production'ı yalnızca canlı anahtarlarla kullanın.

Ortam	Temel URL
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`

OpenAPI spesifikasyonunu indir ↓Postman koleksiyonunu indir ↓

Kimlik doğrulama

Her isteği, Authorization başlığında Bearer belirteci olarak gönderilen bir API anahtarıyla doğrulayın. Anahtarlar, API Portal üzerinden kiracı bazında verilir, yalnızca oluşturulduğunda bir kez gösterilir, açık kapsamlar taşır (örneğin shipments.read) ve istenildiği zaman döndürülebilir veya iptal edilebilir.

Anahtarları sunucu tarafında tutun — bunları asla tarayıcı veya mobil kodda göndermeyin. Bir anahtar ifşa olursa, onu API Portal üzerinden döndürün; eski anahtar anında çalışmayı durdurur.

bash

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

Kurallar

Sayfalama

Listeleme uç noktaları, imleç (cursor) tabanlı sayfalama kullanır. Bir sayfanın boyutunu belirlemek için limit (1–100, varsayılan 20) değerini iletin. Daha fazla sonuç olduğunda yanıt has_more değerini true olarak ayarlar ve next_cursor döndürür; bir sonraki sayfayı almak için bunu cursor sorgu parametresi olarak geri iletin. İmleçler şeffaf değildir — bunları bir belirteç olarak ele alın, kendiniz oluşturmayın.

Hız sınırları

İstekler, hesap kademenize göre dakika başına hız sınırına tabidir. Her yanıt X-RateLimit-Limit, X-RateLimit-Remaining ve X-RateLimit-Reset (pencere sıfırlanana kadarki saniye) başlıklarını içerir. Sınırı aşmak, gövdede bir retry_after_seconds değeriyle birlikte 429 döndürür. İstek üzerine münferit anahtarlara daha yüksek bir tavan verilebilir.

Kademe	İstek / dk
Bronze	60
Silver	300
Gold	1.000
Platinum	5.000
Enterprise	Sınırsız

Idempotency

Yazma uç noktaları (POST /shipments gibi) bir Idempotency-Key başlığı gerektirir. Bir isteği aynı anahtarla yeniden denemek, bir kopya oluşturmak yerine orijinal sonucu döndürür; bu nedenle bir ağ yeniden denemesi her zaman güvenlidir. Yalnızca okumaya yönelik (GET) uç noktaların buna ihtiyacı yoktur.

Uç noktalar

GET/health

Anahtarınızın çalıştığını kontrol edin ve mevcut kademenizi ile hız sınırı durumunuzu görün. Bağlantıyı doğrulamak için hafif bir çağrı.

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

Platformun takibe başlaması için bir sevkiyat kaydedin. shipments.write kapsamını ve benzersiz bir Idempotency-Key başlığını gerektirir. Sevkiyat, planınızın aylık kotasından düşülür.

Parametre	Tür	Açıklama
`Idempotency-Key`*	string (header)	Her istek için benzersiz; aynı değerle yeniden denemek, bir kopya oluşturmak yerine orijinal sevkiyatı döndürür.
`tracking_number`*	string	AWB / B-L / takip numarası.
`carrier_code`*	string	Taşıyıcı veya havayolu kodu (PCS kodu, IATA havayolu kodu veya AfterShip kurye slug'ı).
`mode`*	string	Taşıma modu: sea, air veya 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

Sevkiyatlarınızı en yeniden başlayarak, imleç tabanlı sayfalama ve isteğe bağlı filtrelerle listeleyin.

Parametre	Tür	Açıklama
`limit`	integer	1–100, varsayılan 20.
`cursor`	string	Önceki bir sayfadan gelen şeffaf olmayan imleç.
`status`	string	Sevkiyat durumuna göre filtreleyin, örn. in_transit.
`q`	string	Sevkiyat alanları genelinde tam metin araması.
`mode`	string	air, sea, rail veya road.
`carrier_code`	string	Taşıyıcıya göre filtreleyin, örn. maersk.
`po`	string	Satın alma siparişi numarasına göre filtreleyin.

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}

Eksiksiz kargo ayrıntıları ve kilometre taşı geçmişiyle birlikte tek bir sevkiyatı alın.

Parametre	Tür	Açıklama
`id`*	integer	Sevkiyat kimliği (yol parametresi).

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

Sevkiyatın çıkış ve varış noktasındaki güncel/tahmini hava durumunu (Open-Meteo) alın. Talep üzerine zenginleştirme, ~30 dk önbelleğe alınır; konumu çözülemeyen bir bacak null olur.

Parametre	Tür	Açıklama
`id`*	integer	Sevkiyat kimliği (yol parametresi).

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

Sevkiyatın çıkış ve varış noktası yakınındaki (son 7 days içinde 100 km dahilinde) çatışma / sivil kargaşa olaylarını alın. Önbelleğe alınmış sağlayıcı sonuçlarıyla talep üzerine zenginleştirme.

Parametre	Tür	Açıklama
`id`*	integer	Sevkiyat kimliği (yol parametresi).

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

Bir sevkiyat için derli toplu takip zaman çizelgesini (sıralı kilometre taşı olayları) alın.

Parametre	Tür	Açıklama
`id`*	integer	Sevkiyat kimliği (yol parametresi).

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'lar

Sorgulama yapmak yerine, bir şey olduğunda — örneğin bir sevkiyat bir istisnayla karşılaştığında — bilgilendirilmek için webhook'lara abone olun. API Portal üzerinden uç nokta URL'lerini yapılandırır ve olay türlerini seçersiniz; her olay için URL'nize bir JSON yükü POST ederiz.

Her teslimat, bizden geldiğini doğrulayabilmeniz için imzalanır. İmzayı X-MGS-Signature başlığında, olay türünü X-MGS-Event başlığında ve benzersiz bir teslimat kimliğini X-MGS-Delivery-Id başlığında göndeririz (işleyicinizi idempotent yapmak için bunu yeniden kullanın). Teslimatlar, 24 saat boyunca üstel geri çekilme ile yeniden denenir.

X-MGS-Signature şu biçime sahiptir: t=<timestamp>,v1=<signature>; burada signature, uç nokta gizli anahtarınızla anahtarlanmış "<timestamp>.<raw-request-body>" dizesinin onaltılık HMAC-SHA256 değeridir. Doğrulamak için: t ve v1 değerlerini ayırın, HMAC'i zaman damgası, gerçek bir nokta ve tam ham gövde üzerinde yeniden hesaplayın ve karşılaştırın. Eşleşmezse veya zaman damgası çok eskiyse reddedin.

http

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

Hatalar

Hatalar, standart HTTP durum kodlarını ve tutarlı bir JSON zarfını kullanır. Hata nesnesi her zaman kararlı bir kod ve insan tarafından okunabilir bir mesaj taşır; bazı hatalar bağlam alanları ekler. Her yanıt bir request_id içerir — destekle iletişime geçerken bunu belirtin.

Durum	Kod	Ne zaman
400	`validation_error`	İstek gövdesi eksik veya geçersiz (ya da Idempotency-Key başlığı yok).
401	`auth.token_invalid`	Eksik veya geçersiz API anahtarı.
402	`shipment.overage_payment_required`	Sevkiyat kotası tükendi; önce bekleyen aşım tutarını ödeyin.
403	`auth.insufficient_scope`	Anahtar gerekli kapsamdan yoksun, örn. shipments.read.
403	`auth.tenant_suspended`	Kiracı hesabı etkin değil.
404	`shipment.not_found`	İstenen kaynak mevcut değil.
409	`shipment.duplicate`	Bu takip numarası ve taşıyıcıya sahip bir sevkiyat zaten mevcut.
429	`rate_limit_exceeded`	Hız sınırına ulaşıldı; retry_after_seconds değerine bakın.

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

Başlayın

Bir API anahtarı oluşturun

API Portal üzerinden kapsamı belirlenmiş anahtarları oluşturun ve yönetin.

API anahtarlarına git →

Webhook'ları kurun

Değişiklikleri sorgulamak yerine olaylara abone olun.

Webhook'ları yapılandır →

Kullanımı izleyin

İstek hacminizi hız sınırınıza karşı takip edin.

Kullanımı görüntüle →