Kargofly Depo API

Depo Hesabı

Kargofly Depo API ile depo siparişlerini yönetin, stok sorgulayın ve webhook ile anlık bildirim alın. Bu API yalnızca depo hesaplarına aittir — müşteri API için API Dokümantasyonu'na bakın.

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

Hızlı Başlangıç

3 adımda depo API entegrasyonu.

Token Üretin

Depo panelinizde Entegrasyonlar → Entegrasyon Ekle → API Token bölümünden token oluşturun.

İlk İsteği Gönderin

Bearer token ile depo sipariş listenizi çekin.

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 içerir.

{
  "ok": true,
  "orders": [...],
  "total": 14
}

Kimlik Doğrulama

Authorization: Bearer kf_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Token yalnızca üretildiği an tam olarak gösterilir. Kaybedilirse yeni token üretmeniz gerekir.

Kapsam	Yetki
`orders:read`	Depo siparişlerini görüntüle
`orders:write`	Sipariş durumu güncelle
`tracking:read`	Kargo takip sorgula
`stock:read`	Depo stok sorgula
`warehouse:read`	Bakiye, kazanç, fatura sorguları

Hız Limitleri

Plan	İstek / dakika	İstek / gün
Standart	60	10.000

Limit aşımında 429 Too Many Requests + Retry-After header döner.

Siparişler

GET/api/v1/ordersorders:read

Depo hesabınıza bağlı siparişleri listeler.

Parametre	Tip	Açıklama
`page`	integer	Varsayılan: 1
`pageSize`	integer	Min: 1, Maks: 100. Varsayılan: 20
`status`	string	yeni · hazir · yolda · teslim-edildi · geri-dondu · sorunlu
`sortBy`	string	createdAt · barcodeAt · deliveredAt

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

Yanıt 200 OK

{
  "ok": true,
  "orders": [
    {
      "id": "68abc123def456",
      "siparisId": "DEP-0001-XYZ123",
      "status": "yeni",
      "type": "depot",
      "recipient": { "fullName": "Ayşe Demir", "city": "İstanbul", "district": "Kadıköy" },
      "items": [{ "stockId": "stk_001", "productName": "Mavi Tişört L", "quantity": 2 }],
      "createdAt": "2026-07-02T10:00:00.000Z"
    }
  ],
  "total": 14,
  "page": 1,
  "pageSize": 20
}

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

Tek sipariş detayı. :id → ObjectId veya siparisId.

curl -X GET "https://kargofly.com/api/v1/orders/DEP-0001-XYZ123" \
  -H "Authorization: Bearer kf_live_xxx"

Stok

Depodaki ürün stoklarını sorgulayın.

GET/api/v1/stockstock:read

Parametre	Tip	Açıklama
`warehouseId` ✅ Zorunlu	string	Depo ID
`search`	string	Ürün adı veya SKU ile ara
`page`	integer	Sayfa numarası
`pageSize`	integer	Sayfa başı kayıt

curl -X GET "https://kargofly.com/api/v1/stock?warehouseId=wh_abc123" \
  -H "Authorization: Bearer kf_live_xxx"

Yanıt 200 OK

{
  "ok": true,
  "warehouseId": "wh_abc123",
  "warehouseName": "Kargofly Depo İstanbul",
  "stock": [
    {
      "stockId": "stk_001",
      "productName": "Mavi Tişört L",
      "sku": "TSH-BLU-L",
      "quantity": 42,
      "available": true,
      "shelf": "A-3-2"
    }
  ],
  "total": 87,
  "page": 1
}

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

Stok var mı yok mu sorgular. available: true/false

{
  "ok": true,
  "stockId": "stk_001",
  "productName": "Mavi Tişört L",
  "sku": "TSH-BLU-L",
  "quantity": 42,
  "available": true,
  "warehouseId": "wh_abc123",
  "warehouseName": "Kargofly Depo İstanbul"
}

Depo Hesap

Bakiye, kazanç ve fatura sorguları.

GET/api/v1/warehouse/account/balancewarehouse:read

