MapEx Cargo Customer API V1

MapEx Cargo API V1 Dokümantasyonu

Kendi ERP, e-ticaret veya WMS sisteminizden MapEx üzerinde gönderi oluşturabilir, takip bilgisini okuyabilir ve hazır etiketleri alabilirsiniz.

API istekleri HTTPS, Client ID, API Key, IP whitelist ve rate limit ile korunur. Panel giriş şifrenizi entegrasyon sistemleriyle paylaşmayın.

Base URL

https://api.mapcargo.com.tr
V1Gönderi ve takip servisleri
JSONStandart veri formatı
PDFEtiket indirme

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

HeaderAçıklama
X-Mapex-Client-IdAPI Entegrasyonu sayfanızda oluşturulan Client ID.
X-Mapex-Api-KeyOluşturma veya yenileme anında bir kez gösterilen gizli API anahtarı.
Idempotency-KeySadece POST /v1/shipments için zorunlu. Aynı siparişin tekrar gönderilmesi halinde çift gönderi oluşmasını engeller.

Endpointler

MethodPathAçıklama
GET/v1/pingServis sağlık kontrolü.
POST/v1/shipmentsMapEx hesabınızda yeni gönderi oluşturur. Varsayılan mod manual olarak çalışır.
GET/v1/shipmentsHesabınıza ait gönderileri listeler.
GET/v1/shipments/{shipment_no}Gönderi detayını döndürür.
GET/v1/shipments/{shipment_no}/trackingTakip olaylarını döndürür.
GET/v1/shipments/{shipment_no}/labelVarsa taşıyıcı etiketi, yoksa MapEx PDF etiketi döndürür.
DELETE/v1/shipments/{shipment_no}Sadece created durumundaki gönderiyi iptal eder.

Gönderi Oluşturma

service.dispatch_mode boş bırakılırsa manual kabul edilir. Size ayrıca yetki verilmediyse auto modunu kullanmayın.

{
    "external_reference": "ORDER-10001",
    "origin_country": "TR",
    "destination_country": "AE",
    "shipment_type": "SALE",
    "valuation_currency": "USD",
    "service": {
        "dispatch_mode": "manual",
        "carrier_code": "mapex-naqel"
    },
    "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"
}

Hata Formatı

{
  "ok": false,
  "error": {
    "code": "validation_failed",
    "message": "products en az 1 satır içermelidir.",
    "details": []
  },
  "request_id": "req_..."
}
StatusAnlam
400Boş veya hatalı JSON.
401Eksik veya geçersiz API kimliği.
403IP whitelist, pasif API kaydı veya auto AWB yetki hatası.
409Idempotency ya da gönderi durumu çakışması.
422Payload doğrulama hatası.
429Rate limit aşıldı.

Kod Örnekleri

cURL

curl -X POST "https://api.mapcargo.com.tr/v1/shipments" \
  -H "Content-Type: application/json" \
  -H "X-Mapex-Client-Id: mxcl_xxxxxxxxxxxxxxxx" \
  -H "X-Mapex-Api-Key: mxsk_xxxxxxxxxxxxxxxx" \
  -H "Idempotency-Key: order-10001" \
  --data '{
    "external_reference": "ORDER-10001",
    "origin_country": "TR",
    "destination_country": "AE",
    "shipment_type": "SALE",
    "valuation_currency": "USD",
    "service": {
        "dispatch_mode": "manual",
        "carrier_code": "mapex-naqel"
    },
    "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"
}'

PHP

$payload = array (
  'external_reference' => 'ORDER-10001',
  'origin_country' => 'TR',
  'destination_country' => 'AE',
  'shipment_type' => 'SALE',
  'valuation_currency' => 'USD',
  'service' => 
  array (
    'dispatch_mode' => 'manual',
    'carrier_code' => 'mapex-naqel',
  ),
  '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: order-10001",
    ],
    CURLOPT_POSTFIELDS => json_encode($payload, JSON_UNESCAPED_UNICODE | JSON_UNESCAPED_SLASHES),
]);
$response = curl_exec($ch);

JavaScript / Node

const payload = {
    "external_reference": "ORDER-10001",
    "origin_country": "TR",
    "destination_country": "AE",
    "shipment_type": "SALE",
    "valuation_currency": "USD",
    "service": {
        "dispatch_mode": "manual",
        "carrier_code": "mapex-naqel"
    },
    "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": "order-10001"
  },
  body: JSON.stringify(payload)
});
const data = await response.json();

Python

import requests

payload = {
    "external_reference": "ORDER-10001",
    "origin_country": "TR",
    "destination_country": "AE",
    "shipment_type": "SALE",
    "valuation_currency": "USD",
    "service": {
        "dispatch_mode": "manual",
        "carrier_code": "mapex-naqel"
    },
    "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": "order-10001",
    },
)
print(res.json())

C#

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", "order-10001");

var json = """
{
    "external_reference": "ORDER-10001",
    "origin_country": "TR",
    "destination_country": "AE",
    "shipment_type": "SALE",
    "valuation_currency": "USD",
    "service": {
        "dispatch_mode": "manual",
        "carrier_code": "mapex-naqel"
    },
    "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();

OpenAPI

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