Geliştirici Merkezi

KargoJet API referansı; adres, gönderi, webhook, finans, paket şablonu, özel taşıyıcı anlaşması ve hata kodları dahil tüm entegrasyon yüzeylerini yan menülü teknik dokümantasyon düzeninde toplar.

30 dk okuma

KargoJet API Referansı

Bu sayfa, KargoJet API uçlarını ürün mantığı ve operasyon akışıyla birlikte açıklar. Amaç sadece URL vermek değil; entegrasyon yapan geliştiricinin hangi endpoint'i ne zaman kullanacağını, hangi hataya nasıl tepki vereceğini ve hangi operasyon riskini kapattığını netleştirmektir.

KargoJet Whitepaper

KargoJet'in AI destekli ilk kargo entegratörü vizyonu, operasyon mimarisi, Call Center yaklaşımı, e-fatura kontör modeli ve roadmap başlıklarını içeren kurumsal PDF dokümanı.

PDF İndir

Hızlı Başlangıç Rehberi

15 dakikada ilk API çağrınızı yapın

1API Anahtarınızı Oluşturun

KargoJet panelinde Ayarlar > API Anahtarları sayfasına gidin. Yeni Anahtar Oluştur butonuna tıklayın ve anahtarınızı güvenli bir yere kaydedin. Bu anahtar, tüm API çağrılarınızda Authorization başlığında kullanılacaktır.

Authorization: Bearer YOUR_API_KEY

2İlk Gönderici Adresinizi Oluşturun

Gönderi oluşturmadan önce en az bir gönderici adresine ihtiyacınız var. POST /v1/addresses/senders endpoint'ine şirket bilgilerinizi gönderin.

curl -X POST https://api.kargojet.com/v1/addresses/senders \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"title":"Merkez Depo","contactName":"Operasyon","phone":"08501234567","city":"İstanbul","district":"Kadıköy","addressLine":"Caferağa Mah. No: 5"}'

3İlk Gönderinizi Oluşturun

Gönderici adresiniz hazır olduğunda POST /v1/shipments endpoint'iyle ilk gönderinizi oluşturabilirsiniz. Alıcı bilgileri, ağırlık ve desi değerlerini payload'a ekleyin. Başarılı yanıtta barkod ve takip numarası döner.

4Hata Yönetimi ve Retry

429 (rate limit) yanıtlarında Retry-After başlığındaki süre kadar bekleyip tekrar deneyin. 5xx hatalarında exponential backoff uygulayın: 1s, 2s, 4s, 8s. Idempotency-Key başlığı kullanarak aynı isteğin tekrar işlenmesini önleyebilirsiniz.

Operasyonel Not

API anahtarınızı asla istemci taraflı kodda (frontend, mobil uygulama) açık bırakmayın. Tüm API çağrılarını sunucu tarafında yapın.

Webhook Altyapısı Kurma Rehberi

Kargo statü değişikliklerini anlık olarak sisteminize aktarın

Webhook Nedir?

Webhook, KargoJet'in kargo statüsü değiştiğinde sizin belirlediğiniz URL'e otomatik HTTP POST isteği göndermesidir. Sürekli polling yapmak yerine, değişiklik olduğunda anında bildirim alırsınız. Desteklenen olaylar: shipment.created, shipment.in_transit, shipment.delivered, shipment.returned.

URL Tanımlama ve Güvenlik

Webhook URL'inizi POST /v1/webhooks endpoint'iyle tanımlayın. Her webhook isteğinde X-KargoJet-Signature başlığı ile HMAC-SHA256 imzası gönderilir. İsteği aldığınızda bu imzayı doğrulayarak isteğin gerçekten KargoJet'ten geldiğinden emin olun.

const crypto = require('crypto');

function verifySignature(payload, signature, secret) {
  const expected = crypto
    .createHmac('sha256', secret)
    .update(payload)
    .digest('hex');
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expected)
  );
}

Örnek Webhook Payload

{
  "event": "shipment.delivered",
  "timestamp": "2026-05-12T14:30:00Z",
  "data": {
    "shipmentId": "shp_01HX",
    "trackingCode": "KJ1234567890",
    "status": "delivered",
    "deliveredAt": "2026-05-12T14:28:00Z",
    "recipientName": "Ayşe Yılmaz"
  }
}

Retry ve Idempotency

Webhook isteği 2xx yanıt almazsa KargoJet 5 dakika, 30 dakika ve 2 saat aralıklarla toplam 3 kez tekrar dener. Her webhook isteğinde benzersiz bir X-KargoJet-Event-Id başlığı bulunur; bu ID'yi kaydederek aynı olayın birden fazla işlenmesini önleyin.

Bilgi Notu

Webhook URL'iniz 5 saniye içinde yanıt vermezse istek timeout olarak işaretlenir ve retry kuyruğuna alınır. Handler'ınızda ağır işlemleri arka plan kuyruğuna atın, webhook'a hızlı 200 dönün.

E-ticaret Platform Entegrasyonu

WooCommerce, Shopify ve özel mağaza entegrasyonu

Genel Akış

E-ticaret platformunuzdan sipariş geldiğinde, bu siparişi KargoJet API'sine gönderi olarak iletmeniz gerekir. Temel akış şu şekilde çalışır: (1) Platform webhook veya cron ile yeni siparişleri çekin, (2) siparişi KargoJet gönderi formatına dönüştürün, (3) POST /v1/shipments ile gönderiyi oluşturun, (4) dönen barkod ve takip bilgisini platformunuza kaydedin.

WooCommerce

WooCommerce webhook'larını kullanarak order.created olayında sipariş verilerini alın. wc_get_order() ile ürün, adres ve ödeme bilgilerini çekin. KargoJet payload'ına dönüştürüp gönderi oluşturun. Takip numarasını sipariş notlarına ve meta alanına kaydedin.

Shopify

Shopify Admin API veya webhook'larını kullanarak siparişleri çekin. Fulfillment API ile KargoJet'ten aldığınız takip numarasını siparişe bağlayın. Müşteriniz otomatik olarak Shopify üzerinden takip bildirimlerini alır.

Özel Mağaza (Custom)

Kendi e-ticaret altyapınızdan sipariş çeken bağımsız geliştirici olarak uçtan uca entegrasyon şu adımlarla kurulur: veritabanınızdaki yeni siparişleri periyodik olarak sorgulayın veya sipariş oluşturma akışınıza bir hook ekleyin. Adres, ürün ve ağırlık bilgilerini KargoJet şemasına map'leyin. Gönderi oluşturma yanıtındaki barkod URL'ini saklayın ve yazdırma kuyruğunuza gönderin. Webhook ile teslimat güncellemelerini alarak sipariş durumunuzu otomatik güncelleyin.

