fatihtuzlu/qnbfinansbankapi

QNB Finansbank E-Fatura ve E-Arşiv PHP Api

dev-master 2022-07-29 10:44 UTC

Requires

• php: ^8.1

MIT

• Fatih TUZLU

• php
• api
• finansbank
• efatura
• qnb
• qnb finansbank api

README

E-Fatura / E-Arşiv
QNB Finansbank

QNB Finansbank E-Fatura ve E-Arşiv PHP Api

QNB Finansbank web servisleri için PHP ile yazılmış olan bu kütüphane ile E-Arşiv, E-Fatura bildirim işlemlerini yapabilirsiniz.

Bu paket katkıda bulunmak için forklanıp düzenlenmiştir.

Dokümantasyon (QNB FinansBank)

Dokümantasyon dosyalarına ulaşmak için tıklayınız.

Kurulum

 composer require fatihtuzlu/qnbfinansbankapi

Projenizde Kullanma

    <?php     
    include('vendor/autoload.php');

Desteklenen Yöntemler

- E-Fatura

• setEFatura() : E-Fatura bildirme işlemi yapabilirsiniz.
• getFaturaNo() : Portaldaki en son gönderilmiş fatura numaranıza göre sonraki fatura numarasını üretir.
• getEfaturaKullanicisi() : İlgili kişinin vergi numarasından E-Fatura mükellefi olup olmadığı bilgisini getirir.
• gidenBelgeDurumSorgula() : Giden faturalarınızı durumunu sorgulayabilirsiniz..
• gidenBelgeleriListele() : Gönderilmiş faturalarınızı listeleyebilirsiniz.
• gelenBelgeleriListele() : Gelen faturalarınızı listeleyebilirsiniz.

- E-Arşiv

• setEArsiv() : E-Arşiv bildirme işlemi yapabilirsiniz.
• getFaturaNo() : Portaldaki en son gönderilmiş fatura numaranıza göre sonraki fatura numarasını üretir.
• getFaturaSorgula() : Fatura detay görüntüleme servisidir. Faturanın PDF/HTML bilgisi ve detayları döner.
• callFaturaIptalEt() : Fatura iptal etme servisidir.

Bildirilecek Datanın Hazırlanması (UBL)

- Başlangıç datasının hazırlanması

E-Fatura ve E-Arşiv için ortak data hazılarması gerekmektedir. Aşağıdaki kodda görülen şekilde başlangıç datası oluşturulur ve ardından eklemeler yapılarak son data çıktısı alınacatır.Bu Alınan data daha sonrasında ister E-Arşiv istersenizde E-Faturaya gönderebileceksiniz.

    <?php     
    
    $data = new \EFINANS\Component\data();
    
     /* otomaik benzersiz UUID oluşturur. */
    $uuid=$data->getUuid();
    
    $veri = array(
        "ID" => "",
        "ProfileID" => "",
        "UUID" => $uuid,
        "IssueDate" => "",
        "IssueTime" => "",
    );
    
    /* hazırlanan başlangıç datasını set ediyoruz */
    $data->setStartData($veri);

Parameters:

- Not Bilgilerinin Eklenmesi

Her Bir Notu set ediyoruz. Notlar için dokümanı inceleyiniz.

    <?php     
    
    $veri = array(
            "ID" => 1, /* not benzersiz id si */
            "Value" => "", /* not tu buraya yazınız */
    );
    $data->setAddNote($veri);

Örnek:

    // e faturada zorunluluk yoktur. e arşiv için zorunlu olduğundan aşağıdaki notu eklemeniz yeterlidir.
    <?php     
    
    $veri = array(
            "ID" => 1,
            "Value" => "Gönderim Şekli: ELEKTRONIK",
    );
    $data->setAddNote($veri);

Parameters:

- Satıcı ve Alıcı Bilgilerinin Eklenmesi

