MapEx Cargo واجهة العملاء API V1

توثيق MapEx Cargo API V1

يمكنكم إنشاء الشحنات وقراءة التتبع وتنزيل الملصقات من نظام ERP أو التجارة الإلكترونية أو CRM أو WMS الخاص بكم.

طلبات API محمية عبر HTTPS و Client ID و API Key وقائمة IP المسموح بها وحدود الاستخدام. لا تشاركوا كلمة مرور لوحة التحكم مع أنظمة التكامل.

الرابط الأساسي

https://api.mapcargo.com.tr
V1خدمات الشحن والتتبع
JSONصيغة بيانات قياسية
PDFتنزيل الملصق

بداية سريعة

أنشئوا وصول API من صفحة API Entegrasyonu في لوحة العميل. يتم عرض API Key مرة واحدة فقط، لذلك يجب حفظه بأمان وإضافة عنوان IP الخاص بالخادم إلى القائمة البيضاء.

curl -X GET "https://api.mapcargo.com.tr/v1/ping"

التوثيق

Headerالشرح
X-Mapex-Client-IdClient ID الذي يتم إنشاؤه في صفحة API Entegrasyonu.
X-Mapex-Api-Keyمفتاح API السري الذي يظهر مرة واحدة فقط عند الإنشاء أو التجديد.
Idempotency-Keyإجباري فقط مع POST /v1/shipments. يمنع إنشاء شحنة مكررة عند إرسال نفس بيانات الشحن مرة أخرى.

النقاط

MethodPathالشرح
GET/v1/pingفحص حالة الخدمة.
POST/v1/shipmentsينشئ شحنة في حسابكم. يختار النظام الناقل تلقائياً حسب بلد الوجهة وأبعاد الطرود ومستوى السعر في الحساب.
GET/v1/shipmentsيعرض الشحنات التابعة لحسابكم.
GET/v1/shipments/{shipment_no}يعرض تفاصيل الشحنة.
GET/v1/shipments/{shipment_no}/trackingيعرض حركات التتبع وصور الطرود إن وجدت. نصوص التتبع العامة تستخدم عبارة الناقل بدلاً من اسم العلامة التشغيلية.
GET/v1/shipments/{shipment_no}/images/{image_id}يعرض صورة طرد. يجب طلب روابط الصور بنفس API headers.
GET/v1/shipments/{shipment_no}/labelيعرض ملصق الناقل إن وجد، وإلا يعرض ملصق PDF الافتراضي. ظهور الشعار في الملصق الافتراضي يتبع إعداد QR Etikette Logo في حساب العميل.
DELETE/v1/shipments/{shipment_no}يلغي فقط الشحنات التي حالتها created.

إنشاء شحنة

لا تحتاجون إلى إرسال كود الناقل. يختار النظام الناقل المناسب تلقائياً حسب بلد الوجهة وأبعاد الطرود والوزن الحجمي ومستوى السعر في حسابكم. يتم تسجيل الشحنة في النظام وتستمر عمليات AWB والملصق ضمن سير العمل التشغيلي.

مثال Payload

{
    "external_reference": "CARGO-10001",
    "origin_country": "TR",
    "destination_country": "AE",
    "shipment_type": "SALE",
    "valuation_currency": "USD",
    "sender": {
        "entity_type": "COMPANY",
        "company_name": "Sender Company",
        "contact_name": "Sender Name",
        "phone_country_code": "+90",
        "phone": "5551112233",
        "address_line1": "Istanbul warehouse",
        "country_code": "TR",
        "city": "Istanbul",
        "postal_code": "34000"
    },
    "recipient": {
        "entity_type": "PERSON",
        "full_name": "Receiver Name",
        "phone_country_code": "+971",
        "phone": "501112233",
        "email": "receiver@example.com",
        "address_line1": "Business Bay",
        "country_code": "AE",
        "city": "Dubai",
        "postal_code": "00000"
    },
    "packages": [
        {
            "quantity": 1,
            "length_cm": 30,
            "width_cm": 20,
            "height_cm": 10,
            "weight_kg": 2.5
        }
    ],
    "products": [
        {
            "product_name_en": "Cotton T-Shirt",
            "product_name_tr": "Pamuk Tişört",
            "hs_code": "610910",
            "origin_country": "TR",
            "quantity": 2,
            "unit_price": 12.5,
            "currency": "USD"
        }
    ],
    "note": "Test gönderisi"
}

