Basit Kargo API

Tek entegrasyonla Aras, MNG, Yurtiçi, Sürat, PTT ve diğer tüm kargo firmalarına bağlanın. RESTful, JSON, hızlı.

HTTPS Only

RESTful JSON

Webhook Desteği

Base URL

Production

https://basitkargo.com/api

⚠️

Tüm isteklerde HTTPS zorunludur. HTTP istekleri kabul edilmez.

Kimlik Doğrulama

Her istekte Authorization header'ında Bearer token gönderilmelidir. Token'ınızı hesap ayarlarından oluşturabilirsiniz.

            
            
            
        
curl -X GET "https://basitkargo.com/api/handlers" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json"
const res = await fetch("https://basitkargo.com/api/handlers", {
  headers: {
    "Authorization": `Bearer ${TOKEN}`,
    "Content-Type": "application/json"
  }
});
const data = await res.json();
import requests

res = requests.get(
    "https://basitkargo.com/api/handlers",
    headers={"Authorization": f"Bearer {TOKEN}"}
)
data = res.json()

İstek Limiti

API, her token için dakikada 600 istek ile sınırlıdır. Limit aşıldığında istek işlenmez ve 429 Too Many Requests durum koduyla reddedilir; yanıttaki Retry-After header'ı, limitin sıfırlanmasına kaç saniye kaldığını belirtir.

            Yanıt
            429 Too Many Requests
        

HTTP/1.1 429 Too Many Requests
Retry-After: 34

İstek limiti aşıldı. Lütfen kısa bir süre sonra tekrar deneyin.

💡

429 yanıtı aldığınızda isteği hemen tekrarlamak yerine Retry-After süresi kadar bekleyip yeniden deneyin. Toplu aktarımlarda (ör. çok sayıda siparişin tek seferde gönderilmesi) istekleri dakikaya yayarak göndermenizi öneririz. Limitiniz yeterli gelmiyorsa destek ekibimizle iletişime geçebilirsiniz.

Güvenli Tekrar (Idempotency-Key)

Sipariş oluşturan ve kargo kodu üreten uçlarda yanıt zaman aşımına uğrarsa istemci işlemin gerçekleşip gerçekleşmediğini bilemez; isteği körlemesine tekrarlamak ikinci bir sipariş, ikinci bir kargo kodu ve ikinci bir ücret kesintisi demektir. Bunu önlemek için isteğe Idempotency-Key başlığı ekleyin: aynı anahtarla gelen ikinci istek yeniden işlenmez, ilk isteğin yanıtı aynen döner.

💡

Desteklenen uçlar: POST /v2/order, POST /v2/order/barcode, POST /v2/order/{id}/barcode.
Anahtar, istek başına sizin ürettiğiniz benzersiz bir değerdir (UUID önerilir), 1-255 karakter, büyük/küçük harfe duyarlı; boş veya daha uzun başlık 400 döner. Hesabınıza özeldir ve her durumda 24 saat saklanır; sonra aynı anahtar yeni bir istek sayılır.
Tekrarlanan istek 200 ve ilk yanıtın gövdesini alır; Idempotency-Replayed: true başlığıyla ayırt edilir. Bu gövde ilk anın görüntüsüdür, güncel durum için Sipariş Sorgula kullanın.
İlk istek hâlâ işleniyorsa 409 döner; birkaç saniye sonra aynı anahtarla tekrar deneyin. İlk istek 10 dakikayı aşmış ve sonuçlanmamışsa (ör. sunucu yeniden başladı) yine 409 döner: siparişin oluşup oluşmadığını Sipariş Listele / Filtrele ile doğrulayıp yeni bir anahtarla ilerleyin. Aynı anahtar hiçbir zaman işi ikinci kez çalıştırmaz.
Aynı anahtar farklı bir gövde veya farklı bir uçla kullanılırsa 422 döner. JSON alanlarının sırası ve extraServices sırası gövdeyi değiştirmez; paket ve kalem dizilerinin sırası değiştirir.
İlk istek sipariş oluşmadan hata ile biterse (ör. yetersiz bakiye, bölge dışı adres) anahtar serbest kalır; nedeni giderdikten sonra aynı anahtarla yeniden deneyebilirsiniz. Sipariş oluştuktan sonra yanıt üretilemezse anahtar korunur ve tekrar 409 ile sipariş id'sini bildirir; siparişi Sipariş Sorgula ile alın.
Önerilen istemci zaman aşımı: kargo kodu üretimi kargo firmasına bağlı olduğundan 90 saniye; zaman aşımında isteği aynı anahtarla tekrarlayın.

İstek

curl -X POST "https://basitkargo.com/api/v2/order/barcode" \
  -H "Authorization: Bearer TOKEN" -H "Content-Type: application/json" \
  -H "Idempotency-Key: 6f1c2a7e-3b7d-4c7e-9a1e-0d2f6b8c4e21" \
  -d '{ ...sipariş gövdesi... }'

Aynı anahtarla ikinci istek200 OK

HTTP/1.1 200 OK
Idempotency-Replayed: true
Content-Type: application/json

{ ...ilk isteğin yanıtı, yeni sipariş açılmaz, ücret kesilmez... }

Kargo Firmaları

GET /handlers

Hesabınıza açık kargo firmalarının listesini döndürür. Hesabınıza kapalı firmalar listede yer almaz; dönen her code değeri kargo kodu üretim uçlarında kullanılabilir.

                    Yanıt
                    200 OK
                

[
  {
    "name": "Aras Kargo",
    "code": "ARAS",
    "logo": "https://...logo/aras.png"
  },
  {
    "name": "Yurtiçi Kargo",
    "code": "YURTICI",
    "logo": "https://...logo/yurtici.png"
  }
]

💡

Kendi anlaşmanızı kullanmak için kod başına SELF_ ekleyin. Örn: SELF_SURAT. Panelden kendi anlaşmanızı tanımladığınız firmalar listede SELF_ kodlarıyla da yer alır.

Desi/Kg ile Fiyat Sorgulama

GET/handlers/fee/desiKg/{desiKg}

Desi/Kg bilgisi ile tüm firmaların fiyat listesini döndürür. Fiyat "Şehir Dışı - Tüm Türkiye" tarifesidir; gönderici ve alıcı aynı ildeyse geçerli olan şehir içi fiyat için Fiyat Teklifi ucunu kullanın.

Parametre	Tip	Zorunlu	Açıklama
desiKg	number	Evet	Desi/Kg değeri (path); ondalık değer bir üst tam desiye yuvarlanır (2.5 → 3)
codAmount	number	Hayır	Kapıda tahsilat tutarı (query)
codType	string	Hayır	Kapıda ödeme tipi: `CASH` (Nakit) veya `CREDIT_CARD` (Kredi Kartı). Belirtilmezse firmanın desteklediği tip kullanılır (query)

Yanıt200 OK

[
  { "desiKg": 5, "handlerCode": "MNG", "price": 25.54, "codFee": 10.00 },
  { "desiKg": 5, "handlerCode": "YURTICI", "price": 25.54, "codFee": null }
]

Paket Bilgileri ile Fiyat Sorgulama

POST/handlers/fee/packages

Paket ölçüleri ile fiyat listesini döndürür. Hesabınıza açık olan ve paketleri taşıyabilecek (desi kapasitesi uygun) firmalar listelenir; fiyatı hesaplanamayan firmalar listede yer almaz. En az bir paket gönderilmesi zorunludur. Kapıda ödeme tutarı verilirse her satırda tahsilat hizmet bedeli (codFee) de hesaplanır. Fiyat "Şehir Dışı - Tüm Türkiye" tarifesidir; gönderici ve alıcı aynı ildeyse geçerli olan şehir içi fiyat için Fiyat Teklifi ucunu kullanın.

Parametre	Tip	Zorunlu	Açıklama
codAmount	number	Hayır	Kapıda tahsilat tutarı (query)
codType	string	Hayır	`CASH` veya `CREDIT_CARD` (query). Belirtilmezse firmanın desteklediği tip kullanılır; firmanın desteklemediği tip için `codFee` boş döner

İstek Gövdesi

[
  { "height": "10", "width": "15", "depth": "5", "weight": "1" }
]

Yanıt200 OK

[
  {
    "desiKg": 1,
    "handlerCode": "SURAT",
    "price": 87.93,
    "minDesiKg": null,
    "maxDesiKg": null,
    "cashOnDelivery": false,
    "creditCardOnDelivery": false,
    "codFee": null
  }
]

Fiyat Teklifi (Adres Bazlı)

POST/v2/quotes

