Kargofly API

Kargofly platformunu kendi sistemlerinize entegre edin. Siparişlerinizi yönetin, kargo takibi yapın ve webhook ile anlık bildirim alın.

Base URL: kargofly.com/api/v1Format: JSONProtokol: HTTPS

Hızlı Başlangıç

3 adımda API entegrasyonunu tamamlayın.

Token Üretin

Dashboard → Profil Ayarları sayfasına gidin, API Token bölümünden Token Üret butonuna tıklayın. Token yalnızca bir kez gösterilir, güvenli bir yerde saklayın.

İlk İsteği Gönderin

Header'a token'ı ekleyerek test edin:

curl -X GET https://kargofly.com/api/v1/orders \
  -H "Authorization: Bearer kf_live_xxxxx"

Yanıtı Değerlendirin

Tüm yanıtlar ok: true/false alanı içerir.

{
  "ok": true,
  "orders": [...],
  "total": 42,
  "page": 1,
  "pageSize": 20
}

Kimlik Doğrulama

Tüm API isteklerinde Bearer token kullanılır.

Authorization: Bearer kf_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Token yalnızca üretildiği an tam olarak gösterilir. Kaybedilirse yeni token üretmeniz gerekir — eski token geçersiz hale gelir.

Token Formatı

Alan	Açıklama
kf_live_	Sabit prefix
+32 karakter	Rastgele alfanümerik, URL-safe
Toplam 41 karakter	SHA-256 hash olarak saklanır, düz metin asla tutulmaz

Token Kapsamları

Kapsam	Yetki
orders:read	Siparişleri görüntüleme ve detay alma
orders:write	Sipariş oluşturma, güncelleme, silme ve barkod işlemleri
tracking:read	Kargo takip sorgulama
account:read	Bakiye, COD, markalar, adresler, depo bilgisi sorgulama
account:write	Marka ve adres ekleme
stock:read	Stok listesi ve detay sorgulama

Hatalı Token Yanıtı

{
  "ok": false,
  "error": "unauthorized",
  "message": "Geçersiz veya süresi dolmuş token."
}

Hız Limitleri

Kötüye kullanımı önlemek için dakika ve günlük limitler uygulanır.

Plan	İstek / dakika	İstek / gün
Standart	60	10.000
Pro Yakında	300	100.000

Limit aşıldığında 429 Too Many Requests döner. Retry-After header'ı kaç saniye beklemeniz gerektiğini belirtir.

Siparişler

GET/api/v1/ordersorders:read

Hesabınıza ait siparişleri sayfalı olarak döndürür. Durum, tarih aralığı ve arama ile filtrelenebilir.

Query Parametreleri

Parametre	Tip	Zorunlu	Açıklama
page	integer	—	Sayfa numarası. Varsayılan: 1
pageSize	integer	—	Sayfa başı kayıt. Min: 1, Maks: 100. Varsayılan: 20
status	string	—	`yeni` `hazir` `yolda` `teslim-edildi` `geri-dondu` `sorunlu`
startDate	string	—	ISO 8601 tarih. Örn: 2026-01-01
endDate	string	—	ISO 8601 tarih. Örn: 2026-12-31
search	string	—	Alıcı adı, telefon veya siparisId ile ara

curl -X GET "https://kargofly.com/api/v1/orders?page=1&pageSize=10&status=yolda" \
  -H "Authorization: Bearer kf_live_xxx"

Başarılı Yanıt 200 OK

{
  "ok": true,
  "orders": [
    {
      "id": "68abc123def456",
      "siparisId": "SHP-0007-A24BC2",
      "status": "yolda",
      "subStatus": "out_for_delivery",
      "carrier": "SURAT",
      "trackingNumber": "1234567890",
      "recipient": {
        "fullName": "Ahmet Yılmaz",
        "phone": "05XX XXX XX XX",
        "city": "İstanbul",
        "district": "Kadıköy"
      },
      "desi": 3.5,
      "shippingCostTL": "45.00",
      "isCOD": true,
      "collectionStatus": {
        "code": "value_date_waiting",
        "description": "Valör süresi işliyor.",
        "collectedTL": "1500.00",
        "serviceFeeTL": "112.00",
        "cardFeeTL": null,
        "cardUsed": null,
        "valueDateTotalDays": 7,
        "valueDateRemainingDays": 4,
        "transferredAt": null,
        "deliveredAt": "2026-07-03T14:05:00.000Z"
      },
      "brandName": "Marka Adı",
      "shopDomain": "magazam.myshopify.com",
      "source": "SHP",
      "createdAt": "2026-07-01T10:30:00.000Z"
    }
  ],
  "total": 142,
  "page": 1,
  "pageSize": 10,
  "totalPages": 15
}

