Referans

Teknik Referans

Durum değerleri, dosya türleri, dönem kuralları ve hata yönetimi referansı.

LedgerSummaryStates

CurrentStatus, entegratörün bir sonraki güvenli işlemini seçtiği dış durum alanıdır. Aşağıdaki enum adları API cevabında görüldüğü biçimiyle yazılmıştır.

Değer	Dış anlam	Entegratör davranışı	Terminal mi?
`WaitingForUpload`	Kaynak dosya/parça bekleniyor.	VBT Client ile doğru firma, şube ve ay için yüklemeyi başlatın.	Hayır
`WaitingForExtraction`	Yüklenen paket açılıyor.	Aynı dosyayı yeniden yüklemeyin; mevcut kaydı izleyin.	Hayır
`WaitingForParse`	Kaynak içerik ayrıştırılıyor.	Yeni dönem açmayın; Client sonucunu bekleyin.	Hayır
`WaitingForAnalysis`	Fiş, satır, dönem ve mali kurallar doğrulanıyor.	Teşhis raporu tamamlanmadan üretime geçmeyin.	Hayır
`WaitingForClientToServerTransfer`	Analiz edilen parçaların aktarımı bekleniyor.	Tüm Client parçalarını aynı dönem anahtarıyla aktarın.	Hayır
`WaitingForLedgerCreation`	Aktarım üretime hazır; defter oluşturma çağrısı bekleniyor veya işleniyor.	Rapor hazırsa `CreateLedger` çağırın; çağrı sonrası aynı `Uuid`'yi izleyin.	Hayır
`WaitingForApprove`	Yevmiye, kebir ve beratlar kullanıcı kontrolüne hazır.	Önizleme ve mali mutabakat sonrası güncel özeti onaylayın.	Hayır
`WaitingForSign`	Onaylanan dosyalar imza veya mali mühür işlemini bekliyor.	Yeni onay göndermeyin; imza sonucunu izleyin.	Hayır
`WaitingForSendingToGib`	İmza tamamlandı; GİB gönderimi başlatılabilir.	Yetkili gönderim işlemini yalnız bir kez başlatın.	Hayır
`InGibSendQueue`	Paket GİB'e gönderiliyor.	Yeni paket üretmeyin; güncel özeti izleyin.	Hayır
`InGibStatusQueue`	Gönderilen paketin GİB sonucu sorgulanıyor.	Aynı paket adı ve `Uuid` ile sonucu izleyin.	Hayır
`InGibReceiveQueue`	Olumlu sonuçlanan GİB onaylı berat alınıyor.	Dosya erişilebilir olana kadar yeni gönderim yapmayın.	Hayır
`SentToGib`	GİB onaylı berat alma adımı tamamlandı.	Onaylı beratları indirip imzalı defterlerle eşleştirin; ikincil kopya durumu ayrıca izlenebilir.	Akışa göre
`SentSecondCopy`	İkincil kopya adımı tamamlandı.	Arşiv mutabakatını kapatın.	Evet
`Failed`	Süreç bulunduğu aşamada hata ile durdu.	`PreviousStatus`, `FailDescription` ve `Messages[]` ile nedeni belirleyin.	Evet

Dönem Kuralları

Desteklenen standart dönemler Ocak-Aralık aylarıdır.
Her dönem aynı takvim ayının ilk ve son gününü kapsar.
Aralık'tan sonra sonraki yılın Ocak ayına geçilir.
Özel hesap dönemi ve parçalı ay senaryoları bu sözleşmenin dışındadır.

Hata Okuma

Messages[] içindeki hata türü ve metni, özet kaydındaki FailDescription ve güncel durumla birlikte değerlendirilir. Teknik ayrıntı veya stack trace kullanıcıya gösterilmemeli; destek kaydına firma, şube, dönem, Uuid ve zaman bilgisi eklenmelidir.

