GitHub LinkedIn
Blog İletişim
Blog Projeler Dokümanlar Araçlar Hizmetler Dosyalar Linkler Hakkımda İletişim
Creart Official Invoice Module projesinin teknik kapsamını temsil eden görsel

Creart Official Invoice Module

Fatura süreçleri ve kurumsal uygulama entegrasyonları için geliştirilen açık kaynak modül deposu.

GitHub README GitHub'da aç ↗

Creart Resmi Fatura Modulü

WHMCS 8.10+ / 9.x için geliştirilmiş, Türkiye odaklı resmi fatura PDF üretimi ve muhasebe provider entegrasyonu sunan addon modül.

İçindekiler

  1. Ürün Özeti
  2. Kapsam ve Sınırlar
  3. Mimari Genel Bakış
  4. Yıllık Lisans Modeli
  5. Teknik Gereksinimler
  6. Kurulum
  7. İlk Konfigürasyon
  8. Provider Konfigürasyonu
  9. PDF Üretim Kuralları
  10. Lisans Güvenlik Modeli
  11. Hook ve İş Akışı Matrisi
  12. Veritabanı Şeması
  13. Admin Arayüzü
  14. API/Lisans Sunucusu Beklentisi
  15. Test ve Kalite
  16. Hata Senaryoları ve Troubleshooting
  17. Production Checklist
  18. Sürümleme ve Destek

1) Ürün Özeti

ResmiFaturaModulu, WHMCS faturalarını resmi görünümlü PDF çıktısına dönüştürür ve fatura verisini seçili provider’a (Paraşüt/Logo/Mikro) aktarır.

Başlıca Yetkinlikler

  • TCPDF ile resmi fatura düzeni.
  • QR kod, kaşe/imza alanı, yasal metin bloğu.
  • Provider abstraction (FaturaProviderInterface) ile genişletilebilir mimari.
  • Gelişmiş lisans doğrulama (imza, fingerprint, şifreli cache).
  • Hook tabanlı otomasyon (fatura oluşumu, ödeme, günlük cron).

2) Kapsam ve Sınırlar

  • Bu modül doğrudan GİB API entegrasyonu içermez.
  • Akış, WHMCS veri modeli + seçili muhasebe provider API’leri üzerinden ilerler.
  • GİB tarafına direkt gönderim yerine “resmi formatlı PDF + provider entegrasyonu” odaklanır.

3) Mimari Genel Bakış

