# Tatilox Voyce API — Yapay Zeka Bağlantı Rehberi

> Sürüm 1.0.0. Bu belge SANA, bir yapay zekaya yazıldı. Okuyunca şunları bileceksin: bu sistem ne, verilere nasıl ulaşılır, hangi veri neyi anlatır, hangisi neyi anlatmaz. Belgede KİŞİSEL VERİ ve ANAHTAR yoktur; anahtarı kullanıcı sana ayrıca verir.

## 0. Üç cümlede özet

1. Tatilox bir çağrı merkezi (telefon) çalıştırıyor. Çağrılar **Voyce** adlı bulut sistemde oluyor; biz o verinin bir kopyasını (**arşiv**) kendi veritabanımızda tutuyoruz ve **Çağrı Defteri** adlı sitede gösteriyoruz.
2. Bu API, sitede gördüğün HER veriyi sana makine okunur olarak verir (JSON/CSV). Adres: `https://mly555au7hddga4r5n7d39dp.hecateq.cloud/tatiloxvoyceapi/v1`. Her istekte API anahtarı göndereceksin.
3. API **salt-okunurdur**: veriyi okursun, hiçbir şeyi değiştiremezsin.

## 1. Nasıl bağlanırsın

- **Temel adres:** `https://mly555au7hddga4r5n7d39dp.hecateq.cloud/tatiloxvoyceapi/v1`
- **Anahtar:** her istekte başlık olarak: `X-API-Key: tvk_…` (veya `Authorization: Bearer tvk_…`). Anahtarı kullanıcıdan iste; yanıtlarda/loglarda yazma.
- **İlk adım:** `GET https://mly555au7hddga4r5n7d39dp.hecateq.cloud/tatiloxvoyceapi/v1/me` → anahtarın geçerli mi, hangi yetkileri var (read = veri okuma, export = toplu indirme, live = canlı Voyce). Sonra `GET https://mly555au7hddga4r5n7d39dp.hecateq.cloud/tatiloxvoyceapi/v1/tables` ile hangi veri var gör.
- **Yanıt şekli** (hepsinde aynı):

```json
{ "success": true, "data": …, "message": null, "error": null,
  "pagination": { "page": 1, "limit": 50, "total": 4535, "totalPages": 91, "hasMore": true },
  "timestamp": "2026-10-03T09:15:00.000Z" }
```

  Hatada `success:false`, `data:null`, `error:{code,message}`. Liste değilse `pagination:null`.
- **Sayfalama:** `?page=1&limit=50`. `pagination.hasMore` true ise `page+1` iste. Büyük veri için sayfalamak yerine `/export/...` kullan.
- **Tarih:** `from=YYYY-MM-DD&to=YYYY-MM-DD` — **İstanbul günü**, ikisi de dahil. Verilmezse son 7 gün. Ham zaman sütunları (…_time, …_at) **UTC**'dir; İstanbul = UTC+3.
- **Hata kodları:** 400 parametre hatalı · 401 anahtar yok/yanlış · 403 anahtar iptal/süresi dolmuş/yetkisiz · 404 yok · 503 arşiv geçici erişilemiyor.
- **Hazır uçların dışında her şeye ulaşmak:** `GET /tables/{ad}` herhangi bir tabloyu/görünümü süzer. Süzgeç yazımı:
  - eşit: `filter[sütun]=değer` · diğer: `filter[sütun][op]=değer`, op = `eq ne gt gte lt lte like starts in null`
  - `like` = içerir (büyük/küçük harf fark etmez), `starts` = ile başlar, `in` = virgüllü liste (en çok 100), `null` = `true|false`
  - sıralama `sort=-start_time,call_id` (azalan için `-`) · sütun seçimi `fields=a,b` · metin araması `search=ayşe`
  - örnek: `https://mly555au7hddga4r5n7d39dp.hecateq.cloud/tatiloxvoyceapi/v1/tables/calls?filter[queue]=tatilox_queue_otel&filter[start_date_trt][gte]=2026-09-01&sort=-start_time&fields=call_id,start_time,agent&limit=20`
  - toplama (SUM/COUNT/GROUP BY) YOK. Hazır özet için `v_*` görünümlerini veya hazır uçları kullan; gerisini veriyi çekip kendin hesapla (export ile).

## 2. Kavramlar (sade dille)

| Terim | Ne demek |
|---|---|
| **Voyce** | Tatilox'un kullandığı bulut çağrı merkezi (telefon) sistemi. Bütün çağrılar orada olur; bu API onun verisinin kopyasını (arşivini) sunar. |
| **Arşiv** | Voyce'tan düzenli çekilip kendi veritabanımıza yazılan kopya. API'nin okuduğu yer burasıdır. Voyce'a kendisi yazmaz. |
| **Çağrı (satır)** | Konuşması gerçekleşmiş bir telefon görüşmesi. Aktarılırsa birden çok satır olabilir (bacak). |
| **Bacak (leg)** | Bir görüşmenin tek temsilciyle geçen parçası. Görüşme A'dan B'ye aktarılınca iki bacak olur, ikisi aynı interaction_id'yi taşır. |
| **Benzersiz görüşme** | interaction_id sayısı. "Kaç kişi aradı" gibi sorular için bunu say, satır sayısını değil. |
| **Kaçan çağrı** | Müşteri aradı, kuyrukta bekledi, hiç kimse açmadan kapattı. calls tablosunda YOK; ayrı tablolarda. |
| **Geri dönüş** | Kaçan çağrıyı yapan müşteriye sonradan dönülmüş mü (is_called_back). |
| **Kuyruk** | Çağrıların sıraya girdiği grup (Tatilox ana, Otel, Otomatik Arama, Mesai Dışı, Kaçan Çağrı geri arama, Test). |
| **Temsilci (agent)** | Telefonu açan kişi. Kullanıcı adıyla anılır (agent.1…). |
| **Yön** | inbound = müşteri aradı; outbound = temsilci aradı; dialer = otomatik arama kampanyası. |
| **Sonuç kodu (verdict)** | Görüşme bitince temsilcinin seçtiği etiket: Bilgi Aldı, Rezervasyon Oluşturuldu, Randevu Oluştur, No Action… |
| **CRM sonuç kodu** | Müşterinin SON arama sonucu (customers.finish_code). Çağrının sonuç kodundan ayrı bir şeydir. |
| **Test kodu** | Deneme amaçlı sonuç kodları (Testt, WhatsappTest3, Whatsapp Test2, FaultyCall) ve test kuyruğu. Gerçek raporlardan çıkarılır; includeTests=false varsayılandır. |
| **Müşteri (CRM)** | CRM listesindeki kayıtlı kişi. Arayanların çoğu CRM'de kayıtlı DEĞİLDİR. |
| **ContactID** | Çağrıdaki müşteri kimliği (calls.contact_id). Kesin bağdır ama sadece giden/otomatik çağrıların bir kısmında dolu. |
| **Telefon anahtarı (phone_key)** | Telefonun yalnız rakamlı normal hâli: 0532…, +90 532…, 90532… hepsi aynı anahtara iner. Çağrıyı müşteriye bağlamak için kullanılır. |
| **TRT / İstanbul saati** | Türkiye saati (UTC+3). Gün hesaplarında HER ZAMAN İstanbul gününü kullan; API gün parametreleri (from/to) İstanbul günüdür. Ham zaman sütunları UTC'dir. |
| **ACW** | Çağrı bittikten sonra temsilcinin not/işlem yaptığı süre. |
| **IVR** | Arayanı karşılayan sesli menü. |

## 3. Sitede ne görüyorsak, o veri nereden gelir?

Kullanıcı "sitede şu rakama/listeye bakıyorum" derse aşağıdan karşılığını bul. Sol sütun ekranda gördüğü, orta sütun API ucu, sağ sütun altındaki tablo/görünüm.

