Разработчикам

Создавайте решения на API MG Ship

Получайте данные о видимости отгрузок в реальном времени в собственные системы через простой версионируемый REST API.

Обзор

MG Ship API — это REST API, возвращающий JSON по HTTPS. Он предоставляет вашим системам программный доступ к данным о видимости отгрузок — спискам, полным записям об отгрузках и хронологии отслеживания — чтобы вы могли передавать контрольные точки в собственную TMS, ERP или клиентский портал.

Каждый эндпоинт располагается по версионируемому базовому пути, указанному ниже. API версионируется в пути URL (v1). Несовместимые изменения выпускаются по новому пути (v2) с 12-месячным периодом прекращения поддержки предыдущей версии, поэтому интеграция, созданная для v1, продолжает работать.

Базовые URL

Выберите базовый URL для среды, с которой вы интегрируетесь. Каждый путь эндпоинта ниже указывается относительно него. Staging и Test (VPS) предназначены для разработки и тестирования; используйте Production только с рабочими ключами.

Среда	Базовый 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 ↓Скачать коллекцию Postman ↓

Аутентификация

Аутентифицируйте каждый запрос с помощью API-ключа, передаваемого как Bearer-токен в заголовке Authorization. Ключи выпускаются для каждого арендатора в API Portal, отображаются только один раз при создании, имеют явные области доступа (например, shipments.read) и могут быть в любой момент ротированы или отозваны.

Храните ключи на стороне сервера — никогда не размещайте их в коде браузера или мобильных приложений. Если ключ скомпрометирован, ротируйте его в API Portal, и старый ключ немедленно перестанет работать.

bash

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

Соглашения

Пагинация

Эндпоинты списков используют курсорную пагинацию. Передайте limit (1–100, по умолчанию 20), чтобы задать размер страницы. Когда есть дополнительные результаты, ответ устанавливает has_more в true и возвращает next_cursor; передайте его обратно как параметр запроса cursor, чтобы получить следующую страницу. Курсоры непрозрачны — обращайтесь с ними как с токеном, не формируйте их самостоятельно.

Лимиты частоты запросов

Запросы ограничиваются по частоте в минуту в зависимости от уровня вашей учётной записи. Каждый ответ включает заголовки X-RateLimit-Limit, X-RateLimit-Remaining и X-RateLimit-Reset (количество секунд до сброса окна). Превышение лимита возвращает 429 со значением retry_after_seconds в теле ответа. По запросу для отдельных ключей может быть установлен более высокий потолок.

Уровень	Запросов / мин
Bronze	60
Silver	300
Gold	1 000
Platinum	5 000
Enterprise	Без ограничений

Идемпотентность

Эндпоинты записи (такие как POST /shipments) требуют заголовок Idempotency-Key. Повтор запроса с тем же ключом возвращает исходный результат вместо создания дубликата, поэтому повтор после сетевого сбоя всегда безопасен. Эндпоинтам только для чтения (GET) он не нужен.

Эндпоинты

GET/health

Проверьте работоспособность ключа и узнайте свой текущий уровень и статус лимита частоты. Лёгкий вызов для проверки подключения.

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 или slug курьера AfterShip).
`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

Получите список ваших отгрузок, начиная с самых новых, с курсорной пагинацией и необязательными фильтрами.

Параметр	Тип	Описание
`limit`	integer	1–100, по умолчанию 20.
`cursor`	string	Непрозрачный курсор с предыдущей страницы.
`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	Идентификатор отгрузки (параметр пути).

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) в пункте отправления и назначения отгрузки. Обогащение по запросу, кэшируется ~30 мин; участок имеет значение null, если его местоположение не удаётся определить.

Параметр	Тип	Описание
`id`*	integer	Идентификатор отгрузки (параметр пути).

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

Получите события конфликтов / гражданских беспорядков вблизи пункта отправления и назначения отгрузки (в радиусе 100 km за последние 7 days). Обогащение по запросу с кэшированными результатами провайдера.

Параметр	Тип	Описание
`id`*	integer	Идентификатор отгрузки (параметр пути).

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	Идентификатор отгрузки (параметр пути).

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

Вебхуки

Вместо опроса подпишитесь на вебхуки, чтобы получать уведомления о происходящих событиях — например, когда по отгрузке возникает исключение. Вы настраиваете URL эндпоинтов и выбираете типы событий в API Portal, а мы отправляем POST-запрос с JSON-нагрузкой на ваш URL для каждого события.

Каждая доставка подписывается, чтобы вы могли проверить, что она пришла от нас. Мы отправляем подпись в заголовке X-MGS-Signature, тип события в X-MGS-Event и уникальный идентификатор доставки в X-MGS-Delivery-Id (используйте его повторно, чтобы сделать обработчик идемпотентным). Доставки повторяются с экспоненциальной задержкой в течение 24 часов.

X-MGS-Signature имеет вид t=<timestamp>,v1=<signature>, где signature — это шестнадцатеричный HMAC-SHA256 строки "<timestamp>.<raw-request-body>", вычисленный с ключом — секретом вашего эндпоинта. Чтобы проверить: выделите t и v1, заново вычислите HMAC по временной метке, литеральной точке и точному необработанному телу запроса и сравните. Отклоните, если значение не совпадает или временная метка слишком старая.

http

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

Ошибки

Ошибки используют стандартные коды состояния HTTP и единообразную JSON-оболочку. Объект ошибки всегда содержит стабильный код и понятное человеку сообщение; некоторые ошибки добавляют контекстные поля. Каждый ответ включает request_id — указывайте его при обращении в поддержку.

Статус	Код	Когда
400	`validation_error`	Тело запроса отсутствует или недействительно (либо отсутствует заголовок Idempotency-Key).
401	`auth.token_invalid`	Отсутствует или недействителен API-ключ.
402	`shipment.overage_payment_required`	Квота отгрузок исчерпана; сначала погасите задолженность за превышение.
403	`auth.insufficient_scope`	У ключа нет необходимой области доступа, например shipments.read.
403	`auth.tenant_suspended`	Учётная запись арендатора неактивна.
404	`shipment.not_found`	Запрашиваемый ресурс не существует.
409	`shipment.duplicate`	Отгрузка с этим номером отслеживания и перевозчиком уже существует.
429	`rate_limit_exceeded`	Превышен лимит частоты; см. 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-ключ

Создавайте ключи с ограниченными областями доступа и управляйте ими в API Portal.

Перейти к API-ключам →

Настройте вебхуки

Подписывайтесь на события вместо опроса изменений.

Настроить вебхуки →

Отслеживайте использование

Контролируйте объём запросов относительно вашего лимита частоты.

Посмотреть использование →