aenzenith / laravel-luca-efatura
Laravel client for the TÜRMOB Luca e-Fatura web services (InvoiceService, AddressBookService, ProductService): e-Fatura, e-Arşiv, e-İrsaliye and e-SMM over SOAP, with a schema-driven envelope builder, multi-company scoping, tenant guards and a test fake. Laravel 12 and 13, PHP 8.2+.
Requires
- php: ^8.2
- ext-dom: *
- ext-libxml: *
- ext-xmlwriter: *
- illuminate/console: ^12.0|^13.0
- illuminate/contracts: ^12.0|^13.0
- illuminate/http: ^12.0|^13.0
- illuminate/support: ^12.0|^13.0
- nesbot/carbon: ^2.72|^3.0
- psr/log: ^2.0|^3.0
Requires (Dev)
- larastan/larastan: ^3.0
- laravel/pint: ^1.18
- orchestra/testbench: ^10.0|^11.0
- pestphp/pest: ^3.0|^4.0|^5.0
Suggests
None
Provides
None
Conflicts
None
Replaces
None
README
TÜRMOB Luca e-Fatura entegratör web servisleri için Laravel istemcisi. Luca'nın servisleri İşNet NetteFatura altyapısı üzerinde çalışan WCF SOAP servisleridir. Paket üç servisi de kapsar: InvoiceService, AddressBookService ve ProductService.
- e-Fatura, e-Arşiv, e-İrsaliye, irsaliye yanıtı ve e-SMM gönderimi (UBL-TR XML ya da Luca'nın alan modeli), arama, PDF, iptal, kabul/red, e-posta, e-Arşiv raporu
- GİB mükellef sorgusu ve alias listesi, il/ilçe/vergi dairesi kodları, adres defteri, ürün kataloğu
- Kontör bakiyesi, portal kullanıcısı doğrulama, alt bayi listesi
- Belgeyi ProfileID'sine göre doğru operasyona yönlendiren
documents()->sendUbl()
| Gereksinim | Sürüm |
|---|---|
| PHP | 8.2+ (ext-dom, ext-xmlwriter) |
| Laravel | 12, 13 |
Kurulum
composer require aenzenith/laravel-luca-efatura php artisan vendor:publish --tag=luca-config
LUCA_ENVIRONMENT=test # test | production LUCA_COMPANY_TAX_CODE=1234567801 # varsayılan firma VKN/TCKN (çok firmalı kullanımda boş bırakılabilir)
Luca'da kullanıcı adı ve parola yoktur: servisler isteği gönderen sunucunun IP adresiyle kimlik doğrular. Kayıtlı olmayan IP'den gelen bağlantı kesilir ya da hiç kurulamaz. Kurulumdan sonra:
php artisan luca:check
Ayrıntı: IP erişimi ve bağlantı. Diğer komutlar:
luca:taxpayer {vkn} (mükellef ve alias sorgusu), luca:schema (canlı WSDL'den şema derleme).
Kullanım
use Aenzenith\LucaEFatura\Facades\Luca; // Alıcı e-Fatura mükellefi mi? $taxPayer = Luca::taxPayers()->find('1111111111'); // null ise e-Arşiv kesilir // UBL-TR belgeyi ProfileID'sine göre gönder (EARSIVFATURA, TEMELFATURA, TEMELIRSALIYE, EARSIVBELGE...) $sent = Luca::documents()->sendUbl($ubl); $sent->ettn; // belge UUID $sent->number; // fatura numarası // Doğrudan modül Luca::eArchive()->sendXml($ubl, sendMail: true); Luca::eInvoices()->sendXml($ubl, 'urn:mail:defaultpk@alici.com.tr'); // PDF, iptal, kabul/red $pdf = Luca::eArchive()->pdf($ettn); Luca::eArchive()->cancel($ettn, 'Hatalı tutar'); Luca::eInvoices()->reject($ettn, 'Sipariş iptal edildi'); // Çok firmalı: her çağrı açıkça bir firma adına Luca::company($shop->tax_code)->eArchive()->sendXml($ubl);
Her çağrı aynı hattan geçer ve aşağıdaki kontroller istek gönderilmeden önce yapılır:
- Firma kapsamı.
CompanyTaxCode/CompanyVendorNumberkapsamdaki firmadan doldurulur; başka firma yazan istekTenantMismatchExceptionile reddedilir. - Düzenleyen kontrolü. XML gönderimlerinde firma alanı yoktur; Luca belgeyi UBL'deki VKN adına keser. UBL'deki düzenleyen VKN/TCKN kapsamdaki firmayla eşleşmezse belge gönderilmez.
- Şema. Zarflar WCF veri sözleşmesinin sırası ve isim alanlarıyla kurulur. Sözleşmede olmayan alan
(ör.
VatRateyerineVATRate) Luca'da sessizce düşeceği için reddedilir. - Tekrar deneme. Okuma işlemleri bağlantı hatasında tekrar denenir; gönderim, iptal gibi yazma işlemleri asla tekrar denenmez.
- ETTN. Arama servisleri boş ETTN'i "filtre yok" sayıp firmanın ilk belgesini döndürür; geçersiz ETTN'le arama yapılmaz, dönen kaydın ETTN'i istenenle aynı değilse kayıt kullanılmaz.
- Sonuç. Yalnız
Result=Successbaşarıdır.Failed, SOAP fault, HTML hata sayfası, boş yanıt ve bağlantı hatası istisna fırlatır.
Test
use Aenzenith\LucaEFatura\Facades\Luca; use Aenzenith\LucaEFatura\Testing\FakeResponse; $fake = Luca::fake([ 'SendArchiveInvoiceXml' => ['ArchiveInvoices' => [['Ettn' => $ettn, 'ArchiveInvoiceNumber' => 'ABC2026000000001']]], 'GetTaxPayer' => FakeResponse::failure('Mükellef bulunamadı.'), ]); // ... $fake->assertSent('SendArchiveInvoiceXml');
Dokümantasyon
Ayrıntılı kılavuz docs/ altındadır.
Lisans
MIT