{
  "ok": true,
  "warehouseId": "wh_abc123",
  "warehouseName": "Kargofly Depo İstanbul",
  "balanceTL": "4250.00",
  "pendingEarningsTL": "1800.00",
  "currency": "TRY"
}

GET/api/v1/warehouse/account/pending-earningswarehouse:read

{
  "ok": true,
  "pendingEarningsTL": "1800.00",
  "orders": [
    {
      "orderId": "68abc123",
      "siparisId": "DEP-0001-XYZ",
      "earningTL": "25.00",
      "status": "yolda",
      "createdAt": "2026-07-01T10:00:00.000Z"
    }
  ]
}

GET/api/v1/warehouse/account/pending-invoiceswarehouse:read

{
  "ok": true,
  "pendingInvoices": [
    {
      "invoiceId": "inv_001",
      "amountTL": "850.00",
      "period": "2026-06",
      "dueDate": "2026-07-15T00:00:00.000Z",
      "status": "pending"
    }
  ],
  "totalPendingTL": "850.00"
}

Webhook

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

Webhook kurmak için: Depo Paneli → Entegrasyonlar → Entegrasyon Ekle → Webhook

İmza Doğrulama

X-Kargofly-Signature: sha256=HMAC-SHA256(webhookSecret, rawBody)

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

Event: warehouse.order.received

Depoya yeni sipariş atandığında tetiklenir.

{
  "event": "warehouse.order.received",
  "timestamp": "2026-07-02T10:00:00.000Z",
  "data": {
    "siparisId": "DEP-0001-XYZ123",
    "warehouseId": "wh_abc123",
    "status": "yeni",
    "items": [
      { "stockId": "stk_001", "productName": "Mavi Tişört L", "quantity": 2 }
    ],
    "recipient": {
      "fullName": "Ayşe Demir",
      "city": "Ankara",
      "district": "Çankaya"
    },
    "createdAt": "2026-07-02T10:00:00.000Z"
  }
}

Event: warehouse.order.shipped

Sipariş kargoya teslim edildiğinde tetiklenir.

{
  "event": "warehouse.order.shipped",
  "timestamp": "2026-07-02T14:00:00.000Z",
  "data": {
    "siparisId": "DEP-0001-XYZ123",
    "warehouseId": "wh_abc123",
    "carrier": "SURAT",
    "trackingNumber": "1234567890",
    "shippedAt": "2026-07-02T14:00:00.000Z"
  }
}

Event: shipment.status_changed

Kargo durumu her değiştiğinde tetiklenir.

{
  "event": "shipment.status_changed",
  "timestamp": "2026-07-02T08:00:00.000Z",
  "data": {
    "siparisId": "DEP-0001-XYZ123",
    "status": "teslim-edildi",
    "previousStatus": "yolda",
    "location": "Ankara Çankaya Şubesi",
    "carrier": "SURAT",
    "trackingNumber": "1234567890"
  }
}

Yeniden Deneme

Yanıt	Davranış
2xx	Başarılı — tekrar denenmez
4xx	Başarısız — tekrar denenmez
5xx / Timeout	3 kez: 1dk → 5dk → 30dk

Hata Kodları

HTTP	error	Açıklama
400	`validation_error`	Eksik veya hatalı parametre
401	`unauthorized`	Token eksik veya geçersiz
403	`forbidden`	Kapsam yetersiz
404	`not_found`	Kayıt bulunamadı
422	`insufficient_stock`	Stok yetersiz
422	`invalid_status`	Bu işlem mevcut statüste yapılamaz
429	`rate_limited`	Hız limiti aşıldı
500	`server_error`	Sunucu hatası

{
  "ok": false,
  "error": "insufficient_stock",
  "message": "Depoda yeterli stok bulunmuyor."
}

Sipariş Durum Kodları

yeni✱Yeni — Sipariş depoya atandı, hazırlanmayı bekliyor

hazir📦Hazır — Depo hazırladı, kargoya teslim bekleniyor

yolda🚚Yolda — Kargo teslim alındı, dağıtımda

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

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

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

Tüm para birimleri Türk Lirası (TL) cinsindendir.
Tarih/saat değerleri UTC olarak döner.
ok: true başarılı, ok: false hatalı isteği belirtir.