Business Central API v2.0 ile Entegrasyon: Limitler, OAuth ve Webhook

Dynamics 365 Business Central kullanan firmalarda muhasebe ve finans tarafı genellikle oturmuştur. İhtiyaç başka bir yerden çıkar: üretim sahasındaki terminal iş emrini kapatacak, e-ticaret sitesi siparişi gönderecek, depo el terminali sayım sonucunu işleyecek. Bunların hepsi Business Central'ın dışında çalışan, ama onunla konuşması gereken uygulamalardır.

Business Central bu konuda iyi belgelenmiş bir üründür. Microsoft hangi arayüzün önerildiğini, hangi limitlerin geçerli olduğunu ve webhook akışının nasıl işlediğini yayımlamıştır. Bu yazı o belgelerdeki bilgileri bir entegrasyon planına çeviriyor.

Önce Kurulum Biçimi

Business Central iki biçimde kullanılır ve entegrasyon planı buna göre değişir.

Başlık	Çevrim içi	Yerinde kurulum
Veritabanı erişimi	Yok	SQL Server
Kimlik doğrulama	OAuth 2.0 ve Microsoft Entra ID	OAuth önerilir
Güncelleme takvimi	Microsoft belirler	Firma belirler
Önerilen arayüz	API v2.0	API v2.0

Çevrim içi sürümde müşterinin veritabanına erişimi bulunmaz; bütün veri alışverişi API üzerinden yapılır. Yerinde kurulumda SQL Server erişilebilir durumdadır ve bu, bir sonraki başlıktaki soruyu gündeme getirir.

Doğrudan SQL Server'a Bağlanmak

Yerinde kurulumda "sunucuyu atlayıp veritabanına bağlanalım" fikri sık dile getirilir. Microsoft bu konuda açık bir ifade kullanır: SQL Server nesneleriyle doğrudan entegre olmak mümkündür, ancak tavsiye edilmez, hatta desteklenmez.

Gerekçesi iki maddedir:

1. Business Central sunucusunun oluşturduğu SQL nesnelerini doğrudan değiştirmek, yükseltme sürecini ve uzantı senkronizasyonunu bozabilir.
2. Veritabanına tetikleyici ya da saklı yordam eklemek aynı riski taşır. Ayrıca senkronizasyon tablo şemasını değiştirdiğinde bu nesnelere bağlı entegrasyon çalışmaz hâle gelir.

İkinci madde Business Central'a özgü bir duruma işaret eder. Bu üründe şema yalnızca sürüm yükseltmesiyle değil, bir uzantının kurulması ya da güncellenmesiyle de değişebilir. Doğrudan tabloya bağlanmış bir entegrasyon, kimse yükseltme yapmadan da bozulabilir.

Bu yüzden yazma işlemleri API üzerinden yapılır. API'den geçen kayıtta ürünün kendi doğrulamaları, numara serileri ve muhasebe bağlantıları çalışır.

Hangi Arayüz?

Business Central dışarıya üç yüzey açar.

API v2.0. OData v4 üzerine kuruludur, sürümlüdür ve Microsoft'un önerdiği yüzeydir. Çevrim içi tarafta üretim ortamının ortak adresi şu kalıbı izler:

https://api.businesscentral.dynamics.com/v2.0/production/api/v2.0

OData web servisleri. Sayfa nesnelerine bağlıdır. İlgili sayfa değiştiğinde servis de etkilenebilir.

SOAP web servisleri. Microsoft bu yüzeyin verimini düşüreceğini ve ileride kullanımdan kaldıracağını yazmıştır. Yeni bir entegrasyonu SOAP üzerine kurmak önerilmez. SOAP ile çalışan eski bir entegrasyon varsa geçiş, acele etmeden ama takvime yazılarak planlanır.

Standart API ihtiyaç duyulan alanı içermiyorsa çözüm SOAP'a dönmek değil, özel bir API sayfası tanımlamaktır. Bu iş, Business Central uygulama ortağınızla birlikte yürütülür.

Kimlik Doğrulama

Önerilen yöntem OAuth 2.0 ve Microsoft Entra ID'dir. Çevrim içi tarafta web servis erişim anahtarları Ekim 2022'den itibaren kullanımdan kaldırılmıştır ve desteklenmez. Yerinde kurulumlarda bir süre daha kullanılabilir.

