e-Müstahsil Makbuzu

30 Haziran 2027 Geçişi

Entegratörler İçin

Doğrudan JSON API veya UBL kullanan entegratörlerin SMS paketi ve GİB rapor geçiş kuralları.

Planlanan sürümde tam SMS paketi UBL ve rapora yazılır. SMS kullanılmadığında raporda kod, telefon ve operatör bölümü oluşturulmaz. 4 Kasım 2026 testinde GİB, SMS’li, SMS’siz ve her iki türü içeren karma raporu kabul etti (sonuç kodu 30). Yayımlanan GİB rapor şeması SMS’siz satırı zorunlu alan kontrolünde reddediyor. Canlı ortam için GİB teyidi bekleniyor.

Doğrudan JSON API veya hazır UBL kullanan entegratörlerin yeni bir SMS gönderme endpointi çağırması beklenmez. Entegratörün kendi doğrulama sürecinde elde ettiği bilgiler, zaten kullanılan e-müstahsil makbuzu oluşturma veya güncelleme endpointine eklenmelidir.

Kapsam: Değişiklik yeni bir entegratör akışı eklemekten çok, mevcut request modellerinin doğrulama bilgileriyle genişletilmesidir. Portalın kullandığı SMS gönderme ve kod tamamlama işlemleri entegratör sözleşmesine dahil değildir.

Entegratörlerin kullandığı endpointler

Yeni doğrulama davranışı, entegratörlerin zaten kullandığı oluşturma ve güncelleme endpointlerine eklenecektir. Endpoint adresleri değişmeyecek; mevcut request ve response modellerindeki SMS alanları kullanılacaktır.

JSON endpointleri

POST/api/CreditNoteApi/AddOutgoingCreditNote

Yeni e-müstahsil makbuzunu JSON modeliyle oluşturur.

Değişen modelOutgoingCreditNoteRequestModel
Yeni alanlarVerificationMethod, VerificationInfo ve VerificationProvider
SMS paketiVerificationMethod = SMS ile dört doğrulama alt alanı birlikte gönderilmeli veya alanların tamamı boş bırakılmalıdır.
POST/api/CreditNoteApi/UpdateOutgoingCreditNote

Mevcut e-müstahsil makbuzunu JSON modeliyle günceller.

Değişen modelOutgoingCreditNoteRequestModel
Yeni alanlarVerificationMethod, VerificationInfo ve VerificationProvider
SMS paketiYöntem ve güncel doğrulama bilgileri request içinde yeniden gönderilmelidir; eski bilginin korunacağı varsayılmamalıdır.

UBL endpointleri

POST/api/CreditNoteApi/AddOutgoingCreditNoteByUbl

Yeni e-müstahsil makbuzunu hazır UBL CreditNote belgesiyle oluşturur.

Değişen içerikCreditNoteUblRequestModel içindeki UBL XML
Yeni alanlarDoğrulama bilgileri ilgili tarafların Contact düğümlerinde taşınmalıdır.
SMS paketiSMS kullanılacaksa UBL, yöntem sabitleri ve dört doğrulama değeriyle tamamlanmış olmalıdır.
İmzalı UBLIsSigned = true ise XML içindeki telefon ve diğer doğrulama değerleri imzadan önce nihai ve GİB'e uygun olmalıdır.
POST/api/CreditNoteApi/UpdateOutgoingCreditNoteByUbl

Mevcut e-müstahsil makbuzunu güncel UBL CreditNote belgesiyle değiştirir.

Değişen içerikCreditNoteUblRequestModel içindeki UBL XML
Yeni alanlarGüncel doğrulama bilgileri tarafların Contact düğümlerinde taşınmalıdır.
SMS paketiDoğrulama verisi güncel UBL içinde yeniden eksiksiz sağlanmalıdır.
İmzalı UBLDeğiştirilen XML yeniden imzalanmalı ve IsSigned = true ile nihai hali gönderilmelidir.

Sorgulama response değişikliği

Response alanları: Kullanıcıya yönelik süreç durumu mevcut OutgoingCreditNoteStatusForUser alanında doldurulur. Doğrulama yöntemi belge detay ve geçmiş response modellerinde VerificationMethod olarak döner; grid response içinde yer almaz. Mevcut OutgoingCreditNoteStatus korunur.

