Sıkça Sorulan Sorular

İkisi de UBL Invoice belgesini kullanır. e-Fatura, GİB e-Fatura sistemine kayıtlı alıcıya GİB üzerinden iletilir; alıcı kayıtlı değilse e-Arşiv Fatura süreci değerlendirilir. Bu rehber e-Arşiv dışındaki 10 e-Fatura profilini kapsar. Ayrım için Temel Kavram bölümüne bakın.

Alıcının VKN/TCKN bilgisi GİB e-Fatura kullanıcı kaydıyla ve fatura tarihiyle birlikte kontrol edilir. Kayıt bulunamazsa veya mükellefiyet başlangıcı fatura tarihinden sonraysa e-Fatura oluşturulamaz. Entegratör bunu belgeyi göndermeden önce mükellef sorgusuyla doğrulamalıdır.

Profil; işlemin ticari niteliğine ve alıcıya göre seçilir. Genel tek taraflı akışta TEMELFATURA, alıcı kabul/red yanıtı beklenen ticari akışta TICARIFATURA; ihracat, kamu, enerji, HKS, İDİS ve diğer özel işlemlerde kendi profilleri kullanılır. Kesin seçim için giden fatura profil karar ağacını izleyin.

TEMELFATURA tek taraflı teslim akışıdır; alıcının uygulama yanıtı beklenmez. TICARIFATURA iki taraflıdır ve alıcı kabul veya red kararı verir. Belge alanları benzer olsa da sonuç akışı aynı değildir.

Evet. Alıcı kamu mükellefiyse geçerli Türkiye IBAN'ı, hesap para birimi ve gerekli taraf bilgileri kontrol edilir. Bu nedenle yalnızca profil adına bakarak kamu alanları boş bırakılamaz. Ayrıntı için Kamu senaryosuna bakın.

Belge oluşturma, imzalama, GİB'e iletim, alıcıya teslim ve gerekiyorsa kabul/red birbirini izleyen ayrı aşamalardır. İlk başarılı cevap yalnızca belgenin platform tarafından kabul edildiğini gösterebilir; nihai sonuç ETTN ile durum sorgulanarak izlenir. Geçiş sırası Giden Fatura Akışı, enumların tek tek anlamı Belge Durum Kodları bölümündedir.

Hayır. TICARIFATURA, YOLCUBERABERFATURA ve IHRACAT iki taraflı yanıt akışına girer. Diğer profiller teslim sonucuna göre otomatik ilerler; gereksiz kabul/red yanıtı gönderilmemelidir.

Hayır. Red, yanıt bekleyen gelen faturaya verilen uygulama yanıtıdır. İptal, desteklenen profil ve durumdaki bir belgenin GİB Portal'daki iptal sonucunun platforma yansıtılmasıdır. İtiraz ise ayrı bir belge/tarih/açıklama ilişkisiyle kaydedilen itiraz sürecidir. Kullanılacak yol belgenin yönüne, profiline ve mevcut durumuna göre belirlenir.

Doğrudan iptal işaretleme yalnızca TemelFatura ve IlacTibbiCihaz profillerinde desteklenir. Diğer profillerde red veya itiraz gibi uygulanabilir iş akışı değerlendirilmelidir. Yön bazlı ön koşullar için Giden Fatura İptal ve İtiraz Sorumluluğu bölümüne bakın.

Güncelleme, belge kesinleşmeden önceki düzeltmeler içindir. GİB'e gönderilmiş veya nihai duruma ulaşmış belge üzerinde alan değişikliği yapılmaz; mevcut duruma uygun red, iptal, itiraz veya yeni belge süreci değerlendirilir.

UBL XML faturanın yapılandırılmış elektronik belgesidir. PDF veya HTML görünüm, bu belgenin insan tarafından okunabilen sunumudur. Arşivleme sürecinde yalnızca PDF'e dayanılmamalı; UBL/XML de ETTN ve fatura numarasıyla ilişkilendirilmelidir.

Hayır. ETTN/UUID belgenin sistemler arası tekil teknik kimliğidir; fatura numarası ise ticari belge numarasıdır. Entegrasyon ve durum takibinde ETTN, muhasebe ve kullanıcı gösteriminde çoğunlukla fatura numarası kullanılır; ikisi birlikte saklanmalıdır.

