e-Gider Pusulası

Sorumluluklar

Entegratör Sorumlulukları

Entegratörün veri hazırlama, doğrulama ve belge oluşturma sürecindeki sorumlulukları.

Doğrudan entegrasyon: Entegratör, doğrulama işlemini kendi uygulamasında tamamlamalı ve sonucu mevcut belge oluşturma veya güncelleme requestiyle eksiksiz göndermelidir. Portalın SMS gönderme ve kod doğrulama endpointleri doğrudan entegrasyon sözleşmesinin parçası değildir. Doğrulama alanları boş gönderilirse istek beklemeye alınmaz, doğrudan reddedilir — boş doğrulamayla kaydedip sonradan tamamlama yalnızca Portal (UI) kanalına özgüdür.
Ortam varsayımı: Bu sayfadaki "zorunlu" ifadeleri, hedef ortamda SMS/iade kodu doğrulamasının etkin olduğu varsayılan yapılandırmayı esas alır. Bu zorunluluk firma bazında kapatılabilir; kapalıyken doğrulama alanları kontrol edilmeden kabul edilir. Ortamın doğrulama zorunluluğu durumu VBT ile teyit edilmelidir.

İlk Başarılı Belge İçin Uçtan Uca Akış

İlk entegrasyon, aşağıdaki sırayla tamamlandığında senaryo seçimi ile API çağrısı arasında açıkta adım kalmaz.

  1. Token alınmalı ve sonraki çağrılarda VbtAuthorization header'ı gönderilmelidir.
  2. Kullanım senaryosu üzerinden SATIS veya IADE; iade ise teslim, belge ve vekalet seçenekleri belirlenmelidir.
  3. JSON veya hazır UBL yöntemi seçilmelidir. Aynı belge için iki yöntemin alan taşıma kuralları karıştırılmamalıdır.
  4. Doğrulama sağlayıcısı çağrılmalı; doğrulanmış kod, telefon, yöntem, sağlayıcı adı ve VKN aynı doğrulama kaydından hazırlanmalıdır.
  5. Kargolu iadede CargoCompanies/GetAll çağrılmalı; JSON için Code, hazır UBL için aynı kaydın DeliveryParty alanları kullanılmalıdır.
  6. İade edilen belge ve varsa vekil bilgileri senaryoya göre eklenmelidir. BELGESIZ iadede T.C. vatandaşı için TCKN, yabancı uyruklu kişi için PASAPORTNO kullanılmalıdır.
  7. İstenirse PreviewOutgoingExpenseVoucher ile içerik doğrulanmalı; ardından ilgili Add veya Update endpointi çağrılmalıdır.
  8. Yanıtta HasError ve Errors[] kontrol edilmeli; başarılı işlemde dönen ETTN veya belge numarasıyla belge durumu sorgulanmalıdır.
Başarı ölçütü: HTTP 200 tek başına belge kabulü anlamına gelmez. Data.HasError=false olmalı; hata varsa aynı request koşulsuz tekrarlanmamalı, hata koduna göre düzeltilmelidir.
İmza asenkrondur: Data.HasError=false yanıtı belgenin imzalandığı anlamına gelmez; belge önce ExpenseVoucherAndXmlCreated durumuna geçer ve imza kuyruğuna alınır. Nihai Signed durumuna geçiş arka planda tamamlanır. Entegratör Add/Update yanıtından hemen sonra imzalı sonucu beklememeli, belgeyi yeniden sorgulayarak güncel durumu (OutgoingExpenseVoucherStatusForUser) takip etmelidir.

Veri Sorumluluk Tablosu

Entegratörün (ERP/POS) API çağrısından önce hazırlaması ve aynı belge requesti içinde göndermesi gereken veriler aşağıdadır.

#VeriKim ÜretirEntegratör Ne YapmalıHata
1SMS/İade KoduEntegratörün doğrulama süreciDoğrulanmış kod, ilişkili telefon ve yöntem aynı requestte gönderilmelidirEksik veya uyumsuz request reddedilir
2Sağlayıcı bilgileriSMS/iade kodu sağlayıcısıEntegratör adını değil; sağlayıcının açık uygulama adını ve VKN'sini gönderEksik sağlayıcı kaydı reddedilir
3İade belgesi bilgisiKendi sistemiOrijinal belge no/tarih/tür bulValidasyon hatası
4Kargo şirketi referansıPlatform (CargoCompanies/GetAll)JSON çağrısında kaydın Code değerini gönder; hazır UBL çağrısında aynı kaydın VKN, unvan, yetki belge no ve adres alanlarıyla DeliveryParty bölümünü hazırlaJSON'da geçersiz CargoCompanyCode genel zorunlu alan hatası döner; hazır UBL'de DeliveryParty uyumsuzluğu EGP0087 ile reddedilir
5Gerçek kimlikMüşteriBELGESIZ iadede doğrulaGİB reddi
6VerificationMethodDoğrulama yöntemiSMS veya IADEKODU seç; GİB provider değerini platform üretirSenaryoya uygun olmayan yöntem reddedilir
7TelefonDoğrulama işlemiKodun gerçekten ilişkilendirildiği telefonu aynı doğrulama kaydıyla gönderEksik telefon reddedilir
8Vekil bilgisiEntegratörKimlik tipi, kimlik değeri ve adı birlikte gönderEGP0054 / EGP0055 / EGP0084

