İçindekiler
Yeni Yazılar

Kargonomi API Nedir ?

Kargonomi API, Kargonomi paneli üzerinden gerçekleştirilen işlemleri otomatikleştirmenizi sağlayan bir ara yüz sunar. Bu API sayesinde, Kargonomi’nin sunduğu hizmetleri doğrudan kendi uygulamalarınıza entegre edebilir, kargo süreçlerinizi daha verimli ve esnek bir şekilde yönetebilirsiniz.

Base URL

Kargonomi API’ye erişim sağlamak için kullanmanız gereken temel URL bilgisi aşağıdaki gibidir:


https://app.kargonomi.com.tr/api/v1

Kimlik Doğrulama

Kargonomi API, Bearer Token yöntemi ile kimlik doğrulama yapmaktadır. Her istekte, “Authorization“ başlığı altında Bearer Token’ınızı göndermeniz gerekmektedir. Bearer Token, kullanıcı kimliğinizi doğrulamak ve API erişimini sağlamak için kullanılır.

Hemen Kargonomi ile Tanışın!

E-ticaret ve bireysel kargolarınızı uygun fiyatlara göndermek için Kargonomi'yi hemen şimdi ücretsiz deneyebilirsiniz.

Hemen Deneyin!
₺
'den başlayan fiyatlarla

Authorization Başlığı

Her API isteğinde aşağıdaki başlık (header) eklenmelidir:

Authorization: Bearer <token>

Not :

Kargonomi API’yi kullanacak olan partner firmalar, her istekte Bearer Token’a ek olarak X-App-Key değerini de göndermelidir. Detaylı bilgi için Partner API Dokümanı sayfasını ziyaret edebilirsiniz.

Endpointler

Gönderiler

{{base_url}}/shipments - GET

Bu endpoint, tüm kargo gönderilerini listelemek için kullanılır. Sayfalama özelliği mevcuttur ve her sayfada 50 adet gönderi listelenir.

ParametreTürZorunluAçıklama
pageintHayırSayfalama için kullanılır
curl --location 'https://app.kargonomi.com.tr/api/v1/shipments' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer 0htoc1aNkVJhE6mDB0qZhVy69HCIuXzFGM3NOBhu17df3eb6'

Örnek Response :

{
    "data": [
        {
            "id": 1,
            "type": "shipment",
            "shipping_webservice_order_id": null,
            "shipping_webservice_barcode": null,
            "shipping_webservice_tracking_code": null,
            "shipping_provider_name": null,
            "shipping_provider_slug": null,
            "barcode_of_order_id": null,
            "status": "draft",
            "status_label": "Taslak",
            "shipping_webservice_created_at": null,
            "ecommerce_provider_order_no": null,
            "ecommerce_provider": null,
            "package_count": 1,
            "estimated_price": null,
            "real_price": null,
            "extra_shipping_price": "0.0000",
            "buyer_name": "Test Buyer Name",
            "delivery_date_to_shipment_office": null,
            "shipping_provider_customer_delivery_date": null,
            "created_at": "2024-06-18T20:18:06.000000Z",
            "updated_at": "2024-06-18T20:18:06.000000Z",
            "sender": {
                "sender_name": "Test Sender Name",
                "sender_email": "test@mail.com",
                "sender_phone": "5555555555",
                "sender_phone2": null,
                "sender_tax_number": "11111111111",
                "sender_tax_place": "Vergi Dairesi Yok",
                "sender_address": "Test Sender Address Test Sender Address",
                "sender_state": "İSTANBUL",
                "sender_city": "ÜSKÜDAR"
            },
            "buyer": {
                "buyer_name": "Test Buyer Name",
                "buyer_email": null,
                "buyer_phone": "5555555555",
                "buyer_phone2": null,
                "buyer_tax_number": null,
                "buyer_tax_place": null,
                "buyer_address": "Test Buyer Address Test Buyer Address",
                "buyer_state": "İSTANBUL",
                "buyer_city": "AVCILAR"
            },
            "pricing": {
                "package_count": 1,
                "estimated_price": null,
                "real_price": null,
                "extra_shipping_price": "0.0000",
                "price_diff": null
            },
            "warehouse": {
                "id": 12707,
                "name": "Merkez Depo",
                "is_main": 1,
                "contact_name": "Ali Yılmaz",
                "contact_phone": "5565465465",
                "state": "İstanbul",
                "city": "Üsküdar",
                "address": "cumhuriyet mah. vatan sokak no:4",
                "phone": null,
                "tax_number": "98328113892",
                "tax_place": "Acısu"
            },
            "shipment_packages": [
                {
                    "desi": "1",
                    "barcode": "1MEVK1_1",
                    "content": null,
                    "real_desi": null
                }
            ]
        }
    ],
    "links": {
        "first": "https://app.kargonomi.com.tr/api/v1/shipments?page=1",
        "last": "https://app.kargonomi.com.tr/api/v1/shipments?page=1",
        "prev": null,
        "next": null
    },
    "meta": {
        "current_page": 1,
        "from": 1,
        "last_page": 1,
        "links": [
            {
                "url": null,
                "label": "&laquo; Önceki",
                "active": false
            },
            {
                "url": "https://app.kargonomi.com.tr/api/v1/shipments?page=1",
                "label": "1",
                "active": true
            },
            {
                "url": null,
                "label": "Sonraki &raquo;",
                "active": false
            }
        ],
        "path": "https://app.kargonomi.com.tr/api/v1/shipments",
        "per_page": 50,
        "to": 1,
        "total": 1
    }
}

