ALO 153 Web API

Bu doküman, Tatvan Belediyesi kurumsal web sitesinin ALO 153 Destek Merkezi ile entegrasyonu için hazırlanmıştır. Vatandaş; yeni talep oluşturur, kendi talebini sorgular, aşamasını görür, iletişim bilgilerini düzeltir, yanıt yazar, çözüldü olarak işaretler veya kaydını kapatır.

Bu dokümanın her zaman güncel hâli yukarıdaki adreste yayımlanır; giriş gerektirmez. Elinizdeki kopya eskimiş olabilir, kuşkuya düştüğünüzde çevrimiçi sürümü esas alın.

1. Kimlik Doğrulama

Her istek (yalnızca /health hariç) geçerli bir API anahtarı gerektirir. Anahtar, yönetim panelinden Yönetim → API Anahtarları ekranından üretilir.

X-API-Key: tvb_xxxxxxxxxxxx.yyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyy

Kritik güvenlik kuralları

• Anahtar yalnızca sunucu tarafında saklanmalıdır. Tarayıcıya inen JavaScript'e, mobil pakete veya herkese açık depoya konulmamalıdır. Web sitesi, tarayıcıdan gelen isteği kendi sunucusunda karşılayıp API'ye sunucu-sunucu (server-to-server) iletmelidir.
• Anahtar yalnızca üretildiği anda bir kez gösterilir; sistemde geri çevrilemez biçimde (özet olarak) saklanır. Kaybedilirse yenisi üretilir.
• Anahtar sızarsa panelden anında devre dışı bırakılabilir.
• Anahtar URL'de (query string) gönderilmemelidir; yalnızca başlıkta.

Hata yanıtları (kimlik doğrulama)

2. Hız Sınırları (Rate Limit)

Sınır aşıldığında 429 Too Many Requests döner. Web sitesi bu durumu kullanıcıya "Çok fazla deneme yaptınız, lütfen biraz sonra tekrar deneyin" şeklinde göstermelidir.

2.1 X-Client-IP — ziyaretçiyi bildirin (önemli)

İstekler web sitesinin sunucusundan geldiği için, API tüm ziyaretçileri varsayılan olarak tek bir IP gibi görür. Bu durumda bir kişinin denemeleri sitenin tüm ziyaretçilerini kilitler.

Bunu önlemek için her istekte son kullanıcının IP adresini iletin:

X-Client-IP: 88.240.15.72

Sınırlar o ziyaretçiye özel uygulanır; bir ziyaretçinin kilitlenmesi diğerlerini etkilemez. Başlık gönderilmezse tüm trafik ortak kotayı paylaşır.

Bu başlık yalnızca anahtar sahibi güvenilen istemciden kabul edilir. Değeri son kullanıcının gerçek IP'si olmalıdır ($_SERVER['REMOTE_ADDR'] veya proxy arkasındaysanız doğruladığınız X-Forwarded-For değeri).

3. Sahiplik Doğrulaması

Vatandaşın yalnızca kendi talebine erişebilmesi için her istek sahiplik kanıtı taşır. İki yöntemden biri kullanılır:

1. Takip token'ı — track_token: talep oluşturulurken üretilen, tahmin edilemez benzersiz değer (vatandaşa SMS/e-posta ile giden takip bağlantısında yer alır).
2. Talep numarası + telefon — ticket_number + phone: ikisi birlikte eşleşmelidir.

Kanıt eşleşmezse 404 döner; talebin var olup olmadığı dahi sızdırılmaz.

Not: Telefon numarası içeren tüm sorgular POST ile yapılır. Numara URL'de taşınsaydı sunucu/proxy erişim loglarına düşerdi (KVKK riski).

Yalnızca telefonla sorgulama yoktur. Telefon numarası gizli bir bilgi değildir; tek başına yeterli sayılsaydı numarayı bilen herkes o kişinin tüm taleplerini, adresini ve yazışmalarını görebilirdi. Bu nedenle sorgulama daima talep numarası + telefon ya da takip token'ı ile yapılır.

4. Uçlar (Endpoints)

4.1 Servis Durumu