Operasyonel Not

Entegrasyonunuzu önce KargoJet sandbox ortamında test edin. Sandbox'ta gerçek gönderi oluşturulmaz ama tüm API yanıtları production ile aynı formattadır.

Adresler

Gönderici, alıcı, depo ve iade adresleri kargo operasyonunun başlangıç noktasıdır. Yanlış adres verisi, yanlış barkod ve taşıyıcı retlerinin ana sebebidir.

POST/v1/addresses/senders

Gönderici adresi oluştur

Şirket, depo veya mağaza çıkış noktası olarak kullanılacak gönderici adresini oluşturur.

Ne zaman kullanılır?

İlk kurulum, yeni depo açılışı veya farklı şehirden çıkış yapılacak operasyonlarda kullanılır.

Request

bash

curl https://api.kargojet.com/v1/addresses/senders \
  -X POST \
  -H "Authorization: Bearer $KARGOJET_API_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: ORD-10042" \
  -d @payload.json

Body

json

{
  "title": "Merkez Depo",
  "contactName": "Operasyon Ekibi",
  "phone": "08500000000",
  "city": "İstanbul",
  "district": "Tuzla",
  "addressLine": "Orhanlı Mah. Depo Cad. No: 12",
  "isDefault": true
}

Response

json

{
  "id": "addr_sender_01HX",
  "type": "sender",
  "title": "Merkez Depo",
  "isDefault": true,
  "createdAt": "2026-05-09T12:00:00Z"
}

Operasyon Notu

Varsayılan gönderici adresi, fiyat karşılaştırma ve gönderi oluşturma payload'ında adres verilmediğinde kullanılır.

Operasyon Notu

Telefon ve açık adres alanları taşıyıcı validasyonlarından geçtiği için eksik bırakılmamalıdır.

Hata Durumları

HTTP 401

Token eksik, geçersiz veya süresi dolmuş.

HTTP 403

Token bu işlem için yetkili değil.

HTTP 422

Gönderilen alanlardan biri operasyonel doğrulamadan geçmedi.

HTTP 429

Rate limit aşıldı. Retry-After başlığı dikkate alınmalı.

POST/v1/addresses/recipients

Alıcı adresi oluştur

Müşteri teslimat adresini KargoJet adres defterine kaydeder.

Ne zaman kullanılır?

Tekrarlayan B2B müşteriler veya çağrı merkezi siparişlerinde alıcı adresini tekrar kullanmak için idealdir.

Request

bash

curl https://api.kargojet.com/v1/addresses/recipients \
  -X POST \
  -H "Authorization: Bearer $KARGOJET_API_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: ORD-10042" \
  -d @payload.json

Body

json

{
  "name": "Ayşe Yılmaz",
  "phone": "5551112233",
  "city": "İstanbul",
  "district": "Kadıköy",
  "addressLine": "Caferağa Mah. Örnek Sok. No: 10"
}

Response

json

{
  "id": "addr_recipient_01HX",
  "name": "Ayşe Yılmaz",
  "city": "İstanbul",
  "district": "Kadıköy"
}

Operasyon Notu

Alıcı adresini ayrı kaydetmek zorunlu değildir; gönderi oluştururken inline recipient objesi de gönderilebilir.

Operasyon Notu

Adres defteri, iade ve tekrar gönderim senaryolarında manuel veri girişini azaltır.

Hata Durumları

HTTP 401

Token eksik, geçersiz veya süresi dolmuş.

HTTP 403

Token bu işlem için yetkili değil.

HTTP 422

Gönderilen alanlardan biri operasyonel doğrulamadan geçmedi.

HTTP 429

Rate limit aşıldı. Retry-After başlığı dikkate alınmalı.

GET/v1/addresses

Adresleri listele

Hesaptaki gönderici, alıcı, depo ve iade adreslerini sayfalı olarak listeler.

Ne zaman kullanılır?

Gönderi formunda depo seçimi, iade adresi seçimi veya panelde adres defteri ekranı oluşturmak için kullanılır.

Parametreler

Alan	Tip	Zorunluluk	Açıklama
page	number	Opsiyonel	Sayfa numarası. Varsayılan 1.
limit	number	Opsiyonel	Sayfa başına kayıt. Varsayılan 25, maksimum 100.
type	sender \| recipient \| return \| warehouse	Opsiyonel	Adres tipine göre filtreleme.
city	string	Opsiyonel	İl adına göre filtreleme.

Request

bash

curl https://api.kargojet.com/v1/addresses \
  -X GET \
  -H "Authorization: Bearer $KARGOJET_API_TOKEN" \
  -H "Content-Type: application/json"

Response

json

{
  "data": [
    { "id": "addr_01HX", "type": "warehouse", "title": "Merkez Depo" }
  ],
  "pagination": { "page": 1, "limit": 25, "total": 1 }
}

Operasyon Notu

Liste yanıtındaki adres id, gönderi oluşturma ve fiyat karşılaştırma endpoint'lerinde kullanılabilir.

Operasyon Notu

Adres silinmiş olsa bile geçmiş gönderilerdeki adres snapshot'ı korunmalıdır.

Hata Durumları

HTTP 401

Token eksik, geçersiz veya süresi dolmuş.

HTTP 403

Token bu işlem için yetkili değil.

HTTP 422

Gönderilen alanlardan biri operasyonel doğrulamadan geçmedi.

HTTP 429

Rate limit aşıldı. Retry-After başlığı dikkate alınmalı.

GET/v1/addresses/{addressId}

Tek adres getir

Belirli bir adresin detaylarını döndürür.

Ne zaman kullanılır?

Gönderi öncesi depo adresinin güncel olup olmadığını kontrol etmek için kullanılır.

Request

bash

curl https://api.kargojet.com/v1/addresses/{addressId} \
  -X GET \
  -H "Authorization: Bearer $KARGOJET_API_TOKEN" \
  -H "Content-Type: application/json"

Response

json

{
  "id": "addr_01HX",
  "type": "warehouse",
  "title": "Merkez Depo",
  "city": "İstanbul",
  "district": "Tuzla",
  "isDefault": true
}

Operasyon Notu

404 dönerse kullanıcıdan yeni adres seçmesi istenmelidir.

Hata Durumları

HTTP 401

Token eksik, geçersiz veya süresi dolmuş.

HTTP 403

Token bu işlem için yetkili değil.

HTTP 422

Gönderilen alanlardan biri operasyonel doğrulamadan geçmedi.

HTTP 429

Rate limit aşıldı. Retry-After başlığı dikkate alınmalı.

HTTP 404

Adres bulunamadı veya bu hesaba ait değil.

DELETE/v1/addresses/{addressId}

Adres sil

Adres defterindeki kullanılmayan bir adresi pasife alır.

