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.
| Alan | Değer | Kullanım Bağlamı |
|---|---|---|
OutgoingCreditNoteStatus | CreditNoteAndXmlCreated | Makbuz ve UBL XML oluşturuldu |
Signed | Makbuz imzalandı; GİB gönderimine hazır | |
PartyIdentification.SchemeId | TCKN | Gerçek kişi veya çiftçi kimliği |
VKN | Tüzel kişi veya firma kimliği | |
ProfileId | EARSIVBELGE | GİB e-Arşiv belge profili |
CreditNoteTypeCode | MUSTAHSILMAKBUZ | e-Müstahsil Makbuzu belge tipi |
TaxScheme.TaxTypeCode | 0003 / GV STOPAJI | Gelir vergisi stopajı |
8001 / BORSA TES.ÜC. | Borsa tescil kesintisi | |
SGK_PRIM / SGK PRIM KESINTISI | SGK prim kesintisi | |
9040 / MERA FONU | Mera fonu kesintisi |
Hata ve Mesaj Kodları
Bu tablo, e-Müstahsil Makbuzu modülünün mesaj sınıfında ve ortak mesaj katmanında tanımlı kodları listeler. Kod açıklamaları, ilgili mesaj anahtarının temsil ettiği işlem kapsamına göre verilmiştir.
| Kod | Mesaj Anahtarı | Kapsam |
|---|---|---|
COM0008 | SignFirmError | İmza firmasıyla ilgili ortak hata |
COM0014 | FirmNotFound | Firma kaydı bulunamadığında dönen ortak hata |
COM0016 | UnknownDocumentNumberSupplier | Belge numarası sağlayıcısı çözümlenemediğinde dönen ortak hata |
COM0017 | ProvidedUUIdIsNotValidGuid | Gönderilen UUId geçerli GUID formatında değildir |
EMM0001 | ModelIsEmpty | Request modeli boş veya işlenebilir durumda değildir |
EMM0005 | ProfileIdError | ProfileId değeri EARSIVBELGE değildir |
EMM0006 | CreditNoteTypeCodeError | CreditNoteTypeCode değeri MUSTAHSILMAKBUZ değildir |
EMM0009 | CreditNoteNumberSequenceControlError | Makbuz numarası sıra veya format kontrolü başarısızdır |
EMM0010 | CreditNoteToUblXmlConversionError | Request modelinden UBL XML üretimi başarısızdır |
EMM0011 | CreditNoteInsertError | Makbuz kaydı oluşturulamadı |
EMM0012 | CreditNoteCreated | Makbuz oluşturma başarılı mesajı |
EMM0013 | CreditNoteFindError | Makbuz kaydı bulunamadı |
EMM0014 | CreditNoteUpdateParameterError | Güncelleme parametreleri geçersizdir |
EMM0015 | CreditNoteUpdateError | Makbuz güncelleme işlemi başarısızdır |
EMM0016 | CreditNoteUpdated | Makbuz güncelleme başarılı mesajı |
EMM0017 | CreditNoteStatusUpdateError | Makbuz durum güncelleme işlemi başarısızdır |
EMM0019 | CreditNotePdfCreated | PDF üretimi başarılı mesajı |
EMM0020 | CreditNoteExternalIdRequired | CreditNoteExternalId zorunludur |
EMM0021 | CreditNoteUblParseError | UBL XML parse işlemi başarısızdır |
EMM0022 | CreditNoteCreatedFromUbl | UBL üzerinden makbuz oluşturma başarılı mesajı |
EMM0023 | CreditNoteSearched | Makbuz sorgulama başarılı mesajı |
EMM0024 | CreditNoteNotSignedCancelError | İmzalanmamış makbuz iptal edilmeye çalışılmıştır |
EMM0025 | CreditNoteAlreadyCancelled | Makbuz daha önce iptal edilmiştir |
EMM0026 | CreditNoteCancelled | Makbuz iptali başarılı mesajı |
EMM0027 | CreditNoteUpdatedFromUbl | UBL üzerinden güncelleme başarılı mesajı |
EMM0028 | CreditNoteExternalIdExists | CreditNoteExternalId daha önce kullanılmıştır |
EMM0029 | CreditNoteViewed | Makbuz görüntüleme başarılı mesajı |
EMM0030 | CreditNoteZipFindError | ZIP paket kaydı bulunamadı |
EMM0031 | CreditNoteEmailSendSuccess | E-posta gönderimi başarılı mesajı |
EMM0033 | CreditNoteUblXmlZip | UBL XML ZIP çıktısı üretimi |
EMM0034 | CreditNoteZipUpdateError | ZIP paket güncelleme işlemi başarısızdır |
EMM0035 | CreditNoteUUIdExistsError | UUId 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.
| Referans | Kapsam | Not |
|---|---|---|
ErrorModel.ErrorCode | Response hata listesi | Mesaj kodu veya log kodu bu alanda taşınır |
HasError / Errors[] | Oluşturma, güncelleme ve iptal response modeli | Makbuz işlem sonucundaki hata listesi response gövdesinde taşınır |
GIB_PARTY_INACTIVE | Taraf profili doğrulaması | GİB taraf kaydı aktif değilse validasyon listesine eklenebilir |
UNHANDLED_EXCEPTION | Servis hata yakalama bloğu | Beklenmeyen exception durumunda genel hata kodu olarak döner |
EArchiveStatus | İptal ve rapor durumu | CreditNoteCancelRequestModel tarafında 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.
| Konu | Kaynak | Ne 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 kontrolleri | Kullanı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
Henüz aktif değildir. Aşağıdaki kod ve enum değerleri GİB zorunluluğu ve VBT aktivasyon duyurusundan sonra geçerli olacaktır; bugünkü entegrasyon davranışını değiştirmez. 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ğer | Entegratör açısından anlamı |
|---|---|
CreditNoteAndXmlCreated | Doğrulama verisi kabul edilmiş ve belge işleme alınmıştır. |
Signed | Belge imzalanmış ve gönderime hazır duruma gelmiştir. |
WaitingForVerification / WaitingForSmsCode | Portalı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–EMM0060):
| Kod | Anlamı |
|---|---|
EMM0036 | Makbuzun mevcut durumu SMS doğrulama işlemi için uygun değildir. |
EMM0037 | Bu makbuz için SMS doğrulama işlemi devam etmektedir. |
EMM0038 | SMS doğrulama deneme sınırına ulaşıldı. |
EMM0039 | Makbuz için geçerli bir doğrulama kodu bulunmaktadır; süresi dolmadan yeni kod gönderilemez. |
EMM0040 | SMS doğrulama kodu gönderilemedi. |
EMM0041 | Doğrulama kodu geçersizdir veya süresi dolmuştur. |
EMM0051 | SMS doğrulama sağlayıcısı bilgileri yapılandırılmamıştır. |
EMM0052 | Excel ile toplu yükleme yalnızca Portal (UI) kullanıcıları için kullanılabilir. |
EMM0053 | SMS doğrulama işlemi için belge kimliği alanlarından biri gönderilmelidir. |
EMM0054 | Telefon numarası geçerli bir Türkiye mobil numarası olmalıdır. |
EMM0055 | VerificationToken alanı zorunludur ve geçerli GUID biçiminde olmalıdır. |
EMM0056 | Doğrulama kodu 6 haneli ve yalnızca rakamlardan oluşmalıdır. |
EMM0057 | SMS doğrulama kodu gönderme ve doğrulama işlemleri yalnızca Portal (UI) kullanıcıları için kullanılabilir. |
EMM0058 | Doğrulama sağlayıcısının VKN bilgisi 10 haneli ve yalnızca rakamlardan oluşmalıdır. |
EMM0059 | Doğrulama tamamlanmamış bir makbuz için imzalama işlemi başlatılamaz. |
EMM0060 | VerificationMethod geçersizdir; e-Müstahsil Makbuzu için geçerli değer SMS'tir. |
API hatası olmayan kodlar:
EMM0042–EMM0049 aralığındaki kayıtlar başarılı SMS gönderimi, doğrulama, telefon değişikliği ve iptal bildirimi gibi platform olaylarında kullanılan mesaj ve bildirim kayıtlarıdır; entegratör hata yönetimi bu kodlara dayandırılmamalıdır.