Şube Mobil API Rehberi

1. Hızlı başlangıç

Dört istekle ilk akışı preprod ortamında deneyin. Şifre yerine kendi test şifrenizi yazın.

1. Giriş yapın, token alın. X-Client-Type: mobile başlığı şarttır; yoksa token yanıtta gelmez.

   Kopyalacurl -X POST "https://api-mobile.preprod.jetdiji.com/api/portal/v1/agency-auth/login" \
     -H "Content-Type: application/json" \
     -H "X-Client-Type: mobile" \
     -d '{"email":"sube.yetkili@example.com","password":"***"}'

   Yanıttaki data.accessToken değerini saklayın (8 saat geçerli). 409 AGENCY_SELECTION_REQUIRED gelirse error.agencies listesinden bir id seçip aynı isteğe "agencyId" ekleyin.
2. Oturumu doğrulayın. Yetkiler (capabilities) buradan gelir.

   KopyalaTOKEN="buraya-accessToken"
   curl "https://api-mobile.preprod.jetdiji.com/api/portal/v1/agency-auth/session" \
     -H "Authorization: Bearer $TOKEN"

3. Bir ekran verisi okuyun (B11 Ana sayfa).

   Kopyalacurl "https://api-mobile.preprod.jetdiji.com/api/portal/v1/branch/dashboard" \
     -H "Authorization: Bearer $TOKEN"

4. Bir yazma isteği gönderin (kurye ata). Gönderi ve kurye kimliklerini GET branch/preparation ve GET branch/dispatch/options?shipmentId=… yanıtlarından alın. Her yazma isteğinde yeni bir Idempotency-Key üretin.

   Kopyalacurl -X POST "https://api-mobile.preprod.jetdiji.com/api/portal/v1/branch/dispatch/handover" \
     -H "Authorization: Bearer $TOKEN" \
     -H "Content-Type: application/json" \
     -H "Idempotency-Key: 6f1d1c7e-2b7a-4e0c-9a51-3a9f8f2e7b10" \
     -d '{"courierId":"KURYE_ID","shipmentIds":["GONDERI_ID"]}'

   Aynı komutu aynı anahtarla tekrar çalıştırın: yanıt 200 ve data.replayed: true olur, ikinci bir zimmet açılmaz.

2. Ortamlar ve hesaplar

• Yollar iki ortamda aynıdır: /api/portal/v1/....
• Hesaplar ve token'lar ortamlar arasında geçmez.
• Swagger'daki / ("Aynı origin") sunucusu yalnız doküman panelin kendi alan adında açıldığında kullanılır. "Try it out" yalnız test ortamlarında çalışır.
• Test hesabı: JetDiji ekibinden isteyin. Tüm düğmeleri deneyebilmek için AGENCY_ADMIN rolü isteyin; yalnız operasyon akışını görmek için AGENCY_OPERATOR yeterlidir (bkz. Roller).

3. Kimlik doğrulama

1. POST agency-auth/login — gövde { email, password, agencyId? }, başlık X-Client-Type: mobile. Yanıt: data.accessToken, data.tokenType: "Bearer", data.expiresAt (ISO). Başlık yoksa token yalnız jetdiji_agency_session çerezine yazılır (web).
2. Şube seçimi (409). Kullanıcının birden çok şube yetkisi varsa ya da kullanıcı SYSTEM_OWNER ise (tek şube olsa bile) yanıt 409 AGENCY_SELECTION_REQUIRED + error.agencies[] olur. Kullanıcıya listeyi gösterin, seçilen id'yi agencyId olarak ekleyip aynı isteği tekrarlayın. SYSTEM_OWNER tüm aktif şubeleri seçebilir; şube rolü olmadan da şube seçerek bağlanabilir.
3. GET agency-auth/session — açılışta token'ı doğrulayın; rolleri (roles[].code), yetenekleri (capabilities: { operate, manage }) ve şube bilgisini alın.
4. Sonraki tüm isteklerde Authorization: Bearer <accessToken>. Token, web çerezindekiyle aynı HS256 JWT'dir.
5. POST agency-auth/logout — sunucu oturumu LOGGED_OUT yapar; token artık geçmez. Token geçersiz ya da eksik olsa da 200 döner. Ardından token'ı cihazdan silin.