GET/api/v1/orders/:idorders:read

Tek bir siparişin tüm detaylarını döndürür. :id parametresi MongoDB ObjectId veya siparisId olabilir.

curl -X GET "https://kargofly.com/api/v1/orders/SHP-0007-A24BC2" \
  -H "Authorization: Bearer kf_live_xxx"

Başarılı Yanıt 200 OK

{
  "ok": true,
  "order": {
    "id": "68abc123def456",
    "siparisId": "SHP-0007-A24BC2",
    "status": "yolda",
    "carrier": "SURAT",
    "trackingNumber": "1234567890",
    "recipient": {
      "fullName": "Ahmet Yılmaz",
      "phone": "05XX XXX XX XX",
      "email": "ahmet@ornek.com",
      "address": "Bağdat Cad. No:1 D:5",
      "city": "İstanbul",
      "district": "Kadıköy",
      "postalCode": "34710"
    },
    "desi": 3.5,
    "weight": 1.2,
    "shippingCostTL": "45.00",
    "isCOD": false,
    "codAmountTL": null,
    "brandName": "Marka Adı",
    "shopDomain": "magazam.myshopify.com",
    "source": "SHP",
    "note": "Kapıda bırakın",
    "createdAt": "2026-07-01T10:30:00.000Z",
    "updatedAt": "2026-07-02T08:15:00.000Z",
    "tracking": {
      "lastStatus": "yolda",
      "lastLocation": "İstanbul Dağıtım Merkezi",
      "lastUpdatedAt": "2026-07-02T07:00:00.000Z"
    }
  }
}

POST/api/v1/ordersorders:write

Yeni sipariş oluşturur. type alanıyla kargo veya depo tipi seçilir. Depo tipinde warehouseId ve her item için variantId veya sku zorunludur.

Request Body

Alan	Tip	Zorunlu	Açıklama
type	string	—	`cargo` (varsayılan) veya `depot`
receiver.name	string	✅	Alıcı adı soyadı
receiver.phone	string	—	Alıcı telefonu
receiver.city	string	✅	İl adı
receiver.district	string	✅	İlçe adı
receiver.neighborhood	string	—	Mahalle adı
receiver.addressLine	string	✅	Açık adres (min 8 karakter)
items	array	✅	Ürün listesi (en az 1)
items[].title	string	✅	Ürün adı
items[].quantity	integer	—	Adet. Varsayılan: 1
items[].sku	string	Depo ise ✅*	Ürün SKU kodu
items[].variantId	string	Depo ise ✅*	Shopify varyant ID (sayısal). * sku veya variantId ikisinden biri zorunlu
items[].price	string	—	Birim fiyat (TL)
carrier	string	—	Kargo firması kodu. Varsayılan: `surat`
cargoFeePayment	string	—	`sender` (varsayılan) veya `receiver`
cargoType	string	—	`outbound` (varsayılan) veya `inbound`
isCod	boolean	—	Kapıda ödeme. Varsayılan: false
codAmountTL	number	COD ise ✅	Kapıda tahsil edilecek tutar (TL)
warehouseId	string	Depo ise ✅	Depo ID — `GET /api/v1/account/warehouses` ile alın
brandId	string	—	Marka ID — `GET /api/v1/account/brands` ile alın
shopDomain	string	—	Bağlı mağaza domain (örn: magazam.myshopify.com). Verilmezse mağazasız oluşur.

Kargo Tipi Örnek

curl -X POST "https://kargofly.com/api/v1/orders" \
  -H "Authorization: Bearer kf_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "receiver": {
      "name": "Ayşe Demir",
      "phone": "05321234567",
      "city": "İstanbul",
      "district": "Kadıköy",
      "addressLine": "Bağdat Cad. No:1 D:5"
    },
    "items": [
      { "title": "Mavi Tişört L", "quantity": 2, "sku": "TSH-BLU-L" }
    ],
    "carrier": "surat",
    "isCod": false,
    "cargoFeePayment": "sender"
  }'

Depo Tipi Örnek

