e-Müstahsil Makbuzu

Referans

Teknik Referans

Enum değerleri, hata/mesaj kodları, validasyon referansları ve kaynak bölüm bağlantıları.

Enumlar

e-Müstahsil Makbuzu sözleşmesindeki sabit değerler; belgenin GİB profilini, belge tipini, taraf kimliğini, durum bilgisini ve kesinti kodlarını belirler. Aşağıdaki değerler API'nin gözlenebilir kabul ve durum sözleşmesini gösterir.

AlanDeğerKullanım Bağlamı
OutgoingCreditNoteStatusCreditNoteAndXmlCreatedMakbuz ve UBL XML oluşturuldu
SignedMakbuz imzalandı; GİB gönderimine hazır
PartyIdentification.SchemeIdTCKNGerçek kişi veya çiftçi kimliği
VKNTüzel kişi veya firma kimliği
ProfileIdEARSIVBELGEGİB e-Arşiv belge profili
CreditNoteTypeCodeMUSTAHSILMAKBUZe-Müstahsil Makbuzu belge tipi
TaxScheme.TaxTypeCode0003 / GV STOPAJIGelir vergisi stopajı
8001 / BORSA TES.ÜC.Borsa tescil kesintisi
SGK_PRIM / SGK PRIM KESINTISISGK prim kesintisi
9040 / MERA FONUMera fonu kesintisi

Taraf Kimlik Sözleşmesi

TarafRequestGİB raporu
Makbuzu düzenleyen/alıcı firmaAccountingSupplierParty altında VKN/TCKN ve unvan/adSMS sağlayıcı bilgisi bu tarafın Contact/OtherCommunication alanından alınır.
Üretici/çiftçiAccountingCustomerParty altında 11 haneli TCKN ve ad/soyadmustahsilBilgileri.gercekKisi üretilir; SMS kodu ve telefon bilgiDetay alanına taşınır.

Taraf ve kimlik kontrolleri belge kayıt validasyonunda yapılır. GİB raporu oluşturulurken aynı iş kuralları yeniden çalıştırılmaz; kayıt sırasında oluşturulan üretici, VerificationInfo ve VerificationProvider raporlama snapshot'ları rapora eşlenir.

Hata ve Mesaj Kodları

Üretici/çiftçi kimliği kayıt validasyonunda SCHEME koduyla kontrol edilir; entegratör hata ayrımında ErrorMessage içeriğini de dikkate almalıdır.

KodGözlenebilir mesaj (birebir)
SCHEMEAccountingCustomerParty üretici/çiftçi için TCKN kimliği taşımalıdır.
SCHEMESMS doğrulamalı e-Müstahsil Makbuzunda üretici/çiftçi kimliği TCKN olmalıdır.

Aşağıdaki tablo, e-Müstahsil Makbuzu modülünün mesaj sınıfında ve ortak mesaj katmanında tanımlı diğer kodları listeler. Kod açıklamaları, ilgili mesaj anahtarının temsil ettiği işlem kapsamına göre verilmiştir.

KodMesaj AnahtarıKapsam
COM0008SignFirmErrorİmza firmasıyla ilgili ortak hata
COM0014FirmNotFoundFirma kaydı bulunamadığında dönen ortak hata
COM0016UnknownDocumentNumberSupplierBelge numarası sağlayıcısı çözümlenemediğinde dönen ortak hata
COM0017ProvidedUUIdIsNotValidGuidGönderilen UUId geçerli GUID formatında değildir
EMM0001ModelIsEmptyRequest modeli boş veya işlenebilir durumda değildir
EMM0005ProfileIdErrorProfileId değeri EARSIVBELGE değildir
EMM0006CreditNoteTypeCodeErrorCreditNoteTypeCode değeri MUSTAHSILMAKBUZ değildir
EMM0009CreditNoteNumberSequenceControlErrorMakbuz numarası sıra veya format kontrolü başarısızdır
EMM0010CreditNoteToUblXmlConversionErrorRequest modelinden UBL XML üretimi başarısızdır
EMM0011CreditNoteInsertErrorMakbuz kaydı oluşturulamadı
EMM0012CreditNoteCreatedMakbuz oluşturma başarılı mesajı
EMM0013CreditNoteFindErrorMakbuz kaydı bulunamadı
EMM0014CreditNoteUpdateParameterErrorGüncelleme parametreleri geçersizdir
EMM0015CreditNoteUpdateErrorMakbuz güncelleme işlemi başarısızdır
EMM0016CreditNoteUpdatedMakbuz güncelleme başarılı mesajı
EMM0017CreditNoteStatusUpdateErrorMakbuz durum güncelleme işlemi başarısızdır
EMM0019CreditNotePdfCreatedPDF üretimi başarılı mesajı
EMM0020CreditNoteExternalIdRequiredCreditNoteExternalId zorunludur
EMM0021CreditNoteUblParseErrorUBL XML parse işlemi başarısızdır
EMM0022CreditNoteCreatedFromUblUBL üzerinden makbuz oluşturma başarılı mesajı
EMM0023CreditNoteSearchedMakbuz sorgulama başarılı mesajı
EMM0024CreditNoteNotSignedCancelErrorİmzalanmamış makbuz iptal edilmeye çalışılmıştır
EMM0025CreditNoteAlreadyCancelledMakbuz daha önce iptal edilmiştir
EMM0026CreditNoteCancelledMakbuz iptali başarılı mesajı
EMM0027CreditNoteUpdatedFromUblUBL üzerinden güncelleme başarılı mesajı
EMM0028CreditNoteExternalIdExistsCreditNoteExternalId daha önce kullanılmıştır
EMM0029CreditNoteViewedMakbuz görüntüleme başarılı mesajı
EMM0030CreditNoteZipFindErrorZIP paket kaydı bulunamadı
EMM0031CreditNoteEmailSendSuccessE-posta gönderimi başarılı mesajı
EMM0033CreditNoteUblXmlZipUBL XML ZIP çıktısı üretimi
EMM0034CreditNoteZipUpdateErrorZIP paket güncelleme işlemi başarısızdır
EMM0035CreditNoteUUIdExistsErrorUUId daha önce kullanılmıştır