Evet. Giden ve gelen faturalar için ayrı PDF, HTML ve XML/UBL çıktı endpointleri vardır. Giden belge seçenekleri Sorgulama ve Belge Çıktıları, gelen belge seçenekleri XML, PDF, HTML ve Belge Paketi bölümlerinde açıklanır.

Önerilen sıra: token alma, alıcı mükellefiyetini ve etiketini doğrulama, profile uygun request hazırlama, önizleme, oluşturma, ETTN'yi saklama, durum takibi, gelen faturaları alma ve ERP mutabakatı. Tam akış Uçtan Uca Entegrasyon Yol Haritası bölümündedir.

POST /api/Account/Token çağrısından alınan token, sonraki isteklerin VbtAuthorization header'ında gönderilir. Token veya parola loglara, hata mesajlarına ve örnek payload'lara yazılmamalıdır.

Fatura oluşturulmadan önce doğrulanmalıdır. Mükellefiyet yalnızca VKN/TCKN varlığı değildir; fatura tarihi mükellefiyet başlangıcıyla uyumlu olmalı, gönderilen ReceiverIdentifier ilgili mükellefin kayıtlı etiketlerinden biri olmalıdır.

ProfileId iş senaryosunu, InvoiceTypeCode belgenin satış, iade, istisna, tevkifat gibi türünü belirler. Her profil bütün türleri kabul etmez. Geçerli kombinasyonlar ve profile özgü zorunlu alanlar Alan Zorunluluk Matrisi içinde yer alır.

Platformun modeli UBL'ye dönüştürmesini istiyorsanız AddOutgoingInvoice; düz XML sözleşmesini kullanıyorsanız AddOutgoingInvoiceByXml; kendi ürettiğiniz geçerli UBL Invoice belgesini gönderecekseniz AddOutgoingInvoiceByUbl kullanılır. Aynı belge için bu yollar birlikte kullanılmaz.

Belge kaydedilmeden önce, gerçek request gövdesinin doğrulama ve görsel sonucunu kontrol etmek için kullanılmalıdır. Preview başarısı oluşturma çağrısının yerini almaz; yalnızca aynı verinin üretime gitmeden önce sorunlarını yakalamaya yardımcı olur.

Tek başına başarılı olduğu anlamına gelmez. Response gövdesindeki HasError, Errors[], ETTN ve işlem verileri birlikte değerlendirilmelidir. Ayrıca oluşturma başarısı nihai GİB/alıcı sonucu değildir; belge durumu sonradan sorgulanır.

Önce sonucu belirsiz kabul edin. InvoiceExternalId ve varsa ETTN ile mevcut kaydı sorgulamadan yeni ETTN üreterek tekrar göndermek mükerrer belge riski yaratır. Güvenli tekrar yaklaşımı Güvenli Gönderim ve Tekilleştirme bölümündedir.

InvoiceExternalId yerel ERP kaydıyla korelasyon sağlar; ETTN platform, GİB ve alıcı arasındaki teknik belge kimliğidir. Timeout, tekrar, destek ve mutabakat işlemlerinde iki kimliğin eşleştirilmiş olması belgenin güvenle bulunmasını sağlar.

Hayır. Otomatik gönderim kullanılan sözleşmelerde oluşturma sonrasındaki imzalama ve gönderim platform tarafından ilerler. Bu endpoint yalnızca ayrıca kararlaştırılmış manuel gönderim akışında kullanılmalıdır; aynı ETTN için kör biçimde tekrarlanmamalıdır.

GetOutgoingInvoicesStatus çağrısına EttnList gönderilir. Her satır bağımsız değerlendirilir; bir belgenin başarılı olması listedeki diğerlerinin de başarılı olduğu anlamına gelmez. Durumların sırası ve güvenli tekrar davranışı Giden Fatura Akışı sayfasında yer alır.

Teknik durum imzalama, gönderim, GİB ve alıcı aşamalarını ayrıntılı gösterir. *StatusForUser ise ekranda ve iş akışında kullanılacak özet anlamı verir. Otomasyon teknik alanla, kullanıcı mesajı özet alanla yürütülmelidir.

GetIncomingInvoiceList veya ayrıntı gerekiyorsa GetDetailedIncomingInvoiceList filtreli ve sayfalanmış biçimde kullanılır. Her ETTN yerel sistemde tekilleştirilir; aynı fatura sonraki sorguda yeniden geldiğinde ikinci bir muhasebe kaydı oluşturulmaz.

