Kullanım Kılavuzu

Genel Bakış

Divan; gelen faturaların satınalma siparişleriyle karşılaştırılması, departmanlara ve çalışanlara dağıtılması, not ve fayda takibi, tedarikçi iletişimi ve yapay zeka destekli kalem eşleştirmesi gibi işlemleri tek bir platformda toplar.

Yetki Seviyeleri

Her kullanıcının bir register_number (yetki seviyesi) değeri vardır. Menüde görünen sayfalar ve yapılabilecek işlemler bu seviyeye göre belirlenir.

Dashboard

Ana sayfa, seçilen tarih aralığına göre fatura süreçlerinin genel görünümünü sunar.

Tarih filtreleri

• Son 7 gün, Son 1 ay, Son 3 ay, Tüm zamanlar
• Özel Aralık — başlangıç ve bitiş tarihi seçerek istediğiniz dönemi görüntüleyin

Özet kartları

• Toplam fatura sayısı ve tutarı
• SAS numarası eksik fatura adedi ve tutarı
• Depo giriş bekleyen faturalar
• Fatura–satınalma tutarsızlıkları
• Ortalama işlem süresi ve tamamlanma oranı
• Fayda var adet ve fayda TL toplamı
• Tedarikçilere gönderilen mail ve alınan cevap sayıları
• Depo hatırlatma ve yönetici bildirim sayıları

Grafikler

Aylık SAS tutar/adet grafikleri ve durum dağılımı pasta grafiği gösterilir.

Log indirme (Excel)

Yetki seviyesi 3 ve üzeri kullanıcılar, seçilen tarih aralığındaki tüm işlem kayıtlarını Excel dosyası olarak indirebilir.

Faturalar

Tüm faturaların listelendiği ana çalışma ekranıdır. Filtreleme, sıralama, detay inceleme ve toplu işlemler buradan yapılır.

Liste özellikleri

• Metin arama, tarih, kategori, departman, durum, etiket, fayda ve lokasyon filtreleri
• Sütun seçimi, sürükle-bırak sıralama ve genişlik ayarı (tercihler tarayıcıda saklanır)
• Sayfalama (sayfa başına 50 kayıt)
• Fatura tutarı, satınalma tutarı, tutar farkı, miktar farkı ve yüzde karşılaştırması

Fatura detayı

• Fatura kalemleri ve karşılık gelen satınalma kalemleri yan yana görüntülenir
• Not geçmişi (metin ve görsel not desteği)
• Kategori ve etiket güncelleme
• Fayda var / fayda tutarı işaretleme (yetki 2+)
• Tekli görev atama — çalışana veya departmana yönlendirme
• Fatura PDF görüntüleme

Toplu işlemler