Veri Sorumluluk Tablosu

Doğrudan entegrasyonda SMS kullanıyorsanız kodu API çağrısından önce doğrulayın. İşlem ve belge tarihi birlikte 30 Haziran 2027’ye ulaştığında tam SMS paketi zorunludur.

VeriKim üretir?Entegratör ne yapmalı?Platform ne yapar?
VerificationMethodEntegratörMM için desteklenen SMS değeri gönderilmelidir.Değeri doğrular; model requestinde GİB UBL yöntem sabitlerini üretir.
VerificationInfo.CodeSMS doğrulama hizmetiÜreticinin doğruladığı 4–6 karakterli kod değiştirilmeden gönderilmelidir; boşluk ve kontrol karakteri kullanılamaz.Kodu GİB e-Arşiv XSD sözleşmesine göre doğrular.
VerificationInfo.PhoneNumberEntegratörün SMS doğrulama süreciKodun gerçekten gönderildiği Türkiye mobil numarası gönderilmelidir. İmzalı hazır UBL'deki Telephone doğrudan 5XXXXXXXXX biçiminde olmalıdır.JSON/model girişinde 5XXXXXXXXX, 05XXXXXXXXX veya +905XXXXXXXXX biçimini normalize eder. İmzalı UBL'i değiştirmez; canonical olmayan telefonla gelen imzalı UBL'i reddeder. Ayrı e-Arşiv raporunda 05XXXXXXXXX üretir.
VerificationProvider.ApplicationNameSMS sağlayıcısıKendi SMS sağlayıcısı kullanılıyorsa sağlayıcının resmî unvanı gönderilmelidir.Değeri UBL sağlayıcı alanına taşır.
VerificationProvider.VknSMS sağlayıcısıKendi SMS sağlayıcısı kullanılıyorsa sağlayıcının 10 haneli VKN'si gönderilmelidir.VKN'yi UBL sağlayıcı alanına taşır.
Sağlayıcı bilgisi: VerificationProvider, SMS kodunu fiilen gönderen hizmet sağlayıcının resmî bilgileridir. Kendi SMS sağlayıcınızı kullanıyorsanız resmî unvanı ve 10 haneli VKN'yi gönderin. SMS VBT Portal üzerinden gönderiliyorsa VerificationProvider göndermeyin; sağlayıcı bilgisi platform tarafından eklenir.

Senaryo Bazlı Hazırlık Matrisi

SenaryoSMS doğrulama bilgileriBeklenen sonuçGönderim öncesi kontrol
JSON ile oluşturmaVerificationMethod = SMS ve dört alt alanBelge doğrulanmış veriyle normal işleme alınır.Kod, telefon, sağlayıcı adı ve VKN aynı doğrulama kaydına ait olmalıdır.
JSON ile güncellemeYöntem ve güncel doğrulama bilgileriBelge yeni request ve doğrulama verisiyle yeniden değerlendirilir.Güncel request tam gönderilmeli; önceki doğrulama bilgisine dayanılmamalıdır.
Hazır UBL ile oluşturmaSMS/SMS_PROVIDER sabitleri ve iki tarafın Contact verileriUBL doğrulama verisiyle birlikte kabul edilir.Mevcut taraf, adres ve kimlik alanları korunmalıdır.
Hazır UBL ile güncellemeGüncel UBL içinde tam yöntem ve doğrulama verisiBelge UBL'deki yeni doğrulama verisiyle güncellenir.Eski ve yeni Contact değerlerinin çelişmediği doğrulanmalıdır.
İmzalı hazır UBLİmzadan önce tamamlanmış, nihai UBL ve IsSigned = trueİmzalı XML değiştirilmeden saklanır ve imzalı belge olarak işlenir.Telefon dahil tüm SMS alanları GİB'e uygun olmalı; düzeltme gerekiyorsa XML yeniden oluşturulup yeniden imzalanmalıdır.
ÖnizlemeDoğrulama bilgisi aranmazBelge kaydedilmeden önizleme üretilir.Önizleme başarısı gerçek gönderim kabulü olarak yorumlanmamalıdır.
Eksik veya geçersiz yöntemVerificationMethod yok ya da SMS dışındaRequest zorunlu alan veya EMM0060 hatasıyla reddedilir.MM için yalnızca SMS gönderilmelidir.
Kısmi doğrulama verisiDört alt alandan biri veya daha fazlası eksikRequest validasyon hatasıyla reddedilir.Yöntem, iki model ve dört alt alan birlikte gönderilmelidir.

