SAP'den SGK'ya: İşe Giriş, İşten Ayrılış, Vizite ve MUHSGK Entegrasyonu

Türkiye'de personel verisini SAP HCM'de tutan bir şirket için SGK, en sık konuşulan dış sistemlerden biridir: her işe alımda, her işten ayrılışta, her sağlık raporunda ve her ay sonunda. Bu bildirimleri İK'nın SGK ekranlarına tek tek girmesi hem zaman alır hem de SAP'deki kayıtla SGK'daki kaydın ayrışmasına yol açar.

SGK, işe giriş, işten ayrılış ve vizite işlemleri için resmi SOAP web servisleri sunar. Bu yazıda bu servislere SAP'den, ara katman kullanmadan, doğrudan ABAP ile bağlanan bir yapıyı anlatıyorum: bildirim personel işleminde doğar, SGK'ya kuyruk üzerinden gider, sonucu SAP'de saklanır. Metot ve alan adları SGK'nın yayımladığı kullanım kılavuzlarından alınmıştır; kılavuzlar zaman içinde güncellendiği için uygulamaya geçmeden önce güncel sürümünü kontrol edin.

Hangi Bildirim, Hangi Kanal?

Dört süreç aynı kurumla ilgili görünse de kanalları, kimlik doğrulama yöntemleri ve tetikleyicileri farklıdır. Tasarıma başlamadan bu farkı görmek, sonradan yaşanacak birçok sürprizi önler:

Mimari: ABAP'tan Doğrudan SOAP

SGK servisleri internete açık HTTPS adresleri üzerinden SOAP konuşur. SAP tarafında her servis için WSDL'den bir consumer proxy üretilir (SE80'de Enterprise Service sihirbazı); servis adresi ve bağlantı ayarları koddan değil, SOAMANAGER'daki logical port'tan gelir. İşe giriş ve işten ayrılış için SGK iki ayrı servis yayımlar; vizite için tek bir servis vardır.

Kurulumda üç teknik ayrıntı sık takılır:

• HTTPS zorunludur. SGK kılavuzu HTTP ile yapılan çağrıların hata vereceğini açıkça belirtir. SAP'nin bağlantıyı kurabilmesi için SGK sunucu sertifikasının zincirini STRUST'ta SSL istemci PSE'sine eklemek gerekir.
• WSDL şemayı dışarıdan alır. 4A servislerinin WSDL'i veri tiplerini ayrı bir XSD adresinden içeri alır. SGK kılavuzu bazı geliştirme araçlarında bu XSD'nin indirilip WSDL'deki schemaLocation'ın düzeltilmesini önerir. Proxy üretimi URL'den sorun çıkarırsa aynı yolu izleyip WSDL'i ve XSD'yi yerel dosyadan kullanın.
• Test ortamında kendi işyeriniz kendiliğinden bulunmaz. Test ortamında kendi işyeri sicilinizle çalışmak için SGK'ya e-posta ile başvurup işyeri bilgilerinin test ortamına aktarılmasını istemek gerekir; adres kılavuzda yazılıdır.

Mimari kararın özü şudur: SGK çağrısı, bildirimi doğuran ekran işleminin içinde yapılmaz. Her bildirim önce SAP'de bir kuyruk tablosuna yazılır, gönderim ayrı bir adımda yapılır, sonuç aynı satırda saklanır. Aşağıdaki yapı fikri anlatmak için yeterlidir:

ZHR_SGK_BILDIRIM   (SGK bildirim kuyruğu)
  PERNR / BILDIRIM_TURU / OLAY_TARIHI      personel, GIRIS veya CIKIS, işlem tarihi
  TCKIMLIK_NO                              sigortalının TC kimlik numarası
  ISYERI_SICIL                             26 haneli işyeri sicili
  DURUM                                    BEKLIYOR, GONDERILDI, SORGULANACAK,
                                           VERI_HATASI, AYAR_HATASI, TEKRAR_DENE
  REFERANS_KODU                            SGK'nın her başarılı bildirge için ürettiği kod
  SGK_MESAJI / DENEME_SAYISI               son cevap metni, kaç kez denendiği
  OLUSTURMA_ZAMANI / SON_DENEME_ZAMANI