Bir gönderi için hesabınıza açık kargo firmalarını ve ücretlerini tek çağrıda verir. Paneldeki "Kargo Kodu Oluştur" listesi ve kargo kodu üretimiyle aynı kuralı çalıştırır: gönderici ve alıcı aynı ildeyse şehir içi, değilse şehir dışı tarife uygulanır; desi sınırları, kapıda ödeme desteği ve tutar limiti, ödeme yöntemi ve bölge kapsamı dikkate alınır. Listelenen firma kod üretiminde kabul edilen firma, price.total tahsil edilecek ücrettir.

💡

Gönderici adresi: sender.addressId (kayıtlı adres) → yoksa sender.city/town → yoksa API anahtarınıza tanımlı varsayılan adres → o da yoksa hesabınızın varsayılan adresi (sipariş oluşturma ile aynı sıra). addressId ile city birlikte gönderilemez. Hangisinin kullanıldığı basis.firmAddressSource alanında döner (bkz. Fiyat Teklifi Kodları). Gelen kargoda (cargoType=INCOMING) bu kural alıcı tarafı için geçerlidir.
Alıcı adresi: recipient.city zorunlu değildir; verilmezse şehir dışı tarife varsayılır (basis.pricingBasis=INTERCITY_ASSUMED) ve o taraf için bölge kapsamı denetlenmez; il verilip ilçe verilmezse kapsam il düzeyinde denetlenir.
Mevcut sipariş: orderId verilirse adres, paket, ödeme ve kapıda ödeme bilgileri siparişten okunur; diğer gönderi alanları birlikte gönderilemez.
includeUnavailable=true ile bu gönderiyi taşıyamayan firmalar da available=false ve reasons ile listelenir. Hesabınıza kapalı firmalar hiçbir durumda listelenmez.
price.paymentMethodFee: kargo ücreti şubede (CASH) veya alıcı tarafından (RECIPIENT) ödendiğinde bakiyenizden düşülen platform hizmet bedeli; bu yöntemlerde taşıma ücretinin kendisi bakiyenizden düşülmez. total her durumda toplam maliyettir.
Fiyatlar KDV dahildir ve hesabınızın indirimi uygulanmıştır. Teklif kimliği ve fiyat kilidi yoktur; kod üretiminde ücret güncel tarifeyle yeniden hesaplanır, beyan edilen desi ile tartılan desi farkı sonradan yansıtılabilir.
contract=SELF satırları kendi anlaşmanızdır (handlerCode SELF_ ile başlar); shipmentFee 0'dır, taşıma ücretini kargo firması size faturalandırır.

Alan	Tip	Zorunlu	Açıklama
packages	array	Evet	Paket ölçüleri: `height`, `width`, `depth` (cm) ve `weight` (kg); en az bir paket. `orderId` verildiğinde gönderilmez
orderId	string	Hayır	Mevcut siparişin ID'si; verilirse gönderi bilgileri siparişten okunur
sender.addressId	string	Hayır	Kayıtlı gönderici adres ID'si (bkz. Adres Listesi)
sender.city / sender.town	string	Hayır	Gönderici il / ilçe (resmî adlar). `addressId` ile birlikte gönderilemez
recipient.city / recipient.town	string	Hayır	Alıcı il / ilçe
cargoType	string	Hayır	`OUTGOING` (varsayılan) veya `INCOMING`
paymentMethod	string	Hayır	Kargo ücreti ödeme yöntemi: `ADVANCE` (varsayılan), `CASH`, `RECIPIENT`
cod.amount	number	Hayır	Kapıda tahsilat tutarı; verilirse kapıda ödemeli gönderi olarak fiyatlanır
cod.type	string	Hayır	`CASH` (varsayılan) veya `CREDIT_CARD`. Belirtilmezse nakit tahsilat varsayılır (kargo kodu üretimiyle aynı); yalnız kartla tahsilat yapan firmalar için `CREDIT_CARD` gönderin
extraServices	array	Hayır	Ek hizmet kodları, örn. `SEND_SMS_TO_SENDER`, `KT`. Alan hiç gönderilmezse siparişte olduğu gibi markanın varsayılanları (örn. teslimde satıcıya bildirim) fiyata dahil edilir; boş dizi `[]` "ek hizmet yok" demektir
brandId	string	Hayır	Ek hizmet varsayılanlarının alınacağı marka ID'si; belirtilmezse varsayılan marka. Yalnız `extraServices` gönderilmediğinde anlamlıdır
handlerCodes	array	Hayır	Yalnız bu firmalar, örn. `["ARAS","SURAT"]`
includeUnavailable	boolean	Hayır	Taşıyamayan firmaları sebepleriyle de listele (varsayılan `false`)

İstek Gövdesi

{
  "sender":    { "addressId": "adr-1" },
  "recipient": { "city": "İstanbul", "town": "Ataşehir" },
  "packages":  [ { "height": 10, "width": 15, "depth": 5, "weight": 1 } ],
  "paymentMethod": "ADVANCE",
  "cod": { "amount": 6000.00, "type": "CASH" },
  "includeUnavailable": true
}

cURL

curl -X POST "https://basitkargo.com/api/v2/quotes" \
  -H "Authorization: Bearer TOKEN" -H "Content-Type: application/json" \
  -d '{"recipient":{"city":"İstanbul"},"packages":[{"weight":1}]}'

Yanıt200 OK

{
  "calculatedAt": "2026-09-18T14:05:00",
  "currency": "TRY",
  "taxIncluded": true,
  "basis": {
    "totalDesiKg": 1,
    "pricingBasis": "IN_CITY",           // IN_CITY | INTERCITY | INTERCITY_ASSUMED
    "senderCity": "İstanbul",
    "recipientCity": "İstanbul",
    "firmAddressSource": "ADDRESS_ID",   // ORDER | ADDRESS_ID | CITY | DEFAULT_ADDRESS | NONE
    "orderId": null
  },
  "quotes": [
    {
      "handlerCode": "ARAS",
      "handler": "Aras Kargo",
      "logo": "https://...logo/aras.png",
      "available": true,
      "contract": "BASIT_KARGO",        // BASIT_KARGO | SELF
      "price": { "shipmentFee": 103.00, "codFee": 140.00, "extraServicesFee": 0, "paymentMethodFee": 0, "total": 243.00 },
      "estimatedDeliveryDays": 1,
      "pickupAddress": null,            // yalnız adresten toplama yapan firmalarda dolu
      "capabilities": { "cashOnDelivery": true, "creditCardOnDelivery": true, "maxCodAmount": 7000, "minDesiKg": 0, "maxDesiKg": 100 },
      "reasons": []
    },
    {
      "handlerCode": "PTT",
      "handler": "PTT Kargo",
      "logo": "https://...logo/ptt.png",
      "available": false,
      "contract": "BASIT_KARGO",
      "price": null,
      "capabilities": { "cashOnDelivery": true, "creditCardOnDelivery": true, "maxCodAmount": 5000, "minDesiKg": 0, "maxDesiKg": 30 },
      "reasons": [ { "code": "COD_AMOUNT_EXCEEDS_LIMIT", "message": "Kapıda ödeme tutarı kargo firmasının limitini aşıyor." } ]
    }
  ]
}

Tarife Tabloları

GET/v2/tariffs

Hesabınıza açık kargo firmalarının tam fiyat tablolarını döndürür: firmanın üst desi sınırına kadar desi başına şehir içi ve şehir dışı ücret, kapıda ödeme hizmet bedeli bantları ve kart komisyonu, ücretli ek hizmetler ve firma yetenekleri. Panelin "Kargo Firmaları" sayfasında gördüğünüz rakamların aynısıdır: KDV dahil, hesabınızın indirimi uygulanmış. Toplu fiyat hesabını kendi tarafınızda yapmak için kullanın; tek bir gönderinin kesin fiyatı için Fiyat Teklifi ucunu kullanın.

💡

Önbellek: yanıt ETag ve Cache-Control: private, max-age=3600 başlıklarıyla döner. If-None-Match ile aynı etiketi gönderirseniz tarife değişmemişse 304 Not Modified alırsınız. Etiket yalnız tarife satırlarından türetilir; bir tarife veya hesabınızın indirimi değişince değişir. Yanıt hesaba özeldir (Vary: Authorization, Cookie); paylaşılan önbelleklerde saklanmaz.
Desi aralığı: prices firmanın taşıdığı en yüksek desiye kadar her desi için tam fiyatı içerir (tablo dışı desiler firmanın ekstra desi kuralıyla hesaplanıp aynı yuvarlamayla verilir); şehir içi/dışı sütunu gönderinin illerine göre seçilir.
contract=SELF satırları kendi anlaşmanızdır; fiyat tablosu taşımaz.
Kapıda ödeme bandında fee sabit ücret, baseFee + rate bant alt sınırını aşan tutarın oranı, baseFee + ratePerHundred aşan her 100 TL için ek ücret demektir; feeText okunur halidir.

