SAP Business One Service Layer: Okuma, Yazma ve Oturum Yönetimi

SAP Business One Service Layer nedir?

SAP Business One Service Layer, SAP Business One iş nesnelerini HTTP üzerinden OData protokolüyle sunan resmî programlama arayüzüdür. SAP'nin kılavuzuna göre servis kök adresi https://sunucu:port/b1s/sürüm kalıbındadır, varsayılan olarak HTTPS kullanır; v1 OData 3, v2 OData 4 ile çalışır. Veri JSON ile taşınır ve nesnelerin listesi servisin kendi metadata belgesinden okunur.

SAP Business One'da ikinci resmî arayüz DI API'dir. DI API COM tabanlıdır, yani Windows'a bağlıdır; Service Layer ile nesne ve özellik tanımlarının büyük kısmını paylaşır. Yeni bir ara katman kuruluyorsa varsayılan tercih genellikle Service Layer'dır, çünkü platform bağımsızdır ve web ile mobil uygulamalara doğrudan oturur.

Hangi yama seviyesinde olduğunuz önemlidir. SAP iş ortaklarının sürüm notlarına göre FP 2405 itibarıyla v1 ucu kullanımdan kaldırılmış (deprecated) sayılıyor ve yeni geliştirmeler v2'ye geliyor; kaldırma tarihi açıklanmadı. Yeni bir SAP B1 entegrasyonu v2 üzerine kurulmalıdır; bu durum kurulumunuzda SAP'nin kendi sürüm notlarıyla teyit edilir.

Service Layer oturum yönetimi nasıl yapılır?

Service Layer'da her işlem bir oturum içinde yapılır; oturum Login çağrısıyla açılır, Logout çağrısıyla kapanır. SAP'nin kılavuzundaki örnekte Login isteği şirket veritabanı adını, kullanıcı adını ve şifreyi taşır:

{"CompanyDB": "SIRKET_DB", "UserName": "entegrasyon", "Password": "***"}

Başarılı girişte sunucu B1SESSION çerezini ve yük dengeleyici için ROUTEID çerezini döndürür. Kılavuza göre sonraki her istekte B1SESSION zorunludur; ROUTEID oturumun aynı düğümde kalmasını sağlayarak performansı korur. Logout başarılı olduğunda içerik dönmeyen bir 204 yanıtı gelir.

Oturum ömrü ve yeniden giriş

Login yanıtında SessionTimeout değeri döner; kılavuza göre varsayılan değer 30 dakikadır ve b1s.conf yapılandırma dosyasında "her oturum için boşta kalma süresi" olarak değiştirilebilir. Yani süre kurulumdan kuruluma değişebilir ve koda sabit yazılmamalıdır. Oturum düştüğünde kılavuzdaki hata mesajı "Invalid session or session already timeout." biçimindedir ve HTTP 401 ile döner.

Entegrasyonda doğru davranış şudur:

• Oturumu paylaşın: Her istekte yeniden giriş yapmayın; açık oturumu bir oturum havuzunda tutup yeniden kullanın.
• Bir kez yeniden deneyin: 401 geldiğinde yeniden giriş yapıp aynı isteği yalnızca bir kez tekrarlayın; ikinci 401 bir kimlik veya yetki sorunudur.
• Ayrı kullanıcı açın: Entegrasyon için kişisel değil, yetkisi yalnızca gereken nesnelerle sınırlı bir SAP kullanıcısı tanımlayın.
• Şirket adını doğru yazın: Şirket veritabanı adının büyük/küçük harfe duyarlı olduğu ve v1 ile v2 oturumlarının karıştırılmaması gerektiği, kurulum günü en sık atlanan iki ayrıntıdır.

SAP'nin kılavuzuna göre 10.0 FP 2305'ten itibaren Active Directory etkinleştirilip kullanıcılar bağlandığında Windows etki alanı kullanıcısıyla da giriş yapılabiliyor. Hangi kimlik doğrulama yönteminin kullanılacağı kurulumun güvenlik politikasına göre belirlenir.

Service Layer ile okuma: OData sorgusu ve SQL Query

Okuma için iki yol vardır: nesneler üzerinde OData sorgusu ve 10.0 FP 2011'den itibaren eklenen SQL Query özelliği. OData sorgusu, iş ortağı kartları, siparişler ya da stok kalemleri gibi nesneleri filtreleyip seçilen alanlarla getirir; sonuçlar sayfalanır ve sonraki sayfa bir bağlantıyla istenir.

SQL Query daha esnek bir okuma imkânı sunar ama sınırları belgede açıkça yazılıdır:

• İzin listesi: Sorgulanabilen tablolar b1s_sqltable.conf dosyasındaki izin listesiyle sınırlıdır. Kılavuza göre listede olmayan tablolar desteklenmez ve listeye tablo eklemek destek kapsamı dışındadır.
• SQL alt kümesi: Desteklenen anahtar kelimeler, MS SQL ile HANA arasındaki farklar gözetilerek seçilmiş bir alt kümedir: seçim, filtre, gruplama, sıralama gibi sorgu ifadeleri.
• Sayfalama zorunlu: Sorgu sonucu sayfalar hâlinde döner; büyük kümeyi tek seferde çekmek mümkün değildir.
• Harf duyarlılığı: Tablo ve kolon adları veritabanında tanımlandığı biçimde yazılmalıdır.