Ne zaman kullanılır?

Kapanan depo veya artık kullanılmayan gönderici adreslerini temizlemek için kullanılır.

Request

bash

curl https://api.kargojet.com/v1/addresses/{addressId} \
  -X DELETE \
  -H "Authorization: Bearer $KARGOJET_API_TOKEN" \
  -H "Content-Type: application/json"

Response

json

{ "deleted": true }

Operasyon Notu

Geçmiş gönderilerdeki adres bilgisi etkilenmez.

Operasyon Notu

Varsayılan adres siliniyorsa önce yeni varsayılan adres seçilmelidir.

Hata Durumları

HTTP 401

Token eksik, geçersiz veya süresi dolmuş.

HTTP 403

Token bu işlem için yetkili değil.

HTTP 422

Gönderilen alanlardan biri operasyonel doğrulamadan geçmedi.

HTTP 429

Rate limit aşıldı. Retry-After başlığı dikkate alınmalı.

HTTP 409

Adres aktif gönderilerde kullanıldığı için silinemez.

GET/v1/locations/cities

İlleri listele

KargoJet ve taşıyıcı validasyonlarında desteklenen Türkiye il listesini döndürür.

Ne zaman kullanılır?

Checkout veya adres formunda serbest metin yerine kontrollü seçim sunmak için kullanılır.

Request

bash

curl https://api.kargojet.com/v1/locations/cities \
  -X GET \
  -H "Authorization: Bearer $KARGOJET_API_TOKEN" \
  -H "Content-Type: application/json"

Response

json

[{ "code": "34", "name": "İstanbul" }, { "code": "06", "name": "Ankara" }]

Operasyon Notu

Şehir listesi cache'lenebilir; sık değişen bir veri değildir.

Hata Durumları

HTTP 401

Token eksik, geçersiz veya süresi dolmuş.

HTTP 403

Token bu işlem için yetkili değil.

HTTP 422

Gönderilen alanlardan biri operasyonel doğrulamadan geçmedi.

HTTP 429

Rate limit aşıldı. Retry-After başlığı dikkate alınmalı.

GET/v1/locations/cities/{cityCode}/districts

İlçeleri listele

Seçilen ile bağlı ilçeleri ve varsa taşıyıcı operasyon kısıtlarını döndürür.

Ne zaman kullanılır?

Mobil alan, uzak bölge veya taşıyıcı kısıtlarını checkout aşamasında göstermek için kullanılır.

Request

bash

curl https://api.kargojet.com/v1/locations/cities/{cityCode}/districts \
  -X GET \
  -H "Authorization: Bearer $KARGOJET_API_TOKEN" \
  -H "Content-Type: application/json"

Response

json

[{ "name": "Kadıköy", "isRemoteArea": false }, { "name": "Şile", "isRemoteArea": true }]

Operasyon Notu

Uzak bölge bilgisi fiyat ve teslimat günü hesaplarında dikkate alınmalıdır.

Hata Durumları

HTTP 401

Token eksik, geçersiz veya süresi dolmuş.

HTTP 403

Token bu işlem için yetkili değil.

HTTP 422

Gönderilen alanlardan biri operasyonel doğrulamadan geçmedi.

HTTP 429

Rate limit aşıldı. Retry-After başlığı dikkate alınmalı.

HTTP 404

İl kodu bulunamadı.

Gönderiler

Gönderi endpoint'leri fiyat alma, teklif kabul etme, barkod üretme, iade, klonlama, takip ve paket güncelleme akışlarını kapsar.

POST/v1/shipments

Gönderi oluştur

Alıcı, paket ve taşıyıcı bilgileriyle yeni gönderi kaydı oluşturur.

Ne zaman kullanılır?

Sipariş ödeme aldıktan sonra barkod ve takip numarası üretmek için kullanılır.

Request

bash

curl https://api.kargojet.com/v1/shipments \
  -X POST \
  -H "Authorization: Bearer $KARGOJET_API_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: ORD-10042" \
  -d @payload.json

Body

json

{
  "reference": "ORD-10042",
  "carrierCode": "aras",
  "recipient": { "name": "Ayşe Yılmaz", "phone": "5551112233" },
  "parcel": { "widthCm": 30, "lengthCm": 20, "heightCm": 10, "weightKg": 1.4 }
}

Response

json

{ "id": "shp_01HX", "trackingNumber": "3489123412", "status": "label_created" }

Operasyon Notu

Idempotency-Key kullanılmalıdır; aksi halde timeout sonrası çift barkod riski oluşur.

Hata Durumları

HTTP 401

Token eksik, geçersiz veya süresi dolmuş.

HTTP 403

Token bu işlem için yetkili değil.

HTTP 422

Gönderilen alanlardan biri operasyonel doğrulamadan geçmedi.

HTTP 429

Rate limit aşıldı. Retry-After başlığı dikkate alınmalı.

POST/v1/shipments/drafts

İki aşamalı gönderi oluştur

Önce taslak gönderi oluşturur, sonra teklif kabul edilerek barkod üretir.

Ne zaman kullanılır?

Kullanıcıya taşıyıcı teklifleri gösterilen checkout veya panel akışlarında kullanılır.

Request

bash

curl https://api.kargojet.com/v1/shipments/drafts \
  -X POST \
  -H "Authorization: Bearer $KARGOJET_API_TOKEN" \
  -H "Content-Type: application/json"

Response

json

{ "draftId": "draft_01HX", "offers": [{ "carrierCode": "yurtici", "amount": 82.5 }] }

Operasyon Notu

Taslaklar belirli süre sonra expire olur; kullanıcı bekletiliyorsa teklif yeniden alınmalıdır.

Hata Durumları

HTTP 401

Token eksik, geçersiz veya süresi dolmuş.

HTTP 403

Token bu işlem için yetkili değil.

HTTP 422

Gönderilen alanlardan biri operasyonel doğrulamadan geçmedi.

HTTP 429

Rate limit aşıldı. Retry-After başlığı dikkate alınmalı.

POST/v1/shipments/cod

Kapıda ödemeli gönderi oluştur

Tahsilat tutarı ve ödeme tipiyle COD gönderi oluşturur.

Ne zaman kullanılır?

Kapıda nakit veya kart tahsilatı yapılacak siparişlerde kullanılır.

Request

bash

curl https://api.kargojet.com/v1/shipments/cod \
  -X POST \
  -H "Authorization: Bearer $KARGOJET_API_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: ORD-10042" \
  -d @payload.json

Body

json

{ "reference": "ORD-10043", "cod": { "amount": 1299.9, "paymentType": "card" } }

Response

json

{ "id": "shp_cod_01HX", "codStatus": "pending_collection" }

Operasyon Notu