Token süresi

• Oturum 8 saat geçerlidir (JWT exp + sunucudaki portal_user_sessions.expiresAt).
• Süre dolunca, oturum iptal edilince ya da şube / kullanıcı pasifleşince tüm uçlar 401 UNAUTHENTICATED döner → giriş ekranı.
• Yenileme (refresh) ucu yoktur; süre dolunca yeniden giriş gerekir.

Giriş hataları

Hata ek alanları (remainingAttempts, lockedUntil, agencies) error içindedir. Üst seviye kopyaları ve 409'daki data.agencies yalnız eski web uyumluluğu içindir; mobil error.* okur.

Diğer notlar

• E-posta küçük harfe çevrilir. Davetli (INVITED) kullanıcı ilk girişte ACTIVE olur.
• Şifre değiştirme: şube API'sinde şifre değiştirme ucu yoktur. mustChangePassword: true gelirse bunu kullanıcıya bilgi olarak gösterin.
• Token saklama: iOS Keychain / Android Keystore (EncryptedSharedPreferences). Düz dosyaya ya da AsyncStorage'a yazmayın; token'ı loglamayın.
• Web çerezi (jetdiji_agency_session, httpOnly) de desteklenir ama mobilde kullanılmaz.
• Yetki ve düğme gösterimi için Roller bölümüne bakın.

4. Hata yönetimi

Tüm uçlar (kimlik, acente, şube) aynı zarfı döner:

Kopyala{
  "success": false,
  "error": {
    "code": "DISPATCH_NOT_READY",
    "message": "Gönderi artık dağıtıma hazırlık adımında değil. Ekranı yenileyin.",
    "shipmentNumber": "JD2026100300123"
  },
  "code": "DISPATCH_NOT_READY",
  "message": "Gönderi artık dağıtıma hazırlık adımında değil. Ekranı yenileyin."
}

• Yalnız error.code'a bakın. error.message varsa kullanıcıya doğrudan gösterilebilir; yoksa kod için kendi çevirinizi kullanın. Üst seviye code / message eski web uyumluluğu içindir.
• Uca özgü ek alanlar error içindedir (eski error.details kaldırıldı): shipmentNumber, transferId, transferNumber, max, variables, allowed, reason, issues, minLength / maxLength; login'de remainingAttempts, lockedUntil, agencies.
• Bozuk JSON: JSON gövde okuyan tüm uçlarda bozuk / boş / nesne olmayan gövde → 400 INVALID_JSON (eski INVALID_BODY kaldırıldı). İstisna: transfers/incoming/{id}/confirm boş gövdeyi {} sayar.
• Şema hatası (geçerli JSON, yanlış alan): zod kullanan uçlarda (transfer, etiket, sayım) 422 VALIDATION_FAILED + error.issues: [{ path, code, message }]; diğer uçlarda uca özgü 400 kodları (ör. DISPATCH_INVALID_INPUT, CARD_OWNER_TYPE_INVALID).
• Başarı: { "success": true, "data": ... }. Yazma uçlarında ayrıca üst seviye replayed / idempotent gelir (eski web uyumluluğu; mobil data.replayed okur).

İstemci ne yapmalı

400 hataları (eksik anahtar, bozuk JSON, geçersiz alan) istemci hatasıdır: düzeltmeden tekrar göndermeyin.

5. Yazma istekleri ve çevrimdışı

Idempotency-Key kuralı

• Tüm şube yazma uçlarında başlık Idempotency-Key zorunludur: 8–160 karakter, boşluksuz görünür ASCII (0x21–0x7E). Önerilen: UUID v4.
• Her kullanıcı eylemi için bir kez üretin; yeniden denemede aynı anahtarı gönderin.
• Başlık yok → 400 IDEMPOTENCY_KEY_REQUIRED. Uzunluk / karakter dışı → 400 IDEMPOTENCY_KEY_INVALID (error.minLength, error.maxLength). Sunucu anahtarı kırpmaz, yok saymaz.
• X-Client-Event-Id başlığı ve gövdedeki clientEventId anahtar yerine geçmez. Sunucu başlığı okumaz; gövde alanı varsa yalnız audit kaydına yazılır.

