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.

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çtikten sonra, günlük rapor GİB'e iletilene kadar 200 (Processing) görünür; rapor gidince 1000 olur (genellikle ertesi gün).
• 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: yanıt verilmemişse Waiting (StatusCode 0); verildiyse yanıtın teslim durumu — Approved, yanıtın GİB'e başarıyla ulaştığını gösterir.

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.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.