COD tutarı ürün bedeli, kargo bedeli ve komisyon hesaplarıyla mutabık olmalıdır.

Hata Durumları

HTTP 401

Token eksik, geçersiz veya süresi dolmuş.

HTTP 403

Token bu işlem için yetkili değil.

HTTP 422

Gönderilen alanlardan biri operasyonel doğrulamadan geçmedi.

HTTP 429

Rate limit aşıldı. Retry-After başlığı dikkate alınmalı.

POST/v1/provider-shipments

Özel anlaşmalı taşıyıcıyla gönderi oluştur

Kendi kargo sözleşmeniz üzerinden taşıyıcıya gönderi aktarır.

Ne zaman kullanılır?

KargoJet fiyatları yerine şirketinizin özel Aras/Yurtiçi/MNG anlaşmasını kullanmak için.

Request

bash

curl https://api.kargojet.com/v1/provider-shipments \
  -X POST \
  -H "Authorization: Bearer $KARGOJET_API_TOKEN" \
  -H "Content-Type: application/json"

Response

json

{ "id": "shp_provider_01HX", "providerAccountId": "pa_01HX" }

Operasyon Notu

Provider hesabı test edilmeden canlı gönderi kabul edilmemelidir.

Hata Durumları

HTTP 401

Token eksik, geçersiz veya süresi dolmuş.

HTTP 403

Token bu işlem için yetkili değil.

HTTP 422

Gönderilen alanlardan biri operasyonel doğrulamadan geçmedi.

HTTP 429

Rate limit aşıldı. Retry-After başlığı dikkate alınmalı.

GET/v1/shipments

Gönderileri listele

Gönderileri tarih, statü, taşıyıcı, referans veya takip numarasına göre listeler.

Ne zaman kullanılır?

Panel gönderi listesi, operasyon raporu ve müşteri hizmetleri ekranları için kullanılır.

Parametreler

Alan	Tip	Zorunluluk	Açıklama
status	string	Opsiyonel	label_created, in_transit, delivered, failed, returned.
carrierCode	string	Opsiyonel	Taşıyıcı kodu ile filtreleme.
reference	string	Opsiyonel	Sipariş referansı ile arama.

Request

bash

curl https://api.kargojet.com/v1/shipments \
  -X GET \
  -H "Authorization: Bearer $KARGOJET_API_TOKEN" \
  -H "Content-Type: application/json"

Response

json

{ "data": [{ "id": "shp_01HX", "status": "in_transit" }], "pagination": { "total": 1 } }

Operasyon Notu

Liste endpoint'i müşteri ekranında kullanılacaksa telefon/adres maskelenmelidir.

Hata Durumları

HTTP 401

Token eksik, geçersiz veya süresi dolmuş.

HTTP 403

Token bu işlem için yetkili değil.

HTTP 422

Gönderilen alanlardan biri operasyonel doğrulamadan geçmedi.

HTTP 429

Rate limit aşıldı. Retry-After başlığı dikkate alınmalı.

POST/v1/shipments/{draftId}/accept-offer

Teklifi kabul et

Taslak gönderide seçilen taşıyıcı teklifini kabul eder ve barkod üretir.

Ne zaman kullanılır?

İki aşamalı gönderi akışında kullanıcı taşıyıcı seçtikten sonra kullanılır.

Request

bash

curl https://api.kargojet.com/v1/shipments/{draftId}/accept-offer \
  -X POST \
  -H "Authorization: Bearer $KARGOJET_API_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: ORD-10042" \
  -d @payload.json

Body

json

{ "offerId": "offer_01HX" }

Response

json

{ "shipmentId": "shp_01HX", "trackingNumber": "3489123412" }

Operasyon Notu

Offer süresi dolduysa 409 döner; fiyat yeniden alınmalıdır.

Hata Durumları

HTTP 401

Token eksik, geçersiz veya süresi dolmuş.

HTTP 403

Token bu işlem için yetkili değil.

HTTP 422

Gönderilen alanlardan biri operasyonel doğrulamadan geçmedi.

HTTP 429

Rate limit aşıldı. Retry-After başlığı dikkate alınmalı.

HTTP 409

Teklif süresi dolmuş veya daha önce kabul edilmiş.

POST/v1/shipments/{shipmentId}/clone

Gönderiyi klonla

Aynı alıcı/paket bilgileriyle yeni gönderi taslağı oluşturur.

Ne zaman kullanılır?

Tekrar gönderim, hasarlı paket yenileme veya aynı müşteriye ikinci çıkışlarda kullanılır.

Request

bash

curl https://api.kargojet.com/v1/shipments/{shipmentId}/clone \
  -X POST \
  -H "Authorization: Bearer $KARGOJET_API_TOKEN" \
  -H "Content-Type: application/json"

Response

json

{ "draftId": "draft_clone_01HX" }

Operasyon Notu

Klonlama yeni barkod üretmez; barkod için teklif kabulü gerekir.

Hata Durumları

HTTP 401

Token eksik, geçersiz veya süresi dolmuş.

HTTP 403

Token bu işlem için yetkili değil.

HTTP 422

Gönderilen alanlardan biri operasyonel doğrulamadan geçmedi.

HTTP 429

Rate limit aşıldı. Retry-After başlığı dikkate alınmalı.

POST/v1/shipments/{shipmentId}/return

İade gönderisi oluştur

Teslim edilmiş veya iade talebi açılmış gönderi için iade kodu üretir.

Ne zaman kullanılır?

Müşterinin ürünü geri göndermesi için kontrollü tersine lojistik başlatır.

Request

bash

curl https://api.kargojet.com/v1/shipments/{shipmentId}/return \
  -X POST \
  -H "Authorization: Bearer $KARGOJET_API_TOKEN" \
  -H "Content-Type: application/json"

Response

json

{ "returnCode": "KJ-RET-4921", "expiresAt": "2026-05-16T12:00:00Z" }

Operasyon Notu

İade kodu süreli olmalıdır; süresi geçen kodlar operasyon maliyeti doğurur.

Hata Durumları

HTTP 401

Token eksik, geçersiz veya süresi dolmuş.

HTTP 403

Token bu işlem için yetkili değil.

HTTP 422

Gönderilen alanlardan biri operasyonel doğrulamadan geçmedi.

HTTP 429

Rate limit aşıldı. Retry-After başlığı dikkate alınmalı.

PATCH/v1/shipments/{shipmentId}/package

Paket bilgisini güncelle

Barkod oluşmadan önce paket ölçülerini günceller.

Ne zaman kullanılır?

Depo paketleme sırasında kutu ölçüsü değiştiyse fiyat ve desi güncellemek için kullanılır.

Request

bash

curl https://api.kargojet.com/v1/shipments/{shipmentId}/package \
  -X PATCH \
  -H "Authorization: Bearer $KARGOJET_API_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: ORD-10042" \
  -d @payload.json