حقول الطلب

اسم الحقل / النوعالشرحإجباريالقيود
external_reference (string)مرجع فريد في نظامكم لربط الشحنة بسجلاتكم.نعمحتى 120 حرفاً. يجب أن يكون فريداً لكل عميل.
origin_country (string)كود بلد الإرسال ISO-2.لاالقيمة الافتراضية في V1 هي TR.
destination_country (string)كود بلد الوصول ISO-2.نعمحرفان. مثال: AE, CA, US.
shipment_type (string)نوع الشحنة.لاالافتراضي SALE. القيم المقبولة: SALE, SAMPLE, GIFT, MICRO_EXPORT.
valuation_currency (string)عملة قيم المنتجات.لاالافتراضي USD. الأكواد المقبولة: USD - دولار أمريكي، EUR - يورو، GBP - جنيه إسترليني، CAD - دولار كندي، SAR - ريال سعودي.
note (string)ملاحظة تشغيلية.لايفضل ألا تتجاوز 500 حرف.
sender (object)بيانات المرسل.نعميتضمن حقول sender.*.
sender.entity_type (string)نوع المرسل.نعمإجباري. PERSON أو COMPANY.
sender.full_name (string)اسم المرسل الشخصي.حسب الحالةإجباري عندما يكون sender.entity_type هو PERSON. حتى 160 حرفاً.
sender.company_name (string)اسم شركة المرسل.حسب الحالةإجباري عندما يكون sender.entity_type هو COMPANY. حتى 180 حرفاً.
sender.contact_name (string)شخص الاتصال في الشركة.لاحتى 160 حرفاً.
sender.phone_country_code (string)كود دولة هاتف المرسل.لامثال: +90. حتى 10 أحرف.
sender.phone (string)رقم هاتف المرسل.نعمحتى 30 حرفاً.
sender.email (string)بريد المرسل.لايفضل صيغة بريد صحيحة.
sender.address_line1 (string)عنوان المرسل، السطر الأول.نعمحتى 190 حرفاً.
sender.address_line2/3 (string)أسطر عنوان إضافية.لاحتى 190 حرفاً لكل سطر.
sender.country_code (string)كود بلد المرسل.نعميجب أن يكون TR في V1.
sender.city (string)مدينة المرسل.نعمحتى 120 حرفاً.
sender.postal_code (string)الرمز البريدي للمرسل.لاحتى 20 حرفاً.
recipient (object)بيانات المستلم.نعميتضمن حقول recipient.*.
recipient.entity_type (string)نوع المستلم.نعمإجباري. PERSON أو COMPANY.
recipient.full_name (string)اسم المستلم الشخصي.حسب الحالةإجباري عندما يكون recipient.entity_type هو PERSON. حتى 160 حرفاً.
recipient.company_name (string)اسم شركة المستلم.حسب الحالةإجباري عندما يكون recipient.entity_type هو COMPANY. حتى 180 حرفاً.
recipient.contact_name (string)شخص الاتصال في الشركة.لاحتى 160 حرفاً.
recipient.phone_country_code (string)كود دولة هاتف المستلم.لامثال: +971 أو +1.
recipient.phone (string)رقم هاتف المستلم.نعمحتى 30 حرفاً.
recipient.email (string)بريد المستلم.لاليس إجبارياً لكل عميل.
recipient.address_line1 (string)عنوان المستلم، السطر الأول.نعمحتى 190 حرفاً.
recipient.address_line2/3 (string)أسطر عنوان إضافية.لاحتى 190 حرفاً لكل سطر.
recipient.country_code (string)كود بلد المستلم.نعميجب أن يطابق destination_country.
recipient.state_code/state_name (string)الولاية أو المنطقة.حسب الحالةيفضل في دول مثل US/CA.
recipient.city (string)مدينة المستلم.نعمحتى 120 حرفاً.
recipient.postal_code (string)الرمز البريدي للمستلم.لاقد يكون إجبارياً حسب بلد الوصول.
packages (array)قائمة الطرود/القطع.نعمحد أدنى 1 وحد أقصى 100 صف.
packages[].quantity (integer)عدد القطع بنفس الأبعاد والوزن.لاالافتراضي 1. الحد الأقصى 100.
packages[].length_cm / width_cm / height_cm (integer)أبعاد الطرد.نعمعدد صحيح موجب بالسنتيمتر.
packages[].weight_kg (decimal)وزن الطرد.نعمقيمة موجبة بالكيلوغرام. حتى 3 منازل عشرية.
products (array)قائمة المنتجات/المحتويات.نعمحد أدنى صف واحد.
products[].product_name_en / product_name_tr (string)اسم المنتج.نعمproduct_name_en إجباري. إذا لم يتم إرسال product_name_tr يتم استخدام product_name_en.
products[].hs_code (string)كود HS.نعميجب أن يحتوي على 4-20 رقماً. يفضل 6-12 رقماً.
products[].origin_country (string)بلد منشأ المنتج.لاالافتراضي TR. كود ISO-2.
products[].quantity (integer)كمية المنتج.نعمعدد صحيح موجب.
products[].unit_price (decimal)قيمة الوحدة.نعملا يتم قبول صفر. يجب أن تكون قيمة موجبة؛ يتم قبول 0.01.
products[].currency (string)عملة المنتج.نعمإجباري. الأكواد المقبولة: USD - دولار أمريكي، EUR - يورو، GBP - جنيه إسترليني، CAD - دولار كندي، SAR - ريال سعودي.

