SAP B1 Service Layer Nedir? İlk API Çağrısı Rehberi

Service Layer, SAP Business One'ın HANA ve SQL sürümlerinde çalışan resmi REST API katmanıdır: iş nesnelerini (BusinessPartners, Items, Orders, Invoices…) OData protokolü üzerinden HTTPS ile dışarı açar. Oturum bazlı authentication ile çalışır; login çağrısından dönen session çerezini sonraki isteklerde taşırsınız. Eski COM tabanlı DI API'nin aksine platform bağımsızdır — entegrasyonu Node.js, .NET, Python, PHP, hangi stack'te yazıyorsanız oradan çağırırsınız.

Bu yazı, SAP entegrasyon projelerinde her gün kullandığımız katmanı geliştirici gözüyle anlatıyor: mimari, authentication, ilk çağrı ve sahada öğrendiğimiz tuzaklar. Hedef okur, B1'e dışarıdan bağlanacak bir sistem — e-ticaret, WMS, banka, özel yazılım — geliştiren ekip.

Service Layer mimarisi: ne, nerede çalışır

Service Layer, B1 sunucusunun yanında koşan bir web servis katmanıdır. HANA sürümünde ürünle birlikte gelir; SQL Server sürümlerinde de güncel sürümlerle birlikte kullanılabilir hale geldi. Mimaride üç şey bilmeniz yeterli:

• Load balancer + node yapısı: İstekler bir load balancer üzerinden birden çok Service Layer node'una dağıtılır. Yoğun entegrasyonlarda node sayısı ayarlanabilir bir ölçekleme noktasıdır.
• OData protokolü: Nesneler OData v3/v4 uçlarından sunulur. $filter, $select, $top, $skip, $orderby gibi standart sorgu parametreleri çalışır — SELECT * mantığıyla veri çekmek yerine alan bazlı sorgu yazarsınız.
• DI API ile aynı iş kuralları: Service Layer, çekirdekteki iş mantığını kullanır. Yani API'den kestiğiniz fatura, ekrandan kesilen faturayla aynı doğrulamalardan geçer; stok yetersizse ekranda ne hata alıyorsanız API'de de onu alırsınız. Entegrasyonun güvenilirliği buradan gelir — veritabanına doğrudan yazmak gibi tehlikeli kısayollara ihtiyaç kalmaz.

Sahada hâlâ SQL'e doğrudan INSERT atan "entegrasyon"larla karşılaşıyoruz; bunlar iş kurallarını atladığı için stok ve muhasebe tutarlılığını sessizce bozar. Kural basit: B1'e yazan her satır Service Layer'dan (veya DI API'den) geçer, doğrudan tablo yazmak yalnızca felaket senaryosu üretir.

Authentication: login, session ve timeout

Service Layer oturum bazlıdır. Üç bilgiyle login olursunuz: veritabanı adı (CompanyDB), kullanıcı adı ve parola. Dönen B1SESSION çerezi sonraki tüm isteklerde taşınır.

POST https://b1sunucu:50000/b1s/v1/Login
Content-Type: application/json

{
  "CompanyDB": "SBODEMOTR",
  "UserName": "entegrasyon.user",
  "Password": "********"
}

Başarılı cevap, oturum kimliğini hem gövdede hem Set-Cookie başlığında döner:

{
  "odata.metadata": "https://b1sunucu:50000/b1s/v1/$metadata#B1Sessions/@Element",
  "SessionId": "3f2a61b2-...",
  "Version": "1000200",
  "SessionTimeout": 30
}

Pratikte dikkat ettiğimiz üç kural:

1. Entegrasyona özel kullanıcı açın. Gerçek bir personelin hesabıyla entegrasyon koşturmak, hem lisans hem iz sürme açısından sorun üretir; yetkileri entegrasyonun ihtiyacına göre daraltılmış ayrı bir kullanıcı tanımlarız.
2. Session'ı isteğe değil havuza bağlayın. Her istekte yeniden login olmak Service Layer'ı gereksiz yorar. Oturumu açıp SessionTimeout süresi (varsayılan 30 dakika) boyunca yeniden kullanmak, süre dolunca yenilemek doğru desendir.
3. 401'i yeniden-login akışıyla karşılayın. Oturum sunucu tarafında her an düşebilir. İstemcinizde "401 aldıysan bir kez login olup isteği tekrarla" mantığı yoksa, entegrasyonunuz gece yarısı sessizce durur.

İlk çağrı: iş ortağı sorgulama ve sipariş oluşturma

Login sonrası ilk okuma çağrısı için BusinessPartners uygun bir başlangıç. OData sorgu parametreleriyle yalnızca ihtiyaç duyduğunuz alanları çekin:

GET https://b1sunucu:50000/b1s/v1/BusinessPartners?$select=CardCode,CardName,CurrentAccountBalance&$filter=CardType eq 'cCustomer'&$top=20
Cookie: B1SESSION=3f2a61b2-...

Yazma tarafında tipik ilk senaryo satış siparişi oluşturmaktır:

POST https://b1sunucu:50000/b1s/v1/Orders
Cookie: B1SESSION=3f2a61b2-...
Content-Type: application/json

{
  "CardCode": "C20000",
  "DocDueDate": "2026-02-15",
  "DocumentLines": [
    { "ItemCode": "A00001", "Quantity": 5, "UnitPrice": 100 },
    { "ItemCode": "A00002", "Quantity": 2 }
  ]
}