| Ekranda gördüğü | API ucu | Veri (tablo/görünüm) |
|---|---|---|
| Genel Bakış (sayılar ve grafikler) | GET /overview, /verdicts, /abandons/daily | calls, v_calls_daily, v_abandons_daily |
| Çağrılar sekmesi | GET /calls | calls, v_calls_enriched |
| CRM sekmesi (müşteri listesi ve filtreler) | GET /customers, /customers/facets | customers |
| Kaçan Çağrılar sekmesi | GET /abandons, /abandons/daily, /abandons/hourly | v_abandons, abandon_calls_report, abandon_events |
| Sonuç Kodları sekmesi | GET /verdicts | v_calls_result, v_verdict_matrix, finish_codes |
| Kişi çekmecesi (bir kişiye tıklayınca) | GET /contacts/by-phone, /contacts/by-customer | v_contacts, v_contact_summary, customers |
| Üstteki hızlı arama | GET /search | customers, calls |
| Canlı sekmesi (şu an kim müsait, kuyruklar) | GET /live/agents, /live/queues, /live/queue-statistics | (arşivde değil, Voyce'tan canlı; "live" yetkisi ister) |
| Canlı kaçan çağrı havuzu | GET /live/abandons | abandon_events (arşivdeki kayıt hâli) |
| Kuyruk & Hat sekmesi | GET /tables/queues, /tables/reference_snapshots | queues, reference_snapshots |
| Randevu & Görev sekmesi | GET /tables/appointments, /tables/tasks, /tables/calendar_events | appointments, tasks, calendar_events |
| Voyce paneli → CRM sayfası | GET /customers | customers |
| Voyce paneli → Raporlar → Çağrı Detayı | GET /calls | calls |
| Voyce paneli → Raporlar → Kaçan Çağrı Detayı | GET /abandons | abandon_calls_report |
| Voyce paneli → Raporlar → Sonuç Kodu Detayı | GET /verdicts | v_calls_result |
| Voyce paneli → diğer resmi raporlar (SL, performans, kalite…) | (arşivlenmiyor) | Yok. Çağrı verisinden hesaplanabilir ama resmi değer değildir. |

**Ek bilgi:** Sitedeki "toplam çağrı" kartı konuşulan çağrılardır. "Kaçan" kartı ayrı kaynaktandır (kaçan çağrı tabloları). İkisi toplanırsa gelen çağrı hacmi çıkar.

## 4. Sık sorulan sorular → hangi isteği atmalı

| Soru | İstek | Not |
|---|---|---|
| Dün kaç çağrı geldi, kaç tanesi kaçtı? | `GET /overview?from=YYYY-MM-DD&to=YYYY-MM-DD` | calls.total (konuşulan) + abandons.total (kaçan). Toplam gelen = gelen konuşulan + kaçan. |
| Sonuç kodu dağılımı nedir? | `GET /verdicts?from=…&to=…&groupBy=day\|agent\|queue\|direction\|hour\|week\|month` | categories = genel dağılım, groups = kırılım. |
| Bu telefon numarasıyla ne konuşulmuş? | `GET /contacts/by-phone?number=0532 111 11 11` | Çağrılar, kaçan çağrılar ve (varsa) müşteri tek yanıtta. |
| Şu müşterinin geçmişi? | `GET /contacts/by-customer?id=<customer_id>` | Önce GET /search?q=<ad> ile customer_id bul. |
| Ada/numaraya göre kişi bul | `GET /search?q=Ayşe` | En az 3 karakter. |
| Geri dönülmemiş kaçan çağrılar | `GET /abandons?from=…&to=…&calledBack=false` | Liste; sayfalıdır. |
| Günlük kaçan çağrı oranı / trend | `GET /abandons/daily?from=…&to=…` | Gün gün hazır özet. |
| Saat saat yoğunluk | `GET /abandons/hourly?from=…&to=…  veya  /verdicts?groupBy=hour` | Saat dilimi İstanbul. |
| Bir temsilcinin çağrıları | `GET /calls?agent=agent.1&from=…&to=…` | agent tam kullanıcı adı. |
| Bir kuyruğun çağrıları | `GET /calls?queue=tatilox_queue_otel&from=…&to=…` | queue teknik ad; adları GET /tables/queues. |
| Temsilci/kuyruk bazlı sonuç kodu sayıları | `GET /tables/v_verdict_matrix?filter[day][gte]=…&filter[day][lte]=…` | Hazır toplamlar; sayıları kendin topla. |
| Günlük çağrı hacmi (kuyruk/yön) | `GET /tables/v_calls_daily?filter[day][gte]=…&sort=day` | Hazır özet. |
| Müşteri listesi, filtreli | `GET /customers?finishCode=Bilgi Aldı&queue=…&page=1` | Filtre değerleri için GET /customers/facets. |
| Başka hiçbir uçta olmayan bir şey | `GET /tables sonra GET /tables/<ad>?filter[sütun][op]=değer` | Tüm tablo/görünümler süzülebilir. |
| Her şeyi indir (analiz için) | `GET /export/<tablo>?format=ndjson&filter[…]=…` | Büyük veri için sayfalamadan iyidir; limit ile sınırla. |
| Veri güncel mi? Hemen güncelle | `GET /sync/status → freshness; gerekirse POST /sync/run {"job":"calls_intraday"}` | "sync" yetkisi gerekir. Eksik şüphesi için POST /sync/compare {"hours":24}; ağır işler (customers_sync) yalnız gerçekten gerekirse. |
| Şu an canlı durum | `GET /live/agents, /live/queues` | "live" yetkisi gerekir. Arşiv bugünü geç gösterir; anlık için bunlar. |

## 5. Kurallar ve tuzaklar (mutlaka uy)

1. Sadece OKU. Bu API ile Voyce'ta hiçbir şey değiştirilemez; değiştirmeyi deneme.
2. Bir sayıyı söylemeden önce hangi tablo/uçtan geldiğini ve hangi tarih aralığı (İstanbul günü) olduğunu belirt.
3. Çağrı SATIR sayısı ≠ benzersiz görüşme sayısı. "Kaç kişi/görüşme" için benzersiz say (v_calls_by_interaction veya /overview.calls.uniqueInteractions).
4. "Toplam gelen çağrı" = konuşulan gelen + kaçan. Sadece calls'a bakıp kaçanları unutma.
5. Test sonuç kodlarını/kuyruğunu varsayılan olarak ele (API varsayılanı zaten eler; includeTests=true verme).
6. Müşteri eşleşmesi yoksa "müşteri yok" de, uydurma. Arayanların çoğu CRM'de kayıtlı değildir.
7. Bugünün çağrıları birkaç dakika gecikmeli olabilir (arşiv ~10 dakikada bir yenilenir; kesin sayım ertesi sabah). Anlık için /live/* kullan; tazelik için GET /tables/v_sync_health.
8. Sonuç kodu ile CRM sonuç kodu farklı şeylerdir; karıştırma. Durum harfleri (C/U/M/K/I) anlamı doğrulanmadı; yorumlama.
9. Kişisel veri (ad, telefon, TCKN) açıktır; yalnız kullanıcının işi için kullan, başkasına açma. Kart numarası zaten maskeli (***1234); tamamlamaya çalışma. Parola/token alanları yoktur.
10. Hata gelirse yanıttaki error.code'a göre davran: 400 parametreyi düzelt, 401/403 anahtar sorunu (kullanıcıya söyle), 503 arşiv geçici erişilemez (sonra tekrar dene).
11. Her yanıt { success, data, message, error, pagination, timestamp } zarfındadır; önce success'e bak, pagination.hasMore true ise page+1 iste.

### Veri ne kadar taze?

- Çağrılar Voyce'tan **her 10 dakikada** (dün + bugün) ve her gece (İstanbul 04:00, son 14 gün) yeniden çekilir; yani bugünün çağrıları en fazla birkaç dakika gecikmeli görünür. Kaçan çağrılar canlı havuzdan ~2 dakikada bir yakalanır, gece raporu (03:30) kesin kaydı tamamlar.
- Kaçan çağrılar ayrıca her 2 dakikada canlı havuzdan yakalanır (gün içi tazelik).
- Müşteri listesi her gece baştan yenilenir. Gün içi eklenen müşteri ertesi geceye kadar yoktur.
- Tazeliği doğrula: `GET /tables/v_sync_health` (calls_sync_ok_trt vb. son başarı zamanları) — dünden eskiyse kullanıcıya "veri güncel olmayabilir" de.

## 6. Uç noktalar (kısa liste)

| Metot ve yol | Ne yapar | Yetki |
|---|---|---|
| `GET /` | API özeti — Sürüm, temel adres ve uç nokta listesi. Anahtar gerekmez. | anahtarsız |
| `GET /health` | Sağlık kontrolü — Servis ve arşiv veritabanı durumu (anahtar gerekmez). | anahtarsız |
| `GET /ai-guide` | Yapay zeka rehberi — Başka bir yapay zekaya verilecek tek belge (Markdown): sistem ne, nasıl bağlanılır, kavramlar, sitede ne görünüyorsa hangi veri olduğu, soru→istek tarifleri, kurallar ve tüm tabloların/görünümlerin "ne / ne değil" sözlüğü. Anahtar gerekmez; veri veya anahtar içermez. format=json ile makine okunur sürüm; download=1 ile .md olarak indirilir. | anahtarsız |
| `GET /me` | Anahtar bilgisi — İstekte kullanılan API anahtarının adı ve yetkileri (anahtarın kendisi dönmez). | undefined |
| `GET /overview` | Genel bakış — Aralık için çağrı, kaçan çağrı, müşteri sayıları, eşleşme oranları ve en sık sonuç kodları. | read |
| `GET /calls` | Çağrılar — Çağrı kayıtları (bacak bazlı), kişi eşleşmesi ve sonuç kodu ile. Yeni olandan eskiye sıralı. | read |
| `GET /customers` | CRM müşterileri — Müşteri listesi (arşiv). Ad, telefon, TCKN ham gelir; kart numarası maskelidir. | read |
| `GET /customers/facets` | Müşteri filtre değerleri — Müşteri filtreleri için sonuç kodu / kuyruk / temsilci / durum dağılımları. | read |
| `GET /contacts/by-phone` | Kişi (telefondan) — Bir telefon numarasının tüm çağrı/kaçan çağrı geçmişi ve eşleşen müşteri(ler). key veya number verin. | read |
| `GET /contacts/by-customer` | Kişi (müşteri kimliğinden) — Bir müşterinin tüm çağrı/kaçan çağrı geçmişi. | read |
| `GET /abandons` | Kaçan çağrılar — Kaçan çağrılar (canlı havuz + gece raporu birleşik), geri dönüş bilgisi ile. | read |
| `GET /abandons/daily` | Kaçan çağrılar (günlük) — Gün gün kaçan çağrı ve geri dönüş sayıları. | read |
| `GET /abandons/hourly` | Kaçan çağrılar (saatlik) — Saat dilimine göre (TRT) kaçan çağrı dağılımı. | read |
| `GET /verdicts` | Sonuç kodu dağılımı — Çağrıların sonuç kodu dağılımı; gün/hafta/ay/saat/temsilci/kuyruk/yön kırılımı. | read |
| `GET /search` | Hızlı arama — Ad veya numaradan kişi araması (en az 3 karakter). | read |
| `GET /tables` | Tablo ve görünüm listesi — Arşivdeki tüm tablo/görünümler: sütunlar, tipler, birincil anahtar, tahmini satır sayısı. (Kimlik/anahtar tabloları hariç.) | read |
| `GET /tables/{table}` | Tablo sorgula — Herhangi bir tablo/görünümü süz, sırala, sayfala. Zaman değerleri UTC ISO8601'dir; yalnız tarih verilirse UTC gün başı sayılır. Ham JSON (raw) sütunları dahildir. | read |
| `GET /export/{table}` | Toplu çıktı (export) — Süzgeçle eşleşen satırları akıtarak indirir: CSV (UTF-8 BOM), JSON veya NDJSON. Sayfalama yoktur; limit ile üst sınır (varsayılan 100.000, en çok 2.000.000). | export |
| `GET /live/agents` | Canlı temsilci durumu — Voyce'tan anlık temsilci durumları (arşivden değil, Voyce'a salt-okuma istek; 5 sn önbellek). | live |
| `GET /live/queues` | Canlı kuyruk durumu — Voyce'tan anlık kuyruk durumları. | live |
| `GET /live/queue-statistics` | Canlı kuyruk istatistikleri — Voyce canlı kuyruk istatistikleri. | live |
| `GET /live/abandons` | Canlı kaçan çağrı havuzu — Voyce'un anlık kaçan çağrı havuzu. enrich=1 ile arşivdeki kişi eşleşmesi eklenir. | live |
| `GET /sync/status` | Güncelleme durumu — Voyce verisinin ne kadar taze olduğu: toplayıcı durumu, canlı havuz, gün içi çağrı yenileme ve gece işlerinin son başarı/sonraki koşu zamanları, arşivdeki en yeni çağrı/kaçan çağrı (freshness), süren iş. Ayarlar da görünür ama bu uçtan DEĞİŞTİRİLEMEZ (ayar yönetimi yalnız yönetici belirteciyle). | sync |
| `POST /sync/run` | Verileri şimdi güncelle (Voyce → arşiv) — Bir güncellemeyi hemen başlatır (Voyce'tan yalnız OKUR; Voyce'ta hiçbir şey değişmez). job: poll (tek canlı kaçan çağrı turu, sonucu hemen döner), calls_intraday (dün+bugünün çağrıları, hızlı: birkaç saniye), calls_sync (son 14 gün), abandon_refetch, reconcile, customers_sync (≈10 dk, ağır). Diğerleri arka planda sürer ve 202 döner; ilerleme GET /sync/status ile izlenir. Aynı anda tek iş: sürerken 409 job_running. Toplayıcı kapalı/duraklamışsa 409/503. | sync |
| `POST /sync/compare` | Voyce ile arşivi karşılaştır (tanı) — Son N saatin çağrılarını Voyce'tan (salt-okuma, 1-3 istek) çekip arşivle kimlik bazında karşılaştırır; Voyce'ta olup arşivde olmayan çağrıları listeler. Eksik varsa POST /sync/run {job:"calls_intraday"} ile tamamlanır. | sync |

Tam ayrıntı ve örnekler: `https://mly555au7hddga4r5n7d39dp.hecateq.cloud/tatiloxvoyceapi/docs` · OpenAPI: `https://mly555au7hddga4r5n7d39dp.hecateq.cloud/tatiloxvoyceapi/v1/openapi.json`.

## 7. Veri sözlüğü — hangi tablo ne, ne değil

Her tabloda: **Bu ne** (anlamı), **Bu ne DEĞİL** (yanlış anlaşılmaması gereken), **Sitede nerede**, **Ne zaman kullan**. `…_trt` ile biten veya `date_trt` sütunları İstanbul saatidir; diğer zamanlar UTC.

### A. Çağrılar (konuşulmuş görüşmeler)

#### `call_cdr` — Tam çağrı kaydı (konuşulan + konuşulmayan)  _(tablo · yaklaşık 206.463 satır)_
- **Bu ne:** Voyce CDR kaydının HER satırı: IVR'da kapatan, cevapsız, meşgul, kaçan ve konuşulmuş çağrılar. Sütun adları/birimleri calls ile aynı (süreler saniye, zamanlar UTC).
- **Bu ne DEĞİL / dikkat:** Konuşma metni ve anket serbest metni (survey) dış veri API'sinde YOKTUR. Aynı çağrı calls tablosunda da varsa iki tabloda tekrar eder; tekilleştirilmişi için v_calls_all.
- **Sitede nerede görünür:** Yok (yalnız veri API'si).
- **Ne zaman kullan:** "IVR'da kaç kişi kapattı, kaç çağrı cevapsız kaldı" gibi, konuşulmamış çağrıları da sayan sorular.
- **Birincil anahtar:** `call_id`

| Sütun | Tip | Ne demek |
|---|---|---|
| `call_id` | text | Çağrı kimliği (CdrDetails _id = calls.call_id). |
| `interaction_id` | text | Görüşme kimliği. |
| `voyce_internal_id` | text | Voyce iç kimliği. |
| `interaction_type` | text | Etkileşim türü. |
| `start_time` | timestamp with time zone | Başlangıç (UTC). |
| `end_time` | timestamp with time zone | Bitiş (UTC). |
| `start_date_trt` | date | Gün, İstanbul. |
| `direction` | text | Yön. |
| `remote_number` | text | Karşı numara (gizlilik moduna göre maskeli). |
| `local_number` | text | Bizim numara. |
| `line_name` | text | Aranan hat (CdrDetails LineName; kaynakta yoksa boş). |
| `queue` | text | Kuyruk. |
| `outbound_queue` | text | Giden kuyruk. |
| `agent` | text | Temsilci. |
| `verdict` | text | Sonuç kodu. |
| `disposition` | text | Çağrı sonlanma biçimi. |
| `terminate_side` | text | Kapatan taraf. |
| `talk_event` | boolean | Konuşma oldu mu (true/false). |
| `ivr_event` | boolean | IVR'a girdi mi. |
| `queue_wait_event` | boolean | Kuyrukta bekledi mi. |
| `transfer_event` | boolean | Aktarıldı mı. |
| `connected_seconds` | numeric | Konuşma süresi (saniye). |
| `queue_wait_seconds` | numeric | Kuyruk bekleme (saniye). |
| `ivr_wait_seconds` | numeric | IVR bekleme (saniye). |
| `dialing_seconds` | numeric | Çevirme süresi (saniye). |
| `alert_seconds` | numeric | Çalma süresi (saniye). |
| `hold_seconds` | numeric | Beklemeye alma (saniye; kaynakta zaten saniye, doğrulandı). |
| `acw_seconds` | numeric | Çağrı sonrası iş süresi (saniye). |
| `last_ivr_name` | text | Son IVR adı. |
| `inbound_route` | text | Gelen çağrı rotası. |
| `campaign` | text | Kampanya. |
| `contact_id` | text | Voyce müşteri kimliği. |
| `classification` | text | Sınıflandırma. |
| `is_out_of_work` | boolean | Mesai dışı mı. |
| `recording_file` | text | Ses kaydı dosya adı. |
| `raw` | jsonb | Voyce'un bize verdiği kaydın TAMAMI (ham JSON). Yukarıdaki sütunlarda olmayan her ayrıntı burada. |
| `exported_at` | timestamp with time zone | Teknik: bu satırın en son yazıldığı an. |
| `first_seen_at` | timestamp with time zone | Teknik: satırın arşive ilk girdiği an. |
| `updated_at` | timestamp with time zone | Teknik: satırdaki anlamlı bir değerin en son değiştiği an. |

#### `calls` — Çağrılar (ham kayıt)  _(tablo · yaklaşık 187.620 satır)_
- **Bu ne:** Konuşma gerçekleşmiş HER telefon görüşmesinin bir satırı. Bir görüşme başka temsilciye aktarılırsa her parçası (bacak) ayrı satırdır.
- **Bu ne DEĞİL / dikkat:** Kaçan çağrıları İÇERMEZ (onlar B grubunda). Bu yüzden "toplam gelen çağrı" = konuşulan (burası) + kaçan. Benzersiz görüşme sayısı satır sayısı DEĞİLDİR (aktarma bacakları aynı interaction_id'yi paylaşır).
- **Sitede nerede görünür:** Çağrı Defteri → Çağrılar sekmesi ve Genel Bakış sayıları. Voyce paneli → Raporlar → Çağrı Detayı.
- **Ne zaman kullan:** Tek tek çağrıyı, süresini, temsilcisini, kuyruğunu, sonuç kodunu ve ses kaydı dosya adını görmek için en ayrıntılı kaynak.
- **Birincil anahtar:** `call_id`

| Sütun | Tip | Ne demek |
|---|---|---|
| `call_id` | text | Satırın benzersiz kimliği (Voyce `_id`). Her bacağın kendi call_id'si vardır. |
| `interaction_id` | text | Görüşme kimliği. AYNI görüşmenin aktarma bacakları aynı interaction_id'yi taşır; benzersiz görüşme saymak için bunu say. |
| `start_time` | timestamp with time zone | Çağrı başlangıcı, UTC. (İstanbul saati için start_date_trt veya v_calls.start_trt.) |
| `end_time` | timestamp with time zone | Çağrı bitişi, UTC. |
| `start_date_trt` | date | Başlangıç GÜNÜ, İstanbul takvimine göre (YYYY-MM-DD). Günlük sayım için bunu kullan. |
| `direction` | text | Yön: inbound = müşteri bizi aradı, outbound = temsilci müşteriyi aradı, dialer = otomatik arama kampanyası. |
| `remote_number` | text | Karşı tarafın telefonu (müşteri numarası). Ham yazılır, farklı biçimlerde olabilir (0532…, +90…). |
| `local_number` | text | Bizim hat/dahili numara. |
| `line_name` | text | Gelen aramada aranan hat numarası. |
| `queue` | text | Kuyruk teknik adı (queues tablosundaki queue_name). Örn. tatilox_queue_otel. |
| `agent` | text | Temsilci kullanıcı adı (users.username). Boş olabilir (IVR'de kalan / otomatik çağrı). |
| `verdict` | text | Çağrı sonuç kodu (temsilcinin seçtiği). Yazım farkı olabilir ("Bilgi Aldı" / "Bilgi aldı"); düzeltilmişi için /verdicts veya v_calls_result. |
| `disposition` | text | Santral sonucu. Güvenme: gelen konuşulan çağrıda ANSWERED, giden/otomatikte boş. "Cevaplandı mı" için connected_seconds > 0 kullan. |
| `terminate_side` | text | Hattı kim kapattı: local (biz) / remote (karşı taraf). |
| `last_ivr_name` | text | Çağrının son geçtiği sesli menü (IVR). |
| `connected_seconds` | numeric | Konuşma süresi (saniye). |
| `queue_wait_seconds` | numeric | Kuyrukta beklenen süre (saniye). |
| `ivr_wait_seconds` | numeric | Sesli menüde geçen süre (saniye). |
| `acw_seconds` | numeric | Çağrı sonrası temsilcinin yaptığı iş süresi (saniye, ACW). |
| `recording_file` | text | Ses kaydı dosya adı. Dosyanın kendisi bu API'den indirilmez; ad içinde müşteri numarası geçer. |
| `campaign` | text | Kampanya adı (otomatik aramalarda). |
| `contact_id` | text | Voyce müşteri kimliği = customers.customer_id. Yalnız giden/otomatik çağrıların bir kısmında dolu; GELEN çağrıda genelde boş (müşteriyi telefondan eşleştir). |
| `raw` | jsonb | Voyce'un bize verdiği kaydın TAMAMI (ham JSON). Yukarıdaki sütunlarda olmayan her ayrıntı burada. |
| `exported_at` | timestamp with time zone | Teknik: bu satırın en son yazıldığı an. |
| `first_seen_at` | timestamp with time zone | Teknik: satırın arşive ilk girdiği an. |
| `updated_at` | timestamp with time zone | Teknik: satırdaki anlamlı bir değerin en son değiştiği an. |

#### `verdict_map` — Sonuç kodu düzeltme listesi  _(tablo)_
- **Bu ne:** Yazım farklarını birleştiren ve test kodlarını işaretleyen küçük liste.
- **Bu ne DEĞİL / dikkat:** Çağrı verisi değildir.
- **Ne zaman kullan:** Hangi kodların test sayıldığını öğrenmek için.
- **Birincil anahtar:** `verdict_key`

| Sütun | Tip | Ne demek |
|---|---|---|
| `verdict_key` | text | Küçük harfli, kırpılmış anahtar. |
| `normalized` | text | Gösterilecek düzgün ad. |
| `category` | text | Kategori. |
| `is_test` | boolean | true = test kodu. |

#### `v_ai_line_transfers` — IVR -> dış yapay zeka hattı aktarmaları  _(görünüm)_
- **Bu ne:** IVR'dan dış yapay zeka hattına yapılan aktarmalar (panelde "YAPAY ZEKA ARAMASI"); aktarma başına TEK satır, her aktarma için arayanın sonradan bir temsilciye ulaşıp ulaşmadığı.
- **Bu ne DEĞİL / dikkat:** Bu çağrılar calls'ta YOKTUR. Sonuçlar ilişkilendirmedir, nedensellik değildir. Veri donmuştur: Voyce 2026-11-08'den beri bu rapor için satır döndürmüyor (data_through son kaydı gösterir). Transkript/kayıt yolu yok.
- **Sitede nerede görünür:** Yok (yalnız veri API'si).
- **Ne zaman kullan:** Yapay zeka hattına aktarılan arayanların ardından temsilciye dönüş oranı.

| Sütun | Tip | Ne demek |
|---|---|---|
| `transfer_key` | text | Aktarma kimliği (rapor satır anahtarı). |
| `interaction_id` | text | Görüşme kimliği. |
| `start_time` | timestamp with time zone | Aktarma zamanı (UTC). |
| `start_date_trt` | date | Gün, İstanbul. |
| `caller_phone10` | text | Arayan telefonu, son 10 hane. |
| `has_recording` | boolean | Kayıt var mı (yol gösterilmez). |
| `transfer_seq` | bigint | Bu arayanın zaman sırasıyla kaçıncı aktarması. |
| `first_agent_contact_at` | timestamp with time zone | Aktarmadan sonra 7 gün içinde aynı telefonla temsilcili ilk çağrı (UTC); boş = yok. |
| `agent_contact_24h` | boolean | 24 saat içinde temsilci teması var mı. |
| `agent_contact_7d` | boolean | 7 gün içinde temsilci teması var mı. |
| `inbound_agent_contact_24h` | boolean | 24 saat içinde yalnız GELEN yönlü temsilci teması var mı. |
| `data_through` | timestamp with time zone | Rapordaki en yeni kayıt zamanı (UTC): verinin tazeliği. |

#### `v_call_handler` — Çağrıyı kim karşıladı  _(görünüm)_
- **Bu ne:** v_calls_all + transkript: her çağrı için karşılayan tür (temsilci, temsilci_konusmadi, ivr, kuyruk, ulasilamadi, belirsiz; kural sürümü handler-1). Memnuniyet anketi anonsu temsilci konuşması sayılmaz.
- **Bu ne DEĞİL / dikkat:** Transkript metni yoktur. Aktarma bacakları ayrı satırdır.
- **Sitede nerede görünür:** Yok (yalnız veri API'si).
- **Ne zaman kullan:** Çağrıların ne kadarını gerçekten temsilci karşıladı.

| Sütun | Tip | Ne demek |
|---|---|---|
| `call_id` | text |  |
| `interaction_id` | text |  |
| `start_time` | timestamp with time zone |  |
| `start_date_trt` | date | Gün, İstanbul. |
| `direction` | text |  |
| `queue` | text |  |
| `agent` | text |  |
| `source` | text | calls veya cdr. |
| `handler_type` | text | Karşılayan tür. |
| `has_transcript` | boolean | Transkript var mı. |
| `agent_segments` | bigint | Sistem dışı temsilci konuşma parçası sayısı (transkript yoksa boş). |
| `system_segments` | bigint | Sistem anonsu sayılan parça sayısı (anket anonsu). |

#### `v_calls` — Çağrılar + İstanbul saati  _(görünüm)_
- **Bu ne:** calls tablosunun aynısı; ek olarak İstanbul saatiyle start_trt, end_trt, date_trt sütunları var.
- **Bu ne DEĞİL / dikkat:** Yeni veri içermez, sadece kolaylık.
- **Sitede nerede görünür:** Çağrılar sekmesi.
- **Ne zaman kullan:** Saati İstanbul olarak okumak istediğinde.

| Sütun | Tip | Ne demek |
|---|---|---|
| `call_id` | text | Satırın benzersiz kimliği (Voyce `_id`). Her bacağın kendi call_id'si vardır. |
| `interaction_id` | text | Görüşme kimliği. AYNI görüşmenin aktarma bacakları aynı interaction_id'yi taşır; benzersiz görüşme saymak için bunu say. |
| `start_time` | timestamp with time zone | Çağrı başlangıcı, UTC. (İstanbul saati için start_date_trt veya v_calls.start_trt.) |
| `end_time` | timestamp with time zone | Çağrı bitişi, UTC. |
| `start_date_trt` | date | Başlangıç GÜNÜ, İstanbul takvimine göre (YYYY-MM-DD). Günlük sayım için bunu kullan. |
| `direction` | text | Yön: inbound = müşteri bizi aradı, outbound = temsilci müşteriyi aradı, dialer = otomatik arama kampanyası. |
| `remote_number` | text | Karşı tarafın telefonu (müşteri numarası). Ham yazılır, farklı biçimlerde olabilir (0532…, +90…). |
| `local_number` | text | Bizim hat/dahili numara. |
| `line_name` | text | Gelen aramada aranan hat numarası. |
| `queue` | text | Kuyruk teknik adı (queues tablosundaki queue_name). Örn. tatilox_queue_otel. |
| `agent` | text | Temsilci kullanıcı adı (users.username). Boş olabilir (IVR'de kalan / otomatik çağrı). |
| `verdict` | text | Çağrı sonuç kodu (temsilcinin seçtiği). Yazım farkı olabilir ("Bilgi Aldı" / "Bilgi aldı"); düzeltilmişi için /verdicts veya v_calls_result. |
| `disposition` | text | Santral sonucu. Güvenme: gelen konuşulan çağrıda ANSWERED, giden/otomatikte boş. "Cevaplandı mı" için connected_seconds > 0 kullan. |
| `terminate_side` | text | Hattı kim kapattı: local (biz) / remote (karşı taraf). |
| `last_ivr_name` | text | Çağrının son geçtiği sesli menü (IVR). |
| `connected_seconds` | numeric | Konuşma süresi (saniye). |
| `queue_wait_seconds` | numeric | Kuyrukta beklenen süre (saniye). |
| `ivr_wait_seconds` | numeric | Sesli menüde geçen süre (saniye). |
| `acw_seconds` | numeric | Çağrı sonrası temsilcinin yaptığı iş süresi (saniye, ACW). |
| `recording_file` | text | Ses kaydı dosya adı. Dosyanın kendisi bu API'den indirilmez; ad içinde müşteri numarası geçer. |
| `campaign` | text | Kampanya adı (otomatik aramalarda). |
| `contact_id` | text | Voyce müşteri kimliği = customers.customer_id. Yalnız giden/otomatik çağrıların bir kısmında dolu; GELEN çağrıda genelde boş (müşteriyi telefondan eşleştir). |
| `raw` | jsonb | Voyce'un bize verdiği kaydın TAMAMI (ham JSON). Yukarıdaki sütunlarda olmayan her ayrıntı burada. |
| `exported_at` | timestamp with time zone | Teknik: bu satırın en son yazıldığı an. |
| `first_seen_at` | timestamp with time zone | Teknik: satırın arşive ilk girdiği an. |
| `updated_at` | timestamp with time zone | Teknik: satırdaki anlamlı bir değerin en son değiştiği an. |
| `start_trt` | timestamp without time zone | Başlangıç, İstanbul saati. |
| `end_trt` | timestamp without time zone | Bitiş, İstanbul saati. |
| `date_trt` | date | Gün, İstanbul. |

#### `v_calls_all` — Tüm çağrılar (calls + yalnız CDR'de olanlar)  _(görünüm)_
- **Bu ne:** calls satırları ile call_cdr'de olup calls'ta bulunmayan (konuşulmamış) satırların birleşimi; çağrı başına TEK satır. Sütunlar v_calls ile aynı (raw yok), sonra source, sonra yalnız CDR'ye özgü sütunlar (calls satırlarında boş).
- **Bu ne DEĞİL / dikkat:** Konuşulmuş-çağrı metrikleri için calls/v_calls kullanılmalı: bu görünüm paydaya IVR/cevapsız/meşgul satırlarını katar. HangupInIVR kaçan çağrı DEĞİLDİR; v_abandons ile örtüşme ölçülmedi.
- **Sitede nerede görünür:** Yok (yalnız veri API'si).
- **Ne zaman kullan:** "Toplam kaç çağrı geldi (konuşulan + konuşulmayan)" sorusu için.

| Sütun | Tip | Ne demek |
|---|---|---|
| `call_id` | text | Satırın benzersiz kimliği (Voyce `_id`). Her bacağın kendi call_id'si vardır. |
| `interaction_id` | text | Görüşme kimliği. AYNI görüşmenin aktarma bacakları aynı interaction_id'yi taşır; benzersiz görüşme saymak için bunu say. |
| `start_time` | timestamp with time zone | Çağrı başlangıcı, UTC. (İstanbul saati için start_date_trt veya v_calls.start_trt.) |
| `end_time` | timestamp with time zone | Çağrı bitişi, UTC. |
| `start_date_trt` | date | Başlangıç GÜNÜ, İstanbul takvimine göre (YYYY-MM-DD). Günlük sayım için bunu kullan. |
| `direction` | text | Yön: inbound = müşteri bizi aradı, outbound = temsilci müşteriyi aradı, dialer = otomatik arama kampanyası. |
| `remote_number` | text | Karşı tarafın telefonu (müşteri numarası). Ham yazılır, farklı biçimlerde olabilir (0532…, +90…). |
| `local_number` | text | Bizim hat/dahili numara. |
| `line_name` | text | Gelen aramada aranan hat numarası. |
| `queue` | text | Kuyruk teknik adı (queues tablosundaki queue_name). Örn. tatilox_queue_otel. |
| `agent` | text | Temsilci kullanıcı adı (users.username). Boş olabilir (IVR'de kalan / otomatik çağrı). |
| `verdict` | text | Çağrı sonuç kodu (temsilcinin seçtiği). Yazım farkı olabilir ("Bilgi Aldı" / "Bilgi aldı"); düzeltilmişi için /verdicts veya v_calls_result. |
| `disposition` | text | Santral sonucu. Güvenme: gelen konuşulan çağrıda ANSWERED, giden/otomatikte boş. "Cevaplandı mı" için connected_seconds > 0 kullan. |
| `terminate_side` | text | Hattı kim kapattı: local (biz) / remote (karşı taraf). |
| `last_ivr_name` | text | Çağrının son geçtiği sesli menü (IVR). |
| `connected_seconds` | numeric | Konuşma süresi (saniye). |
| `queue_wait_seconds` | numeric | Kuyrukta beklenen süre (saniye). |
| `ivr_wait_seconds` | numeric | Sesli menüde geçen süre (saniye). |
| `acw_seconds` | numeric | Çağrı sonrası temsilcinin yaptığı iş süresi (saniye, ACW). |
| `recording_file` | text | Ses kaydı dosya adı. Dosyanın kendisi bu API'den indirilmez; ad içinde müşteri numarası geçer. |
| `campaign` | text | Kampanya adı (otomatik aramalarda). |
| `contact_id` | text | Voyce müşteri kimliği = customers.customer_id. Yalnız giden/otomatik çağrıların bir kısmında dolu; GELEN çağrıda genelde boş (müşteriyi telefondan eşleştir). |
| `exported_at` | timestamp with time zone | Teknik: bu satırın en son yazıldığı an. |
| `first_seen_at` | timestamp with time zone | Teknik: satırın arşive ilk girdiği an. |
| `updated_at` | timestamp with time zone | Teknik: satırdaki anlamlı bir değerin en son değiştiği an. |
| `start_trt` | timestamp without time zone | Başlangıç, İstanbul saati. |
| `end_trt` | timestamp without time zone | Bitiş, İstanbul saati. |
| `date_trt` | date | Gün, İstanbul. |
| `source` | text | calls = konuşulmuş çağrı kaydı; cdr = yalnız CDR'de olan (konuşulmamış) çağrı. |
| `hold_seconds` | numeric | Beklemeye alma (saniye; yalnız cdr satırlarında). |
| `dialing_seconds` | numeric | Çevirme süresi (saniye; yalnız cdr). |
| `alert_seconds` | numeric | Çalma süresi (saniye; yalnız cdr). |
| `outbound_queue` | text | Giden kuyruk (yalnız cdr). |
| `inbound_route` | text | Gelen rota (yalnız cdr). |
| `classification` | text | Sınıflandırma (yalnız cdr). |
| `is_out_of_work` | boolean | Mesai dışı mı (yalnız cdr). |
| `talk_event` | boolean | Konuşma oldu mu (yalnız cdr). |
| `ivr_event` | boolean | IVR'a girdi mi (yalnız cdr). |
| `queue_wait_event` | boolean | Kuyrukta bekledi mi (yalnız cdr). |
| `transfer_event` | boolean | Aktarıldı mı (yalnız cdr). |

#### `v_calls_by_interaction` — Benzersiz görüşme (aktarmalar birleşik)  _(görünüm)_
- **Bu ne:** Görüşme başına TEK satır. Aktarma bacakları tek satırda toplanır.
- **Bu ne DEĞİL / dikkat:** Bacak sayısı değil görüşme sayısıdır; temsilci bazlı ayrıntı yoktur (sadece son temsilci).
- **Sitede nerede görünür:** Genel Bakış'taki "benzersiz çağrı" sayısı.
- **Ne zaman kullan:** "Kaç görüşme oldu" sorusu için.

| Sütun | Tip | Ne demek |
|---|---|---|
| `interaction_id` | text | Görüşme kimliği. |
| `legs` | bigint | Kaç parçadan (bacak) oluştuğu. 1 = aktarma yok. |
| `first_start` | timestamp with time zone | İlk başlangıç (UTC). |
| `last_end` | timestamp with time zone | Son bitiş (UTC). |
| `first_start_trt` | timestamp without time zone | İlk başlangıç İstanbul. |
| `last_end_trt` | timestamp without time zone | Son bitiş İstanbul. |
| `date_trt` | date | Gün İstanbul. |
| `total_connected_seconds` | numeric | Tüm bacakların toplam konuşma süresi. |
| `last_agent` | text | Görüşmeyi son alan temsilci. |
| `verdict_last` | text | Son sonuç kodu. |
| `first_queue` | text | İlk girdiği kuyruk. |
| `direction` | text | Yön. |
| `transferred` | boolean | Aktarıldı mı (legs > 1). |

#### `v_calls_daily` — Günlük çağrı özeti  _(görünüm)_
- **Bu ne:** Gün × yön × kuyruk bazında hazır toplamlar.
- **Bu ne DEĞİL / dikkat:** Temsilci veya sonuç kırılımı yok (onlar için v_verdict_matrix).
- **Sitede nerede görünür:** Genel Bakış grafikleri.
- **Ne zaman kullan:** Günlük/kuyruk bazlı hacim; hazır olduğu için hızlı.

| Sütun | Tip | Ne demek |
|---|---|---|
| `day` | date | Gün (İstanbul). |
| `direction` | text | Yön. |
| `queue` | text | Kuyruk. |
| `unique_calls` | bigint | Benzersiz görüşme sayısı. |
| `answered_calls` | bigint | Konuşulmuş çağrı sayısı. |
| `legs` | bigint | Bacak (satır) sayısı. |
| `talk_seconds` | numeric | Toplam konuşma saniyesi. |

#### `v_calls_enriched` — Çağrı + eşleşen müşteri  _(görünüm)_
- **Bu ne:** v_calls + çağrının hangi müşteriye ait olduğu (önce ContactID, yoksa telefondan).
- **Bu ne DEĞİL / dikkat:** Eşleşme her çağrıda yoktur: arayanların çoğu CRM'de kayıtlı değildir; bu hata değil.
- **Sitede nerede görünür:** Çağrılar sekmesindeki müşteri adı.
- **Ne zaman kullan:** Çağrıya müşteri adı eklemek için.

| Sütun | Tip | Ne demek |
|---|---|---|
| `call_id` | text | Satırın benzersiz kimliği (Voyce `_id`). Her bacağın kendi call_id'si vardır. |
| `interaction_id` | text | Görüşme kimliği. AYNI görüşmenin aktarma bacakları aynı interaction_id'yi taşır; benzersiz görüşme saymak için bunu say. |
| `start_time` | timestamp with time zone | Çağrı başlangıcı, UTC. (İstanbul saati için start_date_trt veya v_calls.start_trt.) |
| `end_time` | timestamp with time zone | Çağrı bitişi, UTC. |
| `start_date_trt` | date | Başlangıç GÜNÜ, İstanbul takvimine göre (YYYY-MM-DD). Günlük sayım için bunu kullan. |
| `direction` | text | Yön: inbound = müşteri bizi aradı, outbound = temsilci müşteriyi aradı, dialer = otomatik arama kampanyası. |
| `remote_number` | text | Karşı tarafın telefonu (müşteri numarası). Ham yazılır, farklı biçimlerde olabilir (0532…, +90…). |
| `local_number` | text | Bizim hat/dahili numara. |
| `line_name` | text | Gelen aramada aranan hat numarası. |
| `queue` | text | Kuyruk teknik adı (queues tablosundaki queue_name). Örn. tatilox_queue_otel. |
| `agent` | text | Temsilci kullanıcı adı (users.username). Boş olabilir (IVR'de kalan / otomatik çağrı). |
| `verdict` | text | Çağrı sonuç kodu (temsilcinin seçtiği). Yazım farkı olabilir ("Bilgi Aldı" / "Bilgi aldı"); düzeltilmişi için /verdicts veya v_calls_result. |
| `disposition` | text | Santral sonucu. Güvenme: gelen konuşulan çağrıda ANSWERED, giden/otomatikte boş. "Cevaplandı mı" için connected_seconds > 0 kullan. |
| `terminate_side` | text | Hattı kim kapattı: local (biz) / remote (karşı taraf). |
| `last_ivr_name` | text | Çağrının son geçtiği sesli menü (IVR). |
| `connected_seconds` | numeric | Konuşma süresi (saniye). |
| `queue_wait_seconds` | numeric | Kuyrukta beklenen süre (saniye). |
| `ivr_wait_seconds` | numeric | Sesli menüde geçen süre (saniye). |
| `acw_seconds` | numeric | Çağrı sonrası temsilcinin yaptığı iş süresi (saniye, ACW). |
| `recording_file` | text | Ses kaydı dosya adı. Dosyanın kendisi bu API'den indirilmez; ad içinde müşteri numarası geçer. |
| `campaign` | text | Kampanya adı (otomatik aramalarda). |
| `contact_id` | text | Voyce müşteri kimliği = customers.customer_id. Yalnız giden/otomatik çağrıların bir kısmında dolu; GELEN çağrıda genelde boş (müşteriyi telefondan eşleştir). |
| `raw` | jsonb | Voyce'un bize verdiği kaydın TAMAMI (ham JSON). Yukarıdaki sütunlarda olmayan her ayrıntı burada. |
| `exported_at` | timestamp with time zone | Teknik: bu satırın en son yazıldığı an. |
| `first_seen_at` | timestamp with time zone | Teknik: satırın arşive ilk girdiği an. |
| `updated_at` | timestamp with time zone | Teknik: satırdaki anlamlı bir değerin en son değiştiği an. |
| `start_trt` | timestamp without time zone | Başlangıç, İstanbul saati. |
| `end_trt` | timestamp without time zone | Bitiş, İstanbul saati. |
| `date_trt` | date | Gün, İstanbul. |
| `contact_key` | text | Normalize telefon anahtarı. |
| `match_customer_id` | text | Eşleşen müşteri kimliği. |
| `match_customer_name` | text | Eşleşen müşteri adı. |
| `match_method` | text | contact_id veya phone; boş = eşleşme yok. |
| `match_count` | bigint | Aynı telefonda kaç müşteri var. |
| `phone_conflict` | boolean | true = ContactID ile telefon farklı müşterileri gösteriyor (ContactID kazanır). |

#### `v_calls_result` — Çağrı + düzeltilmiş sonuç kodu + müşteri  _(görünüm)_
- **Bu ne:** Her çağrıya: yazımı düzeltilmiş sonuç kodu, kategorisi, test kodu mu, notu ve eşleşen müşterinin CRM sonuç kodu eklenmiş hâli.
- **Bu ne DEĞİL / dikkat:** Ham değerleri değiştirmez; çağrı sonuç kodu ile müşterinin CRM sonuç kodu AYRI şeylerdir.
- **Sitede nerede görünür:** Sonuç Kodları sekmesi.
- **Ne zaman kullan:** Sonuç kodu analizi.

| Sütun | Tip | Ne demek |
|---|---|---|
| `call_id` | text | Satırın benzersiz kimliği (Voyce `_id`). Her bacağın kendi call_id'si vardır. |
| `interaction_id` | text | Görüşme kimliği. AYNI görüşmenin aktarma bacakları aynı interaction_id'yi taşır; benzersiz görüşme saymak için bunu say. |
| `start_time` | timestamp with time zone | Çağrı başlangıcı, UTC. (İstanbul saati için start_date_trt veya v_calls.start_trt.) |
| `start_trt` | timestamp without time zone | Başlangıç İstanbul. |
| `end_trt` | timestamp without time zone | Bitiş İstanbul. |
| `date_trt` | date | Gün İstanbul. |
| `direction` | text | Yön: inbound = müşteri bizi aradı, outbound = temsilci müşteriyi aradı, dialer = otomatik arama kampanyası. |
| `queue` | text | Kuyruk teknik adı (queues tablosundaki queue_name). Örn. tatilox_queue_otel. |
| `agent` | text | Temsilci kullanıcı adı (users.username). Boş olabilir (IVR'de kalan / otomatik çağrı). |
| `remote_number` | text | Karşı tarafın telefonu (müşteri numarası). Ham yazılır, farklı biçimlerde olabilir (0532…, +90…). |
| `contact_key` | text | Normalize telefon anahtarı (eşleştirme için). |
| `connected_seconds` | numeric | Konuşma süresi (saniye). |
| `verdict` | text | Çağrı sonuç kodu (temsilcinin seçtiği). Yazım farkı olabilir ("Bilgi Aldı" / "Bilgi aldı"); düzeltilmişi için /verdicts veya v_calls_result. |
| `verdict_normalized` | text | Yazımı birleştirilmiş sonuç kodu (Bilgi Aldı = Bilgi aldı; NoAnswer = Cevapsız; Busy = Meşgul). |
| `verdict_category` | text | Sonuç kodu kategorisi (çoğu boş). |
| `is_test` | boolean | true = test kodu; gerçek raporlardan çıkar. |
| `verdict_note` | text | Temsilcinin sonuç koduna yazdığı not. |
| `verdict_action_date` | text | Sonuç koduna girilen aksiyon (geri arama) tarihi. |
| `detail_finish_code` | text | Ham detaydaki sonuç kodu. |
| `match_customer_id` | text | Eşleşen müşteri kimliği. |
| `match_method` | text | Nasıl eşleşti: contact_id (kesin) veya phone (telefondan). Boş = eşleşen müşteri yok. |
| `match_count` | bigint | Kaç müşteri eşleşti. |
| `crm_finish_code` | text | Eşleşen MÜŞTERİNİN son sonuç kodu (CRM). |
| `crm_finish_code_normalized` | text | Aynısı, yazımı düzeltilmiş. |

#### `v_handler_daily` — Günlük karşılama türü sayıları  _(görünüm)_
- **Bu ne:** Gün × karşılama türü × yön adedi; ayrıca ai_hatti_aktarma satırları.
- **Bu ne DEĞİL / dikkat:** ai_hatti_aktarma, ivr ile toplanmaz (aynı çağrı iki yerde görünebilir).
- **Sitede nerede görünür:** Yok (yalnız veri API'si).
- **Ne zaman kullan:** Günlük temsilci/IVR/yapay zeka hattı dağılımı.

| Sütun | Tip | Ne demek |
|---|---|---|
| `start_date_trt` | date | Gün, İstanbul. |
| `handler_type` | text | Karşılayan tür. |
| `direction` | text | Yön. |
| `n` | bigint | Adet. |

#### `v_verdict_matrix` — Sonuç kodu matrisi  _(görünüm)_
- **Bu ne:** Gün × kuyruk × temsilci × yön × düzeltilmiş sonuç kodu bazında çağrı adedi.
- **Bu ne DEĞİL / dikkat:** Tek tek çağrı yok, sadece sayılar.
- **Sitede nerede görünür:** Sonuç Kodları sekmesi.
- **Ne zaman kullan:** Temsilci/kuyruk bazlı sonuç dağılımı.

| Sütun | Tip | Ne demek |
|---|---|---|
| `day` | date | Gün. |
| `queue` | text | Kuyruk. |
| `agent` | text | Temsilci. |
| `direction` | text | Yön. |
| `normalized` | text | Düzeltilmiş sonuç kodu. |
| `category` | text | Kategori. |
| `is_test` | boolean | Test kodu mu. |
| `calls` | bigint | Çağrı adedi. |

### B. Kaçan çağrılar (müşteri bekledi, kapattı)

#### `abandon_calls_report` — Kaçan çağrılar (resmi rapor)  _(tablo · yaklaşık 63.962 satır)_
- **Bu ne:** Voyce'un "Kaçan Çağrı" raporundaki her satır: müşteri kuyrukta beklerken telefonu kapattı, hiçbir temsilciye bağlanmadı.
- **Bu ne DEĞİL / dikkat:** calls tablosunda YOKTUR. Gün içinde hemen görünmeyebilir (gece raporuyla tamamlanır; canlı kaçanlar abandon_events'te).
- **Sitede nerede görünür:** Çağrı Defteri → Kaçan Çağrılar. Voyce paneli → Raporlar → Kaçan Çağrı Detayı.
- **Ne zaman kullan:** En kesin kaçan çağrı kaynağı (geri dönüş bilgisi dahil). Tekilleştirilmişi için v_abandons.
- **Birincil anahtar:** `report_row_id`

| Sütun | Tip | Ne demek |
|---|---|---|
| `report_row_id` | text | Satır kimliği. |
| `event_time` | timestamp with time zone | Kaçan çağrı zamanı (UTC) = müşterinin kuyruğa girdiği an. |
| `queue` | text | Hangi kuyrukta kaçtı. |
| `caller` | text | Arayan numara. |
| `wait_seconds` | numeric | Kapatmadan önce kuyrukta beklediği saniye. |
| `line` | text | Hat (çoğunlukla boş). |
| `raw` | jsonb | Voyce'un bize verdiği kaydın TAMAMI (ham JSON). Yukarıdaki sütunlarda olmayan her ayrıntı burada. |
| `exported_at` | timestamp with time zone | Teknik: bu satırın en son yazıldığı an. |
| `first_seen_at` | timestamp with time zone | Teknik: satırın arşive ilk girdiği an. |
| `updated_at` | timestamp with time zone | Teknik: satırdaki anlamlı bir değerin en son değiştiği an. |

#### `abandon_events` — Kaçan çağrılar (canlı havuz yakalamaları)  _(tablo · yaklaşık 193 satır)_
- **Bu ne:** Voyce'un canlı kaçan havuzundan 2 dakikada bir alınan kayıtlar. Gün içi tazelik için.
- **Bu ne DEĞİL / dikkat:** Resmi liste değil: havuzdan 2 dakikadan önce düşen çağrıyı kaçırabilir; ayrıca aynı kaçan çağrı raporda da olabilir (çift saymamak için v_abandons kullan).
- **Ne zaman kullan:** Bugünün kaçanlarını anlık görmek.
- **Birincil anahtar:** `queue`, `enter_key`, `caller`, `event_digest`

| Sütun | Tip | Ne demek |
|---|---|---|
| `queue` | text | Kuyruk. |
| `enter_key` | text | Kuyruğa giriş anı anahtarı. |
| `caller` | text | Arayan. |
| `event_digest` | text | Teknik tekilleştirme özeti. |
| `enter_time` | timestamp with time zone | Kuyruğa giriş (UTC). |
| `wait_seconds` | numeric | Beklenen saniye. |
| `first_seen_at` | timestamp with time zone | Teknik: satırın arşive ilk girdiği an. |
| `last_seen_at` | timestamp with time zone | Havuzda son görülme. |
| `source` | text | Kaynak (live_pool). |
| `raw` | jsonb | Voyce'un bize verdiği kaydın TAMAMI (ham JSON). Yukarıdaki sütunlarda olmayan her ayrıntı burada. |

#### `v_abandons` — Kaçan çağrılar (TEKİLLEŞTİRİLMİŞ — bunu kullan)  _(görünüm)_
- **Bu ne:** Rapor + canlı havuz kayıtlarının çift sayım olmadan birleşimi. Çoğu soru için doğru kaynak.
- **Bu ne DEĞİL / dikkat:** Müşteri adı yok (v_abandons_enriched'de).
- **Sitede nerede görünür:** Çağrı Defteri → Kaçan Çağrılar.
- **Ne zaman kullan:** Kaçan çağrı listesi/sayısı.

| Sütun | Tip | Ne demek |
|---|---|---|
| `source` | text | Nereden geldi: report (rapor), live (canlı), both (ikisi de). |
| `queue` | text | Kuyruk. |
| `caller` | text | Arayan numara. |
| `event_time` | timestamp with time zone | Zaman (UTC). |
| `event_time_trt` | timestamp without time zone | Zaman (İstanbul). |
| `date_trt` | date | Gün (İstanbul). |
| `wait_seconds` | numeric | Beklenen saniye. |
| `is_called_back` | boolean | Müşteriye sonradan geri dönüldü mü (true/false). Son 14 günün bilgisi günceldir; daha eskisi sonradan değişmez. |
| `report_row_id` | text | Rapor satırı kimliği. |
| `live_enter_key` | text | Canlı havuz anahtarı. |

#### `v_abandons_daily` — Günlük kaçan çağrı özeti  _(görünüm)_
- **Bu ne:** Gün × kuyruk: kaçan sayısı, ortalama bekleme, geri dönülen sayısı ve oranı.
- **Sitede nerede görünür:** Kaçan Çağrılar grafikleri.
- **Ne zaman kullan:** Kaçan çağrı trendi.

| Sütun | Tip | Ne demek |
|---|---|---|
| `day` | date | Gün. |
| `queue` | text | Kuyruk. |
| `abandons` | bigint | Kaçan sayısı. |
| `avg_wait_seconds` | numeric | Ortalama bekleme (sn). |
| `called_back` | bigint | Geri dönülen sayısı. |
| `callback_rate` | numeric | Geri dönüş oranı (0–1 arası; 0,5 = %50). |

#### `v_abandons_enriched` — Kaçan çağrı + eşleşen müşteri  _(görünüm)_
- **Bu ne:** v_abandons + arayanın hangi müşteri olduğu (telefondan).
- **Bu ne DEĞİL / dikkat:** Arayanların çoğu CRM'de yoktur (eşleşme düşüktür; hata değil).
- **Sitede nerede görünür:** Kaçan Çağrılar sekmesindeki müşteri adı.
- **Ne zaman kullan:** Kaçanı arayan müşteriyle birlikte görmek.

| Sütun | Tip | Ne demek |
|---|---|---|
| `source` | text | Nereden geldi: report (rapor), live (canlı), both (ikisi de). |
| `queue` | text | Kuyruk. |
| `caller` | text | Arayan numara. |
| `event_time` | timestamp with time zone | Zaman (UTC). |
| `event_time_trt` | timestamp without time zone | Zaman (İstanbul). |
| `date_trt` | date | Gün (İstanbul). |
| `wait_seconds` | numeric | Beklenen saniye. |
| `is_called_back` | boolean | Müşteriye sonradan geri dönüldü mü (true/false). Son 14 günün bilgisi günceldir; daha eskisi sonradan değişmez. |
| `report_row_id` | text | Rapor satırı kimliği. |
| `live_enter_key` | text | Canlı havuz anahtarı. |
| `row_id` | text | Teknik satır kimliği. |
| `contact_key` | text | Normalize telefon. |
| `match_customer_id` | text | Müşteri kimliği. |
| `match_customer_name` | text | Müşteri adı. |
| `match_method` | text | phone; boş = eşleşme yok. |
| `match_count` | bigint | Kaç müşteri eşleşti. |

### C. Müşteriler (CRM) ve kişi eşleştirme

#### `customer_phones` — Müşteri telefon anahtarları  _(tablo · yaklaşık 91.181 satır)_
- **Bu ne:** Telefondan müşteri bulmak için yardımcı tablo: her müşterinin telefonu normalize edilmiş hâlde (phone_key).
- **Bu ne DEĞİL / dikkat:** Kişi verisi değil, eşleştirme yardımcısı.
- **Ne zaman kullan:** Çağrıdaki numarayı müşteriye bağlamak.
- **Birincil anahtar:** `customer_id`, `phone_key`, `source_field`

| Sütun | Tip | Ne demek |
|---|---|---|
| `customer_id` | text | Müşteri kimliği. |
| `phone_key` | text | Normalize telefon (yalnız rakamlar; 0532…, +90532…, 532… hepsi aynı anahtar). |
| `source_field` | text | Telefon hangi alandan alındı. |

#### `customers` — Müşteriler (CRM)  _(tablo · yaklaşık 93.202 satır)_
- **Bu ne:** Voyce CRM'deki müşteri listesi: bir satır = bir müşteri.
- **Bu ne DEĞİL / dikkat:** Bu CRM'de telefon ayrı sütunda değil müşteri numarası (customer_no) içindedir. Çağrı yapan HER kişi müşteri değildir; arayanların çoğu CRM'de kayıtlı değildir.
- **Sitede nerede görünür:** Çağrı Defteri → CRM. Voyce paneli → CRM sayfası.
- **Ne zaman kullan:** Kişi adı, son sonuç kodu, temsilci, deneme sayıları.
- **Birincil anahtar:** `customer_id`

| Sütun | Tip | Ne demek |
|---|---|---|
| `customer_id` | text | Müşteri kimliği (Voyce `_id`). calls.contact_id ile eşleşir. |
| `customer_no` | text | CRM "Müşteri No". Bu CRM'de genelde TELEFON numarasıdır. |
| `customer_name` | text | Adı Soyadı. |
| `phone` | text | Ayrı telefon sütunu — bu CRM'de boş; telefon customer_no'dadır. |
| `phones` | jsonb | Çoklu telefon — bu CRM'de boş. |
| `email` | text | E-posta (çok az kayıtta dolu). |
| `queue` | text | CRM kuyruğu (görünen ad: Tatilox / Otel / Otomatik Arama…). |
| `status` | text | CRM "Durum" harfi (C, U, M, K, I). Anlamı Voyce'ta tanımlı, burada doğrulanmadı; harfe anlam uydurma. |
| `finish_code` | text | Müşterinin SON arama sonucu (CRM Sonuç Kodu). Bir çağrının sonuç kodu değildir. |
| `assigned_agent` | text | Atanmış temsilci. |
| `total_attempts` | bigint | Toplam arama denemesi (CRM "Toplam Temas"). |
| `attempts` | bigint | Güncel kampanyadaki deneme (CRM "Temas"). |
| `active` | boolean | Aktif mi. |
| `create_date` | timestamp with time zone | Kaydın oluşturulma zamanı. |
| `insert_date` | timestamp with time zone | Sisteme yüklenme tarihi (CRM "Yüklenme Tarihi"). |
| `raw` | jsonb | Voyce'un bize verdiği kaydın TAMAMI (ham JSON). Yukarıdaki sütunlarda olmayan her ayrıntı burada. |
| `exported_at` | timestamp with time zone | Teknik: bu satırın en son yazıldığı an. |
| `first_seen_at` | timestamp with time zone | Teknik: satırın arşive ilk girdiği an. |
| `updated_at` | timestamp with time zone | Teknik: satırdaki anlamlı bir değerin en son değiştiği an. |
| `deleted_at` | timestamp with time zone | Voyce'ta artık görünmüyorsa dolar (satır silinmez, işaretlenir). BOŞ = Voyce'ta hâlâ var. |

#### `v_contact_summary` — Kişi çağrı özeti  _(görünüm)_
- **Bu ne:** Telefon başına çağrı özeti: ilk/son temas, son sonuç kodu, eşleşen müşteri.
- **Sitede nerede görünür:** Kişi çekmecesi.
- **Ne zaman kullan:** Bir kişinin özet geçmişi.

| Sütun | Tip | Ne demek |
|---|---|---|
| `contact_key` | text | Normalize telefon. |
| `calls` | bigint | Çağrı (bacak) sayısı. |
| `unique_interactions` | bigint | Benzersiz görüşme. |
| `first_utc` | timestamp with time zone | İlk. |
| `last_utc` | timestamp with time zone | Son. |
| `last_verdict` | text | Son sonuç kodu. |
| `match_count` | bigint | Eşleşen müşteri sayısı. |
| `match_customer_id` | text | Eşleşen müşteri. |

#### `v_contacts` — Kişiler (telefon bazlı)  _(görünüm)_
- **Bu ne:** Telefon başına bir "kişi": kaç çağrı, kaç kaçan çağrı, ilk/son temas, CRM'de kaç kayıt. CRM'de olmayan arayanlar da dahildir.
- **Bu ne DEĞİL / dikkat:** Ad içermez (v_contact_summary / customers'tan bakılır).
- **Sitede nerede görünür:** Kişi çekmecesi.
- **Ne zaman kullan:** En çok arayanlar, kişi sayısı.

| Sütun | Tip | Ne demek |
|---|---|---|
| `contact_key` | text | Normalize telefon. |
| `calls` | numeric | Çağrı sayısı. |
| `abandons` | numeric | Kaçan çağrı sayısı. |
| `first_utc` | timestamp with time zone | İlk temas (UTC). |
| `last_utc` | timestamp with time zone | Son temas (UTC). |
| `crm_customers` | bigint | CRM'de kaç müşteri kaydı bu telefona ait (0 = CRM'de yok). |
| `crm_status` | text | CRM durumu. |

#### `v_customer_phone` — Telefon → müşteri  _(görünüm)_
- **Bu ne:** Telefon anahtarından müşteriye giden hazır görünüm.
- **Ne zaman kullan:** Bir numaranın hangi müşteri(ler)e ait olduğu.

| Sütun | Tip | Ne demek |
|---|---|---|
| `phone_key` | text | Normalize telefon. |
| `source_field` | text | Hangi alandan. |
| `customer_id` | text | Müşteri. |
| `customer_no` | text | Müşteri no. |
| `customer_name` | text | Ad. |
| `finish_code` | text | Son sonuç kodu. |
| `queue` | text | Kuyruk. |
| `status` | text | Durum harfi. |
| `assigned_agent` | text | Temsilci. |
| `active` | boolean | Aktif. |
| `insert_date` | timestamp with time zone | Yüklenme. |
| `deleted_at` | timestamp with time zone | Doluysa Voyce'ta artık yok. |
| `keys_in_group` | bigint | Aynı müşterinin kaç telefon anahtarı var. |

#### `v_match_quality` — Eşleştirme kalitesi  _(görünüm)_
- **Bu ne:** Tek satır: kaç çağrı/kaçan çağrının müşteriyle eşleştiği.
- **Ne zaman kullan:** Eşleşme oranını söylemek.

| Sütun | Tip | Ne demek |
|---|---|---|
| `calls_total` | bigint | Toplam çağrı. |
| `calls_by_contact_id` | bigint | ContactID ile (kesin) eşleşen. |
| `calls_by_phone` | bigint | Telefonla eşleşen. |
| `calls_unmatched` | bigint | Eşleşmeyen (CRM'de olmayan arayan). |
| `calls_no_key` | bigint | Numarası olmayan. |
| `calls_multi_match` | bigint | Birden çok müşteriye giden. |
| `contact_phone_conflicts` | bigint | ContactID ve telefon çelişen. |
| `abandons_total` | bigint | Toplam kaçan. |
| `abandons_by_phone` | bigint | Telefonla eşleşen kaçan. |
| `abandons_unmatched` | bigint | Eşleşmeyen kaçan. |
| `abandons_no_key` | bigint | Numarasız kaçan. |
| `abandons_multi_match` | bigint | Çoklu eşleşen kaçan. |
| `customers_total` | bigint | Müşteri sayısı. |
| `customers_with_phone_key` | bigint | Telefon anahtarı olan müşteri. |
| `customer_phone_keys` | bigint | Toplam anahtar. |
| `shared_phone_keys` | bigint | Birden çok müşteriyi paylaşan telefon. |

### D. Tanım listeleri (kuyruk, temsilci, sonuç kodu...)

#### `finish_codes` — Sonuç kodu tanımları  _(tablo · yaklaşık 23 satır)_
- **Bu ne:** Voyce'ta tanımlı sonuç kodları ve bayrakları (ulaşıldı mı, not zorunlu mu…, raw içinde).
- **Bu ne DEĞİL / dikkat:** Kod kullanım sayısı değildir (sayım için /verdicts). Bir kaç satır kategori kimliğidir.
- **Sitede nerede görünür:** Sonuç Kodları.
- **Ne zaman kullan:** Geçerli sonuç kodlarını listelemek.
- **Birincil anahtar:** `finish_code`
- **Sütunlar:** `finish_code` (Sonuç kodu adı); `display_name` (Ekranda görünen ad); `raw` (Voyce'un bize verdiği kaydın TAMAMI (ham JSON). Yukarıdaki sütunlarda olmayan her ayrıntı burada); `exported_at` (Teknik: bu satırın en son yazıldığı an); `first_seen_at` (Teknik: satırın arşive ilk girdiği an); `updated_at` (Teknik: satırdaki anlamlı bir değerin en son değiştiği an)

#### `projects` — Proje  _(tablo)_
- **Bu ne:** Voyce proje tanımı.
- **Ne zaman kullan:** Proje adı.
- **Birincil anahtar:** `project_name`
- **Sütunlar:** `project_name` (Proje adı); `display_name` (Ekranda görünen ad); `raw` (Voyce'un bize verdiği kaydın TAMAMI (ham JSON). Yukarıdaki sütunlarda olmayan her ayrıntı burada); `exported_at` (Teknik: bu satırın en son yazıldığı an); `first_seen_at` (Teknik: satırın arşive ilk girdiği an); `updated_at` (Teknik: satırdaki anlamlı bir değerin en son değiştiği an)

#### `queues` — Kuyruklar  _(tablo)_
- **Bu ne:** Çağrı kuyruklarının listesi (teknik ad + görünen ad).
- **Sitede nerede görünür:** Kuyruk & Hat sekmesi.
- **Ne zaman kullan:** calls.queue değerini okunur ada çevirmek.
- **Birincil anahtar:** `queue_name`
- **Sütunlar:** `queue_name` (Teknik ad (calls.queue ile aynı)); `display_name` (Ekranda görünen ad); `raw` (Voyce'un bize verdiği kaydın TAMAMI (ham JSON). Yukarıdaki sütunlarda olmayan her ayrıntı burada); `exported_at` (Teknik: bu satırın en son yazıldığı an); `first_seen_at` (Teknik: satırın arşive ilk girdiği an); `updated_at` (Teknik: satırdaki anlamlı bir değerin en son değiştiği an)

#### `reference_snapshots` — Referans anlık görüntüleri  _(tablo · yaklaşık 51 satır)_
- **Bu ne:** Hat, kampanya, IVR gibi tanımların Voyce'tan alınmış ham kopyaları (uç yoluyla etiketli).
- **Sitede nerede görünür:** Kuyruk & Hat sekmesi.
- **Ne zaman kullan:** Hat/IVR/kampanya tanımlarına bakmak (payload sütunu).
- **Birincil anahtar:** `endpoint`, `fetched_at`
- **Sütunlar:** `endpoint` (Hangi Voyce ucundan alındı); `fetched_at` (Alınma anı); `payload` (Yanıtın tamamı (JSON)); `payload_sha256` (Teknik içerik özeti)

#### `statuses` — Temsilci durumları  _(tablo · yaklaşık 22 satır)_
- **Bu ne:** Temsilcinin seçebildiği durumlar (Müsait, Mola…).
- **Ne zaman kullan:** Durum adları.
- **Birincil anahtar:** `status_name`
- **Sütunlar:** `status_name` (Durum adı); `display_name` (Ekranda görünen ad); `raw` (Voyce'un bize verdiği kaydın TAMAMI (ham JSON). Yukarıdaki sütunlarda olmayan her ayrıntı burada); `exported_at` (Teknik: bu satırın en son yazıldığı an); `first_seen_at` (Teknik: satırın arşive ilk girdiği an); `updated_at` (Teknik: satırdaki anlamlı bir değerin en son değiştiği an)

#### `tags` — Etiketler  _(tablo)_
- **Bu ne:** Voyce etiket tanımları.
- **Ne zaman kullan:** Etiket listesi.
- **Birincil anahtar:** `tag`
- **Sütunlar:** `tag` (Etiket); `display_name` (Ekranda görünen ad); `raw` (Voyce'un bize verdiği kaydın TAMAMI (ham JSON). Yukarıdaki sütunlarda olmayan her ayrıntı burada); `exported_at` (Teknik: bu satırın en son yazıldığı an); `first_seen_at` (Teknik: satırın arşive ilk girdiği an); `updated_at` (Teknik: satırdaki anlamlı bir değerin en son değiştiği an)

#### `users` — Kullanıcılar / temsilciler  _(tablo)_
- **Bu ne:** Voyce kullanıcıları ve temsilciler.
- **Bu ne DEĞİL / dikkat:** Parola/token alanları API'den çıkarılır.
- **Ne zaman kullan:** calls.agent kullanıcı adını isme çevirmek.
- **Birincil anahtar:** `username`
- **Sütunlar:** `username` (Kullanıcı adı (calls.agent ile aynı)); `display_name` (Ekranda görünen ad); `raw` (Voyce'un bize verdiği kaydın TAMAMI (ham JSON). Yukarıdaki sütunlarda olmayan her ayrıntı burada); `exported_at` (Teknik: bu satırın en son yazıldığı an); `first_seen_at` (Teknik: satırın arşive ilk girdiği an); `updated_at` (Teknik: satırdaki anlamlı bir değerin en son değiştiği an)

### E. Randevu, görev, takvim

#### `appointments` — Randevular  _(tablo · yaklaşık 12.529 satır)_
- **Bu ne:** Temsilcilerin takvimine koyduğu randevular.
- **Bu ne DEĞİL / dikkat:** Voyce bu listeyi 1000 satırda keser; eksik olabilir.
- **Sitede nerede görünür:** Randevu & Görev sekmesi.
- **Ne zaman kullan:** Randevu listesi.
- **Birincil anahtar:** `appointment_id`
- **Sütunlar:** `appointment_id` (Kimlik); `agent` (Temsilci); `scheduled_at` (Randevu zamanı); `title` (Başlık); `status` (Durum); `phone` (Telefon); `raw` (Voyce'un bize verdiği kaydın TAMAMI (ham JSON). Yukarıdaki sütunlarda olmayan her ayrıntı burada); `exported_at` (Teknik: bu satırın en son yazıldığı an); `first_seen_at` (Teknik: satırın arşive ilk girdiği an); `updated_at` (Teknik: satırdaki anlamlı bir değerin en son değiştiği an)

#### `calendar_events` — Takvim olayları  _(tablo · yaklaşık 1.207 satır)_
- **Bu ne:** Takvimdeki olaylar.
- **Bu ne DEĞİL / dikkat:** Voyce 1000 satırda keser.
- **Sitede nerede görünür:** Randevu & Görev sekmesi.
- **Ne zaman kullan:** Takvim.
- **Birincil anahtar:** `event_id`
- **Sütunlar:** `event_id` (Kimlik); `title` (Başlık); `agent` (Temsilci); `start_at` (Başlangıç); `end_at` (Bitiş); `raw` (Voyce'un bize verdiği kaydın TAMAMI (ham JSON). Yukarıdaki sütunlarda olmayan her ayrıntı burada); `exported_at` (Teknik: bu satırın en son yazıldığı an); `first_seen_at` (Teknik: satırın arşive ilk girdiği an); `updated_at` (Teknik: satırdaki anlamlı bir değerin en son değiştiği an)

#### `tasks` — Görevler  _(tablo · yaklaşık 1.643 satır)_
- **Bu ne:** Görev panolarındaki görevler.
- **Sitede nerede görünür:** Randevu & Görev sekmesi.
- **Ne zaman kullan:** Görev listesi.
- **Birincil anahtar:** `task_id`
- **Sütunlar:** `task_id` (Kimlik); `section` (Pano/bölüm); `title` (Başlık); `status` (Durum); `assignee` (Atanan kişi); `due_at` (Son tarih); `raw` (Voyce'un bize verdiği kaydın TAMAMI (ham JSON). Yukarıdaki sütunlarda olmayan her ayrıntı burada); `exported_at` (Teknik: bu satırın en son yazıldığı an); `first_seen_at` (Teknik: satırın arşive ilk girdiği an); `updated_at` (Teknik: satırdaki anlamlı bir değerin en son değiştiği an)

### F. Teknik / izleme tabloları (çoğu zaman gerekmez)

#### `abandon_poll_runs` — Canlı havuz okuma turları  _(tablo · yaklaşık 33.537 satır)_
- **Bu ne:** Her 2 dakikalık okumanın kaydı (başarılı/hatalı, kaç kayıt).
- **Bu ne DEĞİL / dikkat:** İş verisi değil, izleme.
- **Ne zaman kullan:** Toplayıcı sağlıklı mı?
- **Birincil anahtar:** `run_id`
- **Sütunlar:** `run_id`, `polled_at`, `status`, `queues`, `records`, `new_records`, `error`

#### `abandon_pool_stats` — Havuz sayıları  _(tablo · yaklaşık 202.314 satır)_
- **Bu ne:** Tur başına kuyruk havuz sayıları.
- **Bu ne DEĞİL / dikkat:** İzleme.
- **Birincil anahtar:** `run_id`, `queue`
- **Sütunlar:** `run_id`, `queue`, `record_count`, `oldest_enter_time`

#### `abandon_report_windows` — Kaçan rapor çekim pencereleri  _(tablo · yaklaşık 1.050 satır)_
- **Bu ne:** Gece raporunun hangi gün aralığının tam çekildiğinin kaydı.
- **Bu ne DEĞİL / dikkat:** İzleme.
- **Ne zaman kullan:** Eksik çekilen pencere var mı (status ≠ done)?
- **Birincil anahtar:** `window_key`
- **Sütunlar:** `window_key`, `level`, `window_start`, `window_end`, `status`, `row_count`, `data_limit`, `attempts`, `next_retry_at`, `fetched_at`

#### `agent_events` — Temsilci olay günlüğü  _(tablo · yaklaşık 572.002 satır)_
- **Bu ne:** Temsilcinin durum değişiklikleri (giriş, çıkış, mola, hazır, konuşmada...) olay olay.
- **Bu ne DEĞİL / dikkat:** Çağrı verisi değildir. prev_status_length saniyedir (doğrulandı).
- **Sitede nerede görünür:** Yok (yalnız veri API'si).
- **Ne zaman kullan:** Temsilcinin ne zaman hangi durumda olduğu.
- **Birincil anahtar:** `event_id`
- **Sütunlar:** `event_id`, `event_time`, `username`, `event`, `status`, `reason`, `prev_event`, `prev_status`, `prev_reason`, `prev_status_length`, `last_action_at`, `interaction_id`, `interaction_queue`, `agent_queues`, `agent_name`, `raw`, `exported_at`

#### `export_runs` — Aktarım çalışma kayıtları  _(tablo)_
- **Bu ne:** Arşive toplu aktarım çalıştırmalarının özeti.
- **Bu ne DEĞİL / dikkat:** İzleme.
- **Birincil anahtar:** `run_id`
- **Sütunlar:** `run_id`, `started_at`, `finished_at`, `status`, `pii_mode`, `scope`, `from_date`, `counters`, `warnings`

#### `reconciliation_runs` — Gece uzlaştırma  _(tablo · yaklaşık 1.334 satır)_
- **Bu ne:** Voyce'taki sayı ile arşivdeki sayının her gece karşılaştırılması.
- **Bu ne DEĞİL / dikkat:** İzleme.
- **Ne zaman kullan:** Veriler Voyce ile tutuyor mu? status = ok iyi; mismatch sorun.
- **Birincil anahtar:** `id`
- **Sütunlar:** `id`, `ran_at`, `scope`, `day`, `source_count`, `db_count`, `diff`, `status`

#### `report_rows` — Panel rapor arşivi satırları  _(tablo · yaklaşık 99.412 satır)_
- **Bu ne:** Panel raporlarının satırları (varsayılan kapalı).
- **Bu ne DEĞİL / dikkat:** Genelde boş.
- **Birincil anahtar:** `report_name`, `variant`, `row_key`
- **Sütunlar:** `report_name`, `variant`, `row_key`, `event_time`, `window_key`, `data`, `fetched_at`, `first_seen_at`, `updated_at`

#### `report_windows` — Panel rapor arşivi pencereleri  _(tablo · yaklaşık 3.899 satır)_
- **Bu ne:** Panel raporlarının arşivlenmesi (varsayılan kapalı).
- **Bu ne DEĞİL / dikkat:** Genelde boş.
- **Birincil anahtar:** `report_name`, `variant`, `window_key`
- **Sütunlar:** `report_name`, `variant`, `window_key`, `level`, `window_start`, `window_end`, `status`, `row_count`, `data_limit`, `attempts`, `next_retry_at`, `fetched_at`

#### `row_history` — Değişiklik geçmişi  _(tablo · yaklaşık 19.698 satır)_
- **Bu ne:** Bir kayıt değiştiğinde neyin neyden neye döndüğü (örn. bir çağrının sonuç kodu düzeltildi).
- **Bu ne DEĞİL / dikkat:** Sadece arşivin gördüğü değişiklikleri içerir.
- **Ne zaman kullan:** Bir kaydın eski hâli.
- **Birincil anahtar:** `id`
- **Sütunlar:** `id`, `table_name`, `pk`, `changed_at`, `changes`

#### `v_agent_events` — Temsilci olayları + İstanbul saati  _(görünüm)_
- **Bu ne:** agent_events tablosunun raw ve agent_name HARİÇ hali; event_time_trt ve date_trt İstanbul saatiyle eklenmiştir.
- **Bu ne DEĞİL / dikkat:** Çağrı verisi değildir. Aynı olayların ham hali Activity/LoginLogout raporlarında da vardır: ikisini birlikte toplamayın (çift sayım).
- **Sitede nerede görünür:** Yok (yalnız veri API'si).
- **Ne zaman kullan:** Temsilcinin ne zaman hangi durumda olduğu (İstanbul saatiyle).
- **Sütunlar:** `event_id`, `event_time`, `event_time_trt`, `date_trt`, `username`, `event`, `status`, `reason`, `prev_event`, `prev_status`, `prev_reason`, `prev_status_length`, `last_action_at`, `interaction_id`, `interaction_queue`, `agent_queues`

#### `v_archive_coverage` — Arşiv kapsamı (kaynak başına)  _(görünüm)_
- **Bu ne:** call_cdr, agent_events ve call_transcripts için satır sayısı, en eski/en yeni kayıt ve geçmiş doldurma imleci.
- **Bu ne DEĞİL / dikkat:** Yalnız bu üç kaynak; geçmiş doldurma sütunları call_transcripts için boştur.
- **Sitede nerede görünür:** Yok (yalnız veri API'si).
- **Ne zaman kullan:** "O tarihte veri yok" ile "henüz doldurulmadı" ayrımı için.
- **Sütunlar:** `source`, `row_count`, `first_record_at`, `last_record_at`, `backfill_from`, `backfill_to`, `backfill_next_day`, `backfill_done`, `backfill_skipped_days`

#### `v_call_ai_signals` — Voyce yapay zeka alanı var mı bayrakları  _(görünüm)_
- **Bu ne:** calls satırı başına Voyce'un yapay zeka ile ilgili alanlarının dolu olup olmadığı (yalnız var/yok, içerik yok).
- **Bu ne DEĞİL / dikkat:** Bugün hepsi boş/false: Voyce bu alanları doldurmaya başlayınca fark etmek için vardır.
- **Sitede nerede görünür:** Yok (yalnız veri API'si).
- **Ne zaman kullan:** Voyce'un yeni yapay zeka alanlarını doldurup doldurmadığını izlemek.
- **Sütunlar:** `call_id`, `start_date_trt`, `has_transcript`, `is_ai_recording`, `ai_recordings_present`, `speech_present`, `analysis_keys_present`, `risk_summary_present`

#### `v_report_catalog` — Rapor arşivi özeti  _(görünüm)_
- **Bu ne:** Rapor arşivinin özeti (varsayılan boş).
- **Sütunlar:** `report_name`, `variant`, `row_count`, `first_event_trt`, `last_event_trt`, `done_windows`, `incomplete_windows`, `unsupported_or_empty_windows`, `last_fetched_trt`

#### `v_report_rows` — Rapor arşivi satırları  _(görünüm)_
- **Bu ne:** Rapor arşivi satırlarının görünümü (varsayılan boş).
- **Sütunlar:** `report_name`, `variant`, `row_key`, `event_time`, `event_time_trt`, `date_trt`, `data`, `first_seen_at`, `updated_at`

#### `v_sync_health` — Senkron sağlığı  _(görünüm)_
- **Bu ne:** Tek satır: gece işlerinin son başarı zamanları, eksik pencere ve uyuşmazlık sayıları, müşteri sayısı.
- **Sitede nerede görünür:** Panel üst çubuğundaki uyarı.
- **Ne zaman kullan:** Veri ne kadar taze? (calls_sync_ok_trt dünden eskiyse "veri güncel olmayabilir" de.)
- **Sütunlar:** `abandon_refetch_ok_trt`, `calls_sync_ok_trt`, `customers_sync_ok_trt`, `reconcile_ok_trt`, `incomplete_report_windows`, `incomplete_call_windows`, `recent_mismatches`, `last_reconcile_trt`, `customers_active`, `customers_deleted`, `customers_cap`, `reports_sync_ok_trt`, `incomplete_report_archive_windows`

## 8. Bu belgeyi kullanırken

- Bir şeyden emin değilsen uydurma: `GET /tables/{ad}?limit=3` ile gerçek satıra bak.
- Sayı verirken tarih aralığını ve kaynağı yaz. Veri yoksa "yok" de.
- Bu rehberin güncel hâli her zaman: `https://mly555au7hddga4r5n7d39dp.hecateq.cloud/tatiloxvoyceapi/v1/ai-guide`.
