MapEx Cargo API V1 Dokümantasyonu

Hızlı Başlangıç

Müşteri panelinizdeki API Entegrasyonu sayfasından bir API kaydı oluşturun. Size gösterilen API Key yalnızca bir kez görünür; bu değeri entegrasyon sisteminizde güvenli şekilde saklayın ve sunucu IP adresinizi whitelist alanına ekleyin.

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

Kimlik Doğrulama

Endpointler

Gönderi Oluşturma

Taşıyıcı kodu göndermeniz gerekmez. Sistem varış ülkesi, paket ölçüleri, toplam desi ve hesabınızın fiyat seviyesine göre uygun taşıyıcıyı otomatik seçer. Gönderi sisteme kaydedilir; AWB ve etiket işlemleri operasyon akışında ilerler.

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

Gönderilecek Alanlar

Takip ve Paket Görselleri

/v1/shipments/{shipment_no}/tracking cevabında takip ekranı için güvenli özet bilgiler summary, takip hareketleri events, varsa paket görselleri package_images alanında döner. Paket görseli URLlerini indirirken aynı X-Mapex-Client-Id ve X-Mapex-Api-Key headerlarını göndermelisiniz.

{
    "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_..."
}

Hata Formatı

{
  "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_..."
}

Kod Örnekleri

$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);

import requests

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

res = requests.post(
    "https://api.mapcargo.com.tr/v1/shipments",
    json=payload,
    headers={
        "X-Mapex-Client-Id": "mxcl_xxxxxxxxxxxxxxxx",
        "X-Mapex-Api-Key": "mxsk_xxxxxxxxxxxxxxxx",
        "Idempotency-Key": "cargo-10001",
    },
    timeout=20,
)
print(res.json())

using System.Net.Http;
using System.Text;

using var client = new HttpClient();
client.DefaultRequestHeaders.Add("X-Mapex-Client-Id", "mxcl_xxxxxxxxxxxxxxxx");
client.DefaultRequestHeaders.Add("X-Mapex-Api-Key", "mxsk_xxxxxxxxxxxxxxxx");
client.DefaultRequestHeaders.Add("Idempotency-Key", "cargo-10001");

var json = """
{
    "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"
}
""";

var response = await client.PostAsync(
    "https://api.mapcargo.com.tr/v1/shipments",
    new StringContent(json, Encoding.UTF8, "application/json")
);
var body = await response.Content.ReadAsStringAsync();

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

const response = await fetch("https://api.mapcargo.com.tr/v1/shipments", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "X-Mapex-Client-Id": "mxcl_xxxxxxxxxxxxxxxx",
    "X-Mapex-Api-Key": "mxsk_xxxxxxxxxxxxxxxx",
    "Idempotency-Key": "cargo-10001"
  },
  body: JSON.stringify(payload)
});

const data = await response.json();

OpenAPI

Makine tarafından okunabilir şema: https://api.mapcargo.com.tr/openapi.json