Gönderi Detayı

{{base_url}}/shipments/{id} - GET

Bu endpoint, belirli bir kargo gönderisinin detaylarını görüntülemek için kullanılır.

curl --location 'https://app.kargonomi.com.tr/api/v1/shipments/{id}' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer 0htoc1aNkVJhE6mDB0qZhVy69HCIuXzFGM3NOBhu17df3eb6'

Örnek Response : 

{
    "id": 1,
    "type": "shipment",
    "shipping_webservice_order_id": null,
    "shipping_webservice_barcode": null,
    "shipping_webservice_tracking_code": null,
    "shipping_provider_name": null,
    "shipping_provider_slug": null,
    "barcode_of_order_id": null,
    "status": "draft",
    "status_label": "Taslak",
    "shipping_webservice_created_at": null,
    "ecommerce_provider_order_no": null,
    "ecommerce_provider": null,
    "package_count": 1,
    "estimated_price": null,
    "real_price": null,
    "extra_shipping_price": "0.0000",
    "delivery_date_to_shipment_office": null,
    "shipping_provider_customer_delivery_date": null,
    "created_at": "2024-06-18T20:18:06.000000Z",
    "updated_at": "2024-06-18T20:18:06.000000Z",
    "sender": {
        "sender_name": "Test Sender Name",
        "sender_email": "test@mail.com",
        "sender_phone": "5555555555",
        "sender_phone2": null,
        "sender_tax_number": "11111111111",
        "sender_tax_place": "Vergi Dairesi Yok",
        "sender_address": "Test Street, Test City, 12345",
        "sender_state": "İSTANBUL",
        "sender_city": "ÜSKÜDAR"
    },
    "buyer": {
        "buyer_name": "Test Buyer Name",
        "buyer_email": null,
        "buyer_phone": "5555555555",
        "buyer_phone2": null,
        "buyer_tax_number": null,
        "buyer_tax_place": null,
        "buyer_address": "Buyer Street, Buyer City, 12345",
        "buyer_state": "İSTANBUL",
        "buyer_city": "AVCILAR"
    },
    "pricing": {
        "package_count": 1,
        "estimated_price": null,
        "real_price": null,
        "extra_shipping_price": "0.0000",
        "price_diff": null
    },
    "warehouse": {
         "id": 12707,
         "name": "Merkez Depo",
         "is_main": 1,
         "contact_name": "Ali Yılmaz",
         "contact_phone": "5565465465",
         "state": "İstanbul",
         "city": "Üsküdar",
         "address": "cumhuriyet mah. vatan sokak no:4",
         "phone": null,
         "tax_number": "98328113892",
         "tax_place": "Acısu"
    },
    "shipment_packages": [
        {
            "desi": "1",
            "barcode": "1MEVK1_1",
            "content": null,
            "real_desi": null
        }
    ]
}

Gönderi Oluşturma

{{base_url}}/shipments - POST

Bu endpoint, kargo gönderisi oluşturmak için kullanılır. Aynı anda birden fazla gönderi oluşturulabilir.