Önce GET /api/v1/account/warehouses ile warehouseId alın, ardından GET /api/v1/stock?type=depot ile ürünlerin variantId değerlerini öğrenin.

// POST /api/v1/orders — depo tipi
{
  "type": "depot",
  "warehouseId": "68abc111def222",
  "receiver": {
    "name": "Ahmet Yılmaz",
    "phone": "05321234567",
    "city": "Ankara",
    "district": "Çankaya",
    "addressLine": "Atatürk Bul. No:10 Daire:3"
  },
  "items": [
    {
      "title": "Mavi Tişört L",
      "quantity": 1,
      "variantId": "44123456789012",
      "sku": "TSH-BLU-L"
    }
  ],
  "carrier": "surat",
  "isCod": false
}

Başarılı Yanıt 201 Created

{
  "ok": true,
  "order": {
    "id": "68abc999fff111",
    "siparisId": "API-0007-X9Y2Z1",
    "type": "cargo",
    "status": "new"
  }
}

Olası Hata Yanıtları

{ "ok": false, "error": "missing_receiver_fields", "message": "receiver.name, city, district ve addressLine (min 8 karakter) zorunludur" }
{ "ok": false, "error": "missing_items" }
{ "ok": false, "error": "depot_items_require_sku_or_variant_id", "message": "Depo tipi siparişlerde her ürün için 'sku' veya 'variantId' zorunludur." }
{ "ok": false, "error": "depot_requires_warehouse_id", "message": "Depo tipi siparişlerde warehouseId zorunludur." }

PATCH/api/v1/orders/:idorders:write

Yalnızca yeni statüsündeki siparişleri günceller.

Güncellenebilir Alanlar

{
  "recipient": {
    "fullName": "Yeni Ad",
    "phone": "05321234567",
    "address": "Yeni Adres No:5",
    "cityCode": "34",
    "districtCode": "1234",
    "neighborhoodCode": "5678"
  },
  "desi": 4,
  "isCod": true,
  "codAmountTL": 299.90,
  "note": "Kapıda bırakın",
  "cargoFeePayment": "sender"
}

{ "ok": true, "order": { "id": "...", "status": "yeni", ... } }

DELETE/api/v1/orders/:idorders:write

Yalnızca yeni statüsündeki (barkod alınmamış) siparişleri kalıcı siler.

{ "ok": true }

POST/api/v1/orders/:id/barcodeorders:write

yeni → hazır. Kargo firmasına API çağrısı yapılır, barkod ve takip numarası döner.

{
  "ok": true,
  "barcodeNumber": "9876543210",
  "trackingNumber": "1234567890",
  "labelUrl": "https://kargofly.com/api/v1/orders/xxx/barcode/download",
  "status": "hazir"
}

DELETE/api/v1/orders/:id/barcodeorders:write

hazır → yeni. Kargo firmasına iptal bildirimi gönderilir.

{ "ok": true }

GET/api/v1/orders/:id/barcode/downloadorders:read

Kargo etiketi PDF döner. Content-Type: application/pdf

curl -X GET "https://kargofly.com/api/v1/orders/SHP-0007-A24BC2/barcode/download" \
  -H "Authorization: Bearer kf_live_xxx" \
  --output label.pdf

POST/api/v1/orders/:id/return-barcodeorders:write

teslim-edildi statüsündeki sipariş için iade barkodu oluşturur. Alıcı bu barkodla paketi geri gönderir.

{
  "ok": true,
  "returnBarcodeNumber": "1122334455",
  "returnLabelUrl": "https://kargofly.com/api/v1/orders/xxx/return-barcode/download"
}

DELETE/api/v1/orders/:id/return-barcodeorders:write

İade barkodunu iptal eder.

{ "ok": true }

POST/api/v1/orders/create-with-barcodeorders:write

Tek istekte sipariş oluşturur ve barkod alır. Request body POST /orders ile aynıdır. Barkod alınamazsa sipariş otomatik silinir (rollback).

{
  "ok": true,
  "order": {
    "id": "68abc999fff111",
    "siparisId": "API-0007-X9Y2Z1",
    "status": "hazir",
    "barcodeNumber": "9876543210",
    "trackingNumber": "1234567890",
    "labelUrl": "https://kargofly.com/api/v1/orders/xxx/barcode/download",
    "shippingCostTL": "38.50"
  }
}

Hesap

GET/api/v1/account/balanceaccount:read