Request model değişiklikleri

OutgoingCreditNoteRequestModel, üst seviyedeki yöntem alanı ve iki doğrulama nesnesiyle genişletilecektir. SMS kullanılacaksa yöntem ve alt alanlar eksiksiz gönderilmelidir; kullanılmayacaksa tamamı boş bırakılmalıdır.

Yeni alanAlt alan / değerAnlamı
VerificationMethodSMSMM için desteklenen doğrulama yöntemidir. ChannelCode veya Type gönderilmez.
VerificationInfoCodeÜreticinin doğruladığı, GİB e-Arşiv XSD'sine uygun 4–6 karakterli SMS kodu; boşluk veya kontrol karakteri içeremez.
PhoneNumberDoğrulama kodunun gönderildiği telefon numarası.
VerificationProviderApplicationNameSMS doğrulama hizmetini sağlayan firmanın veya servisin adı.
VknSMS doğrulama hizmeti sağlayıcısının VKN'si.
SMS paket bütünlüğü: VerificationMethod, Code, PhoneNumber, ApplicationName ve Vkn aynı doğrulama kaydının ayrılmaz alanlarıdır. SMS kullanılacaksa paket eksiksiz gönderilmelidir; eski ChannelCode/Type biçimi desteklenmez.

Planlanan JSON model örneği

Örnek, normal bir e-Müstahsil Makbuzu için gereken belge alanlarıyla doğrulama alanlarını birlikte içerir ve JSON olarak doğrudan kopyalanabilir.

{
  "CreditNoteExternalId": "ERP-MM-2026-001",
  "ProfileId": "EARSIVBELGE",
  "CreditNoteTypeCode": "MUSTAHSILMAKBUZ",
  "DocumentCurrencyCode": "TRY",
  "IssueDate": "2026-11-04T09:00:00",
  "AccountingSupplierParty": {
    "Party": {
      "PartyIdentifications": [
        {
          "SchemeId": "VKN",
          "Value": "1234567890"
        }
      ],
      "PartyName": "Örnek Tarım Ürünleri A.Ş.",
      "PostalAddress": {
        "CityName": "Denizli",
        "Country": {
          "Name": "Türkiye"
        }
      }
    }
  },
  "AccountingCustomerParty": {
    "Party": {
      "PartyIdentifications": [
        {
          "SchemeId": "TCKN",
          "Value": "12345678901"
        }
      ],
      "Person": {
        "FirstName": "Ahmet",
        "FamilyName": "Çiftçi"
      }
    }
  },
  "LegalMonetaryTotal": {
    "LineExtensionAmount": 5000,
    "TaxExclusiveAmount": 5000,
    "TaxInclusiveAmount": 5000,
    "PayableAmount": 5000
  },
  "TaxTotal": [
    {
      "TaxAmount": 0,
      "TaxSubtotal": [
        {
          "TaxableAmount": 5000,
          "TaxAmount": 0,
          "Percent": 0,
          "TaxCategory": {
            "TaxScheme": {
              "TaxTypeCode": "0015"
            }
          }
        }
      ]
    }
  ],
  "CreditNoteLine": [
    {
      "Id": "1",
      "CreditedQuantity": {
        "UnitCode": "KGM",
        "Value": 1000
      },
      "LineExtensionAmount": 5000,
      "Item": {
        "Name": "Yaş Sebze"
      },
      "Price": 5,
      "TaxTotal": {
        "TaxAmount": 0,
        "TaxSubtotal": [
          {
            "TaxableAmount": 5000,
            "TaxAmount": 0,
            "Percent": 0,
            "TaxCategory": {
              "TaxScheme": {
                "TaxTypeCode": "0015"
              }
            }
          }
        ]
      }
    }
  ],
  "VerificationMethod": "SMS",
  "VerificationInfo": {
    "Code": "482193",
    "PhoneNumber": "05551112233"
  },
  "VerificationProvider": {
    "ApplicationName": "SMS_SAGLAYICI_ADI",
    "Vkn": "1234567890"
  }
}

UBL model değişiklikleri