Tekrar davranışı

• Aynı anahtar + aynı uç tekrar gelirse ilk başarılı sonuç döner: HTTP 200 (ilk istek 201/202 olsa bile) ve data.replayed: true (ilk istekte false). Üst seviye replayed ve idempotent aynı değerin eski web kopyasıdır.
• Anahtar kapsamı: dağıtım, etiket, sayım ve kart uçlarında aynı kullanıcı; transfer, kurye dönüşü, SMS ve fatura uçlarında aynı şube.
• Hatalı ilk istek saklanmaz; aynı anahtarla yeniden denenebilir. Aynı anahtar farklı gövdeyle gelirse ilk sonuç döner (gövde karşılaştırılmaz).
• Sonucu nesne olmayan işlemlerde (counts/{id} void-scan, line-reason, close, cancel) yanıt data: { result: null, replayed } olur.
• Kontrol sırası: oturum (401) → yetenek (403) → anahtar (400) → gövde (400/422). İstisnalar: compliance/cards yeteneği gövdedeki ownerType'a göre seçtiği için anahtar → gövde → yetenek; counts/{id} yetenek kontrolü (action'a göre) gövde doğrulandıktan ve sayım bulunduktan sonra yapılır.

Anahtar gerekmeyen POST'lar (yan etkisiz; başlık gönderilirse yok sayılır): transfers/outgoing/resolve, preparation/print-rows, sms/preview, compliance/cards/verify (audit yazar ama durum değiştirmez). agency-auth/login ve logout da anahtar istemez.

Çevrimdışı kuyruk

Web'deki offline-queue.ts ile aynı sözleşme:

1. Kullanıcı eylemi geldiğinde anahtarı üretin ve isteği anahtarıyla birlikte cihazda saklayın.
2. İsteği gönderin. Ağ hatası ya da 5xx gelirse kuyrukta tutun ve aynı Idempotency-Key ile yeniden deneyin.
3. Sunucu teyidi (success: true) gelmeden "tamamlandı / içeri alındı" göstermeyin; o ana kadar "kuyrukta" gösterin.
4. 4xx yanıt kalıcı hatadır: kaydı kuyruktan çıkarın ve kullanıcıya gösterin.

6. Ekran ekran akışlar

Her kart aynı sırayı izler: amaç, çağrı sırası, iş kuralları, hata durumunda ne yapılmalı. Yollar /api/portal/v1/ önekiyle başlar. Tüm yazma çağrıları Idempotency-Key ister (bkz. 5. bölüm); yetki için Roller bölümüne bakın.

7. Kavramlar

Gönderi durum kodları

currentStatusCode sayısal metindir. Şube uçlarında kullanılanlar:

Aşama (stage)

• INCOMING: merkezde hazırlanıyor, bu şubeye gelecek.
• AWAITING_COURIER: 4010, kurye yok.
• IN_QUEUE: 4010, kuryeye zimmetlendi, kurye henüz okutmadı.
• IN_DISTRIBUTION: 4020, dağıtımda.

Neden kodları

• 9117 Normal ilk çıkış.
• 9116 Devir: alıcıya ulaşılamayınca tekrar çıkış. Öncelik HIGH.
• Teslim edilemedi (5110) nedenleri ayrı bir uçta değil, GET branch/courier-jobs yanıtındaki cancelReasons[] içinde gelir.

Zimmet kuralları

• Okutarak kabul: kurye ataması (dispatch/handover) gönderiyi 4010'da bırakır (stage=IN_QUEUE). Zimmet ve 4020'ye geçiş yalnız kurye kendi uygulamasında okutarak kabul ettiğinde olur.
• Kurye değişimi: dağıtımdaki gönderide reassign REASSIGN devri açar; yeni kurye okutana kadar zimmet eski kuryededir.
• Gün sonu: kurye gönderiyi elinde tutabilir; gün sonu iadesi şubede okutularak alınır (pending/courier-return-scan). Kabulde otomatik yeniden dağıtım denenir (redelivery).
• Kuryede bekleme alarmı: varsayılan 24 saat; şube bazında 1–336 saat arası ayarlanabilir (Provider.configuration.courierHoldingAlertHours). Yanıtlarda alertHours / holdingAlertHours olarak gelir; overdue bayrakları bu eşiğe göredir.