Kullanıcının mevcut bakiyesini döndürür.

{ "ok": true, "balanceTL": "1250.75", "currency": "TRY" }

GET/api/v1/account/codaccount:read

Kapıda ödemeli siparişlerden bekleyen tahsilatların valör bazlı dağılımı.

{
  "ok": true,
  "breakdown": { "today": "0.00", "in1Day": "350.00", "in2Days": "1200.00", "in3Days": "800.00", "in4Days": "450.00" },
  "totalPendingTL": "2800.00",
  "currency": "TRY"
}

GET/api/v1/account/brandsaccount:read

Kayıtlı markaları listeler. status: approved · waiting · rejected

{
  "ok": true,
  "brands": [
    {
      "id": "68abc111aaa001",
      "name": "Marka Adı",
      "website": "https://markaadi.com",
      "status": "approved",
      "statusLabel": "Onaylandı",
      "isDefault": true,
      "platform": "manual",
      "logoUrl": null,
      "shopDomain": "markaadi.myshopify.com",
      "isDepotAccount": false,
      "createdAt": "2026-01-15T10:00:00.000Z"
    }
  ]
}

POST/api/v1/account/brandsaccount:write

Yeni marka ekler. Eklenen marka onay bekler (status: "waiting") — admin onayladıktan sonra sipariş oluşturmada kullanılabilir.

Alan	Tip	Zorunlu	Açıklama
name	string	✅	Marka adı (max 100 karakter)
website	string	—	Web sitesi URL
instagram	string	—	Instagram handle

{ "ok": true, "brand": { "id": "...", "name": "...", "status": "waiting", "statusLabel": "Onay Bekleniyor" } }

GET/api/v1/account/addressesaccount:read

Kayıtlı gönderici adreslerini listeler.

{
  "ok": true,
  "addresses": [
    { "id": "addr_001", "title": "Ana Depo", "phone": "02121234567", "city": "İstanbul", "district": "Kadıköy", "addressLine": "Bağdat Cad. No:1", "isDefault": true }
  ]
}

POST/api/v1/account/addressesaccount:write

Yeni gönderici adresi ekler (max 10).

Alan	Tip	Zorunlu	Açıklama
title	string	✅	Adres başlığı
phone	string	✅	Telefon numarası
city	string	✅	İl adı
district	string	✅	İlçe adı
addressLine	string	✅	Açık adres

{ "ok": true, "address": { "id": "...", "title": "...", "city": "İstanbul", "isDefault": false } }

GET/api/v1/account/warehousesaccount:read

Hesabınıza bağlı depo bilgisini döndürür. Depo tipi sipariş oluşturmak için gerekli warehouseId değerini buradan alın. Onaylı depo yoksa warehouse: null döner.

// Başarılı yanıt — onaylı depo bağlı
{
  "ok": true,
  "warehouse": {
    "warehouseId": "68abc111def222",
    "name": "İstanbul Depo A.Ş.",
    "city": "İstanbul",
    "district": "Bağcılar",
    "address": "Sanayi Mah. Depo Sok. No:5",
    "phone": "02121234567"
  }
}

// Depo bağlı değil veya henüz onaylanmadı
{ "ok": true, "warehouse": null }

Stok

Ürün stoklarını sorgulayın. Depo tipi sipariş oluşturmadan önce variantId değerlerini buradan öğrenin.

GET/api/v1/stockstock:read

Parametre	Tip	Açıklama
type	string	`cargo` (varsayılan) veya `depot`
shopDomain	string	Belirli bir mağazanın ürünlerini filtrele
inStock	boolean	`true` ise yalnızca stoku > 0 olan ürünler
search	string	Ürün adı, SKU veya variantId araması
page	integer	Sayfa (varsayılan: 1)
pageSize	integer	Maks: 100. Varsayılan: 20

curl -X GET "https://kargofly.com/api/v1/stock?type=depot&inStock=true" \
  -H "Authorization: Bearer kf_live_xxx"

{
  "ok": true,
  "stock": [
    {
      "stockId": "68abc111aaa001",
      "variantId": "44123456789012",
      "variantIdFull": "gid://shopify/ProductVariant/44123456789012",
      "sku": "TSH-BLU-L",
      "productName": "Mavi Tişört L",
      "quantity": 42,
      "available": true,
      "shopDomain": "magazam.myshopify.com",
      "imageUrl": "https://cdn.shopify.com/..."
    }
  ],
  "total": 87,
  "page": 1,
  "pageSize": 20,
  "totalPages": 5
}