Proxy'yi uygulamanın geri kalanına doğrudan açmak yerine küçük bir istemci sınıfının arkasına almak, iki şey kazandırır: SGK yapıları tek bir yerde kalır ve gönderim mantığı, SGK'ya bağlanmadan ABAP Unit ile test edilebilir. Destination, logical port ve dış servis çağrısının genel kurallarını SAP entegrasyon senaryoları yazısında anlattım.

Kimlik Bilgileri ve İşyeri Sicilleri

4A servisleri için ayrı bir web servis kullanıcısı yoktur; e-SGK'daki işyeri kullanıcısı kullanılır ve bilgiler her çağrının gövdesinde gönderilir:

Vizite servisinin kimlik modeli farklıdır: vizite uygulamasının kullanıcı kodu, işyeri kodu ve şifresiyle wsLogin çağrılır, dönen 36 karakterlik token sonraki çağrılarda kullanılır ve 30 dakika geçerlidir. İki servis için iki ayrı kimlik bilgisi seti yönetmek gerekir.

Birden çok işyeri sicili olan şirketlerde her işyerinin kendi kullanıcı bilgileri vardır. SAP'deki organizasyon atamasından (personel alanı ve alt alanı) doğru işyeri siciline giden eşleştirme bir customizing tablosunda tutulmalı ve her bildirim gönderilmeden önce bu eşleştirmeden geçmelidir.

İşe Giriş Bildirgesi

Tetikleyici personel işlemidir: işe alma işlemi kaydedildiğinde kuyruğa bir işe giriş satırı yazılır. Gönderimi aynı kaydın içinde değil, hemen ardından ayrı bir adımda (bgRFC veya kısa aralıklı bir arka plan işi) yapmanızı öneririm. Böylece SGK yavaşladığında İK ekranı beklemez, SGK kapalıyken bile personel işlemi kaydedilir.

Zamanlama bir süreç kararıdır. 5510 sayılı Kanun'a göre işe giriş bildirgesi genel kural olarak çalışan işe başlamadan en geç bir gün önce verilir; inşaat, tarım ve balıkçılık gibi bazı işyerlerinde en geç işe başlama günü, yeni tescil edilen işyerlerinde ise farklı bir süre uygulanır. Bu, İK'nın işe alma işlemini çalışan ilk gün geldiğinde değil, önceden girmesi demektir. Geriye tarihli girilen bir işe alma, sistem ne kadar iyi olursa olsun geç bildirimdir. Güncel süreleri ve istisnaları mevzuattan teyit edin.

Bir işe giriş kaydının SGK'ya giden başlıca alanları ve dikkat edilecek noktalar:

iseGirisKaydet metodu bir çağrıda en fazla 10 sigortalı kabul eder. Kuyruktaki bekleyen kayıtlar bu yüzden işyeri sicili bazında 10'arlı paketlere bölünür:

" pending: aynı işyeri siciline ait, gönderilmeyi bekleyen işe girişler
" c_max_per_call = 10 (SGK: çağrı başına en fazla 10 sigortalı)
DATA batch TYPE tt_queue.

LOOP AT pending INTO DATA(queued).
  APPEND queued TO batch.
  IF lines( batch ) = c_max_per_call.
    send_batch( batch ).
    CLEAR batch.
  ENDIF.
ENDLOOP.

IF batch IS NOT INITIAL.
  send_batch( batch ).
ENDIF.

Cevabın iki seviyesi vardır ve ikisi ayrı ele alınmalıdır. Paket düzeyindeki hataKodu, isteğin bütün olarak değerlendirmeye alınıp alınmadığını söyler: yanlış işyeri şifresi veya uyuşmayan sicil gibi durumlarda paketteki hiçbir kayıt işlenmez. Kayıt düzeyindeki islemSonucu ise her sigortalı için ayrı sonuçtur:

METHOD send_batch.
  DATA request  TYPE zsgk4a_ise_giris_parametre.
  DATA response TYPE zsigortali_ise_giris_sonuclari.

  request-kullanici_bilgileri         = credentials->for_workplace( batch[ 1 ]-isyeri_sicil ).
  request-sigortali_ise_giris_listesi = VALUE #( FOR entry IN batch ( to_sgk_entry( entry ) ) ).
  request-ayni_isveren_farkli_isyeri_nakil = 'H'.

  TRY.
      proxy->ise_giris_kaydet( EXPORTING input  = request
                               IMPORTING output = response ).
    CATCH cx_ai_system_fault INTO DATA(fault).
      " Cevap gelmedi: SGK bildirgeyi almış olabilir. Tekrar göndermeden önce sorgulanacak.
      set_status( entries = batch status = c_status-verify text = fault->get_text( ) ).
      RETURN.
  ENDTRY.

  " 1. seviye: paketin tamamı
  CASE response-hata_kodu.
    WHEN 0.
      " Paket değerlendirmeye alındı; sonuç kayıt bazında
    WHEN -101.
      " SGK tarafında sistem hatası: daha sonra tekrar denenir
      set_status( entries = batch status = c_status-retry text = response-hata_aciklamasi ).
      RETURN.
    WHEN OTHERS.
      " Şifre, sicil, işyeri durumu: hiçbir kayıt işlenmedi, bir insanın bakması gerekir
      set_status( entries = batch status = c_status-config_error text = response-hata_aciklamasi ).
      RETURN.
  ENDCASE.

  " 2. seviye: her sigortalı ayrı
  LOOP AT response-sigortali_ise_giris_sonuc INTO DATA(result).
    ASSIGN batch[ tckimlik_no = result-tckimlik_no ] TO FIELD-SYMBOL(<queued>).
    IF sy-subrc <> 0.
      CONTINUE.
    ENDIF.

    CASE result-islem_sonucu.
      WHEN 0.
        " Referans kodu saklanmazsa bildirgenin PDF dökümü alınamaz
        set_sent( entry = <queued> reference = result-referans_kodu ).
      WHEN -101.
        set_status( entries = VALUE #( ( <queued> ) ) status = c_status-retry
                    text    = result-islem_aciklamasi ).
      WHEN OTHERS.
        " Veri hatası: düzeltilmeden tekrar göndermenin anlamı yok
        set_status( entries = VALUE #( ( <queued> ) ) status = c_status-data_error
                    text    = result-islem_aciklamasi ).
    ENDCASE.
  ENDLOOP.
ENDMETHOD.

Başarılı her bildirge için SGK bir referans kodu üretir ve kılavuz bu kodun işveren tarafından saklanmasını ister. Bildirgenin PDF dökümünü veren iseGirisPdfDokum metodu bu kodla çalışır; kod kuyruğa yazılmazsa döküm için SGK ekranına gitmek gerekir.

Tarih biçimi küçük ama inatçı bir hata kaynağıdır. SGK istekleri dd.MM.yyyy bekler; kullanıcının tarih ayarına bağlı biçimlendirme, arka plan işi başka bir kullanıcıyla çalıştığında sessizce bozulur:

METHOD to_sgk_date.
  " DATE = USER veya WRITE kullanma: sonuç çalıştıran kullanıcının ayarına bağlı olur
  result = |{ date+6(2) }.{ date+4(2) }.{ date(4) }|.
ENDMETHOD.

Kılavuzun kendisinde bile sorgu cevaplarındaki tarihler için dd/MM/yyyy biçimi geçer. Gelen tarihleri tek bir biçim varsayarak çözmeyin; ikisini de kabul eden bir dönüştürücü yazın.

İşten Ayrılış Bildirgesi