8. Roller (operate / manage)

Şube tek bir yetki modeli kullanır (src/modules/agency-portal/branch-permissions.ts). Roller iki yeteneğe çevrilir:

• Sistem sahibi = oturumda isSystemOwner: true ya da rol kodu SYSTEM_OWNER. Şube rolü olmadan girişte şube seçerek bağlanabilir.
• Düğmeler: GET agency-auth/session → user.capabilities: { operate, manage }. Aynı nesne preparation, dispatch, courier-jobs, counts, counts/{id} yanıtlarında capabilities olarak da gelir.
• Eski canManage alanı korunur: preparation / dispatch / courier-jobs → capabilities.operate; counts / counts/{id} → capabilities.manage. Mobilde capabilities kullanın.
• Yetkisiz kullanıcıya yazma düğmelerini pasif ve ipuçlu gösterin; yine de her yazma ucunda 403'ü ele alın.
• Yetki hatası her uçta tektir: 403 FORBIDDEN, error.reason = BRANCH_OPERATE_REQUIRED ("Bu işlem şube operasyon yetkisi gerektirir.") ya da BRANCH_MANAGE_REQUIRED ("Bu işlem şube yöneticisi yetkisi gerektirir."). Eski BRANCH_FORBIDDEN kodu ve eski reason değerleri (BRANCH_DISPATCH_ROLE_REQUIRED, COUNT_PERMISSION_REQUIRED) artık dönmez.

Uç → yetki tablosu

9. Etiket yazdırma (ZPL)

• branch/labels uçları her etikette hazır ZPL (zpl) döner: 100×100 mm, 203 dpi (^PW800 ^LL800), ^CI28 (UTF-8). QR yazıcıda üretilir (^BQ).
• Alıcı adı ve telefonu etikete asla basılmaz; yanıtta da yer almaz.

1. POST branch/labels { action: "generate", labelTypeCode, quantity, warehouseId, shipmentReference? }
2. ZPL'i Zebra yazıcıya gönderin: Bluetooth (Zebra Link-OS SDK / BLE SPP) ya da ağ üzerinden TCP 9100 portuna ham ZPL. Birden çok etiketi \n ile birleştirip tek seferde yollayabilirsiniz (web de böyle yapar).
3. Baskı başarılı olunca POST branch/labels { action: "printed", labelIds, printer: "<cihaz adı>" } (sayaç + audit). Web, Zebra yoksa printer: "BROWSER" gönderir.

• Zebra yoksa web etiketi istemcide HTML olarak çizip tarayıcıdan yazdırır (label-html); HTML üreten bir API ucu yoktur. Mobilde ZPL kullanamıyorsanız aynı alanlardan (barkod, tür, paket i/n, gönderi no, depo, tarih) yerel bir PDF / görsel üretin.
• B01 "Etiket yazdır" (preparation/print-rows) ZPL döndürmez; gönderi satırı verir, etiket istemcide çizilir (alıcı telefonu bu sorguda da yoktur).

10. Sayım

Tüm işlemler POST branch/counts/{countId} üzerinden, gövdedeki action ile yapılır.

• clientScanId (1–60, [A-Za-z0-9_-]) sayım servisinde ayrı bir tekrar korumasıdır: aynı id adedi ikinci kez eklemez. Web bunu çevrimdışı kuyrukla, Idempotency-Key = clientScanId olacak şekilde gönderir; UUID her iki kurala da uyar.
• data.replayed yalnız Idempotency-Key tekrarını gösterir. clientScanId tekrarında (yeni anahtarla) adet eklenmez ama data.replayed: false döner.
• Yetki kontrolü gövde doğrulandıktan ve sayım bulunduktan sonra yapılır.
• Başlatma (POST branch/counts): warehouseId, countTypeCode (FULL, CYCLE, SPOT; varsayılan FULL), note. Sayım kör değildir (blind: false, detayda expectedHidden: false); audit inventory.count.started.
• Detay (GET branch/counts/{countId}): başlık, özet, satırlar (sistem stoğu / sayılan / fark), koli durumları, seri farkları, son okutmalar, kullanıcı adları. Alt nesneler admin sayım modülüyle aynı çıktıdır (getStockCountDetail).

