e-Serbest Meslek Makbuzu

Referans

Teknik Referans

Enum değerleri, hata/mesaj kodları ve validasyon referansları.

Enumlar

e-SMM request ve response modelleri, teslim şekli, belge durumu ve para birimini sabit kod listeleriyle ayrıştırır. Aşağıdaki değerler API modeli ve servis akışları üzerinden doğrulanmıştır.

AlanDeğerKullanım Bağlamı
GonderimSekliKagitAlıcıya kâğıt çıktı teslimi
ElektronikElektronik teslim; e-posta işlevleri kullanılabilir
OutgoingSmmStatusPdfCreatedBelge ve PDF çıktısı oluşturuldu
SignedBelge imzalı duruma ulaştı; GİB gönderimine hazır
DocumentCurrencyCodeTRY, USD, EUR vb.ISO 4217 para birimi kodu
OrderByTypeASC / DESCListe sıralama yönü
EArchiveStatusGibDocumentStatus (Valid, Cancelled vb.)Belgenin e-Arşiv geçerlilik/iptal durumu; e-posta ve rapor durumundan bağımsızdır
EArchiveMailStatusEmailStatusAlıcı e-postası gönderim durumu; GİB raporlama sonucunu göstermez
EArchiveReportStatusGibReportDocumentStatus (WaitingForReport vb.)Normal GİB raporu sonucu; tekil PDF durumundan bağımsızdır
EArchiveCancelReportStatusGibReportDocumentStatusGİB iptal raporu sonucu; normal rapor durumundan ayrı izlenir

Alıcı Kimlik Sözleşmesi

KimlikRequestGİB raporu
VKNAlici.VknTckn 10 hane ve tüzel kişi unvanıYalnız tuzelKisi üretilir.
TCKNAlici.VknTckn 11 hane ve gerçek kişi ad/soyadYalnız gercekKisi üretilir.

İki kişi yapısı birlikte üretilemez ve ikisi de boş bırakılamaz. Rakam dışı kimlik SMM016, 10/11 hane dışındaki kimlik SMM017 ile reddedilir.

Hata ve Mesaj Kodları

Alan doğrulamaları SMM önekli kodlarla döner. Entegratör kodu ve mesajı birlikte kaydetmeli; kullanıcıya alan bağlamını koruyarak göstermelidir.

KodDoğrulama alanıİstemci davranışı
SMM001Request gövdesi boşİstek modeli oluşturulmadan tekrar gönderilmez.
SMM002Düzenleme tarihi geçersizIssueDate düzeltilir.
SMM003–SMM005, SMM007Alıcı, VKN/TCKN veya ad-soyadKimlik tipine uygun taraf alanları tamamlanır.
SMM006"Unvan en az 2 haneli olmalıdır."VKN'li alıcının Alici.Unvan değeri en az iki karakter olacak biçimde tamamlanır.
SMM008–SMM010Oran, kur, dış referans veya taraf bütünlüğüDönen mesajdaki alan/koşul düzeltilir; otomatik kör tekrar yapılmaz.
SMM011–SMM015Alıcı kişi/kurum alanlarıKimlik tipine uygun unvan veya ad/soyad alanları tamamlanır.
SMM016Alıcı VKN/TCKN değeri yalnız rakamlardan oluşmalıdır.Boşluk, harf ve noktalama kaldırılır.
SMM017Alıcı VKN 10, TCKN 11 hane olmalıdır.Kimlik uzunluğu seçilen türe göre düzeltilir; eski SMM018 dalı kullanılmaz.
SMM019–SMM022Alıcı adresiAdres, ülke, ilçe/semt ve şehir alanları tamamlanır.
UNHANDLED_EXCEPTIONBeklenmeyen işlem hatasıDış referansla sonuç sorgulanır; korelasyon bilgisiyle destek kaydı açılır.
Retry ayrımı: İçerik hatalarında veri düzeltilmeden tekrar denenmez. Ağ/5xx hatalarında ise önce dış referansla belgenin oluşup oluşmadığı sorgulanır.

İşlem Hata Kodları

Yukarıdaki alan doğrulama kodlarından ayrı olarak, işlem seviyesinde dönen SMM önekli ikinci bir kod ailesi vardır. Bu kodlar belge bulma, oluşturma, imzalama, iptal ve e-posta gibi operasyonel adımlarda döner.

KodAnlamı
SMM0001Belge bulunamadı.
SMM0002Belge başarıyla oluşturuldu.
SMM0003Belge başarıyla güncellendi.
SMM0004Belge başarıyla iptal edildi.
SMM0005Belge zaten iptal edilmiş.
SMM0006PDF başarıyla oluşturuldu.
SMM0007İmzalama hatası.
SMM0008Belge zip/arşiv kaydı bulunamadı.
SMM0009E-posta başarıyla gönderildi.
SMM00010Belge durumu güncellenemedi.
SMM00011Belge güncelleme hatası.
SMM00012Belge görüntülendi (log kaydı).
SMM00013Excel dosyası bulunamadı.
Not: Kod uzunlukları farklıdır (SMM0001–SMM0009 ve SMM00010–SMM00013); entegratör karşılaştırmayı sayısal değer üzerinden değil, dönen tam kod dizesi üzerinden yapmalıdır.

Validasyon Referansları

Validasyon yanıtlarında modüle özgü mesaj kodları dışında ortak yanıt zarfı alanları da görülür. Bu bölüm, response içindeki alanların nasıl ayrıştırılacağını teknik olarak sınırlar.

ReferansKapsamNot
RefreshTokenStandart yanıt zarfıBoş değilse güvenli biçimde saklanır ve sonraki çağrıda kullanılır
Data.HasError / Data.Errors[]Oluşturma, güncelleme ve önizleme response modeliİşlem sonucu ve hata detay listesi response gövdesinde birlikte değerlendirilir
ErrorModel.ErrorCodeResponse hata listesiİşlem mesaj kodu bu alanda taşınır
Data.SmmPdfFileBytesPDF ve önizleme yanıtıBase64 çözülüp application/pdf olarak kullanılır
UNHANDLED_EXCEPTIONServis hata yakalama bloğuBeklenmeyen exception durumunda genel hata kodu olarak döner
Senaryo referanslarıKullanım senaryoları karar tablolarıRehberdeki test matrisini işaretler; response mesaj kodu olarak kullanılmaz

Kaynak Bölümler

Teknik referans, ana akıştaki karar noktalarının yerine geçmez; ilgili bölümdeki business bağlamıyla birlikte okunmalıdır. Aşağıdaki bağlantılar kodların ve enumların hangi akışta değerlendirileceğini gösterir.

KonuKaynakNe Zaman Bakılır?
Alan ve endpoint ayrıntılarıEntegratör API Endpoint ReferansıRequest modeli hazırlanırken
Portal işlemleriPortal API Endpoint ReferansıPortal akışları incelenirken
Tam JSON örnekleriRequest ÖrnekleriSenaryo uyarlanırken
İş alanı / GİB raporu eşlemesiRequest → Belge → GİB Raporu MappingAlanın GİB raporundaki karşılığı doğrulanırken
Mevzuat ve teknik çerçeveGİB ReferansıVergi/kesinti kuralları veya resmi kaynak gerektiğinde