Kurye Mobil API Rehberi

1. Hızlı başlangıç

Beş dakikada ilk isteğinizi atın. Örnekler preprod ortamını kullanır; şifre yerine kendi test şifrenizi yazın.

1. Giriş yapın ve token alın. X-Client-Type: mobile başlığı olmadan token dönmez.

   Kopyalacurl -s -X POST https://api-mobile.preprod.jetdiji.com/api/public/v1/courier-auth/login \
     -H "Content-Type: application/json" \
     -H "X-Client-Type: mobile" \
     -d '{"identifier":"kurye@example.com","password":"***"}'

   Yanıttaki data.accessToken değerini saklayın:

   KopyalaBASE=https://api-mobile.preprod.jetdiji.com
   TOKEN=<data.accessToken>

2. Bir okuma isteği atın. Görev listesi; bir görevin id değerini not edin.

   Kopyalacurl -s "$BASE/api/public/v1/courier-tasks?page=1&pageSize=5" \
     -H "Authorization: Bearer $TOKEN"

3. Bir yazma isteği atın. Göreve not kanıtı ekleyin. Yazma isteklerinde Idempotency-Key gönderin.

   KopyalaSHIPMENT_ID=<tasks[0].id>
   curl -s -X POST "$BASE/api/public/v1/courier-tasks/$SHIPMENT_ID/evidence" \
     -H "Authorization: Bearer $TOKEN" \
     -H "Content-Type: application/json" \
     -H "Idempotency-Key: 7d0f4c4e-1b2a-4f7e-9c3d-5a6b7c8d9e0f" \
     -d '{"evidenceType":"NOTE","textValue":"Paket kapıcıya bırakıldı.","category":"DELIVERY"}'

   İlk çağrı 201 döner. Aynı komutu tekrar çalıştırın: aynı kayıt 200 ile döner, ikinci kayıt açılmaz.

2. Ortamlar ve hesaplar

• Token'ı hangi ortamdan aldıysanız o ortamda kullanın.
• API Referansı'ndaki "Aynı origin" (/) seçeneği, dokümanın sunulduğu sunucuya istek atar. "Try it out" yalnız test ortamlarında açıktır.
• Test hesabı: preprod kurye hesabını JetDiji ekibinden isteyin.

Temel biçimler

• Tüm yollar /api/public/v1/ ile başlar. Bu rehberde kısalık için önek yazılmaz (ör. courier-tasks).
• Tarih/saat alanları ISO 8601, UTC (Z) döner.
• Ondalık koordinat ve ağırlık alanları JSON'da string gelir (ör. "41.012345").
• Başarılı yanıt: { "success": true, "data": {…} }. Bazı uçlarda ek message, başvuru uçlarında ek meta gelir.
• Web karşılığı /kurye-paneli uygulamasıdır; ekran kartlarında web yolu da verilmiştir.

3. Kimlik doğrulama

1. Açılışta saklı token varsa GET courier-auth/session çağırın. 200 → K01; 401 → giriş ekranı.
2. Girişte POST courier-auth/login; gövde { "identifier": "<e-posta veya telefon>", "password": "…" }, başlık X-Client-Type: mobile.
3. Yanıttan data.accessToken, data.tokenType: "Bearer", data.expiresAt alın. Başlık yoksa bu alanlar dönmez, yalnız web çerezi yazılır.
4. Sonraki her istekte Authorization: Bearer <accessToken> gönderin.
5. Çıkışta POST courier-auth/logout çağırın; o token'ın oturumu kapanır. Sonra token'ı cihazdan silin.

4. Hata yönetimi

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

Kopyala{ "success": false,
  "error": { "code": "OTP_INVALID", "message": "…", "remainingAttempts": 3 },
  "code": "OTP_INVALID", "message": "…" }