GET/api/v1/stock/:stockIdstock:read

Tek ürünün stok durumunu döndürür. stockId, liste yanıtındaki stockId alanıdır (MongoDB ObjectId).

{
  "ok": true,
  "stockId": "68abc111aaa001",
  "variantId": "44123456789012",
  "sku": "TSH-BLU-L",
  "productName": "Mavi Tişört L",
  "quantity": 42,
  "available": true,
  "imageUrl": null
}

Yardımcı Veriler

Statik veriler — sık değişmez, istemci tarafında önbelleğe alınabilir.

GET/api/v1/helpers/carriers

Hesabınızın kullanabildiği kargo firmalarını listeler. Yalnızca size açık olanlar döner — listede olmayan bir firmayla sipariş oluşturamazsınız.

Alan	Açıklama
pricingMode	`tarife` → Kargofly tarifesi uygulanır. `kendi_cari` → kendi kargo anlaşmanızı kullanıyorsunuz; kargo ücretini kargo firmasına siz ödersiniz, bizden yalnızca sabit komisyon tahsil edilir.
codAvailable	Bu firmayla kapıda ödemeli gönderi yapabilir misiniz
receiverPayAvailable	Alıcı öder seçeneği açık mı
maxDesi	Kabul edilen üst desi sınırı. Aşarsanız `desi_limit` hatası döner.

{
  "ok": true,
  "carriers": [
    { "code": "surat", "name": "Sürat Kargo", "agreementName": "Sürat Kargo",
      "active": true, "pricingMode": "tarife", "codAvailable": true,
      "receiverPayAvailable": false, "maxDesi": 700 },
    { "code": "aras", "name": "Aras Kargo", "agreementName": "Aras Kargo",
      "active": true, "pricingMode": "tarife", "codAvailable": true,
      "receiverPayAvailable": false, "maxDesi": 700 },
    { "code": "hepsijet", "name": "Hepsijet", "agreementName": "Hepsijet",
      "active": true, "pricingMode": "tarife", "codAvailable": true,
      "receiverPayAvailable": false, "maxDesi": 40 },
    { "code": "kolaygelsin", "name": "KolayGelsin", "agreementName": "KolayGelsin",
      "active": true, "pricingMode": "kendi_cari", "codAvailable": false,
      "receiverPayAvailable": false, "maxDesi": 40 }
  ]
}

GET/api/v1/customers/searchorders:read

Daha önce gönderi yaptığınız alıcılar arasında arama yapar. Sipariş formunuzda isim yazıldıkça adres ve telefonu otomatik doldurmak için kullanın. Her alıcı bir kez döner; en son kullanılan adres esas alınır.

Parametre	Tip	Zorunlu	Açıklama
q	string	✅	Ad veya telefonda aranacak metin — en az 2 karakter
limit	number	—	Kaç alıcı dönsün. Varsayılan 10, en çok 50

GET /api/v1/customers/search?q=ahmet&limit=5

{
  "ok": true, "arama": "ahmet", "adet": 1,
  "musteriler": [
    {
      "ad": "Ahmet Yılmaz",
      "telefon": "05XXXXXXXXX",
      "adres": "İstiklal Cad. No:12 D:3",
      "adres2": "",
      "il": "İstanbul", "ilce": "Kadıköy", "mahalle": "Caferağa",
      "ilKodu": "34", "ilceKodu": "1234", "postaKodu": "34710",
      "sonSiparis": "2026-09-15T08:20:00.000Z"
    }
  ]
}

Yalnızca kendi siparişleriniz taranır. Başka bir hesabın alıcı bilgisi hiçbir koşulda dönmez.

GET/api/v1/helpers/payment-methods

{ "ok": true, "paymentMethods": [{ "code": "sender", "label": "Gönderici Öder" }, { "code": "receiver", "label": "Alıcı Öder" }] }

GET/api/v1/helpers/cities

Türkiye il listesi. İlçeler için /helpers/cities/:cityCode/districts, mahalleler için /helpers/cities/:cityCode/districts/:districtCode/neighborhoods

{ "ok": true, "cities": [{ "code": "34", "name": "İstanbul", "plateCode": "34" }] }

GET/api/v1/helpers/desiaccount:read