GET /health

Anahtar gerektirmez. İzleme (uptime) kontrolü için kullanılır.

{
  "status": "ok",
  "service": "tatvan-web-api",
  "time": "2026-07-29T21:21:14+03:00"
}

4.2 Mahalle Listesi (form için)

GET /neighborhoods
X-API-Key: ...

Talep formundaki mahalle açılır listesini doldurmak içindir. Yalnızca aktif ve herkese açık mahalleler döner; çağrı merkezine özel kayıtlar (örn. "Adres Belirtilmedi") dışarı verilmez.

Yanıt: 200 OK

{
  "data": [
    { "id": 1, "name": "Atatürk Mahallesi" },
    { "id": 2, "name": "Sahil Mahallesi" }
  ]
}

Liste nadiren değişir; sitenizde günlük önbelleğe almanız önerilir.

4.3 Yeni Talep Oluşturma

POST /tickets
X-API-Key: ...
X-Client-IP: 88.240.15.72
Content-Type: application/json

{
  "citizen_name": "Ahmet Yılmaz",
  "citizen_phone": "0532 999 88 77",
  "citizen_email": "ahmet@example.com",
  "neighborhood_id": 2,
  "address": "Sahil Mah. 123. Sok. No:4",
  "subject": "Sokak lambası yanmıyor",
  "description": "Sokağımızdaki aydınlatma direği üç gündür yanmıyor.",
  "latitude": 38.5012,
  "longitude": 42.2795,
  "kvkk_consent": true
}

Kategori (konu başlığı) gönderilmez. Talebi hangi kategoriye ve müdürlüğe yönlendireceğine çağrı merkezi temsilcisi karar verir. Vatandaş yalnızca konuyu serbest metin olarak yazar.

Fotoğraf/belge eki ile gönderim

Ek göndereceksiniz multipart/form-data kullanın (JSON yerine). İzin verilen türler: jpg, jpeg, png, webp, heic, pdf, doc, docx.

curl -X POST https://153.vegabyte.com.tr/api/web/v1/tickets \
  -H "X-API-Key: $ALO153_API_KEY" \
  -H "X-Client-IP: 88.240.15.72" \
  -F "citizen_name=Ahmet Yılmaz" \
  -F "citizen_phone=05329998877" \
  -F "subject=Sokak lambası yanmıyor" \
  -F "description=Aydınlatma direği üç gündür yanmıyor." \
  -F "kvkk_consent=1" \
  -F "photos[]=@lamba.jpg" \
  -F "photos[]=@sokak.jpg"

Yanıt: 201 Created — Talep Detay Nesnesi

Yanıttaki ticket_number ve track_token değerlerini kullanıcıya gösterin; track_token takip ekranına yönlendirme için kullanılır. Vatandaşa ayrıca sistem tarafından bilgilendirme SMS'i/e-postası gönderilir.

Hatalar:

4.4 Takip Token'ı ile Talep Detayı

GET /tickets/{track_token}
X-API-Key: ...

Vatandaşa gönderilen takip bağlantısındaki token ile talebin tüm detayını döner.

Yanıt: 200 OK — bkz. Talep Detay Nesnesi

Hatalar: 404 (talep bulunamadı)

4.5 Talep No + Telefon ile Sorgulama

POST /tickets/lookup
X-API-Key: ...
Content-Type: application/json

{
  "ticket_number": "153-2026-000004",
  "phone": "0532 999 88 77"
}

Telefon numarası esnek biçimde kabul edilir: 05329998877, 0532 999 88 77, +90 532 999 88 77, 905329998877 — hepsi aynı numaraya normalize edilir.

Yanıt: 200 OK — Talep Detay Nesnesi

Hatalar:

4.6 Bilgi Düzeltme (Düzenleme)

POST /tickets/update
X-API-Key: ...
Content-Type: application/json

{
  "track_token": "5b7d4c7e-...",
  "citizen_name": "Ahmet Yılmaz",
  "citizen_email": "yeni@example.com",
  "address": "Sahil Mah. 123. Sok. No:6",
  "neighborhood_id": 3
}

