Yapay zekâ aracı için özet kart

Entegrasyon kodu üretecek bir modelin ilk okuyacağı yer burasıdır. Kılavuzun tamamını okumadan da doğru kod yazabilmek için gereken kurallar burada toplanmıştır.

Kimlik

• JSON: her istekte X-Api-Key: <anahtar> başlığı. · XML: her operasyonun ilk parametresi <userInfo Username="…" Password="<anahtar>"/>.
• Yalnız HTTPS. Anahtar ortama özgüdür (test ↔ canlı taşınmaz).

Yanıt zarfı (her iki kapıda da aynı)

• İş kuralı hataları HTTP 200 ile döner; IsSucceded=false ve Türkçe Message. HTTP kodunu değil, IsSucceded alanını kontrol edin.
• Alan adı IsSucceded'dir — "Succeeded" değil, tek "e" ile. Kod üretirken bu yazımı birebir kullanın.
• Asıl veri Value içindedir. IsSucceded=true, iş sonucunun olumlu olduğu anlamına gelmez: e-Arşiv iptalinde sonuç Value'dadır, toplu gönderimde her satırın kendi IsSucceded'i vardır.

Kimlik alanlarının adlandırma tuzağı

ETTN (UUID) ile belge numarası iki ayrı değerdir; kodunuzda iki ayrı alanda tutun (ör. ettn ve belgeNo). Tek bir invoiceId değişkeni kullanırsanız uçlar arasında sessizce yanlış değer taşırsınız.

Gönderim kuralları

• UBL-TR 1.2, imzasız gönderilir. cbc:ID (belge numarası) ve cbc:UUID (ETTN) boş bırakılır; ikisini de sistem üretir ve gönderdiğiniz değeri ezer.
• cbc:IssueDate çalışma anındaki sunucu tarihinden üretilmelidir; ileri tarihli ya da 7 günden eski olamaz (VUK 231/5). Örneklerdeki tarihleri koda sabit yazmayın — bkz. Sunucu Saati.
• Yalnız TRY. Yalnız SATIS, IADE, TEVKIFAT, TEVKIFATIADE, ISTISNA tipleri.
• Scenario=Automated önerilir; e-Fatura/e-Arşiv kararını sistem verir.
• XML kapısında <Invoice> elemanına UBL varsayılan ad alanını yazmayın; içerik cbc:/cac: önekleriyle gelir.

Base64 kuralı

