🧾 Fatura

GİB e-Arşiv portal üzerinde; e-Fatura, e-SMM, e-Müstahsil oluşturma, düzenleme, imzalama vb. işlemlere olanak tanır.

Başlarken

Bu paket GİB'e tabi şahıs şirketi ya da şirket hesapları ile çalışır ve bu kişiler adına resmi fatura/makbuz oluşturur. GİB e-Arşiv portala tarayıcınızdan giriş yapmak için aşağıdaki linkleri kullanabilirsiniz;

• https://earsivportaltest.efatura.gov.tr/login.jsp
• https://earsivportal.efatura.gov.tr/intragiris.html

Kullanıcı kodu ve parola bilgilerini muhasebecinizden ya da GİB - İnteraktif Vergi Dairesi'nden edinebilirsiniz.

Fatih Kadir Akın'ın fatura.js paketinden faydalanılmıştır.

Kurulum

🛠️ Paketi composer ile projenize dahil edin;

🎉 Özellikler

• Api Bağlantısı
• Belge Oluşturma
  • e-Fatura
  • Satış
  • İade
  • Tevkifat
  • İstisna
  • Özel Matrah
  • e-Müstahsil
  • e-SMM
• Belge Güncelleme
• Belge Silme
• Belge İmzalama
  • Sms ile İmzalama
• Belge Listeleme
  • Düzenlenen Belgeler
  • Adıma Düzenlenen Belgeler
  • Belge Detayları
  • HTML Çıktı Alma
  • Belge İndirme Adresi
  • Belgeyi Sunucuya Kaydetme
• Vergiler
  • Vergi Ekleme
  • Vergi Listesi
  • Vergiler ve Toplamlar
• İptal/İtiraz Talepleri
• GİB Profil Bilgileri
• Mükellef Sorgulama
• Birimler

🔗Api Bağlantısı

Test Kullanıcısı

e-Arşiv portal üzerinden yeni bir test kullanıcısı oluşturmak ve token almak için;

Token ve kullanıcı bilgilerine ulaşmak için;

Gerçek Kullanıcı

e-Arşiv portal kullanıcı bilgilerinizi setCredentials metodunu kullanarak tanımlayabilirsiniz.

Bilgilerinizi doğrudan login metoduyla da tanımlayabilirsiniz.

Not: Token değerini herhangi bir yerde kullanmanız gerekmeyecek.

Oturum Sonlandırma

Herhangi bir kısıtlama veya oturum sorunu yaşamamak adına, işlemlerden sonra oturumu sonlandırabilir ya da setToken yöntemini kullanabilirsiniz.

Bir kez token aldıktan sonra token süresi sonlanana kadar login/logout olmadan da işlem yapılabilir.

Token süresi sonlandığında yeni token alınmalıdır.

📃Belge Oluşturma

Model kullanırken named arguments (adlandırılmış değişkenler) veya dizilerle çalışabilirsiniz. Oluşturulan belgeler, daha sonra imzalanmak üzere e-Arşiv portalda taslaklara kaydedilir.

faturaUuid ve belgeNumarasi belirtildiyse; portalda bu bilgilerle eşleşen belge güncellenir, diğer durumda portal üzerinde yeni bir belge oluşturulur. Belge Güncelleme sayfasını kontrol edin.

e-Fatura

Kütüphaneyi kullanarak aşağıdaki fatura türleri ile çalışabilirsiniz;

• Satış
• İade
• Tevkifat
• İstisna
• Özel Matrah

Döviz cinsinden fatura düzenlemek için modelde paraBirimi ve dovizKuru parametreleri kullanılmalıdır.

Belge oluştururken model kullanmak istemiyorsanız /examples klasörü altındaki createInvoiceWithoutModel.php dosyasındaki örneği inceleyebilirsiniz.

Satış

Satış faturası oluşturabilmek için, faturaTipi InvoiceType::Satis gönderilmelidir.

İade

İade faturası oluşturabilmek için, faturaTipi InvoiceType::Iade gönderilmeli; iadeye konu faturalar addReturnItem metoduyla faturaya eklenmelidir.

Tevkifat

Tevkifatlı fatura oluşturabilmek için, faturaTipi InvoiceType::Tevkifat gönderilmelidir.

Tevkifat kodlarına ait liste çıktısını almak için;

İstisna

İstisna fatura oluşturabilmek için, faturaTipi InvoiceType::Istisna gönderilmeli; 12 haneli gtip kodu faturaya ait ürün/hizmet eklenirken belirtilebilir.

Özel Matrah

Özel matrah fatura oluşturabilmek için, faturaTipi InvoiceType::OzelMatrah gönderilmeli; faturaya ait ürün/hizmet eklenirken ozelMatrahNedeni ve ozelMatrahTutari belirtilmelidir.

Özel matrah nedenlerine ait liste çıktısını almak için;

e-Müstahsil

Müstahsil makbuzu ile çalışılacaksa, Gib sınıfı başlatılırken DocumentType::ProducerReceipt başlangıç parametresi olarak gönderilmelidir.

e-SMM

Serbest meslek makbuzu ile çalışılacaksa, Gib sınıfı başlatılırken DocumentType::SelfEmployedReceipt başlangıç parametresi olarak gönderilmelidir.

Not Ekleme

Belgelere not eklemek için, setNote metodunu kullanabilirsiniz. Not eklenmemiş belgelere otomatik olarak, "yazı ile toplam ödenecek tutar" not olarak eklenir.

💸Vergi Ekleme

Belgedeki hizmetlere addTax metodunu kullanarak vergi ekleyebilirsiniz. Vergiler doğrudan belgeye eklenemez, yalnızca öğe modeli üzerinden her bir öğeye ayrı ayrı eklenebilir.

Vergi Listesi