Yıllar önce yazılmış bir entegrasyonunuz varsa hangi yöntemle kimlik doğruladığını bilmeniz gerekir. Yerinde kurulumdan çevrim içine geçiş planlanıyorsa bu madde geçiş listesinin başına yazılır.

İstemci kimliği ve gizli anahtar sunucu tarafında, erişimi sınırlı bir yerde tutulur. Kod deposuna ya da istemci uygulamasına yazılmaz.

Limitlerle Kapasite Hesabı

Microsoft, Business Central için istek limitlerini yayımlamıştır. Aşağıdaki değerler üreticinin belgelerinden alınmıştır; güncel hâli için Microsoft'un dokümanına bakılmalıdır.

Limit	Değer	Aşıldığında
Kullanıcı başına istek	5 dakikalık pencerede 6.000	429
Eşzamanlı istek	En fazla 5, fazlası kuyruğa alınır	Kuyrukta 8 dakika bekleyen istek 503 alır
İşlem zaman aşımı	8 dakika	408
İstek yürütme süresi	10 dakika	504
Sayfa boyutu	En fazla 20.000 kayıt	413
Toplu istekte işlem sayısı	En fazla 100	-
Webhook aboneliği	En fazla 200	-

Eski belgelerde geçen ortam başına dakikalık istek değerleri güncel değildir. Sınır artık kullanıcı başına tanımlanır. Hizmet hesabı ile normal kullanıcı arasında limit açısından fark yoktur.

Örnek bir hesap

Aşağıdaki hesap varsayımsaldır ve yöntemi göstermek içindir.

Diyelim ki üretim sahasında 40 terminal var ve her terminal vardiya boyunca dakikada ortalama iki işlem gönderiyor. Bu, dakikada 80, beş dakikada 400 istek eder. Tek bir hizmet hesabının beş dakikalık 6.000 istek sınırının çok altındadır.

Burada dikkat edilmesi gereken sınır başka bir satırdadır: eşzamanlı istek sayısı. Vardiya değişiminde 40 terminal aynı anda işlem gönderirse beşten fazlası kuyruğa girer. Bu yüzden terminaller Business Central'ı doğrudan çağırmaz. Araya bir kuyruk katmanı konur, istekler sırayla ve denetimli biçimde iletilir.

Limit aşıldığında

Microsoft'un önerdiği davranış, isteği bir süre bekledikten sonra yeniden denemektir. Bekleme süresi sabit tutulabilir ya da her denemede artırılabilir. Yükü artırmak gerektiğinde iş yükünün birden fazla kullanıcı ya da hizmet hesabı arasında dağıtılması önerilir.

Entegrasyon katmanı 429 ve 503 yanıtlarını iş hatasından ayırmalıdır. "Stok yetersiz" bir iş hatasıdır ve kullanıcıya gösterilir. "Limit aşıldı" ise geçici bir durumdur ve kullanıcıya yansıtılmadan yeniden denenir.

Webhook: İki Kritik Adım

Business Central, bir kayıt değiştiğinde bildirim gönderebilir. Abonelik, API'ye yapılan bir istekle oluşturulur. İstekte bildirim adresi, izlenecek kaynak ve entegrasyonun kendi belirlediği bir doğrulama değeri yer alır.

El sıkışma

Abonelik oluşturulurken Business Central, bildirim adresine bir doğrulama jetonuyla istek gönderir. Karşı tarafın bu jetonu yanıt gövdesinde aynen geri döndürmesi ve başarılı yanıt vermesi gerekir. Bu adım tamamlanmazsa abonelik kurulmaz.

Bildirim adresi yazılıp bu adım atlandığında "webhook çalışmıyor" sonucuna varılır ve sorun başka yerde aranır.

Yenileme

Abonelik süresiz değildir. Yenilenmezse varsayılan olarak üç gün sonra düşer. Düştüğünde hata üretmez; bildirimler gelmemeye başlar.

Bu yüzden entegrasyon kendi aboneliklerini takip eder ve süresi dolmadan yeniler. Yenileme bir arka plan görevi olarak çalışır, başarısız olursa uyarı üretir.

Güvenlik ve yedek yol