Katmanlar

  • Entry: resmifaturamodulu.php
  • Hooks: hooks.php
  • License: src/License/LicenseValidator.php
  • PDF: src/Pdf/InvoicePdfGenerator.php
  • Providers: src/Providers/*
  • Support: src/Support/*
  • Templates: templates/admin/*

Tasarım Prensipleri

  • strict_types=1
  • PSR-4 autoload
  • Interface + Factory tabanlı provider seçimi
  • Güvenlikte fail-closed yaklaşımı

4) Yıllık Lisans Modeli

Bu ürün yıllık lisans ile satılır.

  • Lisans süresi: 365 gün.
  • Lisans bağlama: domain + IP + instance_id + fingerprint.
  • Süre sonu: otomatik akışlar kısıtlanabilir, yenileme gerekir.
  • Yenileme kapsamı: sürüm güncellemeleri, güvenlik yamaları, teknik destek.
  • Lisans devri: satıcı onayı ile kontrollü.

Önerilen Ticari Politika

  • Ana lisans: 1 production domain.
  • Opsiyonel ek lisans: staging/dev domain.
  • Yenileme gecikmesi sonrası grace period: satıcı politikasına göre tanımlanabilir.

5) Teknik Gereksinimler

  • PHP 8.2+
  • IonCube Loader 14+
  • WHMCS 8.10+ / 9.x
  • Composer
  • OpenSSL eklentisi (AES-256-GCM için önerilir)
  • İnternet erişimi (lisans doğrulama ve provider API çağrıları için)

6) Kurulum

  1. Modül klasörünü WHMCS kökünde aşağıya yerleştirin:
    • modules/addons/resmifaturamodulu/
  2. Bağımlılıkları kurun:
composer install --no-dev
  1. WHMCS Admin panelde Addon Modules bölümünden modülü aktive edin.
  2. Aktivasyonda lisans anahtarını girin.
  3. Provider ayarlarını kaydedin.
  4. Gerekli client custom field’ları doğrulayın:
    • Vergi Dairesi
    • VKN/TCKN
    • Ticari Unvan

7) İlk Konfigürasyon

Admin ayar ekranındaki temel adımlar:

  • Aktif provider seçin: local_only | parasut | logo | mikro
  • Otomasyon bayraklarını belirleyin:
  • InvoiceCreated sonrası gönderim
  • InvoicePaid sonrası gönderim
  • Firma bilgilerini doldurun:
  • Ünvan, VKN, MERSIS, adres, telefon, e-posta, logo, IBAN
  • Yasal metni HTML olarak kaydedin

8) Provider Konfigürasyonu

Genel Parametreler

  • provider.api_url
  • provider.company_id
  • provider.client_id
  • provider.client_secret
  • provider.username
  • provider.password

Provider Seçenekleri

  • local_only: sadece yerel PDF üretimi, dış sistem gönderimi yok.
  • parasut: OAuth/token akışı + satış faturası gönderimi.
  • logo: token/basic auth tabanlı REST gönderimi.
  • mikro: token tabanlı JSON REST gönderimi.

Güvenlik

  • Hassas bilgiler settings tablosunda şifreli tutulur.
  • Provider credential’larını loglara düz metin yazmayın.

9) PDF Üretim Kuralları

src/Pdf/InvoicePdfGenerator.php aşağıdaki unsurları üretir:

  • A4 dikey sayfa
  • Türkçe karakter uyumlu font
  • Firma başlık bloğu
  • Alıcı bilgileri
  • Satır bazlı ürün/hizmet tablosu
  • KDV kırılımı ve toplamlar
  • Tutarın yazıyla karşılığı
  • Yasal metin alanı
  • Kaşe/imza boşlukları
  • QR kod
  • Trial watermark

Çıktı Dizini

  • Varsayılan: storage/pdfs/
  • Dosya adı örneği: invoice_123_20260218_001501.pdf

10) Lisans Güvenlik Modeli

LicenseValidator katmanı:

  • Request/response imza doğrulama (HMAC-SHA256)
  • nonce + timestamp replay koruması
  • Cihaz/kurulum fingerprint bağlama
  • Runtime bütünlük hash kontrolü
  • PBKDF2 ile anahtar türetme
  • AES-256-GCM ile şifreli cache
  • DB fallback (offline tolerans)

Lisans Geçersizse

  • Hook akışları işlevsel olarak durdurulur.
  • Admin tarafta uyarı gösterilir.
  • Olay loglanır.

11) Hook ve İş Akışı Matrisi

Uygulanan kritik hook’lar:

  • InvoiceCreated: PDF üret + opsiyonel provider push
  • InvoicePaid: opsiyonel tekrar push/senkron
  • AdminAreaPageInvoice: sidebar ve lisans uyarısı
  • DailyCronJob: lisans check + temizlik işleri
  • AfterCronJob: status sync için uygun nokta
  • AdminInvoicesControlsOutput: admin badge/aksiyon alanı
  • InvoiceCancelled, InvoiceRefunded, InvoiceDeleted: audit logging
  • AddInvoicePayment: ödeme hareket logu
  • ClientAdd, ClientEdit: müşteri veri değişimi takibi

12) Veritabanı Şeması

  • tbl_resmifatura_settings
  • tbl_resmifatura_logs
  • tbl_resmifatura_manuel
  • tbl_resmifatura_lisans

Migration dosyası:

  • database/migrations/20260217_create_tables.php

13) Admin Arayüzü

  • templates/admin/config.tpl
  • templates/admin/invoice_sidebar.tpl

Arayüz İşlevleri

  • Provider/Firma/Lisans/Yasal metin ayarları
  • Manuel ETTN ve resmi no girişi
  • Faturadan tek tık PDF üretimi
  • Provider’a manuel gönderim
  • Durum senkronlama

14) API/Lisans Sunucusu Beklentisi

Lisans endpoint’i şu yapıyı desteklemelidir:

Request:

  • payload:
  • key, ip, domain, instance_id, whmcs_version, timestamp, nonce, fingerprint, integrity_hash
  • signature

Response:

  • payload:
  • valid, message, expiry, max_instances, allowed_ips, allowed_domains, timestamp, nonce, integrity_hash
  • signature

Not: Response imzası doğrulanamazsa lisans invalid kabul edilir.

15) Test ve Kalite

Test Komutları

composer test

Test Dosyaları

  • tests/LicenseValidatorTest.php
  • tests/ProviderFactoryTest.php
  • tests/InvoicePdfGeneratorTest.php

Öneri

  • CI’de en az PHP 8.2 + static analysis + unit test koşun.

16) Hata Senaryoları ve Troubleshooting

Sık Görülen Problemler

  • Lisans API timeout
  • Provider 401/403
  • Provider 429 rate limit
  • Geçersiz VKN/TCKN formatı
  • PDF yazma izni hatası
  • QR/merge sırasında kütüphane uyumsuzluğu

Hızlı Kontrol Adımları

  1. tbl_resmifatura_logs tablosunu kontrol edin.
  2. Lisans tarihini ve domain/IP eşleşmesini doğrulayın.
  3. storage/pdfs yazma izinlerini kontrol edin.
  4. Provider API URL ve credential’ları doğrulayın.
  5. Cron çalışmasını doğrulayın.

17) Production Checklist

  1. Lisans anahtarı ve doğrulama endpoint’i aktif.
  2. Provider credentials production bilgileri girildi.
  3. Firma bilgileri ve yasal metin tamamlandı.
  4. PDF klasör izinleri doğrulandı.
  5. Cron job günlük çalışıyor.
  6. İlk test faturası local_only ile üretildi.
  7. Provider’a test gönderimi başarılı.
  8. Log retention politikası belirlendi.

18) Sürümleme ve Destek

  • Sürüm: 1.2.0
  • Teknik notlar: IMPLEMENTATION_NOTES.md
  • Destek ve yıllık lisans yenileme: satış/destek kanalınız

Lisans ve Hukuki

Bu depodaki kod örnekleri proje gereksinimine göre düzenlenmiştir. Ticari kullanımda yıllık lisans koşulları sözleşme ile belirlenmelidir.

#rest-api #e-invoice #saas
GitHub Source