Vatandaşın, talebini oluştururken hatalı/eksik girdiği iletişim ve konum bilgilerini düzeltmesi içindir. Sahiplik kanıtı olarak track_token yerine ticket_number + phone de gönderilebilir.

Değiştirilebilen alanlar

Yalnızca gönderdiğiniz alanlar değerlendirilir (kısmi güncelleme); göndermediğiniz alanlar olduğu gibi kalır.

Değiştirilemeyen alanlar

• Telefon numarası — sahiplik kanıtıdır; değiştirilmesi talebin başkasına devredilmesi anlamına gelirdi. İstekte gönderilse bile yok sayılır.
• Konu ve açıklama — personelin üzerinde çalıştığı içeriktir. Ek bilgi için yanıt yazma ucunu kullanın.

Süre kısıtı

Düzeltme yalnızca talep oluşturulduktan sonraki ilk 24 saat içinde ve talep açıkken yapılabilir. Süre dolduktan sonra 409 döner; bu durumda vatandaş yanıt yazarak düzeltmeyi iletebilir.

Yanıt: 200 OK

{
  "message": "Bilgileriniz güncellendi.",
  "updated": [
    "Ad Soyad: \"Ahmet Yilmaz\" → \"Ahmet Yılmaz\"",
    "Adres: \"Sahil Mah. 123. Sok. No:4\" → \"Sahil Mah. 123. Sok. No:6\""
  ],
  "data": { }
}

updated dizisi uygulanan değişikliklerin okunabilir özetidir; kullanıcıya onay mesajı olarak gösterilebilir. Aynı değişiklik panelde personele iç not olarak da işlenir, böylece kayıt geçmişi izlenebilir kalır.

Hatalar:

4.7 Talebe Yanıt Yazma

POST /tickets/reply
X-API-Key: ...
Content-Type: application/json

{
  "track_token": "5b7d4c7e-...",
  "message": "Sorun devam ediyor, tekrar bakılabilir mi?"
}

Sahiplik kanıtı olarak track_token yerine ticket_number + phone de gönderilebilir. message: 2–1000 karakter.

Yanıt: 201 Created

{
  "message": "Yanıtınız talebinize eklendi.",
  "data": {
    "id": 12,
    "body": "Sorun devam ediyor, tekrar bakılabilir mi?",
    "author_type": "citizen",
    "created_at": "2026-07-29T21:22:07+03:00"
  }
}

Hatalar: 409 (talep kapalı), 404, 422

4.8 Çözüldü Olarak İşaretleme

POST /tickets/resolve
X-API-Key: ...
Content-Type: application/json

{
  "track_token": "5b7d4c7e-...",
  "note": "Sorun giderildi, teşekkürler."
}

note isteğe bağlıdır (en fazla 1000 karakter).

Yanıt: 200 OK

{
  "message": "Talebiniz çözüldü olarak işaretlendi.",
  "data": {
    "ticket_number": "153-2026-000004",
    "status": { "value": "resolved", "label": "Çözüldü", "order": 3, "color": "teal" },
    "resolved_at": "2026-07-29T21:23:07+03:00"
  }
}

Hatalar: 409 (zaten çözülmüş), 404

4.9 Kaydı Kapatma

POST /tickets/close
X-API-Key: ...
Content-Type: application/json

{
  "track_token": "5b7d4c7e-...",
  "reason": "Talebimden vazgeçtim."
}

Vatandaşın talebinden vazgeçmesi / kaydı sonlandırması içindir. reason isteğe bağlıdır (en fazla 500 karakter).

Önemli: Kayıt silinmez. Yönetim panelinde ve raporlarda görünmeye devam eder; yalnızca "Çözüldü" durumuna alınır ve geçmişine "Vatandaş kaydı kapattı" notu işlenir. Kurumsal arşiv bütünlüğü korunur.

Yanıt: 200 OK

{
  "message": "Kaydınız kapatıldı. Kurum arşivinde saklanmaya devam eder.",
  "data": {
    "ticket_number": "153-2026-000004",
    "status": { "value": "resolved", "label": "Çözüldü", "order": 3, "color": "teal" },
    "closed_at": "2026-07-29T21:23:07+03:00"
  }
}

