Xpensio — SAP Entegrasyon Teknik Kılavuzu

1 Genel Mimari

1.1 Adapter Kalıbı (Factory Pattern)

Xpensio, tüm ERP/HR entegrasyonlarını Adapter Factory kalıbıyla yönetir. Ortam değişkenine (SAP_TYPE, IDENTITY_PROVIDER) göre uygun adapter otomatik seçilir:

┌─────────────────────── Xpensio Backend (NestJS) ───────────────────────┐
│                                                                         │
│  SapAdapterFactory                    IdentityAdapterFactory            │
│  ├─ ECC     → SapEccAdapter           ├─ SAP_HCM     → SapHcmAdapter   │
│  ├─ S4_ONPREM → SapS4OnPremAdapter    ├─ SAP_S4_ONPREM → S4OnPrem…     │
│  ├─ S4_CLOUD  → SapS4CloudAdapter     ├─ SAP_S4_CLOUD  → S4Cloud…      │
│  └─ MOCK      → SapMockAdapter        ├─ AZURE_AD    → AzureAdAdapter  │
│                                        ├─ LDAP        → LdapAdapter     │
│                                        └─ MOCK        → MockAdapter     │
└─────────────────────────────────────────────────────────────────────────┘

1.2 FI Posting (Masraf Muhasebeleştirme) Adapterleri

1.3 HR / Kimlik Sync Adapterleri

1.4 Platform Karşılaştırma Matrisi

2 Ortak Referanslar

2.1 Kullanıcı / HR Alan Eşleşmesi

2.2 Masraf → FI Mapping

2.3 Grade → Rol Eşleştirmesi

2.4 Çok Seviyeli Onay Zinciri

Grade Limit Örnekleri: G7–12 → 10.000 TRY  |  G13–15 → 25.000 TRY  |  G16–18 → 50.000 TRY

2.5 Vergi & Ödeme Kodları

3 SAP ECC 6.0 Entegrasyonu

IDENTITY_PROVIDER=SAP_HCM SAP_TYPE=ECC ABAP 7.0+

3.1 Kurulum Sırası

3.2 DDIC Nesneleri (SE11)

ZEXP_AUTH — Kimlik Doğrulama

ZEXP_POST_LOG — FI Posting Log

ZEXP_CFG — Genel Yapılandırma

ZEXP_CFG_GL — Masraf Türü → GL Hesap Eşleşme

ZEXP_USERS — Kullanıcı Tablosu

ZEXP_GRADE_POLICIES — Grade / Politika Tablosu

ZEXP_COMPANY — Şirket Yapılandırması

ZEXP_S_POST_PAYLOAD — POST_EXPENSE Giriş Yapısı

COMPANYCODE (BUKRS), EMPLOYEEID (CHAR 20), EMPLOYEENAME (CHAR 100),
EXPENSEDATE (CHAR 8), POSTINGDATE (CHAR 8), DOCUMENTTYPE (BLART),
NETAMOUNT (DEC 13,2), TAXAMOUNT (DEC 13,2), GROSSAMOUNT (DEC 13,2),
TAXCODE (CHAR 2), TAXGLACCOUNT (SAKNR), CURRENCY (WAERS),
GLACCOUNT (SAKNR), COSTCENTER (KOSTL), PROJECTCODE (PS_POSID),
DESCRIPTION (CHAR 50), REFERENCE (CHAR 16), DEBUGMODE (CHAR 1)

3.3 ABAP — ZCL_EXPENSE_POSTING (FI Belge Oluşturma)

Interface: IF_HTTP_EXTENSION  |  SICF: /sap/bc/zexpense/post_expense

HANDLE_REQUEST — Ana Giriş Noktası