Parametre	Tip	Zorunlu	Açıklama
handlerCodes	string	Hayır	Virgülle ayrılmış firma kodları (query), örn. `ARAS,SURAT`; verilmezse hesabınıza açık tüm firmalar
If-None-Match	header	Hayır	Önceki yanıtın `ETag` değeri; eşleşirse `304` döner

cURL

curl "https://basitkargo.com/api/v2/tariffs?handlerCodes=ARAS" \
  -H "Authorization: Bearer TOKEN" -H 'If-None-Match: "3f2a..."'

Yanıt200 OK

{
  "generatedAt": "2026-09-18T14:05:00",
  "currency": "TRY",
  "taxIncluded": true,
  "tariffs": [
    {
      "handlerCode": "ARAS",
      "handler": "Aras Kargo",
      "logo": "https://...logo/aras.png",
      "contract": "BASIT_KARGO",
      "capabilities": { "outgoing": true, "incoming": true, "paymentMethods": ["ADVANCE", "CASH", "RECIPIENT"], "cashOnDelivery": true, "creditCardOnDelivery": true, "maxCodAmount": 7000, "minDesiKg": 0, "maxDesiKg": 100 },
      "prices": [
        { "desi": 1, "inCityFee": 84.30, "fee": 98.80 },
        { "desi": 30, "inCityFee": 300.00, "fee": 360.00 },
        { "desi": 100, "inCityFee": 1414.50, "fee": 1490.50 }  // firmanın üst desi sınırına kadar tam fiyatlar
      ],
      "codFees": {
        "bands": [ { "min": 0, "max": 400, "fee": 20, "rangeText": "0 - 400 TL", "feeText": "20 TL" }, { "min": 6250, "max": 6999, "baseFee": 140, "rate": 0.015, "feeText": "140 TL + %1.5" } ],
        "creditCardCommissionPercent": 4.5
      },
      "extraServices": [ { "code": "SEND_SMS_TO_SENDER", "name": "Teslim Olunca Bana Bildirim Gelsin", "fee": 1 } ]
    },
    {
      "handlerCode": "SELF_ARAS",
      "handler": "Aras Kargo - KA",
      "contract": "SELF",        // kendi anlaşmanız: fiyat tablosu yok, ücreti kargo firması faturalandırır
      "prices": [],
      "codFees": null
    }
  ]
}

Sipariş İşlemleri

POST/v2/order

Yeni sipariş oluşturur (NEW durumunda). Firmaları ve fiyatları GET /v2/order/{id}/fee ile listeleyip kargo kodunu POST /v2/order/{id}/barcode ile üretebilirsiniz.

Alan	Tip	Zorunlu	Açıklama
type	string	Hayır	Kargo tipi: `OUTGOING` (giden) veya `INCOMING` (gelen). Varsayılan: `OUTGOING`
orderTotal	number	Hayır	Sipariş tutarı (TL). Kapıda ödeme tutarından bağımsızdır; otomasyondaki "Sipariş Tutarı" koşulu ve raporlar için kullanılır
orderPaymentType	string	Hayır	Siparişin ödeme tipi (bkz. Sipariş Ödeme Tipleri). `COLLECT_ON_DELIVERY` gönderilip `collect` verilmezse kapıda ödeme `orderTotal` tutarıyla açılır; ikisi de yoksa hata döner
orderPaymentStatus	string	Hayır	Ödeme durumu (bkz. Sipariş Ödeme Durumları). Yalnız ön ödemeli tiplerde saklanır; kapıda ödemede yok sayılır, tahsilat durumu yanıtta `codInfo.collectionStatus` ile döner
addressId	string	Hayır	Kayıtlı gönderici adres ID'si. Belirtilmezse varsayılan adres kullanılır
brandId	string	Hayır	Mağaza marka/profil ID'si. Belirtilmezse varsayılan profil kullanılır

                    
                    
                
{
  "type": "OUTGOING",              // OUTGOING veya INCOMING (varsayılan: OUTGOING)
  "content": {
    "name": "Test Sipariş",
    "code": "#123456",
    "items": [
      { "name": "Ürün Adı", "code": "STK32", "quantity": "1" }
    ],
    "packages": [
      { "height": 10, "width": 15, "depth": 5, "weight": 1 }
    ]
  },
  "client": {
    "name": "Test Alıcı",
    "phone": "5555555555",
    "email": "musteri@ornek.com",   // opsiyonel — müşteri e-posta adresi
    "city": "İstanbul",
    "town": "Kadıköy",
    "address": "Koşuyolu Mah."
  },
  "collect": 100,             // kapıda ödeme tutarı
  "collectOnDeliveryType": "CASH",  // CASH veya CREDIT_CARD
  "orderTotal": 349.90,       // opsiyonel, sipariş tutarı
  "orderPaymentType": "COLLECT_ON_DELIVERY", // opsiyonel: CREDIT_CARD, BANK_TRANSFER, COLLECT_ON_DELIVERY, OTHER
  "addressId": "adres-id",       // opsiyonel, kayıtlı gönderici adres ID
  "brandId": "brand-id"       // opsiyonel, mağaza marka/profil ID
}
curl -X POST "https://basitkargo.com/api/v2/order" \
  -H "Authorization: Bearer TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"content":{"name":"Test","packages":[{"height":10,"width":15,"depth":5,"weight":1}]},"client":{"name":"Alıcı","phone":"555","city":"İstanbul","town":"Kadıköy","address":"..."}}'

Yanıt200 OK

{
  "id": "888-6AR-OUP",
  "barcode": null,
  "type": "OUTGOING",
  "status": "NEW",
  "validationFailed": false,
  "createdTime": "2023-01-01T15:41:47.755"
}

Sipariş Oluştur + Kargo Kodu Üret

POST/v2/order/barcode

Sipariş oluşturur ve anında kargo kodu üretir.

💡

Kendi anlaşmanız: handlerCode = SELF_SURAT
En ucuz firma: handlerCode = ECONOMIC
En hızlı firma: handlerCode = FAST
Zaman aşımında güvenle tekrar deneyebilmek için Idempotency-Key başlığı gönderin (bkz. Güvenli Tekrar); başlıksız bir tekrar ikinci siparişi ve ikinci ücreti üretir.
Alıcı adresini ödeme adımında önceden denetlemek için Adres Doğrulama ucunu kullanın; sipariş kuralı aynıdır.

Alan	Tip	Zorunlu	Açıklama
handlerCode	string	Evet	Kargo firması kodu
type	string	Hayır	Kargo tipi: `OUTGOING` (giden) veya `INCOMING` (gelen). Varsayılan: `OUTGOING`
orderTotal	number	Hayır	Sipariş tutarı (TL). Kapıda ödeme tutarından bağımsızdır; otomasyondaki "Sipariş Tutarı" koşulu ve raporlar için kullanılır
orderPaymentType	string	Hayır	Siparişin ödeme tipi (bkz. Sipariş Ödeme Tipleri). `COLLECT_ON_DELIVERY` gönderilip `collect` verilmezse kapıda ödeme `orderTotal` tutarıyla açılır; ikisi de yoksa hata döner
orderPaymentStatus	string	Hayır	Ödeme durumu (bkz. Sipariş Ödeme Durumları). Yalnız ön ödemeli tiplerde saklanır; kapıda ödemede yok sayılır, tahsilat durumu yanıtta `codInfo.collectionStatus` ile döner
addressId	string	Hayır	Kayıtlı gönderici adres ID'si. Belirtilmezse varsayılan adres kullanılır
brandId	string	Hayır	Mağaza marka/profil ID'si. Belirtilmezse varsayılan profil kullanılır

İstek Gövdesi

{
  "handlerCode": "SURAT",
  "type": "OUTGOING",              // OUTGOING veya INCOMING (varsayılan: OUTGOING)
  "content": {
    "name": "Test Sipariş",
    "code": "#123456",
    "packages": [{ "height": 10, "width": 15, "depth": 5, "weight": 1 }]
  },
  "client": {
    "name": "Test Alıcı",
    "phone": "5555555555",
    "email": "musteri@ornek.com",   // opsiyonel — müşteri e-posta adresi
    "city": "İstanbul",
    "town": "Kadıköy",
    "address": "Koşuyolu Mah."
  },
  "collect": 100,
  "addressId": "adres-id",       // opsiyonel, kayıtlı gönderici adres ID
  "brandId": "brand-id"       // opsiyonel, mağaza marka/profil ID
}