• Dosya döndüren uçlarda (…InvoicePdf, …InvoiceView, …InvoiceData) Data base64'tür.
• Fatura detayı döndüren uçlarda InvoiceXml base64 değildir, ham XML metnidir (sürüm 1.1'de değişti).

Takip döngüsü

• StatusCode ile karar verin, Status metniyle değil. Üç kova: 1000 bitti-başarılı · 1200/2000 bitti-geçersiz · 10/1400 iptal · diğer her değer yolda, tekrar sorun.
• Tanımadığınız kodu "yolda" sayın; asla "başarısız" saymayın.
• Yolda olan belgeleri tek tek değil, InvoiceIds listesiyle toplu sorgulayın. 5–10 dakikada bir yeterlidir.
• Kabul / Red Yanıtı Durumu ucu ayrı bir durum kümesi kullanır (Waiting · Queued · Processing · SentToGib · Success · Error); orada başarı Success/1000'dir.

Sayfa boyutu

• Liste uçları: varsayılan 20, en fazla 1000. · UBL döndüren detay uçları: en fazla 5.
• PageIndex 0'dan başlar. Boş sayfa gelince durun.

Yazım tuzakları

IsSucceded (tek "e") · WaitingForAprovement (tek "p") · GetUserAliasses (çift "s"). Bunlar sunucudaki gerçek adlardır; "düzeltmeyin".

Mükerrer işlem koruması

• Gönderimde LocalDocumentId ile kendi belge referansınızı taşıyın ve ağ hatasında körlemesine tekrar göndermeyin — önce Giden Fatura Listesi ile belgenin oluşup oluşmadığına bakın.
• Gelen kutusunda ETTN'yi benzersiz anahtar yapın; alındı işaretlemesini kendi kaydınız yazıldıktan sonra atın. Ayrıntı: Ortamlar ve Adresler.

Muhasebeizleme · Entegrasyon API

Faturalarınızı kendi yazılımınızdan yönetin

Mi API ile e-Fatura ve e-Arşiv faturalarınızı gönderir, GİB'deki yolculuklarını izler, gelen faturalarınızı alır ve yanıtlarsınız. İster JSON ile, ister XML (SOAP) ile — aynı operasyonlar, aynı sonuçlar.

32 operasyon JSON + XML (SOAP 1.1) UBL-TR 1.2 Özel entegratör altyapısı Canlı deneme konsolu

Hızlı başlangıç → Fatura Gönder WSDL

Kılavuzun tamamı tek dosya Yapay zekâ aracınıza verin, entegrasyon kodunuzu o yazsın — operasyonlar, alanlar, örnekler ve hata mesajlarıyla birlikte. İçerik her indirişte bu sayfadan üretilir.

Kılavuzu indir (.md)

Neler yapabilirsiniz?

İki kapı, tek çekirdek

API iki biçimde hizmet verir. Hangisini seçerseniz seçin istek aynı iş kurallarıyla işlenir ve yanıtlar aynı alan adlarını taşır. Bu kılavuzda her operasyon tek sayfadır; JSON ile XML arasında istediğiniz an geçebilirsiniz.

Operasyon ve alan adları e-belge entegratörlerinde yaygın kullanılan sözleşmeyle uyumludur. Başka bir entegratörle çalışıyorsanız çağrılarınızın çoğunu yalnız adres ve kimlik bilgisini değiştirerek taşıyabilirsiniz.

Bu kılavuz nasıl kullanılır?

• Sol menü — başlangıç konuları ve 32 operasyon. Ctrl + K ile arayın.
• Orta alan — her operasyonun amacı, alanları, yanıtı, gerçek örnekleri, hata mesajları ve beş dilde kod örneği.
• Sağ konsol — anahtarınızı bir kez girin, formu doldurun ve isteği test ortamına gönderin. Yanıttaki belgeler (PDF, HTML, UBL) doğrudan konsolda açılır.
• Tek dosya — yukarıdaki Kılavuzu indir düğmesi kılavuzun tamamını tek bir Markdown dosyası olarak indirir. Dosyayı yapay zekâ aracınıza verip entegrasyon kodunuzu yazdırabilirsiniz; içerik her indirişte bu sayfanın güncel hâlinden üretilir, ayrı bir sürüm tutulmaz.

Hızlı Başlangıç

Dört adımda ilk faturanızı gönderin.

1. Test ortamına erişin

   Entegrasyonu önce test ortamında geliştirin: test.muhasebeizleme.com. Test hesabınız yoksa destek ekibimizden talep edin. Test ortamındaki belgelerin mali değeri yoktur.

2. API anahtarı üretin

   Portal'da Ayarlar menüsündeki API Key Ayarları ekranında Yeni API Key'e tıklayın; anahtara bir ad ve bitiş tarihi verin (varsayılan 3 yıl).

   Anahtar yalnız bir kez gösterilir. Hemen güvenli bir yere kaydedin; kaybederseniz silip yenisini üretin.
3. Bağlantıyı test edin

   Sağdaki konsola kullanıcı adınızı ve anahtarınızı yazıp Doğrula'ya basın — firmanızın adı görünürse hazırsınız. Aynı çağrı komut satırından:
4. İlk faturanızı gönderin

   Fatura Gönder sayfasında konsoldaki Örnek e-Arşiv faturası düğmesi, hesabınızın bilgileriyle doldurulmuş gönderilebilir bir UBL hazırlar. Gönderin; dönen InvoiceId (ETTN) ile durumunu sorgulayın, PDF'ini alın.

Canlıya geçiş

• Canlı Portal'da (muhasebeizleme.com) ayrı bir anahtar üretin — test anahtarı canlıda çalışmaz, canlı anahtarı testte çalışmaz.
• Adresi test.api.muhasebeizleme.com → api.muhasebeizleme.com olarak değiştirin.
• Hesabınızda API kanalında kullanılabilir bir belge serisi tanımlı olduğundan emin olun.
• Takip döngünüzün durum kodlarını doğru yorumladığını test ortamında sınayın.

Temel Kavramlar

e-Belgeye yeniyseniz önce bu sayfayı okuyun: entegrasyon sorunlarının çoğu buradaki kavramların karıştırılmasından çıkar.

ETTN ve belge numarası

Her e-belgenin iki kimliği vardır:

• ETTN (UUID) — 3f2b8c1e-7a4d-4e8b-9c0f-12ab34cd56ef gibi. Belgenin evrensel, benzersiz kimliğidir.
• Belge numarası — ABC2026000000123 gibi: 3 karakter seri + yıl + 9 hane sıra.

İkisini de biz üretir, Fatura Gönder yanıtında döneriz. Takipte ETTN'yi kullanın.

e-Fatura mı, e-Arşiv mi?

Alıcı GİB'e kayıtlı bir e-Fatura mükellefiyse belge e-Fatura olarak GİB üzerinden alıcının posta kutusuna gider. Değilse e-Arşiv olarak düzenlenir: alıcıya elektronik ortamda iletilir ve GİB'e günlük raporlanır. Fatura Gönder'de Scenario=Automated verirseniz bu kararı biz veririz; belgenin sonuçta hangi kanaldan gittiği yanıttaki InvoiceScenario alanında yazar.

Senaryo (ProfileID)

UBL'deki cbc:ProfileID: TEMELFATURA, TICARIFATURA (alıcı 8 gün içinde kabul/red yanıtı verebilir), IHRACAT, KAMU… e-Arşiv faturasında her zaman EARSIVFATURA'dır. Tam liste: Durum ve kod tabloları.

Fatura tipi (InvoiceTypeCode)

API ile gönderilebilen tipler: SATIS, IADE, TEVKIFAT, TEVKIFATIADE, ISTISNA. Diğer tipler (özel matrah, ihraç kayıtlı, SGK…) şimdilik Portal üzerinden düzenlenir.

Zarf

e-Faturalar GİB'e bir zarf içinde gider. Zarfın durum kodu (EnvelopeStatusCode) belgenin GİB tarafındaki yolculuğunu gösterir. e-Arşivde zarf yoktur.

Posta kutusu (PK) ve gönderici birim (GB)

Her e-Fatura mükellefinin GİB'de en az bir posta kutusu (faturaların geldiği adres, ör. urn:mail:defaultpk@…) ve bir gönderici birim (faturaların çıktığı adres) etiketi vardır. Alıcının etiketlerini Posta Kutusu Etiketleri ile sorgulayabilirsiniz.

Gelen / giden kutusu ve arşiv işareti

Giden kutusu kestiğiniz e-Fatura ve e-Arşiv faturaları, gelen kutusu size gelen e-Faturalardır. Arşiv işareti (IsArchived) "bu belgeyi aldım, işledim" bilgisidir ve gelen kutusunu mükerrersiz çekmenin anahtarıdır — bkz. Entegrasyon akışları.

Kontör

Başarıyla tamamlanan her belge ve her bildirim kontör tüketir. Bakiyenizi Kontör Bakiyesi ile izleyin; kontör yoksa yeni fatura kabul edilmez.

Ortamlar ve Adresler

Test ve canlı ortam birbirinden tamamen ayrıdır: ayrı adres, ayrı hesap, ayrı anahtar.

Teknik ayrıntılar

• Karakter kodlaması: UTF-8 — istek ve yanıt.
• Tarih ve saat: Türkiye saati (UTC+3). Adı …Utc ile biten alanlar da Türkiye saatidir.
• Zaman aşımı: belge içeriği uçları (PDF, HTML, UBL) yüzlerce KB dönebilir; istemci zaman aşımını en az 60 saniye tutun.
• Boyut sınırı: bir SOAP mesajı en fazla 50 MB olabilir.
• Çağrı yeri: API sunucudan sunucuya kullanım içindir; anahtarınızı tarayıcıda ya da mobil uygulamada çalışan koda gömmeyin.

İstek sıklığı

API'de yayımlanmış sabit bir çağrı sınırı yoktur; buna karşılık altyapıyı koruyan önlemler devrededir ve aşırı yüklenen bir hesabın istekleri geçici olarak yavaşlatılabilir. Aşağıdaki ölçüler normal bir entegrasyon için fazlasıyla yeterlidir:

• Durum takibi: yolda olan belgeleri 5–10 dakikada bir sorgulayın. Daha sık sorgulamak sonucu hızlandırmaz — GİB tarafındaki işlem süresi dakikalarla ölçülür.
• Toplu sorgulama: belge başına ayrı istek atmayın. Giden Belge Durumu ve Gelen Belge Durumu uçları InvoiceIds listesi alır; tek istekte yüzlerce belgeyi sorgulayabilirsiniz.
• Gelen kutusu: 15–30 dakikada bir çekmek yeterlidir.
• Eşzamanlılık: aynı hesap için aynı anda 4–5 açık istekten fazlasını hedeflemeyin; toplu işleri kuyruğa alıp sırayla işleyin.
• Geri çekilme: 5xx ya da zaman aşımı alırsanız hemen tekrar denemeyin. Artan bekleme (ör. 2, 4, 8, 16 saniye) uygulayın ve tekrar denemeyi sınırlayın.

Mükerrer işlem koruması

API'de istek başına bir tekrar-koruma (idempotency) anahtarı yoktur: aynı fatura iki kez gönderilirse iki ayrı belge oluşur ve ikisi de kontör tüketir. Koruma entegrasyon tarafında kurulur:

1. Kendi belge referansınızı taşıyın. Fatura Gönder'de LocalDocumentId alanına kendi kaydınızın kimliğini yazın (ör. ERP-000123). Bu değer saklanmaz, yanıtta size geri döner; toplu gönderimde hata alan satırı eşleştirmenizi sağlar.
2. Gönderim öncesi durumu kendinizde tutun. Kendi kaydınızı "gönderiliyor" olarak işaretleyin, yanıt dönünce ETTN ve belge numarasıyla "gönderildi" yapın.
3. Yanıtsız kalan istekte sorgulayın, tekrar göndermeyin. Giden Fatura Listesi'ni CreateStartDate + TargetTcknVkn (gerekirse InvoiceNumbers) süzgeciyle çağırıp belgenin oluşup oluşmadığına bakın. Oluşmuşsa ETTN'yi kaydınıza yazın; oluşmamışsa yeniden gönderin.
4. Gelen kutusunda ETTN'yi benzersiz anahtar yapın. Aynı belge ikinci kez düşerse veritabanı seviyesinde yakalanır.
5. Alındı işaretlemesini kayıttan sonra yapın. Alındı İşaretle çağrısını kendi kaydınız kalıcı olarak yazıldıktan sonra atın; aksi hâlde kayıt çökerse belge "alınmış" sayılır ve bir daha gelmez.

Kimlik Doğrulama

Tek kimlik bilgisi API anahtarıdır. Anahtar hangi hesaba aitse işlemler o hesap adına yapılır ve anahtar o hesabın tüm e-belge işlemlerine erişir.

JSON (REST)

Anahtarı her istekte X-Api-Key başlığında gönderin:

GET /integration/v1/testconnection HTTP/1.1
Host: test.api.muhasebeizleme.com
X-Api-Key: API_ANAHTARINIZ

XML (SOAP)

Her operasyonun ilk parametresi userInfo'dur; anahtar Password özniteliğine yazılır:

<TestConnection xmlns="http://tempuri.org/"><userInfo Username="KULLANICI_ADINIZ" Password="API_ANAHTARINIZ"/></TestConnection>

• Password — API anahtarınız. Kimliği yalnız anahtar belirler.
• Username — bilgi amaçlıdır; Portal kullanıcı adınızı yazabilirsiniz. Hesap Bilgisi yanıtında User/Name olarak geri döner.
• Öznitelik biçimi önerilir; eleman biçimi (<userInfo><Username>…</Username><Password>…</Password></userInfo>) de kabul edilir.

Kimlik hataları

{"IsSucceded": false, "Message": "Geçersiz, süresi dolmuş veya yetkisiz ApiKey.", "Value": null}

<s:Envelope xmlns:s="http://schemas.xmlsoap.org/soap/envelope/"><s:Body><s:Fault><faultcode>s:Client</faultcode><faultstring xml:lang="tr-TR">Geçersiz, süresi dolmuş veya yetkisiz ApiKey.</faultstring></s:Fault></s:Body></s:Envelope>

XML kapısında kimlik hatası bilinçli olarak Fault döner: doğrulanamayan istek uygulama katmanına hiç ulaşmaz. İstemcinizde SOAP istisnasını yakalayın.

Anahtar yönetimi

• Anahtar Portal'da API Key Ayarları ekranında üretilir ve yalnız bir kez gösterilir.
• Her anahtarın bir bitiş tarihi vardır; süresi dolan ya da silinen anahtar anında reddedilir.
• Her entegrasyona (ERP, e-ticaret sitesi…) ayrı anahtar üretin; birini silmek diğerini etkilemez.
• Anahtarın son kullanım zamanı ve IP adresi kaydedilir.
• Anahtarınızı belirli IP adresleriyle sınırlamak isterseniz destek ekibimizden talep edin.

JSON mu, XML mi?

İki kapı aynı operasyonları ve aynı iş kurallarını sunar; fark yalnız taşıma biçimindedir.

Hangisini seçmeli?

• Yeni bir entegrasyon → JSON. Her dilde birkaç satırla çağrılır.
• WSDL tabanlı mevcut bir entegrasyon (ERP, .NET "Hizmet Başvurusu Ekle", Java JAX-WS…) → XML. WSDL'den istemci üretip doğrudan çağırabilirsiniz.

SOAP zarfı

Tüm elemanlar http://tempuri.org/ ad alanındadır; operasyon elemanına xmlns="http://tempuri.org/" yazmanız yeterlidir. Öznitelikler ad alanı almaz.

<?xml version="1.0" encoding="utf-8"?><soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"><soap:Body><GetOutboxInvoiceList xmlns="http://tempuri.org/"><userInfo Username="KULLANICI_ADINIZ" Password="API_ANAHTARINIZ"/><query PageIndex="0" PageSize="20"><CreateStartDate>2026-09-01T00:00:00</CreateStartDate><IsArchived>false</IsArchived></query></GetOutboxInvoiceList></soap:Body></soap:Envelope>

• SOAP 1.1 kullanılır: Content-Type: text/xml; charset=utf-8 ve tırnak içinde SOAPAction başlığı zorunludur.
• Elemanları şemadaki sırayla yazın; boş bıraktığınız alanları hiç yazmayın.
• Operasyon parametresi olan diziler (invoiceIds) <string> elemanlarıyla; liste sorgusundaki süzgeç dizileri (InvoiceIds, InvoiceNumbers) ise sarmalayıcısız, tekrarlanan elemanlarla yazılır.
• Parametre adları büyük/küçük harfe duyarlıdır: vknTckn, invoiceId, isInbox…

Yanıt Zarfı ve HTTP Kodları

Her yanıt aynı zarfla gelir: işlem başarılı mı (IsSucceded), açıklama (Message) ve sonuç (Value).

{"IsSucceded": true, "Message": null, "Value": {"AccountId": 1024, "ServerTime": "2026-09-11T20:28:47+03:00"}}

<TestConnectionResult IsSucceded="true"><Value><AccountId>1024</AccountId><ServerTime>2026-09-11T20:28:47+03:00</ServerTime></Value></TestConnectionResult>

• IsSucceded yazımı bilinçlidir (sektörde yaygın sözleşmeyle uyum); alan adını bu hâliyle kullanın.
• İş kuralı hataları (belge bulunamadı, kontör yetersiz, geçersiz parametre…) HTTP 200 ile, IsSucceded=false ve Türkçe Message olarak döner.
• Value bir liste ise XML'de her eleman ayrı bir <Value> elemanıdır.
• Tek bir doğru/yanlış dönen işlemlerde XML'de Value bir özniteliktir: <IsEInvoiceUserResult IsSucceded="true" Value="true"/>.
• XML'de Message yalnız doluyken yazılır.

HTTP kodları

400 örneği

{"type": "about:blank", "title": "Geçersiz istek.", "status": 400, "detail": "Alan doğrulamalarını kontrol edin.", "instance": "/integration/v1/queryoutboxinvoicestatus", "correlationId": null, "errors": {"req": [""]}}

Durum ve Kod Tabloları

Belgenin nerede olduğunu Status (metin) ve StatusCode (sayı) söyler. İş mantığınızı StatusCode'a bağlayın.

Giden belge durumları

• e-Arşiv: belge imzalanıp denetimden geçtiği anda 1000 (Approved) olur — günlük raporun GİB'e gitmesini beklemez. e-Arşiv faturasının alıcıya iletilen şekli belgenin aslıdır ve GİB onayı gerektirmez; raporlama ayrı bir ödevdir, belgenin geçerliliğini değiştirmez. Aynısı e-SMM, e-MM, e-Adisyon ve e-Döviz için de geçerlidir. (1400'e düşen iptaller de günlük raporla bildirilir.)
• InternalCode iç işlem kodudur; destek taleplerinde işe yarar, iş mantığınızı buna bağlamayın.
• Tanımadığınız bir kod gelirse belgeyi "yolda" sayın — veri kaybı, fazladan bir sorgudan pahalıdır.

