Santral API Rehberi

1. Genel bakış

Santral, JetLogi sistemine yalnız bu API üzerinden erişir; veritabanı veya başka bir iç sisteme bağlantı yoktur. API, sesli asistanın ihtiyaç duyduğu alanları döner. Alıcının adı, açık adresi, teslim kanıtı ve kuryenin telefon numarası dönmez.

Açılan kayıtlar JetLogi destek ekranına düşer ve gönderiye bağlanır. Operasyon ekibi kaydı oradan takip eder.

2. Hızlı başlangıç

Örnekler test (preprod) ortamını kullanır. TOKEN yerine size iletilen token'ı yazın.

1. Değişkenleri tanımlayın.

   KopyalaBASE=https://api-ivr.preprod.jetdiji.com/api/ivr/v1
   TOKEN=<size iletilen token>

2. Arayan numarayla gönderileri sorgulayın.

   Kopyalacurl -s "$BASE/shipments?phone=905321110026" \
     -H "Authorization: Bearer $TOKEN"

3. Tek gönderiyi sorgulayın. Yanıttaki reference değerini kullanın.

   Kopyalacurl -s "$BASE/shipments/JL100245871" \
     -H "Authorization: Bearer $TOKEN"

4. Hızlandırma talebi açın.

   Kopyalacurl -s -X POST "$BASE/shipments/JL100245871/tickets" \
     -H "Authorization: Bearer $TOKEN" \
     -H "Content-Type: application/json" \
     -d '{"kind":"expedite","note":"Müşteri teslimatın hızlandırılmasını istedi.","callerPhone":"905321110026","callId":"111-55849811574444.1"}'

Test ortamında açılan kayıtlar gerçek destek ekranına düşer. Test kayıtlarının note alanına "TEST" yazın.

3. Ortamlar ve erişim

Canlı ortam, testler tamamlandıktan sonra ayrı bir token ile açılır.

Kimlik doğrulama

• Her istekte Authorization: Bearer <token> başlığı gönderilir. Token yoksa veya yanlışsa 401 UNAUTHORIZED döner.
• Token süresizdir. Test ve canlı ortamın token'ları farklıdır.
• Token JetLogi tarafından birebir ve güvenli bir kanaldan iletilir. Token'ı e-posta, grup yazışması, kod deposu veya log gibi yerlere yazmayın.
• Token'ın sızdığından şüphelenirseniz JetLogi'ye bildirin. Yeni token üretilir, eskisi hemen geçersiz olur.

Bağlantı kuralları

• Yalnız HTTPS kabul edilir. Bu host'ta bu rehberde anlatılan uçlar dışında bir yol açık değildir (404).
• Hız sınırı: IP başına dakikada 60 istek. Aşılırsa 429 RATE_LIMITED döner.
• IP izin listesi: Canlı ortamda yalnız santralin bildireceği çıkış IP'lerinden gelen istekler kabul edilecek. Ayrıntı için Netleştirilecek konular'a bakın.
• Zaman aşımı: Yanıtlar genelde 1 saniyenin altındadır. İstemci tarafında 5 saniyelik bir zaman aşımı öneririz. Süre dolarsa arayan canlı temsilciye aktarılmalıdır.
• Biçimler: Gövde JSON ve UTF-8'dir. Tarihler ISO 8601 biçimindedir ve Türkiye saatiyle (+03:00) döner, örneğin 2026-09-14T08:12:00+03:00.

4. Telefonla sorgulama

GET /shipments?phone={numara}

Numaraya alıcı olarak kayıtlı gönderileri döner. Sesli asistanın ilk sorgusu bu olmalıdır: çoğu arayanın gönderi numarasını sormaya gerek kalmaz.

Davranış

• Açık gönderiler önce gelir. Teslim, iade veya iptal ile kapanmamış gönderiler listenin başındadır; ardından son harekete göre yeniden eskiye sıralanır.
• En fazla 10 gönderi döner.
• Kayıt yoksa 200 ve boş liste döner. Bu bir hata değildir; asistan gönderi numarası veya barkod istemelidir.
• Numara geçersizse 422 PHONE_INVALID döner (sabit hat, yabancı numara, eksik hane gibi).

Örnek yanıt

