API Dokümantasyonu | Basit Kargo

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()

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.

Yanıt200 OK

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

Paket Bilgileri ile Fiyat Sorgulama

POST/handlers/fee/packages

Paket ölçüleri ile fiyat listesini döndürür.

İstek Gövdesi

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

Yanıt200 OK

[
  { "desiKg": 1, "handlerCode": "MNG", "price": 15.54 }
]

Sipariş İşlemleri

POST/v2/order

Yeni sipariş oluşturur. Kargo kodu ayrıca üretilebilir.

                    
                    
                
{
  "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",
    "city": "İstanbul",
    "town": "Kadıköy",
    "address": "Koşuyolu Mah."
  },
  "collect": 100,             // kapıda ödeme tutarı
  "collectOnDeliveryType": "CASH"  // CASH veya CREDIT_CARD
}
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

İstek Gövdesi

{
  "handlerCode": "SURAT",
  "content": {
    "name": "Test Sipariş",
    "code": "#123456",
    "packages": [{ "height": 10, "width": 15, "depth": 5, "weight": 1 }]
  },
  "client": {
    "name": "Test Alıcı",
    "phone": "5555555555",
    "city": "İstanbul",
    "town": "Kadıköy",
    "address": "Koşuyolu Mah."
  },
  "collect": 100
}

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
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ş siparişin kargo kodunu iptal eder.

İ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

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 → COMPLETED

🚚

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",
  "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": "COMPLETED",
  "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 },
  "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

✔

TeslimCOMPLETED

Kod	Açıklama
`NEW`	Yeni
`READY_TO_SHIP`	Gönderime Hazır
`SHIPPED`	Yolda
`OUT_FOR_DELIVERY`	Dağıtıma Çıkarıldı
`COMPLETED`	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
`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

Ö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)

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ı

Basit Kargo API

Base URL

Kimlik Doğrulama

Kargo Firmaları

Desi/Kg ile Fiyat Sorgulama

Paket Bilgileri ile Fiyat Sorgulama

Sipariş İşlemleri

Sipariş Oluştur + Kargo Kodu Üret

Sipariş Listele / Filtrele

Sipariş Sorgula (ID)

Sipariş Sorgula (Barkod)

Sipariş Sorgula (Takip No)

Kargo Kodu İptal

İade Oluştur

Etiket İndir

Konum Bilgileri

İlçeler

Mahalleler

Kullanıcı

Webhook

Durum Değişikliği

Kargo Hareketi

Durum Değişikliği Webhook'u

Kargo Hareketi Webhook'u

Referans Tabloları

Kargo Durum Akışı

Kargo Firması Kodları

Ödeme Yöntemleri

Kargo Tipleri

Kapıda Ödeme Türleri

Sıralama Seçenekleri