11. Transfer okutma

Gelen transfer (B02/B17)

• scanType (CARGO_CODE | PARCEL_BARCODE | ITEM_BARCODE) yalnız önceliktir: önce kalemin okutma kodu (ITEM_BARCODE'da seri no da) aranır, sonra gönderi no / takip no / etiket / koli barkodu tüm yollarla çözülür.
• transferId verilirse arama o transferle sınırlanır. clientEventId (1–80) zorunlu alandır ama yalnız audit içindir; deviceId isteğe bağlıdır.
• accept (eventCode: "transfer.accept"): okutulmuş ve bekleyen kalemleri kabul eder; kalem hataları failed[] içinde (200). Yeni anahtarla tekrar çağrı kabul edilmiş kalemleri atlar (accepted: 0).
• confirm (eventCode: "transfer.accepted"): okutulanları içeri alır, kalanları MISSING (NOT_SCANNED_AT_BRANCH) kapatır; transfer ACCEPTED / PARTIALLY_ACCEPTED olur. İsteğe bağlı note (500).

Merkeze transfer (B03)

• resolve: gönderiye bağlı olmayan, şube deposundaki koli / paket etiketi → kind: PACKAGE (transferin ambalaj barkodu, gövdede packageBarcodes). Aksi halde gönderi çözümlenir → kind: SHIPMENT (bu birimin zimmetinde, terminal değil, açık devirde değil).
• scanType=CARGO_CODE kargo koduyla, diğerleri AUTO çözümleyiciyle aranır.
• Gönderim: transferType (RETURN, EQUIPMENT, PHYSICAL_DOCUMENT, CARD_RETURN, BRANCH_TRANSFER, OTHER), destinationWarehouseId (centers[].id), lines (1–500; her satır shipmentId + en fazla 200 barcodes), packageBarcodes (en fazla 200), note (300).
• Taslak + satırlar + sevk tek istekte yapılır; sevk başarısızsa taslak kalır (409 TRANSFER_DISPATCH_FAILED). Başarıda eventCode: "transfer.dispatched".
• Gönderiye bağlı olmayan ekipman / evrak satırı eklenemez (her satır bir shipmentId ister).

12. Dosya, konum ve harita

Dosya

Şube uçlarında multipart yükleme ve dosya indirme ucu yoktur. Kart QR'ı yanıtta satır içi SVG (card.qrSvg), etiketler ZPL metni olarak gelir.

Konum ve harita

• Şube uygulaması konum göndermez. Kurye konumu kurye uygulamasının görev konum ucundan gelir.
• courier-map / dashboard son 24 saatteki son konumu döner. Canlı durum son konum yaşından türetilir: ACTIVE ≤10 dk, BREAK 10–60 dk, OFFLINE >60 dk ya da konum yok (eşikler thresholds).
• Harita çizimi, kümeleme ve mesafe gösterimi istemcide yapılır.
• Kurye önerilerindeki etaMinutes sunucuda kuş uçuşu mesafe / 20 km/sa + 5 dk ile hesaplanır; konum 180 dakikadan eskiyse null.

13. Boş dönen modüller

Bu modüllerin şeması henüz yok. Uçlar schemaReady: false döner ve sahte veri üretmez; uygulamada boş durum ekranı gösterin.

Olmayan işlemler

• SMS: kanal yalnız SMS (PUSH, BOTH → 422 CHANNEL_NOT_AVAILABLE); hedef CUSTOMER_GROUP → 422 TARGET_TYPE_NOT_SUPPORTED. Ağ geçidi yoksa kayıtlar SKIPPED (SMS_GATEWAY_NOT_CONFIGURED).
• Fatura onayı (approve) yok.
• Şube kartı iptal / yenileme kaydı yok (kart imzalı belirteçtir, 365 gün geçerli).
• Merkeze transferde gönderiye bağlı olmayan ekipman / evrak satırı eklenemez.
• Duyuru okundu / onay ve eğitim ilerleme uçları yok.
• Şifre değiştirme ve token yenileme uçları yok.