Kopyala{
  "shipments": [
    {
      "reference": "JL100245871",
      "shipmentNumber": "SHP-260914-000123",
      "trackingNumber": "JL100245871",
      "company": "AlbarakaTürk",
      "product": "Kart Teslimatı",
      "status": "OUT_FOR_DELIVERY",
      "statusCode": "4020",
      "statusName": "Dağıtıma Çıktı",
      "isOpen": true,
      "custodyAt": "2026-09-14T08:12:00+03:00",
      "slotEndAt": "2026-09-14T18:00:00+03:00",
      "plannedDeliveryAt": "2026-09-14T00:00:00+03:00",
      "deliveredAt": null,
      "lastEventAt": "2026-09-14T08:12:00+03:00",
      "courierName": "Ruken T.",
      "agencyName": "Güney / Denizli"
    },
    {
      "reference": "JL100198342",
      "shipmentNumber": "SHP-260902-000088",
      "trackingNumber": "JL100198342",
      "company": "Vakıf Katılım",
      "product": "Kart Teslimatı",
      "status": "DELIVERED",
      "statusCode": "5010",
      "statusName": "Teslim Edildi",
      "isOpen": false,
      "custodyAt": null,
      "slotEndAt": "2026-09-05T18:00:00+03:00",
      "plannedDeliveryAt": null,
      "deliveredAt": "2026-09-04T14:37:00+03:00",
      "lastEventAt": "2026-09-04T14:37:00+03:00",
      "courierName": null,
      "agencyName": null
    }
  ]
}

Birden fazla açık gönderi varsa asistan firmayı ve ürünü söyleyerek hangisini sorduğunu teyit etmelidir, örneğin "AlbarakaTürk kartınız için mi arıyorsunuz?". Numara okunacaksa reference kullanılmalıdır.

5. Gönderi no / barkod ile sorgulama

GET /shipments/{reference}

reference aşağıdakilerden biri olabilir; hangisi olduğunu belirtmeniz gerekmez:

• Gönderi numarası veya takip numarası (menü 1)
• Etiketteki barkod (menü 2)
• Gönderiyi veren firmanın (bankanın) referans numarası (menü 2)

Büyük/küçük harf fark etmez. Tuşlamayla girilen değerlerin başındaki ve sonundaki boşluklar yok sayılır.

Örnek yanıt

Telefonla sorgudaki alanlara ek olarak customerPhone döner.

Kopyala{
  "reference": "JL100245871",
  "shipmentNumber": "SHP-260914-000123",
  "trackingNumber": "JL100245871",
  "company": "AlbarakaTürk",
  "product": "Kart Teslimatı",
  "status": "OUT_FOR_DELIVERY",
  "statusCode": "4020",
  "statusName": "Dağıtıma Çıktı",
  "isOpen": true,
  "custodyAt": "2026-09-14T08:12:00+03:00",
  "slotEndAt": "2026-09-14T18:00:00+03:00",
  "plannedDeliveryAt": "2026-09-14T00:00:00+03:00",
  "deliveredAt": null,
  "lastEventAt": "2026-09-14T08:12:00+03:00",
  "courierName": "Ruken T.",
  "agencyName": "Güney / Denizli",
  "customerPhone": "905321110026"
}

Olası sonuçlar

customerPhone yalnız arayan numarayla karşılaştırmak içindir; sesli okunmaz. Bu alanın biçimi henüz kesinleşmedi; bkz. Netleştirilecek konular.

6. Destek kaydı oluşturma

POST /shipments/{reference}/tickets

Arayanın talebini gönderiye bağlı bir destek kaydı olarak açar. reference sorgu uçlarındakiyle aynı değerleri kabul eder.

İstek gövdesi

Yanıtlar

201: yeni kayıt açıldı

Kopyala{ "ticketReference": "TKT-261006-3F9A1C2B", "status": "open", "duplicate": false }

200: aynı konuda açık kayıt zaten var

Kopyala{ "ticketReference": "TKT-261006-3F9A1C2B", "status": "open", "duplicate": true }

• Aynı gönderi ve aynı kind için son 24 saatte açık bir kayıt varsa yeni kayıt açılmaz, mevcut kayıt döner. Asistan "talebiniz zaten kayıtlı, ekibimiz ilgileniyor" diyebilir.
• status değeri open, ya da kayıt ilerlediyse güncel durumudur (assigned, in_progress gibi).
• ticketReference arayana okunabilir. Asistan dönüş süresi taahhüt etmemelidir.

