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 120 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.

Kargo Firmaları

GET /handlers

Aktif kargo firmalarının listesini döndürür.

                    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

Desi/Kg ile Fiyat Sorgulama

GET/handlers/fee/desiKg/{desiKg}

Desi/Kg bilgisi ile tüm firmaların fiyat listesini döndürür.

Parametre	Tip	Zorunlu	Açıklama
desiKg	int	Evet	Desi/Kg değeri (path)
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.

İ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
  }
]

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

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.
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.

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, "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.

Parametre	Tip	Zorunlu	Açıklama
startDate	string	Hayır	Başlangıç tarihi (YYYY-MM-DDTHH:mm:ss)
endDate	string	Hayır	Bitiş tarihi
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.

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

Kullanıcı

GET/firm/balance

Kullanıcı bakiyesini sorgular.

Yanıt200 OK

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.

Müşteriler

Müşteri havuzunuz: bugüne kadar kargo gönderdiğiniz alıcılar, sipariş sayısı ve harcama toplamlarıyla birlikte. Tekrar gönderi oluştururken alıcı bilgilerini buradan çekebilirsiniz.

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": [
    {
      "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; müşteri kimliği olarak phone alanını kullanın. 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.

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.

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": { "shipmentFee": 29.93, "totalCost": 29.93 },
  "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
`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)

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ı