ParametreTürZorunluAçıklama
shipment.sender_namestringwarehouse_id varsa – HayırGönderici adı (min: 5, max: 255 karakter)
shipment.sender_emailstringwarehouse_id varsa – HayırGönderici email (geçerli email formatında, max: 255 karakter)
shipment.sender_tax_numberstringwarehouse_id varsa – HayırGönderici vergi / kimlik No (min: 10, max: 11 karakter)
shipment.sender_tax_placeintegerwarehouse_id varsa – HayırGönderici vergi dairesi (max: 20 karakter)
shipment.sender_phoneintegerwarehouse_id varsa – HayırGönderici telefon numarası (10 karakter)
shipment.sender_addressstringwarehouse_id varsa – HayırGönderici adresi (min: 10, max: 512 karakter)
shipment.sender_state_idintegerwarehouse_id varsa – HayırGönderici şehir kimliği (mevcut şehir kimlikleri ile eşleşmeli)
shipment.sender_city_idintegerwarehouse_id varsa – HayırGönderici ilçe kimliği (mevcut ilçe kimlikleri ile eşleşmeli)
shipment.warehouse_idintegerHayırGönderici Adres ID – warehouse_id yollanması durumunda gönderici adres bilgisi Warehouse’dan çekilecektir.
shipment.buyer_namestringEvetAlıcının adı (min: 5, max: 255 karakter, en az 2 kelime)
shipment.buyer_emailstringHayır
Alıcının e-posta adresi (geçerli email formatında, max: 255 karakter)
shipment.buyer_tax_numberstringHayırAlıcının vergi numarası (min: 10, max: 11 karakter)
shipment.buyer_tax_placestringHayırAlıcının vergi dairesi (max: 20 karakter)
shipment.buyer_phonestringEvetAlıcının telefon numarası (10 karakter)
shipment.buyer_addressstringEvetAlıcının adresi (min: 10, max: 512 karakter)
shipment.buyer_state_idintegerEvetAlıcının şehir kimliği (mevcut şehir kimlikleri ile eşleşmeli)
shipment.buyer_city_idintegerEvetAlıcının ilçe kimliği (mevcut ilçe kimlikleri ile eşleşmeli)
shipment.packagesarrayEvetGönderiye ait paket detayları içeren bir dizi (en az 1 öğe)
shipment.packages.*.contentstringHayırPaket içeriği
shipment.packages.*.barcodestringHayırPaket barkodu
shipment.packages.*.desinumericEvetPaket desi değeri (0’dan büyük)
curl --location 'https://app.kargonomi.com.tr/api/v1/shipments' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer 0htoc1aNkVJhE6mDB0qZhVy69HCIuXzFGM3NOBhu17df3eb6' \
--data-raw '{
  "shipment": {
    "sender_name": "Test Sender",
    "sender_email": "testsender@example.com",
    "sender_tax_number": "1234567890",
    "sender_tax_place": "Test Place",
    "sender_phone": "5555555555",
    "sender_address": "Test Street, Test City, 12345",
    "sender_state_id": "34",
    "sender_city_id": "828",
    //"warehouse_id": "12707", opsiyonel
    "buyer_name": "Test Buyer",
    "buyer_email": "testbuyer@example.com",
    "buyer_tax_number": "",
    "buyer_tax_place": "",
    "buyer_phone": "5555555555",
    "buyer_address": "Buyer Street, Buyer City, 12345",
    "buyer_state_id": "66",
    "buyer_city_id": "662",
    "packages": [
        {
        "content": "Test Content",
        "barcode": "",
        "desi": "1"
        }
    ]
  }
}'

Örnek Response :

{
    "id": 1,
    "type": "shipment",
    "shipping_webservice_order_id": null,
    "shipping_webservice_barcode": null,
    "shipping_webservice_tracking_code": null,
    "shipping_provider_name": null,
    "shipping_provider_slug": null,
    "barcode_of_order_id": null,
    "status": "draft",
    "status_label": "Taslak",
    "shipping_webservice_created_at": null,
    "ecommerce_provider_order_no": null,
    "ecommerce_provider": null,
    "package_count": 1,
    "estimated_price": null,
    "real_price": null,
    "extra_shipping_price": "0.0000",
    "delivery_date_to_shipment_office": null,
    "shipping_provider_customer_delivery_date": null,
    "created_at": "2024-06-18T20:18:06.000000Z",
    "updated_at": "2024-06-18T20:18:06.000000Z",
    "sender": {
        "sender_name": "Test Sender Name",
        "sender_email": "test@mail.com",
        "sender_phone": "5555555555",
        "sender_phone2": null,
        "sender_tax_number": "11111111111",
        "sender_tax_place": "Vergi Dairesi Yok",
        "sender_address": "Test Street, Test City, 12345",
        "sender_state": "İSTANBUL",
        "sender_city": "ÜSKÜDAR"
    },
    "buyer": {
        "buyer_name": "Test Buyer Name",
        "buyer_email": null,
        "buyer_phone": "5555555555",
        "buyer_phone2": null,
        "buyer_tax_number": null,
        "buyer_tax_place": null,
        "buyer_address": "Buyer Street, Buyer City, 12345",
        "buyer_state": "İSTANBUL",
        "buyer_city": "AVCILAR"
    },
    "pricing": {
        "package_count": 1,
        "estimated_price": null,
        "real_price": null,
        "extra_shipping_price": "0.0000",
        "price_diff": null
    },
    "warehouse": {
         "id": 12707,
         "name": "Merkez Depo",
         "is_main": 1,
         "contact_name": "Ali Yılmaz",
         "contact_phone": "5565465465",
         "state": "İstanbul",
         "city": "Üsküdar",
         "address": "cumhuriyet mah. vatan sokak no:4",
         "phone": null,
         "tax_number": "98328113892",
         "tax_place": "Acısu"
    },
    "shipment_packages": [
        {
            "desi": "1",
            "barcode": "1MEVK1_1",
            "content": null,
            "real_desi": null
        }
    ]
}

