Creart-Official-Invoice-Module Proje Dokümanı

Creart-Official-Invoice-Module, hamzadenizyilmaz hesabında yayımlanan açık kaynak proje deposudur.

Proje özeti

Creart-Official-Invoice-Module, hamzadenizyilmaz hesabında yayımlanan açık kaynak proje deposudur.

Alan	GitHub bilgisi
Depo	hamzadenizyilmaz/Creart-Official-Invoice-Module
Ana dil	Belirtilmemiş
Varsayılan dal	`main`
Lisans	AGPL-3.0
Oluşturulma	2026-02-17
Son kaynak güncellemesi	2026-02-17

Proje README belgesi

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

Ürün Özeti
Kapsam ve Sınırlar
Mimari Genel Bakış
Yıllık Lisans Modeli
Teknik Gereksinimler
Kurulum
İlk Konfigürasyon
Provider Konfigürasyonu
PDF Üretim Kuralları
Lisans Güvenlik Modeli
Hook ve İş Akışı Matrisi
Veritabanı Şeması
Admin Arayüzü
API/Lisans Sunucusu Beklentisi
Test ve Kalite
Hata Senaryoları ve Troubleshooting
Production Checklist
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

Modül klasörünü WHMCS kökünde aşağıya yerleştirin:
- modules/addons/resmifaturamodulu/
Bağımlılıkları kurun:

composer install --no-dev

WHMCS Admin panelde Addon Modules bölümünden modülü aktive edin.
Aktivasyonda lisans anahtarını girin.
Provider ayarlarını kaydedin.
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ı

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

17) Production Checklist

Lisans anahtarı ve doğrulama endpoint’i aktif.
Provider credentials production bilgileri girildi.
Firma bilgileri ve yasal metin tamamlandı.
PDF klasör izinleri doğrulandı.
Cron job günlük çalışıyor.
İlk test faturası local_only ile üretildi.
Provider’a test gönderimi başarılı.
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.

Kaynak ve doğrulama

Bu sayfadaki depo tarihleri ve teknik metadata GitHub public API kaydından alınmıştır. İçeriğin otoritatif ve en güncel sürümü GitHub deposudur.