Body

json

{ "widthCm": 31, "lengthCm": 21, "heightCm": 11, "weightKg": 1.8 }

Response

json

{ "shipmentId": "shp_01HX", "billableDesi": 3 }

Operasyon Notu

Barkod üretildikten sonra paket güncelleme taşıyıcıya göre engellenebilir.

Hata Durumları

HTTP 401

Token eksik, geçersiz veya süresi dolmuş.

HTTP 403

Token bu işlem için yetkili değil.

HTTP 422

Gönderilen alanlardan biri operasyonel doğrulamadan geçmedi.

HTTP 429

Rate limit aşıldı. Retry-After başlığı dikkate alınmalı.

GET/v1/tracking/status-codes

Takip statü kodları

KargoJet'in normalize takip statülerini ve açıklamalarını döndürür.

Ne zaman kullanılır?

Webhook eventlerini kendi sipariş statülerinize map etmek için kullanılır.

Request

bash

curl https://api.kargojet.com/v1/tracking/status-codes \
  -X GET \
  -H "Authorization: Bearer $KARGOJET_API_TOKEN" \
  -H "Content-Type: application/json"

Response

json

[{ "code": "in_transit", "label": "Yolda" }, { "code": "delivered", "label": "Teslim edildi" }]

Operasyon Notu

Taşıyıcıya özel statüler bu normalize listeye dönüştürülür.

Hata Durumları

HTTP 401

Token eksik, geçersiz veya süresi dolmuş.

HTTP 403

Token bu işlem için yetkili değil.

HTTP 422

Gönderilen alanlardan biri operasyonel doğrulamadan geçmedi.

HTTP 429

Rate limit aşıldı. Retry-After başlığı dikkate alınmalı.

GET/v1/providers/service-codes

Taşıyıcı servis kodları

Standart, express, same day, return gibi taşıyıcı hizmet kodlarını listeler.

Ne zaman kullanılır?

Checkout'ta farklı teslimat seçenekleri sunmak için kullanılır.

Request

bash

curl https://api.kargojet.com/v1/providers/service-codes \
  -X GET \
  -H "Authorization: Bearer $KARGOJET_API_TOKEN" \
  -H "Content-Type: application/json"

Response

json

[{ "carrierCode": "aras", "service": "standard", "label": "Standart Teslimat" }]

Operasyon Notu

Her taşıyıcı her ilçede tüm servisleri sunmayabilir.

Hata Durumları

HTTP 401

Token eksik, geçersiz veya süresi dolmuş.

HTTP 403

Token bu işlem için yetkili değil.

HTTP 422

Gönderilen alanlardan biri operasyonel doğrulamadan geçmedi.

HTTP 429

Rate limit aşıldı. Retry-After başlığı dikkate alınmalı.

Webhooklar

Webhook endpoint'leri, takip ve operasyon olaylarını kendi sisteminize gerçek zamanlı aktarmak için kullanılır.

POST/v1/webhooks/endpoints

Webhook oluştur

Yeni webhook URL'i ve dinlenecek event tiplerini kaydeder.

Ne zaman kullanılır?

Sipariş sisteminizi teslimat ve iade statüleriyle senkron tutmak için.

Request

bash

curl https://api.kargojet.com/v1/webhooks/endpoints \
  -X POST \
  -H "Authorization: Bearer $KARGOJET_API_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: ORD-10042" \
  -d @payload.json

Body

json

{ "url": "https://example.com/webhooks/kargojet", "events": ["shipment.delivered", "shipment.failed"] }

Response

json

{ "id": "wh_01HX", "status": "active", "secret": "kj_whsec_..." }

Operasyon Notu

Secret sadece oluşturma anında gösterilir; güvenli saklanmalıdır.

Hata Durumları

HTTP 401

Token eksik, geçersiz veya süresi dolmuş.

HTTP 403

Token bu işlem için yetkili değil.

HTTP 422

Gönderilen alanlardan biri operasyonel doğrulamadan geçmedi.

HTTP 429

Rate limit aşıldı. Retry-After başlığı dikkate alınmalı.

GET/v1/webhooks/endpoints

Webhookları listele

Kayıtlı webhook endpoint'lerini ve durumlarını listeler.

Ne zaman kullanılır?

Panelde geliştirici ayarları ekranını oluşturmak için.

Request

bash

curl https://api.kargojet.com/v1/webhooks/endpoints \
  -X GET \
  -H "Authorization: Bearer $KARGOJET_API_TOKEN" \
  -H "Content-Type: application/json"

Response

json

{ "data": [{ "id": "wh_01HX", "url": "https://example.com/webhooks/kargojet" }] }

Operasyon Notu

Secret listede dönmez; sadece masked gösterim yapılmalıdır.

Hata Durumları

HTTP 401

Token eksik, geçersiz veya süresi dolmuş.

HTTP 403

Token bu işlem için yetkili değil.

HTTP 422

Gönderilen alanlardan biri operasyonel doğrulamadan geçmedi.

HTTP 429

Rate limit aşıldı. Retry-After başlığı dikkate alınmalı.

POST/v1/webhooks/endpoints/{webhookId}/test

Webhook test et

Seçilen webhook URL'ine test event gönderir.

Ne zaman kullanılır?

Canlıya geçmeden önce imza doğrulama ve endpoint erişimini test etmek için.

Request

bash

curl https://api.kargojet.com/v1/webhooks/endpoints/{webhookId}/test \
  -X POST \
  -H "Authorization: Bearer $KARGOJET_API_TOKEN" \
  -H "Content-Type: application/json"

Response

json

{ "delivered": true, "statusCode": 202, "durationMs": 184 }

Operasyon Notu

Test event gerçek gönderi statüsü üretmez.

Hata Durumları

HTTP 401

Token eksik, geçersiz veya süresi dolmuş.

HTTP 403

Token bu işlem için yetkili değil.

HTTP 422

Gönderilen alanlardan biri operasyonel doğrulamadan geçmedi.

HTTP 429

Rate limit aşıldı. Retry-After başlığı dikkate alınmalı.

DELETE/v1/webhooks/endpoints/{webhookId}

Webhook sil

Webhook endpoint'ini pasife alır.

Ne zaman kullanılır?

Eski staging URL'lerini veya kullanılmayan entegrasyonları temizlemek için.

Request

bash

curl https://api.kargojet.com/v1/webhooks/endpoints/{webhookId} \
  -X DELETE \
  -H "Authorization: Bearer $KARGOJET_API_TOKEN" \
  -H "Content-Type: application/json"

Response

json

{ "deleted": true }

Operasyon Notu

Silinen webhook'a event gönderimi durur; geçmiş event kayıtları korunur.