Aynı bu set işlemini 'Customer' içinde alıcı bilgilerini yazıp yapmalı ve aşağıdaki 'Supplier' yazan yeri değiştirip set etmelisiniz.

    <?php     
    
      $veri = array(
        "Party" => array(
            "WebsiteURI" => "",
            "PartyIdentificationID" => "",
            "PartyName" => "",
            "Telephone" => "",
            "Telefax" => "",
            "ElectronicMail" => "",
            "PartyTaxSchemeName" => "",
        ),
        "PostalAddress" => array(
            "StreetName" => "",
            "BuildingNumber" => "",
            "CitySubdivisionName" => "",
            "CityName" => "",
            "PostalZone" => "",
            "CountryName" => "Türkiye",
        ),
    );    
    $data->setSupplierCustomerParty('Supplier', $veri);

Parameters:

- Satıcı ve Alıcı Personel Bilgilerinin Eklenmesi

'Customer' için mutlaka set edin çünkü TC kimlik no olduğunda zorunludur. Supplier için zorunlu değil ama girebilirsiniz

    <?php     
    
       $veri = array(
          "FirstName" => "",
          "FamilyName" => "",
       );
              
       $data->setPerson('Customer', $veri);

Parameters:

- Ödeme Koşulları Girilmesi

Bilgi notu şeklinde girilemsi zorunlu değildir.

    <?php     
    
        $veri = array(
           "Note" => "Ziraat Bankası",
           "PaymentDueDate" => "2020-07-30",
       );
       $data->setPaymentTerms($veri);

Parameters:

- Fatura Satırlarının Girilmesi

Bu adım da her satır için bu işlemi tekrarlamanız veya bir döngü içerisinde tüm fatura satırlarınızı set etmeniz gerekmektedir.

    <?php     
            
    $veri = array(
        "ID" => "", 
        "InvoicedQuantity" => "",
        "LineExtensionAmount" => "",
        "BaseAmount" => 0,
        "TaxAmount" => 0,
        "TaxSubtotal" => array(
            0 => array(
                "TaxableAmount" => 0,
                "TaxAmount" => 0,
                "Percent" => 0,
                "TaxSchemeName" => "KDV",
                "TaxSchemeTaxTypeCode" => "0015",
            ), 
            1 => array(
                "TaxableAmount" => 0,
                "TaxAmount" => 0,
                "Percent" => 0,
                "TaxSchemeName" => "Özel İletişim Vergisi",
                "TaxSchemeTaxTypeCode" => "4080",
            ),
        ),
        "ItemName" => "",
        "PriceAmount" => 0,
    );
    
    $data->setInvoiceLine($veri);

Parameters:

- Datanın Son Halinin Alınması

Bu adım da fatura satırlarından otomatik olarak parasal toplamların ve vergisel toplamların heaplanıp, E-Arşiv ve E-Fatura ya gönderileck datanın son halinin, xml öncesi array datasının alıp bir değişkene atıyoruz ve artık bildirim aşamasına geçebiliriz.

    <?php  
       
    $qnb_data = $data->setTotals()->getData();

Servis Bağlantı İşlemleri

Web servislerine bağlantı için TEST veya CANLI ortam username ve password bilgilerini tanımlıyoruz. Bu bilgiler qnbfinansbank tarafından alınır. Email atıp bilgileri alabilirsiniz.

    <?php  
    
    $config = new \EFINANS\Config\config();
    
    $options=$config->setUsername("CANLI_VEYA_TEST_USERNAME")
    ->setpassword("CANLI_VEYA_TEST_USERNAME")
    ->setvergiTcKimlikNo("CANLI_VEYA_TEST_VERGI_KIMLIKNO")
    ->setUrl("CANLI_VEYA_TEST_URL")
    ->getConfig();

Parameters:

Test Url

• E-Arşiv : https://earsivtest.efinans.com.tr/earsiv/ws/EarsivWebService?wsdl
• E-Fatura : https://erpefaturatest.cs.com.tr:8443/efatura/ws/connectorService?wsdl

E-Fatura İşlemleri