Hata katmanı	Gözlenebilir belirti	Entegratör işlemi
HTTP/kimlik	401/403 veya yetki mesajı	`Email` ve `Password` ile yeniden oturum açın; `SecurityFirmUUID` bağlamını doğrulayın.
Request sözleşmesi	`Messages[]` alan/format hatası	Gövdedeki zorunlu alanı ve tarih/şube biçimini düzeltin.
Kaynak veri	`DiagnoseMessages` içinde parça/fiş/satır bilgisi	Belirtilen kaynak kaydı düzeltin ve süreç raporunu yeniden doğrulayın.
Yaşam döngüsü	İşlem mevcut `CurrentStatus` için uygun değil	Durumu zorlamayın; çağrıyı doğru kontrol noktasında yapın.
GİB sonucu	Paket durum kodu/açıklaması veya onaylı dosyanın hazır olmaması	Aynı paket ve `Uuid` ile sonucu izleyin; yeni paket üretmeyin.

Süreç Hata Kodları

Messages[].MessageModel.Code alanı, metin dilinden bağımsız teknik hata anahtarıdır. Aşağıdaki kodlar dönem oluşturma, onay, imza ve çıktı alma işlemlerinde doğrudan ele alınmalıdır.

Kod	Anlam	Güvenli işlem
`LedgerSummary.NotFound`	Firma/şube/dönem veya UUID için özet bulunamadı.	Kimlik alanlarını doğrulayın; sonucu bilmeden yeni dönem açmayın.
`LedgerSummary.InvalidState`	İşlem mevcut `CurrentStatus` için geçerli değil.	Güncel özeti alın ve yalnız ilgili durumun izin verdiği çağrıyı yapın.
`LedgerSummary.FiscalYearInconsistency`	İstek dönemi firma için etkin takvim yılıyla uyuşmuyor.	`PeriodStart`, `PeriodEnd` ve firma yılını birlikte doğrulayın.
`LedgerSummary.InvalidHeaderSequenceStartNumber`	İlk dönemin yevmiye madde sırası 1 ile başlamıyor.	Kaynak fiş sırasını düzeltip Client analizini yeniden tamamlayın.
`LedgerSummary.InvalidDetailSequenceStartNumber`	İlk dönemin satır sırası 1 ile başlamıyor.	Kaynak satır sırasını düzeltip süreç raporunu yeniden doğrulayın.
`LedgerSummary.PreviousLedgerProcessNotFound`	Önceki dönem zinciri bulunamadı.	Ayların firma ve şube bazında sıralı açıldığını kontrol edin.
`LedgerSummary.PreviousLedgerProcessNotCompleted`	Önceki dönemin işlemleri tamamlanmadı.	Önceki dönemin hata, GİB sonucu ve arşiv durumunu kapatın.
`LedgerSummary.CannotRegisterForTheSameDate`	Aynı tarih/dönem için ikinci özet oluşturulmak isteniyor.	Mevcut kaydı `Uuid` ile bulun; mükerrer oluşturmayın.
`LedgerSummary.LedgerExistsForTheSpecifiedMonth`	Belirtilen ay için defter zaten mevcut.	Mevcut dönem özetini sorgulayın ve durumuna göre devam edin.
`LedgerSummary.SummaryStatusFailed`	Şubelerden en az biri üretim için uygun değil.	Her şubenin güncel özetini ve teşhis raporunu ayrı kontrol edin.
`LedgerSummary.LedgerApprovalFailed`	Şubelerden en az biri onay beklemiyor.	Toplu onaydan önce tüm şubeleri `WaitingForApprove` durumuna getirin.
`LedgerSummary.LedgerSignFailed`	Şubelerden en az birinin imza adımı tamamlanmadı.	GİB gönderimini başlatmadan önce imza durumlarını mutabık hale getirin.
`LedgerFiles.YevmiyeNotFound`, `LedgerFiles.KebirNotFound`	Defter dosyası henüz oluşmadı veya bulunamadı.	Özet durumunu izleyin; farklı bir UUID ile çıktı aramayın.
`LedgerFiles.YevmiyeBeratNotFound`, `LedgerFiles.KebirBeratNotFound`	Mükellef berat dosyası henüz oluşmadı veya bulunamadı.	Üretim/imza adımının tamamlanmasını bekleyin.
`LedgerFiles.GibYevmiyeBeratNotFound`, `LedgerFiles.GibKebirBeratNotFound`	GİB onaylı berat henüz alınmadı veya bulunamadı.	Aynı paket kimliğiyle GİB durumunu izleyin ve olumlu sonuçtan sonra dosyayı alın.