METHOD if_http_extension~handle_request.
  " 1. HTTP metod kontrolü (sadece POST)
  " 2. Auth doğrulama: ZEXP_AUTH → username + password
  " 3. JSON body → ZEXP_S_POST_PAYLOAD'a parse
  " 4. Zorunlu alan kontrolü (companycode, glaccount, netamount…)
  " 5. POST_EXPENSE çağır
  " 6. JSON response: { STATUS, BELNR, GJAHR, MESSAGE }
  " 7. ZEXP_POST_LOG'a loglama
ENDMETHOD.

POST_EXPENSE — BAPI Çağrısı

METHOD post_expense.
  " ── HEADER ──
  ls_header-comp_code  = is_payload-companycode.
  ls_header-doc_date   = is_payload-expensedate.
  ls_header-pstng_date = is_payload-postingdate.
  ls_header-doc_type   = is_payload-documenttype.
  ls_header-ref_doc_no = is_payload-reference.
  ls_header-currency   = is_payload-currency.
  ls_header-bus_act    = 'RFBU'.

  " ── KALEM 1: Gider GL (Borç) ──
  ls_accgl-gl_account = is_payload-glaccount.
  ls_accgl-tax_code   = is_payload-taxcode.
  ls_accgl-costcenter = is_payload-costcenter.
  ls_curr-amt_doccur  = is_payload-netamount.

  " ── KALEM 2: KDV GL (Borç, sadece KDV > 0) ──
  IF is_payload-taxamount > 0.
    ls_acctax-gl_account = is_payload-taxglaccount.
    ls_curr-amt_doccur   = is_payload-taxamount.
  ENDIF.

  " ── KALEM 3: Personel Cari (Alacak) ──
  ls_accpay-vendor    = is_payload-employeeid.
  ls_curr-amt_doccur  = - is_payload-grossamount.

  " ── BAPI ÇAĞRISI ──
  IF is_payload-debugmode = 'X'.
    CALL FUNCTION 'BAPI_ACC_DOCUMENT_CHECK' ...
  ELSE.
    CALL FUNCTION 'BAPI_ACC_DOCUMENT_POST' ...
  ENDIF.

  " Hata kontrolü
  IF RETURN tablosunda E tipi mesaj var.
    CALL FUNCTION 'BAPI_TRANSACTION_ROLLBACK'.
    ev_status = 'E'.  ev_message = hata metni.
  ELSE.
    CALL FUNCTION 'BAPI_TRANSACTION_COMMIT' EXPORTING wait = 'X'.
    ev_status = 'S'.  ev_belnr = belge no.
  ENDIF.
ENDMETHOD.

3.4 ABAP — ZCL_EXPENSE_USER_LIST (HR Sync)

SICF: /sap/bc/zexpense/user_list

METHOD if_http_extension~handle_request.
  " ── Auth kontrolü (ZEXP_AUTH) ──
  " GET /           → ZEXP_USERS tablosundan JSON döndür
  " GET ?action=SYNC → PA0001/PA0002'den çekip ZEXP_USERS güncelle
  "   - Mevcut kayıt: UPDATE
  "   - Yeni kayıt:   INSERT
  "   - HR'da yok:    ISACTIVE = '0'
  " JSON Response: { EMPLOYEE_COUNT, SYNCED, INSERTED, DEACTIVATED }
ENDMETHOD.

3.5 SICF Servisleri

Transaction: SICF → /sap/bc/zexpense/
  /post_expense  → Handler: ZCL_EXPENSE_POSTING
  /user_list     → Handler: ZCL_EXPENSE_USER_LIST
  Authentication: HTTP Basic (SAP standart)

3.6 Kullanıcı & Yetkilendirme

SU01 — Sistem Kullanıcısı

PFCG — Yetkilendirme Nesneleri

3.7 FI Uyarlamalar

3.8 Bağlantı Yapılandırması (DB Encrypted)

Admin Panel → ERP Ayarları

Minimal .env (Sadece sistem seviyesi)

# Sadece şifreleme anahtarı .env'de tutulur
ENCRYPTION_KEY=<64_HEX_KARAKTER>   # 32-byte AES key