JSON ve hazır UBL farkı: JSON modelinde yalnızca VerificationMethod = SMS gönderilir; platform SMS ve SMS_PROVIDER UBL sabitlerini üretir. Hazır UBL gönderildiğinde bu sabitler XML içinde entegratör tarafından sağlanmalıdır.
İmzalı UBL değiştirilemez: CreditNoteUblRequestModel.IsSigned = true ile gönderilen XML'in telefon, SMS kodu, yöntem ve sağlayıcı alanları imzadan önce nihai ve GİB kurallarına uygun hazırlanmalıdır. Platform imzalı XML'i yeniden yazmaz veya eksik alan eklemez; aksi işlem elektronik imzayı geçersiz kılar. Bir alanın düzeltilmesi gerekiyorsa UBL entegratör tarafından düzeltilip yeniden imzalanarak gönderilmelidir. IsSigned, entegratörün beyanıdır; yalnız geçerli elektronik imzası entegratör tarafından doğrulanmış UBL için true gönderilmelidir.
JSON alanı / sabitUBL karşılığıHazır UBL değeri
VerificationMethodAccountingCustomerParty/Party/Contact/NameSMS
VerificationInfo.CodeAccountingCustomerParty/Party/Contact/IDDoğrulanan kod
VerificationInfo.PhoneNumberAccountingCustomerParty/Party/Contact/TelephoneKodun gönderildiği telefon
VerificationMethodAccountingSupplierParty/Party/Contact/OtherCommunication/ChannelCode/@nameSMS_PROVIDER
VerificationProvider.ApplicationNameAccountingSupplierParty/Party/Contact/OtherCommunication/ChannelCodeSağlayıcı adı
VerificationProvider.VknAccountingSupplierParty/Party/Contact/OtherCommunication/ValueSağlayıcı VKN

Planlanan UBL kullanım örneği

Aşağıdaki parçalar mevcut AccountingCustomerParty ve AccountingSupplierParty taraflarının Party düğümlerine eklenmelidir. Örnekte gösterilmeyen kimlik, unvan, adres ve vergi bilgileri mevcut UBL yapısında korunmalıdır.

<!-- Üreticinin doğruladığı kod ve kodun gönderildiği telefon -->
<cac:AccountingCustomerParty>
  <cac:Party>
    <!-- Mevcut PartyIdentification, PartyName ve PostalAddress alanları -->
    <cac:Contact>
      <cbc:ID>482193</cbc:ID>
      <cbc:Name>SMS</cbc:Name>
      <cbc:Telephone>5551112233</cbc:Telephone>
    </cac:Contact>
  </cac:Party>
</cac:AccountingCustomerParty>

<!-- SMS sağlayıcısının adı ve VKN'si -->
<cac:AccountingSupplierParty>
  <cac:Party>
    <!-- Mevcut PartyIdentification, PartyName ve PostalAddress alanları -->
    <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>
Tek Contact yapısı korunmalıdır: İlgili Party altında zaten bir Contact düğümü varsa doğrulama alanları bu düğümle birleştirilmelidir; aynı taraf için çelişen telefon veya sağlayıcı bilgileri üretilmemelidir. Hazır UBL örneğinde telefon, GİB teknik kılavuzundaki gibi 5XXXXXXXXX biçimindedir.

Response model değişiklikleri

OutgoingCreditNoteResponseModel belge detayında, OutgoingCreditNoteHistoryResponseModel ise geçmiş kaydında VerificationMethod değerini taşır. OutgoingCreditNoteStatusForUser kullanıcıya gösterilecek SMS sürecini, mevcut OutgoingCreditNoteStatus ise ana belge durumunu taşımaya devam eder. VerificationMethod grid response modelinde bulunmaz.

Response sınırı: Belge detay response'una kod, telefon veya sağlayıcı için yeni üst seviye alan eklenmez. GetOutgoingCreditNote yanıtında OutgoingCreditNoteStatusForUser ve VerificationMethod izlenir.

GİB e-Arşiv raporu eşlemesi

Planlanan sürümde tam SMS paketi UBL ve rapora yazılır. SMS kullanılmadığında raporda kod, telefon ve operatör bölümü oluşturulmaz. Entegratör rapor için ayrı istek göndermez.

