JetDiji Servis Entegrasyon Rehberi

1. Hızlı başlangıç

Üç komutla ilk gönderinizi açıp durumunu sorgulayın. Örnekler preprod ortamını kullanır; *** yerine kendi bilgilerinizi yazın.

1. Token alın. Gövde form biçimindedir (application/x-www-form-urlencoded).

   KopyalaBASE=https://api.preprod.jetdiji.com
   curl -s -X POST "$BASE/api/integration/v1/oauth/token" \
     -H "Content-Type: application/x-www-form-urlencoded" \
     -d "grant_type=client_credentials" \
     -d "client_id=***" \
     -d "client_secret=***"

   Yanıttaki access_token değerini saklayın (varsayılan 900 sn geçerli):

   KopyalaTOKEN=<access_token>

2. Gönderi oluşturun. Yazma isteklerinde X-Idempotency-Key zorunludur.

   Kopyalacurl -s -X POST "$BASE/api/integration/v2/shipments" \
     -H "Authorization: Bearer $TOKEN" \
     -H "Content-Type: application/json" \
     -H "X-Idempotency-Key: 7d0f4c4e-1b2a-4f7e-9c3d-5a6b7c8d9e0f" \
     -d '{
       "customerReference": "SIP-2026-000123",
       "productCode": "<ürün kodu>",
       "recipient": { "name": "<Alıcı Adı Soyadı>", "phone": "<05XXXXXXXXX>" },
       "destinationAddress": {
         "countryCode": "TR", "cityCode": "34", "districtCode": "1421",
         "addressLine": "<Açık adres>"
       }
     }'

   İlk çağrı 201 ve "replayed": false döner. Aynı komutu tekrar çalıştırın: aynı gönderi "replayed": true ile döner, ikinci kayıt açılmaz. Yanıttaki data.shipmentNumber değerini not edin.
3. Durumu sorgulayın. Takip numarası henüz yoksa gönderi numarasını kullanın.

   Kopyalacurl -s "$BASE/api/integration/v2/shipments/<shipmentNumber>?include=movements" \
     -H "Authorization: Bearer $TOKEN"

   ?include=movements için token'da shipment.events.read scope'u olmalıdır; yoksa parametreyi kaldırın.

2. Ortamlar ve hesap

• Doküman her ortamda /swagger/index.html adresindedir. "Try it out" yalnız test ortamında açıktır.
• Hesap: client_id ve client_secret bilgilerini JetDiji ekibinden isteyin: info@jetlogi.com.
• Talepte hangi ürün(ler) için entegrasyon yapacağınızı ve hangi uçları kullanacağınızı belirtin; scope'lar buna göre tanımlanır (bkz. 3. bölüm).
• Gönderilerinizi web üzerinden de izleyebilirsiniz: https://panel.jetdiji.com.
• Token'ı hangi ortamdan aldıysanız o ortamda kullanın.

Temel biçimler

• Tüm gönderi uçları /api/integration/v2/ ile başlar. Token ucu /api/integration/v1/oauth/token adresinde kalır.
• İstek ve yanıt gövdeleri JSON'dur (token ucu hariç). Tarih/saat alanları ISO 8601 döner.
• Başarılı yanıt: { "success": true, "data": {…}, "requestId": "REQ-…", "correlationId": null }. Yazma uçlarında ek olarak replayed gelir.
• İl ve ilçe kodla verilir: cityCode plaka kodudur (ör. 34), districtCode JetDiji ilçe kodudur (ör. Kadıköy 1421). Kod listelerini referans uçlarından alın: reference/cities ve reference/cities/{cityCode}/districts.

İsteğe bağlı izleme başlıkları

3. Kimlik doğrulama

Servis OAuth 2.0 client credentials akışını kullanır.

1. POST /api/integration/v1/oauth/token, Content-Type: application/x-www-form-urlencoded, gövdede grant_type=client_credentials.
2. Kimliği iki yoldan biriyle gönderin: Authorization: Basic base64(client_id:client_secret) başlığı ya da client_id + client_secret form alanları. İkisi birlikte gelir ve çelişirse 401 invalid_client.
3. İsterseniz scope alanında boşlukla ayrılmış liste verin. Boş bırakırsanız istemcinize tanımlı tüm scope'lar verilir; tanımlı olmayan scope isterseniz 400 invalid_scope.
4. Yanıt: { "access_token": "…", "token_type": "Bearer", "expires_in": 900, "scope": "…" }. Yanıt Cache-Control: no-store ile gelir.
5. Sonraki her istekte Authorization: Bearer <access_token> gönderin. Süre dolunca yeni token alın; yenileme (refresh) ucu yoktur.

Scope'lar ve uçlar

İptal uçları shipment.cancel scope'unu ister. shipment.update iptal yetkisi vermez. İptal kullanacaksanız bu scope'u hesap talebinizde belirtin.