Gönderi Güncelleme

{{base_url}}/shipments/{id} - PUT

Bu endpoint, kargo gönderisini güncellemek için kullanılır. Gönderi oluşturulurken uygulanan doğrulama kuralları, bu endpoint için de geçerlidir.

curl --location --request PUT 'https://app.kargonomi.com.tr/api/v1/shipments/{id}' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer 0htoc1aNkVJhE6mDB0qZhVy69HCIuXzFGM3NOBhu17df3eb6' \
--data-raw '{
  "shipment": {
    "sender_name": "Test Sender",
    "sender_email": "testsender@example.com",
    "sender_tax_number": "1234567890",
    "sender_tax_place": "Test Place",
    "sender_phone": "5555555555",
    "sender_address": "Test Street, Test City, 12345",
    "sender_state_id": "34",
    "sender_city_id": "828",
    //"warehouse_id": "123", opsiyonel
    "buyer_name": "Test Buyer",
    "buyer_email": "testbuyer@example.com",
    "buyer_tax_number": "",
    "buyer_tax_place": "",
    "buyer_phone": "5555555555",
    "buyer_address": "Buyer Street, Buyer City, 12345",
    "buyer_state_id": "66",
    "buyer_city_id": "662",
    "packages": [
        {
        "content": "Test Content",
        "barcode": "",
        "desi": "1"
        }
    ]
  }
}'

Gönderi Güncelleme – PATCH

{{base_url}}/shipments/{id} - PATCH

Bu endpoint, mevcut bir kargo gönderisine ait bilgilerin kısmi olarak güncellenmesi için kullanılır.
Yalnızca gönderilen alanlar güncellenir; diğer alanlar mevcut değerlerini korur.

Gönderi oluşturulurken uygulanan doğrulama kuralları, bu endpoint için de geçerlidir.

Not: Tüm gönderi verilerini baştan güncellemek için PUT endpoint’i kullanılmalıdır.

curl --location --request PATCH 'https://app.kargonomi.com.tr/api/v1/shipments/{id}' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer 0htoc1aNkVJhE6mDB0qZhVy69HCIuXzFGM3NOBhu17df3eb6' \
--data-raw '{
  "shipment": {
    "buyer_name": "Yeni Alıcı Adı",
    "buyer_phone": "5551234567",
    "buyer_address": "Yeni Adres, İstanbul, 34000",
    "packages": [
      {
        "content": "Güncellenmiş İçerik",
        "desi": "2"
      }
    ]
  }
}'

Gönderi Silme

{{base_url}}/shipments/{id} - DELETE

Bu endpoint, belirli bir kargo gönderisini silmek için kullanılır.

curl --location --request DELETE 'https://app.kargonomi.com.tr/api/v1/shipments/{id}' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer 0htoc1aNkVJhE6mDB0qZhVy69HCIuXzFGM3NOBhu17df3eb6'

Gönderiyi Hazır Hale Getirme

{{base_url}}/confirm-shipping-price - POST

Bu endpoint, bir önceki endpointte alınan fiyat teklifleri arasından seçilen kargo firmasını gönderi ile eşleştirerek gönderiyi hazır hale getirmenizi sağlar. Aşağıdaki ID değerleri”Fiyat Teklifi Alma” endpointinden dönen response dan alınmalıdır.

ParametreTürZorunluAçıklama
shipment_idintEvetKargo Gönderisinin ID Değeri
shipping_provider_idintEvetKargo Firmasının ID Değeri
curl --location 'https://app.kargonomi.com.tr/api/v1/confirm-shipping-price' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer 0htoc1aNkVJhE6mDB0qZhVy69HCIuXzFGM3NOBhu17df3eb6' \
--form 'shipment_id="{shipmentId}"' \
--form 'shipping_provider_id="{shippingProviderId}"'

Örnek Response :