Request alanıRapor alanıDeğer
AccountingCustomerPartymustahsilBilgileri.gercekKisitckn, adiSoyadi
VerificationInfomustahsilBilgileri.gercekKisi.bilgiDetaykod, telefon (05XXXXXXXXX)
VerificationProvideroperatorUygulamaBilgiunvan, vkn
UBL imzası ile rapor imzası ayrıdır: Hazır UBL içindeki Telephone değeri değiştirilmez. Platform, kayıt sırasında doğrulanıp saklanan 5XXXXXXXXX değerini ayrı e-Arşiv raporu oluşturulurken 05XXXXXXXXX biçiminde rapora yazar; rapor daha sonra kendi imza sürecinden geçer. Bu dönüşüm kaynak UBL'e uygulanmadığı için UBL imzasını etkilemez.
Tip adı request alanı değildir: operatorKullanimType, e-Arşiv rapor XSD'sindeki teknik tip adıdır ve JSON requestine eklenmez.
DeğerEntegratör açısından anlamı
CreditNoteAndXmlCreatedDoğrulama verisi kabul edilmiş ve belge işleme alınmıştır.
SignedBelge imzalanmış ve gönderime hazır duruma gelmiştir.
WaitingForVerification / WaitingForSmsCodePortalın etkileşimli doğrulama adımlarıdır; doğrudan entegrasyonun normal başarılı gönderim sonucu değildir.

Başarılı ve başarısız yanıt örnekleri

Oluşturma ve güncelleme endpointleri işlem sonucunu Data.HasError altında taşır. Portalın kullandığı SMS gönderme ve kod doğrulama endpointlerinde request iş kuralı hatası oluştuğunda ise API hata zarfı döner. Entegrasyon bu iki yanıt biçimini birbirine karıştırmamalıdır.

Başarılı oluşturma yanıtı

{
  "RefreshToken": "",
  "Data": {
    "HasError": false,
    "Errors": [
      {
        "ErrorCode": null,
        "ErrorMessage": null
      }
    ],
    "CreditNoteNumber": "MUS2026000000145",
    "Ettn": "550e8400-e29b-41d4-a716-446655440000"
  }
}
Başarı kararı: Errors listesinin boş olduğu varsayılmamalıdır. Belgenin kabul edildiği kararı Data.HasError = false değeri üzerinden verilmelidir; belge numarası ve ETTN aynı Data nesnesinden okunmalıdır.

Başarısız oluşturma yanıtı

Doğrudan entegrasyonda SMS alanlarından biri gönderildiği halde paket tamamlanmazsa oluşturma veya güncelleme sonucu aşağıdaki biçimde döner.

{
  "RefreshToken": "",
  "Data": {
    "HasError": true,
    "Errors": [
      {
        "ErrorCode": "SCM0002",
        "ErrorMessage": "VerificationProvider.Vkn zorunlu bir elemandır boş geçilemez!"
      }
    ],
    "CreditNoteNumber": null,
    "Ettn": null
  }
}
Başarısız kabul: HTTP çağrısı tamamlanmış olsa bile Data.HasError = true ise belge kabul edilmiş sayılmamalıdır. Eksik alanlar Data.Errors listesinden okunmalı ve request tamamlanarak yeniden gönderilmelidir.

Portal SMS endpointi hata yanıtı

Yeni SMS gönderme ve kod doğrulama kontrolleri mevcut API hata zarfını kullanır. Bu endpointler yalnızca VBT Portal tarafından çağrılır; Portal dışındaki kanallar EMM0057 ile reddedilir. Hata ayrımında HTTP durumuyla birlikte ErrorCode dikkate alınmalı; programatik akış değişebilecek mesaj metnine bağlanmamalıdır.

{
  "Type": 2,
  "Type_Desc": "Business",
  "ErrorCode": "EMM0054",
  "Message": "Telefon numarası geçerli bir Türkiye mobil numarası olmalıdır.",
  "Detail": {
    "StackTrace": null,
    "Type": "Vbt.Core.ExceptionHandling.VbtException",
    "InnerExceptions": null
  }
}
AlanPortal davranışı
TypeHatanın uygulama kategorisini belirtir. SMS doğrulama iş kuralı hatalarında 2 değeri döner.
Type_DescType değerinin açıklamasıdır; iş kararı için zorunlu kabul edilmemelidir.
ErrorCodeProgramatik hata ayrımında bu alan kullanılır.
MessageKullanıcıya açıklayıcı bilgi olarak gösterilir; karar mantığı mesaj metnine bağlanmaz.
DetailTeknik hata türünü taşıyabilir; Portalın iş kararı bu alana bağlanmaz.
DataYalnızca veri taşıyan özel hata tiplerinde bulunabilir; her hata yanıtında geleceği varsayılmaz.