Hatalar: 409 (zaten kapalı), 404

5. Talep Detay Nesnesi

{
  "data": {
    "ticket_number": "153-2026-000004",
    "track_token": "5b7d4c7e-...",
    "subject": "API test talebi",
    "status": { "value": "resolved", "label": "Çözüldü", "order": 3, "color": "teal" },
    "is_open": false,
    "category": "Alt Yapı / Yol Şikayeti",
    "neighborhood": "Sahil Mahallesi",
    "department": "Fen İşleri Müdürlüğü",
    "is_emergency": false,
    "created_at": "2026-07-29T21:22:40+03:00",
    "resolved_at": "2026-07-29T21:23:07+03:00",
    "description": "Talep açıklaması...",
    "citizen": {
      "name": "Test Vatandaş",
      "phone": "05329998877",
      "email": null,
      "address": "Test Adres"
    },
    "location": { "latitude": null, "longitude": null },
    "attachments_count": 0,
    "stages": [
      { "key": "received",  "label": "Talep Alındı",   "order": 0, "state": "completed", "completed": true,  "active": false, "reached_at": "2026-07-29T21:22:40+03:00" },
      { "key": "forwarded", "label": "Birime İletildi", "order": 1, "state": "completed", "completed": true,  "active": false, "reached_at": null },
      { "key": "in_review", "label": "İnceleniyor",     "order": 2, "state": "completed", "completed": true,  "active": false, "reached_at": null },
      { "key": "resolved",  "label": "Çözüldü",         "order": 3, "state": "completed", "completed": true,  "active": false, "reached_at": "2026-07-29T21:23:07+03:00" }
    ],
    "replies": [
      {
        "id": 4,
        "body": "Talebiniz ilgili müdürlüğe iletilmiştir.",
        "author_type": "staff",
        "author_name": "Merve K.",
        "created_at": "2026-07-29T21:23:31+03:00"
      }
    ],
    "can": { "reply": false, "resolve": false, "close": false }
  }
}

Alan açıklamaları

Ek dosyalar indirilemez. attachments_count yalnızca kaç dosya eklendiğini bildirir; dosyaların kendisi web API'si üzerinden sunulmaz. Vatandaşın yüklediği belgeler yalnızca yetkili personelin panelinde görüntülenir. Sitenizde "3 dosya eklediniz" biçiminde bilgi gösterebilirsiniz.

Aşama (stage) durumları

reached_at alanı, aşamaya ulaşıldığı an (ISO 8601). null ise o aşama için ayrı bir kayıt tutulmamıştır (örn. doğrudan çözüme geçen talepler).

Gizlilik notları

• Belediye personelinin soyadı maskelenir (Merve K.); tam ad dışarı verilmez.
• Personelin iç notları (dahili yazışmalar) API'de hiçbir koşulda dönmez.
• Vatandaşın kendi ad/telefon/adres bilgisi tam döner (kendi kaydını sorgulamaktadır).

6. Hata Biçimi

Doğrulama hataları Laravel standardındadır:

{
  "message": "Geçerli bir cep telefonu numarası giriniz (örn. 0532 111 22 33).",
  "errors": {
    "phone": ["Geçerli bir cep telefonu numarası giriniz (örn. 0532 111 22 33)."]
  }
}

Diğer hatalarda yalnızca message döner.

7. Örnek Entegrasyon

PHP (sunucu tarafı)

$response = Http::withHeaders([
        'X-API-Key' => env('ALO153_API_KEY'),
        'Accept'    => 'application/json',
    ])
    ->post('https://153.vegabyte.com.tr/api/web/v1/tickets/lookup', [
        'ticket_number' => $request->input('ticket_number'),
        'phone'         => $request->input('phone'),
    ]);

if ($response->status() === 404) {
    return back()->withErrors('Talep numarası ve telefon eşleşmedi.');
}

$ticket = $response->json('data');

Node.js (sunucu tarafı)