{
    "shipping_provider_with_price": [
        {
            "id": 3,
            "name": "Kolay Gelsin",
            "slug": "kolaygelsin",
            "price": "22.67 + KDV"
        },
        {
            "id": 4,
            "name": "Aras Kargo",
            "slug": "aras",
            "price": "22.67 + KDV"
        },
        {
            "id": 5,
            "name": "Sürat Kargo",
            "slug": "surat",
            "price": "22.67 + KDV"
        },
        {
            "id": 6,
            "name": "Hepsijet",
            "slug": "hepsijet",
            "price": "Hizmet Dışı Bölge"
        },
        {
            "id": 7,
            "name": "PTT Kargo",
            "slug": "ptt",
            "price": "22.67 + KDV"
        },
        {
            "id": "-1",
            "name": "Otomatik",
            "slug": "otomatik",
            "price": null
        }
    ],
    "shipment": {
        "id": 8,
        "type": "shipment",
        "shipping_webservice_order_id": null,
        "shipping_webservice_barcode": null,
        "shipping_webservice_tracking_code": null,
        "shipping_provider_name": null,
        "shipping_provider_slug": null,
        "barcode_of_order_id": null,
        "status": "draft",
        "status_label": "Taslak",
        "shipping_webservice_created_at": null,
        "ecommerce_provider_order_no": null,
        "ecommerce_provider": null,
        "package_count": 1,
        "estimated_price": null,
        "real_price": null,
        "extra_shipping_price": "0.0000",
        "buyer_name": "Test Buyer Name",
        "delivery_date_to_shipment_office": null,
        "shipping_provider_customer_delivery_date": null,
        "created_at": "2024-06-25T09:36:32.000000Z",
        "updated_at": "2024-06-25T09:36:35.000000Z",
        "sender": {
            "sender_name": "Test Sender Name",
            "sender_email": "test@mail.com",
            "sender_phone": "5555555555",
            "sender_phone2": null,
            "sender_tax_number": "11111111111",
            "sender_tax_place": "Üsküdar",
            "sender_address": "Sender Street, Sender City, 12345",
            "sender_state": "İSTANBUL",
            "sender_city": "ÜSKÜDAR"
        },
        "buyer": {
            "buyer_name": "Test Buyer Name",
            "buyer_email": "test@mail.com",
            "buyer_phone": "5555555555",
            "buyer_phone2": null,
            "buyer_tax_number": null,
            "buyer_tax_place": null,
            "buyer_address": "Buyer Street, Buyer City, 12345",
            "buyer_state": "İSTANBUL",
            "buyer_city": "ARNAVUTKÖY"
        },
        "pricing": {
            "package_count": 1,
            "estimated_price": null,
            "real_price": null,
            "extra_shipping_price": "0.0000",
            "price_diff": null
        },
        "shipment_packages": [
            {
                "desi": "1",
                "barcode": "JRJ3PA_1",
                "content": "Defter",
                "real_desi": null
            }
        ]
    }
}

Not : shipping_provider_id değeri eğer -1 olarak gönderilirse otomatik olarak en düşük fiyat teklifi veren kargo firması seçilecektir.

Gönderiyi İptal Etme

{{base_url}}/shipments/cancel - POST

Bu endpoint, “İşleme Hazır” hale getirilmiş fakat henüz kargoya verilmemiş gönderilerin iptali için kullanılır. İptal işlemi, sistem tarafından 36 saat içinde teknik süreç tamamlandıktan sonra uygulanır.

curl --location --request POST 'https://app.kargonomi.com.tr/api/v1/shipments/cancel' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer 0htoc1aNkVJhE6mDB0qZhVy69HCIuXzFGM3NOBhu17df3eb6' \
--data-raw '{
    "shipment_id": "1"
}'

Örnek Response : 

{
    "message": "Gönderi için iptal talebiniz alındı. Teknik nedenlerden dolayı iptal işlemi 36 saat içinde yapılacaktır.",
    "shipment_id": 1
}

Depo Kaydı

{{base_url}}/warehouses
curl --location 'https://app.kargonomi.com.tr/api/v1/warehouses' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer 0htoc1aNkVJhE6mDB0qZhVy69HCIuXzFGM3NOBhu17df3eb6' \
--data '{
    "warehouse": {
        "name": "Ev Adresim",
        "is_main": true,
        "contact_name": "Ali Yılmaz",
        "address": "cumhuriyet mah. vatan sokak no:4",
        "contact_phone": "5454545451",
        "state_id": "41",
        "city_id": "580",
        "tax_number": "14792973114"
    }
}'

Barkod Çıktısı Alma

{{base_url}}/shipments/{id}/barcode - GET

Oluşturulan kargo gönderilerinin base64 formatında barkod çıktısını almak için kullanılır.

