Search by

aenzenith / laravel-luca-efatura

aenzenith

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+.

Package info

github.com/aenzenith/laravel-luca-efatura

pkg:composer/aenzenith/laravel-luca-efatura

Statistics

Installs: 4

Dependents: 0

Suggesters: 0

Stars: 0

Open Issues: 0

v0.1.1 2026-11-16 10:01 UTC

This package is auto-updated.

Last update: 2026-11-16 10:08:27 UTC


README

Packagist Version PHP Version Laravel Tests License

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 / CompanyVendorNumber kapsamdaki firmadan doldurulur; başka firma yazan istek TenantMismatchException ile 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. VatRate yerine VATRate) 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=Success baş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