Sipariş için Firma ve Fiyat Listesi

GET/v2/order/{id}/fee

Mevcut bir siparişi taşıyabilecek kargo firmalarını hesaplanmış fiyatlarıyla listeler. Paneldeki "Kargo Kodu Oluştur" ekranında görünen listenin API karşılığıdır: desi limitleri, ödeme yöntemi, kapıda ödeme desteği ve hesabınıza açık firmalar dikkate alınır; liste fiyata göre artan sıralıdır. Dönen handlerCode değeri POST /v2/order/{id}/barcode çağrısında kullanılır.

💡

Fiyatlar bilgilendirme amaçlıdır; teklif/fiyat ID kavramı yoktur. Kargo kodu üretiminde ücret güncel olarak yeniden hesaplanır ve bakiyeden düşülür.
duration: gönderici-alıcı şehir çiftine göre tahmini teslim süresi (gün).
codFee yalnızca kapıda ödemeli siparişlerde hesaplanır; diğer siparişlerde 0 döner.
Kendi anlaşmanız tanımlıysa SELF_ ile başlayan firmalar da listelenir; bu satırlarda fee 0'dır (taşıma ücreti kargo firmanızca kendi anlaşmanıza göre faturalandırılır).
Teslimat adresinin bölge uygunluğu taşıyıcı tarafında kargo kodu üretimi sırasında denetlenir; listede görünen bir firma nadiren "bu adrese teslimat yapmıyor" hatası verebilir — bu durumda başka bir firma deneyin.

Alan	Tip	Zorunlu	Açıklama
id	string (path)	Evet	Fiyatları listelenecek siparişin ID'si

cURL

curl "https://basitkargo.com/api/v2/order/888-6AR-OUP/fee" \
  -H "Authorization: Bearer TOKEN"

Yanıt200 OK

[
  {
    "handlerCode": "HEPSIJET",
    "handler": "HepsiJET",
    "handlerLogo": "hepsijet.png",
    "pickupAddress": "Koşuyolu Mah. No:1 Kadıköy/İstanbul",  // sadece adresten toplama yapan firmalarda
    "fee": 84.90,
    "codFee": 12.50,  // kapıda ödemeli değilse 0 döner
    "duration": 2,      // tahmini teslim süresi (gün)
    "disabled": false   // her zaman false (kapalı firmalar listelenmez)
  },
  {
    "handlerCode": "SURAT",
    "handler": "Sürat Kargo",
    "handlerLogo": "surat.png",
    "pickupAddress": null,  // adresten toplama yapmayan firmalarda null
    "fee": 89.90,
    "codFee": 8.50,
    "duration": 2,
    "disabled": false
  }
]

Mevcut Siparişe Kargo Kodu Üret

POST/v2/order/{id}/barcode

Daha önce POST /v2/order ile oluşturulmuş, NEW durumundaki bir siparişe kargo firması seçip kargo kodu üretir. Paneldeki "Kargo Kodu Oluştur" adımının API karşılığıdır: barkod atanır, kargo ücreti bakiyeden düşülür ve sipariş READY_TO_SHIP durumuna geçer. Yeni sipariş oluşturmaz.

💡

Firmaları ve güncel fiyatları görmek için: GET /v2/order/{id}/fee
Kendi anlaşmanız: handlerCode = SELF_SURAT
En ucuz firma: handlerCode = ECONOMIC
En hızlı firma: handlerCode = FAST

⚠

Sadece NEW durumundaki siparişler için çalışır; kargo kodu zaten üretilmiş siparişte hata döner.
İşlem başarısız olursa (bölge dışı adres, yetersiz bakiye vb.) sipariş NEW durumunda kalır; başka bir firma ile tekrar deneyebilirsiniz.
Zaman aşımında tekrar için Idempotency-Key gönderin (bkz. Güvenli Tekrar): başlıksız bir tekrar ilk istek bittikten sonra gelirse hata alır (kod zaten üretilmiş), ancak ilk istek kargo firmasını beklerken gelirse ikinci bir kod ve ikinci bir ücret üretebilir.
shipmentInfo.handlerShipmentCode bazı firmalarda kargo fiziksel olarak teslim alındıktan sonra dolar; null gelebilir. Eşleştirme için id veya barcode kullanın.
priceInfo (tüm sipariş yanıtlarında ve webhook gövdesinde aynı): shipmentFee kargo ücretidir ve varsa desi farkını zaten içerir. extraFee kargo firmasının ölçümünden sonra oluşan desi farkıdır (yeni ücret eksi teklif edilen ücret; ölçülen desi düşükse negatiftir ve fark bakiyenize iade edilmiştir); yalnız peşin ödemeli Basit Kargo anlaşmalı gönderilerde oluşur, fark yoksa null kalır ve shipmentFee ile toplanmaz. returnFee teslim edilemeyip size geri dönen (RETURNED) gönderide kesilen dönüş ücretidir (null = kesilmedi); İade Oluştur ile açılan iade gönderisinin ücreti ise o siparişin kendi shipmentFee'sidir. extraServicesFee ek hizmet bedelidir ve kod üretiminden sonraki ilk durum kontrolünde dolar; kod üretme yanıtında 0 görünebilir, kesin tutar için Sipariş Sorgula ya da webhook kullanın.
priceInfo.totalCost = shipmentFee + returnFee + extraServicesFee (null alanlar 0 sayılır, kuruşa yukarı yuvarlanır); kapıda ödeme bedelini (codInfo.fee) içermez. Alıcı öder / şubede ödensin gönderilerde shipmentFee bakiyenizden kesilmez, yalnız hizmet bedeli kesilir; kendi anlaşmanızla (SELF_) gönderilerde kargo firmasının size faturaladığı tutardır ve ilk durum kontrolünde dolar.
Webhook gövdesinde null alanlar hiç gönderilmez; anahtar yoksa null sayın. REST yanıtlarında null olarak gelir.

Alan	Tip	Zorunlu	Açıklama
id	string (path)	Evet	Kargo kodu üretilecek siparişin ID'si
handlerCode	string	Evet	Kargo firması kodu

                    
                    
                
{
  "handlerCode": "SURAT"
}
curl -X POST "https://basitkargo.com/api/v2/order/888-6AR-OUP/barcode" \
  -H "Authorization: Bearer TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"handlerCode":"SURAT"}'

Yanıt200 OK

{
  "id": "888-6AR-OUP",
  "barcode": "1234567890",
  "type": "OUTGOING",
  "status": "READY_TO_SHIP",
  "shipmentInfo": {
    "handler": { "name": "Sürat Kargo", "code": "SURAT" },
    "handlerShipmentCode": null
  },
  "priceInfo": { "paymentMethod": "ADVANCE", "shipmentFee": 89.90, "extraFee": null, "returnFee": null, "extraServicesFee": 0, "totalCost": 89.90 },
  "orderTotal": 349.90,
  "orderPaymentType": "COLLECT_ON_DELIVERY",
  "orderPaymentStatus": null,   // kapıda ödemede daima null
  "codInfo": { "collectOnDelivery": true, "type": "CASH", "amount": 349.90, "collectionStatus": "COLLECTION_PENDING", "collectionStatusText": "Tahsilat Bekleniyor", "releaseDate": null }
}

Sipariş Güncelle

PUT/v2/order

Mevcut siparişi günceller. Sadece NEW durumundaki (henüz kargo kodu üretilmemiş) siparişler düzenlenebilir.

⚠

id alanı zorunludur — güncellenecek siparişin ID'si.
content alanı zorunludur.
Kargo kodu üretilmiş veya teslim aşamasındaki siparişler güncellenemez.