ParametreTürZorunluAçıklama
formatstringHayırBarkod Formatı Örn: pdf,zpl
packageContentVisibilityboolHayırGönderinin içerisindeki paket bilgisinin
görünürlüğü
warningVisibilityboolHayırBarkod çıktısında kargo şubesinin dikkat
etmesi gereken uyarı bilgisininin
görünürlüğü
integratedOrderNoVisibilityboolHayırBarkod çıktısı alınan siparişin, entegre
sitedeki sipariş numarasının
görünürlüğü 
curl --location 'https://app.kargonomi.com.tr/api/v1/shipments/{id}/barcode?format=pdf' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer 0htoc1aNkVJhE6mDB0qZhVy69HCIuXzFGM3NOBhu17df3eb6'

Not: Şu an için sadece pdf formatı desteklenmektedir.

Fiyat Teklifi Alma

{{base_url}}/shipment-price-comparison/{id} - GET

Bu endpoint, ilgili kargo gönderisi için çeşitli kargo firmalarının tekliflerini listelemek için kullanılır.

curl --location 'https://app.kargonomi.com.tr/api/v1/shipment-price-comparison/{id}' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer 0htoc1aNkVJhE6mDB0qZhVy69HCIuXzFGM3NOBhu17df3eb6'

Örnek Response : 

{
    "shipping_provider_with_price": [
        {
            "id": 3,
            "name": "Kolay Gelsin",
            "slug": "kolaygelsin",
            "price": "22.67 + KDV"
        },
        {
            "id": 4,
            "name": "Aras Kargo",
            "slug": "aras",
            "price": "22.67 + KDV"
        },
        {
            "id": 5,
            "name": "Sürat Kargo",
            "slug": "surat",
            "price": "22.67 + KDV"
        },
        {
            "id": 6,
            "name": "Hepsijet",
            "slug": "hepsijet",
            "price": "Hizmet Dışı Bölge"
        },
        {
            "id": 7,
            "name": "PTT Kargo",
            "slug": "ptt",
            "price": "22.67 + KDV"
        },
        {
            "id": "-1",
            "name": "Otomatik",
            "slug": "otomatik",
            "price": null
        }
    ],
    "shipment": {
        "id": 8,
        "type": "shipment",
        "shipping_webservice_order_id": null,
        "shipping_webservice_barcode": null,
        "shipping_webservice_tracking_code": null,
        "shipping_provider_name": null,
        "shipping_provider_slug": null,
        "barcode_of_order_id": null,
        "status": "draft",
        "status_label": "Taslak",
        "shipping_webservice_created_at": null,
        "ecommerce_provider_order_no": null,
        "ecommerce_provider": null,
        "package_count": 1,
        "estimated_price": null,
        "real_price": null,
        "extra_shipping_price": "0.0000",
        "buyer_name": "Test Buyer Name",
        "delivery_date_to_shipment_office": null,
        "shipping_provider_customer_delivery_date": null,
        "created_at": "2024-06-25T09:36:32.000000Z",
        "updated_at": "2024-06-25T09:36:35.000000Z",
        "sender": {
            "sender_name": "Test Sender Name",
            "sender_email": "test@mail.com",
            "sender_phone": "5555555555",
            "sender_phone2": null,
            "sender_tax_number": "11111111111",
            "sender_tax_place": "Üsküdar",
            "sender_address": "Sender Street, Sender City, 12345",
            "sender_state": "İSTANBUL",
            "sender_city": "ÜSKÜDAR"
        },
        "buyer": {
            "buyer_name": "Test Buyer Name",
            "buyer_email": "test@mail.com",
            "buyer_phone": "5555555555",
            "buyer_phone2": null,
            "buyer_tax_number": null,
            "buyer_tax_place": null,
            "buyer_address": "Buyer Street, Buyer City, 12345",
            "buyer_state": "İSTANBUL",
            "buyer_city": "ARNAVUTKÖY"
        },
        "pricing": {
            "package_count": 1,
            "estimated_price": null,
            "real_price": null,
            "extra_shipping_price": "0.0000",
            "price_diff": null
        },
        "shipment_packages": [
            {
                "desi": "1",
                "barcode": "JRJ3PA_1",
                "content": "Defter",
                "real_desi": null
            }
        ]
    }
}

Bakiye Sorgulama

{{base_url}}/user/credit - GET

Bu endpoint, kullanıcınızın mevcut bakiye (kredi) bilgisini görüntülemek için kullanılır.

curl --location --request GET 'https://app.kargonomi.com.tr/api/v1/user/credit' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer 0htoc1aNkVJhE6mDB0qZhVy69HCIuXzFGM3NOBhu17df3eb6'

Örnek Response :

{
    "data": {
        "credit": 122.8
    }
}

