API Dokümantasyonu | Basit Kargo

Başlangıç

Basit Kargo API'sine hoş geldiniz! Bu dokümantasyon, API'mizi kullanmaya başlamanız için ihtiyacınız olan tüm bilgileri içermektedir. RESTful mimarisi ile tasarlanmış API'miz, JSON formatında veri alışverişi yapar ve HTTP metodlarını kullanır.

Önemli Not: API kullanmaya başlamadan önce bir API anahtarı (token) almanız gerekmektedir. Hesap ayarlarınızdan API anahtarınızı oluşturabilirsiniz.

Base URL

Tüm API istekleri aşağıdaki base URL üzerinden yapılmalıdır:

                        Base URL
                    
https://basitkargo.com/api

Dikkat: Lütfen tüm isteklerinizde HTTPS protokolünü kullanın. HTTP üzerinden yapılan istekler kabul edilmeyecektir.

Kimlik Doğrulama

API'miz, güvenli erişim için API anahtarı (token) tabanlı kimlik doğrulama kullanır. Her istek için Authorization header'ında Bearer token olarak API anahtarınızı göndermeniz gerekmektedir.

API Token Kullanımı

cURL

curl -X GET "https://basitkargo.com/api/handlers" \
                        -H "Authorization: Bearer YOUR_API_TOKEN" \
                        -H "Content-Type: application/json"

Kargo Firmaları

GET /handlers

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

Örnek Yanıt

                            JSON
                            200 OK
                        
[
                            {
                            "name": "Aras Kargo",
                            "code": "ARAS",
                            "logo": "https://d24n3wbxi285j5.cloudfront.net/public/basitkargo/logo/aras.png"
                            },
                            {
                            "name": "Yurtiçi Kargo",
                            "code": "YURTICI",
                            "logo": "https://d24n3wbxi285j5.cloudfront.net/public/basitkargo/logo/yurtici.png"
                            },
                            {
                            "name": "Aras Kargo - KA (Kendi Anlaşmam)",
                            "code": "SELF_ARAS",
                            "logo": "https://d24n3wbxi285j5.cloudfront.net/public/basitkargo/logo/aras.png"
                            }
                            ]

Not: Kendi kargo anlaşmalarınızı kullanmak için kod başına SELF_ eklenir; örneğin: SELF_SURAT

Desi/Kg ile Fiyat Sorgulama

GET /handlers/fee/desiKg/{desiKg}

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

Örnek İstek

                            URL
                        
GET /handlers/fee/desiKg/5

Örnek Yanıt

                            JSON
                            200 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çü ve ağırlık bilgileri ile tüm kargo firmalarının fiyat listesini döndürür.

Örnek İstek

JSON

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

Örnek Yanıt

                            JSON
                            200 OK
                        
[
                            {
                            "desiKg": 1,
                            "handlerCode": "MNG",
                            "price": 15.54
                            },
                            {
                            "desiKg": 1,
                            "handlerCode": "YURTICI",
                            "price": 15.54
                            }
                            ]

Kargo Durum Kodları

Servislerde durum ("status") bilgisi altında dönen parametrelerin açıklamaları:

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 (Sorunlu)
`DELAYED`	Gecikmeli
`RETURNING`	Geri Dönüyor
`RETURNED`	Geri Döndü
`LOST`	Kayıp

Kullanım: Bu durum kodları, kargo sorgulama endpointlerinden dönen yanıtlarda "status" alanında bulunur.

Sipariş İşlemleri

POST /v2/order

Sipariş bilgilerini ekler. Daha sonra kargo kodu oluşturabilirsiniz.

Örnek İstek

JSON

{
                            "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" // kapıda ödeme türü: CASH, CREDIT_CARD
                            }

Örnek Yanıt

                            JSON
                            200 OK
                        
{
                            "id": "888-6AR-OUP",
                            "barcode": null,
                            "type": "OUTGOING",
                            "status": "NEW",
                            "validationFailed": false,
                            "validationFailedMessage": null,
                            "createdTime": "2023-01-01T15:41:47.7553603",
                            "updatedTime": "2023-01-01T15:41:47.7633629"
                            }

