KolaySürec TMS
Entegrasyon API'si

Content-Type:       application/json
X-Idempotency-Key:  <uuid-v4>     // Önerilen — çift kayıt önler

{
  // ── Kimlik Doğrulama ─────────────────────────────────
  "company_code":      100001,                    // zorunlu — integer
  "api_key":           "ks_live_xxxxxxxxxxxx",     // zorunlu — string

  // ── Sipariş Bilgisi ───────────────────────────────────
  "tms_order_id":      "ORD-2025-001",            // zorunlu — sisteminizden benzersiz sipariş no
  "customer_email":    "musteri@firma.com",       // zorunlu — PIN e-postası buraya gider
  "scenario":          "DIRECT_ROAD",             // zorunlu — bkz. Senaryo Referansı
  "primary_asset_type": "TRAILER",               // opsiyonel — RORO senaryoları için

  // ── Araç Eşleştirme ──────────────────────────────────
  "assets": {
    "truck_plate":     "34 ABC 1234",             // opsiyonel — sistemdeki plaka ile eşleşir
    "trailer_plate":   "06 XYZ 5678",             // opsiyonel
    "driver_license":  "B-12345678"               // opsiyonel — ehliyet no ile eşleşir
  },

  // ── Zaman Planı ──────────────────────────────────────
  "schedule": {
    "start":           "2025-06-01T08:00:00Z",    // zorunlu — ISO 8601
    "end":             "2025-06-02T18:00:00Z"     // zorunlu — ISO 8601
  },

  // ── Adres Bilgisi ────────────────────────────────────
  "location": {
    "pickup_address":  "İstanbul, Türkiye",       // opsiyonel
    "delivery_address":"Ankara, Türkiye",         // opsiyonel
    "pickup_lat":      41.0082,                   // opsiyonel — ondalık derece
    "pickup_lng":      28.9784,                   // opsiyonel
    "delivery_lat":    39.9334,                   // opsiyonel
    "delivery_lng":    32.8597                    // opsiyonel
  },

  // ── Yük Bilgisi (Opsiyonel) ──────────────────────────
  "cargo": {
    "description":          "Otomotiv yedek parça",  // opsiyonel
    "weight_kg":            15000,                   // opsiyonel — kilogram
    "volume_m3":            45.5,                    // opsiyonel — metreküp
    "dangerous_goods":      false,                   // opsiyonel — ADR
    "temperature_controlled":false                   // opsiyonel — soğuk zincir
  }
}

{
  "order_id":     "clx8k2mn0000108l4gq9p1234",  // KolaySürec sipariş UUID'si
  "shipment_id":  "clx8k2mn0000208l4abc45678",  // Sevkiyat UUID'si
  "status":       "CONFIRMED",                  // Sipariş durumu
  "legs_created": 1,                           // Oluşturulan güzergah segmenti sayısı
  "issues":       ["truck_plate eşleşmedi"],   // Boşsa tüm araçlar eşleşti
  "idempotent":   false                        // true ise daha önce işlendi
}

{
  "code":       "TENANT_003",   // Makine tarafından okunabilir hata kodu
  "message":    "API key invalid", // İnsan tarafından okunabilir açıklama
  "statusCode": 401,            // HTTP durum kodu
  "timestamp":  "2025-06-01T10:00:00.000Z",
  "path":       "/api/v1/tms/sync"
}

curl -X POST "https://sandbox.kolaysurec.com/api/v1/tms/sync" \
  -H "Content-Type: application/json" \
  -H "X-Idempotency-Key: $(uuidgen)" \
  -d '{
    "company_code": 100001,
    "api_key": "your_api_key_here",
    "tms_order_id": "ORD-2025-001",
    "customer_email": "musteri@firma.com",
    "scenario": "DIRECT_ROAD",
    "assets": {
      "truck_plate": "34 ABC 1234",
      "trailer_plate": "06 XYZ 5678",
      "driver_license": "B-12345678"
    },
    "schedule": {
      "start": "2025-06-01T08:00:00Z",
      "end": "2025-06-02T18:00:00Z"
    },
    "location": {
      "pickup_address": "Gebze OSB, Kocaeli",
      "delivery_address": "OSTİM, Ankara"
    }
  }'

const response = await fetch('https://sandbox.kolaysurec.com/api/v1/tms/sync', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-Idempotency-Key': crypto.randomUUID(),
  },
  body: JSON.stringify({
    company_code:   100001,
    api_key:        process.env.KOLAYSUREC_API_KEY,
    tms_order_id:   'ORD-2025-001',
    customer_email: 'musteri@firma.com',
    scenario:       'DIRECT_ROAD',
    assets: {
      truck_plate:    '34 ABC 1234',
      trailer_plate:  '06 XYZ 5678',
      driver_license: 'B-12345678',
    },
    schedule: {
      start: '2025-06-01T08:00:00Z',
      end:   '2025-06-02T18:00:00Z',
    },
    location: {
      pickup_address:   'Gebze OSB, Kocaeli',
      delivery_address: 'OSTİM, Ankara',
    },
  }),
});

const data = await response.json();

if (data.issues.length === 0) {
  console.log('✓ Tam atama:', data.order_id);
} else {
  console.warn('⚠ Bekleyen atama, issues:', data.issues);
}

import requests, uuid, os

response = requests.post(
    "https://sandbox.kolaysurec.com/api/v1/tms/sync",
    headers={
        "Content-Type": "application/json",
        "X-Idempotency-Key": str(uuid.uuid4()),
    },
    json={
        "company_code":   100001,
        "api_key":        os.environ["KOLAYSUREC_API_KEY"],
        "tms_order_id":   "ORD-2025-001",
        "customer_email": "musteri@firma.com",
        "scenario":       "DIRECT_ROAD",
        "assets": {
            "truck_plate":    "34 ABC 1234",
            "trailer_plate":  "06 XYZ 5678",
            "driver_license": "B-12345678",
        },
        "schedule": {"start": "2025-06-01T08:00:00Z", "end": "2025-06-02T18:00:00Z"},
        "location": {
            "pickup_address": "Gebze OSB, Kocaeli",
            "delivery_address": "OSTİM, Ankara",
        },
    },
)

data = response.json()
print("order_id:", data["order_id"], "| issues:", data["issues"])

$payload = [
    'company_code'   => 100001,
    'api_key'        => $_ENV['KOLAYSUREC_API_KEY'],
    'tms_order_id'   => 'ORD-2025-001',
    'customer_email' => 'musteri@firma.com',
    'scenario'       => 'DIRECT_ROAD',
    'assets'         => ['truck_plate' => '34 ABC 1234', 'driver_license' => 'B-12345678'],
    'schedule'       => ['start' => '2025-06-01T08:00:00Z', 'end' => '2025-06-02T18:00:00Z'],
    'location'       => ['pickup_address' => 'Gebze OSB', 'delivery_address' => 'OSTİM Ankara'],
];

$ch = curl_init('https://sandbox.kolaysurec.com/api/v1/tms/sync');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POST           => true,
    CURLOPT_POSTFIELDS     => json_encode($payload),
    CURLOPT_HTTPHEADER     => [
        'Content-Type: application/json',
        'X-Idempotency-Key: ' . bin2hex(random_bytes(16)),
    ],
]);

$data = json_decode(curl_exec($ch), true);
echo $data['order_id'];