Scope eksikse uç 403 CUSTOMER_API_SCOPE_FORBIDDEN döner. Scope, istemcinizin güncel tanımıyla birlikte kontrol edilir: tanımınızdan çıkarılan bir scope, eski token'da olsa bile kullanılamaz.

4. Gönderi yaşam döngüsü

Bir gönderinin entegrasyon tarafındaki tipik yolculuğu. Parantez içindeki adımlar isteğe bağlıdır.

Gönderi kimlikleri

Oluşturma yanıtında dört kimlik döner. Hangisinin nerede kullanılacağı:

1. (Kodları hazırlayın.) İl ve ilçe kodlarını GET reference/cities ve …/districts ile alıp önbelleğe alın. Kart
2. Oluştur. POST shipments. Yanıttaki shipmentNumber'ı saklayın; trackingNumber oluşturma anında boş olabilir. Tüm {trackingNumber} yollarında gönderi numarası da kabul edilir. Kart
3. (Güncelle.) Teslimden önce alıcı/adres (PATCH {trackingNumber} ya da …/address), ürün listesi (PUT …/products) ya da müşteri referansı (PUT …/customer-reference) değiştirilebilir. Bu uçlarda durum kısıtı yoktur. Kartlar
4. (Hazırlık ve evrak.) Gerekli evrakları GET …/required-documents ile öğrenin. Ürününüzde onay adımı varsa gönderi 2041 Onay Bekleniyor aşamasına gelince kararınızı POST …/preparation-status ile iletin. Kartlar
5. Durum ve hareket takibi. GET shipments/{trackingNumber} (ya da müşteri referansı / işlem numarasıyla arama). Geçmiş için ?include=movements ya da GET …/movements. Son durumlar: 5010 Teslim Edildi, 7020 İade Edildi, 5140 İmha Edildi, 8010–8030 İptal. Kartlar
6. (İptal.) Sipariş sizin tarafınızda iptal olursa POST …/cancel. Gönderinin bulunduğu aşamada iptal yolu yoksa 409 döner. Kartlar

Güncelleme, hazırlık kararı ve iptal kayıtları durum kodu taşımaz; hareket listesinde görünmez. Sonucu durum sorgusuyla izleyin.

5. Hata yönetimi

Tüm v2 uçları aynı hata zarfını döner (şema ErrorResponse):

Kopyala{ "success": false,
  "error": { "code": "VALIDATION_ERROR",
             "message": "The request body does not match CreateShipmentRequest.",
             "details": [ { "path": "recipient.phone", "message": "…" } ] },
  "requestId": "REQ-3f6c2a9e-…",
  "correlationId": null }

• Yalnız error.code ve HTTP durumuna bakın. message İngilizcedir ve değişebilir.
• details çoğunlukla null'dur. VALIDATION_ERROR'da her sorun için { "path", "message" } içerir. Gövdedeki bilinmeyen alan da 422 döner.
• Token ucu farklı biçim kullanır: { "error": "invalid_client", "error_description": "…" }.

İstemci ne yapmalı

6. Idempotency ve tekrar deneme

Ağ kesintisinde aynı işlemi güvenle tekrarlayabilmeniz için tüm yazma uçları (POST/PATCH/PUT) X-Idempotency-Key başlığını zorunlu ister. Yoksa 400 IDEMPOTENCY_KEY_REQUIRED.

1. Her yeni işlem için yeni bir anahtar üretin (UUID önerilir) ve isteği göndermeden önce işlemle birlikte saklayın.
2. Yanıt alamazsanız (zaman aşımı, 5xx) aynı anahtar ve aynı gövdeyle tekrar deneyin.
3. Yanıtta "replayed": true görürseniz işlem daha önce uygulanmıştır; yeniden uygulanmadı. data gönderinin güncel değerlerini taşır.
4. Farklı bir işlem için asla eski anahtarı kullanmayın; 409 IDEMPOTENCY_KEY_REUSE_CONFLICT alırsınız.

• Anahtarlar işlem türüne göre ayrı tutulur: aynı anahtarı oluşturma ve güncelleme için kullanmak çakışma üretmez, ama bunu yapmayın.
• İki iptal ucu (takip no ve işlem no) aynı anahtar alanını paylaşır.
• Aynı anahtarla eşzamanlı gelen iki istekten biri işlemi uygular, diğeri replay olarak döner.
• Hazırlık kararında aynı karar daha önce uygulandıysa yeni anahtarla da replayed: true dönebilir.

7. Uç uç kartlar

Her kart aynı şablonu izler: Amaç, İstek, Yanıt, İş kuralları, Hata durumunda. Yollar /api/integration/v2/ önekiyle yazılmamıştır (token ucu hariç). Tüm yazma uçlarında Authorization ve X-Idempotency-Key başlıkları gerekir.

8. Durum, alt durum ve neden kodları

v2 her zaman kanonik JetDiji kodlarını döner. Adlar Türkçedir.

Ana gruplar

Durumlar (statusCode)

• Neden adı müşteriye gösterilen addır; JetDiji'nin iç adından farklı olabilir (ör. 9312).
• Kod listesine yeni değerler eklenebilir. Bilinmeyen kodu hata saymayın; name alanını gösterin.