Hata Durumları

HTTP 401

Token eksik, geçersiz veya süresi dolmuş.

HTTP 403

Token bu işlem için yetkili değil.

HTTP 422

Gönderilen alanlardan biri operasyonel doğrulamadan geçmedi.

HTTP 429

Rate limit aşıldı. Retry-After başlığı dikkate alınmalı.

Bakiye ve Finans

Bakiye, fiyat ve mutabakat endpoint'leri operasyonun finansal doğruluğunu sağlar.

GET/v1/wallet/balance

Bakiye getir

Kullanılabilir bakiye, bloke tutar ve para birimini döndürür.

Ne zaman kullanılır?

Gönderi oluşturmadan önce hesabın yeterli bakiyesi olup olmadığını kontrol etmek için.

Request

bash

curl https://api.kargojet.com/v1/wallet/balance \
  -X GET \
  -H "Authorization: Bearer $KARGOJET_API_TOKEN" \
  -H "Content-Type: application/json"

Response

json

{ "available": 15420.5, "blocked": 820.0, "currency": "TRY" }

Operasyon Notu

Bloke bakiye henüz kesinleşmemiş gönderi veya COD hareketlerinden oluşabilir.

Hata Durumları

HTTP 401

Token eksik, geçersiz veya süresi dolmuş.

HTTP 403

Token bu işlem için yetkili değil.

HTTP 422

Gönderilen alanlardan biri operasyonel doğrulamadan geçmedi.

HTTP 429

Rate limit aşıldı. Retry-After başlığı dikkate alınmalı.

POST/v1/prices

Fiyatları listele

Paket ve adres verisine göre taşıyıcı fiyat listesini döndürür.

Ne zaman kullanılır?

Panelde veya checkout'ta kullanıcıya taşıyıcı alternatifleri sunmak için.

Request

bash

curl https://api.kargojet.com/v1/prices \
  -X POST \
  -H "Authorization: Bearer $KARGOJET_API_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: ORD-10042" \
  -d @payload.json

Body

json

{ "senderAddressId": "addr_01HX", "parcel": { "desi": 3 }, "recipientCity": "Ankara" }

Response

json

{ "offers": [{ "carrierCode": "mng", "amount": 74.9, "currency": "TRY" }] }

Operasyon Notu

Fiyat yanıtı tahmindir; gönderi oluşturma anında taşıyıcı validasyonu ile kesinleşir.

Hata Durumları

HTTP 401

Token eksik, geçersiz veya süresi dolmuş.

HTTP 403

Token bu işlem için yetkili değil.

HTTP 422

Gönderilen alanlardan biri operasyonel doğrulamadan geçmedi.

HTTP 429

Rate limit aşıldı. Retry-After başlığı dikkate alınmalı.

Kapıda Ödeme

Kapıda ödeme endpoint'leri tahsilatlı gönderi oluşturma, tahsilat statüsü izleme, komisyon kesintisi ve satıcıya aktarım mutabakatını yönetir.

POST/v1/cod/shipments

Kapıda ödemeli gönderi oluştur

Ürün bedelinin teslimat sırasında kurye tarafından tahsil edileceği gönderi kaydını oluşturur.

Ne zaman kullanılır?

Kredi kartı kullanmayan müşterilere satış yapan e-ticaret işletmelerinde, tahsilat bilgisini gönderiyle birlikte taşıyıcıya aktarmak için kullanılır.

Request

bash

curl https://api.kargojet.com/v1/cod/shipments \
  -X POST \
  -H "Authorization: Bearer $KARGOJET_API_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: ORD-10042" \
  -d @payload.json

Body

json

{
  "reference": "ORD-10043",
  "carrierCode": "aras",
  "recipient": {
    "name": "Mehmet Demir",
    "phone": "5552223344",
    "city": "Bursa",
    "district": "Nilüfer",
    "addressLine": "Ataevler Mah. Örnek Cad. No: 8"
  },
  "parcel": { "widthCm": 25, "lengthCm": 18, "heightCm": 12, "weightKg": 1.2 },
  "cod": {
    "amount": 1499.90,
    "currency": "TRY",
    "paymentType": "cash_or_card",
    "collectionReference": "ORD-10043-COD"
  }
}

Response

json

{
  "id": "shp_cod_01HX",
  "trackingNumber": "3489123412",
  "cod": {
    "status": "pending_collection",
    "amount": 1499.90,
    "commission": 29.90,
    "netAmount": 1470.00
  }
}

Operasyon Notu

COD tutarı sipariş toplamı ile birebir eşleşmelidir; kargo bedeli ayrıca tahsil edilecekse payload içinde açık belirtilmelidir.

Operasyon Notu

Kapıda ödeme gönderileri iptal edildiğinde tahsilat hareketi oluşmaz; teslim edildi statüsü beklenmelidir.

Hata Durumları

HTTP 401

Token eksik, geçersiz veya süresi dolmuş.

HTTP 403

Token bu işlem için yetkili değil.

HTTP 422

Gönderilen alanlardan biri operasyonel doğrulamadan geçmedi.

HTTP 429

Rate limit aşıldı. Retry-After başlığı dikkate alınmalı.

HTTP 409

Aynı collectionReference ile daha önce COD gönderi oluşturulmuş.

GET/v1/cod/shipments

Kapıda ödeme gönderilerini listele

COD gönderilerini tahsilat, teslimat ve aktarım durumlarına göre listeler.

Ne zaman kullanılır?

Finans ekibinin hangi kapıda ödeme gönderilerinin tahsil edildiğini, hangilerinin beklediğini ve hangilerinin aktarımda olduğunu görmesi için kullanılır.

Parametreler

Alan	Tip	Zorunluluk	Açıklama
status	pending_collection \| collected \| transferred \| failed	Opsiyonel	Tahsilat durumuna göre filtreleme.
carrierCode	string	Opsiyonel	Taşıyıcı koduna göre filtreleme.
dateFrom / dateTo	ISO date	Opsiyonel	Teslimat veya tahsilat tarih aralığı.
reference	string	Opsiyonel	Sipariş ya da collectionReference ile arama.

Request

bash

curl https://api.kargojet.com/v1/cod/shipments \
  -X GET \
  -H "Authorization: Bearer $KARGOJET_API_TOKEN" \
  -H "Content-Type: application/json"

Response

json

{
  "data": [
    {
      "shipmentId": "shp_cod_01HX",
      "reference": "ORD-10043",
      "trackingNumber": "3489123412",
      "status": "collected",
      "amount": 1499.90,
      "netAmount": 1470.00
    }
  ],
  "pagination": { "page": 1, "limit": 25, "total": 1 }
}

Operasyon Notu

Bu endpoint müşteri hizmetleri ekranında da kullanılabilir; müşteri sadece takip durumunu, finans ekibi tahsilat durumunu görmelidir.