Alan	Tip	Zorunlu	Açıklama
id	string	Evet	Güncellenecek siparişin ID'si
content	object	Evet	Sipariş içeriği (ürün, paket bilgileri)
type	string	Hayır	Kargo tipi: `OUTGOING` veya `INCOMING`
orderTotal	number	Hayır	Sipariş tutarı (TL). Kapıda ödeme tutarından bağımsızdır; otomasyondaki "Sipariş Tutarı" koşulu ve raporlar için kullanılır
orderPaymentType	string	Hayır	Siparişin ödeme tipi (bkz. Sipariş Ödeme Tipleri). `COLLECT_ON_DELIVERY` gönderilip `collect` verilmezse kapıda ödeme `orderTotal` tutarıyla açılır; ikisi de yoksa hata döner
orderPaymentStatus	string	Hayır	Ödeme durumu (bkz. Sipariş Ödeme Durumları). Yalnız ön ödemeli tiplerde saklanır; kapıda ödemede yok sayılır, tahsilat durumu yanıtta `codInfo.collectionStatus` ile döner
addressId	string	Hayır	Kayıtlı gönderici adres ID'si. Belirtilmezse varsayılan adres kullanılır
brandId	string	Hayır	Mağaza marka/profil ID'si. Belirtilmezse varsayılan profil kullanılır

                    
                    
                
{
  "id": "888-6AR-OUP",           // zorunlu — güncellenecek sipariş ID
  "type": "OUTGOING",
  "content": {
    "name": "Güncellenmiş Sipariş",
    "code": "#123456",
    "items": [
      { "name": "Ürün Adı", "code": "STK32", "quantity": "2" }
    ],
    "packages": [
      { "height": 12, "width": 18, "depth": 6, "weight": 2 }
    ]
  },
  "client": {
    "name": "Test Alıcı",
    "phone": "5555555555",
    "email": "musteri@ornek.com",   // opsiyonel — müşteri e-posta adresi
    "city": "İstanbul",
    "town": "Kadıköy",
    "address": "Koşuyolu Mah."
  },
  "collect": 150,
  "collectOnDeliveryType": "CASH",
  "orderTotal": 349.90,
  "orderPaymentType": "COLLECT_ON_DELIVERY",
  "addressId": "adres-id",       // opsiyonel
  "brandId": "brand-id"          // opsiyonel
}
curl -X PUT "https://basitkargo.com/api/v2/order" \
  -H "Authorization: Bearer TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"id":"888-6AR-OUP","content":{"name":"Güncel","packages":[{"height":12,"width":18,"depth":6,"weight":2}]},"client":{"name":"Alıcı","phone":"555","city":"İstanbul","town":"Kadıköy","address":"..."}}'

Sipariş Listele / Filtrele

POST/v2/order/filter

Siparişleri filtreler. Tüm parametreler opsiyoneldir. Yanıt gövdesi sipariş dizisidir; sayfalama bilgisi yanıt başlıklarında gelir: X-Total-Count (toplam kayıt), X-Total-Pages, X-Page, X-Page-Size.

Parametre	Tip	Zorunlu	Açıklama
startDate	string	Hayır	Başlangıç tarihi (YYYY-MM-DDTHH:mm:ss)
endDate	string	Hayır	Bitiş tarihi
keyword	string	Hayır	Serbest metin arama: alıcı adı/telefonu, sipariş no, barkod, kargo takip kodu veya ürün adı. Diğer filtrelerle birlikte (VE) uygulanır
statusList	string[]	Hayır	Durum kodları listesi
handlerCode	string	Hayır	Kargo firması kodu
orderPaymentType	string	Hayır	Sipariş ödeme yöntemi (bkz. Sipariş Ödeme Tipleri); `COLLECT_ON_DELIVERY` tüm kapıda ödemeli siparişleri getirir
orderPaymentStatus	string	Hayır	Sipariş ödeme durumu (bkz. Sipariş Ödeme Durumları); yalnız ön ödemeli siparişlerde eşleşir
sortBy	string	Hayır	Sıralama kriteri
page	int	Hayır	Sayfa no (varsayılan: 0)
size	int	Hayır	Sayfa boyutu (varsayılan: 20, max: 100)

İstek Gövdesi

{
  "startDate": "2024-01-01T00:00:00",
  "endDate": "2024-12-31T23:59:59",
  "statusList": ["READY_TO_SHIP", "SHIPPED"],
  "handlerCode": "MNG",
  "sortBy": "CREATED_TIME",
  "page": 0,
  "size": 50
}

Sipariş Sorgula (ID)

GET/v2/order/{id}

Sipariş ID ile detay bilgilerini getirir.

Sipariş Sorgula (Barkod)

GET/v2/order/barcode/{barcode}

Barkod numarası ile sipariş bilgilerini getirir.

Sipariş Sorgula (Takip No)

GET/v2/order/handler-shipment-code/{code}

Kargo firması takip numarası ile sipariş bilgilerini getirir.

Kargo Kodu İptal

DELETE/order/barcode/{barcode}

Şubeye teslim edilmemiş (gönderime hazır durumdaki) siparişin kargo kodunu iptal eder. Sipariş silinmez; taslak (NEW) durumuna döner — yeniden kod alabilir veya Sipariş Sil ile silebilirsiniz. İptalde bu gönderi için bakiyenizden kesilen tutarların tamamı (kargo ücreti, varsa kapıda ödeme ve ek hizmet bedelleri) aynı istek içinde bakiyenize iade edilir; yanıt gövdesi boştur. İptal anında kargo firmasından güncel durum sorgulanır: gönderi teslim alınmışsa hata döner ve hiçbir şey değişmez; kargo firması kodu kendi tarafında zaten iptal etmişse sipariş taslağa döner, ücret iade edilir ve istek başarılı sayılır.

Sipariş Sil

DELETE/order/{id}

Taslak (NEW) durumdaki siparişi siler. Yalnızca henüz kargo kodu üretilmemiş siparişler silinebilir; kodlu gönderi için önce kodu iptal edin — sipariş taslağa döner, sonra silebilirsiniz.

İade Oluştur

GET/v2/order/return/barcode/{barcode}

Teslim edilmiş sipariş için iade kodu oluşturur.

Etiket İndir

GET/label/svg/{id}

Sipariş etiketini SVG formatında indirir.

Konum Bilgileri

GET/country/TR/cities

Türkiye şehir listesini döndürür.

Yanıt200 OK

[
  { "id": 1, "name": "Adana" },
  { "id": 2, "name": "Adıyaman" }
]

İlçeler

GET/city/{id}/towns

Şehre ait ilçe listesi. Örn: GET /city/32/towns

Mahalleler

GET/city/{cityName}/town/{townName}/neigborhoods

İlçeye ait mahalle listesi. Örn: GET /city/Isparta/town/Yalvaç/neigborhoods

Adres Doğrulama

POST/address/validate

Bir teslimat adresini sipariş açmadan önce, sipariş oluşturmanın uyguladığı kuralla denetler ve resmî il / ilçe adlarını döner. Mağazanızın ödeme adımında sunucu tarafından çağırıp alıcıyı adresi düzeltmeye yönlendirebilirsiniz; valid: true dönen bir adres, sipariş oluştururken adres yüzünden reddedilmez. API token'ınız sipariş açıp bakiyenizi harcayabilir: bu ucu tarayıcıdaki mağaza kodundan değil, kendi sunucunuzdan çağırın.

Alan	Tip	Zorunlu	Açıklama
city	string	Evet	Şehir adı (bkz. Şehirler)
town	string	Evet	İlçe adı (bkz. İlçeler)
address	string	Evet	Açık adres metni, 11-200 karakter; mahalle adı içeriyorsa çözümlenir

İstek

curl -X POST "https://basitkargo.com/api/address/validate" \
  -H "Authorization: Bearer TOKEN" -H "Content-Type: application/json" \
  -d '{ "city": "istanbul", "town": "kadıköy", "address": "Caferağa Mah. Moda Cad. No: 12 D: 3" }'

Yanıt200 OK

{
  "valid": true,
  "message": null,
  "city": "İstanbul",
  "town": "Kadıköy",
  "neighborhood": "Caferağa"
}

💡