Parametre	Tip	Açıklama
carrier ✅	string	Kargo kodu
desi ✅	number	Desi değeri
cityCode	string	Hedef il kodu

{
  "ok": true, "carrier": "SURAT", "desi": 4, "lane": "outCity",
  "pricingMode": "tarife", "estimatedCostTL": "139.66",
  "usedRateRow": { "desi": 4, "fiyatTL": 139.66 },
  "note": "Kapıda ödeme ve depo ücreti hariçtir."
}

Bu uç yalnızca kargo ücretini döndürür. Kapıda ödeme, depo ücreti ve indirimler dahil net tutar için /api/v1/pricing/quote kullanın.

Fiyatlandırma

Sipariş oluşturmadan önce ne ödeyeceğinizi öğrenin.

GET/api/v1/pricing/quoteaccount:read

Bir gönderi için tam fiyat teklifi: kargo ücreti, indiriminiz, depo ücreti ve kapıda ödeme kalemleri. Panelde gördüğünüz tutarın aynısı hesaplanır.

Parametre	Tip	Zorunlu	Açıklama
carrier	string	✅	Kargo kodu — `/helpers/carriers` ile alın
desi	number	✅	Desi. Tam sayıya yuvarlanır (3,4 → 3 · 3,5 → 4)
lane	string	—	`inCity` (aynı il) veya `outCity`. Varsayılan `outCity`
cod	boolean	—	Kapıda ödemeli mi
codAmount	number	cod ise ✅	Tahsil edilecek tutar (TL)
card	boolean	—	Alıcı kartla ödeyecekse kart komisyonu da hesaplanır

{
  "ok": true,
  "carrier": "surat", "desi": 4, "lane": "outCity",
  "pricingMode": "tarife",
  "shippingTL": "139.66",       // indirim sonrası ödeyeceğiniz
  "listShippingTL": "139.66",   // indirimsiz liste fiyatı
  "discountTL": "0.00",         // size özel indirim
  "depotFeeTL": "0.00",
  "cod": {
    "amountTL": "1500.00",
    "serviceFeeTL": "112.00",   // kapıda ödeme hizmet bedeli
    "cardFeeTL": "67.50"        // alıcı kartla öderse
  },
  "totalTL": "319.16",
  "usedRateRow": { "desi": 4, "fiyatTL": 139.66 },
  "note": "Tahmini tutardır; barkod anında geçerli tarife uygulanır."
}

Kendi cari anlaşması kullananlar: pricingMode kendi_cari döner. Kargo ücretini kargo firmasına siz ödersiniz; shippingTL bizim sabit komisyonumuzdur, tarife fiyatı değildir. Kapıda ödeme kalemleri de çıkmaz.

Hata	Anlamı
carrier_not_configured	Bu firma hesabınıza açık değil (404)
desi_limit	Firmanın üst desi sınırı aşıldı (422)
rate_not_configured	Bu desi için tarifede fiyat yok (404)

GET/api/v1/pricing/tariffaccount:read

Bir firmanın desi bazlı fiyat tablosunun tamamı. Kendi fiyat hesabınızı kurmak veya müşterinize fiyat göstermek için tek seferde çekin.

GET /api/v1/pricing/tariff?carrier=hepsijet

{
  "ok": true,
  "carrier": "hepsijet",
  "pricingMode": "tarife",
  "maxDesi": 40,
  "extraDesiAboveThirtyTL": "0.00",   // 30 desi üstü her desi için ek
  "heavyCargo": null,                  // { minDesi, flatFeeTL } — varsa tek seferlik
  "rates": [
    { "desi": 1, "inCityTL": "119.79", "outCityTL": "119.79" },
    { "desi": 2, "inCityTL": "119.79", "outCityTL": "119.79" }
  ],
  "infoLines": ["..."],
  "note": "Müşteriye özel indirimler bu tabloya yansımaz."
}

Bu tablo liste fiyatıdır; size özel indirimler yansımaz. Ödeyeceğiniz net tutar için /api/v1/pricing/quote kullanın.

Webhook

Kargofly'daki olaylar gerçekleştiğinde belirlediğiniz URL'e otomatik POST isteği gönderilir.

Webhook kurmak için: Dashboard → Profil Ayarları → Webhook → URL ve event tipini seçerek ekleyin.

Event Tipleri

EVENTshipment.status_changedDurum değişikliği — basit bildirim