Bildirim adresi internete açıktır. Gelen isteğin beklenen kaynaktan geldiği, abonelikte tanımlanan doğrulama değeriyle kontrol edilir.

Webhook tek başına yeterli sayılmaz. Arkada seyrek çalışan bir mutabakat turu, kaçan bildirimleri yakalar.

Sürüm ve Uzantı Değişiklikleri

Çevrim içi tarafta güncelleme takvimini Microsoft belirler. Entegrasyon bu değişikliklere dayanıklı yazılır:

• Yanıtta beklenmeyen yeni bir alan geldiğinde hata verilmez, alan yok sayılır.
• Beklenen bir alan eksikse kayıt işaretlenir, akış durmaz.
• Adres, sürüm, ortam adı ve kimlik bilgileri yapılandırmada tutulur.
• Uzantı kurulumu ve güncellemesi de bir değişiklik olarak ele alınır; ardından örnek kayıtlarla doğrulama yapılır.

Başlamadan Önce Kontrol Listesi

1. Kurulum çevrim içi mi, yerinde mi
2. Kaç şirket ve kaç ortam var
3. Standart API ihtiyaç duyulan alanları içeriyor mu
4. Entra ID üzerinde uygulama kaydını kim açacak
5. Beklenen istek hacmi ve en yoğun an ne zaman
6. Hangi kaynaklar için webhook kullanılacak
7. Uygulama ortağınız bu çalışmadan haberdar mı

Son madde atlanmamalıdır. Lisans, ortam yönetimi ve uzantı yayını uygulama ortağınızın alanıdır. API kullanımının lisans tarafındaki karşılığı da onunla teyit edilir.

Sıkça Sorulan Sorular

Business Central'a Power BI dışında bir rapor paneli bağlanabilir mi?

Bağlanabilir. Veri API üzerinden belirli aralıklarla çekilir ve panel kendi tablosundan beslenir. Böylece panelin her açılışı istek limitinden düşmez.

Eski entegrasyonumuz erişim anahtarı kullanıyor, ne yapmalıyız?

Çevrim içi tarafta erişim anahtarları desteklenmez. Entegrasyonun OAuth 2.0'a geçirilmesi gerekir. Yerinde kurulumda bir süre daha çalışır, ancak çevrim içine geçiş planı varsa bu iş öne alınır.

Webhook bildirimi birkaç gün çalışıp neden duruyor?

En olası sebep aboneliğin yenilenmemesidir. Abonelik varsayılan olarak üç gün sonra düşer ve hata üretmez. Yenileme görevinin çalışıp çalışmadığı kontrol edilir.

Saha terminalleri Business Central'a doğrudan bağlanabilir mi?

Önerilmez. Eşzamanlı istek sınırı nedeniyle yoğun anlarda istekler kuyruğa girer. Araya konan bir katman istekleri sıraya alır, limit yanıtlarını yönetir ve bağlantı kesildiğinde kayıtları bekletir.

Microsoft iş ortağı mısınız?

Hayır. D'Cloud Software hiçbir yazılım üreticisinin bayisi, iş ortağı ya da çözüm ortağı değildir. Lisans, ortam yönetimi ve ürün danışmanlığı uygulama ortağınızın alanıdır. Bizim yaptığımız iş, belgelenmiş API üzerinden çalışan entegrasyonu ve dış uygulamayı geliştirmektir.

Teslimden sonra destek nasıl işliyor?

Teslim sonrası 15 gün ücretsiz hata düzeltme sözleşmeye yazılır. Abonelik yenileme takibi ve güncelleme sonrası doğrulama gibi süren işler ayrı bir bakım maddesinde tanımlanır.

Sonuç

Business Central entegrasyonunda belirsizlik azdır, çünkü kurallar yayımlanmıştır. Yazma API üzerinden yapılır, kimlik doğrulama OAuth ile kurulur, kapasite limit tablosuna göre hesaplanır ve webhook abonelikleri düzenli yenilenir. Doğrudan veritabanına bağlanmak üreticinin desteklemediği bir yoldur.

Business Central kurulumunuzu üretim sahanıza, deponuza ya da e-ticaret sitenize bağlamak istiyorsanız, ihtiyacınızı birlikte değerlendirmek için iletişime geçin.