Adres uygunsuz olsa da yanıt 200'dür: valid: false ve message alanında sipariş oluşturmanın kaydedeceği aynı metin döner: "Şehir bilgisi yanlış veya eksik", "İlçe bilgisi yanlış veya eksik", "Adres Çok Kısa", "Adres Çok Uzun", "Adres Alanında Uygunsuz İçerik Var". Boş veya bozuk JSON gövde 400, istek limiti 429 döner.
city ve town resmî yazımdır; siparişi bu değerlerle açmanız önerilir. neighborhood adres metninden çıkarılan tahmini mahalledir, alıcıya kesin bilgi olarak göstermeyin; bulunamazsa null gelir ve adres yine geçerlidir, sipariş için mahalle zorunlu değildir. (Adres Ekle'nin kuralı daha sıkıdır ve mahalle ister.)
Emoji gibi özel karakterler sipariş kaydında olduğu gibi burada da silinerek denetlenir. Yalnız alıcı adı ve telefonu bu uçta denetlenmez: sipariş kuralı ad için en az 3 karakter, telefon için rakam dışı karakterler ayıklandıktan sonra 10 hane ister.
Kargo firmasının bu adrese teslimat yapıp yapmadığı yalnız kargo kodu üretilirken bilinir; bu uç onu denetleyemez.

Kullanıcı

GET/firm/balance

Kullanıcı bakiyesini sorgular.

Yanıt200 OK

Hesap Durumu

GET/firm/status

Üyelik durumunu döner: hesap tipi (bireysel / kurumsal) ve esnaf vergi muafiyeti, hesap onaylı mı, hangi onay aşamasında, son hatalı belge nedeni ve aşamanın ne anlama geldiğini anlatan Türkçe özet. Onay bekleyen hesaplar da bu ucu çağırabilir.

Yanıt200 OK

{
  "accountType": "CORPORATE",
  "accountTypeLabel": "Kurumsal Hesap",
  "taxExempt": false,
  "taxExemptionExpiresAt": null,
  "status": "WRONG_DOCUMENT",
  "statusLabel": "Hatalı Belge",
  "approved": false,
  "approvedAt": null,
  "lastDocumentUploadedAt": "2026-09-04T14:12:00",
  "wrongDocumentReason": "TAX_CERTIFICATE_OUTDATED",
  "wrongDocumentReasonLabel": "Vergi Levhası Güncel Değil",
  "wrongDocumentAt": "2026-09-05T10:30:00",
  "summary": "Hatalı belge: yüklenen belge kabul edilmedi; bildirilen neden: Vergi Levhası Güncel Değil (05.09.2026). Düzeltilmiş belgenin panelden veya mobil uygulamadan yeniden yüklenmesi gerekiyor."
}

status değerleri: APPROVED, DOCUMENT_WAITING, DOCUMENT_UPLOADED, WRONG_DOCUMENT, NOT_APPROVED, DISABLED, BANNED. Hatalı belge alanları yalnız WRONG_DOCUMENT durumunda dolar. accountType: INDIVIDUAL veya CORPORATE; taxExempt esnaf vergi muafiyet belgesiyle kayıtlı hesaplarda true.

Marka Listesi

GET/firm/brand

Kayıtlı marka/profil listesini getirir. Sipariş oluştururken brandId alanında kullanılır.

Yanıt200 OK

[
  {
    "id": "abc-123",
    "name": "Marka Adı",
    "status": "APPROVED",
    "logo": "https://...",
    "website": "https://...",
    "instagram": "@marka",
    "createdAt": "2024-01-15T10:30:00"
  }
]

Marka Ekle

POST/firm/brand

Yeni marka/profil oluşturur. Yeni markalar WAITING_APPROVAL (Onay Bekliyor) durumunda açılır; ekibimiz inceleyip onayladıktan sonra APPROVED olur.

Alan	Tip	Zorunlu	Açıklama
name	string	Evet	Marka adı
website	string	Hayır	Web sitesi adresi
instagram	string	Hayır	Instagram kullanıcı adı

                    
                    
                
{
  "name": "Marka Adı",
  "website": "https://www.ornek.com",   // opsiyonel
  "instagram": "@marka"              // opsiyonel
}
curl -X POST "https://basitkargo.com/api/firm/brand" \
  -H "Authorization: Bearer TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name":"Marka Adı","website":"https://www.ornek.com","instagram":"@marka"}'

Yanıt200 OK

{
  "id": "abc-123",
  "status": "WAITING_APPROVAL",
  "name": "Marka Adı",
  "logo": null,
  "website": "https://www.ornek.com",
  "instagram": "@marka",
  "createdAt": "2026-08-17T10:30:00"
}

💡

Sipariş oluştururken brandId alanında yalnızca APPROVED durumundaki markalar kullanılabilir; onay bekleyen marka gönderilirse varsayılan marka kullanılır. Durumlar: APPROVED (Onaylı), WAITING_APPROVAL (Onay Bekliyor), REJECTED (Reddedildi).

Adres Listesi

GET/firm/address

Kayıtlı gönderici adres listesini getirir. Sipariş oluştururken addressId alanında kullanılır.

Yanıt200 OK

[
  {
    "id": "xyz-456",
    "name": "Depo Adresi",
    "phone": "5551234567",
    "city": "İstanbul",
    "town": "Kadıköy",
    "address": "Koşuyolu Mah.",
    "type": "SHIPPING",
    "createdTime": "2024-01-15T10:30:00"
  }
]

Adres Ekle

POST/firm/address

Yeni gönderici adresi oluşturur. Oluşturulan adres, sipariş oluştururken addressId alanında hemen kullanılabilir.

Alan	Tip	Zorunlu	Açıklama
name	string	Evet	Adres başlığı (örn: Depo, Merkez Ofis)
phone	string	Evet	İletişim telefonu (5XXXXXXXXX)
city	string	Evet	Şehir adı — resmî kayıtlarla eşleşmeli (bkz. Şehirler)
town	string	Evet	İlçe adı — resmî kayıtlarla eşleşmeli (bkz. İlçeler)
address	string	Evet	Mahalle adı dahil açık adres (en az 11 karakter)
senderName	string	Hayır	Gönderici ad soyad — `senderNationalId` ile birlikte verilmelidir. İkisi de boş bırakılırsa firma yetkilisinin bilgileri kullanılır
senderNationalId	string	Hayır	Gönderici TC kimlik / vergi numarası (10 veya 11 hane) — `senderName` ile birlikte verilmelidir

                    
                    
                
{
  "name": "Depo Adresi",
  "phone": "5551234567",
  "city": "İstanbul",
  "town": "Kadıköy",
  "address": "Koşuyolu Mah. Örnek Sok. No:1",
  "senderName": "Ad Soyad",          // opsiyonel
  "senderNationalId": "12345678901"   // opsiyonel
}
curl -X POST "https://basitkargo.com/api/firm/address" \
  -H "Authorization: Bearer TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name":"Depo Adresi","phone":"5551234567","city":"İstanbul","town":"Kadıköy","address":"Koşuyolu Mah. Örnek Sok. No:1"}'

Yanıt200 OK

{
  "id": "xyz-456",
  "name": "Depo Adresi",
  "phone": "5551234567",
  "city": "İstanbul",
  "town": "Kadıköy",
  "address": "Koşuyolu Mah. Örnek Sok. No:1",
  "type": "SHIPPING",
  "createdTime": "2026-08-17T10:30:00"
}

⚠️

Adres, resmî adres kayıtları (UAVT) ile doğrulanır: city ve town resmî isimlerle eşleşmeli, address metni geçerli bir mahalle adı içermelidir. Aksi halde "Şehir bilgisi yanlış veya eksik", "İlçe bilgisi yanlış veya eksik" ya da "Mahalle/Köy Eksik Veya Hatalı" hatası döner. Bir hesapta en fazla 100 adres bulunabilir.

Yardım Makaleleri

GET/help/search?q={metin}&limit={1-5}

Basit Kargo'nun nasıl çalıştığına dair onaylı yardım makalelerini arar (ücretler, kapıda ödeme tahsilatı, iade, entegrasyonlar, destek saatleri). Yapay zeka asistanlarının doğru bilgi vermesi için tasarlanmıştır; en iyi eşleşen makaleleri başlık ve tam metinle döndürür. limit isteğe bağlıdır, varsayılan 3. Tek makale için GET /help/{slug} kullanılır.

Yanıt200 OK

[
  {
    "slug": "kapida-odeme",
    "title": "Kapıda ödeme nasıl çalışır?",
    "summary": "Kapıda Ödeme ayarlarından IBAN ile aktif edilir; ...",
    "body": "Kapıda ödemeyi panelde ..."
  }
]

Müşteriler

Müşteri havuzunuz: bugüne kadar kargo gönderdiğiniz alıcılar ve elle eklediğiniz müşteriler, sipariş sayısı ve harcama toplamlarıyla birlikte. Tekrar gönderi oluştururken alıcı bilgilerini buradan çekebilir, paneldeki Müşterilerim sayfasında olduğu gibi kayıt ekleyip düzeltebilirsiniz.

POST/customer/search

Müşterilerinizi arar/listeler. Tüm alanlar opsiyoneldir; boş gövde {} tüm müşterileri son sipariş tarihine göre listeler.