İşten ayrılış bildirgesi, iş sözleşmesinin sona erdiği günü izleyen 10 gün içinde verilir ve istenCikisKaydet metoduyla gönderilir. Paketleme ve iki seviyeli sonuç kontrolü işe girişle aynıdır; farkı, taşıdığı veridedir.

• Çıkış nedeni: istenCikisNedeni, deneme süreli sözleşmenin feshinden emekliliğe, nakilden toplu işçi çıkarmaya uzanan iki haneli bir koddur. SAP'deki çıkış işleminin nedeninden (MASSN/MASSG) bir eşleştirme tablosuyla türetilmelidir. Yanlış çıkış kodu, çalışanın işsizlik ödeneği gibi haklarını doğrudan etkiler; bu eşleştirme İK ile birlikte, satır satır onaylanmalıdır.
• Dönem bilgileri: Bildirge, içinde bulunulan ve önceki dönem için belgeturu, hakedilenucret, primikramiye, eksikgunsayisi ve eksikgunnedeni taşır. Bu veriler bordrodan gelir; ama çıkış bildirgesinin süresi, o ayın bordrosu kesinleşmeden dolabilir. Ücret bilgisinin hangi kaynaktan ve hangi kesinlikte alınacağı önceden kararlaştırılmalıdır.
• Eksik gün: Eksik gün sayısı girilirse nedeni de zorunludur ve 1–31 arasında olmalıdır. Neden kodu, SAP'deki devamsızlık türünden eşleştirmeyle gelir.
• Nakil: Sözleşme sona ermeden aynı işverenin başka işyerine nakilde çıkış nedeni 16'dır ve gidilecek işyerinin 26 haneli sicili ayrıca gönderilir.

Servis, istenCikisDonemVeGunSayisiBul adında bir yardımcı metot da sunar: gönderilen işyeri ve sigortalı bilgisine göre SGK'nın gözünden dönem başlangıç ve bitiş tarihlerini ve gün sayılarını döndürür. Göndermeden önce SAP'nin hesapladığı gün sayısını bununla karşılaştırmak, en tartışmalı hatalardan birini gönderim öncesine çeker.

Zaman Aşımı ve Mükerrer Bildirge

SGK servislerinde zaman aşımı ve geçici kesinti, sahada en çok uğraştıran konulardan biridir ve tasarımda baştan beklenmelidir. Asıl tehlike, zaman aşımına uğrayan isteğin karşı tarafa ulaşmamış olduğunu varsaymaktır. İstek SGK'ya ulaşmış, işlenmiş ve yalnız cevap size dönmemiş olabilir. Kılavuzdaki istek yapısında bir tekrar koruma (idempotency) anahtarı yoktur; körlemesine tekrar göndermek mükerrer bildirge riskidir.

Güvenli yol, cevabı gelmeyen kaydı önce sorgulanacak durumuna almak ve tekrar göndermeden önce SGK'ya sormaktır. 4A servisleri bunun için TC kimlik numarası ve tarihle sorgulama metotları sunar:

