Business Central API v1.0 kaldırıldı: entegrasyonu v2.0'a taşıma
Business Central API v1.0, 2026 sürüm dalgası 1'de (28.0) kaldırıldı. Entegrasyonunuzun hangi sürümü çağırdığını bulma ve v2.0'a geçiş adımları.
İçindekiler
Business Central’ın standart API v1.0 sürümü 2026 sürüm dalgası 1’de, yani 28.0 güncellemesinde kaldırıldı. Muhasebe programınız, e-ticaret sitesiniz ya da kendi yazdığınız bir uygulama Business Central’a /api/v1.0/ ile başlayan adresler üzerinden bağlanıyorsa bu bağlantıyı v2.0 adreslerine taşımanız gerekir. Microsoft’a göre v2.0, v1.0’ın tüm işlevlerini içerir. Geçiş çoğunlukla adres, anahtar ve alan adı düzeltmesinden oluşur.
Bu yazıda neyin kaldırıldığını, entegrasyonunuzun v1.0 kullanıp kullanmadığını nasıl bulacağınızı, iki sürüm arasındaki farkları ve geçişi hangi sırayla yapacağınızı anlatıyoruz. Anlatım Microsoft Learn belgelerine dayanır ve Business Central online içindir.
Neyin kaldırıldığı
Microsoft’un kaldırılan özellikler sayfasında API v1.0 şöyle geçer: 2024 sürüm dalgası 1’de eskimiş olarak işaretlendi, 2026 sürüm dalgası 1’de (28.0) kaldırıldı. Yerine, 2020 sürüm dalgası 2’de gelen API v2.0 kullanılır. Yani kaldırma sürpriz bir karar değil. Microsoft yaklaşık iki yıl önceden eskimiş olarak işaretlemişti.
Kapsamı doğru anlamak önemlidir. Kaldırılan şey, Microsoft’un her ortamda hazır sunduğu standart API’nin v1.0 sürümüdür. Standart API’nin adresi şu biçimdedir:
https://api.businesscentral.dynamics.com/v2.0/{ortam adı}/api/v2.0/{uç nokta}Adresin başındaki v2.0, Business Central’ın birden çok ortamı desteklemeye başladığı dönemden kalır ve API sürümüyle ilgisi yoktur. API sürümü /api/ kısmından sonra gelir. Yayıncı ve grup içeren özel API’lerin adresi /api/{yayıncı}/{grup}/{sürüm} biçimindedir ve sürüm bölümünü uygulamayı yazan geliştirici belirler. Microsoft’un kendi örneğinde özel bir API’nin sürümü v1.0 olarak tanımlanmıştır. Bu nedenle adreste v1.0 gördüğünüzde önce /api/v1.0/ mı, yoksa /api/yayinci/grup/v1.0/ mı olduğuna bakın. Yalnızca ilki kaldırılmıştır.
Daha eski bir değişiklik de aynı yöne işaret eder: standart API’nin beta sürümü 2021 sürüm dalgası 2’de kaldırılmıştı ve Microsoft entegrasyonların v2.0’a geçmesini önermişti.
Entegrasyonun v1.0 kullanıp kullanmadığını bulma
Sorunun yarısı çoğu zaman çağrıyı kimin yaptığını bilmemektir. Aşağıdaki yoldan sırayla ilerleyin.
- Bilinen sistemleri sayın. Business Central’a bağlanan her yazılımın listesini çıkarın: e-ticaret sitesi, depo uygulaması, raporlama aracı, banka ya da kargo bağlayıcısı, iş ortağının yazdığı özel uygulamalar.
- Bağlantı ayarlarındaki adrese bakın. Her sistemin ayar ekranında ya da yapılandırma dosyasında Business Central adresi vardır. İçinde
/api/v1.0/geçiyorsa geçilecek bağlantı budur. - API Overview sayfasını açın. Microsoft’a göre bu sayfa 2026 sürüm dalgası 2 ve sonrasında vardır. Sağ üstteki Search (Ara) kutusuna API Overview yazıp açın. API v2.0, Microsoft APIs ve Custom APIs gibi görünümlerle listeyi daraltabilir, API Publisher (API Yayıncısı), API Group (API Grubu) ve API Version (API Sürümü) sütunlarıyla süzebilirsiniz. Sayfa bir API’yi yapılandırmaz ve erişim vermez. Yalnızca ortamda neyin yayımlandığını gösterir.
- Telemetriye bakın. Ortamınız Azure Application Insights’a bağlıysa web hizmeti isteklerini izleyen RT0008 olayında her çağrının
endpoint(uç nokta) vecategory(kategori) bilgisi yazılır. Aşağıdaki sorgu, son bir gün içinde çağrılan adresleri listeler:
traces
| where timestamp > ago(1d)
| where customDimensions has "RT0008"
| where customDimensions.eventId == "RT0008"
| project timestamp,
category = customDimensions.category,
endpoint = customDimensions.endpointMicrosoft ayrıca çağıranı tanımayı kolaylaştıran bir yol önerir. İsteklerde User-Agent üstbilgisi ya da client-request-id üstbilgisi gönderilirse bu bilgi telemetride httpHeaders alanında görünür. Böylece hangi adresin hangi sistemden geldiğini eşleştirebilirsiniz. Kendi yazdığınız uygulamalarda bu üstbilgiyi eklemek geçiş sırasında işinizi çok kolaylaştırır.
- Başarısız çağrıları ayırın. Telemetride
httpStatusCodealanı 4xx olan çağrılar istemci tarafında bir sorun olduğunu gösterir. Microsoft’un durum kodu tablosuna göre gelen bir API çağrısında 404, uç noktanın metadata içinde bulunmadığı anlamına gelir. Kaldırılan v1.0 uç noktaları bu tanıma uyar.
v1.0 ile v2.0 arasındaki farklar
Microsoft’un geçiş belgesi değişiklikleri dört başlıkta toplar. Çağrı adresini değiştirmek yetmez. Yanıtı okuyan kod da bu farklara göre güncellenmelidir.
| Konu | API v1.0 | API v2.0 |
|---|---|---|
| Anahtar alanlar | Bazı kaynaklar çok parçalı ya da GUID olmayan anahtar kullanır | Her kaynak GUID anahtarla, yani SystemId ile çağrılır |
| İç içe alanlar | address gibi alanlar iç içe JSON nesnesi döner | Alanlar ilk düzey özelliktir ya da gezinme özelliğiyle gelir |
| İlişkili veri | Alt sayfalar her zaman dizi döner | Bire bir ilişkiler tek nesne döner |
| Seçenek alanları | Metin olarak döner | Güçlü türlü enum olarak döner |
Anahtarlar ve SystemId
v1.0’da şu kaynaklar SystemId ile değil, GUID olmayan ya da çok parçalı anahtarlarla çağrılıyordu: attachments, defaultDimensions, dimensionLines, generalLedgerEntries, salesInvoiceLines, salesOrderLines, purchaseInvoiceLines, trialBalance, incomeStatement ve benzerleri. v2.0’da bunların hepsi tek bir GUID anahtara geçti. Microsoft’a göre SystemId değişmez, platform tarafından zorlanır ve dizinlidir. Bu da denetimi ve okuma hızını iyileştirir. v2.0’da yeni kayıt oluştururken SystemId değerini kendiniz de verebilirsiniz. Satır kaynaklarını bu anahtarlarla çağıran kodu bulmak, geçişin en dikkat isteyen kısmıdır.
İç içe alanlar
v1.0’da POSTALADDRESS, Collection(DIMENSION), ITEM-UOM ve DOCUMENTLINEOBJECTDETAILS türündeki alanlar karmaşık nesne olarak dönüyordu. Microsoft’a göre bu alanlar çalışma anında hesaplandığı için ek işlem yükü getiriyordu. V2.0’da hepsi ya ilk düzey özelliğe ya da gezinme özelliğine çevrildi.
Müşteri kaynağı bunun örneğidir. v1.0’da adres bir address nesnesinin içindeydi. v2.0’da aynı bilgi addressLine1, addressLine2, city, state, country ve postalCode alanları olarak doğrudan yanıtın içinde gelir. Kalem kaynağında ise v1.0’daki baseUnitOfMeasure alanının ilk düzey bir karşılığı yoktur. Onun yerine unitOfMeasure gezinme özelliği kullanılır ve yanıta $expand ile eklenir:
GET {adres}/companies({sirketId})/items({kalemId})?$expand=unitOfMeasureBire bir ilişkiler
v1.0’da gezinme özelliklerinin hepsi koleksiyon sayılıyordu ve JSON dizisi dönüyordu. v2.0’da bazı özellikler bire bir ilişki olarak işaretlendi ve artık dizi yerine tek nesne dönüyor. Microsoft’un listesindeki bire bir ilişkiler şunlardır. Müşteride agedAccountsReceivable, customerFinancialDetails ve picture alanları bu gruba girer. Satıcıda agedAccountsPayable ve picture, kalemde unitOfMeasure, inventoryPostingGroup, generalProductPostingGroup ve picture aynı şekilde tek nesne döner. Satış ve satın alma satırlarında location, satış ve satın alma faturalarında pdfDocument de tek nesnedir. Bu alanları dizi gibi okuyan kod geçişten sonra hata verir.
Enum alanları
v1.0’da seçenek türündeki alanlar metin olarak dönüyordu. v2.0’da güçlü türlü enum olurlar. Microsoft’a göre geçerli değerlere metadata uç noktasından, başlıklara ise entityDefinitions uç noktasından ulaşılır. Bu özellik bir arayüzde açılır liste doldurmak gibi işleri kolaylaştırır. Kodunuz değerleri sabit metinlerle karşılaştırıyorsa kontrol edilmelidir.
Geçiş adımları
Aşağıdaki sıra, canlı sistemi riske atmadan ilerlemek için uygundur.
- Sandbox ortamı hazırlayın. Üretimin kopyası olan bir sandbox’ta deneme yapın. Nasıl açılacağını sandbox yazımızda anlattık. Kopyada dış bağlantıların kapalı geldiğini unutmayın.
- Adresi v2.0’a çevirin. Ortam adı ve şirket kimliğini koruyarak adresin sürüm bölümünü değiştirin:
https://api.businesscentral.dynamics.com/v2.0/{ortam adı}/api/v2.0/companies({sirketId})/{uç nokta}. Şirket kimliğinicompaniesuç noktasından alırsınız. Microsoft şirketi adrese parantez içinde yazmayı ya da?company=parametresiyle vermeyi kabul ediyor. - Kaynak adlarını ve anahtarları gözden geçirin. Yukarıdaki listedeki kaynakları çağırıyorsanız
SystemIdkullanımına geçin. - Yanıtı okuyan kodu güncelleyin. İç içe alanları ilk düzey alanlarla değiştirin,
$expandgerektiren yerleri belirleyin, dizi bekleyen yerlerde tek nesneyi işleyin. - Enum değerlerini doğrulayın. Metin karşılaştırması yapan her yer için
metadatayanıtına bakın. - Yetkilendirmeyi kontrol edin. Microsoft, üretimde Microsoft Entra ID tabanlı OAuth 2.0 kimlik doğrulamasının kullanılmasını ister. Temel kimlik doğrulama (basic authentication, web hizmeti erişim anahtarı) Business Central online’da 2022 sürüm dalgası 1’den beri eskimiş sayılır ve desteklenmez. Entegrasyonunuz hâlâ erişim anahtarı kullanıyorsa bunu da aynı geçişte düzeltin.
- Dil üstbilgisini kararlaştırın. Yanıtın dilini ve biçimini sabitlemek istiyorsanız
Accept-Languageüstbilgisini gönderin. Bu üstbilgi hata iletilerinin dilini ve tarih biçimini de etkiler. - Sandbox’ta tam bir akışı deneyin. Bir kayıt oluşturun, değiştirin, silin ve listeleyin. Yalnızca okuma çağrılarını deneyip yazma çağrılarını bırakmak sık yapılan bir eksiktir.
- Üretime alın ve telemetriyi izleyin. Geçişten sonraki birkaç gün 4xx durum kodlarını sorgulayın. Beklenmedik bir 404 ya da 400 genellikle atlanmış bir alan adını gösterir.
Sık yapılan hatalar
- Yalnızca adresi değiştirip bırakmak. v2.0 yanıtında
addressgibi iç içe alanlar yoktur. Bunları okuyan kod yeni alan adlarına göre güncellenmelidir. - Özel API’yi standart API sanmak. Özel bir API’nin sürüm bölümünde
v1.0yazması onun kaldırıldığı anlamına gelmez. Önce adresin biçimine bakın. - Eksik işlevi tahminle çözmek. Microsoft v2.0’da v1.0 işlevinin eksik olduğu bir durumda BCApps deposunda bildirim açmanızı ister.
- API’yi alan eklemek için genişletmeyi düşünmek. Microsoft’un belgesine göre standart API’ler şu an ek alanla genişletilemez. Bu ihtiyaç varsa API’nin AL kodu kopyalanıp özel bir API yazılır.
- Geçişi tek sisteme bakarak bitirmek. Aynı ortama bağlanan her yazılımın adresine tek tek bakın.
Sırada kalkacak olanlar
API v1.0 tek değişiklik değil. Microsoft’un aynı sayfasına göre Finance reports API (beta) 2026 sürüm dalgası 2’de eskimiş olarak işaretlendi ve 2027 sürüm dalgası 1’de (sürüm 30.0) kaldırılacak. Raporlama ve analiz senaryoları için yerine Analytics API kullanılması öneriliyor. Bu API salt okunur uç noktalar sunar ve Power BI uygulamaları ile özel raporlar için hazırlanmıştır. Raporlamada bu beta uç noktayı kullanıyorsanız geçişi v1.0 işiyle birlikte planlamak iyi olur.
Sürüm 26’dan itibaren bir Microsoft sayfasını SOAP uç noktası olarak yayımlamak da mümkün değil. Telemetride bu tür çağrıları bulmak için Deprecated endpoint called (RT0053) olayı vardır. Güncelleme zamanlamasını güncelleme takvimi yazımızda, güncel sürümün diğer değişikliklerini 29.0 yenilikleri yazımızda bulabilirsiniz.
Xen Bilişim’in hizmeti
Entegrasyon projelerinde önce Business Central’a bağlanan sistemlerin dökümünü çıkarıyor, her bağlantının hangi API sürümünü ve hangi kimlik doğrulamasını kullandığını belirliyor, sonra sandbox ortamında v2.0 geçişini deneyip üretime alıyoruz. Kendi uygulamanızı ya da üçüncü taraf bağlayıcıyı güncellemek gerekiyorsa bunu entegrasyon hizmetimiz kapsamında yapabiliriz. Canlıdaki kurulumlarda telemetri ve hata incelemesini uygulama yönetimi ve destek hizmetimizle yürütüyoruz. Bağlantılarınızın durumunu birlikte gözden geçirmek için bizimle iletişime geçebilirsiniz.
Sık sorulan sorular
Business Central API v1.0 ne zaman kaldırıldı?
Microsoft'un kaldırılan özellikler sayfasına göre API v1.0 2024 sürüm dalgası 1'de eskimiş olarak işaretlendi ve 2026 sürüm dalgası 1'de, yani 28.0 güncellemesinde kaldırıldı. Sürüm 28.0 ve sonrasında v1.0 adresine giden çağrılar için v2.0'a geçmek gerekir.
API v2.0, v1.0'ın yaptığı her şeyi yapıyor mu?
Microsoft'a göre API v2.0, v1.0'daki tüm işlevleri içerir ve geçiş mümkün olmalıdır. Eksik bir şey bulursanız Microsoft, BCApps deposunda bildirim açmanızı ister.
Entegrasyonumun v1.0 kullandığını nasıl anlarım?
Çağrı adreslerinde /api/v1.0/ bölümü varsa v1.0 kullanıyorsunuzdur. Business Central'ın Application Insights telemetrisindeki web hizmeti çağrısı olayı (RT0008) her çağrının uç noktasını ve kategorisini kaydeder, böylece hangi sistemin hangi adresi çağırdığını sorgulayabilirsiniz.
Yönetim merkezinden ya da arayüzden API sürümüne bakabilir miyim?
Microsoft'a göre 2026 sürüm dalgası 2 ve sonrasında Business Central'da API Overview (API Genel Bakış) sayfası vardır. Sayfa ortamdaki API sayfalarını, sorgularını ve kod birimlerini listeler. API Version (API Sürümü) sütunuyla süzebilir, API URL (API Adresi) alanından uç noktayı açabilirsiniz.
API v2.0 ile v1.0 arasındaki en büyük fark nedir?
Microsoft'un geçiş belgesine göre üç değişiklik öne çıkar. Çok parçalı ya da GUID olmayan anahtarlar yerini SystemId'ye bırakır. İç içe geçmiş alanlar (örneğin address) ilk düzey özelliklere ya da gezinme özelliklerine dönüşür. Seçenek (option) türündeki alanlar enum olur.
Kaynaklar
Bu yazı, Microsoft iş uygulamaları hizmetini veren Xen Bilişim ekibi tarafından hazırlanmıştır. Hakkımızda
