# SCAPI ve OCAPI farkı: SFCC API'leri, SLAS ve geçiş rehberi URL: https://www.ozanaltinbas.com/tr/makale/scapi-vs-ocapi Author: Ozan Altinbas (Ozan Altınbaş), SFCC Technical Architect Published: 2026-11-12 Category: Mimari | Tags: SFCC, SCAPI, OCAPI, SLAS, Headless Ticaret --- Salesforce B2C Commerce, ticaret motorunu iki REST API ailesiyle dışarı açar: 2014'ten beri platformda olan **Open Commerce API (OCAPI)** ve headless commerce için 2020'de sunulan **B2C Commerce API (SCAPI)**. İkisi örtüşür ama birbirinin yerine geçmez: host'lar, kimlik doğrulama, yetkilendirme ve önbellek davranışı farklıdır ve yalnızca SCAPI geliştirilmeye devam ediyor. OCAPI [Nisan 2026 itibarıyla deprecated (kullanımdan kaldırılmış) durumda](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-commerce-ocapi/versioninganddeprecationpolicy.html) ve yeni projeler yalnızca SCAPI kullanmalı. Önce isim, çünkü sık sık yanlış yazılıyor: Salesforce SCAPI'yi **B2C Commerce API** olarak adlandırıyor ve **Salesforce Commerce API** adıyla da anıldığını belirtiyor ([Get Started with the B2C Commerce API](https://developer.salesforce.com/docs/commerce/b2c-commerce/guide/scapi-get-started.html)). "Shopper Commerce API" bir Salesforce adı değildir; "Shopper", SCAPI'nin iki API grubundan birinin önekidir. Platformun genel resmi için [SFCC rehberi](https://www.ozanaltinbas.com/tr/sfcc) ile başlayın. --- ## SCAPI ve OCAPI farkı: bir bakışta | | SCAPI (B2C Commerce API) | OCAPI (Open Commerce API) | |---|---|---| | Durum | Aktif; yeni özellikler yalnızca burada çıkıyor | Nisan 2026'dan beri deprecated; yalnızca düzeltmeler ve güvenlik güncellemeleri | | API grupları | Shopper API'leri, Admin API'leri ve kendi Custom API'leriniz | Shop API, Data API, Meta API | | Host | `{shortCode}.api.commercecloud.salesforce.com`, realm başına bir tane | Instance ya da storefront alan adı; `/dw/shop`, `/dw/data`, `/dw/meta` altında | | Sürümleme | `v1` (Shopper Baskets ayrıca `v2`); eklemeli değişiklikler sürümü değiştirmez | Yıl bazlı (`v24_5`); her yeni sürüm bir öncekini deprecated yapar | | Alışverişçi kimlik doğrulaması | SLAS: refresh token'lı OAuth 2.1 JWT'leri | Client ID ve alışverişçi JWT'si; SLAS token'ları da kabul edilir | | Arka ofis kimlik doğrulaması | Account Manager client'ı, `client_credentials`, scope'lar | Account Manager client credentials ya da Business Manager kullanıcı grant'i | | Yetkiler | SLAS veya Account Manager client'ındaki scope'lar | Business Manager'daki OCAPI Settings JSON'u | | Önbellek | SCAPI CDN ve web-tier önbellek; TTL API'ye ve expansion'a göre | OCAPI Settings'te kaynak başına `cache_time` | | Trafik koruması | Load shedding (503) ve rate limit (429) | Salesforce'a göre eşdeğeri yok | | Genişletilebilirlik | Hook'lar ve Custom API'ler | Yalnızca hook'lar | --- ## Her API ailesi nedir ### SCAPI: Shopper API'leri ve Admin API'leri İki SCAPI grubu arasındaki ayrım diğer her şeyi belirler ([Get Started with the B2C Commerce API](https://developer.salesforce.com/docs/commerce/b2c-commerce/guide/scapi-get-started.html)): | | Shopper API'leri | Admin API'leri | |---|---|---| | Amaç | Müşteriye dönük: gezinme, sepet, ödeme | Satıcıya dönük: ürün, sipariş, stok yönetimi | | Kimlik doğrulama | SLAS (OAuth 2.1) | Account Manager | | Ölçek | Yüksek ölçek, anonim kullanıcılar | Orta düzey kullanım | | Erişim | Salt okunur (Baskets ve Orders hariç) | Okuma ve yazma | **Custom API'ler** bunların üzerine oturur: bir cartridge'da yazdığınız ve SCAPI gateway'i üzerinden Shopper ya da Admin endpoint'i olarak açtığınız endpoint'ler. Salesforce `commerce-sdk`, `commerce-sdk-isomorphic` ve `@salesforce/commerce-sdk-react` SDK'larını sunar; Composable Storefront (PWA Kit) yalnızca Shopper API'lerini kullanır. Bu storefront kararı için [SFRA ve PWA Kit karşılaştırmasına](https://www.ozanaltinbas.com/tr/makale/sfra-vs-pwa-kit) bakın. ### OCAPI: Shop, Data ve Meta API'leri **Shop API** bir alışverişçi olarak ya da bir müşteri adına alışveriş yapan Business Manager kullanıcısı olarak çalışır. **Data API** kuponlar, müşteri listeleri ve içerik gibi satıcı kaynaklarını okur ve yazar. **Meta API** ise API'nin kendisini tanımlar ([Get Started With OCAPI](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-commerce-ocapi/get-started-with-ocapi.html)). Her OCAPI isteği bir client ID belirtmek zorundadır: bearer token, `client_id` parametresi ya da `x-dw-client-id` header'ı ile; aksi hâlde HTTP 400 döner ([OCAPI Client Application Identification](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-commerce-ocapi/clientapplicationidentification.html)). --- ## Endpoint ve URL yapısı SCAPI, realm başına short code'dan türetilen tek bir host adı kullanır ve instance'ı path'teki organization ID ile tanımlar ([Base URL and Request Formation](https://developer.salesforce.com/docs/commerce/b2c-commerce/guide/base-url.html)). OCAPI ise instance'ın kendisinde yaşar; site ve sürüm path'tedir ([OCAPI URL Syntax](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-commerce-ocapi/urlschema.html)): ```text SCAPI: https://{shortCode}.api.commercecloud.salesforce.com/{apiFamily}/{apiName}/v1/organizations/{organizationId}/... e.g. https://kv7kzm78.api.commercecloud.salesforce.com/product/shopper-products/v1/organizations/f_ecom_zzte_053/products/25695327M?siteId=RefArchGlobal OCAPI: https://{domain}/s/{site_id}/dw/{api_type}/{version}/{resource} e.g. https://{domain}/s/RefArch/dw/shop/v24_5/products/25695327M ``` - **Short code**: tüm realm'in paylaştığı sekiz karakterlik değer. Business Manager'da **Administration > Site Development > Salesforce Commerce API Settings** altından talep edin; yayılması 24 saate kadar sürebilir. - **Organization ID**: instance başına bir tane. Demo değer `f_ecom_zzte_053` içinde `zzte` realm'i, `053` instance'ı gösterir (birincil instance'larda `prd`, `stg` veya `dev`). - **Site**: path segmenti değil, `siteId` query parametresi. Fark mimaridir. Salesforce, SCAPI'yi kimlik doğrulama ve yönlendirmeyi üstlenen bir CDN gateway'inin arkasında, ayrıştırılmış ve çok servisli bir mimari olarak tanımlar; OCAPI ise Salesforce'un ifadesiyle "uygulama katmanında çalışır ve kaynaklar için Business Manager ve storefront mantığıyla yarışır" ([The Advantages of SCAPI](https://developer.salesforce.com/docs/commerce/b2c-commerce/guide/why-use-scapi.html)). --- ## Kimlik doğrulama ### Shopper API'leri: SLAS nedir? Shopper Login and API Access Service (SLAS), hem SCAPI'nin hem de OCAPI'nin Shopper API'lerini koruyan kimlik doğrulama servisidir ([SLAS overview](https://developer.salesforce.com/docs/commerce/b2c-commerce/guide/slas.html)). Her SLAS client'ı bir tenant'a, her tenant da tek bir instance'a bağlıdır. Client'lar SLAS Admin UI'da (`https://{shortCode}.api.commercecloud.salesforce.com/shopper/auth-admin/v1/ui/`) ya da SLAS Admin API ile, Account Manager'daki **SLAS Organization Administrator** rolüyle yönetilir. Belirleyici soru, client'ın bir secret'ı güvenle saklayıp saklayamayacağıdır. Full-stack web uygulamaları ve backend-for-frontend (BFF) katmanı olan her şey için **private client** kullanın; **public client**'ı yalnızca secret saklanamadığında, örneğin SLAS'ı doğrudan çağıran bir mobil uygulamada kullanın. [SLAS best practices](https://developer.salesforce.com/docs/commerce/b2c-commerce/guide/slas-best-practices.html) sayfası production'da private client kullanılmasını ve bu client için Strict Client Auth'un açılmasını öneriyor. İstisna, PWA Kit ya da Storefront Next'in kullandığı client'lardır: bu storefront'lar gerekli `x-slas-client-auth` header'ını henüz göndermediği için `/login` ve `/authorize` istekleri 401 döner. | Client | Alışverişçi | Grant type | |---|---|---| | Public | Misafir | `authorization_code_pkce` (`/authorize`, `hint=guest` ile) | | Public | Kayıtlı | `authorization_code_pkce` | | Private | Misafir | `client_credentials` | | Private | Kayıtlı, federe giriş | `authorization_code` | | Private | Kayıtlı, B2C Commerce girişi | `authorization_code` veya `authorization_code_pkce` | Oturum tasarımını belirleyen token kuralları: - Access token'lar **30 dakika** geçerlidir ve yalnızca verildikleri instance ve site için çalışır. - Production tenant'larında refresh token'lar kayıtlı alışverişçiler için **90 gün**, misafirler için **30 gün**; production dışı tenant'larda **9 gün** geçerlidir. Public client refresh token'ları tek kullanımlıktır. - Tek bir refresh token 60 saniye içinde en fazla 3 kez kullanılabilir; sonrasında HTTP 429 döner. - Misafir token istekleri `channel_id` göndermek zorundadır; bu kural 25 Mart 2025'ten beri tüm production tenant'larında uygulanıyor. - OCAPI, client'ın çağırmasına izin verilen kaynaklar için SLAS token'larını kabul eder; aşamalı geçişi mümkün kılan da budur. Private client ile alınan bir misafir token'ı ve ardından yapılan bir Shopper API çağrısı: ```bash curl "https://{shortCode}.api.commercecloud.salesforce.com/shopper/auth/v1/organizations/{organizationId}/oauth2/token" \ --user "{client_id}:{client_secret}" \ --data "grant_type=client_credentials" \ --data "channel_id=RefArch" curl "https://{shortCode}.api.commercecloud.salesforce.com/product/shopper-products/v1/organizations/{organizationId}/products/25695327M?siteId=RefArch" \ --header "Authorization: Bearer {access_token}" ``` Üç hatadan kaçının: SLAS client'larına admin scope'ları (ya da Account Manager client'larına shopper scope'ları) eklemek, ki bu token'ları şişirir ve çalışmaz; public client'a `sfcc.shopper-context.rw` vermek; ve tek bir USID'yi birçok misafir için kullanmak, çünkü Shopper API istekleri USID'ye göre yönlendirilir. ### Admin API'leri: Account Manager Admin API'leri, Account Manager'da oluşturulmuş bir API client'ı gerektirir: instance'larına filtrelenmiş **Salesforce Commerce API** rolü, Allowed Scopes altında gerekli `sfcc.*` scope'ları, token endpoint auth method olarak `client_secret_post` ve token formatı olarak JWT ([Authorization for SCAPI Admin APIs](https://developer.salesforce.com/docs/commerce/b2c-commerce/guide/authorization-for-admin-apis.html)). Yalnızca `client_credentials` desteklenir ve her token tek bir instance'ı kapsar: ```bash curl "https://account.demandware.com/dwsso/oauth2/access_token" \ --request POST \ --user "{client_id}:{client_secret}" \ --header "Content-Type: application/x-www-form-urlencoded" \ --data "grant_type=client_credentials" \ --data-urlencode "scope=SALESFORCE_COMMERCE_API:{realm}_{instance} sfcc.catalogs" ``` SCAPI client'ı OCAPI ile kullanılamaz, tersi de geçerlidir; OCAPI için açılan bir client Salesforce Commerce API rolünü taşımamalıdır. Ayrı client'ları baştan planlayın. ### Karşılaştırma için OCAPI kimlik doğrulaması Shop API'de katalog verisi için izinli bir client ID yeterlidir; alışverişçi çağrıları `/customers/auth` kaynağından alınan bir müşteri JWT'si taşır; agent çağrıları bir Business Manager kullanıcısının OAuth token'ını kullanır. Data API, Account Manager'dan alınan client-credentials token'ını (30 dakika) ya da Business Manager user grant'ini (15 dakika) kabul eder ([OCAPI OAuth 2.0](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-commerce-ocapi/oauth.html)). Salesforce, OCAPI'nin alışverişçi kimlik doğrulamasını yerel refresh token desteği olmayan, kendine özgü bir yapı olarak özetliyor. --- ## Yetkiler: OCAPI Settings ve OAuth scope'ları OCAPI varsayılan olarak hiçbir izin vermez. Her client ID'nin, **Administration > Site Development > Open Commerce API Settings** altında, API tipi (Shop veya Data) ve bağlam (Global ya da tek bir site) bazında OCAPI Settings JSON'unda bir kaydı olmalıdır. Bunun dışındaki her istek HTTP 401 döner, değişikliklerin devreye girmesi üç dakikayı bulabilir ve Data API kaynaklarının çoğu yalnızca global izin destekler ([OCAPI Settings](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-commerce-ocapi/ocapisettings.html)): ```json { "_v": "24.5", "clients": [ { "client_id": "[your_own_client_id]", "allowed_origins": ["https://www.example.com"], "resources": [ { "resource_id": "/product_search", "methods": ["get"], "read_attributes": "(**)", "write_attributes": "(**)", "cache_time": 900 }, { "resource_id": "/baskets/*/items", "methods": ["post"], "read_attributes": "(**)", "write_attributes": "(product_id, quantity)" } ] } ] } ``` `_v` çağırdığınız OCAPI sürümünü değil, ayar dosyasının formatını sürümler; `resource_id` ise `/products/*/images` gibi kalıpları kabul eder. Geçiş sırasında bu doküman elinizdeki en değerli kayıttır: her client'ın neyi çağırabildiğinin tam listesi (çevresindeki yönetim işleri için [Business Manager rehberine](https://www.ozanaltinbas.com/tr/makale/sfcc-business-manager-guide) bakın). 1 Eylül 2026'dan beri yeni müşteriler için açılan realm'lerde OCAPI settings artık sunulmuyor; yeni realm açan mevcut müşteriler bunu destek talebiyle istemek zorunda. SCAPI'de böyle bir doküman yoktur: Salesforce'un eşleme tablosu `OcapiConfigs` için "uygulanamaz" der, çünkü yetkiler client üzerindeki scope'lardır. `.rw` ile biten bir scope okuma-yazma yetkisi verir; dolayısıyla `sfcc.catalogs.rw sfcc.products` okuma-yazma katalog ve salt okunur ürün anlamına gelir. En az yetkiyi verin. --- ## Rate limit'ler, load shedding ve timeout'lar SCAPI platformu iki yolla korur ([Load Shedding and Rate Limiting](https://developer.salesforce.com/docs/commerce/b2c-commerce/guide/throttle-rates.html)): - **Load shedding**: sistem maksimum kapasiteye ölçeklendikten sonra yük eşiğine ulaştığında endpoint'ler HTTP 503 döner. Checkout API'leri (Shopper Baskets, Shopper Orders) bundan muaftır. Korunan yanıtlar `sfdc_load` (0–100) ve `sfdc_load_status` header'larını taşır: %80'de `WARN`, %90'da `THROTTLE`. - **Rate limit'ler**: HTTP 429; SLAS ayrıca saniye cinsinden bir `Retry-After` header'ı ekler. SLAS, production instance başına dakikada 24.000, production dışı instance başına dakikada 500, `getJwksUri` ve `getWellknownOpenidConfiguration` için ise dakikada 25 isteğe izin verir. Belgelenmiş limitler SLAS ve Omnichannel Inventory API'leri için geçerlidir; diğer tüm endpoint'ler artık rate limit'e tabi değildir. Limitler Customer Success Manager ya da Account Executive üzerinden ayarlanabilir. En önemli timeout ve boyut limitleri ([Timeouts and Limits](https://developer.salesforce.com/docs/commerce/b2c-commerce/guide/timeouts-limits.html)): | Kısıt | Belgelenen değer | Aşılırsa durum kodu | |---|---|---| | Shopper API yanıtı | 10 sn | 504 | | Admin API yanıtı | 60 sn | 504 | | Shopper API'de hook çalışması, hook başına | 10 sn | 500 | | İstek gövdesi | 5 MB | 413 | | Yanıt gövdesi | 10 MB | 500 | | Hook circuit breaker | Son 100 çağrıda 50'den fazla hata | 503 | [Hook circuit breaker](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-commerce-ocapi/hookcircuitbreaker.html) açıldığında o extension point 60 saniye boyunca 503 döner, ardından toparlanmayı test eder. Salesforce, OCAPI'de load shedding ya da rate limiting benzeri bir mekanizma olmadığını belirtiyor; bu yüzden OCAPI döneminden kalma client'lar 429 ve 503'ü nadiren düzgün ele alır. Canlıya çıkmadan önce `Retry-After` desteğini ve backoff mantığını ekleyin. --- ## Önbellek: ne değişiyor SCAPI, uygun GET yanıtlarını iki katmanda önbelleğe alır: uçta bir SCAPI CDN'i ve origin'de bir web-tier önbelleği. Bunun için site üzerinde **Enable Page Caching** açık olmalıdır ([SCAPI Caching](https://developer.salesforce.com/docs/commerce/b2c-commerce/guide/server-side-web-tier-caching.html)). Products, Search, Availability, Promotions, SEO URL mapping, Stores ve Configurations önbelleğe alınır; Baskets, Orders, Customers, SLAS ve Shopper Context alınmaz. İsabet oranını dört kural belirler: - İstenen expansion'lar arasındaki **en düşük TTL** geçerli olur ve `expand` gönderilmezse 60 saniyelik `availability` dahil hepsi seçilmiş sayılır. Her zaman açık bir `expand` gönderin. - Önbellek anahtarı **hook'lar çalışmadan önce** hesaplanır; hook içinde uygulanan kişiselleştirme yanlış ya da kaçırılan kayıtlar üretir. Bunun yerine Shopper Context API'yi kullanın; `personalized=none` ise her alışverişçi için aynı olan içeriği işaretler. - Custom API yanıtları yalnızca web-tier'da ve yalnızca script'iniz `response.setExpires()` ile bir önbellek süresi belirlediğinde (1 ile 86.400 saniye arası) önbelleğe alınır. - CDN isabeti, oturum kapatıldıktan sonra bile önbellekteki bir 200 yanıtını döndürebilir; bu yüzden kişisel verileri önbelleğe alınabilir yanıtların dışında tutun. OCAPI ise OCAPI Settings'ten kaynak başına bir `cache_time` alır (varsayılan 60 saniye, en fazla 86.400) ve müşteri JWT'si varsa kişiselleştirilmiş yanıtları varsayılan olarak önbelleğe alır. [SFCC önbellek rehberi](https://www.ozanaltinbas.com/tr/makale/sfcc-caching) ikisini page cache ve eCDN ile birlikte ele alıyor. --- ## Genişletilebilirlik: hook'lar ve Custom API'ler ### Hook'lar: iki API'de ortak Extension point'ler `dw.ocapi.shop.*` adlarını korur ve **aynı hook'lar hem SCAPI hem OCAPI isteklerinde çalışır** ([Customization with Hooks](https://developer.salesforce.com/docs/commerce/b2c-commerce/guide/extensibility_via_hooks.html)). **Administration > Global Preferences > Feature Switches** altında API hook execution'ı açın; kayıt hâlâ cartridge'ın `package.json` dosyasından bir `hooks.json` dosyasına uzanır: ```json { "hooks": [ { "name": "dw.ocapi.shop.basket.billing_address.beforePUT", "script": "./basket_hook_scripts.js" } ] } ``` ```javascript var Status = require('dw/system/Status'); // SCAPI Shopper Baskets ve OCAPI Shop API isteklerinde aynı şekilde çalışır. exports.beforePUT = function (basket, doc) { var isValidAddress = true; // gerçek doğrulamayla değiştirin if (!isValidAddress) { var status = new Status(Status.ERROR); status.addDetail('validation_error', 'Bad billing address'); return status; } // Başarıda hiçbir şey döndürmeyin: döndürülen bir değer sistem // implementasyonunu ve bu extension point'e kayıtlı sonraki hook'ları atlar. }; ``` Dallanmak için `request.isSCAPI()` kullanın; özellikle controller'larla paylaşılan bir calculate hook'u transaction açıyorsa bu, SCAPI'yi bozar. `modifyResponse` içinde eklenen alanlar `c_` property'si olmalıdır; Shopper Experience, Shopper Login, Shopper Payments, Shopper Custom Objects ve Shopper Consents hook desteklemez. Ayrıntılar için [SFCC hook rehberine](https://www.ozanaltinbas.com/tr/makale/sfcc-hooks) bakın. ### Custom API'ler: yalnızca SCAPI Custom API'ler OCAPI'de hiç olmayan şeydir: SCAPI gateway'inin arkasında, `https://{shortCode}.api.commercecloud.salesforce.com/custom/{apiName}/{apiVersion}/organizations/{organizationId}/{endpointPath}` adresinde çalışan kendi REST endpoint'leriniz ([Custom APIs](https://developer.salesforce.com/docs/commerce/b2c-commerce/guide/custom-apis.html)). Her API, `cartridge/rest-apis/` altında üç dosya içeren bir klasördür. Sözleşme bir OAS 3.0 `schema.yaml` dosyasıdır; burada isteğe bağlı kısımlar çıkarılmış hâliyle: ```yaml openapi: 3.0.0 info: version: 1.0.1 title: Loyalty Information API components: securitySchemes: ShopperToken: type: oauth2 flows: clientCredentials: tokenUrl: https://my-shortcode.api.commercecloud.salesforce.com/shopper/auth/v1/organizations/my-org-id/oauth2/token scopes: c_loyaltyInfo_r: Read loyalty information of a customer paths: /customers: get: operationId: getLoyaltyInfo parameters: - in: query name: c_customer_id required: true schema: type: string - in: query name: siteId required: true schema: type: string minLength: 1 responses: "200": description: Shows loyalty information for the customer security: - ShopperToken: ["c_loyaltyInfo_r"] ``` `script.js`, `operationId` ile aynı adı taşıyan bir fonksiyon export eder; `api.json` ise ikisini eşler: ```javascript var RESTResponseMgr = require('dw/system/RESTResponseMgr'); exports.getLoyaltyInfo = function () { var customerId = request.getHttpParameterMap().get('c_customer_id').getStringValue(); // ... customerId için sadakat verisini sorgulayın ... if (customerId === 'customer1') { RESTResponseMgr.createSuccess({ tier: 'silver', points: 14275 }).render(); } else { RESTResponseMgr.createError(404, 'customer-not-found', 'Customer Unknown', 'You provided an unknown customer ID.').render(); } }; exports.getLoyaltyInfo.public = true; ``` ```json { "endpoints": [ { "endpoint": "getLoyaltyInfo", "schema": "schema.yaml", "implementation": "script" } ] } ``` Tasarlamadan önce bilmeniz gereken kurallar: - **Kayıt**, API'yi içeren code version aktive edildiğinde gerçekleşir ve cartridge, sitenin cartridge path'inde olmalıdır (Admin endpoint'leri için Business Manager sitesininkinde); bkz. [cartridge geliştirme rehberi](https://www.ozanaltinbas.com/tr/makale/sfcc-cartridge-development). - **Güvenlik**: endpoint başına tam olarak bir şema, `ShopperToken` (SLAS) ya da `AmOAuth2` (Account Manager), ve `c_` ile başlayan, en fazla 25 karakterlik tam olarak bir özel scope ([Custom API authentication](https://developer.salesforce.com/docs/commerce/b2c-commerce/guide/custom-api-authentication.html)). - **Doğrulama**: her parametre tanımlanmalı, özel olanlar `c_` önekini almalı ve istek gövdelerinde `additionalProperties` kullanılamaz. `siteId` içeren istek bir Shopper isteğidir; içermeyen bir Admin isteği. - **Limitler**: Shopper endpoint'leri varsayılan olarak 60 saniyelik çalışma süresine (120'ye kadar ayarlanabilir, 10 önerilir) ve storefront kotaları altında 5 MiB istek gövdesine sahiptir; Admin endpoint'leri 20 MB kabul eder. --- ## OCAPI'ye hâlâ nerede ihtiyaç var Mayıs 2026 itibarıyla Salesforce, hâlâ en iyi OCAPI üzerinden yürütülen iki alan sayıyor: sistem bilgisi (düşük seviyeli sunucu durumu ve bakım göstergeleri) ve henüz Admin API'si yayımlanmamış bazı niş Data API görevleri ([The Advantages of SCAPI](https://developer.salesforce.com/docs/commerce/b2c-commerce/guide/why-use-scapi.html)). OCAPI ayrıca mevcut bir entegrasyonun, üçüncü taraf cartridge'ın ya da aracın hâlâ onu çağırdığı her yerde yaşamaya devam ediyor. Bu bir geçiş backlog'udur, üzerine yeni bir şey inşa etmek için gerekçe değil. Salesforce'un eşleme tablosundan bir kesit: | OCAPI kaynağı | SCAPI karşılığı | |---|---| | Shop Baskets | Shopper Baskets v1 / v2 | | Shop Products, Shop Categories | Shopper Products | | Shop ProductSearch, Shop SearchSuggestion | Shopper Search | | Shop Content, Shop Folders | Shopper Experience | | Shop Orders, Shop OrderSearch | Shopper Orders | | Shop Sessions | Hybrid Auth ile karşılanır | | Data Products, Data Catalogs | Admin Products, Admin Catalogs | | Data Jobs, Data CodeVersions | Admin Jobs, Admin Scripts | | Data OcapiConfigs | Uygulanamaz: Account Manager ve SLAS'taki scope'lar | Özellik açığı artık ters yönde: Shopper Context, Shopper SEO, Custom API'ler, CDN Zones ve Omnichannel Inventory API'leri yalnızca SCAPI'de var. Kişiselleştirme bunun neden önemli olduğunu gösteriyor. Salesforce'un ifadesiyle OCAPI'de kişiselleştirilmiş bir fiyat genellikle bir modify-response hook'u gerektiriyordu; SCAPI'de alışverişçi niteliklerini Shopper Context'e gönderirsiniz ve platform fiyatları ve promosyonları yerel olarak çözer. --- ## Salesforce'un OCAPI için açıkladığı yön [OCAPI Versioning and Deprecation Policy](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-commerce-ocapi/versioninganddeprecationpolicy.html) bu konuda net: - OCAPI, Nisan 2026 itibarıyla deprecated. Destek talepleri, hata düzeltmeleri ve güvenlik güncellemeleri uygun olduğu yerde sürüyor; yenilik gelmiyor. - Bir kullanım ömrü sonu (EOL) tarihi belirlenmedi. Karar her yıl gözden geçiriliyor ve olası bir EOL tarihi, Salesforce'un OCAPI'yi emekliye ayırmaya resmen karar verdiği tarihten en az iki yıl sonraya konacak. - Yeni projeler yalnızca SCAPI kullanmalı; mevcut OCAPI kullanıcıları geçişlerini planlamaya başlamalı ([The Advantages of SCAPI](https://developer.salesforce.com/docs/commerce/b2c-commerce/guide/why-use-scapi.html)). Bugün bir uçurum kenarı yok, ama OCAPI dondurulmuş durumda. Onu bir platform seçimi olarak değil, kaldırma planı olan bir bağımlılık olarak ele alın. --- ## OCAPI'den SCAPI'ye geçiş kontrol listesi | # | Adım | Ne yapılmalı | |---|---|---| | 1 | Envanter | Her client ID için OCAPI Settings'i dışa aktarın (Shop ve Data, global ve site bazında) ve gerçek trafikle karşılaştırın. | | 2 | Eşleme | Her kaynağı Salesforce'un tablosuyla eşleyin; şimdilik OCAPI'de kalacak belgelenmiş açıkları işaretleyin. | | 3 | Hazırlık | Realm'in short code'unu talep edin (24 saat ayırın) ve her instance'ın organization ID'sini kaydedin. | | 4 | Önce SLAS | Kanallar, scope'lar ve redirect URI'larla SLAS client'ları oluşturun (BFF olan her yerde private). OCAPI SLAS token'larını kabul ettiği için kimlik doğrulama endpoint'lerden önce taşınabilir. | | 5 | Admin client'ları | En az yetkili yeni Account Manager client'ları oluşturun; OCAPI client'ları yeniden kullanılamaz. | | 6 | Hook'lar | API hook execution'ı açın, her `dw.ocapi.shop.*` hook'unu SCAPI üzerinden test edin, `request.isSCAPI()` ile dallanın ve başarıda hiçbir şey döndürmeyin. | | 7 | Kişiselleştirme | Fiyat ve promosyon mantığını hook'lardan Shopper Context'e taşıyın; böylece önbellek anahtarının parçası olur. | | 8 | Custom API'ler | Endpoint gibi davranması için hook'lara ya da controller'lara sıkıştırılmış mantığı bir Custom API ile değiştirin. | | 9 | Önbellek | Page caching'i açın, açık `expand` değerleri gönderin ve kişisel verileri önbelleğe alınabilir yanıtların dışında tutun. | | 10 | Dayanıklılık | 429'u `Retry-After` ile ele alın, 503'te backoff uygulayın, 10 saniyelik timeout'u hesaba katın ve izleme için `correlation-id` header'ı gönderin. | | 11 | Hibrit storefront'lar | B2C Commerce 25.3'ten itibaren Plugin SLAS'ın yerini alan [Hybrid Auth](https://developer.salesforce.com/docs/commerce/b2c-commerce/guide/hybrid-auth.html)'u kullanın: `sfcc.session_bridge` scope'unu ekleyin ve `plugin_slas`'ı kaldırın. | | 12 | Kapatma | Taşınan kaynakları OCAPI Settings'ten çıkarın ve kullanılmayan OCAPI client ID'lerini devre dışı bırakın. | --- ## Önemli çıkarımlar - SCAPI, **B2C Commerce API**'dir ve Salesforce Commerce API olarak da anılır: Shopper API'leri, Admin API'leri ve Custom API'ler. - OCAPI **Nisan 2026'dan beri deprecated** ve bir EOL tarihi belirlenmedi. Yeni projeler yalnızca SCAPI kullanır. - Alışverişçiler **SLAS** ile (production'da BFF arkasında private client), arka ofis sistemleri **Account Manager** client'larıyla kimlik doğrular. SCAPI ve OCAPI ayrı client gerektirir. - Yetkiler OCAPI Settings JSON'undan **OAuth scope'larına** taşınır. - **10 saniyelik** Shopper API timeout'u, `Retry-After` ile gelen **429** ve load shedding altındaki **503** için tasarlayın. - Mevcut hook'lar iki API'de de çalışır; **Custom API'ler** OCAPI'nin zorunlu kıldığı geçici çözümlerin yerini alır. İş gerekçesi için [headless Commerce Cloud](https://www.ozanaltinbas.com/tr/makale/headless-commerce-cloud) yazısına bakın. Headless bir proje ya da OCAPI'den SCAPI'ye geçiş mi planlıyorsunuz? Karar vermeden önce kimlik doğrulama modelinin, hook'ların ve önbellek kurgusunun bir mimar gözüyle incelenmesi [SFCC danışmanlık hizmetlerinin](https://www.ozanaltinbas.com/tr/hizmet) bir parçası; konuşmak için [iletişime geçin](https://www.ozanaltinbas.com/tr/iletisim). ## Ek kaynaklar - [The Advantages of SCAPI](https://developer.salesforce.com/docs/commerce/b2c-commerce/guide/why-use-scapi.html): Salesforce'un karşılaştırması, deprecation duyurusu ve tam OCAPI-SCAPI eşleme tablosu. - [Get Started with the B2C Commerce API](https://developer.salesforce.com/docs/commerce/b2c-commerce/guide/scapi-get-started.html): resmi adlandırma, Shopper ve Admin API'leri, SDK'lar ve kısıtlar. - [SLAS overview](https://developer.salesforce.com/docs/commerce/b2c-commerce/guide/slas.html): client tipleri, grant type'lar ve token ömürleri. - [Load Shedding and Rate Limiting](https://developer.salesforce.com/docs/commerce/b2c-commerce/guide/throttle-rates.html): güncel SCAPI ve SLAS limitleri. - [Custom APIs](https://developer.salesforce.com/docs/commerce/b2c-commerce/guide/custom-apis.html): sözleşme, implementasyon, eşleme ve sınırlamalar. - [OCAPI Versioning and Deprecation Policy](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-commerce-ocapi/versioninganddeprecationpolicy.html): deprecation'ın ne anlama geldiği ve EOL kararının nasıl verileceği.