Edge-Case Tablosu

DurumSonuçEntegratör davranışı
VerificationMethod boş, doğrulama nesneleri doluZorunlu alan hatasıyla reddedilir.VerificationMethod = SMS eklenmelidir.
VerificationMethod değeri SMS dışındaEMM0060 ile reddedilir.MM için yalnızca SMS kullanılmalıdır.
VerificationInfo dolu, VerificationProvider boşReddedilir.SMS sağlayıcısının adı ve VKN'siyle birlikte yeniden gönderilmelidir.
Sağlayıcı dolu, kod veya telefon eksikReddedilir.Eksik üretici doğrulama bilgisi tamamlanmalıdır.
JSON requestinde yöntem ve dört alt alan tamNormal belge akışına alınır.Response ve belge durumu mevcut yöntemle takip edilmelidir.
Hazır UBL'de Contact/Name veya ChannelCode/@name yanlışYöntem çözümlenemez ve request reddedilir.SMS ve SMS_PROVIDER sabitleri düzeltilmelidir.
UBL içinde ikinci ve çelişen Contact üretilmişBelge anlamı belirsizleşir veya validasyon hatası oluşur.Doğrulama alanları tarafın mevcut Contact yapısıyla birleştirilmelidir.
İmzalı UBL'de telefon veya başka bir SMS alanı hatalıPlatform imzalı XML üzerinde düzeltme yapmaz.UBL düzeltilmeli, yeniden imzalanmalı ve IsSigned = true ile yeniden gönderilmelidir.
Preview başarılı, gerçek gönderimde doğrulama alanı eksikGerçek gönderim reddedilir.Preview ile gönderim validasyonunun aynı olmadığı dikkate alınmalıdır.

Entegratör geçiş kontrol listesi

  • VBT aktivasyon duyurusu ve yürürlük tarihi alındı.
  • Kullanılan oluşturma ve güncelleme endpointleri belirlendi.
  • VerificationMethod = SMS, iki doğrulama nesnesi ve dört alt alan eşlendi.
  • Hazır UBL üreten sistemlerde SMS ve SMS_PROVIDER sabitleri eklendi.
  • İmzalı UBL'de telefon ve tüm SMS alanlarının imzadan önce nihai olduğu, düzeltme halinde UBL'in yeniden imzalandığı test edildi.
  • Detay ve geçmiş response parser'ları VerificationMethod alanını okuyacak şekilde güncellendi.
  • OutgoingCreditNoteStatusForUser durumları desteklendi.
  • Eksiksiz JSON, eksik yöntem, geçersiz yöntem, kısmi JSON, eksiksiz UBL, imzalı UBL ve kısmi UBL senaryoları test edildi.
  • Erken kabul gerekiyorsa VBT tarafından bildirilen ortam yürürlük tarihi izlendi; belge tarihiyle birlikte değerlendirilmesi test edildi.

Entegratör durum akışı

Doğrudan entegrasyonda Portalın etkileşimli SMS adımları bulunmaz. Request, doğrulama yöntemi ve doğrulama alanlarının bütünlüğüne göre mevcut belge işleme akışına alınır veya reddedilir.

Entegratör state akışı

Doğrudan JSON veya UBL entegrasyonunda etkileşimli SMS adımları bulunmaz. Request, yöntem ve doğrulama alanları eksiksizse mevcut belge işleme akışına alınır; eksik veya geçersiz yöntem ile kısmi veri doğrudan reddedilir.

Entegratör SMS doğrulama state akışı JSON veya UBL requestinin doğrulama yöntemi ve dört doğrulama alanı açısından denetlenmesi, eksik veya geçersiz verinin reddedilmesi ve tam verinin belge işleme ile imzaya ilerlemesi. JSON / UBL request Oluşturma veya güncelleme Yöntem ve alanlar tam mı? SMS · kod · telefon sağlayıcı adı · VKN Belge kabul edildi CreditNoteAndXmlCreated Signed Gönderime hazır VALIDASYON HATASI Request reddedildi Yöntem ve eksik alanlar tamamlanarak yeniden gönderilmelidir. Tam veri mevcut belge işleme ve imza akışına devam eder.