POST /v2/order/barcode

Sipariş bilgilerini ekler ve belirtilen kargo firması için kargo kodu (barkod) üretir.

Özel Kullanımlar:

Kendi kargo anlaşmanızı kullanmak için handlerCode değerinin başına SELF_ ekleyin (örn: SELF_SURAT)
En düşük fiyatlı firma ile otomatik göndermek için handlerCode değerine ECONOMIC girin
En hızlı gönderim için handlerCode değerine FAST girin

Request Body

Önceki endpoint ile aynı parametreler + handlerCode parametresi

Alan	Tip	Zorunlu	Açıklama
handlerCode	string	Evet	Kargo firması kodu (ARAS, MNG, YURTICI, SURAT, ECONOMIC, FAST)

Örnek İstek

JSON

{
                            "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 filtreleyerek listeler. Tüm parametreler opsiyoneldir, boş body ile tüm siparişleri getirir.

Request Parametreleri

Parametre	Tip	Zorunlu	Açıklama
startDate	string	Hayır	Başlangıç tarihi (ISO 8601 Format) Format: YYYY-MM-DDTHH:mm:ss Örnek: "2024-01-01T00:00:00"
endDate	string	Hayır	Bitiş tarihi (ISO 8601 Format) Format: YYYY-MM-DDTHH:mm:ss Örnek: "2024-12-31T23:59:59"
statusList	array[string]	Hayır	Kargo durum kodları listesi (NEW, READY_TO_SHIP, SHIPPED, vb.)
handlerCode	string	Hayır	Kargo firması kodu (ARAS, MNG, YURTICI, SURAT, vb.)
sortBy	string	Hayır	Sıralama kriteri (CREATED_TIME, UPDATED_TIME, STATUS)
page	integer	Hayır	Sayfa numarası (varsayılan: 0)
size	integer	Hayır	Sayfa başına kayıt sayısı (varsayılan: 20, max: 100)

Örnek İstek

JSON

{
                            "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 sipariş 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.

Sipariş Kargo Kodu İptal

DELETE /order/barcode/{barcode}

Kargo şubesine teslim edilmemiş siparişi 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ş barkodunu (etiketini) SVG formatında indirir.

Konum Bilgileri

GET /country/TR/cities

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

Örnek Yanıt

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

GET /city/{id}/towns

Şehre ait ilçe listesini döndürür.

Örnek İstek

                            URL
                        
GET /city/32/towns

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

İlçeye ait köy/mahalle listesini döndürür.

Örnek İstek

                            URL
                        
GET /city/Isparta/town/Yalvaç/neigborhoods

Kullanıcı İşlemleri

GET /user/balance

Kullanıcı bakiyesini sorgular.

Örnek Yanıt

Webhook

Webhook'lar, Basit Kargo'da gerçekleşen olaylar hakkında sizi anlık olarak bilgilendiren otomatik HTTP POST istekleridir. Kargo durumundaki değişiklikler veya hareketler gerçekleştiğinde, sistem sizin belirlediğiniz URL'e JSON formatında bildirim gönderir.

Webhook Yapılandırması:

Webhook ayarlarınızı yapılandırmak için Basit Kargo Yönetim Paneline giriş yapın ve Ayarlar > Webhook bölümünden:

Webhook URL'inizi tanımlayın
Hangi olay tiplerini almak istediğinizi seçin
Webhook'u kaydedin

Webhook Tipleri

Basit Kargo'da 2 farklı tipte webhook bulunur:

Durum Değişikliği

Kargonun ana durumu değiştiğinde tetiklenir.

Örnek: NEW → READY_TO_SHIP → SHIPPED → COMPLETED

Kargo Hareketi

Her kargo hareketi/taşımasında tetiklenir.

Örnek: Transfer merkezi değişimi, şubeye varış, dağıtıma çıkış

Durum Değişikliği Webhook'u

POST YOUR_WEBHOOK_URL

Kargo durumu değiştiğinde (örn: Yeni → Gönderime Hazır) sisteminize gönderilir.

Webhook Payload Örneği

JSON

{
                            "id":"XXX-XXX-XXX",
                            "barcode":"1234567890",
                            "status":"SHIPPED",
                            "handler":{"name":"Aras Kargo","code":"ARAS","logo":"aras.png"},
                            "handlerShipmentCode":"1234567890"
                            }

Kargo Hareketi Webhook'u

POST YOUR_WEBHOOK_URL

Her kargo hareketi/taşımasında (transfer merkezi değişimi, şubeye varış vb.) sisteminize gönderilir.

Webhook Payload Örneği

JSON

{
                            "id": "101-DM2-XYD",
                            "barcode": "1234567890",
                            "type": "OUTGOING",
                            "status": "COMPLETED",
                            "validationFailed": false,
                            "validationFailedMessage": "",
                            "createdTime": "2022-07-28T20:01:21",
                            "updatedTime": "2022-08-14T18:12:24",
                            "content": {
                            "name": "Ekran Kartı",
                            "code": "#123456",
                            "packages": [
                            {
                            "height": 25,
                            "width": 10,
                            "depth": 20,
                            "weight": 1,
                            "kgDesi": 2
                            }
                            ],
                            "totalDesiKg": 2.00
                            },
                            "sender": {
                            "name": "Gönderici Adı",
                            "phone": "4444444444"
                            },
                            "recipient": {
                            "name": "Alıcı Adı",
                            "phone": "5555555555",
                            "city": "Yalova",
                            "town": "Merkez",
                            "address": "açık adres"
                            },
                            "shipmentInfo": {
                            "handler": {
                            "name": "MNG Kargo",
                            "code": "MNG",
                            "logo": "mng.png"
                            },
                            "handlerShipmentCode": "1234567890",
                            "handlerShipmentTrackingLink": "https://kargotakip.mngkargo.com.tr/?takipNo=1234567890",
                            "handlerDesi": 5.00,
                            "lastState": "Teslim Edildi",
                            "shippedTime": "2022-07-28T20:01:21",
                            "deliveredTime": null
                            },
                            "priceInfo": {
                            "paymentMethod": "ADVANCE",
                            "shipmentFee": 29.93,
                            "extraFee": null,
                            "totalCost": 29.93
                            },
                            "traces": [
                            {
                            "status": "Teslim Edildi",
                            "time": "2022-08-17T18:10:10",
                            "location": "YALOVA (MERKEZ)",
                            "locationDetail": "MİMOZA Şube"
                            },
                            {
                            "status": "Gönderi Adresinize Yönlendirildi",
                            "time": "2022-08-17T12:37:35",
                            "location": "YALOVA (MERKEZ)",
                            "locationDetail": "MİMOZA Şube"
                            },
                            {
                            "status": "Gönderi Varış Birimine Ulaştı",
                            "time": "2022-08-17T09:46:43",
                            "location": "YALOVA (MERKEZ)",
                            "locationDetail": "MİMOZA Şube"
                            },
                            {
                            "status": "Transfer Aşamasında",
                            "time": "2022-08-17T09:46:42",
                            "location": "YALOVA (MERKEZ)",
                            "locationDetail": "MİMOZA Şube"
                            },
                            {
                            "status": "Transfer Aşamasında",
                            "time": "2022-08-17T01:47:28",
                            "location": "BURSA",
                            "locationDetail": "BURSA AKTARMA"
                            },
                            {
                            "status": "Transfer Aşamasında",
                            "time": "2022-08-16T21:07:04",
                            "location": "İSTANBUL",
                            "locationDetail": "MARMARA AKTARMA"
                            },
                            {
                            "status": "Transfer Aşamasında",
                            "time": "2022-08-16T15:14:19",
                            "location": "İSTANBUL (KADIKÖY)",
                            "locationDetail": "HASANPAŞA Şube"
                            },
                            {
                            "status": "Gönderi Hazırlandı",
                            "time": "2022-08-16T09:53:09",
                            "location": "İSTANBUL (KADIKÖY)",
                            "locationDetail": "HASANPAŞA Şube"
                            }
                            ]
                            }

Kargo Firması Kodları (HandlerCode)

API'de kullanılabilecek tüm kargo firması kodları:

Kod	Açıklama	Anlaşma Tipi
`PTT`	PTT Kargo	Basit Kargo Anlaşması
`MNG`	MNG Kargo	Basit Kargo Anlaşması
`YURTICI`	Yurtiçi Kargo	Basit Kargo Anlaşması
`ARAS`	Aras Kargo	Basit Kargo Anlaşması
`SURAT`	Sürat Kargo	Basit Kargo Anlaşması
`ECONOMIC`	En Ekonomik Firma (Otomatik Seçim)	Sistem Otomatiği
`FAST`	En Hızlı Firma (Otomatik Seçim)	Sistem Otomatiği
`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

Not: SELF_ ile başlayan kodlar, kendi kargo firması anlaşmanızı kullanmak istediğinizde kullanılır. Bu durumda Basit Kargo'nun anlaşması değil, sizin kargo firması ile yaptığınız özel anlaşma geçerli olur.

Ödeme Yöntemleri (PaymentMethod)

Kargo ödemesi için kullanılabilecek ödeme yöntemleri:

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

Kargo Tipleri (CargoType)

Kargonun yönüne göre tipler:

Kod	Açıklama
`OUTGOING`	Giden Kargo (Sizden müşteriye gönderilen kargo)
`INCOMING`	Gelen Kargo (Size gelen kargo)

Kapıda Ödeme Türleri (CollectOnDeliveryType)

Kapıda ödeme yapılacaksa, ödeme türü:

Kod	Açıklama
`CASH`	Nakit ile Kapıda Ödeme
`CREDIT_CARD`	Kredi Kartı ile Kapıda Ödeme (POS)

Sıralama Seçenekleri (CargoSortBy)

Sipariş listelerken kullanılabilecek sıralama kriterleri:

Kod	Açıklama	Alan
`CREATED_TIME`	Oluşturulma Zamanı	Siparişin sisteme eklendiği tarih/saat
`UPDATED_TIME`	Güncellenme Zamanı	Siparişin son güncellenme tarih/saat
`CODE_GENERATED_TIME`	Kargo Kodu Üretim Zamanı	Barkod/takip numarasının oluşturulduğu tarih/saat
`SHIPPED_TIME`	Kargoya Verilme Zamanı	Kargonun şubeye teslim edildiği tarih/saat
`DELIVERED_TIME`	Teslim Edilme Zamanı	Kargonun alıcıya teslim edildiği tarih/saat

Genel Bilgiler

Kargo Firmaları

Sipariş İşlemleri

Konum Bilgileri

Kullanıcı

Webhook

Durum Kodları

Parametre Detayları

Başlangıç

Base URL

Kimlik Doğrulama

API Token Kullanımı

Kargo Firmaları

Örnek Yanıt

Desi/Kg ile Fiyat Sorgulama

Örnek İstek

Örnek Yanıt

Paket Bilgileri ile Fiyat Sorgulama

Örnek İstek

Örnek Yanıt

Kargo Durum Kodları

Sipariş İşlemleri

Örnek İstek

Örnek Yanıt

Request Body

Örnek İstek

Sipariş Listele/Filtrele

Request Parametreleri

Örnek İstek

Sipariş Sorgula (ID)

Sipariş Sorgula (Barkod)

Sipariş Sorgula (Takip No)

Sipariş Kargo Kodu İptal

İade Oluştur

Etiket İndir

Konum Bilgileri

Örnek Yanıt

Örnek İstek

Örnek İstek

Kullanıcı İşlemleri

Örnek Yanıt

Webhook

Webhook Tipleri

Durum Değişikliği Webhook'u

Webhook Payload Örneği

Kargo Hareketi Webhook'u

Webhook Payload Örneği

Kargo Firması Kodları (HandlerCode)

Ödeme Yöntemleri (PaymentMethod)

Kargo Tipleri (CargoType)

Kapıda Ödeme Türleri (CollectOnDeliveryType)

Sıralama Seçenekleri (CargoSortBy)