Senaryo Bazlı Hazırlık Matrisi

Belge gönderilmeden önce doğrulama yöntemi ile senaryoya özgü alanlar birlikte hazırlanmalıdır.

SenaryoDoğrulamaEk bilgiler
SATISVerificationMethod=SMSVerificationProvider ve VerificationInfo eksiksiz gönderilmelidir.
Yüz yüze IADEVerificationMethod=SMS veya VerificationMethod=IADEKODUReturnedDocumentReference gönderilmelidir.
Kargolu IADEVerificationMethod=IADEKODUReturnedDocumentReference ve CargoCompanyCode gönderilmelidir.
Vekaletli IADETeslim biçiminin izin verdiği doğrulama yöntemiAsıl alıcı korunmalı; DelegateReceiver kimlik tipi, kimlik değeri ve ad ile gönderilmelidir.

Metot Bazlı Özel Kurallar

Aynı belge verisi farklı giriş metotlarında farklı taşıma biçimleri kullanır. Ayrıntılı request ve response sözleşmeleri Entegratör API Endpoint Referansı içinde yer alır.

Metot grubuEntegratörün göndermesi gerekenÖzel durum
JSON AddTam belge requesti ile VerificationInfo ve VerificationProviderAltı doğrulama alanı aynı doğrulama kaydına ait olmalıdır.
JSON UpdateGüncel tam belge ve doğrulama alanlarıEski doğrulama bilgisinin otomatik korunacağı varsayılmamalıdır.
UBL Add / UpdateDoğrulama ve sağlayıcı bilgilerini içeren güncel UBLBilgiler ilgili Contact düğümlerinde bulunmalı; mevcut taraf bilgileri ve tek Contact yapısı korunmalıdır.
ERP/API PreviewNormal gönderimle aynı doğrulama alanlarıÖnizleme kayıt oluşturmaz; ancak aynı içerik validasyonundan geçer.

Hazır UBL Endpoint Kuralları

Hazır UBL kullanan entegratör, JSON request alanlarını ayrıca göndermez; aynı iş bilgisini UBL içindeki taraf ve Contact düğümleriyle taşır.

EndpointBeklenen UBL içeriğiÖzel durum
AddOutgoingExpenseVoucherByUblSenaryoya uygun sağlayıcı, doğrulama, kargo ve belge referansı alanları UBL içinde eksiksiz bulunmalıdır.IsSigned=true, entegratörün belgenin imzalı olduğuna ilişkin beyanıdır ve yalnız gerçekten imzalanmış UBL için kullanılmalıdır. Platform bu beyana güvenir; imzalı UBL byte içeriğini tamamlamaz veya değiştirmez.
UpdateOutgoingExpenseVoucherByUblGüncel belge ve doğrulama bilgileri UBL içinde yeniden sağlanmalıdır.Eski UBL'deki doğrulama bilgisi otomatik olarak miras alınmaz.
Vekaleten yapılan iadelerde Contact konumu değiştirilmelidir: Normal akışta doğrulama bilgileri AccountingCustomerParty/Party/Contact altında gönderilmelidir. İade işlemini asıl alıcı yerine vekil gerçekleştiriyorsa vekilin kimlik ve ad bilgileri BuyerCustomerParty içinde; doğrulama bilgileri de BuyerCustomerParty/Party/Contact altında gönderilmelidir. Asıl alıcının AccountingCustomerParty bilgileri korunmalıdır. GİB raporundaki aliciBilgileri/bilgiDetay, vekile ait doğrulama bilgileri üzerinden üretilir.

Hazır UBL Örnekleri

Aşağıdaki parça hem Add hem Update UBL çağrısında FileBytes içine konulan tam UBL belgesinin ilgili bölümlerini gösterir. Tarafların mevcut kimlik, unvan, adres ve vergi alanları korunmalıdır.

Başarılı SMS doğrulama alanları 
<cac:AccountingCustomerParty>
  <cac:Party>
    <!-- Mevcut taraf alanları korunur -->
    <cac:Contact>
      <cbc:ID>482193</cbc:ID>
      <cbc:Name>SMS</cbc:Name>
      <cbc:Telephone>05551112233</cbc:Telephone>
    </cac:Contact>
  </cac:Party>