Yeni hata kodları ve beklenen davranış

Tablodaki API mesajı sütunu, kaynak projedeki gerçek lokalizasyon metnini gösterir. Yapılacak işlem sütunu ise mesajın entegrasyon veya operasyon tarafında nasıl ele alınacağını açıklar.

KodGerçek API mesajıNe anlama gelir?Yapılacak işlem
EMM0036Makbuzun mevcut durumu SMS doğrulama işlemi için uygun değildir.Belge beklenen SMS doğrulama state'inde değildir.Belgenin güncel durumu yeniden sorgulanmalı; tamamlanmış veya iptal edilmiş akış tekrar başlatılmamalıdır.
EMM0037Bu makbuz için SMS doğrulama işlemi devam etmektedir. İşlem tamamlandıktan sonra yeniden deneyin.Aynı belge için başka bir SMS gönderme veya kod doğrulama işlemi sürmektedir.Eşzamanlı istek tekrarlanmamalı; mevcut işlemin sonucu beklenmelidir.
EMM0038SMS doğrulama deneme sınırına ulaşıldı. Lütfen daha sonra yeniden deneyin.Gönderme veya doğrulama deneme sınırına ulaşılmıştır.Otomatik tekrar döngüsü durdurulmalı ve işlem daha sonra yeniden denenmelidir.
EMM0039Makbuz için geçerli bir doğrulama kodu bulunmaktadır. Kodun süresi dolmadan yeni kod gönderilemez.Daha önce gönderilen kod hâlâ geçerlidir.Yeni SMS istenmemeli; mevcut kod kullanılmalı veya kodun süresinin dolması beklenmelidir.
EMM0040SMS doğrulama kodu gönderilemedi.SMS gönderimi teknik olarak tamamlanamamıştır.Belge doğrulanmış kabul edilmemeli; Portal yönlendirmesine göre yeniden denenmelidir.
EMM0041Doğrulama kodu geçersizdir veya süresi dolmuştur.Girilen kod doğrulanamamış veya kullanım süresi sona ermiştir.Eski kodla tekrar denenmemeli; Portal üzerinden yeni kod akışı başlatılmalıdır.
EMM0051SMS doğrulama sağlayıcısı bilgileri yapılandırılmamıştır. İşleme devam edebilmek için ApplicationName ve Vkn ayarlarını kontrol edin.VBT tarafındaki SMS sağlayıcısı ayarları eksiktir.İşlem durdurulmalı ve VBT sistem yöneticisine bildirilmelidir.
EMM0052Excel ile toplu yükleme yalnızca Portal (UI) kullanıcıları için kullanılabilir.Excel yüklemesi Portal dışındaki bir kanaldan çağrılmıştır.Excel yüklemesi VBT Portal üzerinden gerçekleştirilmelidir; ERP entegrasyonunda JSON veya UBL endpointleri kullanılmalıdır.
EMM0053SMS doğrulama işlemi için Id, CreditNoteExternalId, Ettn veya CreditNoteNumber alanlarından biri gönderilmelidir.Portal SMS endpointi belgeyi belirleyecek bir kimlik almamıştır.Portal isteğinde desteklenen belge kimliklerinden biri gönderilmelidir.
EMM0054Telefon numarası geçerli bir Türkiye mobil numarası olmalıdır.SMS gönderilecek telefon numarası boş veya geçersiz biçimdedir.Portal isteğinde geçerli Türkiye mobil numarası kullanılmalıdır.
EMM0055VerificationToken alanı zorunludur ve geçerli GUID biçiminde olmalıdır.Kod doğrulama isteğinin token alanı eksik veya geçersizdir.SMS gönderme endpointinin döndürdüğü token değiştirilmeden kullanılmalıdır.
EMM0056Doğrulama kodu 4 ile 6 karakterden oluşmalı, boşluk veya kontrol karakteri içermemelidir.Kod alanı GİB e-Arşiv XSD biçim kuralına uymamaktadır.GİB e-Arşiv XSD'sine uygun 4–6 karakterli kod gönderilmelidir.
EMM0057SMS doğrulama kodu gönderme ve doğrulama işlemleri yalnızca Portal (UI) kullanıcıları için kullanılabilir.Portal SMS endpointlerinden biri UI dışındaki bir kanaldan çağrılmıştır.Doğrudan entegrasyonda bu endpointler çağrılmamalı; doğrulama bilgileri oluşturma veya güncelleme requestinde eksiksiz gönderilmelidir.
EMM0058Doğrulama sağlayıcısının VKN bilgisi 10 haneli ve yalnızca rakamlardan oluşmalıdır.Oluşturma veya güncelleme requestindeki sağlayıcı VKN bilgisi geçersizdir.Doğrulama sağlayıcısının geçerli VKN bilgisi gönderilmelidir.
EMM0059e-Müstahsil Makbuzunun doğrulama işlemi henüz tamamlanmadığı için imzalama işlemi başlatılamadı.Belge doğrulama beklerken imza aşamasına ulaşmıştır.Belge doğrulanmış kabul edilmemeli; doğrulama tamamlandıktan sonra güncel durum yeniden sorgulanmalıdır.
EMM0060VerificationMethod alanı geçersiz. e-Müstahsil Makbuzu için geçerli değer: SMSRequestte desteklenmeyen bir doğrulama yöntemi gönderilmiştir.VerificationMethod alanı SMS olarak gönderilmelidir.
EMM0061İmzalı UBL içindeki Contact/Telephone alanı 5XXXXXXXXX biçiminde olmalıdır. İmzalı belge üzerinde telefon normalizasyonu yapılamaz.IsSigned = true gönderilen UBL'deki telefon canonical biçimde değildir.Telefon UBL içinde 5XXXXXXXXX biçimine getirilmeli, belge yeniden imzalanmalı ve yeniden gönderilmelidir.
API hatası olmayan kodlar: EMM0042–EMM0046 aralığındaki kayıtlar başarılı SMS gönderimi, doğrulama ve telefon değişikliği gibi platform olaylarında kullanılan mesaj kayıtlarıdır. Entegratör hata yönetimi bu kodlara dayandırılmamalıdır.