التتبع وصور الطرود

استجابة /v1/shipments/{shipment_no}/tracking ترجع ملخصاً آمناً في summary وحركات التتبع في events وصور الطرود في package_images عند توفرها. يجب تنزيل روابط الصور بنفس X-Mapex-Client-Id و X-Mapex-Api-Key.

{
    "ok": true,
    "shipment_no": "123456",
    "status": "in_transit",
    "tracking_number": "TRK123456789",
    "carrier_tracking_code": "TRK123456789",
    "summary": {
        "package_count": 2,
        "weight_kg": "47.00",
        "origin_country": "TR",
        "origin_country_name": "Turkey",
        "destination_country": "CA",
        "destination_country_name": "Canada",
        "recipient_name": "Ja*** AT*****"
    },
    "events": [
        {
            "event_time": "2026-07-06 14:20:00",
            "title": "Kayıt oluşturuldu",
            "title_tr": "Kayıt oluşturuldu",
            "title_en": "Shipment created",
            "subtitle": "Gönderi bilgileri taşıyıcıya API üzerinden iletildi.",
            "subtitle_tr": "Gönderi bilgileri taşıyıcıya API üzerinden iletildi.",
            "subtitle_en": "Shipment details were sent to the carrier through the API.",
            "location_text": "ISTANBUL TR",
            "location_country_code": "TR",
            "source": "SYSTEM",
            "carrier_tracking_no": "TRK123456789"
        }
    ],
    "package_images": [
        {
            "image_id": 127,
            "pack_no": 1,
            "image_type": "PACKAGE",
            "capture_method": "UPLOAD",
            "file_name": "123456-1-example.jpg",
            "file_ext": "jpg",
            "mime_type": "image/jpeg",
            "file_size_bytes": 424634,
            "image_width": 2200,
            "image_height": 1650,
            "is_primary": true,
            "url": "https://api.mapcargo.com.tr/v1/shipments/123456/images/127",
            "thumbnail_url": "https://api.mapcargo.com.tr/v1/shipments/123456/images/127?size=thumb",
            "created_at": "2026-07-06 14:25:00"
        }
    ],
    "request_id": "req_..."
}