Gelen belge durumları

Gelen kutusunda Status, belgenin uygulama yanıtı durumudur:

Uygulama yanıtı durumu

Kabul / Red Yanıtı Durumu ayrı bir durum kümesi kullanır (Waiting · Queued · Processing · SentToGib · Success · Error). Yanıt verilmemişse Waiting (StatusCode 0); verildiyse yanıtın teslim durumudur ve başarı Success / 1000'dir — yanıtın GİB'e başarıyla ulaştığını gösterir. Bu uçta Approved dönmez.

Kanal (Scenario)

Senaryo (Profile / Type)

Liste satırlarında senaryo iki biçimde gelir: UBL'deki ProfileID değeri (Profile) ve sözleşme adı (Type). OZELFATURA'nın sözleşme karşılığı yoktur; Type boş döner.

Fatura tipi

UBL'deki cbc:InvoiceTypeCode. Liste satırlarında InvoiceType Türkçe adı (ör. Satış), InvoiceTipType sözleşme adını taşır.

Entegrasyon Akışları

Üç temel döngü. Akışınızı bunlara göre kurarsanız mükerrer işlem, kaybolan belge ve bitmeyen takip sorunlarını baştan önlersiniz.

1 · Fatura gönderimi

1. (İsteğe bağlı) Alıcıyı sorgulayın

   e-Fatura Mükellefi mi? — Scenario=Automated kullanıyorsanız gerekmez.