Şehirler ve İlçeler

{{base_url}}/states/{countryId?} - GET
curl --location 'https://app.kargonomi.com.tr/api/v1/states/1' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer 0htoc1aNkVJhE6mDB0qZhVy69HCIuXzFGM3NOBhu17df3eb6'

NOT: countryId değeri yollamak zorunlu değildir. Varsayılan olarak Türkiye'nin şehirleri listelenecektir.
{{base_url}}/cities/{stateId} - GET
curl --location 'https://app.kargonomi.com.tr/api/v1/cities/{stateId}' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer 0htoc1aNkVJhE6mDB0qZhVy69HCIuXzFGM3NOBhu17df3eb6'

Webhook İşlemleri

Bu servisler, Kargonomi üzerinde gerçekleşen belirli olaylar için (örneğin gönderi oluşturulması veya güncellenmesi) kullanıcı hesabına bağlı webhook tanımlamalarını yönetmenizi sağlar.

Webhooklar, Kargonomi tarafından tetiklendiğinde sizin belirlediğiniz URL’e POST isteği gönderilir.

Webhook Listesi

{{base_url}}/webhooks - GET

Kullanıcı hesabına kayıtlı tüm webhook tanımlarını listeler.

curl --location 'https://app.kargonomi.com.tr/api/v1/webhooks' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer 0htoc1aNkVJhE6mDB0qZhVy69HCIuXzFGM3NOBhu17df3eb6'

Webhook Detay

{{base_url}}/webhooks/{id} - GET

Belirtilen webhook kaydının detay bilgilerini döner.

curl --location 'https://app.kargonomi.com.tr/api/v1/webhooks/1' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer 0htoc1aNkVJhE6mDB0qZhVy69HCIuXzFGM3NOBhu17df3eb6'

Webhook Oluşturma

{{base_url}}/webhooks - POST

Yeni bir webhook kaydı oluşturur. Webhooklar belirli bir event’e göre tetiklenir ve seçtiğiniz URL’e veri gönderilir.

ParametreTürZorunluAçıklama
namestringEvetWebhook kaydına verilecek isim.
urlstringEvetWebhook iletilecek url bilgisi.
event_typestringEvetWebhook’un tetikleneceği olay türü.
“shipment.updated”
is_activeboolHayırWebhook kaydının aktif/pasif durumu
curl --location 'https://app.kargonomi.com.tr/api/v1/webhooks' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer 0htoc1aNkVJhE6mDB0qZhVy69HCIuXzFGM3NOBhu17df3eb6'
--data '{
  "name": "Kargonomi Shipment Updated Webhook",
  "url": "https://example.com/hooks/shipment",
  "event_type": "shipment.updated",
  "is_active": true
}'

Webhook Güncelleme

{{base_url}}/webhooks - PUT

Mevcut webhook kaydını günceller.

curl --location --request PUT 'https://app.kargonomi.com.tr/api/v1/webhooks/1' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer 0htoc1aNkVJhE6mDB0qZhVy69HCIuXzFGM3NOBhu17df3eb6'
--data '{
  "name": "Güncellenmiş Webhook",
  "url": "https://example.com/hooks/shipment",
  "event_type": "shipment.updated",
  "is_active": false
}'

Webhook Silme

{{base_url}}/webhooks - DELETE

Webhook kaydını siler.

curl --location --request DELETE 'https://app.kargonomi.com.tr/api/v1/webhooks/1' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer 0htoc1aNkVJhE6mDB0qZhVy69HCIuXzFGM3NOBhu17df3eb6'

Webhook Payload Yapısı

Webhook tetiklendiğinde sistem sizin belirttiğiniz URL’ye POST isteğinde bulunur.

Aşağıdaki örnek, gönderilen webhook payload’ının tam yapısıdır:

