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.
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.
Parametre | Tür | Zorunlu | Açıklama |
page | int | Hayır | Sayfalama için kullanılır |
curl --location 'http://localhost/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
},
"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": "« Önceki",
"active": false
},
{
"url": "https://app.kargonomi.com.tr/api/v1/shipments?page=1",
"label": "1",
"active": true
},
{
"url": null,
"label": "Sonraki »",
"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
},
"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.
Parametre | Tür | Zorunlu | Açıklama |
shipment.sender_name | string | Evet | Gönderenin adı (min: 5, max: 255 karakter) |
shipment.sender_email | string | Evet | Gönderenin e-posta adresi (geçerli email formatında, max: 255 karakter) |
shipment.sender_tax_number | string | Evet | Gönderenin vergi numarası (min: 10, max: 11 karakter) |
shipment.sender_tax_place | string | Evet | Gönderenin vergi dairesi (max: 20 karakter) |
shipment.sender_phone | string | Evet | Gönderenin telefon numarası (10 karakter) |
shipment.sender_address | string | Evet | Gönderenin adresi (min: 10, max: 512 karakter) |
shipment.sender_state_id | integer | Evet | Gönderenin şehir kimliği (mevcut şehir kimlikleri ile eşleşmeli) |
shipment.sender_city_id | integer | Evet | Gönderenin ilçe kimliği (mevcut ilçe kimlikleri ile eşleşmeli) |
shipment.buyer_name | string | Evet | Alıcının adı (min: 5, max: 255 karakter, en az 2 kelime) |
shipment.buyer_email | string | Hayır | Alıcının e-posta adresi (geçerli email formatında, max: 255 karakter) |
shipment.buyer_tax_number | string | Hayır | Alıcının vergi numarası (min: 10, max: 11 karakter) |
shipment.buyer_tax_place | string | Hayır | Alıcının vergi dairesi (max: 20 karakter) |
shipment.buyer_phone | string | Evet | Alıcının telefon numarası (10 karakter) |
shipment.buyer_address | string | Evet | Alıcının adresi (min: 10, max: 512 karakter) |
shipment.buyer_state_id | integer | Evet | Alıcının şehir kimliği (mevcut şehir kimlikleri ile eşleşmeli) |
shipment.buyer_city_id | integer | Evet | Alıcının ilçe kimliği (mevcut ilçe kimlikleri ile eşleşmeli) |
shipment.packages | array | Evet | Gönderiye ait paket detayları içeren bir dizi (en az 1 öğe) |
shipment.packages.*.content | string | Hayır | Paket içeriği |
shipment.packages.*.barcode | string | Hayır | Paket barkodu |
shipment.packages.*.desi | numeric | Evet | Paket 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",
"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 :
"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",
"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 #
{{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",
"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 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'
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.
Parametre | Tür | Zorunlu | Açıklama |
format | string | Hayır | Barkod Formatı Örn: pdf,zpl |
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": "Sendeo",
"slug": "sendeo",
"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
}
]
}
}
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.
Parametre | Tür | Zorunlu | Açıklama |
shipment_id | int | Evet | Kargo Gönderisinin ID Değeri |
shipping_provider_id | int | Evet | Kargo 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": "Sendeo",
"slug": "sendeo",
"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.
Ş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'
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ı)