{
  "event": "shipment.status_changed",
  "timestamp": "2026-07-02T08:00:00.000Z",
  "data": {
    "siparisId": "SHP-0007-A24BC2",
    "status": "yolda",
    "previousStatus": "hazir",
    "location": "İstanbul Kadıköy Şubesi",
    "carrier": "SURAT",
    "trackingNumber": "1234567890"
  }
}

İmza Doğrulama

Her webhook isteğinde X-Kargofly-Signature header'ı gönderilir. Formül: sha256=HMAC-SHA256(webhookSecret, rawBody)

Node.js

Python

const crypto = require("crypto");

function verifySignature(rawBody, signature, secret) {
  const expected = "sha256=" + crypto
    .createHmac("sha256", secret)
    .update(rawBody)
    .digest("hex");
  return crypto.timingSafeEqual(
    Buffer.from(expected),
    Buffer.from(signature)
  );
}

Yeniden Deneme Politikası

Yanıt	Davranış
2xx	Başarılı — tekrar denenmez
4xx	Başarısız — tekrar denenmez (kalıcı hata)
5xx / Timeout	Başarısız — 3 kez yeniden denenir (1dk, 5dk, 30dk)

Endpoint'inizin 5 saniye içinde yanıt döndürmesi beklenir. Uzun işlemler için webhook'u asenkron işleyin.

Hata Kodları

HTTP	error	Açıklama
400	validation_error	Eksik veya hatalı parametre
401	unauthorized	Token eksik veya geçersiz
403	forbidden	Token bu işlem için yetkisiz (kapsam yetersiz)
404	not_found	Kayıt bulunamadı
409	conflict	Çakışma (örn: aynı sipariş tekrar oluşturuldu)
422	insufficient_balance	Yetersiz bakiye
422	carrier_unavailable	Kargo firması aktif değil
429	rate_limited	Hız limiti aşıldı
500	server_error	Sunucu hatası

Hata Yanıt Formatı

{
  "ok": false,
  "error": "validation_error",
  "message": "recipient.phone geçerli bir Türkiye telefon numarası olmalı."
}

Sipariş Durum Kodları

yeni✱Yeni — Sipariş alındı, henüz kargoya verilmedi

hazir📦Hazır — Kargo barkodu oluşturuldu, teslim bekleniyor

yolda🚚Yolda — Kargo firması teslim aldı, dağıtımda

teslim-edildi✅Teslim Edildi — Alıcıya ulaştı

geri-dondu🔄Geri Döndü — Alıcıya teslim edilemedi, geri döndü

sorunlu⚠️Sorunlu — Gecikme, kayıp veya hasar durumu

Notlar

Tüm para birimleri aksi belirtilmedikçe Türk Lirası (TL) cinsindendir.
Tarih/saat değerleri UTC olarak döner — 2026-07-02T08:00:00.000Z
Yanıtlardaki ok: true başarılı, ok: false hatalı isteği belirtir.

Alt Durum Kodları

subStatus alanı, yolda durumunun içindeki ayrıntıyı verir. Kargo firmasından böyle bir bilgi gelmemişse null döner.

Kod	Anlamı
out_for_delivery	Dağıtıma çıktı — bugün teslim edilecek
delayed	Gecikmeli
problem	Sorunlu — kargo firması bir engel bildirdi
needs_support	Destek gerekiyor — müdahale bekliyor
returning	Geri dönüyor — gönderici adresine yönlendirildi
lost	Kayıp

Tahsilat Durumları

Kapıda ödemeli siparişlerde collectionStatus.code alanı, tahsil edilen paranın hangi aşamada olduğunu söyler. Kapıda ödemesiz siparişte alanın tamamı null olur.

Kod	Anlamı
calculating	Teslimat bekleniyor; valör henüz başlamadı
value_date_waiting	Teslim edildi, valör süresi işliyor
early_use_available	Valör dolmadı ama ön kullanıma açık
bank_ready	Valör doldu, aktarım sırada
transferred	Tahsilat bakiyenize aktarıldı
uncollected	Gönderi teslim edilmedi — tahsilat yapılmadı
own_account	Tahsilat kendi kargo cari hesabınıza gider, Kargofly bakiyesine geçmez

cardFeeTL ve cardUsed alanları null ise, alıcının nakit mi kartla mı ödediği bilgisi kargo firmasından henüz gelmemiştir. Teslimattan sonra dolar.