3.9 Test Prosedürü

A) SAP Tarafı Test (SE38)

REPORT ZTEST_EXPENSE_POST.
" 1. ZEXP_S_POST_PAYLOAD yapısını doldur
" 2. DEBUGMODE = 'X' ile BAPI_ACC_DOCUMENT_CHECK çağır
" 3. RETURN tablosunu kontrol et → hata yoksa DEBUGMODE = '' ile tekrarla
" 4. BELNR alındı → FB03 ile belgeyi doğrula

B) REST Client Testi

curl -X POST http://<SAP_HOST>:<PORT>/sap/bc/zexpense/post_expense \
  -H "Content-Type: application/json" \
  -u "<USER>:<PASS>" \
  -d '{
    "COMPANYCODE":"<BUKRS>","EMPLOYEEID":"<VENDOR_NO>",
    "EXPENSEDATE":"20260324","POSTINGDATE":"20260324",
    "DOCUMENTTYPE":"SA","NETAMOUNT":100,"TAXAMOUNT":0,
    "GROSSAMOUNT":100,"TAXCODE":"V0","CURRENCY":"TRY",
    "GLACCOUNT":"<GL>","COSTCENTER":"<KY>",
    "DESCRIPTION":"Test","REFERENCE":"TEST-001","DEBUGMODE":"X"
  }'

C) Xpensio Uçtan Uca Test

1. POST /api/v1/identity/sync → Kullanıcılar SAP'den çekildi
2. Dashboard → Yeni masraf oluştur → Onayla
3. Muhasebe → SAP'ye Gönder → Durum: POSTED_TO_SAP
4. SAP FB03 ile belge numarasını doğrula

3.10 Kurulum Kontrol Listesi

SAP Tarafı

• DDIC nesneleri oluşturuldu ve aktive edildi (SE11)
• ZCL_EXPENSE_POSTING sınıfı oluşturuldu (SE24)
• ZCL_EXPENSE_USER_LIST sınıfı oluşturuldu (SE24)
• SICF servis node'ları aktive edildi
• ZEXP_API_USER sistem kullanıcısı oluşturuldu (SU01)
• Z_EXPENSE_API_ROLE rol atandı (PFCG)
• ZEXP_AUTH tablosu dolduruldu (SM30)
• ZEXP_CFG + ZEXP_CFG_GL tabloları dolduruldu (SM30)
• GL hesaplar, masraf yerleri, vergi kodları tanımlandı
• Personel → Vendor FI eşleşmesi yapıldı
• DEBUGMODE=X ile test postu başarılı
• Gerçek posting ile BELNR alındı ve FB03'te doğrulandı

Xpensio Tarafı

• Admin Panel → ERP Ayarları üzerinden SAP bağlantı bilgileri girildi
• Identity sync başarılı (POST /api/v1/identity/sync)
• Grade dağılımı ve manager zinciri doğrulandı
• Test masrafı → Onayla → SAP POST → POSTED_TO_SAP

4 S/4HANA On-Premise

IDENTITY_PROVIDER=SAP_S4_ONPREM SAP_TYPE=S4_ONPREM ABAP 7.50+

4.1 ECC ile Temel Farklar

4.2 FI Posting Yaklaşımları

Yaklaşım A — BAPI Compat (Önerilen, En Hızlı Kurulum)

S/4HANA BAPI_ACC_DOCUMENT_POST'u desteklemeye devam eder. Bölüm 3.2–3.7'deki ECC ABAP kodu ve DDIC nesneleri birebir çalışır. Tek değişiklik:

SAP_TYPE=S4_ONPREM   # (ECC yerine)

Yaklaşım B — OData v4 Journal Entry API

ABAP geliştirme yapmadan doğrudan S/4HANA standart OData servisi kullanılır:

POST /sap/opu/odata/sap/API_JOURNALENTRYITEMBASIC_SRV/JournalEntryItem
Authorization: Basic <base64>
Content-Type: application/json

{
  "CompanyCode": "<BUKRS>",
  "PostingDate": "2026-03-24",
  "JournalEntryType": "SA",
  "to_JournalEntryItem": {
    "results": [
      { "GLAccount": "<GIDER_GL>", "DebitCreditCode": "S",
        "AmountInTransactionCurrency": "100.00", "CostCenter": "<KY>" },
      { "GLAccount": "<KARSI_GL>", "DebitCreditCode": "H",
        "AmountInTransactionCurrency": "120.00" }
    ]
  }
}

4.3 HR / Kimlik Sync

Seçenek A — HCM Compat: HCM modülü mevcutsa → Bölüm 3.4'teki ABAP user_list aynen uygulanır.

Seçenek B — OData EmployeeEntity:

GET /sap/opu/odata/sap/HCMFAB_EMPLOYEE_SRV/EmployeeCollection
  ?$select=EmployeeId,FirstName,LastName,EmailAddress,
           OrganizationalUnit,Position,Grade
  &$filter=IsActive eq true

Bu yaklaşımda ABAP geliştirme gerekmez; IDENTITY_PROVIDER=SAP_S4_ONPREM ile otomatik seçilir.

4.4 Bağlantı Yapılandırması (DB Encrypted)

Bölüm 3.8'deki yapı aynen geçerlidir. Admin Panel → ERP Ayarları:

4.5 Kontrol Listesi

• BAPI compat: ECC Bölüm 3.10 kontrol listesinin tamamı uygulandı
• OData: /IWFND/MAINT_SERVICE servisleri aktive edildi
• HTTPS sertifikası SAP ICM'e yüklendi (STRUST)
• Universal Journal (ACDOCA) konfigürasyonu doğrulandı
• ENV SAP_TYPE=S4_ONPREM olarak ayarlandı
• HR sync (HCM veya OData) testi başarılı
• FI Posting testi başarılı, BELNR alındı

5 S/4HANA Cloud + SuccessFactors

IDENTITY_PROVIDER=SAP_S4_CLOUD SAP_TYPE=S4_CLOUD ABAP Gerekmez

5.1 OAuth 2.0 Kurulumu (XSUAA / BTP)

1. BTP Cockpit → Subaccount → Service Marketplace → S/4HANA Cloud aboneliği
2. Service Instance oluştur → clientid ve clientsecret al
3. Scope'lara Journal Entry API erişimi ekle

Token Endpoint

POST https://<XSUAA>.authentication.<REGION>.hana.ondemand.com/oauth/token
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials
&client_id=<CLIENT_ID>
&client_secret=<CLIENT_SECRET>

5.2 FI Posting — Journal Entry API

Adım 1: CSRF Token Al

GET /sap/opu/odata/sap/API_JOURNALENTRYITEMBASIC_SRV/$metadata
Authorization: Bearer <TOKEN>
x-csrf-token: Fetch

→ Response Header: x-csrf-token: <CSRF_VALUE>

Adım 2: Journal Entry Oluştur

POST /sap/opu/odata/sap/API_JOURNALENTRYITEMBASIC_SRV/JournalEntryItem
Authorization: Bearer <TOKEN>
x-csrf-token: <CSRF_VALUE>
Content-Type: application/json

{
  "CompanyCode": "<BUKRS>",
  "AccountingDocumentType": "SA",
  "DocumentReferenceID": "<EXPENSE_ID>",
  "PostingDate": "2026-03-24",
  "to_JournalEntryItem": {
    "results": [
      { "GLAccount": "<GIDER_GL>", "DebitCreditCode": "S",
        "AmountInTransactionCurrency": "100.00",
        "CostCenter": "<KY>", "TaxCode": "V5" },
      { "GLAccount": "<KARSI_GL>", "DebitCreditCode": "H",
        "AmountInTransactionCurrency": "120.00",
        "Vendor": "<TEDARIKCI_NO>" }
    ]
  }
}