Operasyon Notu

Tahsil edildi bilgisi teslim edildi bilgisinden sonra gecikmeli gelebilir.

Hata Durumları

HTTP 401

Token eksik, geçersiz veya süresi dolmuş.

HTTP 403

Token bu işlem için yetkili değil.

HTTP 422

Gönderilen alanlardan biri operasyonel doğrulamadan geçmedi.

HTTP 429

Rate limit aşıldı. Retry-After başlığı dikkate alınmalı.

GET/v1/cod/summary

Kapıda ödeme özetini getir

Bekleyen, tahsil edilen, komisyon kesilen ve aktarılabilir COD tutarlarını özetler.

Ne zaman kullanılır?

Panel ana sayfasında veya finans dashboard'unda güncel kapıda ödeme alacağını göstermek için kullanılır.

Parametreler

Alan	Tip	Zorunluluk	Açıklama
dateFrom / dateTo	ISO date	Opsiyonel	Özetin hesaplanacağı tarih aralığı.
carrierCode	string	Opsiyonel	Taşıyıcı bazında COD özeti almak için.

Request

bash

curl https://api.kargojet.com/v1/cod/summary \
  -X GET \
  -H "Authorization: Bearer $KARGOJET_API_TOKEN" \
  -H "Content-Type: application/json"

Response

json

{
  "currency": "TRY",
  "pendingCollection": 32500.00,
  "collected": 184250.75,
  "commission": 4210.50,
  "transferable": 180040.25,
  "transferred": 95000.00
}

Operasyon Notu

Aktarılabilir tutar, taşıyıcı mutabakatı ve komisyon kesintisi sonrası oluşur.

Operasyon Notu

COD özeti cüzdan bakiyesinden ayrı takip edilmelidir; her tahsilat hemen kullanılabilir bakiye değildir.

Hata Durumları

HTTP 401

Token eksik, geçersiz veya süresi dolmuş.

HTTP 403

Token bu işlem için yetkili değil.

HTTP 422

Gönderilen alanlardan biri operasyonel doğrulamadan geçmedi.

HTTP 429

Rate limit aşıldı. Retry-After başlığı dikkate alınmalı.

GET/v1/cod/transfers

Kapıda ödeme aktarım hareketlerini listele

Satıcıya yapılan COD para aktarım hareketlerini listeler.

Ne zaman kullanılır?

Muhasebe ve finans ekiplerinin banka hareketleriyle KargoJet COD aktarım kayıtlarını eşleştirmesi için kullanılır.

Parametreler

Alan	Tip	Zorunluluk	Açıklama
status	scheduled \| paid \| failed	Opsiyonel	Aktarım durumuna göre filtreleme.
dateFrom / dateTo	ISO date	Opsiyonel	Aktarım tarih aralığı.

Request

bash

curl https://api.kargojet.com/v1/cod/transfers \
  -X GET \
  -H "Authorization: Bearer $KARGOJET_API_TOKEN" \
  -H "Content-Type: application/json"

Response

json

{
  "data": [
    {
      "id": "cod_tr_01HX",
      "status": "paid",
      "grossAmount": 184250.75,
      "commission": 4210.50,
      "netAmount": 180040.25,
      "paidAt": "2026-05-09T12:00:00Z"
    }
  ]
}

Operasyon Notu

Aktarım listesi banka mutabakatında ana referanstır.

Operasyon Notu

failed durumundaki aktarım hareketleri finans operasyonu tarafından manuel incelenmelidir.

Hata Durumları

HTTP 401

Token eksik, geçersiz veya süresi dolmuş.

HTTP 403

Token bu işlem için yetkili değil.

HTTP 422

Gönderilen alanlardan biri operasyonel doğrulamadan geçmedi.

HTTP 429

Rate limit aşıldı. Retry-After başlığı dikkate alınmalı.

POST/v1/cod/reconciliation

Kapıda ödeme mutabakatı başlat

Belirli tarih aralığındaki COD gönderi, tahsilat, komisyon ve aktarım kayıtlarını karşılaştırır.

Ne zaman kullanılır?

Ay sonu veya haftalık finans kapanışında taşıyıcı tahsilat kayıtlarıyla KargoJet kayıtlarını eşleştirmek için kullanılır.

Request

bash

curl https://api.kargojet.com/v1/cod/reconciliation \
  -X POST \
  -H "Authorization: Bearer $KARGOJET_API_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: ORD-10042" \
  -d @payload.json

Body

json

{
  "dateFrom": "2026-05-01",
  "dateTo": "2026-05-09",
  "carrierCode": "aras",
  "includeTransferred": true
}

Response

json

{
  "jobId": "cod_rec_01HX",
  "status": "processing",
  "estimatedReadyAt": "2026-05-09T12:05:00Z"
}

Operasyon Notu

Mutabakat sonucu asenkron hazırlanır; yüksek hacimde doğrudan response beklenmemelidir.

Operasyon Notu

Fark çıkan kayıtlar collectionReference, trackingNumber ve transferId ile raporlanmalıdır.

Hata Durumları

HTTP 401

Token eksik, geçersiz veya süresi dolmuş.

HTTP 403

Token bu işlem için yetkili değil.

HTTP 422

Gönderilen alanlardan biri operasyonel doğrulamadan geçmedi.

HTTP 429

Rate limit aşıldı. Retry-After başlığı dikkate alınmalı.

HTTP 409

Aynı tarih aralığı için devam eden mutabakat işi var.

Kargo Şablonları

Paket şablonları sık kullanılan kutu ölçülerini standartlaştırır ve desi hatalarını azaltır.

POST/v1/parcel-templates

Paket şablonu oluştur

Sık kullanılan kutu ölçüsünü kayıt altına alır.

Ne zaman kullanılır?

Depo ekibinin her siparişte ölçü girmesini engellemek için.

Request

bash

curl https://api.kargojet.com/v1/parcel-templates \
  -X POST \
  -H "Authorization: Bearer $KARGOJET_API_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: ORD-10042" \
  -d @payload.json

Body

json

{ "name": "Küçük Kutu", "widthCm": 20, "lengthCm": 15, "heightCm": 10, "weightKg": 0.4 }

Response

json

{ "id": "tpl_01HX", "billableDesi": 1 }

Operasyon Notu

Şablonlar ürün değil, paketleme standardıdır.

Hata Durumları

HTTP 401

Token eksik, geçersiz veya süresi dolmuş.

HTTP 403

Token bu işlem için yetkili değil.

HTTP 422

Gönderilen alanlardan biri operasyonel doğrulamadan geçmedi.

HTTP 429

Rate limit aşıldı. Retry-After başlığı dikkate alınmalı.