SQL Query bir yazma kapısı değildir. SAP'nin bu özelliği tanıtan yazısında da veritabanının SQL sorgularıyla değil, yalnızca sunulan API'ler (DI API ya da Service Layer) üzerinden değiştirilebileceği vurgulanıyor.

Ağır ve sık tekrarlanan rapor sorguları için Service Layer'ı her açılışta yormak yerine, zamanlanmış olarak beslenen ayrı bir rapor deposu kurmak hem paneli hızlandırır hem de SAP kullanıcılarının performansını korur.

Service Layer ile yazma: belge oluşturma, güncelleme ve toplu işlem

Yazma, ilgili nesnenin koleksiyonuna POST ile yeni kayıt göndermek ve PATCH ile mevcut kaydı güncellemekle yapılır. Bu yoldan geçen her işlemde SAP'nin kendi iş mantığı çalışır: zorunlu alan kontrolü, belge-satır ilişkisi, numaralandırma ve muhasebe bağlantıları. Hata varsa anlamlı bir mesaj döner ve kayıt oluşmaz.

PATCH ile PUT farkı: sessiz veri kaybı tuzağı

SAP'nin kılavuzu güncelleme için genellikle PATCH'i öneriyor ve farkı açıkça yazıyor: PATCH istekte verilmeyen alanları olduğu gibi bırakır, PUT ise onları varsayılan değere ya da boşa çeker. Yalnızca adresi güncellemek için PUT gönderen bir entegrasyon, istekte yer almayan alanları farkında olmadan silebilir.

Kılavuzdaki bir not daha önemli: salt okunur alanlar (örneğin iş ortağı kodu) güncellenemez ve istekte gönderilirse sessizce yok sayılır. Hata dönmediği için entegrasyon güncellemenin yapıldığını sanabilir; bu yüzden kritik güncellemelerden sonra kaydı yeniden okuyup karşılaştırmak iyi bir alışkanlıktır.

Toplu işlem ve değişiklik kümeleri

Service Layer, birden fazla işlemi tek bir HTTP isteğinde gönderen toplu işlem ($batch) özelliğini destekler. Kılavuza göre toplu istek içindeki işlemler sırayla çalışır. Değişiklik kümesi (change set) ise atomik bir iş birimidir: içindeki tek bir alt istek başarısız olursa kümenin tamamı geri alınır. Örneğin bir sipariş ve ona bağlı bir başka kayıt birlikte oluşmalıysa aynı değişiklik kümesine konur.

Eşzamanlı güncelleme ve mükerrer kayıt

10.0 FP 2102'den itibaren Service Layer ETag mekanizmasını destekler. Okunan kaydın ETag değeri güncelleme isteğinde If-Match başlığıyla gönderildiğinde, kayıt o arada başka biri tarafından değiştirilmişse güncelleme reddedilir. Bu, iki sistemin aynı kaydı üst üste yazmasını önler.

Mükerrer kayıt için ise yerleşik bir anahtar beklenmemelidir. Dış sistemin sipariş numarası, SAP belgesinde izlenebilir bir alanda (kurulumda seçilen bir referans alanı ya da kullanıcı tanımlı alan) taşınır ve her POST'tan önce bu numarayla sorgulanır. Cevabı alınamayan gönderim doğrudan tekrarlanmaz; önce kaydın oluşup oluşmadığı kontrol edilir.

Doğrudan tabloya yazmak neden desteklenmiyor?

SAP Business One'da sistem tablolarına doğrudan ekleme, güncelleme ve silme yapılması SAP tarafından desteklenmez. SAP'nin veri değiştirme rehberine göre bu kural SDK üzerinden çalıştırılan doğrudan sorguları da kapsar. Desteklenmeyen bir kullanım biçimine geçmek, kurulumun destek kapsamı açısından da risk doğurur.

Tanımlı bir istisna var: iki tipteki kullanıcı tanımlı tablolar, "No Object" ve "No Object with Auto Increment". Entegrasyonun kendi eşleme kayıtlarını ve işlem günlüklerini SAP tarafında tutması gerekiyorsa bu alan kullanılabilir. İş belgesi oluşturmak için ise yol her zaman nesne arayüzüdür.

Doğrudan yazmanın sonucu genellikle anında görünmez. Belge tablosuna satır yazılır ama ilgili muhasebe kaydı oluşmaz; tutarsızlık aylar sonra mutabakatta ortaya çıkar. Bu yüzden "daha hızlı olsun" gerekçesiyle doğrudan yazma önerilmez.

SAP B1 webhook ve olay bildirimi: 2026 itibarıyla durum