Alan	Tip	Zorunlu	Açıklama
search	string	Hayır	Ad veya telefonda arama (içeren eşleşme).
city	string	Hayır	Şehir filtresi (tam eşleşme), örn. `İstanbul`.
minOrders / maxOrders	number	Hayır	Sipariş sayısı aralığı.
minSpending / maxSpending	number	Hayır	Toplam harcama aralığı (TL).
startDate / endDate	string	Hayır	`YYYY-AA-GG` biçiminde; sipariş istatistiklerinin hesaplandığı tarih penceresini belirler.
sortBy	string	Hayır	`name`, `city`, `town`, `orderCount`, `totalSpending`, `lastOrderDate` (varsayılan).
ascending	boolean	Hayır	Artan sıralama, varsayılan `false`.
page / size	number	Hayır	Sayfa (1'den başlar) ve sayfa boyutu (varsayılan `20`, en fazla `100`).

cURL

curl -X POST "https://basitkargo.com/api/customer/search" \
  -H "Authorization: Bearer TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"search":"Ahmet"}'

Yanıt200 OK

{
  "currentPage": 1,
  "pageSize": 20,
  "totalPage": 1,
  "totalNumberOfItems": 2,
  "items": [
    {
      "id": 1234,
      "name": "Ahmet Yılmaz",
      "phone": "5551234567",
      "city": "İstanbul",
      "town": "Kadıköy",
      "address": "Koşuyolu Mah. Örnek Sok. No:1 D:3",
      "orderCount": 7,
      "totalSpending": 2340.00,
      "lastOrderDate": "2026-08-12T16:41:09"
    }
  ]
}

💡

Havuz, gönderilerinizin alıcı bilgilerinden otomatik oluşur; elle kayıt için Müşteri Ekle, düzeltme için Müşteri Güncelle (id bu yanıttan alınır). startDate/endDate müşteri listesini daraltmaz, yalnızca orderCount/totalSpending istatistiklerinin penceresini belirler — belirli dönemde sipariş verenleri bulmak için tarih aralığını minOrders: 1 ile birlikte kullanın. Geçersiz tarih biçiminde hata döner.

Müşteri Ekle

POST/customer

Müşteri havuzuna elle kayıt ekler; paneldeki Müşterilerim → Müşteri Ekle ile aynı kurallar geçerlidir, tüm alanlar zorunludur. Mevcut kaydın üzerine yazmaz: aynı ad ve telefonla kayıt zaten varsa, il/ilçe/adres aynıysa o kayıt olduğu gibi döner (zaman aşımı sonrası isteği tekrarlamak güvenlidir), farklıysa kayıt numarasını içeren bir hata döner ve bilgileri Müşteri Güncelle ile değiştirmeniz istenir.

Alan	Tip	Zorunlu	Açıklama
name	string	Evet	Ad soyad
phone	string	Evet	Telefon (5XXXXXXXXX). `+90` / `0` öneki ve boşluklar kaydedilirken temizlenir
city	string	Evet	İl
town	string	Evet	İlçe
address	string	Evet	Açık adres

                    
                    
                
{
  "name": "Ahmet Yılmaz",
  "phone": "5551234567",
  "city": "İstanbul",
  "town": "Kadıköy",
  "address": "Koşuyolu Mah. Örnek Sok. No:1 D:3"
}
curl -X POST "https://basitkargo.com/api/customer" \
  -H "Authorization: Bearer TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name":"Ahmet Yılmaz","phone":"5551234567","city":"İstanbul","town":"Kadıköy","address":"Koşuyolu Mah. Örnek Sok. No:1 D:3"}'

Yanıt200 OK

{
  "id": 1234,
  "name": "Ahmet Yılmaz",
  "phone": "5551234567",
  "city": "İstanbul",
  "town": "Kadıköy",
  "address": "Koşuyolu Mah. Örnek Sok. No:1 D:3"
}

⚠️

Eksik alanda "… alanı boş olamaz.", 255 karakteri aşan alanda "… en fazla 255 karakter olabilir.", 10 haneli olmayan telefonda "Geçerli bir telefon numarası giriniz." hatası döner; fazla haneli numara kesilmez, reddedilir. Aynı ad ve telefonla farklı adresli kayıt varsa "Bu ad ve telefonla kayıtlı bir müşteri zaten var (kayıt no …)" döner. Yanıtta sipariş istatistikleri yer almaz; bunlar yalnızca Müşteri Ara yanıtındadır.

Müşteri Güncelle

PUT/customer/{id}

Kayıtlı bir müşteriyi günceller. id, Müşteri Ara yanıtındaki id alanıdır. Yalnızca gövdede gönderdiğiniz alanlar değişir; göndermediğiniz alanlar korunur, boş gönderilen alan hata verir, en az bir alan gönderilmelidir.

Alan	Tip	Zorunlu	Açıklama
currentPhone	string	Hayır	Güvenlik kontrolü: kaydın Müşteri Ara yanıtındaki telefonu. Verilirse kayıtlı telefonla eşleşmeli, aksi halde işlem reddedilir — yanlış `id` ile başka bir müşteriyi değiştirmemek için önerilir
name	string	Hayır	Yeni ad soyad
phone	string	Hayır	Yeni telefon (5XXXXXXXXX)
city	string	Hayır	Yeni il
town	string	Hayır	Yeni ilçe
address	string	Hayır	Yeni açık adres

                    
                    
                
{
  "currentPhone": "5551234567",              // opsiyonel güvenlik kontrolü
  "address": "Fenerbahçe Mah. Yeni Sok. No:5"   // yalnızca değişen alanlar
}
curl -X PUT "https://basitkargo.com/api/customer/1234" \
  -H "Authorization: Bearer TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"currentPhone":"5551234567","address":"Fenerbahçe Mah. Yeni Sok. No:5"}'

Yanıt200 OK

{
  "id": 1234,
  "name": "Ahmet Yılmaz",
  "phone": "5551234567",
  "city": "İstanbul",
  "town": "Kadıköy",
  "address": "Fenerbahçe Mah. Yeni Sok. No:5"
}

⚠️

Kayıt hesabınıza ait değilse veya silinmişse "Müşteri bulunamadı.", currentPhone uyuşmazsa "Verilen mevcut telefon bu müşteri kaydıyla eşleşmiyor…" döner. Ad ve telefon, havuzda müşterinin kimliğidir: yeni ad + telefon ikilisi başka bir kayda aitse "Bu ad ve telefonla kayıtlı başka bir müşteri zaten var." hatası döner ve kayıt değişmez. Telefonu değiştirdiğinizde o numaraya bağlı notlar, etiketler ve pazarlama izni eski numarada kalır; mevcut siparişlerin alıcı bilgileri de değişmez.

Webhook

Webhook'lar, kargo durumundaki değişikliklerde belirlediğiniz URL'e otomatik HTTP POST isteği gönderir.

⚙️

Yapılandırma: Yönetim Paneli → Ayarlar → Webhook bölümünden URL ve olay tiplerini tanımlayın.

📣

Durum Değişikliği

Ana durum değiştiğinde tetiklenir. NEW → SHIPPED → DELIVERED

🚚

Kargo Hareketi

Her hareket/taşımada tetiklenir. Transfer, şubeye varış, dağıtım.

Durum Değişikliği Webhook'u

POSTYOUR_WEBHOOK_URL

Kargo durumu değiştiğinde gönderilir.

Payload

{
  "id": "XXX-XXX-XXX",
  "orderNumber": "#123456",
  "orderId": "987654321",
  "barcode": "1234567890",
  "status": "SHIPPED",
  "handler": { "name": "Aras Kargo", "code": "ARAS" },
  "handlerShipmentCode": "1234567890"
}

Kargo Hareketi Webhook'u

POSTYOUR_WEBHOOK_URL

Her kargo hareketi/taşımasında gönderilir. Gövde, Sipariş Sorgula yanıtıyla aynı biçimdedir; alan anlamları için bkz. Mevcut Siparişe Kargo Kodu Üret.

Payload

{
  "id": "101-DM2-XYD",
  "barcode": "1234567890",
  "status": "DELIVERED",
  "content": {
    "name": "Ekran Kartı",
    "packages": [{ "height": 25, "width": 10, "depth": 20, "weight": 1 }],
    "totalDesiKg": 2.00
  },
  "sender": { "name": "Gönderici", "phone": "444" },
  "recipient": { "name": "Alıcı", "city": "Yalova", "town": "Merkez" },
  "shipmentInfo": {
    "handler": { "name": "MNG Kargo", "code": "MNG" },
    "handlerShipmentCode": "1234567890",
    "lastState": "Teslim Edildi"
  },
  "priceInfo": { "paymentMethod": "ADVANCE", "shipmentFee": 29.93, "extraServicesFee": 0, "totalCost": 29.93 },   // null alanlar (extraFee, returnFee) webhook gövdesinde yer almaz
  "orderTotal": 349.90,
  "orderPaymentType": "COLLECT_ON_DELIVERY",
  "orderPaymentStatus": null,
  "codInfo": { "collectOnDelivery": true, "type": "CASH", "amount": 349.90, "fee": 12.50, "collectionStatus": "COLLECTED", "collectionStatusText": "Tahsil Edildi, Bakiyenize Aktarılacak", "releaseDate": "2022-08-24" },
  "traces": [
    { "status": "Teslim Edildi", "time": "2022-08-17T18:10:10", "location": "YALOVA" },
    { "status": "Dağıtıma Çıktı", "time": "2022-08-17T12:37:35", "location": "YALOVA" }
  ]
}