const res = await fetch('https://153.vegabyte.com.tr/api/web/v1/tickets/lookup', {
  method: 'POST',
  headers: {
    'X-API-Key': process.env.ALO153_API_KEY,
    'Content-Type': 'application/json',
    Accept: 'application/json',
  },
  body: JSON.stringify({ ticket_number: ticketNumber, phone }),
});

if (res.status === 404) throw new Error('Talep bulunamadı.');
const { data } = await res.json();

cURL

curl -X POST https://153.vegabyte.com.tr/api/web/v1/tickets/lookup \
  -H "X-API-Key: $ALO153_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"ticket_number":"153-2026-000004","phone":"05329998877"}'

8. Web Sitesi İçin Öneriler

1. Anahtarı gizleyin. Tarayıcıdan gelen formu kendi sunucunuzda karşılayın, API'ye oradan gidin. Anahtar hiçbir zaman istemciye inmemelidir.
2. X-Client-IP gönderin. Aksi halde tüm ziyaretçileriniz aynı hız sınırı kotasını paylaşır ve bir kişi hepsini kilitleyebilir (bkz. bölüm 2.1).
3. Formda kendi bot korumanızı kullanın. Yeni talep ucu dakikada 3 istekle sınırlıdır; buna ek olarak sitenizde captcha/honeypot bulundurun.
4. Mahalle listesini önbelleğe alın. GET /neighborhoods günde bir kez çekilmesi yeterlidir.
5. Aşama çubuğunu stages dizisiyle çizin. state alanı doğrudan tamamlandı/aktif/bekliyor gösterimine karşılık gelir.
6. Butonları can nesnesine göre gösterin. Kapalı taleplerde yanıt/çözüldü/kapat butonları gizlenmelidir; aksi halde 409 alırsınız.
7. Düzenleme butonunu süreye göre gösterin. created_at üzerinden 24 saat geçmişse "Bilgilerimi düzelt" seçeneğini gizleyin.
8. KVKK uyarısı gösterin. Hem talep formunda hem sorgulama ekranında kişisel veri işlendiğine dair bilgilendirme ve açık onay kutusu bulunmalıdır.
9. Sorgulama formunda iki alanı da isteyin. Yalnızca telefonla sorgulama bilinçli olarak desteklenmez (bkz. bölüm 3). Formunuzda hem talep numarası hem telefon alanı zorunlu olmalıdır.
10. Takip bağlantısını kullanıcıya hatırlatın. Talep oluşturulduğunda dönen track_token ile hazırlanan bağlantı, kullanıcının talep numarasını hatırlamadan doğrudan takip ekranına girmesini sağlar.

9. Çalışan Örnek Entegrasyon

Bu dokümandaki tüm uçları kullanan, çalışır durumda bir referans uygulama hazırlanmıştır. Kendi entegrasyonunuzu yazmadan önce incelemeniz önerilir.

Örnek uygulama düz PHP ile yazılmıştır ve şunları gösterir:

• Anahtarın sunucu tarafında tutulması ve isteklerin sunucu-sunucu iletilmesi (lib/Alo153Client.php)
• X-Client-IP başlığının doğru gönderimi
• Fotoğraf ekli talep oluşturma (multipart/form-data)
• Talep numarası + telefon ile sorgulama ve takip token'ı ile detay
• Aşama çubuğunun stages dizisiyle çizilmesi
• Yanıt yazma, bilgi düzeltme, çözüldü işaretleme ve kayıt kapatma
• Her ekranda yapılan API çağrısının istek/yanıt/süre dökümü (teknik günlük)

Örnek site canlı API'ye bağlıdır; burada oluşturduğunuz talepler gerçek kayıt olarak sisteme düşer ve vatandaşa SMS gider. Test ederken bunu göz önünde bulundurun.

10. Sürüm ve Destek

• Sürüm: v1 (/api/web/v1)
• Geriye dönük uyumsuz değişiklikler yeni sürüm yolu (/api/web/v2) ile yayınlanır.
• Yeni anahtar talebi, anahtar iptali ve teknik destek: yönetim paneli Yönetim → API Anahtarları ekranı / sistem yöneticisi.

Değişiklik geçmişi