</cac:AccountingCustomerParty>

<cac:AccountingSupplierParty>
  <cac:Party>
    <!-- Mevcut taraf alanları korunur -->
    <cac:Contact>
      <cac:OtherCommunication>
        <cbc:ChannelCode name="SMS_PROVIDER">SMS_SAGLAYICI_ADI</cbc:ChannelCode>
        <cbc:Value>1234567890</cbc:Value>
      </cac:OtherCommunication>
    </cac:Contact>
  </cac:Party>
</cac:AccountingSupplierParty>
Vekaleten yapılan iade — BuyerCustomerParty ve Contact 
<cac:AccountingSupplierParty>
  <cac:Party>
    <!-- Satıcı bilgileri korunur -->
    <cac:Contact>
      <cac:OtherCommunication>
        <cbc:ChannelCode name="IADE_PROVIDER">IADE_KODU_SAGLAYICI_ADI</cbc:ChannelCode>
        <cbc:Value>1234567890</cbc:Value>
      </cac:OtherCommunication>
    </cac:Contact>
  </cac:Party>
</cac:AccountingSupplierParty>

<cac:AccountingCustomerParty>
  <cac:Party>
    <cac:PartyIdentification>
      <cbc:ID schemeID="TCKN">11111111110</cbc:ID>
    </cac:PartyIdentification>
    <!-- Asıl alıcının diğer taraf bilgileri korunur -->
  </cac:Party>
</cac:AccountingCustomerParty>

<cac:BuyerCustomerParty>
  <cac:Party>
    <cac:PartyIdentification>
      <cbc:ID schemeID="PASAPORTNO">U12345678</cbc:ID>
    </cac:PartyIdentification>
    <cac:Person>
      <cbc:FirstName>Vekil Ad Soyad</cbc:FirstName>
    </cac:Person>
    <cac:Contact>
      <cbc:ID>IADE-482193</cbc:ID>
      <cbc:Name>IADEKODU</cbc:Name>
      <cbc:Telephone>05551112233</cbc:Telephone>
    </cac:Contact>
  </cac:Party>
</cac:BuyerCustomerParty>

Vekilin kimliği TCKN veya PASAPORTNO olabilir. Doğrulama Contact alanları asıl alıcıya değil, vekili temsil eden BuyerCustomerParty altına yazılmalıdır.

Kargolu iade — DeliveryParty ve IADEKODU 
<cac:AccountingCustomerParty>
  <cac:Party>
    <!-- İadeyi yapan gerçek kişinin kimlik ve taraf bilgileri -->
    <cac:Contact>
      <cbc:ID>IADE-739251</cbc:ID>
      <cbc:Name>IADEKODU</cbc:Name>
      <cbc:Telephone>05551112233</cbc:Telephone>
    </cac:Contact>
  </cac:Party>
</cac:AccountingCustomerParty>

<cac:AccountingSupplierParty>
  <cac:Party>
    <!-- Satıcı bilgileri korunur -->
    <cac:Contact>
      <cac:OtherCommunication>
        <cbc:ChannelCode name="IADE_PROVIDER">IADE_KODU_SAGLAYICI_ADI</cbc:ChannelCode>
        <cbc:Value>1234567890</cbc:Value>
      </cac:OtherCommunication>
    </cac:Contact>
  </cac:Party>
</cac:AccountingSupplierParty>

<cac:Delivery>
  <cac:DeliveryParty>
    <cbc:IndustryClassificationCode name="YETKIBELGENO">İST.U-NET.M2.34.60</cbc:IndustryClassificationCode>
    <cac:PartyIdentification>
      <cbc:ID schemeID="VKN">9860008925</cbc:ID>
    </cac:PartyIdentification>
    <cac:PartyName>
      <cbc:Name>Yurtiçi Kargo Servisi A.Ş.</cbc:Name>
    </cac:PartyName>
    <cac:PostalAddress>
      <cbc:CityName>İstanbul</cbc:CityName>
      <cbc:CitySubdivisionName>Sarıyer</cbc:CitySubdivisionName>
      <cac:Country><cbc:Name>Türkiye</cbc:Name></cac:Country>
    </cac:PostalAddress>
  </cac:DeliveryParty>
</cac:Delivery>

Kargolu iadede SMS yöntemi kullanılamaz. JSON request'te VerificationMethod=IADEKODU gönderilmelidir. DeliveryParty; CargoCompanies/GetAll kaydındaki VKN, unvan, yetki belge numarası, şehir, ilçe ve ülke değerleriyle hazırlanmalıdır. Platform bu alanları değiştirmez; kayıtla uyuşmayan UBL'yi EGP0087 ile reddeder. IsSigned=true belgelerde bütün alanlar imzadan önce UBL'ye eklenmiş olmalıdır.