SAP'nin Service Layer kılavuzuna göre SAP Business One 10.0 FP 2602'den itibaren Service Layer webhook desteği sunuyor. Webhook, SAP'de bir olay olduğunda (örneğin satış siparişi oluşturulduğunda) tanımlı adrese bildirim gönderir; entegrasyonun sürekli "yeni sipariş var mı" diye sormasına gerek kalmaz.

Kılavuzdan entegrasyon tasarımını etkileyen ayrıntılar:

• Varsayılan kapalı: Webhook her şirket için varsayılan olarak kapalıdır; kılavuzdaki adımda şirketin yönetim bilgisini güncelleyen bir Service Layer çağrısıyla açılır.
• Ayrı servis: Bildirimleri Webhook Messenger Service adlı ayrı bir bileşen gönderir; kurulu ve çalışır durumda olmalıdır.
• HTTPS şartı: Bildirim adresi HTTPS olmalıdır; uç noktanın SSL sertifikası varsayılan olarak doğrulanır ve kılavuz canlı ortamda bu doğrulamanın açık kalmasını öneriyor.
• Tekrar deneme: Başarısız gönderim en çok beş kez, 2 saniyeden başlayıp her seferinde ikiye katlanan aralıklarla tekrar denenir.
• Mükerrer bildirim: Geçici hatalardaki tekrar denemeler aynı olay için birden fazla bildirim üretebilir; kılavuz alıcı sistemin idempotent olmasını ve olay kimliğini kullanmasını öneriyor.
• Sıra: Tek şirket içinde olay sırası korunmaya çalışılır; birden çok şirketten bildirim alan bir webhook için sıra garanti edilmez.

FP 2608 ile bildirim içeriğine ek nesne alanları eklenebiliyor ve olaylar bir formül ifadesiyle filtrelenebiliyor.

Webhook kullanılsa bile, bildirim alıcısının kapalı olduğu süre için periyodik bir kontrol turu açık bırakılmalıdır. Kılavuz kaçırılan bildirimler için ayrıca bir yeniden oynatma (replay) işlevi tanımlıyor.

Sıkça Sorulan Sorular

SAP Business One Service Layer ile DI API arasındaki fark nedir?

Service Layer HTTP üzerinden çalışan, OData tabanlı ve platform bağımsız bir arayüzdür; DI API ise COM tabanlıdır ve Windows'a bağlıdır. İkisi nesne ve özellik tanımlarının büyük kısmını paylaşır. Yeni web ve mobil entegrasyonlar için genellikle Service Layer tercih edilir; mevcut bir DI API yapısı varsa o korunabilir.

Service Layer oturumu neden sık sık düşüyor?

Oturum, yapılandırmada dakika olarak tanımlanan boşta kalma süresi dolunca düşer; SAP'nin kılavuzuna göre varsayılan değer 30 dakikadır. Entegrasyon her istekte yeni oturum açmak yerine oturumu paylaşmalı, 401 aldığında bir kez yeniden giriş yapıp isteği tekrarlamalıdır. B1SESSION çerezinin her istekte gönderildiği de kontrol edilmelidir.

Service Layer SQL Query ile SAP'ye kayıt yazılabilir mi?

Hayır. SQL Query okuma için tasarlanmıştır; kılavuza göre izin listesindeki tablolarla ve SQL'in sınırlı bir sorgu alt kümesiyle çalışır. Kayıt oluşturma ve güncelleme Service Layer nesneleri ya da DI API üzerinden yapılır.

SAP Business One webhook destekliyor mu?

SAP'nin Service Layer kılavuzuna göre 10.0 FP 2602'den itibaren destekliyor; webhook şirket bazında varsayılan olarak kapalıdır ve Webhook Messenger Service'in çalışıyor olması gerekir. Daha eski bir yama seviyesindeyseniz değişiklikler zamanlanmış sorgulamayla yakalanır. Kurulumunuzun yama seviyesi SAP iş ortağınızla teyit edilir.

Service Layer kullanımı için ek lisans gerekir mi?

Service Layer ya da DI API kullanımı için ayrı bir lisans veya iş ortaklığı şartı olduğuna dair doğrulanmış bir bilgiye ulaşmadık. Bu yüzden ne gerekir ne gerekmez diyoruz; kurulumunuzdaki durum mevcut SAP iş ortağınızla teyit edilir.

SAP B1 entegrasyonunuz için sonraki adım

SAP Business One'ı değiştirmeden web sitenizi, saha uygulamanızı ya da depo ekranınızı Service Layer üzerinden bağlamak istiyorsanız işe yama seviyenizi, veritabanı hattınızı (MS SQL ya da HANA) ve akışlarınızı netleştiren keşifle başlıyoruz. SAP iş ortağı değiliz; lisans, kurulum ve yükseltme mevcut iş ortağınızda kalır, biz onun yanında belgelenmiş arayüzler üzerinden özel geliştirme yaparız. Kapsam keşifte netleşir, fiyat sabittir ve sözleşmede yazılır; teslim sonrası 15 gün içinde çıkan hataları ücretsiz düzeltiriz. Ücretsiz online keşif görüşmesi için iletişime geçin; isterseniz WhatsApp'tan da yazabilirsiniz.