5.3 HR Sync — SuccessFactors Employee Central API

SuccessFactors OAuth 2.0

POST https://<SF_HOST>/oauth/token
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials
&client_id=<SF_CLIENT_ID>
&client_secret=<SF_CLIENT_SECRET>
&company_id=<SF_COMPANY_ID>

Çalışan Listesi

GET https://<SF_HOST>/odata/v4/sfsf/User
  ?$select=userId,firstName,lastName,email,department,
           jobTitle,managerId,payGrade
  &$filter=status eq 'active'
  &$top=1000
Authorization: Bearer <SF_TOKEN>

Departman Listesi

GET https://<SF_HOST>/odata/v4/sfsf/FODepartment
  ?$select=departmentId,name,headOfUnit,parentUnit
  &$filter=effectiveStatus eq 'A'

Pozisyon Listesi

GET https://<SF_HOST>/odata/v4/sfsf/Position
  ?$select=positionCode,externalName,payGrade
  &$filter=effectiveStatus eq 'A'

5.4 SuccessFactors → Xpensio Alan Eşleşmesi

5.5 Bağlantı Yapılandırması (DB Encrypted)

Bölüm 3.8'deki yapı aynen geçerlidir. Admin Panel → ERP Ayarları:

5.6 Kontrol Listesi

SAP BTP / S/4HANA Cloud

• BTP Subaccount oluşturuldu
• OAuth2 client oluşturuldu, clientid/secret alındı
• Journal Entry API yetkisi service binding'e eklendi
• Token alınıyor + OData $metadata çekilebiliyor
• Test journal entry başarılı

SuccessFactors

• EC Admin: API User / OAuth2 Client oluşturuldu
• Employee, FODepartment, Position OData erişimi verildi
• API test: User koleksiyonundan aktif çalışanlar listeleniyor
• managerId → email resolve çalışıyor

Xpensio

• Admin Panel → ERP Ayarları üzerinden bağlantı bilgileri girildi (DB encrypted)
• S/4 Cloud token yenileme çalışıyor (expire öncesi otomatik)
• SF token yenileme çalışıyor
• Identity sync başarılı, kullanıcılar + departmanlar + pozisyonlar oluştu
• FI Posting testi → POSTED_TO_SAP durumu OK

5b Kurumsal Kart Mutabakatı & UMSKZ Akışı

Xpensio, kurumsal kredi kartı ekstresini içeri alarak satırları masraf kayıtlarıyla otomatik eşler ve eşleşmiş satırları mevcut SAP FI Push akışına teslim eder. Banka tarafına ek bir RFC veya web servisi gerekmez — eşleşmiş kayıtlar BAPI_ACC_DOCUMENT_POST üzerinden standart yolla post edilir.

5b.1 Muhasebe Yansıması (UMSKZ Eşlemesi)

5b.2 İş Akışı

1. Ekstre import: Banka CSV/PDF/Excel dosyası Finance tarafından yüklenir. Parser tarih/tutar/merchant/currency çıkarır, satırlar UNMATCHED olarak kayıt edilir.
2. Auto-match: Skor algoritması (tarih ±2 gün, tutar ±%0.5–2 FX, merchant fuzzy, fatura/VKN bonus) ≥ 80 olan satırları masrafa bağlar.
3. Manuel + bölme: Kalan satırlar Finance tarafından elle bağlanır veya N parçaya bölünür.
4. SAP Push: Bağlanmış masraf zaten standart onay zincirini geçmişse mevcut SAP FI Push pipeline'ı tetiklenir; UMSKZ kart tipinden türetilir.

5b.3 Tenant Başına Banka Şablonu

Müşterinin kullandığı banka standart Garanti/İş/Akbank parserlarımızdan farklıysa, admin "CSV Şablonları" sekmesinden kolon eşleştirmesi tanımlar:

• dateCol — header satırındaki tarih kolonunun adı
• amountCol — tutar kolonu adı
• descriptionCol — açıklama kolonu (opsiyonel)
• skipRows — header öncesi atlanacak satır sayısı (banka logo/başlık satırları için)

Yükleme dropdown'unda "Özel: {şablon adı}" olarak görünür ve seçilince bankFormat=custom:NAME olarak iletilir.

5b.4 Çok Döviz

USD/EUR/GBP harcamalar canlı kurla TRY karşılığına çevrilerek karşılaştırılır. Cross-currency tolerans %2 (TRY/TRY için %0.5). Kur kaynağı: FxRateService — open.er-api.com (1 saatlik cache + admin manuel override).

6 Güvenlik & Ağ Gereksinimleri

6.1 Ağ & Firewall

6.2 Kimlik Bilgileri Yönetimi — erpConfig AES-256-GCM

• SAP kullanıcı adı, şifre, client secret gibi hassas bilgiler .env dosyasında tutulmaz
• Tüm SAP bağlantı bilgileri veritabanında Organization.erpConfig alanında AES-256-GCM ile şifrelenerek saklanır
• Şifreleme anahtarı (ENCRYPTION_KEY) tek .env parametresidir — production'da Docker Secret veya K8s Secret olarak yönetilir
• Setup Wizard veya Admin Panel → ERP Ayarları üzerinden girilen bilgiler otomatik şifrelenir
• API'den config okunurken password/secret alanları otomatik maskelenir (••••••••)
• Config güncelleme sırasında maskeli alanlar korunur (mevcut değer override edilmez)
• Kaynak koda credential bilgisi asla gömülmez

Şifreleme Akışı

Şifrelenen Alanlar (örnek erpConfig payload)

{
  "sapType": "S4_ONPREM",
  "baseUrl": "https://sap.musteri.com:44300",
  "username": "XPENSIO_API",
  "password": "•••••••• (encrypted at rest)",
  "clientSecret": "•••••••• (encrypted at rest)",
  "client": "100",
  "language": "TR",
  "ca": "-----BEGIN CERTIFICATE----- ... (encrypted at rest)",
  "glConfig": {
    "byCompany": {
      "1000": {
        "expenseGl": "770000",
        "taxGl": "190000",
        "expenseCostCenter": "10001",
        "paymentConfig": { "umskz": "0", "payableGl": "335000" }
      }
    }
  }
}

Güvenlik Kontrolleri

• API yanıtı: GET /admin/organization → password/secret alanları otomatik maskelenir; clear-text hiçbir endpoint'ten dönmez
• Audit log: Her erpConfig değişikliği AuditLog'a (user + timestamp + targetField) yazılır
• Test ortamı: Dev'de ENCRYPTION_KEY ayrı (basit / sabit), production key dev/staging'e asla kopyalanmaz
• Anahtar rotasyonu prosedürü: (1) Tüm org'lar için eski anahtarla erpConfig decrypt → JSON; (2) yeni anahtarla encrypt → DB güncelle; (3) ENCRYPTION_KEY env güncellenip restart

6.3 SAP Tarafı Güvenlik

• TLS: SICF dahil tüm HTTP çağrıları HTTPS olmalı (SAP ICM SSL sertifikası — STRUST)
• IP Kısıtlaması: SICF servis erişimini sadece Xpensio backend IP'sine kısıtlayın
• Least Privilege: API kullanıcısına yalnızca gerekli yetkilendirme nesneleri verilmeli
• Parola Politikası: API kullanıcısı parolası 90 günde bir rotasyona tabi tutulmalı
• Denetim: SAP SM21 (system log) / ST22 (dump analizi) loglarını periyodik kontrol edin
• API Kullanıcısı: System tipinde oluşturun (Dialog değil), interaktif oturum açmasın