Veri Doğrulama Kodları

TempLedgerAnalysis kodları VBT Client analizinde kaynak fiş veya satırla birlikte raporlanır. Kodun yanında gelen PartNumber, EntryNumber, HeaderSequenceNumber, LineSequenceNumber ve DocumentReference değerleri hatalı ERP kaydını bulmak için kullanılır.

Kod grubu	Kapsanan kontroller	Düzeltme noktası
`LedgerHeader_EnteredBy_`, `LedgerHeader_EnteredDate_`	Kaydı giren kullanıcı, zorunlu tarih, tarih sırası ve gelecekte tarih.	Kaynak fiş başlığı.
`LedgerHeader_HeaderSequence*`	Yevmiye madde numarasının zorunluluğu, tekilliği ve kesintisiz sırası.	Kaynak fiş sıra üretimi.
`LedgerHeader_TotalDebit_`, `LedgerHeader_TotalCredit_`, `LedgerHeader_Amount`	Başlık borç/alacak değerleri, satır toplamları ve denge.	Fiş başlığı ve bağlı satırlar.
`LedgerHeader_IncludesInvalidPeriod`	Fiş tarihi seçilen aylık dönemin dışında.	Kaynak tarih veya istek dönemi.
`LedgerDetail_LineSequence`, `LedgerDetail_HeaderSequenceNumber_`	Satır numarası ve bağlı olduğu yevmiye madde numarası.	Kaynak fiş satırı ve başlık ilişkisi.
`LedgerDetail_AccountMainId_`, `LedgerDetail_AccountMainDescription_`, `LedgerDetail_AccountSubId_*`	Ana hesap kodu/açıklaması ve alt hesabın ana hesabı içermesi.	Hesap planı eşlemesi.
`LedgerDetail_Amount_`, `LedgerDetail_DebitCreditNote_`	Pozitif tutar ile `D`/`C` yönü.	Kaynak muhasebe satırı.
`LedgerDetail_PostingDate_`, `LedgerDetail_DocumentReference_`	Satır tarihinin ve fiş referansının başlıkla uyumu.	Kaynak satır tarihi ve referansı.
`LedgerDetail_DocumentType_*`, `LedgerDetail_DocumentTypes_NotMatching`	Belge türü değer kümesi, koşullu belge alanları ve aynı fişte tür tutarlılığı.	Belge türü, numarası, tarihi ve “other” açıklaması.
`LedgerDetail_AmountOriginal*`	Yabancı para tutarı, para birimi, kur ve kur tarihi birlikteliği.	Dövizli kaynak satır.
`LedgerPartConsistency_*`	Parçalar ve önceki dönem arasında tarih, madde ve satır sürekliliği.	Parçalama sırası ve önceki dönem son değerleri.

Çıktı Türleri

Çıktı	`Data` biçimi	Kullanım
HTML önizleme	HTML işaretleme metni	Onay öncesi insan gözüyle kontrol.
PDF	Base64 kodlu PDF byte dizisi	Okunabilir görüntü; yasal teknik dosyanın yerine geçmez.
ZIP	Base64 kodlu ZIP byte dizisi	İmzalı veya GİB onaylı teknik dosyaları indirme.