Validasyon Referansları

Makbuz validasyonları, modüle özgü mesaj kodlarının yanında taraf profili ve servis yanıt alanları üzerinden de izlenir. Bu bölüm, response ayrıştırılırken hangi alanların teknik referans kabul edileceğini netleştirir.

ReferansKapsamNot
ErrorModel.ErrorCodeResponse hata listesiMesaj kodu veya log kodu bu alanda taşınır
HasError / Errors[]Oluşturma, güncelleme ve iptal response modeliMakbuz işlem sonucundaki hata listesi response gövdesinde taşınır
GIB_PARTY_INACTIVETaraf profili doğrulamasıGİB taraf kaydı aktif değilse validasyon listesine eklenebilir
UNHANDLED_EXCEPTIONServis hata yakalama bloğuBeklenmeyen exception durumunda genel hata kodu olarak döner
EArchiveStatusİptal ve rapor durumuİptal requestinde e-Arşiv durum takibi için kullanılır
Senaryo referanslarıKullanım senaryoları karar tablolarıRehberdeki test matrisini işaretler; response mesaj kodu olarak kullanılmaz

Kaynak Bölümler

Teknik referans sayfası, makbuzun üretim ve iptal kararlarını tek yerde indeksler; detaylı akış için ilgili sayfadaki business bağlamı korunur. Aşağıdaki bağlantılar hangi bilginin hangi akışta kullanılacağını gösterir.

KonuKaynakNe Zaman Bakılır?
Enum alanlarıEntegratör API Endpoint ReferansıRequest modeli hazırlanırken
Vergi/kesinti kodlarıEntegratör API Endpoint ReferansıTaxTotal.TaxSubtotal altında kesinti kodları doldurulurken
Tevkifat alanlarıEntegratör API Endpoint ReferansıWithholdingTaxTotal belge veya satır seviyesinde kullanılacaksa
Edge-case kontrolleriKullanım SenaryolarıTekillik, tarih, numara ve iptal uygunluğu test edilirken
Platform hata yanıtıPlatform SorumluluklarıHasError ve Errors[] alanları analiz edilirken

Planlanan: SMS Doğrulama Hata Kodları ve Durumlar

Geçiş kuralı: Aşağıdaki kod ve enum değerleri SMS doğrulamalı UBL'de kullanılır. 30 Haziran 2027 öncesinde SMS alanları boş olabilir veya paket eksiksiz gönderilebilir; kısmi paket reddedilir. 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. Detay için SMS Doğrulamalı Gönderim — Entegratörler İçin sayfasına bakın.

Requestteki VerificationMethod alanı için desteklenen tek değer SMS'tir. Belge detay ve geçmiş response modelleri aynı alanı döndürür; grid response modeli bu alanı içermez. OutgoingCreditNoteStatusForUser ise mevcut OutgoingCreditNoteStatus alanının yanında SMS doğrulama bekleme adımlarını taşır:

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.

Planlanan SMS doğrulama hata kodları (EMM0036–EMM0061):

KodAnlamı
EMM0036Makbuzun mevcut durumu SMS doğrulama işlemi için uygun değildir.
EMM0037Bu makbuz için SMS doğrulama işlemi devam etmektedir.
EMM0038SMS doğrulama deneme sınırına ulaşıldı.
EMM0039Makbuz için geçerli bir doğrulama kodu bulunmaktadır; süresi dolmadan yeni kod gönderilemez.
EMM0040SMS doğrulama kodu gönderilemedi.
EMM0041Doğrulama kodu geçersizdir veya süresi dolmuştur.
EMM0051SMS doğrulama sağlayıcısı bilgileri yapılandırılmamıştır.
EMM0052Excel ile toplu yükleme yalnızca Portal (UI) kullanıcıları için kullanılabilir.
EMM0053SMS doğrulama işlemi için belge kimliği alanlarından biri gönderilmelidir.
EMM0054Telefon numarası geçerli bir Türkiye mobil numarası olmalıdır.
EMM0055VerificationToken alanı zorunludur ve geçerli GUID biçiminde olmalıdır.
EMM0056Doğrulama kodu 4 ile 6 karakterden oluşmalı, boşluk veya kontrol karakteri içermemelidir.
EMM0057SMS doğrulama kodu gönderme ve doğrulama işlemleri yalnızca Portal (UI) kullanıcıları için kullanılabilir.
EMM0058Doğrulama sağlayıcısının VKN bilgisi 10 haneli ve yalnızca rakamlardan oluşmalıdır.
EMM0059Doğrulama tamamlanmamış bir makbuz için imzalama işlemi başlatılamaz.
EMM0060VerificationMethod geçersizdir; e-Müstahsil Makbuzu için geçerli değer SMS'tir.
EMM0061İmzalı hazır UBL içindeki Contact/Telephone alanı canonical 5XXXXXXXXX biçiminde değildir; imzalı XML üzerinde normalizasyon yapılamaz.
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.