GET/v1/parcel-templates

Paket şablonlarını listele

Hesaba kayıtlı paket ölçü şablonlarını listeler.

Ne zaman kullanılır?

Gönderi oluşturma ekranında kutu seçimi sunmak için.

Request

bash

curl https://api.kargojet.com/v1/parcel-templates \
  -X GET \
  -H "Authorization: Bearer $KARGOJET_API_TOKEN" \
  -H "Content-Type: application/json"

Response

json

{ "data": [{ "id": "tpl_01HX", "name": "Küçük Kutu", "billableDesi": 1 }] }

Operasyon Notu

Depo süreçlerinde şablon seçimi gerçek ölçüm ihtiyacını azaltır.

Hata Durumları

HTTP 401

Token eksik, geçersiz veya süresi dolmuş.

HTTP 403

Token bu işlem için yetkili değil.

HTTP 422

Gönderilen alanlardan biri operasyonel doğrulamadan geçmedi.

HTTP 429

Rate limit aşıldı. Retry-After başlığı dikkate alınmalı.

DELETE/v1/parcel-templates/{templateId}

Paket şablonu sil

Kullanılmayan paket şablonunu siler.

Ne zaman kullanılır?

Artık kullanılmayan kutu tiplerini listeden kaldırmak için.

Request

bash

curl https://api.kargojet.com/v1/parcel-templates/{templateId} \
  -X DELETE \
  -H "Authorization: Bearer $KARGOJET_API_TOKEN" \
  -H "Content-Type: application/json"

Response

json

{ "deleted": true }

Operasyon Notu

Geçmiş gönderilerin paket ölçüleri etkilenmez.

Hata Durumları

HTTP 401

Token eksik, geçersiz veya süresi dolmuş.

HTTP 403

Token bu işlem için yetkili değil.

HTTP 422

Gönderilen alanlardan biri operasyonel doğrulamadan geçmedi.

HTTP 429

Rate limit aşıldı. Retry-After başlığı dikkate alınmalı.

Özel Kargo Anlaşmaları

Kendi Aras, Yurtiçi, MNG veya diğer taşıyıcı sözleşmelerinizi KargoJet operasyon akışına bağlar.

POST/v1/provider-accounts

Taşıyıcı hesabı oluştur

Kendi kargo sözleşmenize ait müşteri kodu ve entegrasyon bilgilerini kaydeder.

Ne zaman kullanılır?

KargoJet fiyatlarıyla birlikte kendi sözleşmeli fiyatlarınızı da kullanmak için.

Request

bash

curl https://api.kargojet.com/v1/provider-accounts \
  -X POST \
  -H "Authorization: Bearer $KARGOJET_API_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: ORD-10042" \
  -d @payload.json

Body

json

{ "carrierCode": "aras", "customerCode": "123456", "username": "api_user", "password": "***" }

Response

json

{ "id": "pa_01HX", "carrierCode": "aras", "status": "test_required" }

Operasyon Notu

Bilgiler kaydedildikten sonra test endpoint'iyle doğrulanmalıdır.

Hata Durumları

HTTP 401

Token eksik, geçersiz veya süresi dolmuş.

HTTP 403

Token bu işlem için yetkili değil.

HTTP 422

Gönderilen alanlardan biri operasyonel doğrulamadan geçmedi.

HTTP 429

Rate limit aşıldı. Retry-After başlığı dikkate alınmalı.

GET/v1/provider-accounts

Taşıyıcı hesaplarını listele

Bağlı özel taşıyıcı anlaşmalarını ve durumlarını listeler.

Ne zaman kullanılır?

Panelde kargo anlaşmaları ekranını beslemek için.

Request

bash

curl https://api.kargojet.com/v1/provider-accounts \
  -X GET \
  -H "Authorization: Bearer $KARGOJET_API_TOKEN" \
  -H "Content-Type: application/json"

Response

json

{ "data": [{ "id": "pa_01HX", "carrierCode": "aras", "status": "active" }] }

Operasyon Notu

Şifre veya secret alanları response içinde açık dönmez.

Hata Durumları

HTTP 401

Token eksik, geçersiz veya süresi dolmuş.

HTTP 403

Token bu işlem için yetkili değil.

HTTP 422

Gönderilen alanlardan biri operasyonel doğrulamadan geçmedi.

HTTP 429

Rate limit aşıldı. Retry-After başlığı dikkate alınmalı.

DELETE/v1/provider-accounts/{providerAccountId}

Taşıyıcı hesabı sil

Özel taşıyıcı anlaşmasını pasife alır.

Ne zaman kullanılır?

Sözleşme bittiyse veya taşıyıcı artık kullanılmayacaksa.

Request

bash

curl https://api.kargojet.com/v1/provider-accounts/{providerAccountId} \
  -X DELETE \
  -H "Authorization: Bearer $KARGOJET_API_TOKEN" \
  -H "Content-Type: application/json"

Response

json

{ "deleted": true }

Operasyon Notu

Pasife alınan anlaşma yeni gönderilerde teklif üretmez.

Hata Durumları

HTTP 401

Token eksik, geçersiz veya süresi dolmuş.

HTTP 403

Token bu işlem için yetkili değil.

HTTP 422

Gönderilen alanlardan biri operasyonel doğrulamadan geçmedi.

HTTP 429

Rate limit aşıldı. Retry-After başlığı dikkate alınmalı.

Çeşitli Hata Kodları

Hata kodları, entegrasyonun kullanıcıya doğru mesaj vermesi ve otomatik retry kararını doğru alması için standartlaştırılır.

GET/v1/error-codes

Hata kodlarını listele

KargoJet API'de dönebilecek hata kodlarını, açıklamalarını ve aksiyon önerilerini listeler.

Ne zaman kullanılır?

Uygulama içinde kullanıcı dostu hata mesajı göstermek ve teknik logları sınıflandırmak için.

Request

bash

curl https://api.kargojet.com/v1/error-codes \
  -X GET \
  -H "Authorization: Bearer $KARGOJET_API_TOKEN" \
  -H "Content-Type: application/json"

Response

json

[{ "code": "invalid_recipient_address", "httpStatus": 422, "action": "Adres il/ilçe eşleşmesini kontrol edin." }]

Operasyon Notu

4xx hataları genelde veri düzeltmesi ister; 5xx ve 429 hataları retry adayıdır.

Operasyon Notu

Her hata response'unda requestId saklanmalıdır.

Hata Durumları

HTTP 401

Token eksik, geçersiz veya süresi dolmuş.

HTTP 403

Token bu işlem için yetkili değil.

HTTP 422

Gönderilen alanlardan biri operasyonel doğrulamadan geçmedi.

HTTP 429

Rate limit aşıldı. Retry-After başlığı dikkate alınmalı.