Vergi listesine ulaşmak için cases statik metodunu kullanabilirsiniz;

Vergiler ve Toplamlar

Belgeye eklenen öğelere ulaşmak için getItems metodunu kullanabilirsiniz;

Belge Günceleme

Fatura oluşturulurken faturaUuid ve belgeNumarasi belirtildiyse; portalda bu bilgilerle eşleşen belge güncellenir, diğer durumda portal üzerinde yeni bir belge oluşturulur.

Belgeleri güncellemek için bir diğer yöntem; önce düzenlenecek belgeyi getirmek ve daha sonra düzenlenecek alanlarla birlikte güncelleme isteği göndermektir. Örneğin oluşturulan faturada yalnızca alıcı bilgilerini güncellemek isteyebilirsiniz;

addItem metodunun kullanılması durumunda içe aktarılmış öğeler silinecektir.

Belge Silme

Taslak belgeleri silmek için deleteDraft metodu kullanılmalıdır. Metod bir dizi kabul eder. Gönderilecek dizi içerisinde silinecek belge veya belgelere ait uuid bilgisi bulunması gerekir.

Aşağıdaki örnek, bilinen bir tarih aralığındaki tüm taslak belgeleri siler.

Belirsiz bir tarih aralığındaki taslak belgeler silinmek isteniyorsa;

Belge İmzalama

☢️ Belge imzalama, faturanın/makbuzun kesilmesi işlemidir ve vergi sisteminde mali veri oluşturur. Belge imzalandıktan sonra üzerinde değişiklik yapılamaz ve silinemez. Bu nedenle dikkatli kullanınız.

📲SMS ile İmzalama

SMS doğrulama işlemleri test hesaplarıyla gerçekleştirilemez.

SMS doğrulamasına başlamak için startSmsVerification yöntemi kullanılmalıdır. Yöntem portalda kayıtlı gsm numarasına bir doğrulama kodu gönderecek ve imzalama işlemi için daha sonra kullanacağınız bir ID döndürecektir.

Doğrulama işlemini tamamlamak için kullanılacak completeSmsVerification yöntemine; SMS ile gelen doğrulama kodu, SMS doğrulaması başlatılırken alınan Operasyon ID'si ve onaylanacak belgelere ait UUID değerlerinin bulunduğu bir dizi olmak üzere 3 farklı parametre gönderilmelidir.

Belge Listeleme

Oluşturulan taslak belgeleri, tarih aralığı belirtmek koşuluyla farklı şekillerde listeleyebilirsiniz.

Düzenlenen Belgeler

Bu örnek, aşağıdaki şu diziyi döndürecektir;

Adıma Düzenlenen Belgeler

Bu metod artık stabil çalışmıyor gibi görünüyor. Belli bir tarihten sonra adınıza düzenlenmiş belgeler bir süredir GİB Portal'dan alınamıyor.

İki tarih arasındaki gelen faturaları (GİB portaldaki adıyla Adıma Düzenlenen Belgeler) listeler.

Belge Detayları

Portal üzerinde kayıtlı belge detaylarına ulaşmak için;

Oluşturulan Son Belge

Portal üzerinde en son oluşturulan belgeye ait detaylara ulaşmak için;

HTML Çıktı Alma

Portal üzerinde kayıtlı belgeye ait HTML çıktıya ulaşmak için;

Belge İndirme Adresi

Belge indirme adresine yalnızca token oluşturduğunuz IP adresi erişebilir. Token sunucuda oluşturulduysa, belgeyi indirmeye yarayan bu link yalnızca sunucuda çalışacaktır. Farklı bir IP adresinden erişilmesi durumunda Oturum geçersiz, token yok hatası dönecektir. Belgeyi sunucunuza indirmek için saveToDisk metodonu kullanabilirsiniz.

Portal üzerinde kayıtlı belgeye ait indirme adresine ulaşmak için;

Belgeyi Sunucuya Kaydetme

Portal üzerinde kayıtlı belgeyi sunucuya kaydetmek için;

Belge Filtreleme

🔍 Kayıtları zincirleme metodlar kullanarak kolayca filtreleyebilirsiniz.

Alıcı adında mehmet ifadesi geçen imzalanmamış kayıtlar döner.

Kullanılabilir Filtreleme Yöntemleri

İptal/İtiraz Talepleri

GİB Portalda kayıtlı İptal/İtiraz taleplerine ulaşmak için getRequests metodunu kullanabilirsiniz. Sonuç bir dizi şeklinde döner.

Yeni iptal/itiraz talebi oluşturmak için objectionRequest ve cancellationRequest metodlarını kullanabilirsiniz.

GİB Profil Bilgileri

Kayıtlı kullanıcı bilgilerine ulaşmak için getUserData metodunu kullanabilirsiniz. Sonuç bir dizi şeklinde döner.

Önce portaldan profil bilgilerini okuyup daha sonra modele import ederek yalnızca belirli alanları güncelleyebilirsiniz.

Mükellef Sorgulama

TC Kimlik Numarası ya da Vergi Numarası ile mükellef sorgulamaya yarar. Fatura oluşturma aşamasında vergi numarasının doğruluğunu sorgulamak için kullanılabilir. Test ortamında sonuç boş döner.

Bu örnek, aşağıdaki şu diziyi döndürecektir;

Birimler

https://www.php.net/manual/en/language.types.enumerations.php sayfasını kontrol edin.

Ürün/Hizmet Birimleri

Vergi Birimleri

Para Birimleri

📧İletişim

İletişim için [email protected] adresine e-posta gönderin.

☢️ Bu paket vergiye tabi olan mali veri oluşturur. Bu paket nedeniyle oluşabilecek sorunlardan bu paket sorumlu tutulamaz, risk kullanana aittir. Riskli görüyorsanız kullanmayınız.