{"id":26505543,"url":"https://github.com/nec0ti/fatrocu","last_synced_at":"2025-06-16T23:05:29.438Z","repository":{"id":272940996,"uuid":"864515913","full_name":"Nec0ti/Fatrocu","owner":"Nec0ti","description":"Fatrocu converts your e-invoice images or pdf files into Excel format","archived":false,"fork":false,"pushed_at":"2025-05-12T15:19:04.000Z","size":175,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-05-12T15:52:34.808Z","etag":null,"topics":["ai","ai-analysis","dokuman","e-document","e-invoice","fatrocu","fiscal-printer","image-processing","invoice","javascript","pos"],"latest_commit_sha":null,"homepage":"https://nec0ti.github.io/Fatrocu/","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Nec0ti.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2024-09-28T12:31:45.000Z","updated_at":"2025-05-12T14:36:15.000Z","dependencies_parsed_at":"2025-01-17T15:45:55.323Z","dependency_job_id":"ba9fb604-5cf2-41c2-8133-461c80a1e177","html_url":"https://github.com/Nec0ti/Fatrocu","commit_stats":null,"previous_names":["nec0ti/fatrocu"],"tags_count":5,"template":false,"template_full_name":null,"purl":"pkg:github/Nec0ti/Fatrocu","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Nec0ti%2FFatrocu","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Nec0ti%2FFatrocu/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Nec0ti%2FFatrocu/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Nec0ti%2FFatrocu/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Nec0ti","download_url":"https://codeload.github.com/Nec0ti/Fatrocu/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Nec0ti%2FFatrocu/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":260256241,"owners_count":22981806,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai","ai-analysis","dokuman","e-document","e-invoice","fatrocu","fiscal-printer","image-processing","invoice","javascript","pos"],"created_at":"2025-03-20T21:47:36.505Z","updated_at":"2025-06-16T23:05:29.423Z","avatar_url":"https://github.com/Nec0ti.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Fatrocu v2 - Akıllı Fatura İşleme Asistanı\n\n**Muhasebe süreçlerinizi hızlandırın ve doğruluğu en üst düzeye çıkarın. Fatrocu v2, e-Faturaları (XML), PDF'leri ve resimleri analiz ederek fatura verilerini otomatik olarak yapılandırılmış Excel formatına dönüştürür.**\n\n---\n\n## Genel Bakış\n\nFatrocu v2, mali müşavirler ve işletmeler için fatura veri girişinin zaman alan ve hataya açık sürecini otomatikleştirmek üzere **yeniden tasarlanmış** bir araçtır. Bu yeni sürüm, güvenilir bir Python backend'i ve modern bir web arayüzü üzerine kurulmuştur.\n\nTürkiye'deki **e-Fatura (UBL-TR XML)** standartlarını doğrudan ayrıştırarak **%100'e yakın doğruluk** sağlarken, PDF ve resim formatındaki faturalar için **Google'ın gelişmiş Gemini 2.5 Pro Experimental modelinin** gücünü kullanır.\n\nSezgisel web arayüzü sayesinde faturalarınızı kolayca yükleyin, Fatrocu'nun akıllı analizini izleyin, çıkarılan verileri gözden geçirin ve tek tıklamayla Excel'e aktarın.\n\n**(Not: Bu proje aktif geliştirme aşamasındadır. Mevcut sürüm temel işlevleri içerir ancak tam özellik seti henüz tamamlanmamıştır.)**\n\n## Anahtar Özellikler (v2)\n\n*   **🚀 Yepyeni Mimari:** Güvenlik, performans ve geliştirilebilirlik için **Python (Flask) Backend + Web (HTML/JS) Frontend** hibrit modeli.\n*   **🥇 e-Fatura (UBL-TR XML) Desteği:** Yüklenen XML dosyalarını veya PDF'e gömülü XML'leri doğrudan ayrıştırarak **maksimum doğruluk** sağlar.\n*   **✨ Gelişmiş PDF ve Resim Analizi:** Google Gemini 2.5 Pro experimental kullanarak PDF, PNG, JPG, JPEG gibi formatlardaki faturalardan metin okuma (OCR) ve akıllı veri çıkarma.\n*   **🧠 Akıllı Veri Çıkarma:** Kritik fatura bilgilerini otomatik olarak tanımlar ve çıkarır:\n    *   Fatura Numarası\n    *   Fatura Tarihi\n    *   Satıcı VKN/TCKN ve Ünvan\n    *   Alıcı VKN/TCKN ve Ünvan (varsa)\n    *   KDV Matrahı, Oranı, Tutarı\n    *   Genel Toplam\n*   **✔️ Arka Plan Veri Doğrulama:** Çıkarılan temel veriler üzerinde otomatik format (tarih, VKN/TCKN) ve matematiksel tutarlılık (Matrah + KDV ≈ Toplam) kontrolleri.\n*   **📊 Excel'e Aktarım:** Başarıyla işlenen ve doğrulanan verileri (ana alanlar) yapılandırılmış `.xlsx` dosyası olarak kolayca dışa aktarın.\n*   **🖥️ Temel Sonuç Görüntüleme Arayüzü:** Kullanıcı dostu web arayüzünde yüklenen faturaların listesi ve AI/XML tarafından çıkarılan verilerin **görüntülenmesi**.\n*   **☁️ Yerel Web Erişimi:** Flask ile çalışan yerel sunucu üzerinden herhangi bir modern web tarayıcısı ile erişim.\n*   **🔐 Güvenli API Anahtarı Yönetimi:** Google Gemini API anahtarı, `.env` dosyası aracılığıyla **güvenli bir şekilde backend'de** yönetilir.\n\n## Nasıl Çalışır?\n\n1.  **Kurulum ve Çalıştırma:** Projeyi yerel makinenize kurun ve `flask run` ile backend sunucusunu başlatın (Detaylar için 'Kurulum ve Kullanım' bölümüne bakın).\n2.  **Yükleme:** Fatura dosyanızı (XML, PDF, PNG, JPG vb.) Fatrocu web arayüzüne (`http://127.0.0.1:5000`) sürükleyip bırakın veya seçin.\n3.  **Akıllı İşleme (Backend):**\n    *   Dosya tipi kontrol edilir (`mimetypes` kullanılır). XML ise doğrudan `lxml` ile ayrıştırılır.\n    *   PDF/Resim ise güvenli bir şekilde backend'e kaydedilir ve Gemini API'sine gönderilir.\n    *   Gemini metin okuma (OCR) ve yapılandırılmış veri çıkarma işlemlerini gerçekleştirir.\n    *   Otomatik veri doğrulama kuralları uygulanır.\n    *   İşlem sonucu (başarılı veya hatalı) JSON olarak kaydedilir.\n4.  **Sonuç Görüntüleme (Frontend):** İşlem sonucu (çıkarılan veriler veya hata mesajı) kullanıcı arayüzünde gösterilir.\n5.  **Aktarım:** Başarılı işlenen faturalar için \"Excel'e Aktar\" butonu ile `.xlsx` dosyası indirilir.\n\n## Teknoloji Mimarisi\n\n*   **Backend:** Python 3.x, Flask\n*   **AI Model:** Google Gemini `gemini-2.5-pro-experimental` (via Google AI API)\n*   **Frontend:** HTML5, CSS3, JavaScript (Vanilla JS)\n*   **Veri İşleme:** Pandas, openpyxl (Excel için), lxml (XML için)\n*   **Dosya Tipi Tespiti:** mimetypes (Python standard library)\n*   **API İletişimi:** Google AI Python SDK\n\n## Gereksinimler\n\n*   **Python:** Sürüm 3.8 veya üzeri önerilir.\n*   **Pip:** Python paket yöneticisi.\n*   **Google Gemini API Anahtarı:** PDF/Resim formatındaki faturaları işleyebilmek için gereklidir.\n    *   [Google AI Studio](https://aistudio.google.com/app/apikey) üzerinden **ücretsiz** bir anahtar edinebilirsiniz.\n    *   Ücretsiz katman, (`gemini-2.5-pro-experimental` vb.) gibi belirli modeller için geçerlidir ve kullanım limitleri vardır. (Kullanmak istediğiniz modelin kota durumunu kontrol edin).\n    *   API anahtarı, proje kurulumunda `.env` dosyasına eklenecektir.\n\n## Kurulum ve Kullanım (Yerel Makine)\n\n1.  **Projeyi Klonlayın/İndirin:**\n    ```bash\n    git clone https://github.com/Nec0ti/Fatrocu.git\n    cd Fatrocu\n    ```\n2.  **Backend Klasörüne Gidin:**\n    ```bash\n    cd backend\n    ```\n3.  **Sanal Ortam Oluşturun ve Aktive Edin:**\n    *   Windows:\n        ```bash\n        python -m venv venv\n        .\\venv\\Scripts\\activate\n        ```\n    *   macOS/Linux:\n        ```bash\n        python3 -m venv venv\n        source venv/bin/activate\n        ```\n4.  **Gerekli Kütüphaneleri Kurun:**\n    ```bash\n    pip install -r requirements.txt\n    ```\n5.  **API Anahtarını Ayarlayın:**\n    *   `backend` klasörü içinde `.env` adında bir dosya oluşturun.\n    *   Dosyanın içine aşağıdaki satırı ekleyin ve `YOUR_GEMINI_API_KEY_HERE` kısmını kendi API anahtarınızla değiştirin:\n        ```\n        GOOGLE_API_KEY=\"YOUR_GEMINI_API_KEY_HERE\"\n        ```\n6.  **Uygulamayı Başlatın:**\n    ```bash\n    flask run\n    ```\n    *   Uygulama genellikle `http://127.0.0.1:5000` adresinde çalışmaya başlayacaktır.\n7.  **Kullanım:**\n    *   Web tarayıcınızdan `http://127.0.0.1:5000` adresini açın.\n    *   \"Dosya Seç veya Sürükle Bırak\" alanını kullanarak fatura dosyalarınızı (XML, PDF, PNG, JPG vb.) yükleyin.\n    *   \"Yükle ve İşle\" butonuna tıklayın.\n    *   \"İşlem Sonucu\" bölümünde çıkarılan verileri veya hata mesajını görün.\n    *   \"Son İşlenen Dosyalar\" listesinden önceki işlemlerin sonuçlarını tekrar görebilir veya Excel olarak indirebilirsiniz.\n\n## Doğruluk Üzerine Not\n\nFatrocu v2, e-Faturalar için çok yüksek doğruluk hedefler. PDF/Resim formatları için kullanılan Gemini modelleri güçlü olsa da, fatura kalitesi, düzeni ve karmaşıklığına bağlı olarak %100 doğruluk garanti edilemez. Bu sürümün amacı, veri girişini **önemli ölçüde hızlandırmak** ve kullanıcıya **hızlı bir kontrol** imkanı sunmaktır. Gelecek sürümlerde eklenecek etkileşimli doğrulama arayüzü bu süreci daha da iyileştirecektir.\n\n## Yol Haritası / Gelecek Planları\n\n*   [ ] **Etkileşimli Doğrulama Arayüzü:** Kullanıcının arayüz üzerinden çıkarılan verileri **düzenlemesi ve onaylaması**. (Yüksek Öncelik)\n*   [ ] **Fatura Görseli Entegrasyonu:** Doğrulama ekranında fatura görselini (PDF/Resim) gösterme.\n*   [ ] **Gelişmiş Veri Çıkarma:** Ürün/Hizmet kalemleri, para birimi, ödeme vadesi, IBAN vb.\n*   [ ] **ÖKC Fişi Optimizasyonu:** Yazar kasa fişleri için özel analiz.\n*   [ ] **Fatura Görseli Üzerinde İşaretleme:** AI'ın bulduğu verinin faturadaki yerini vurgulama.\n*   [ ] **Model/Prompt İyileştirme:** Farklı fatura tipleri için Gemini prompt optimizasyonu.\n*   [ ] **Kullanıcı Tanımlı Alanlar:** Özel alan çıkarma talepleri.\n*   [ ] **Toplu İşlem (Batch Processing):** Çoklu dosya yükleme ve işleme.\n*   [ ] **Muhasebe Yazılımı Entegrasyonları:** API veya dosya formatı ile entegrasyon.\n*   [ ] **Kullanıcı Yönetimi / Veritabanı:** İşlenen faturaları ve ayarları kalıcı olarak saklama.\n\n## Katkıda Bulunma\n\nKatkılarınız memnuniyetle karşılanır! Projeyi geliştirmeye yardımcı olmak isterseniz, lütfen repoyu forklayın, değişikliklerinizi yapın ve bir pull request gönderin. Hataları bildirmek veya yeni özellikler önermek için [GitHub Issues](https://github.com/Nec0ti/Fatrocu/issues) sayfasını kullanmaktan çekinmeyin.\n\n## Lisans\n\nBu proje MIT Lisansı altında lisanslanmıştır - detaylar için `LICENSE` dosyasına bakın.\n\n---\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnec0ti%2Ffatrocu","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fnec0ti%2Ffatrocu","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnec0ti%2Ffatrocu/lists"}