İade edilen belge türü — e-Arşiv Fatura, Satış Fişi ve Belgesiz 
<!-- e-Arşiv Fatura -->
<cac:BillingReference>
  <cac:InvoiceDocumentReference>
    <cbc:ID schemeID="EARSIV_FATURA">GIB2026000000002</cbc:ID>
    <cbc:IssueDate>2026-07-18</cbc:IssueDate>
  </cac:InvoiceDocumentReference>
</cac:BillingReference>

<!-- Satış Fişi -->
<cac:BillingReference>
  <cac:InvoiceDocumentReference>
    <cbc:ID schemeID="SATIS_FISI">FIS-001245</cbc:ID>
    <cbc:IssueDate>2026-07-18</cbc:IssueDate>
  </cac:InvoiceDocumentReference>
</cac:BillingReference>

<!-- Belgesiz -->
<cac:BillingReference>
  <cac:InvoiceDocumentReference>
    <cbc:ID schemeID="BELGESIZ"></cbc:ID>
    <cbc:IssueDate>2026-07-18</cbc:IssueDate>
  </cac:InvoiceDocumentReference>
</cac:BillingReference>

EARSIV_FATURA ve SATIS_FISI seçimlerinde belge numarası gönderilmelidir. BELGESIZ seçiminde numara boş olabilir; tarih yine zorunludur. AccountingCustomerParty içinde T.C. vatandaşı için gerçek TCKN, yabancı uyruklu kişi için PASAPORTNO bulunmalıdır.

Başarısız — eksik sağlayıcı bilgisi 
<cac:OtherCommunication>
  <cbc:ChannelCode name="SMS_PROVIDER">SMS_SAGLAYICI_ADI</cbc:ChannelCode>
  <!-- cbc:Value sağlayıcı VKN'si eksik -->
</cac:OtherCommunication>

VerificationProvider.Vkn karşılığı bulunmadığı için UBL reddedilir. ChannelCode/@name, sağlayıcı adı ve sağlayıcı VKN'si birlikte gönderilmelidir.

Kimlik ve yöntem seçimi: SATIS için VerificationMethod=SMS; yüz yüze IADE için SMS veya IADEKODU; kargolu IADE için yalnız VerificationMethod=IADEKODU kullanılmalıdır. Gerçek kişi alıcı ve vekil kimliği T.C. vatandaşı için TCKN, yabancı uyruklu kişi için PASAPORTNO olmalıdır; bu ayrım BELGESIZ iadede de geçerlidir.
Tek Contact yapısı korunmalıdır: Hazır UBL'de ilgili Party altında bir Contact düğümü zaten varsa doğrulama alanları bu düğümle birleştirilmelidir. Aynı taraf altında ikinci ve çelişen bir Contact oluşturulmamalıdır. JSON request'te ise yalnız VerificationMethod seçilir; GİB alanlarını platform üretir.

Gönderim Kontrol Listesi

  • Belge tipi, doğrulama sağlayıcısı ve doğrulama tipi birbiriyle eşleşmelidir.
  • Sağlayıcı alanlarında entegratörün değil, doğrulama hizmetini sunan kuruluşun uygulama adı ve VKN'si gönderilmelidir.
  • IADE belgesinde iade edilen belge bilgisi; kargolu iadede kargo kodu; vekaletli iadede vekil bilgileri eksiksiz gönderilmelidir.
  • Başarısız çağrı aynı anda yeniden tetiklenmemeli; hata koduna göre request düzeltilmeli veya bekleme süresi tamamlanmalıdır.
  • Başarılı yanıt alınmadan belge doğrulanmış veya işleme hazır kabul edilmemelidir.

Adım Süreci

Entegratör tarafındaki hazırlık süreci, belge senaryosu ve doğrulama bilgisinin doğru kurulmasıyla başlar; akış bu hazırlığın API gönderimine nasıl bağlandığını gösterir.

SATIS SMS sağlayıcı çağır → kod al Müşteriden kodu doğrula API'ye gönder ✓ IADE (Yüz yüze) SMS veya iade kodu doğrula İade belgesi bilgisi hazırla Vekalet? → 3 alan doldur API'ye gönder ✓ IADE (Kargo) İade kodu sağlayıcı çağır Kargo bilgilerini al İade belgesi hazırla API'ye gönder ✓ Platform kod geçerliliğini kontrol etmez — sadece alanların dolu olup olmadığını kontrol eder. Kodun gerçekten doğrulanmış olması tamamen entegratörün sorumluluğundadır.