صيغة الخطأ

{
  "ok": false,
  "error": {
    "code": "validation_failed",
    "message": "products.0.currency zorunludur ve şu kodlardan biri olmalıdır: USD, EUR, GBP, CAD, SAR.",
    "details": {
      "field": "products.0.currency",
      "message_tr": "products.0.currency zorunludur ve şu kodlardan biri olmalıdır: USD, EUR, GBP, CAD, SAR.",
      "message_en": "products.0.currency is required and must be one of these codes: USD, EUR, GBP, CAD, SAR.",
      "allowed_values": ["USD", "EUR", "GBP", "CAD", "SAR"],
      "allowed_currencies": {
        "USD": {"tr": "Amerikan Doları", "en": "US Dollar"},
        "EUR": {"tr": "Euro", "en": "Euro"},
        "GBP": {"tr": "İngiliz Sterlini", "en": "British Pound Sterling"},
        "CAD": {"tr": "Kanada Doları", "en": "Canadian Dollar"},
        "SAR": {"tr": "Suudi Arabistan Riyali", "en": "Saudi Riyal"}
      },
      "received": null
    }
  },
  "request_id": "req_..."
}
Statusالمعنى
400JSON فارغ أو غير صحيح.
401بيانات API ناقصة أو غير صحيحة.
403خطأ في قائمة IP المسموح بها أو وصول API غير نشط.
409تعارض في Idempotency أو حالة الشحنة.
422خطأ في التحقق من Payload.
429تم تجاوز حد الاستخدام.

أمثلة الكود

$payload = array (
  'external_reference' => 'CARGO-10001',
  'origin_country' => 'TR',
  'destination_country' => 'AE',
  'shipment_type' => 'SALE',
  'valuation_currency' => 'USD',
  'sender' => 
  array (
    'entity_type' => 'COMPANY',
    'company_name' => 'Sender Company',
    'contact_name' => 'Sender Name',
    'phone_country_code' => '+90',
    'phone' => '5551112233',
    'address_line1' => 'Istanbul warehouse',
    'country_code' => 'TR',
    'city' => 'Istanbul',
    'postal_code' => '34000',
  ),
  'recipient' => 
  array (
    'entity_type' => 'PERSON',
    'full_name' => 'Receiver Name',
    'phone_country_code' => '+971',
    'phone' => '501112233',
    'email' => 'receiver@example.com',
    'address_line1' => 'Business Bay',
    'country_code' => 'AE',
    'city' => 'Dubai',
    'postal_code' => '00000',
  ),
  'packages' => 
  array (
    0 => 
    array (
      'quantity' => 1,
      'length_cm' => 30,
      'width_cm' => 20,
      'height_cm' => 10,
      'weight_kg' => 2.5,
    ),
  ),
  'products' => 
  array (
    0 => 
    array (
      'product_name_en' => 'Cotton T-Shirt',
      'product_name_tr' => 'Pamuk Tişört',
      'hs_code' => '610910',
      'origin_country' => 'TR',
      'quantity' => 2,
      'unit_price' => 12.5,
      'currency' => 'USD',
    ),
  ),
  'note' => 'Test gönderisi',
);

$ch = curl_init("https://api.mapcargo.com.tr/v1/shipments");
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POST => true,
    CURLOPT_HTTPHEADER => [
        "Content-Type: application/json",
        "X-Mapex-Client-Id: mxcl_xxxxxxxxxxxxxxxx",
        "X-Mapex-Api-Key: mxsk_xxxxxxxxxxxxxxxx",
        "Idempotency-Key: cargo-10001",
    ],
    CURLOPT_POSTFIELDS => json_encode($payload, JSON_UNESCAPED_UNICODE | JSON_UNESCAPED_SLASHES),
]);

$response = curl_exec($ch);
$data = json_decode((string)$response, true);

OpenAPI

المخطط المقروء آلياً: https://api.mapcargo.com.tr/openapi.json