• Yalnız error.code alanına bakın. Dallanmayı error.code + HTTP durumuyla yapın.
• error.message insan okunur metindir (çoğunlukla Türkçe; bazı uçlarda locale ile İngilizce). Her hatada bulunmaz; kullanıcı metnini error.code'dan kendi çevirinizle üretin.
• Uca özgü ek bilgiler error içindedir: remainingAttempts, lockedUntil, field, fieldErrors, fieldCode, minCount, missing, retryAfterSeconds, details[]. Hangi uçta hangisinin geldiği API Referansı'ndaki yanıt açıklamasında yazar.
• Üst seviyedeki code, message, fieldErrors, field, remainingAttempts, lockedUntil, details, meta alanları eski web ekranları için bırakılmıştır; kullanmayın.
• Bozuk, boş ya da nesne olmayan JSON gövdesi tüm JSON uçlarında 400 INVALID_JSON döner. İstisna: POST courier-tasks/{shipmentId}/otp boş gövdeyi {} sayar.
• geography/* uçları aynı error nesnesini döner ama üst seviyede code yoktur (yalnız meta). error.code kuralı orada da geçerlidir.

İstemci ne yapmalı

5. Yazma istekleri ve çevrimdışı

Idempotency-Key

• UUID önerilir. Başlık yoksa gövdedeki idempotencyKey alanı okunur.
• Aralık dışı anahtar → 400 IDEMPOTENCY_KEY_INVALID. Aynı anahtar başka bir işlem ya da gönderi için kullanılırsa → 409 IDEMPOTENCY_KEY_CONFLICT.
• X-Client-Event-Id: cihazdaki kuyruk kaydının kimliği (UUID, en çok 191). Sunucu bunu korelasyon kimliği olarak saklar; X-Correlation-Id de kabul edilir.

Çevrimdışı kuyruk

1. İşlemi cihazda (ör. SQLite ya da IndexedDB) X-Client-Event-Id + Idempotency-Key ile saklayın.
2. Bağlantı gelince kuyruğu eskiden yeniye sırayla boşaltın; her işlemi aynı anahtarla yeniden gönderin.
3. Sunucudan 2xx gelmeden işlemi kullanıcıya "tamamlandı" göstermeyin.
4. 4xx (408 ve 429 hariç) kalıcı hatadır; tekrar denemek sonucu değiştirmez, kullanıcıya gösterin. 408, 429, 5xx ve ağ hatalarını yeniden deneyin.

• Web istemcisinin kuyruğa aldığı işlem türleri: CUSTODY_ACCEPT, CUSTODY_RETURN, REPORT, FORM, EVIDENCE, DOCUMENT_UPLOAD, DELIVERY_RESULT.
• OTP gönderme/doğrulama ve "Müşteriyi Ara" çevrimdışı yapılamaz; kuyruğa almayın.
• Teslim sonucu kuyrukta aynı gövde + aynı anahtarla gönderilir. Gereksinim eksikliğinden sonra gövde değişirse yeni anahtar kullanın.
• Eski konumları start/location uçlarına göndermeyin (tazelik kuralı, bkz. Konum). Kanıt, tutanak ve finalize konumları geçmiş zamanlı olabilir.

6. Ekran ekran akışlar

Kartlar uygulamadaki kullanım sırasıyla dizilidir. Her kart aynı şablonu izler: amaç → çağrı sırası → iş kuralları → hata durumunda. Web sayfaları src/app/[locale]/kurye-paneli/** altındadır.

Giriş ve hesap

Güne başlarken

Görevler ve teslim

Gün sonu

Hesap

Hesabı olmayanlar için

7. Kavramlar

Gönderi durum kodları

statusCode (Shipment.currentStatusCode) sayısal stringtir.

courier-tasks listesi statusCode değerini filtre olarak birebir kabul eder. 7xxx/8xxx gönderiler kuryede kalmadığı için listede nadiren görünür. Eski metin kodları (OUT_FOR_DELIVERY, DELIVERED) yedek olarak gelebilir.

Neden kodları

• Teslim alan tipi → yakınlık eşlemesi (web): SELF → 9201, RELATIVE → 9202/9203, AUTHORIZED → 9207/9205/9206, SECRETARY → 9204.
• Güncel ve dile göre adlandırılmış liste için her zaman GET courier-tasks/delivery-reasons kullanın; kodları sabit yazmayın.

Zimmet kuralları

1. Zimmet yalnız teslim alan taraf okutarak kabul edince değişir. Kurye depodan, birimden ya da başka kuryeden gelen gönderiyi courier-custody/accept ile okutur; kabul aynı işlemde gönderiyi dağıtıma (4020) çıkarır.
2. Teslim edilemeyen gönderi (6010) kuryede kalabilir; kurye aynı barkodu okutarak tekrar çıkış yapar (mode: REDISPATCH, neden 9116). Manuel karar gerektiren nedenlerde ya da çıkış hakkı dolduysa reddedilir.
3. Teslim edildiğinde zimmet kuryeden alıcıya geçer (finalize içinde otomatik).
4. Gün sonu: kurye courier-custody/return ile birime iade başlatır; zimmet birim okutana kadar kuryede kalır.
5. Kuryede 24 saatten uzun duran gönderi alarmlıdır (overview.onCourier[].overdue, alertHours: 24).

8. Konum gönderimi

9. Teslim gereksinimleri ve anket

Teslim akışının adımları sabit değildir; ürün ya da operasyon kuralından gelir. GET courier-tasks/{shipmentId} (alan deliveryRequirements) ya da GET courier-tasks/{shipmentId}/requirements ile okunur (?locale=tr|en etiket dili).

Gereksinim nereden gelir (source.type)

İlk "teslim gereksinimi tanımlayan" kural kazanır:

1. RULE_INSTANCE: gönderinin iş akışına bağlanmış yayınlanmış operasyon kuralı.
2. RULE_POLICY: canlı operasyon kuralı ataması (müşteri/ürün/hizmet kapsamına göre).
3. DEFAULT: 1 teslim fotoğrafı (DELIVERY) + imza + OTP. Sunucuda zorlanmaz (geriye uyum).

Gereksinim alanları

Fotoğrafları gereksinime bağlama

• Yüklerken requirementCode=<code> gönderin (yalnız evidenceType=PHOTO). Kategori boş bırakılırsa gereksinimin kategorisi atanır; farklı kategori → 422 REQUIREMENT_CATEGORY_MISMATCH; tanımsız kod → 422 REQUIREMENT_CODE_INVALID.
• Anket alanına bağlı fotoğraf: requirementCode=form:<ALAN_KODU> (alanın evidenceRule.evidenceTypeCode değeri PHOTO olmalı).
• Kodsuz fotoğraflar kategori eşleşmesiyle sayılır (aynı kategoride sırayla eksik olana).
• Sayım kapsamı: henüz teslim denemesine bağlanmamış kanıtlar + açık deneme. Teslim edilemeyen denemeye bağlanan kanıtlar sonraki denemeye taşınmaz; yeniden çekilmelidir.

Anket

Kayıt PUT courier-tasks/{shipmentId}/form ile yapılır: DRAFT taslak, SUBMITTED tamamlama. Değerler alan kodu (büyük/küçük harf duyarsız) → değer nesnesidir.

• isMultiValue: true alanlarda değer dizidir (en çok 50, tekrarlar atılır). Boş string, boş dizi ve null "boş" sayılır ve kaydedilmez.
• Web ayrıca pattern dener; sunucu pattern uygulamaz. Bilinmeyen alan kodu → 422 FORM_FIELD_INVALID.

Koşullar (visibilityRule, requiredRule, evidenceRule.requiredWhen) şu biçimdedir: { schemaVersion: "COMPLETION_FORM_CONDITION_V1", fieldCode, operatorCode, value }

• Karşılaştırma katıdır: string'ler trim edilip eşitlenir, diğer tipler === (ör. NUMBER 5 ile kural değeri "5" eşit değildir). Bilinmeyen operatör/şema: görünürlükte "görünür", zorunlulukta "zorunlu değil" sayılır.
• visibilityRule yanlışsa alan gizlidir; gizli alanın değeri sunucuda atılır, zorunluluk ve kanıt kontrolü yapılmaz. Sunucu alanları sortOrder sırasıyla işler; koşul yalnız önceki alanların değerlerine bakar.
• requiredRule doğruysa (ya da isRequired) alan SUBMITTED'da zorunludur → FORM_FIELD_REQUIRED.
• evidenceRule = { schemaVersion: "COMPLETION_FORM_EVIDENCE_RULE_V1", evidenceTypeCode: "PHOTO", minCount, requiredWhen }: requiredWhen boş ya da doğruysa form:<ALAN> fotoğraf sayısı minCount'tan az olamaz → FORM_EVIDENCE_REQUIRED (fieldCode, minCount, actual). Sunucu yalnız PHOTO değerini zorlar. Önce fotoğrafları yükleyin, sonra anketi SUBMITTED gönderin.
• DRAFT'ta yalnız değer tipleri doğrulanır. Aynı teslim bağlamında (atama + açık deneme) tek kayıt güncellenir. Tamamlanmış anket aynı değerlerle tekrar gönderilirse aynı kayıt döner; farklı değerlerle 409 FORM_ALREADY_SUBMITTED.

Örnek gereksinim

Kopyala{
  "source": { "type": "RULE_POLICY", "ruleSetCode": "KART_TESLIM", "ruleVersion": 3 },
  "photos": [
    { "code": "DELIVERY", "categoryCode": "DELIVERY", "minCount": 1, "label": "Teslim fotoğrafı" },
    { "code": "DEVICE_FRONT", "categoryCode": "DEVICE", "minCount": 2, "label": "Cihaz ön yüz" }
  ],
  "signatureRequired": true,
  "otpRequired": true,
  "appliesTo": "DELIVERED",
  "form": { "formCode": "KART_TESLIM_ANKETI", "required": true, "fields": [ "…" ] },
  "progress": { "photos": { "DELIVERY": 1, "DEVICE_FRONT": 0, "form:HASAR_FOTO": 0 },
                "signature": false, "otpVerified": false, "formSubmitted": false }
}

Finalize öncesi sunucu kontrolü

POST …/finalize işlem içinde gereksinimleri yeniden hesaplar (kaynak DEFAULT değilse). Kontrol sırası: fotoğraflar (minCount) → (yalnız DELIVERED) imza → OTP → anket (form.required ise SUBMITTED). Eksik varsa hiçbir şey yazılmaz:

Kopyala{ "success": false, "error": { "code": "DELIVERY_REQUIREMENTS_MISSING",
  "missing": [ { "type": "PHOTO", "code": "DEVICE_FRONT", "required": 2, "actual": 1 },
               { "type": "SIGNATURE" }, { "type": "OTP" },
               { "type": "FORM", "code": "KART_TESLIM_ANKETI" } ] } }

Eksik giderildikten sonra gövde değişeceği için yeni Idempotency-Key ile tekrar gönderin (web davranışı). Başarılı finalize'da sayılan kanıtlar ve anket kaydı teslim denemesine bağlanır.

Finalize: eski alanlar

Eski mobil sürümlerle uyumluluk için kabul edilir; yeni istemcide kullanmayın.

10. Dosya yükleme ve indirme

• Kanıt ek alanları: category (varsayılan OTHER), requirementCode (yalnız PHOTO, en çok 80), note (en çok 2000), pageCount (1–500), konum alanları, capturedAt.
• Web istemcisi fotoğrafı yüklemeden önce en uzun kenarı 1600 px, JPEG kalite 0.82'ye küçültür (önerilir).

İndirme

• GET courier-tasks/{shipmentId}/evidence/{evidenceId}/file — Bearer zorunlu. EvidenceDto.fileUrl bu yolu origin'siz verir.
• Görseli Authorization başlıklı istekle indirin; düz <img src> ya da URL ile çalışan görüntüleyici token taşımaz.
• ?download=1 → Content-Disposition: attachment (varsayılan inline). Yanıt Cache-Control: private, no-store. Hata durumunda JSON (ApiError) döner.