GİB Hata Yanıtları ve SAP Düzeltme Akışı

GİB e-Beyan entegrasyonunda her başarısız yanıt “tekrar gönder” ile çözülemez. Yanlış token, eksik yetki, geçersiz veri, dönem kuralı ve geçici servis sorunu farklı sorumlu ve farklı düzeltme adımı gerektirir. SAP ekranında yalnızca “işlem başarısız” göstermek, GİB’in sağladığı teşhis bilgisini kaybettirir.

GİB hata sınıfları

GİB’in KDV1 ve Kurumlar Geçici API dokümanlarında ortak hata sınıfları yer alır:

HTTP durumu	Örnek sınıf	SAP’teki ilk yönlendirme
`400`	JSON, veri formatı veya alan doğrulama hatası	Veri/eşleme sorumlusu
`401`	Kimlik doğrulama başarısız	Entegrasyon ve güvenlik sorumlusu
`403`	Kaynağa veya işleme yetki yok	Yetki ve mükellefiyet sorumlusu
`404`	Kaynak veya uç nokta bulunamadı	Entegrasyon yapılandırması
`422`	Veri geçerli, iş kuralı ihlal edildi	Vergi süreci sorumlusu
`500`	Beklenmeyen sistem hatası	Teknik izleme ve GİB durum kontrolü

HTTP durumu tek başına yeterli değildir. Dokümanlarda hata mesajının açıklamasıyla birlikte hatanın sekme ve satırını gösterebilen mesaj tanımlayıcısı ve sistemsel mesaj kodu bulunabileceği belirtilir. Bu alanlar SAP işlem kaydında ayrı ayrı saklanmalıdır.

SAP hata kaydında bulunması gereken bilgiler

Bir hata kaydı en az şu bağlamı içermelidir:

Şirket kodu, beyanname türü ve vergilendirme dönemi
SAP işlem ve kaynak belge kimliği
GİB beyanname kimliği varsa bu değer
Ortam, servis ve işlem türü
HTTP durumu, GİB mesaj kodu ve açıklama
Sekme, satır veya alan tanımlayıcısı
İlk hata zamanı, son deneme zamanı ve deneme sayısı
Atanan sorumlu, düzeltme notu ve yeniden kontrol sonucu

API anahtarı, kişisel veri veya gereksiz tam istek gövdesi hata ekranına ve genel loglara yazılmamalıdır.

Düzeltme akışı

1. Yanıtı sınıflandırın

Teknik bağlantı, kimlik doğrulama, yetki, veri formatı, iş kuralı ve GİB servis hatasını ayırın. Sınıflandırılamayan hata, varsayılan olarak otomatik tekrara alınmamalıdır.

2. Kaynağa geri bağlayın

Hata belirli bir alan veya satırdaysa kullanıcıyı yalnızca mesaj listesine değil, ilgili SAP kaynak kaydına yönlendirin. Düzeltmenin beyanname kopyasında mı yoksa kaynak kayıtta mı yapılacağı süreç sahibi tarafından belirlenmelidir.

3. Düzeltmeyi kaydedin

Eski değer, yeni değer, değiştiren kişi, zaman ve açıklama kaydı tutun. Kaynak belge değiştirilemiyorsa gerekçeli istisna ve yetkili onayı olmadan hedef değeri değiştirmeyin.

4. Yerel kontrolleri yeniden çalıştırın

Yalnızca hatalı alanı değil, bu alana bağlı toplam ve mutabakatları da yeniden hesaplayın. Düzeltme sonrasında şirket içi onayın yenilenmesi gerekip gerekmediğini rol modeline göre belirleyin.

5. GİB durumunu sorgulayın

Zaman aşımı veya bağlantı kopması, işlemin GİB tarafında hiç oluşmadığını kanıtlamaz. Yeni gönderimden önce mevcut beyanname ve dosya durumunu sorgulayın. Böylece aynı dönem için kontrolsüz mükerrer işlem riski azaltılır.

6. Kontrollü yeniden işlem yapın

400, 403 veya 422 türündeki kalıcı veri/yetki hataları düzeltilmeden otomatik tekrar edilmemelidir. Geçici teknik sorunlarda bile bekleme, deneme sınırı ve son durum sorgusu tanımlanmalıdır. Her yeniden işlem önceki hata kaydıyla ilişkilendirilmelidir.

Dosya yükleme hataları

GİB’in bazı API akışlarında büyük dosyalar parçalara ayrılarak yüklenir. Dokümanda dosya durumu İŞLEME_ALINDI, İŞLENİYOR, BAŞARILI_İŞLENDİ, HATALI veya İPTAL_EDİLDİ olarak izlenebilir; hatalı satırlar için ayrı hata dosyası alınabilir.

SAP ekranı bu asenkron süreci tek bir bekleme animasyonu olarak göstermemelidir. Dosya kimliği, yüklenen parça sayısı, son durum ve hata dosyası bağlantısı işlem kaydında görünür olmalıdır.

Mimari bağlam için SAP E-Beyanname entegrasyon mimarisini, canlıya geçiş testleri için uygulama kontrol listesini okuyun. Fenikstech SAP E-Beyanname çözümünün interaktif simülasyonu şirket içi kontrol ile GİB yanıtlarının aynı işlem akışında nasıl ele alınabileceğini gösterir.

Resmî kaynaklar

Bu yazı 23 Temmuz 2026’da resmî kaynaklara göre gözden geçirilmiştir.