Başarılı cevap 201 Created ile belge numarasını döner. Hata durumunda gövdede error.message.value alanı B1'in gerçek iş kuralı mesajını taşır — "Item no. is missing", "Customer is on hold" gibi. Bu mesajları loglamadan yutmayın; entegrasyon destek taleplerinin çoğu, kaybolan bu mesajın peşinde geçer.

Sahada öğrendiğimiz tuzaklar

Tuzak	Belirti	Önerimiz
Her istekte login	Service Layer yavaşlar, login limiti zorlanır	Session havuzu + timeout yenileme
$select kullanmamak	Devasa cevaplar, yavaş sorgu	Alan bazlı sorgu, sayfalama ($top/$skip)
Hata gövdesini loglamamak	"Çalışmıyor" seviyesinde destek talebi	error.message.value her zaman loga
Tarih/saat formatı varsayımı	Belgeler yanlış tarihe düşer	ISO 8601, sunucu saat dilimini netleştir
UDF isimlerini tahmin etmek	400 Bad Request	$metadata ucundan gerçek şemayı oku
Test ortamı olmadan geliştirme	Canlı veride deneme yanılma	Ayrı test şirketi/DB olmadan başlamayız

Bunların hiçbiri egzotik değil; 30+ ERP dönüşümünde tekrar tekrar aynı desenleri gördük. Entegrasyon projesinin başarısı çoğu zaman API bilgisinden değil, bu operasyonel disiplinlerden geliyor.

Service Layer mi, DI API mi?

Yeni entegrasyonlarda varsayılanımız Service Layer. DI API'yi yalnızca iki durumda tercih ederiz: Service Layer'da henüz karşılığı olmayan nadir bir nesne/işlem gerekiyorsa veya mevcut, sorunsuz çalışan eski bir add-on genişletiliyorsa. Gerekçe pratik: Service Layer platform bağımsızdır, sunucuya istemci kurulumu istemez, ölçeklenir ve HTTP olduğu için izlemesi (log, APM, retry) standart araçlarla yapılır. SAP Business One tarafında yol haritasının da bu yönde olduğunu görüyoruz; yeni yatırımı eski katmana yapmak için iyi bir sebep kalmadı.

Güvenlik ve ağ tarafı notları

Service Layer'ı dışarı açarken standart olarak uyguladığımız kurallar:

• TLS zorunlu, sertifika gerçek: Varsayılan self-signed sertifikayla canlıya çıkmayın; istemcilerde sertifika doğrulamayı kapatan verify=false satırı, sahada en sık gördüğümüz sessiz güvenlik açığıdır.
• Doğrudan internete açmayın: Service Layer portunu dış dünyaya açmak yerine araya bir API gateway/reverse proxy koyun; IP kısıtı, hız limiti ve istek loglama bu katmanda yaşasın.
• Yetkiyi B1 tarafında daraltın: Entegrasyon kullanıcısının yetkisi "her şeye tam" değil, dokunduğu nesnelerle sınırlı olmalı. Sipariş yazan entegrasyonun ana veri silme yetkisi taşıması, tasarım değil ihmaldir.
• Ortam ayrımı disiplini: Test istemcisinin yanlışlıkla canlı CompanyDB'ye login olamaması için ortam bilgilerini yapılandırmadan ayırın; bu hatayı yaşamış her ekip kuralı sonradan koyuyor, biz baştan koyduruyoruz.

Sık sorulan sorular

Service Layer hangi B1 sürümlerinde var?

HANA sürümünde uzun süredir standart; SQL Server tarafında da güncel sürümlerle birlikte destekleniyor. Elinizdeki sürümde durumu netleştirmenin en hızlı yolu https://sunucu:50000/b1s/v1/$metadata ucuna bakmaktır — cevap dönüyorsa katman ayakta demektir.

Service Layer kullanmak ek lisans gerektirir mi?

Service Layer'ın kendisi ayrı lisanslı bir ürün değildir; ancak API üzerinden işlem yapan kullanıcı, B1 lisans modeline tabidir. Entegrasyon kullanıcısının lisans türünü partnerinizle netleştirin — bu, teklif aşamasında sorulmadığında sonradan sürpriz olur.

OData bilmeden Service Layer kullanılır mı?

Başlangıç için $filter ve $select yeterli; derinleşmek isteyen ekip için OData öğrenmek yarım günlük yatırımdır. Asıl zaman, B1 nesne modelini — hangi belge hangi nesneyle, hangi alanla oluşur — öğrenmeye gider; orada partner deneyimi devreye girer.

Entegrasyonu kendi ekibimiz yazsa, sizden ne alırız?

En sık kurduğumuz model tam bu: yazılımı müşterinin ekibi yazar, biz B1 nesne modeli danışmanlığı, test şirketi kurulumu, yetki/performans ayarı ve canlıya alma desteği veririz. İhtiyaç halinde teknik destek sözleşmesiyle çalışmaya devam ederiz.

Toplu veri yüklemede Service Layer performansı yeterli mi?

Günlük entegrasyon hacmi için rahatça yeterli; on binlerce kaydın taşındığı ilk göç senaryolarında ise istekleri batch/paralel kurgulamak ve gerekiyorsa göçü DI araçlarıyla yapmak daha doğrudur. Kural olarak ilk yükleme ile günlük akışı ayrı tasarlar, ikisini aynı koddan geçirmeye çalışmayız.