IsErpProcessed=true yalnızca yerel ERP kaydı ve ona bağlı işlemler başarıyla tamamlandıktan sonra gönderilmelidir. Yerel transaction yarıda kaldıysa işlenmiş işareti verilmemeli; aksi halde belge sonraki aktarım denemelerinden düşebilir.

ApproveOrRejectIncomingInvoice request'inde ForwardForApproveOrReject alanı kabul için ForwardForApprove, red için ForwardForReject olur. Ettn zorunludur; açıklama gerektiğinde ApplicationResponseNote kullanılır. Çağrı sonrasında sonuç durum endpointinden izlenir.

TICARIFATURA, YOLCUBERABERFATURA ve IHRACAT iki taraflı yanıta gider. TEMELFATURA, KAMU, HKS, ENERJI, ILAC_TIBBICIHAZ, YATIRIMTESVIK ve IDIS için gereksiz uygulama yanıtı üretilmez.

ERP alanları için JSON detay modeli, kullanıcı gösterimi için HTML/PDF, elektronik belgenin aslı için UBL/XML kullanılır. Yasal ve teknik iz açısından UBL/XML ETTN ile saklanmalı; PDF tek başına asıl elektronik belge kabul edilmemelidir.

Evet; üç alanın da UBL Invoice içinde ayrı opsiyonel elemanı vardır. Ancak AddOutgoingInvoice JSON isteğinden platformun ürettiği UBL'ye şu anda aktarılmazlar. Hazır UBL gönderiminde kullanılabilirler. Ayrıntı giden fatura mapping tablosunda ayrı satırlarda gösterilir.

Miktar × birim fiyat, satır tutarıyla; satırların toplamı LegalMonetaryTotal.LineExtensionAmount ile; vergi hariç tutar + vergi toplamı, vergi dahil tutarla uyumlu olmalıdır. İskonto, artırım ve tevkifat varsa kendi matrah ve oranları da aynı para biriminde dengelenmelidir.

Bazı profil, alan ve GİB şema kontrolleri ortak SCHEME kodunu kullanır. Bu nedenle yalnızca koda göre switch/case yapmak yeterli değildir; ErrorMessage ve mümkünse ilgili alan bağlamı birlikte değerlendirilmelidir. Hata katmanları Teknik Referans sayfasında ayrılmıştır.

IHRACAT profilinde teslimat adresi, INCOTERMS bilgisi ve her ilgili kalemde 12 haneli sayısal GTİP kodu gerekir. Ayrıca ihracat alıcısı ve taraf kimlikleri profile uygun düzenlenmelidir. Tam liste İhracat senaryosundadır.

HKS'de her kalemde 19 karakterli KUNYENO; İDİS'te SE- + 7 rakam biçiminde sevkiyat no ve kalemlerde ETIKETNO; Yatırım Teşvikte YTBNO şemalı 6 haneli belge numarası, belge tarihi ve uygun sınıflandırma kodu beklenir.

Belge kesinleşmemiş ve güncellenebilir durumdaysa UpdateOutgoingInvoice veya karşılık gelen UBL/XML güncelleme yolu kullanılır. GİB'e iletilmiş ya da nihai sonuçlanmış belge doğrudan değiştirilmez; iş durumuna uygun yeni belge, red, iptal veya itiraz süreci seçilir.

İptal request'i dış sistem referansı, ETTN veya fatura numarasıyla belgeyi tanımlar; itiraz request'i ETTN/UUID ile itiraz belgesi tarihi, numarası, türü ve açıklamasını taşır. Belge bulunamazsa işlem reddedilir; yön ve profil kısıtları ayrıca uygulanır.

Kullanılan her profil için başarılı ve hatalı request; mükellef/etiket kontrolü; timeout sonrası mükerrerlik koruması ve giden durum takibi Giden Fatura Canlıya Geçiş Kontrolü ile; gelen fatura tekilleştirme, kabul/red, XML/PDF arşivleme ve ERP mutabakatı ise Gelen Fatura Canlıya Geçiş Kontrolü ile doğrulanmalıdır.

Endpoint, zaman, süre, HTTP sonucu, ETTN, fatura numarası, dış referans ve hata kodu izlenebilir olmalıdır. Token, parola, kişisel kimlik bilgileri, banka bilgileri ve tam belge içeriği gereksiz yere loglanmamalı; ihtiyaç varsa maskeleme ve erişim kontrolü uygulanmalıdır.