Referans Tabloları

Kargo Durum Akışı

✱

YeniNEW

⚙

HazırREADY_TO_SHIP

📦

YoldaSHIPPED

🚚

DağıtımdaOUT_FOR_DELIVERY

✔

TeslimDELIVERED

Kod	Açıklama
`NEW`	Yeni
`READY_TO_SHIP`	Gönderime Hazır
`SHIPPED`	Yolda
`OUT_FOR_DELIVERY`	Dağıtıma Çıkarıldı
`DELIVERED`	Teslim Edildi
`NEEDS_SUPPORT`	Destek Gerekiyor
`DELAYED`	Gecikmeli
`RETURNING`	Geri Dönüyor
`RETURNED`	Geri Döndü
`LOST`	Kayıp

Kargo Firması Kodları

Kod	Firma	Anlaşma
`PTT`	PTT Kargo	Basit Kargo
`MNG`	MNG Kargo	Basit Kargo
`YURTICI`	Yurtiçi Kargo	Basit Kargo
`ARAS`	Aras Kargo	Basit Kargo
`SURAT`	Sürat Kargo	Basit Kargo
`HEPSIJET`	HepsiJET Kargo	Basit Kargo
`KOLAYGELSIN`	KolayGelsin Kargo	Basit Kargo
`BIRGUNDEKARGO`	Birgünde Kargo (bölgesel; yalnız hizmet bölgesindeki adreslerde sunulur)	Basit Kargo
`ECONOMIC`	En Ekonomik	Otomatik
`FAST`	En Hızlı	Otomatik
`SELF_PTT`	PTT Kargo	Kendi Anlaşmanız
`SELF_MNG`	MNG Kargo	Kendi Anlaşmanız
`SELF_YURTICI`	Yurtiçi Kargo	Kendi Anlaşmanız
`SELF_ARAS`	Aras Kargo	Kendi Anlaşmanız
`SELF_SURAT`	Sürat Kargo	Kendi Anlaşmanız

Kargo Ücreti Ödeme Yöntemleri

Kod	Açıklama
`ADVANCE`	Bakiye ile Öde
`CASH`	Nakit (Şubede Ödeme)
`RECIPIENT`	Alıcı Öder

Kargo Tipleri

Kod	Açıklama
`OUTGOING`	Giden Kargo
`INCOMING`	Gelen Kargo

Kapıda Ödeme Türleri

Kod	Açıklama
`CASH`	Nakit
`CREDIT_CARD`	Kredi Kartı (POS)

Sipariş Ödeme Tipleri

Alıcının siparişi nasıl ödediğini/ödeyeceğini belirtir (orderPaymentType). Kapıdaki nakit/kart ayrımı burada değil, collectOnDeliveryType alanındadır.

Kod	Açıklama
`COLLECT_ON_DELIVERY`	Kapıda Ödeme (kargo firması tahsil eder)
`BANK_TRANSFER`	Havale/EFT
`CREDIT_CARD`	Online Ödeme / Sanal POS (kapıdaki kart tahsilatı değil — o `COLLECT_ON_DELIVERY` + `collectOnDeliveryType=CREDIT_CARD`)
`OTHER`	Diğer

Sipariş Ödeme Durumları

Yalnız ön ödemeli tiplerde (orderPaymentStatus). Kapıda ödemeli siparişlerde bu alan daima null döner; tahsilatın durumu codInfo.collectionStatus ile verilir.

Kod	Açıklama
`PAID`	Ödendi
`PENDING`	Ödeme Bekleniyor (örn. gelmemiş havale)
`UNPAID`	Ödenmedi (başarısız / iptal / iade)

Fiyat Teklifi Kodları

Fiyat Teklifi yanıtındaki kodlar. reasons[].code: firmanın bu gönderiyi neden taşıyamadığı (yalnız available=false satırlarda; hesabınıza kapalı firmalar sebep almaz, hiç listelenmez).

Sebep Kodu	Açıklama
`MAX_DESI_EXCEEDED`	Paket desisi kargo firmasının üst sınırını aşıyor.
`MIN_DESI_NOT_MET`	Toplam desi kargo firmasının alt sınırının altında.
`CARGO_TYPE_NOT_SUPPORTED`	Kargo firması bu kargo yönünü (giden/gelen) desteklemiyor.
`PAYMENT_METHOD_NOT_SUPPORTED`	Kargo firması seçilen kargo ücreti ödeme yöntemini desteklemiyor.
`COD_NOT_SUPPORTED`	Kargo firması seçilen kapıda ödeme tipini desteklemiyor.
`COD_AMOUNT_EXCEEDS_LIMIT`	Kapıda ödeme tutarı kargo firmasının limitini aşıyor.
`COD_NOT_AVAILABLE_WITH_RECIPIENT_PAYMENT`	Alıcı Öder seçeneği ile kapıda ödeme hizmeti kullanılamaz.
`NO_COVERAGE_FOR_SENDER`	Kargo firması gönderici adresinin bulunduğu il/ilçeden kargo alımı yapmıyor.
`NO_COVERAGE_FOR_RECIPIENT`	Kargo firması alıcı adresinin bulunduğu il/ilçeye teslimat yapmıyor.
`COVERAGE_UNAVAILABLE`	Kargo firmasının hizmet bölgesi bilgisi henüz yüklenmedi.
`TARIFF_NOT_DEFINED`	Bu desi için kargo firmasının fiyatı tanımlı değil.
`COD_FEE_NOT_DEFINED`	Bu tutar için kargo firmasının kapıda ödeme hizmet bedeli tanımlı değil.

basis.pricingBasis: hangi tarife sütununun uygulandığı.

Kod	Açıklama
`IN_CITY`	Gönderici ve alıcı aynı ilde: şehir içi tarife uygulandı.
`INTERCITY`	Gönderici ve alıcı farklı illerde: şehir dışı (Tüm Türkiye) tarife uygulandı.
`INTERCITY_ASSUMED`	İl bilgisi eksik: şehir dışı tarife varsayıldı; aynı il çıkarsa gerçek fiyat daha düşük olabilir.

basis.firmAddressSource: hesabınıza ait tarafın (giden kargoda gönderici, gelen kargoda alıcı) adresinin nasıl belirlendiği.

Kod	Açıklama
`ORDER`	Adresler orderId ile verilen siparişten alındı.
`ADDRESS_ID`	addressId ile verilen kayıtlı adres kullanıldı.
`TOKEN_ADDRESS`	İstekte adres yok; API anahtarına tanımlı varsayılan adres kullanıldı.
`CITY`	İstekte verilen il/ilçe kullanıldı.
`DEFAULT_ADDRESS`	Adres verilmedi; hesabın varsayılan gönderici adresi kullanıldı.
`NONE`	Adres verilmedi ve kayıtlı adres yok; il bilinmiyor.

Kapıda Tahsilat Durumları

Kapıda ödemeli siparişlerde tahsilatın ve bakiye aktarımının durumu (codInfo.collectionStatus). Kargo durumu ve tahsilat işleminden anlık türetilir; releaseDate aktarımın planlandığı/yapıldığı tarihtir.

Kod	Açıklama
`TO_BE_COLLECTED`	Ödeme Kapıda Tahsil Edilecek — kargo henüz yola çıkmadı (NEW / READY_TO_SHIP)
`COLLECTION_PENDING`	Tahsilat Bekleniyor — kargo yolda, henüz teslim edilmedi
`COLLECTED`	Tahsil Edildi, Bakiyenize Aktarılacak — `releaseDate` tarihinde bakiyeye geçer
`TRANSFERRED`	Bakiyeye Aktarıldı
`COLLECTED_DIRECT`	Tahsil Edildi, Kargo Firması Öder — kendi sözleşmenizle gönderilen kargolarda ödeme kargo firmasından gelir
`NOT_COLLECTED`	Tahsil Edilmedi — iade, kayıp veya iptal

Sıralama Seçenekleri

Kod	Açıklama
`CREATED_TIME`	Oluşturulma zamanı
`UPDATED_TIME`	Güncellenme zamanı
`CODE_GENERATED_TIME`	Kargo kodu üretim zamanı
`SHIPPED_TIME`	Kargoya verilme zamanı
`DELIVERED_TIME`	Teslim edilme zamanı