METHOD verify_before_resend.
  " Zaman aşımı sonrası: istek SGK'ya ulaşmış ve işlenmiş olabilir.
  " Kör tekrar yerine önce sor; kayıt varsa ikinci bildirge gönderme.
  TRY.
      DATA(answer) = sgk_client->find_entry( workplace = entry-isyeri_sicil
                                             tckn      = entry-tckimlik_no
                                             date      = to_sgk_date( entry-olay_tarihi ) ).
    CATCH zcx_sgk_unavailable.
      RETURN.   " SGK hâlâ cevap vermiyor; durum aynı kalır, sonraki turda tekrar sorulur
  ENDTRY.

  CASE answer-hata_kodu.
    WHEN 0.
      " Kayıt bulundu: bildirge daha önce alınmış, tekrar gönderme
      set_status( entries = VALUE #( ( entry ) ) status = c_status-sent_no_reference
                  text    = `SGK'da kayıt bulundu` ).
    WHEN 1.
      " Kayıt yok: güvenle tekrar gönderilebilir
      set_status( entries = VALUE #( ( entry ) ) status = c_status-pending text = `` ).
    WHEN OTHERS.
      set_status( entries = VALUE #( ( entry ) ) status = c_status-retry
                  text    = answer-hata_aciklama ).
  ENDCASE.
ENDMETHOD.

İki ayrıntı önemlidir. Kılavuzdaki sorgu cevabında referans kodu yer almaz; zaman aşımına uğrayıp sorguyla doğrulanan bir bildirgenin referans kodu bu yoldan geri gelmez, bu yüzden ayrı bir durumla işaretlenir. Ve sorgu metotlarında 5 saniyede en fazla 20 sorgu sınırı vardır: toplu doğrulama yapan bir iş, sorgular arasına kısa bir bekleme koymalıdır.

Vizite: Raporları Çekmek ve Onaylamak

Raporlu bir çalışan için SGK'nın geçici iş göremezlik ödeneğini ödeyebilmesi, işverenin o dönem için "çalışmadığına dair bildirim" vermesine bağlıdır. WS_Vizite servisi bu bildirimi web ekranına girmeden yapmayı sağlar ve web uygulamasında geçerli kurallar servis için de geçerlidir.

Bizim yapıda akış iki parçalıdır: raporlar SGK'dan çekilip SAP'ye kaydedilir; onayı İK, SAP'deki bir listeden verir. Rapor çekmenin kendine özgü bir kuralı vardır. RaporAramaTarihile, poliklinik tarihi verilen tarihten küçük olan ilk 100 açık raporu döndürür. Okunan raporlar RaporOkunduKapat ile kapatılmazsa sonraki sorgular aynı raporları döndürür ve kılavuzun ifadesiyle diğer raporlara erişim engellenir:

METHOD fetch_open_reports.
  DATA(token) = vizite->login( ).              " wsLogin: 30 dakika geçerli token

  DO.
    " Poliklinik tarihi verilen tarihten küçük ilk 100 açık rapor
    DATA(reports) = vizite->find_reports_before( token = token
                                                 date  = sy-datum + 1 ).
    IF reports IS INITIAL.
      EXIT.
    ENDIF.

    " İK onay listesinin okuduğu tablo; rapor ID'sine göre yaz, tekrar gelirse üzerine yazılır
    save_for_approval( reports ).
    COMMIT WORK AND WAIT.

    " Okundu olarak kapatmayı ancak kayıt kalıcı olduktan SONRA yap
    LOOP AT reports INTO DATA(report).
      vizite->mark_as_read( token = token report_id = report-medula_rapor_id ).
    ENDLOOP.

    IF lines( reports ) < 100.
      EXIT.
    ENDIF.
  ENDDO.
ENDMETHOD.

Sıra bilinçlidir. Rapor kapatılıp SAP'ye kaydedilmeden program durursa, rapor bir sonraki tarih sorgusunda gelmez ve gözden kaçar. Kaydedip kapatmadan durursa rapor bir sonraki turda tekrar gelir; kayıt rapor ID'sine göre yapıldığı için zararı yoktur. Uzun süren bir işte token'ın 30 dakikalık ömrünü de hesaba katın: token hatası alındığında yeniden giriş yapılır.

İK onay listesinde her rapor için ayakta ve yatarak tedavi tarihleri, iş başı kontrol tarihi, vaka türü ve rapor durumu görünür. İK bir raporu onayladığında RaporOnay şu bilgilerle çağrılır:

Servis ayrıca yanlış verilen bir onayı geri almak için OnayIptal, işyerinize ait olmayan bir sigortalının raporunu doğru işyerine aktarmak için PersonelimDegildir ve onaylı raporları tarih aralığıyla listelemek için OnayliRaporlarTarihile metotlarını sunar. Onay listesinde bu iki düzeltme yolunun da bulunması, İK'yı SGK ekranına geri göndermemek için gereklidir.

MUHSGK: Beyanname GİB'e Gider

Aylık prim ve hizmet bilgileri muhtasar beyannameyle birleşik olarak Gelir İdaresi'ne verilir. Bizim yapıda SAP bordrosu beyanname verisini GİB'in yayımladığı şemaya uygun XML olarak üretiyordu; bu dosyayı GİB sistemine ayrı bir program otomatik olarak yüklüyordu. SAP'nin sorumluluğu gönderim değil, gönderilen verinin doğruluğudur:

• Şema dönemle birlikte değişir. GİB beyanname şemasını ve kontrollerini güncelleyebilir. XML'i devretmeden önce geçerli şemaya göre doğrulamak, hatayı yükleme aşamasından üretim aşamasına çeker.
• Eksik gün tutarlılığı. Beyannamedeki eksik gün sayısı ve nedeni, işten ayrılış bildirgesinde bildirilenle ve vizite onaylarıyla çelişmemelidir.
• Mutabakat. Üretilen dosyadaki toplamlar (sigortalı sayısı, prime esas kazanç, gün) bordro sonuçlarıyla karşılaştırılmalı; üretilen dosya, dönemi ve oluşturulma zamanıyla arşivlenmelidir. "Hangi veriyi gönderdik?" sorusunun cevabı bu arşivdir.

Kod Tabloları ve Veri Kalitesi

Sahada uğraştıran ret mesajlarının önemli bir kısmı teknik değil, veri kaynaklıdır. Bildirimlerdeki kodların çoğu SAP'de bire bir karşılığı olmayan, ama SAP verisinden türetilebilen listelerdir. Bu türetmeyi programın içine yazmak yerine, geçerlilik tarihli customizing tablolarında tutmak gerekir; çünkü kod listeleri değişir; 2019'daki iş kolu değişikliği bunun bir örneğidir.

En verimli kontrol, gönderimden önce yapılandır. Meslek kodunun biçimi, kısmi süreli çalışmada gün sayısının 1–29 aralığı, eksik gün girildiyse nedeninin dolu olması, nakilde karşı işyeri sicilinin 26 hane olması gibi kurallar SAP'de, personel işlemi kaydedilirken uyarı olarak verilebilir. Hatayı İK'ya işlemi girdiği anda göstermek, ertesi gün SGK'nın ret mesajını yorumlamaktan çok daha ucuzdur.

İzleme ve Destek

Bu yapının günlük kullanıcısı geliştirici değil, İK'dır. Bu yüzden izleme ekranı da İK için tasarlanmalıdır:

• Her bildirimin durumu, SGK'nın son mesajı ve deneme sayısı tek listede görünmeli; veri hatası alan kayıt, düzeltildikten sonra aynı ekrandan tekrar gönderilebilmelidir.
• Ayar hatası durumundaki kayıtlar (şifre, sicil) e-posta veya iş akışıyla sorumluya gitmelidir; bunlar beklerse aynı işyerindeki bütün bildirimler durur.
• Başarılı bildirgenin PDF'i, saklanan referans koduyla istendiği anda alınabilmelidir.
• Teknik ayrıntı (SOAP hatası, zaman aşımı) uygulama günlüğüne (SLG1), personel numarasıyla aranabilir biçimde yazılmalıdır.

Sık Yapılan Hatalar

Sonuç

SGK entegrasyonunda teknik kısım şaşırtıcı derecede küçüktür: birkaç consumer proxy, bir kuyruk tablosu ve bir izleme ekranı. Asıl iş, doğru veriyi doğru zamanda üretmek ve hatanın türünü ayırt etmektir: şifre hatası bir yöneticiye, veri hatası İK'ya, zaman aşımı ise önce bir sorguya gitmelidir. Bu ayrım yapıldığında İK, SGK ekranlarına değil, SAP'deki tek bir listeye bakar.

SAP'de bu tür kamu ve dış sistem entegrasyonları için sunduğum kapsamı entegrasyon hizmet sayfasında bulabilirsiniz.