{
  "meta": {
    "webhook": {
      "name": "Kargonomi Shipment Updated Webhook",
      "url": "https://example.com/hooks/shipment",
      "event_type": "shipment.updated",
      "is_active": true
    },
    "idempotency_key": "1d82586ad2baed95a013bb5349f752ece1374be97f56630465a1a264f13b1847",
    "attempt_number": 1,
    "executed_at": "2025-11-25T11:27:46+03:00"
  },
  "shipment": {
    "id": 1,
    "type": "shipment",
    "shipping_webservice_order_id": null,
    "shipping_webservice_barcode": null,
    "shipping_webservice_tracking_code": null,
    "shipping_provider_name": null,
    "shipping_provider_slug": null,
    "barcode_of_order_id": null,
    "status": "draft",
    "status_label": "Taslak",
    "shipping_webservice_created_at": null,
    "ecommerce_provider_order_no": null,
    "ecommerce_provider": null,
    "package_count": 1,
    "estimated_price": null,
    "real_price": null,
    "extra_shipping_price": "0.0000",
    "delivery_date_to_shipment_office": null,
    "shipping_provider_customer_delivery_date": null,
    "created_at": "2024-06-18T20:18:06.000000Z",
    "updated_at": "2024-06-18T20:18:06.000000Z",
    "sender": {
      "sender_name": "Test Sender Name",
      "sender_email": "test@mail.com",
      "sender_phone": "5555555555",
      "sender_phone2": null,
      "sender_tax_number": "11111111111",
      "sender_tax_place": "Vergi Dairesi Yok",
      "sender_address": "Test Street, Test City, 12345",
      "sender_state": "İSTANBUL",
      "sender_city": "ÜSKÜDAR"
    },
    "buyer": {
      "buyer_name": "Test Buyer Name",
      "buyer_email": null,
      "buyer_phone": "5555555555",
      "buyer_phone2": null,
      "buyer_tax_number": null,
      "buyer_tax_place": null,
      "buyer_address": "Buyer Street, Buyer City, 12345",
      "buyer_state": "İSTANBUL",
      "buyer_city": "AVCILAR"
    },
    "pricing": {
      "package_count": 1,
      "estimated_price": null,
      "real_price": null,
      "extra_shipping_price": "0.0000",
      "price_diff": null
    },
    "warehouse": {
      "id": 12707,
      "name": "Merkez Depo",
      "is_main": 1,
      "contact_name": "Ali Yılmaz",
      "contact_phone": "5565465465",
      "state": "İstanbul",
      "city": "Üsküdar",
      "address": "cumhuriyet mah. vatan sokak no:4",
      "phone": null,
      "tax_number": "98328113892",
      "tax_place": "Acısu"
    },
    "shipment_packages": [
      {
        "desi": "1",
        "barcode": "1MEVK1_1",
        "content": null,
        "real_desi": null
      }
    ]
  }
}

Event Tipleri

event_typeAçıklama
shipment.updatedGönderiye ait bilgilerden (status, tracking code, package count, fiyat vb.) en az biri değiştiğinde tetiklenir.

Signature (İmza) Doğrulama

Tüm webhook gönderimlerinde aşağıdaki header bulunur:

X-Webhook-Signature: <HMAC-SHA256>
  • Payload’ın ham gövdesi alınır
  • secret_key ile HMAC-SHA256 hash üretilir
  • Header’daki değer ile karşılaştırılır
  • Eşleşme yoksa istek reddedilmelidir

Retry (Tekrar Gönderim) Mekanizması

  • 2xx dışındaki tüm yanıtlar tekrar gönderilir
  • Deneme süreleri:
  • 60s → 120s → 300s → 600s → 1200s
  • Toplam 5 ek deneme yapılır
  • Aşağıdaki hatalarda tekrar gönderim sağlanmaz:
  • 400, 401, 403, 404, 409, 410, 422

Shipment Status Kodları

draft : Taslak
ready : İşleme Hazır
webservice_order_failed : Kargo Sipariş Oluşturulamadı
webservice_order_creating : Kargo Siparişi Oluşturuluyor
webservice_order_created : Kargo Siparişi Oluşturuldu
webservice_checking_shipment : Kargo Kaydı Kontrol Ediliyor
webservice_shipment_started : Kargo Teslim Sürecinde
webservice_shipment_delivered : Kargo Teslim Edildi
webservice_shipment_not_delivered : Kargo Teslim Edilemedi
webservice_shipment_returning : Kargo Geri Geliyor
webservice_shipment_missing : Kargo Kayıp
cancelled : Kargo İptal Edildi
request_for_cancellation : İptal Talebi Alındı

HTTP Status Kodları

200 OK : İstek başarılı ve yanıt verildi.

201 Created : İstek başarılı ve yeni bir kaynak oluşturuldu.

204 No Content : İstek başarılı, ancak geri dönecek içerik yok. Genellikle bir kaynak silindiğinde döner.

401 Unauthorized : Kimlik doğrulaması gereksinimleri karşılanmadı.

404 Not Found : İstenen kaynak bulunamadı.

422 Unprocessable Entity: İstek başarılı fakat gönderilen veri işlenemiyor. (genelde validation hatası)

Hemen Kargonomi ile Tanışın!

E-ticaret ve bireysel kargolarınızı uygun fiyatlara göndermek için Kargonomi'yi hemen şimdi ücretsiz deneyebilirsiniz.

Hemen Deneyin!
Kargonomi Teslimat
Picture of Ahmet Atıf Dalbay
Ahmet Atıf Dalbay