E-Faturaya bildirim işlemlerini yapabilmek için class ı çağırıyoruz ve set işlemlerine başlıyoruz.

    <?php  
    
    $efatura = new \EFINANS\Libraries\efatura();
    
    $belgeNo=uniqid();
    
    $return= $efatura->setConfig($options)
    ->setStart()
    ->setBelgeNo($belgeNo)
    ->setData($qnb_data)
    ->setEFatura();
    
    print $return->belgeOid; /* e faturadan bildirim sonrası dönen key */

REQUEST Parameters:

RESPONSE Parameters:

E-Arşiv İşlemleri

E-Arşiv bildirim işlemlerini yapabilmek için class ı çağırıyoruz ve set işlemlerine başlıyoruz.

    <?php  
    
    $earsiv = new \EFINANS\Libraries\earsiv();
    
    $return= $earsiv->setConfig($options)
    ->setStart()
    ->setSube("DFLT")
    ->setKasa("DFLT")
    ->setData($qnb_data)
    ->setEArsiv();    

    print '<pre>'; /* düzgün çıktı görseli için */
    print_r($return);

REQUEST Parameters:

RESPONSE Parameters:

E-Fatura ve E-Arşiv Ek Methodlar

E-Fatura veya E-Arşiv için ihtiyaca göre ek methodlar kullanabilirsiniz.

- E-Fatura

• getFaturaNo() : Portaldaki en son gönderilmiş fatura numaranıza göre sonraki fatura numarasını üretir.

E-Fatura Numarası üretmek için getFaturaNo() Methodu ile geriye dönen değeri $ID değişkenine alıp başlangıç datasına gönderdiğimizde otomatik değil bizim gönderdiğimiz fatura No yu kabul eder.

    <?php      
    
     $efatura = new \EFINANS\Libraries\efatura();
                
     $ID= $efatura->setConfig($options)
     ->setStart()
     ->getFaturaNo("BASLANGIC_SERI_NO") ; 

Parameters:

• getEfaturaKullanicisi() : İlgili kişinin vergi numarasından E-Fatura mükellefi olup olmadığı bilgisini getirir.

Hazırladığımı datanın E-Fatura ya mı E-Arşiv emi gönderecileceğini tespit etmek için getEfaturaKullanicisi() methodu ile kontrol ediyoruz. Eğer (true veya 1) bir değer dönerse e fatura mükellefi demektir ve hazırladığımız datanın E-Fatura ya gönderileceği anlaşılmaktadır. Aksi durumda ise E-Arşive gönderebilirsiniz.

    <?php      
    
     $efatura = new \EFINANS\Libraries\efatura();
                
     $return= $efatura->setConfig($options)
     ->setStart()
     ->getEfaturaKullanicisi("VERGI_VEYA_TC_KIMLIK_NO") ; 

Parameters:

- E-Arşiv

• getFaturaNo() : En Son üretilen e arşiv fatura nosu her çalıştığında otomatik olarak counter artarak döner.

E-Arşiv Numarası üretmek için getFaturaNo() Methodu ile geriye dönen değeri $ID değişkenine alıp başlangıç datasına gönderdiğimizde otomatik değil bizim gönderdiğimiz fatura No yu kabul eder. E-Arşiv olduğu için her çalıştırıldığında yeni bir numara üretir.

    <?php      
    
    $earsiv = new \EFINANS\Libraries\earsiv();
                
     $ID= $earsiv->setConfig($options)
     ->setStart()
     ->setUuid($data->getUuid())
     ->getFaturaNo("BASLANGIC_SERI_NO");

Parameters:

Otomatik Bildirim İşlemleri (Hazırlanıyor..)

E-Fatura veya E-Arşiv gönderisinin otomatik bir şekilde tespit edilip tek bir class üzerinden göndermek siterseniz aşağıdaki yöntemi kullanabilirsiniz.

Destek

Bir hata bulduğunuzu düşünüyorsanız, lütfen GitHub issue tracker kullanarak bildirin, ya da daha iyisi, kütüphaneyi çatallayın ve bir çekme isteği gönderin.

License

MIT Lisansı (MIT). Daha fazla bilgi için lütfen License File bakın.