7. Alan sözlüğü

Değeri null olan bir alan "bilgi yok" demektir. Asistan bu bilgiyi tahmin etmez ve söylemez.

8. Durum grupları

JetLogi'de onlarca iç statü kodu var. Sesli asistanın bunları bilmesi gerekmez: status alanı, kodları aşağıdaki gruplardan birine indirger. Önerilen ifadeler örnektir; anlamı değiştirmeden uyarlanabilir.

9. Sesli asistan kuralları

Bu kurallar JetLogi'nin santral iş gereksinimleri dosyasındaki kesin kuralların API alanlarına karşılığıdır.

10. Önerilen çağrı akışları

Sesli asistan (serbest konuşma)

1. Arayan numarayla GET /shipments?phone= çağrılır.
2. Tek açık gönderi varsa doğrudan onun için konuşulur. Birden fazla varsa firma ve ürün söylenerek teyit edilir. Hiç yoksa gönderi numarası veya barkod istenir ve GET /shipments/{reference} çağrılır.
3. Durum, durum grubuna ve kurallara göre söylenir.
4. Arayan hızlandırma veya destek isterse POST /tickets ile kayıt açılır ve ticketReference okunur.
5. Canlı temsilciye aktarılırken reference ve verilen bilgi aktarım özetine eklenir; arayan baştan anlatmak zorunda kalmaz.

Tuşlamalı IVR

11. Hatalar ve yedek davranış

Tüm hatalar aynı biçimde döner. Karar verirken yalnız error.code alanına bakın; message metni değişebilir.

Kopyala{ "error": { "code": "SHIPMENT_NOT_FOUND", "message": "Shipment was not found." } }

Sorgu uçları (GET) güvenle tekrar denenebilir. Kayıt ucu (POST /tickets) da 24 saatlik tekrar korumasıyla güvenlidir: aynı istek ikinci kez gönderilirse yeni kayıt açılmaz.

12. Netleştirilecek konular

Aşağıdaki iki konuda santral tarafının görüşünü bekliyoruz. Yanıtlara göre bu rehber ve API güncellenecek.

12.1 customerPhone alanı ne için kullanılacak?

Gönderi numarasıyla yapılan sorguda "müşteri iletişim numarası" istendi ve şu an alıcının cep telefonu açık olarak dönüyor.

Neden soruyoruz?

• Toplu veri riski: Gönderi numaraları büyük ölçüde sıralıdır. Token bir şekilde ele geçirilirse numaralar sırayla denenerek alıcıların telefon numaraları toplanabilir.
• KVKK veri minimizasyonu: Kişisel veri yalnız amacın gerektirdiği kadar paylaşılmalıdır. Amaç arayanın gönderi sahibi olup olmadığını anlamaksa, numaranın kendisini paylaşmak gerekmez.

Önerimiz: Amaç karşılaştırmaysa, arayan numarayı sorguyla birlikte gönderin; biz numarayı paylaşmadan eşleşip eşleşmediğini dönelim.

KopyalaGET /shipments/JL100245871?callerPhone=905321110026

{ "reference": "JL100245871", ..., "callerMatches": true }

Numaraya başka bir amaçla ihtiyaç varsa (temsilci ekranında göstermek, geri arama yapmak gibi) amacı paylaşın. Buna göre numarayı maskeli (90532***0026) dönmek gibi bir çözümü birlikte değerlendirelim.

12.2 API'ye hangi çıkış IP'lerinden erişeceksiniz?

Santral sunucularının bu API'yi çağıracağı sabit çıkış IP adreslerinin listesini rica ediyoruz. Yedek ve felaket kurtarma sunucuları da listeye dahil olmalıdır.

Neden soruyoruz?

• İkinci koruma katmanı: Şu an tek koruma token'dır. IP izin listesiyle token sızsa bile istek yalnız sizin sunucularınızdan kabul edilir.
• Canlıya geçiş koşulu: Canlı ortam yalnız izin listesindeki IP'lere açılacak. Test ortamında bu kısıt şimdilik uygulanmıyor, testleri hemen başlatabilirsiniz.
• Değişiklik bildirimi: IP adresleriniz değişecekse önceden haber vermenizi rica ederiz; aksi halde istekler 403 IP_NOT_ALLOWED alır.

13. Sürüm geçmişi