Bu kütüphane, PHP aracılığıyla eArşiv üzerinden fatura oluşturma, düzenleme, imzalama gibi işlemleri yapabilmenize olanak sağlar. Tamamen ücretsizdir ve aktif olarak geliştirilmektedir.
Kendi verileriniz ile test etmek için:
https://earsivportal.efatura.gov.tr/intragiris.html
Test hesaplarıyla test etmek için:
https://earsivportaltest.efatura.gov.tr/login.jsp
Paket Kurulumu:
composer require erenn44/earsiv
Eğer bir sorun yaşıyorsanız veya proje hakkında bir sorunuz varsa lütfen buradan bir kayıt oluşturun, yaşadığınız sorunu hep birlikte çözelim.
- eArşiv oturumunu açma ve sonlandırma.
- Fatura oluşturma.
- İki tarih arası fatura sorgulama.
- Menü listesini görüntüleme.
- Fatura detaylarını görüntüleme.
- Türkçe veya İngilizce seçenekleriyle fatura modeli oluşturma.
- Faturayı HTML olarak çıktı alma.
- Faturanın indirme adresini alma.
- Faturayı iptal etme.
- Varolan bir faturayı sorgulama.
- Kullanıcı bilgilerini çekme. (Şirketinizin temel bilgileri)
- Kullanıcı bilgilerini güncelleme.
- SMS ile Fatura doğrulama ve onaylama.
- Faturayı PDF olarak çıktı alma.
Giriş
Bir client oluşturarak genel yapıyı projemize dahil ediyoruz.
use erenn44\eArsiv\InvoiceManager;
$client = new InvoiceManager();Giriş bilgilerinizi chain fonksiyonlarla tanımlayabiliyorsunuz, bu production için geçerlidir.
// Production environment
$client->setUsername("XXX")->setPassword("YYY");
// VEYA
$client->setCredentials("XXX", "YYY");Alttaki kullanım ile test modunda çalıştırabilir, firmanızın bilgileri olmadan otomatik test girişi yapabilirsiniz. Bu aşamadan sonraki tüm işlemleriniz test hesabıyla gerçekleşir.
// Test Environment
$client->setDebugMode(true)->setTestCredentials();Ayrıca bilgilerinizi görüntülemek isterseniz:
$client->getCredentials();Bilgilerimizi tanımladıktan sonra giriş yapıp token almak içinse: (Bu işlem olmadan diğer adımlara geçilemez)
$client->connect();Faturalandırma
Faturaların listelenmesi aşağıdaki şekilde yapılıyor:
// Tüm faturaları listele
$client->getInvoicesFromAPI("01/01/2020", "08/02/2020");Yeni bir fatura oluşturmak isterseniz, bir kaç seçeneğiniz mevcut, kullanım alışkanlığı olarak ingilizceye alışmışlar için iki farklı yöntem var, ilk aşamada Türkçe'den gidelim.
Örnek olarak şu şekilde bir fatura oluşturabiliriz:
$fatura_detaylari = [
"belgeNumarasi" => "", // Zorunlu değil
"faturaTarihi" => "08/02/2020",
"saat" => "09:07:48",
"paraBirimi" => "TRY",
"dovzTLkur" => "0",
"faturaTipi" => "SATIS",
"hangiTip" => "5000/30000",
"vknTckn" => "11111111111",
"aliciUnvan" => "FURKAN KADIOGLU",
"aliciAdi" => "FURKAN",
"aliciSoyadi" => "KADIOGLU",
"binaAdi" => "", // Zorunlu değil
"binaNo" => "", // Zorunlu değil
"kapiNo" => "", // Zorunlu değil
"kasabaKoy" => "", // Zorunlu değil
"vergiDairesi" => "MALTEPE",
"ulke" => "Türkiye",
"bulvarcaddesokak" => "DENEME SK. DENEME MAH.",
"mahalleSemtIlce" => "", // Zorunlu değil
"sehir" => " ",
"postaKodu" => "", // Zorunlu değil
"tel" => "", // Zorunlu değil
"fax" => "", // Zorunlu değil
"eposta" => "", // Zorunlu değil
"websitesi" => "", // Zorunlu değil
"iadeTable" => [], // Zorunlu değil
"ozelMatrahTutari" => "0", // Zorunlu değil
"ozelMatrahOrani" => 0, // Zorunlu değil
"ozelMatrahVergiTutari" => "0", // Zorunlu değil
"vergiCesidi" => " ", // Zorunlu değil
"malHizmetTable" => [],
"tip" => "İskonto",
"matrah" => 100,
"malhizmetToplamTutari" => 100,
"toplamIskonto" => "0",
"hesaplanankdv" => 18,
"vergilerToplami" => 18,
"vergilerDahilToplamTutar" => 118,
"odenecekTutar" => 118,
"not" => "xxx", // Zorunlu değil
"siparisNumarasi" => "", // Zorunlu değil
"siparisTarihi" => "", // Zorunlu değil
"irsaliyeNumarasi" => "", // Zorunlu değil
"irsaliyeTarihi" => "", // Zorunlu değil
"fisNo" => "", // Zorunlu değil
"fisTarihi" => "", // Zorunlu değil
"fisSaati" => " ", // Zorunlu değil
"fisTipi" => " ", // Zorunlu değil
"zRaporNo" => "", // Zorunlu değil
"okcSeriNo" => "" // Zorunlu değil
];Faturayı oluşturmak yetmez tabi, ürün veya hizmet de girmek lazım, oda şu şekilde oluyor.
$fatura_detaylari["malHizmetTable"][] = [
"malHizmet" => "Yazılım Geliştirme",
"miktar" => 28,
"birim" => "DAY",
"birimFiyat" => "3",
"fiyat" => "84",
"iskontoOrani" => 0,
"iskontoTutari" => "0",
"iskontoNedeni" => "",
"malHizmetTutari" => "99",
"kdvOrani" => 18,
"vergiOrani" => 0,
"kdvTutari" => "15.12",
"vergininKdvTutari" => "0",
"ozelMatrahTutari" => "0", //zorunlu
];Değişkenler Türkçe olduğundan dolayı mapWithTurkishKeys fonksiyonunu kullanıyoruz.
use furkankadioglu\eFatura\Models\Invoice;
$inv = new Invoice();
$inv->mapWithTurkishKeys($fatura_detaylari); // Key yapısı türkçe 🇹🇷
// VEYA
$inv->mapWithEnglishKeys($invoice_details); // Key yapısı ingilizce 🇺🇸Sonrasında bunu InvoiceManager'a kayıt etmemiz gerekiyor. Oda bu şekilde:
$client->setInvoice($inv);Sonrasında da taslak oluşturuyoruz:
$client->createDraftBasicInvoice();Adımıza Düzenlenen Faturaları Sorgulamak için
$client->getInvoicesMeFromAPI("01/01/2021", "31/12/2022");Kullanıcı Bilgileri
Bu kısım firmanızın eArşiv'de kayıtlı olan bilgileridir. Bu bilgileri alabilir ve güncelleyebilirsiniz.
👉Aynı zamanda bu bilgileri almak, fatura oluştururken ihtiyaç duyacağınız bir çok veri ihtiyacınızı da karşılar.
$userInformations = $client->getUserInformationsData();Bu işlem size bir adet UserInformations sınıfı döndürür. Bu sınıftaki verilerinizin tamamını set ve get metodlarıyla değiştirebilirsiniz:
// Sadece vknTckn değiştirilemez.
$userInformations = $userInformations->setUnvan("FRKN Yazılım")->setApartmanNo("4");
$apartmanNo = $userInformations->getApartmanNo(); // 4Ayrıca bu sınıfın verilerini toplu olarak almak isterseniz aşağıdaki kullanımı uygulayabilirsiniz, aynı fonksiyon Invoice sınıfı içinde geçerli:
$userInformations->export(); // Array olarak tüm değişkenleri döndürür.Aynı zamanda bu sınıfı kendiniz oluşturabilir ve array olarak veriyi sağlayabilirsiniz. Sonrasında da şu şekilde sunucuya göndeririz:
$client->setUserInformations($userInformations); // Manager'a tanımla.
$client->sendUserInformationsData(); // Sunucuya gönder.(İndirme/Onaylama/HTML Çıktısını Alma/İptal vb.)
HTML çıktısını almak için:
$client->getInvoiceHTML();PDF çıktısını almak için:
$client->getInvoicePDF();İndirme linkini almak için:
$client->getDownloadURL();Faturayı iptal etmek için:
$client->cancelInvoice();SMS doğrulaması yapmak için:
$client->sendSMSVerification($telefon); // Operasyon id döndürür.SMS doğrulamasını onaylamak ve onaylanacak faturaları göndermek için:
$client->verifySMSCode($kod, $operasyonId);Kişi veya kurumun bilgilerini çekmek için:
$client->getCompanyInfo($TCKimlikNoVeyaVergiNo);Çıkış yapıp, oturumu kapatmak için:
$client->logOutFromAPI();Varolan bir faturayı sorgulamak için:
$oldInvoice = new Invoice();
$oldInvoice->setUuid("e8277cfa-4ac9-11ea-a5b5-acde48001122");
$client->setInvoice($oldInvoice)->getInvoiceFromAPI();
// {"faturaUuid":"8a4423bc-4aca-11ea-8c30-acde48001122","faturaTarihi":"09\/02\/2020"...Kısaltılmış Kullanımlar:
Uzun gelmiş olabilir. 😂 Gayet doğal, chain methodlar ile hayatımızı kolaylaştırıyoruz. Tek satırda işimizi halledelim:
$client->setDebugMode(true) // Test urlsine geçtik
->setTestCredentials() // Test bilgilerini aldık
->connect() // Bilgilerle birlikte sunucuya bağlanıp token aldık.
->setInvoice($inv) // Faturamızı sınıfa tanımladık (Invoice sınıfı kullanılmalı)
->createDraftBasicInvoice() // Taslak faturamızı oluşturduk
->getDownloadURL(); // İndirme adresini aldık
// https://earsivportaltest.efatura.gov.tr/earsiv-services/download?token=b8b6c261c511a9b2757279c0111b538a2f02d98ae2df6205448d002687cab8cf74ce04d187bf0c6ce839dee40a6a8aad003aa6d5946ba02a0942ceb10bde327f&ettn=85933f42-4ab1-11ea-922e-acde48001122&belgeTip=FATURA&onayDurumu=Onaylandı&cmd=downloadResourceSabit Değişkenler:
Bir çok farklı veri tipi olduğundan ve önceden bilinmediğinde sorunlar çıkabileceğini düşünerek, bazı ihtiyaç duyulan sabit seçenekler de mevcut. Tüm değişken isimleri eArşiv de görünenlerle birebir yapıldı. Örnekten bazılarını görebilirsiniz:
use furkankadioglu\eFatura\Models\Country;
use furkankadioglu\eFatura\Models\CurrencyType;
use furkankadioglu\eFatura\Models\InvoiceType;
use furkankadioglu\eFatura\Models\UnitType;
$gunBirim = UnitType::GUN; // DAY
$turkLirasi = CurrencyType::TURK_LIRASI; // TRY
$satisFaturasi = InvoiceType::SATIS; // SATIŞ
$gurcistanUlkesi = Country::GURCISTAN; // GürcistanAnahtar Yapısını Değiştirme:
use furkankadioglu\eFatura\Models\Invoice;
$inv = new Invoice();
$invoice_details = [
"uuid" => $uuid,
"documentNumber" => $documentNumber,
"date" => $date,
"time" => $time,
"currency" => $currency,
"currencyRate" => $currencyRate,
"invoiceType" => $invoiceType,
"taxOrIdentityNumber" => $taxOrIdentityNumber,
"invoiceAcceptorTitle" => $invoiceAcceptorTitle,
"invoiceAcceptorName" => $invoiceAcceptorName,
"invoiceAcceptorLastName" => $invoiceAcceptorLastName,
"buildingName" => $buildingName,
"buildingNumber" => $buildingNumber,
"doorNumber" => $doorNumber,
"town" => $town,
"taxAdministration" => $taxAdministration,
"country" => $country,
"avenueStreet" => $avenueStreet,
"district" => $district,
"city" => $city,
"postNumber" => $postNumber,
"telephoneNumber" => $telephoneNumber,
"faxNumber" => $faxNumber,
"email" => $email,
"website" => $website,
"refundTable" => $refundTable,
"specialBaseAmount" => $specialBaseAmount,
"specialBasePercent" => $specialBasePercent,
"specialBaseTaxAmount" => $specialBaseTaxAmount,
"taxType" => $taxType,
"itemOrServiceList" => $itemOrServiceList,
"type" => $type,
"base" => $base,
"itemOrServiceTotalPrice" => $itemOrServiceTotalPrice,
"totalDiscount" => $totalDiscount,
"calculatedVAT" => $calculatedVAT,
"taxTotalPrice" => $taxTotalPrice,
"includedTaxesTotalPrice" => $includedTaxesTotalPrice,
"paymentPrice" => $paymentPrice,
"note" => $note,
"orderNumber" => $orderNumber,
"orderData" => $orderData,
"waybillNumber" => $waybillNumber,
"waybillDate" => $waybillDate,
"receiptNumber" => $receiptNumber,
"voucherDate" => $voucherDate,
"voucherTime" => $voucherTime,
"voucherType" => $voucherType,
"zReportNumber" => $zReportNumber,
"okcSerialNumber" => $okcSerialNumber
];
$inv->mapWithEnglishKeys($invoice_details); // Key yapısı ingilizceBu şekilde de map edebileceğiniz gibi ayrıyetten getter/setter methodları da mevcut, istediğiniz her veriyi düzenleyebilirsiniz:
$inv->setUuid("Buraya kendi fatura idniz")
->setCountry("Türkiye")
->getCurrencyRate(); // TRYToplu veri alımı ve çıkartımı:
Fatura verisinin değişken değerlerini toplu olarak ekleyebilir veya çıkartabiliriz, şöyle:
$inv = new Invoice($data); // data arrayinden keylere göre tüm verileri alır.
$inv->export(); // tüm verileri çıkartır.Testleri Çalıştırma:
composer test
Daha Fazla Örnek:
Uyarı
🚨 Bu paket vergiye tabi olan belge oluşturur, hiç bir sorumluluk kabul edilmez ve ne yaptığınızdan emin olana kadar debugMode açık şekilde test verileriyle işlem yapmanız önerilir.
Ayrıca