MapEx Cargo API V1 Documentation

Create shipments, read tracking data, and retrieve labels from your ERP, e-commerce, CRM, or WMS system.

API requests are protected with HTTPS, Client ID, API Key, IP whitelist, and rate limits. Do not share your panel password with integration systems.

Base URL

https://api.mapcargo.com.tr

V1Shipment and tracking services

JSONStandard data format

PDFLabel download

Quick Start

Create an API access record from the API Integration page in your customer panel. The API Key is shown only once. Store it securely in your integration system and add your server IP address to the whitelist.

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

Authentication

Header	Description
`X-Mapex-Client-Id`	Client ID generated on your API Integration page.
`X-Mapex-Api-Key`	Secret API key shown only once during creation or regeneration.
`Idempotency-Key`	Required only for POST /v1/shipments. Prevents duplicate shipments when the same cargo data is submitted again.

Endpoints

Method	Path	Description
GET	`/v1/ping`	Service health check.
POST	`/v1/shipments`	Creates a shipment in your account. The system automatically selects a carrier by destination country, package dimensions, and your account price level.
GET	`/v1/shipments`	Lists shipments that belong to your account.
GET	`/v1/shipments/{shipment_no}`	Returns shipment details.
GET	`/v1/shipments/{shipment_no}/tracking`	Returns tracking events and package images, if available. Public tracking text uses carrier wording instead of operation brand wording.
GET	`/v1/shipments/{shipment_no}/images/{image_id}`	Returns a package image. Image URLs must also be requested with the same API headers.
GET	`/v1/shipments/{shipment_no}/label`	Returns a carrier label if available; otherwise returns the default PDF label. The logo on fallback labels follows the QR Label Logo setting on the customer account.
DELETE	`/v1/shipments/{shipment_no}`	Cancels only shipments in created status.

Create Shipment

You do not need to send a carrier code. The system automatically selects a suitable carrier based on destination country, package dimensions, total volumetric weight, and your account price level. The shipment is registered in the system; AWB and label operations continue through the operation flow.

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

Request Fields

Field name / type	Description	Required	Constraints
`external_reference (string)`	Unique reference in your integration system. Used to match the shipment with your own records.	Yes	Maximum 120 characters. Must be unique per customer.
`origin_country (string)`	Origin country ISO-2 code.	No	Default TR for V1.
`destination_country (string)`	Destination country ISO-2 code.	Yes	2 characters. Example: AE, CA, US.
`shipment_type (string)`	Shipment type.	No	Default SALE. Accepted values: SALE, SAMPLE, GIFT, MICRO_EXPORT.
`valuation_currency (string)`	Currency for product values.	No	Default USD. Accepted codes: USD - US Dollar, EUR - Euro, GBP - British Pound Sterling, CAD - Canadian Dollar, SAR - Saudi Riyal.
`note (string)`	Operation note.	No	Maximum 500 characters recommended.
`sender (object)`	Sender information.	Yes	Contains sender.* fields.
`sender.entity_type (string)`	Sender type.	Yes	Required. PERSON or COMPANY.
`sender.full_name (string)`	Person sender name.	Conditional	Required when sender.entity_type is PERSON. Maximum 160 characters.
`sender.company_name (string)`	Company sender name.	Conditional	Required when sender.entity_type is COMPANY. Maximum 180 characters.
`sender.contact_name (string)`	Company contact person.	No	Maximum 160 characters.
`sender.phone_country_code (string)`	Sender phone country code.	No	Example: +90. Maximum 10 characters.
`sender.phone (string)`	Sender phone number.	Yes	Maximum 30 characters.
`sender.email (string)`	Sender email address.	No	Valid email format recommended.
`sender.address_line1 (string)`	Sender address line 1.	Yes	Maximum 190 characters.
`sender.address_line2/3 (string)`	Additional address lines.	No	Maximum 190 characters each.
`sender.country_code (string)`	Sender country code.	Yes	Must be TR for V1.
`sender.city (string)`	Sender city.	Yes	Maximum 120 characters.
`sender.postal_code (string)`	Sender postal code.	No	Maximum 20 characters.
`recipient (object)`	Recipient information.	Yes	Contains recipient.* fields.
`recipient.entity_type (string)`	Recipient type.	Yes	Required. PERSON or COMPANY.
`recipient.full_name (string)`	Person recipient name.	Conditional	Required when recipient.entity_type is PERSON. Maximum 160 characters.
`recipient.company_name (string)`	Company recipient name.	Conditional	Required when recipient.entity_type is COMPANY. Maximum 180 characters.
`recipient.contact_name (string)`	Company contact person.	No	Maximum 160 characters.
`recipient.phone_country_code (string)`	Recipient phone country code.	No	Example: +971, +1.
`recipient.phone (string)`	Recipient phone number.	Yes	Maximum 30 characters.
`recipient.email (string)`	Recipient email address.	No	Not required for every customer.
`recipient.address_line1 (string)`	Recipient address line 1.	Yes	Maximum 190 characters.
`recipient.address_line2/3 (string)`	Additional address lines.	No	Maximum 190 characters each.
`recipient.country_code (string)`	Recipient country code.	Yes	Must match destination_country.
`recipient.state_code/state_name (string)`	State or region.	Conditional	Recommended for countries such as US/CA.
`recipient.city (string)`	Recipient city.	Yes	Maximum 120 characters.
`recipient.postal_code (string)`	Recipient postal code.	No	May be required by destination country.
`packages (array)`	Package/piece list.	Yes	Minimum 1, maximum 100 rows.
`packages[].quantity (integer)`	Number of pieces with the same dimensions and weight.	No	Default 1. Maximum 100.
`packages[].length_cm / width_cm / height_cm (integer)`	Package dimensions.	Yes	Positive integer in centimeters.
`packages[].weight_kg (decimal)`	Package weight.	Yes	Positive kg value. Maximum 3 decimals.
`products (array)`	Product/content list.	Yes	Minimum 1 row.
`products[].product_name_en / product_name_tr (string)`	Product name.	Yes	product_name_en is required. If product_name_tr is not sent, product_name_en is used.
`products[].hs_code (string)`	HS code.	Yes	Must contain 4-20 digits. 6-12 digits recommended.
`products[].origin_country (string)`	Product origin country.	No	Default TR. ISO-2 code.
`products[].quantity (integer)`	Product quantity.	Yes	Positive integer.
`products[].unit_price (decimal)`	Unit product value.	Yes	Zero is not accepted. Must be a positive number; 0.01 is accepted.
`products[].currency (string)`	Product currency.	Yes	Required. Accepted codes: USD - US Dollar, EUR - Euro, GBP - British Pound Sterling, CAD - Canadian Dollar, SAR - Saudi Riyal.

Tracking and Package Images

The /v1/shipments/{shipment_no}/tracking response returns safe tracking-page summary data in summary, tracking events in events, and package images in package_images when available. Package image URLs must be downloaded with the same X-Mapex-Client-Id and X-Mapex-Api-Key headers.

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

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

Status	Meaning
400	Empty or invalid JSON.
401	Missing or invalid API identity.
403	IP whitelist or inactive API access error.
409	Idempotency or shipment status conflict.
422	Payload validation error.
429	Rate limit exceeded.

Code Examples

$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

Machine-readable schema: https://api.mapcargo.com.tr/openapi.json