9. Profil farkları

Davranış farkları istemcinizin bağlı olduğu üründen gelir. Aynı uçlar herkes için geçerlidir.

Ürün kapsamı

• İstemciniz bir ürüne bağlıysa yalnız o ürünün gönderilerini görür ve değiştirir. Başka üründeki gönderi 404 SHIPMENT_NOT_FOUND görünür; başka ürünle oluşturma 403 PRODUCT_NOT_ALLOWED_FOR_CLIENT döner.
• Ürüne bağlı olmayan istemci, müşterinin tüm ürünlerini görür.
• Tüm sorgular kendi müşteri hesabınızla sınırlıdır.

Token'daki profil kodu (ör. KUVEYTTURK_HGS_V2, KUVEYTTURK_CARD_V1) yalnız tutarlılık için kontrol edilir; v2 davranışını değiştirmez.

10. v1'den v2'ye geçiş

Eski /api/ShipmentsService/* uçları çalışmaya devam eder (Eski sürüm (v1)). Yeni entegrasyonlar ve geçişler v2'yi kullanmalıdır.

Kimlik doğrulama

• Eski uçlarda her istek gövdesinde auth.userName / auth.password vardı. v2'de bir kez token alıp Authorization: Bearer … gönderirsiniz (3. bölüm).
• Eski kullanıcı adı/şifre v2'de çalışmaz. v2 için JetDiji ekibinden client_id / client_secret isteyin.
• Tüm yazma isteklerine X-Idempotency-Key ekleyin (6. bölüm).

Uç eşleme

Eski Base ve normal durum uçları aynı veriyi farklı zarfla dönüyordu (Base'de result sarmalayıcısı yoktu, errorCode sayıydı). v2'de tek zarf olduğu için ikisi tek uca eşlenir.

Kimlik eşleme

Alan eşleme

Örnek: eski Update → v2 PATCH

Kopyala# Eski (gövde, özet)
{ "transactionID": "123456789",
  "acceptorName": "<Ad>", "acceptorSurName": "<Soyad>", "acceptorGSM": "<05XXXXXXXXX>",
  "acceptorCity": "İSTANBUL", "acceptorDistrict": "KADIKÖY", "acceptorAddress": "<Açık adres>" }

# v2: önce takip numarasını bulun
curl -s "$BASE/api/integration/v2/shipments/lookup/transaction/123456789" \
  -H "Authorization: Bearer $TOKEN"

# sonra güncelleyin (il/ilçe kodla)
curl -s -X PATCH "$BASE/api/integration/v2/shipments/<trackingNumber>" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -H "X-Idempotency-Key: 0b8e9c1a-6f2d-4e3b-8a7c-1d2e3f4a5b6c" \
  -d '{ "recipient": { "name": "<Ad Soyad>", "phone": "<05XXXXXXXXX>" },
        "destinationAddress": { "countryCode": "TR", "cityCode": "34", "districtCode": "1421",
                                "addressLine": "<Açık adres>" } }'

Örnek: eski UpdateStatus → v2 hazırlık kararı

Kopyala# Eski: { "transactionID": "123456789", "statusID": 1 }
curl -s -X POST "$BASE/api/integration/v2/shipments/<trackingNumber>/preparation-status" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -H "X-Idempotency-Key: 5c4b3a29-1807-4f6e-9d5c-4b3a29180706" \
  -d '{ "decision": "APPROVE" }'

Önemli farklar

• Durum kodları kanonik. v2 her zaman kanonik JetDiji kodlarını döner; eski uçlardaki müşteriye özel dış kod projeksiyonu (ör. 6020) yoktur. Sözlük için 8. bölüme bakın.
• İl/ilçe adı yerine kod. Eski Update ve UpdateAddress il/ilçe adını da kabul ediyordu; v2 yalnız cityCode / districtCode kabul eder.
• Boş dönen alanlar. outputNumber, productNumber, appointmentDate v2'de şimdilik null döner. cargoKey, cargoUrl, barcode / returnBarcode yoktur; create yanıtında trackingUrl, label, returnLabel şimdilik null.
• Hareket geçmişi ayrı. Eskinin tek çağrıda verdiği stateHistory yerine ?include=movements ya da …/movements kullanın; ikisi de shipment.events.read ister.
• İptal için ayrı scope. İptal uçları shipment.cancel ister; shipment.update yetmez.
• Hazırlık kararı enum. statusID yerine decision: APPROVE = 1, REJECT_REMATCH = 2, REJECT_RELEASE = 5. Ön koşul aynıdır: gönderi onay bekliyor olmalı.
• Kısmi güncelleme. Eski Update eksik GSM'i boş yazar ve adresi her zaman isterdi. v2 PATCH'te gönderilmeyen alan değişmez; adres isteğe bağlıdır.
• Hata biçimi. Sayısal hata kodları yerine metin error.code ve HTTP durumu (5. bölüm).