• Birden fazla faturayı seçerek toplu görev atama
• Hazır hata sebebi listesinden not seçimi (Ayarlar'dan yönetilir)
• Toplu atamada isteğe bağlı mail gönderimi

Yapay zeka (fatura detayında)

Fatura detayında AI eşleştirme için seviye 3+ gerekir.

• Fatura ve satınalma kalemlerini otomatik eşleştirme (Gemini veya OpenAI)
• Öğrenilmiş eşleştirmeler ve birim dönüşümlerinden yararlanma
• Manuel düzeltme ve başarılı eşleştirmeyi hafızaya kaydetme
• Oturum bazlı token kullanım takibi

Görevlerim

Size atanmış faturaların listelendiği kişisel çalışma alanıdır. Faturalar sayfasıyla benzer detay ve işlem yeteneklerine sahiptir; odak noktası yalnızca size atanan kayıtlardır.

Yapılabilecekler

• Atanan faturaları filtreleme ve inceleme
• Not ekleme (metin veya görsel)
• SAS numarası güncelleme ve robot entegrasyonu tetikleme
• Faturayı başka bir çalışana veya departmana devretme
• Toplu görev atama ve mail gönderimi
• Fayda bilgisi güncelleme (yetkiye bağlı)

Bildirim entegrasyonu

Size yeni görev atandığında üst menüdeki zil simgesinden bildirim alırsınız. Bildirime tıklayınca ilgili fatura Görevlerim listesinde açılır.

Mailler

Tedarikçi ve depo e-posta adreslerinin yönetildiği modüldür.

Tedarikçi mailleri

• Vergi numarasına bağlı tedarikçi e-posta adreslerini görüntüleme ve düzenleme
• Ek mail adresi tanımlama
• Belirli tedarikçilere mail gönderimini devre dışı bırakma

Depo / lokasyon mailleri

• Üretim yeri ve depo kodlarına bağlı hatırlatma e-posta adresleri
• Depo kodu ve mail adresi ekleme, düzenleme, silme

Mail gönderimi, Ayarlar sayfasındaki SMTP yapılandırmasına bağlıdır. SMTP kapalıysa uygulama içi "Mail gönder" butonları çalışmaz; webhook tetiklemesi bağımsızdır.

Raporlar

Programın çalışan ve tedarikçi bazlı kullanım görünümünü sunar. Tüm metrikler kullanici.log tablosundaki işlem kayıtlarından hesaplanır.

Tarih filtreleri

• Son 7 gün, Son 1 ay, Son 3 ay, Tüm zamanlar
• Özel Aralık — başlangıç ve bitiş tarihi seçerek özel dönem raporu

Özet kartları

İşlem nedir?

İşlem, bir fatura üzerinde yapılan ve sisteme kaydedilen her eylemdir. Sadece faturaya bakmak veya listeyi görüntülemek işlem sayılmaz. Aynı faturada birden fazla işlem yapılırsa her biri ayrı sayılır; bu nedenle Toplam İşlem, Etkileşimli Fatura sayısından yüksek olabilir.

Yapay zeka kalem eşleştirme çağrıları işlem kaydına yazılmaz; yalnızca AI token kullanım tablosunda izlenir.

Diğer bölümler

• Günlük Kullanım Trendi — gün bazında işlem sayısı (en fazla son 14 gün)
• Çalışan Bazlı Kullanım — işlem, fatura ve son işlem tarihi (en aktif 12 çalışan)
• Tedarikçi Bazlı Kullanım — etkileşim ve fatura sayısı (en aktif 12 tedarikçi)

Yapay Zeka

Fatura kalemlerini satınalma kalemleriyle eşleştirmek için yapay zeka desteği sunar. Gemini ve OpenAI sağlayıcıları desteklenir; varsayılan sağlayıcı Ayarlar'dan belirlenir.

Kalem eşleştirme

• Fatura ve satınalma satırlarını anlamsal olarak eşleştirme
• Güven skoru ve gerekçe ile sonuç gösterimi
• Eşleşmeyen satırların ayrı listelenmesi
• Fatura detay ekranından ve Yapay Zeka sayfasından çalıştırılabilir

Öğrenim hafızası

• Başarılı eşleştirmeler — onaylanan fatura/satınalma çiftleri tedarikçi bazında saklanır
• Birim dönüşümleri — örn. kg ↔ adet dönüşüm katsayıları
• Metin dönüşümleri — farklı ürün adı yazımlarının eşleştirilmesi
• Hafıza kayıtları düzenlenebilir ve silinebilir

Token kullanımı ve maliyet

• Oturum bazlı token sayacı (tarayıcı sekmesi açık kaldığı sürece)
• Veritabanında saklanan toplam AI çağrı özeti
• Model bazlı tahmini maliyet hesaplama (USD ve TRY)
• Desteklenen modeller: gpt-4o-mini, gemini-2.5-flash-lite, gemini-2.5-flash ve yedek zincir modelleri

Öğretim (manuel eğitim)

Yapay Zeka sayfasından bir fatura seçip fatura ve satınalma satırlarını manuel eşleştirerek sisteme öğretebilirsiniz. İsteğe bağlı olarak birim dönüşümü de kaydedilebilir.

Bildirimler

Üst menüdeki zil simgesi, size atanan yeni görevleri gösterir. Bildirimler yaklaşık 15 saniyede bir otomatik yenilenir; yeni bildirim geldiğinde ses çalınır.

• Bildirime tıklayınca ilgili fatura Görevlerim sayfasında açılır
• "Tümünü okundu işaretle" ile toplu temizleme
• Görev atama sırasında atanana otomatik bildirim oluşturulur

İşlem Kayıtları (Log)

Fatura üzerindeki önemli kullanıcı eylemleri kullanici.log tablosuna yazılır. Bu kayıtlar hem Dashboard'daki Excel indirme hem de Raporlar sayfasının veri kaynağıdır.

Fatura bazında log görüntüleme

Her faturanın detay ekranında işlem geçmişi kronolojik olarak listelenir.

Toplu log indirme

Dashboard'da yetki seviyesi 3+ kullanıcılar tarih aralığı seçerek tüm logları Excel'e aktarabilir. İndirilen dosyada tarih, kullanıcı, fatura no, firma, işlem türü ve açıklama yer alır.

Integrasyon API istek logları

Dış sistemlerin çağırdığı integrasyon endpoint'leri kullanici.integrasyon_log tablosuna yazılır. API erişimi olan kullanıcılar profil menüsündeki API Erişimi sayfasında kendi isteklerini görebilir; yöneticiler tüm kullanıcıların loglarını listeleyebilir.

Integrasyon API

Harici sistemlerin (ERP, robot, ETL vb.) fatura ve satınalma verisini aktarması, durum/kategori güncellemesi ve görev ataması yapması için HTTP API sunulur. Kimlik doğrulama OAuth2 benzeri client credentials akışı ile yapılır.

Kim erişebilir?

• Yönetici, Kullanıcı Yönetimi ekranından kullanıcıya API erişimi açar/kapatır.
• API erişimi açık kullanıcılar profil menüsünde API Erişimi linkini görür.
• Erişim kapalı kullanıcılar menüyü ve /profil/api-erisim sayfasını göremez.

Kullanıcı arayüzü (API Erişimi)

Profil menüsü → API Erişimi sayfası üç sekmeden oluşur:

• Kimlik Bilgileri — Client ID / Secret oluşturma, test token alma
• API Referansı — Swagger tarzı endpoint dokümantasyonu ve “Dene” ile test çağrısı
• İstek Logları — Son API çağrıları (yönetici: tüm kullanıcılar)

client_secret yalnızca oluşturulduğu anda bir kez gösterilir. Yenileme eski secret'ı geçersiz kılar. Token süresi 1 saattir.

Kimlik doğrulama akışı

1. Kullanıcı arayüzden Client ID ve Secret oluşturur.
2. POST /api/integrasyon/token ile access token alınır.
3. Diğer endpoint'lere Authorization: Bearer <token> header'ı ile istek atılır.

POST /api/integrasyon/token
Content-Type: application/json

{
  "grant_type": "client_credentials",
  "client_id": "api_...",
  "client_secret": "..."
}

Veri gönderme mantığı

Dış servis master ve detay tablolarını ayrı ayrı oluşturmaz. Faturayı ve satınalmayı tek JSON belgesi olarak hazırlar; kalemler satirlar dizisi içinde gelir. Divan sunucusu bunu içeride üst bilgi + kalem tablolarına yazar.

• Fatura belgesi — üst alanlar + satirlar[] (fatura kalemleri)
• Satınalma belgesi (SAS) — sas_no ve üst alanlar + satirlar[] (SAS kalemleri)
• Bir faturada birden fazla SAS olabilir; her SAS için ayrı belge gönderilir.

Ayrıntılı kullanım kılavuzu (alan listeleri, cURL örnekleri, akış diyagramı): docs/integrasyon-api-kullanim.md (proje deposu).

Fatura gönderme örneği

Entegratörün hazırladığı mantıksal JSON:

{
  "fatura_no": "FT2026001",
  "vergi_no": "1234567890",
  "firma_adi": "Örnek Gıda A.Ş.",
  "fatura_tutar": 15000.50,
  "fatura_tarih": "2026-06-01",
  "satirlar": [
    { "satir_no": 1, "stok_kod": "5303553", "miktar": 100, "tutar": 5000 },
    { "satir_no": 2, "stok_kod": "5303554", "miktar": 50, "tutar": 10000.50 }
  ]
}

API’ye iki istek olarak gider: önce fatura-master (üst alanlar), ardından fatura-detay (satirlar). Fatura yoksa önce master zorunludur.

Satınalma (SAS) gönderme örneği

{
  "sas_no": "4500123456",
  "vergi_no": "1234567890",
  "fatura_no": "FT2026001",
  "sas_tutar": 15000.50,
  "satirlar": [
    { "satir_no": 10, "stok_kod": "5303553", "miktar": 100, "tutar": 5000 },
    { "satir_no": 20, "stok_kod": "5303554", "miktar": 50, "tutar": 10000.50 }
  ]
}

Önerilen: satinalma-master + satinalma-detay. Yalnızca satinalma-detay gönderilirse master otomatik oluşabilir; başlık alanları eksik kalabilir.

Veri aktarım endpoint'leri

Tamamlanmış faturalar (durum=3) master/detay güncellemesinden hariç tutulur.

SAS Birim Fiyat listesi (günlük)

SAS Birim Fiyat Uyarısı ekranındaki liste günlük arşivlenir: her takvim günü için tek snapshot (parametre.sas_birim_fiyat_import.liste_gun). Aynı gün Excel veya API ile tekrar yükleme yapılırsa o güne ait satırlar silinip yenisi yazılır; önceki günler korunur. Aynı gün içinde satinalma_belgesi + satinalma_kalemi + malzeme tekrar eden satırlar import sırasında tekilleştirilir.

SAP/robot günlük job örneği: önce fatura ve SAS detaylarını aktarın, ardından POST /api/integrasyon/sas-birim-fiyat ile fark listesini gönderin. İleride liste satırları satinalma.detay üzerinden faturaya bağlanabilir (sas_no + kalem no).

POST /api/integrasyon/sas-birim-fiyat
Authorization: Bearer <token>
Content-Type: application/json

{
  "liste_gun": "2026-06-24",
  "kaynak": "SAP günlük job",
  "satirlar": [
    {
      "satinalma_belgesi": "4502337182",
      "satinalma_kalemi": 10,
      "malzeme": "5303553",
      "tanim": "DANA KONTRAFILE",
      "fatura_birim_fiyat": 125000000,
      "sas_birim_fiyat": 118000000,
      "tutar_farki": 35000
    }
  ]
}

İş akışı endpoint'leri

İş akışı çağrıları UI'daki kategori, departman ve görev atama mantığıyla uyumludur; başarılı işlemler kullanici.log tablosuna da yazılır.

Örnek entegrasyon akışı

1. POST /api/integrasyon/token — erişim tokenı al
2. GET /api/integrasyon/referanslar — kategori/departman/durum kodları (isteğe bağlı)
3. POST /api/integrasyon/fatura — fatura belgesi (üst bilgi + satirlar)
4. Her SAS için POST /api/integrasyon/satinalma — SAS belgesi (üst bilgi + satirlar)
5. POST /api/integrasyon/sas-birim-fiyat — günlük birim fiyat fark listesi (isteğe bağlı)
6. POST /api/integrasyon/fatura-kategori veya fatura-departman — yönlendir
7. POST /api/integrasyon/fatura-gorev-atama — çalışana ata
8. POST /api/integrasyon/fatura-durum — tamamlandı olarak işaretle

Ortam değişkenleri (sunucu)

• INTEGRASYON_JWT_SECRET — Bearer token imzalama (yoksa CLIENTSECRET kullanılır)
• INTEGRASYON_API_KEY — eski sistemler için X-Integrasyon-Key header desteği (isteğe bağlı)

Veritabanı

• kullanici.api_client — kullanıcı başına client kimlikleri
• kullanici.master.api_enabled — kullanıcı bazlı API erişim bayrağı
• kullanici.integrasyon_log — API istek logları
• parametre.sas_birim_fiyat_import — günlük liste arşivi (liste_gun)
• parametre.sas_birim_fiyat — SAS birim fiyat fark satırları

Program Ayarları

Profil menüsünden Ayarlar sayfasına erişilir. Sayfa yan menü + geniş içerik paneli düzenindedir.

SMTP (Mail gönderimi)

• SMTP sunucu, port, TLS, kullanıcı adı ve şifre
• Gönderen adı ve e-posta adresi
• SMTP aktif/pasif anahtarı

Otomatik mesajlar

Görev atama ekranındaki "Hata Sebebi" açılır listesinin içeriği buradan yönetilir. Kayıtlar tablo halinde listelenir; satır içinde düzenlenebilir, yukarı/aşağı taşınabilir veya silinebilir. Tablo altındaki alandan yeni sebep eklenir. Sıra, görev atama ekranındaki listeleme sırasını belirler.

Robot / Webhook

Görev atandığında tetiklenen webhook URL'si. Boş bırakılırsa ortam değişkenindeki varsayılan adres kullanılır.

Yapay zeka ayarları

• Varsayılan sağlayıcı (Gemini veya OpenAI)
• API anahtarları ve model adları (Gemini / OpenAI-Azure kartları)
• Günlük AI sorgu limiti (ortak havuz)
• Boş bırakılan key alanları mevcut değeri korur

Kullanıcı Yönetimi

Profil menüsünden Kullanıcılar sayfasına erişilir.

• Kullanıcı listesi görüntüleme (tabloda API erişim durumu: Açık/Kapalı)
• Yeni kullanıcı oluşturma (ad, e-posta, departman, yetki seviyesi)
• Mevcut kullanıcı düzenleme
• API erişimi açma/kapama (integrasyon API için client credentials)
• Şifre sıfırlama (e-posta ile veya doğrudan yeni şifre atama)
• Yönetici (is_manager) bayrağı

Şifremi unuttum akışı: giriş sayfasından e-posta ile sıfırlama bağlantısı gönderilebilir.