Teknik Entegrasyon Soruları

30 Haziran 2027 öncesinde hangi sözleşmeyi göndermeliyiz?

Canlıda mevcut SMS’siz gönderim devam eder. SMS desteği açıldığında erken kullanım için yöntemi, kodu, telefonu, sağlayıcı adını ve VKN’yi birlikte gönderin.

SMS gönderme ve kod doğrulama endpointlerini entegratör mü çağıracak?

Hayır. Bu işlemler VBT Portalın hazır kullanıcı akışıdır. Doğrudan entegratörler mevcut oluşturma veya güncelleme endpointlerinde VerificationMethod = SMS ile kendi süreçlerinde elde ettikleri dört doğrulama alt alanını gönderir.

Doğrulama alanlarından yalnızca telefon numarasını gönderebilir miyiz?

Hayır. SMS kullanılacaksa VerificationMethod = SMS, kod, telefon, SMS sağlayıcısının adı ve sağlayıcı VKN'si birlikte gönderilmelidir. Alanlardan birinin varlığı paket bütünlüğü kontrolünü başlatır; eksik paket kabul edilmez.

Update işleminde eski doğrulama bilgisi korunur mu?

Entegrasyon eski verinin korunacağını varsaymamalıdır. Güncelleme requesti, güncel ve eksiksiz doğrulama bilgisiyle hazırlanmalıdır.

İmzalı hazır UBL'deki telefon numarasını platform düzeltir mi?

Hayır. IsSigned = true ile gönderilen UBL, elektronik imzası korunarak değiştirilmeden saklanır. Telefon numarası dahil tüm doğrulama alanları imzadan önce GİB kurallarına uygun hazırlanmalıdır. Düzeltme gerekiyorsa UBL'i düzelterek yeniden imzalayın ve yeniden gönderin.

Preview neden doğrulama alanı olmadan başarılı olabilir?

Preview belgeyi kaydetmez veya imzalama sürecine sokmaz. Gerçek oluşturma ve güncelleme çağrıları seçilen sözleşmenin alan bütünlüğünü ayrıca denetler.