2. Faturayı gönderin

   Fatura Gönder. Yanıttaki InvoiceId (ETTN) ve Number'ı kendi kaydınıza yazın; InvoiceScenario belgenin e-Fatura mı e-Arşiv mi olduğunu söyler.

3. Durumu izleyin

   Giden Belge Durumu ile yolda olan belgeleri toplu sorgulayın (5–10 dakikada bir yeterli) ve üç kova kuralını uygulayın.

4. Sonuca göre davranın

   1000 → PDF'i alın, bildirim gönderin. 1200 / 2000 → sebebi İşlem Geçmişi'nden okuyun, belgeyi düzeltip yeniden gönderin.

2 · Gelen kutusu

1. Yeni belgeleri UBL'leriyle çekin

   Gelen Fatura Detayları — OnlyNewestInvoices=true, sayfa boyutu en fazla 5. Tüm sayfaları dolaşın; boş sayfa gelince durun. Tek istekte hem liste hem UBL gelir.

   Yalnız özet yeterliyse Gelen Fatura Listesi (IsArchived=false, sayfa boyutu 1000'e kadar) + gerektikçe Gelen Fatura Detayı ikilisini kullanın.

2. Görsel gerekiyorsa

   PDF ya da HTML görünümü ayrıca alınır.

3. Sisteminize kaydedin

   ETTN'yi benzersiz anahtar olarak kullanın — aynı belge ikinci kez gelirse tanırsınız.

4. Alındı olarak işaretleyin

   Alındı İşaretle — belge bir sonraki turda gelmez. Kaydetme adımınız güvenilirse bu işi SetTaken=true ile önceki adıma da bırakabilirsiniz; ama kayıt çökerse belge alınmış sayılacağı için önerimiz kayıttan sonra işaretlemektir.

5. Ticari faturaysa yanıt verin

   Status=WaitingForAprovement ise 8 gün içinde Kabul / Red. Yanıt bekleyenleri Gelen Belge Durumu ile toplu izleyin.

3 · e-Arşiv iptali

1. İptal edin

   e-Arşiv Faturası İptal — belge tarihinden itibaren 8 gün içinde.

2. Sonucu Value'dan okuyun

   IsSucceded=true tek başına "iptal edildi" demek değildir; iptal Value=true ise gerçekleşmiştir.

3. Durumu izleyin

   İptal edilen belge 1400 (Canceled) olur ve günlük raporla GİB'e bildirilir.

İyi uygulamalar

• Liste uçlarında sayfa boyutu en fazla 1000, detay uçlarında 5'tir; büyük geçmişi tarih aralıklarına bölerek çekin.
• Yolda olan belgeleri tek tek değil, InvoiceIds listesiyle toplu sorgulayın.
• Ağ hatasında aynı faturayı körlemesine yeniden göndermeyin: önce Giden Fatura Listesi'nde tarih ve alıcı süzgeciyle belgenin oluşup oluşmadığını kontrol edin.
• İstek ve yanıtları loglarken API anahtarını maskeleyin.

Sık Sorulan Sorular

Sürüm Notları

1.3 — 23 Eylül 2026

• Fatura detayı dönen uçlarda dört alan kaldırıldı: Giden Fatura Detayları, Giden Fatura Detayı, Gelen Fatura Detayları ve Gelen Fatura Detayı artık InvoiceId, Number, Status ve StatusCode döndürmüyor.
  Neden: aynı ad iki uçta ters anlam taşıyordu — liste uçlarında InvoiceId belge numarası, detay uçlarında ETTN idi. Bu, yanlış alanın okunmasına yol açıyordu.
  Nereden alacaksınız: ETTN ve belge numarası zaten belgenin UBL'inde (cbc:UUID ve cbc:ID); durum için Giden Fatura Listesi / Gelen Fatura Listesi ya da Fatura Durumu.
• Kabul / Red Yanıtı Durumu yenilendi — dört değişiklik:
  • Status artık bu uca özel durum kümesini kullanıyor: Waiting · Queued · Processing · SentToGib · Success · Error. Önceden belge durumu metinleri (Approved vb.) dönüyordu. Başarı artık Success.
  • StatusCode diğer uçlarla aynı ölçeğe geçti (0 · 100 · 200 · 300 · 1000 · 2000); önceden iç kod yayımlanıyordu (ör. 1300). Cevap verilmemiş belgede 0 davranışı değişmedi.
  • Bulunamayan ETTN artık satır döndürüyor: Status=Error, StatusCode=2000, Message="Belge bulunamadı.". Önceden sessizce yanıttan düşüyordu; yanlış yazılmış bir ETTN sonsuza kadar sorgulanabiliyordu.
  • XML kapısı: alanlar artık Value'nun öznitelikleri (<Value InvoiceId="…" Status="Success" …/>), alt eleman değil — diğer durum uçlarıyla aynı şekil. Öznitelik okuyan istemciler bu uçta artık değer bulur.
• e-Arşiv belgeleri artık daha erken 1000 (Approved) oluyor. Önceden belge imzalanıp denetimden geçtikten sonra, GİB'e günlük rapor iletilene kadar (genellikle ertesi gün) 200 (Processing) görünüyordu; artık denetimden geçtiği anda 1000 dönüyor.
  Neden: e-Arşiv faturasının alıcıya iletilen şekli belgenin aslıdır ve GİB onayı gerektirmez — raporlama ayrı bir ödevdir. Eski davranışta müşteriniz "faturanız hazır" bildirimini alırken siz API'den "işlemde" görüyordunuz, takip kapanmıyor ve belge günlerce sorgulanıyordu.
  Kapsam: e-Arşiv faturasının yanı sıra e-SMM, e-MM, e-Adisyon ve e-Döviz belgeleri. e-Fatura etkilenmez. InternalCode bu belgelerde 22 döner.
  Yapmanız gereken: bir şey yoksa yoktur — 1000 zaten "bitti, başarılı" kovasıdır. Yalnız InternalCode üzerinden dallanıyorsanız 22'yi terminal sayın.
• WSDL tek uç nokta listeliyor. Önceden sözleşmede http ve https için iki ayrı port görünüyordu; artık yalnız https var. Hâlihazırda ürettiğiniz istemciler çalışmaya devam eder, sözleşmeyi yeniden üretirseniz seçim yapmanız gerekmez.

1.2 — 12 Eylül 2026

• Doğrulama uçları geldi. Fatura Doğrula ve Belge Doğrula: belgeyi göndermeden şema (XSD) ve GİB şematron kurallarından geçirir — belge numarası tüketilmez, kontör harcanmaz. İmza Doğrula: XML (XAdES) imzalarını doğrular; PDF (PAdES) doğrulaması henüz kullanıma açılmadı.
• Doğrulama yalnız şekil ve GİB kurallarına uygunluğu denetler; tutar ve vergi hesapları matematiksel olarak kontrol edilmez.
• Boş bıraktığınız künye alanları (belge numarası, ETTN, imza yer tutucusu) doğrulamadan önce tamamlanır ve CompletedFields ile bildirilir; gönderimde de aynısı olur.

1.1 — 12 Eylül 2026

• Dört yeni operasyon: Giden Fatura Detayı, Gelen Fatura Detayları, Gelen Belge Durumu ve Sunucu Saati.
• Gelen kutusu artık tek istekle UBL'leriyle birlikte çekilebiliyor; belge başına ayrı detay çağrısı gerekmiyor.
• Biçim değişikliği: Fatura detayı dönen uçlarda (Gelen Fatura Detayı, Giden Fatura Detayı ve çoğul karşılıkları) JSON'daki InvoiceXml alanı artık base64 değil, belgenin XML metnidir. XML kapısı zaten ham UBL veriyordu; iki kapı hizalandı. Base64 yalnız dosya döndüren uçlarda kaldı (UBL, PDF, HTML).
• Aynı uçlara iki alan eklendi: CreateDateUtc (belgenin sisteme kayıt anı) ve Notification (şekil uyumu için; her zaman boş).
• Düzeltme: Gelen Fatura Detayı ve Gelen Belge İşlem Geçmişi yanıtlarındaki Status alanı, liste uçlarıyla aynı şekilde artık belgenin uygulama yanıtı durumunu veriyor (WaitingForAprovement / Approved / Declined). Önceden burada gönderim aşaması durumu görünüyordu.

1.0 — 11 Eylül 2026

• İlk yayın: 25 operasyon, JSON (REST) ve XML (SOAP 1.1) kapıları.
• Canlı deneme konsolu: tek kimlik kartı, JSON / XML geçişi, belge önizleme, beş dilde kod örneği.
• API ile şimdilik yalnız TRY para birimli ve SATIS, IADE, TEVKIFAT, TEVKIFATIADE, ISTISNA tipindeki faturalar gönderilebilir.

Destek

Entegrasyonunuzun her adımında yanınızdayız. Test hesabı talepleriniz için de bize ulaşın.