Kataloğun gerçek zamanlı okunduğu, bir kez kopyalanıp unutulmadığı bir mağaza.
Mağazalar kuruyoruz ve onların üzerine, genelde eksik olan katmanı ekliyoruz: müşteriye yanıt veren ajan, sorunun sorulduğu anda fiyatı ve stok durumunu doğrudan mağazadan okur ve yayımlanmamış bir fiyat uydurmayı reddeder.
Zaten kurduklarımızSe poate verifica din exterior chiar acum, fără să ne întrebi pe noi. Punctul nostru de catalog livrat unui distribuitor răspunde 200 și spune „154 rezultate”; interfața publică a magazinului lui, interogată direct, întoarce antetul `x-wp-total: 154`. Aceeași cifră, două surse independente, verificat pe 06.09.2026. A doua implementare e integrată în platforma de asistenți: serviciul `storeCatalog.service.js` plus trei unelte pe care agentul le poate chema. Rezerva care trebuie spusă: acest al doilea traseu stă pe o ramură de dezvoltare (`feat/store-catalog-global`, `481cfa0`) și nu e încă unificat în trunchi — deci e livrat pentru clienții pe care i-am conectat, nu pornit implicit pentru toți.
Çoğu “katalog entegrasyonu” aslında bir dışa aktarımdır. Biri ürünleri bir kez indirir, bir dosyaya yapıştırır; o andan itibaren müşteriyle konuşan ajan mağazanın eski bir fotoğrafını okur. İlk fiyat değişikliğine ya da ilk tükenen ürüne kadar kusursuz çalışır — ve sonra, susmaktan daha kötü olan bir kesinlikle hata yapar.
Biz mağazayı sorunun geldiği anda okuruz. WooCommerce mağazaları için herkese açık bir arayüz vardır — Store API — ve bu, anahtarsız, hesapsız, eklenti kurmadan ürünleri, fiyatları ve mevcudiyeti döndürür. Adres `/wp-json/wc/store/v1/products`’tur; sayfa başına 100 ürünle, maksimum 20 saniye bekleme süresiyle isteriz ve kaç sayfa olduğunu yanıt başlığından öğreniriz, tahmin etmeyiz. İlk sayfayı tek başına alırız, geri kalanını paralel olarak.
Doğru entegrasyonu doğru görünen birinden ayıran kısım fiyatın çevrilmesidir. Store API “129,90” döndürmez; küçük birimlerde bir rakam dizisi ve ayrıca para biriminin kaç ondalığı olduğunu döndürür. Alışkanlıktan 100’e bölen kişi, iki ondalığı olmayan herhangi bir para biriminde sessizce hata yapar. Daha da önemlisi: sıfır fiyat ücretsiz demek değildir, yayımlanmamış demektir. Bizde sıfır, “fiyat istek üzerine — ekip tarafından teyit edilecek” olur ve ajana uydurmama yönünde açık talimat verilir. Bu, katalog noktasının herkese açık yanıtında hemen şimdi görülebilir.
Kataloğun üzerine diğer parçalar gelir; her biri kendi gerçek durumuyla: restoranın ya da mağazanın yönetim sistemine sepet ve sipariş gönderimi, tüccarlar için MAIB arayüzü üzerinden ya da Stripe ile ödeme, terk edilmiş sepetlerin geri alınması, her 15 dakikada bir senkronizasyonla sipariş durumunun izlenmesi. İşlevsel bir entegrasyonumuz olmayan yerlerde — ve böyle durumlar vardır — aşağıya tam olarak hangisi olduğunu yazın.
Neleri kapsıyor
Çalışma, bileşenlerine ayrılmış hâliyle
Katalog gerçek zamanlı okunur, anahtar ve eklenti olmadan
WooCommerce için mağazanın herkese açık arayüzü olan Store API’yi kullanıyoruz: `/wp-json/wc/store/v1/products`, sayfa başına 100 ürün, maksimum 20 saniye bekleme süresi, başlıkta kendi istemci kimliğimiz ve yalnızca 200 kodunun kabulü. Sayfa sayısını `x-wp-totalpages` başlığından, toplam ürün sayısını `x-wp-total` başlığından okuruz — golü göstermeden sayfalamayız. İlk sayfa tek başına alınır, geri kalanı paralel, 30 sayfa üst sınırıyla. Mağazaya hiçbir şey kurulmaz ve bize tüccar anahtarları verilmez.
Fiyat doğru çevrilir, sıfır ise yayımlanmamış olarak ele alınır
Store API, fiyatı küçük birimlerde dize olarak ve para biriminin ondalık basamak sayısıyla döndürür. 100’e sabit bölmek yerine, o sayının kuvvetindeki ona böleriz — aksi halde farklı ondalık basamak sayısına sahip herhangi bir para birimi yanlış çıkar ve kimse fark etmez. Sıfır `null` olur, yanıt içinde ise „fiyat talep üzerine — ekip tarafından onaylanır” ifadesi, ayrıca ajana bir meslektaştan onay istemesini ve uydurmamasını açıkça söyleyen talimatla birlikte görünür. Fiyat aynı anda iki biçimde gider: arayüz için gösterime hazır metin ve arka plandaki mantık için sayı.
Ajanın çağırabileceği üç araç
Asistan platformunda katalog üç yerleşik araç olarak sunulur — kelime arama, bir cihaz ya da kullanım senaryosuna göre eşleştirme ve bir ürünü kimliğe göre getirme. Ajan bunları `catalog_cauta`, `catalog_potrivire` ve `catalog_produs` adlarıyla görür; her birinin beyan edilmiş kendi parametreleri vardır. Mağaza platformu beklenen platform değilse ya da adres eksikse, araç boş bir liste döndürmek yerine açıkça reddeder; böylece bu durum „ürün yok” diye yorumlanmaz.
Bağlaç kelimeler sonucu bozmaz
“Su filtresi” tam olarak arandığında “de” içeren her şeyi eşleştirir. Teslim edilen katalog noktasında ve sesli widget aramasında boş kelimeler listesini kesiyoruz — `si`, `sau`, `de`, `din`, `la`, `cu`, `pe`, `in`, `pentru` — ve kesmeden sonra yararlı hiçbir şey kalmazsa iki harften uzun kelimelere geri dönüyoruz. Kısmi eşleşmenin eşiği vardır: bir ürün, yalnızca kalan kelimelerin en az yarısına ulaşıyorsa sonuçlara girer.
Mağazanın arayüzü yoksa sayfayı okuruz
Her mağazada Store API yoktur. Geri kalanı için, listeleme sayfalarını açan ve ürün kartlarını okuyan bir ayıklayıcımız vardır; kodda yazılı bütçeyle: en fazla 20 listeleme sayfası, 200 ürün, 24 detay sayfası, sayfa başına 50.000 HTML karakteri, istek başına 5 saniye ve tüm işlem için 45 saniyelik bir süre sınırı. Önce sayfadaki yapılandırılmış ürün verilerini, sonra kartları, sonra paylaşım метaverilerini okur — bu sırayla, çünkü ilk kaynak mağazanın bilerek yazdığı kaynaktır.
Yazılı sınırlarla tazelik, umutla değil
Katalog mağaza başına 10 dakika bellekte tutulur ve aynı mağaza için eşzamanlı istekler tek bir istekte birleştirilir; böylece aynı anda soru soran on müşteri on indirme üretmez. Katalogun herkese açık noktasında yanıt, dağıtım ağı için bir önbellek talimatı da taşır: 5 dakika taze, arka planda yenilenirken 10 dakika daha eski sürümle servis. Döndürülen sonuç sayısı 20 ile sınırlandırılır, varsayılan değer 6’dır.
Sipariş, sepet ve yönetim sistemiyle bağlantı
Sepet, siparişin gönderimi ve siparişin müşterinin yönetim sistemine aktarılması ayrı işlevlerdir, tek bir form değildir. Terk edilmiş sepetlerin geri kazanılması, sohbet yoluyla sipariş verme ve sipariş durumunun izlenmesi de vardır; ayrıca her 15 dakikada bir çalışan iki planlı görev bulunur — biri siparişlerin sonucunu senkronize eder, diğeri ise yönetim sistemindeki durumları iki gün geriden bir gün ilere kadar olan bir zaman penceresinde tamamlar.
Ödemeler: işlevsel olan ve olmayan
Kodda işlevsel olanlar: tüccarlar için MAIB arayüzü — jeton, ardından ödeme isteği; her mağazanın kimlik bilgileri veritabanından okunur ve işlev açıkça etkinleştirilir — ve Stripe; tutar küçük birimlere dönüştürülür ve tahsilat kayıtlara kaydedilir. İşlevsel OLMAYANlar, sürpriz olmasın diye: Paynet, Netopia ve mobilPay için uygulama yoktur ve bunlar istendiğinde kod açıkça reddeder. Moldindconbank yolu, kimlik bilgileri olmadan hata döndüren bir iskelettir. Bunları projeye mevcut bir entegrasyon olarak değil, bir çalışma olarak alıyoruz.
Ajan, ağ düştüğünde uydurmaz
Mağaza sorgusu başarısız olursa, araç boş bir liste döndürmez — ajana katalog hakkında bir yanıt oluşturmamasını söyleyen bir mesaj döndürür. Fark önemlidir: boş liste „yok” diye çevrilir ve yanlış söylenen „yok”, yanlış bir fiyat kadar kesin biçimde bir siparişi kaybettirir.
Nasıl görünüyor
Süreç, adım adım.
01
Herhangi bir vaat öncesi mağazanın doğrulanması
15 saniyelik azami bekleme süresiyle halka açık arayüze tek bir istek göndeririz ve üstbilgiden kaç ürün olduğunu okuruz. Bu yanıttan canlı yolun mümkün olup olmadığını, kaç ürün olduğunu ve fiyat bilgisinin ne kadar eksiksiz olduğunu biliriz. Mağaza yanıt vermezse, bunu tekliften önce söyleriz, uygulama sırasında değil.
02
Kataloğun bağlanması ve fiyatlar üzerinden ilk geçiş
Bağlantıyı teslim ediyoruz, ayrıca fiyatı sıfır olan veya eksik olan ürünler üzerinden bir geçiş sunuyoruz — bunlar neredeyse her zaman gerçek ürünlerdir, hata değildir; bunları ajanın nasıl ele aldığı bizim değil, mağazanın kararıdır. Ajanın yayımlanmamış bir fiyat vermeyi reddettiği tam metni de teslim ediyoruz.
03
Ajanın araçları ve sınırları
Aramayı, eşleştirmeyi ve bir ürünü getirmeyi kuruyoruz; her biri için birlikte belirlenen maksimum sonuç sayısıyla. Buraya mağazaya özgü eş anlamlılar da yazılır — müşterinin bir ürüne nasıl dediği ile kataloğun ona nasıl ad verdiği gibi. Bu adım olmadan arama teknik olarak doğru, pratikte ise işe yaramazdır.
04
Sipariş, ödeme ve yönetim sistemiyle bağlantı
Bunlar bu sırayla kurulur ve her parça yalnızca karşı taraftaki sistemde gerçek erişim kontrol edildikten sonra eklenir. Ödemeler için yalnızca işlevsel uygulamaya sahip olduğumuz bir sağlayıcıdan başlanır; geri kalanı, daha önce belirtilen riskle yeni iş olarak ele alınır, teklifte bir onay kutusu olarak değil.
05
Eksik listesiyle teslim
Adresleri, yapılandırmaları, kodda yazılı sınırları ve kapsanmayanların listesini teslim ediyoruz. Örneğin: teslim edilen genel katalog noktası, mağazaya yapılan istekte maksimum bekleme süresine sahip değildir — mağaza çok yavaş yanıt verirse istek uzar. Bu gerçek bir eksikliktir; bunu teslim listesine ve düzeltme planına yazarız, iç notta değil.
Magazinul, agentul care răspunde, sistemul de gestiune și furnizorul de plată — patru sisteme separate, cu o singură sursă de adevăr pentru preț: magazinul, citit în momentul întrebării.
Veriler
Neye dokunuyoruz, nerede duruyorlar ve ne kadar kalıyorlar
Veri koruma sorumlusu olan herkesin soracağı sorular — o sormadan önce burada sorulmuş hâliyle.
Katalog verileri
Ad, kısa açıklama, güncel fiyat ve liste fiyatı, stok durumu, görsel, kategori ve ürün adresi — hepsi mağazanın herkese açık arayüzünden okunur; bu arayüz bunları zaten herhangi bir ziyaretçiye yayınlar. Mağazanın veritabanını kopyalamayız ve satıcı anahtarı istemeyiz. Onlar müşteride kalır; biz onları talep üzerine okuruz.
Nerede saklanır ve ne kadar
Katalog, işlem belleğinde mağaza başına 10 dakika tutulur ve yeniden başlatıldığında kaybolur — bizde kalıcı bir kopyası yoktur. Genel katalog noktasında dağıtım ağı onu 5 dakika taze ve yenilenirken 10 dakika eski sürüm olarak tutar. Dondurulmuş bir dışa aktarma, teknik olarak tek seçenek olduğunda, canlı kaynak olarak değil, tarihli bir anlık görüntü olarak açıkça işaretlenir.
Sohbet ve sipariş verileri
Müşterinin ne sorduğu ve ne sipariş ettiği, sohbet platformundan ve uygun olduğunda mağazanın yönetim sistemine geçer. Kimlerin erişimi olduğu, ne kadar süre saklandığı ve neyin silindiği proje bazında belirlenir; işleme kaydı başlatmadan önce yazılır, ilk olaydan sonra değil.
Ödeme kimlik bilgileri
Satıcı kimlik bilgileri platformun veritabanında, mağaza başına tutulur ve yalnızca ödeme işlevi o mağaza için açıkça etkinleştirildiğinde okunur. Genel sayfaya ulaşmazlar ve sohbetten geçmezler. Satıcı hesabının yapılandırılması hesap sahibinin kendisi tarafından yapılır, bizim tarafımızdan değil.
Dokunmadıklarımız
Kart verisi almayız. Kataloğu okumak için mağazadan yönetici erişimi istemeyiz — kullanılan arayüz herkese açıktır. Bir proje gerçekten ayrıcalıklı erişim gerektirdiğinde, bu ayrı olarak, yazılı amaçla istenir ve „her ihtimale karşı” tutulmaz.
Bir vaka
Sorunun sorulduğu anda okunan 154 ürünlük bir katalog
Durum
Kişinev’den bir kahve ve su distribütörü, WooCommerce mağazası ve müşterilere metinle ve telefonda yanıt veren ajanları var. Katalog sık sık değişiyor; bir kez kopyalanan liste birkaç gün içinde yanlış olur ve telefonda söylenen yanlış bir fiyat geri alınmaz.
Ne kurduk
Ayrı bir katalog noktası kurduk; bu nokta mağazanın herkese açık arayüzünü sorguluyor: sayfa başına 100 ürün, sayfa sayısı başlıktan okunuyor, ilk sayfa tek başına alınıyor ve geri kalanı paralel işleniyor, 30 sayfalık üst sınır var. Fiyat, mağazanın beyan ettiği ondalık basamak sayısına göre küçük birimlerden çevriliyor; sıfır, yazılı bir yönergeyle ajan için „fiyat talep üzerine — meslektaşlar tarafından doğrulanır” oluyor, böylece uydurma yapmaması söyleniyor. Arama, bağlaçları çıkarıyor ve bir ürünün sonuçlarda görünmeden önce kalan kelimelerin en az yarısına ulaşmasını şart koşuyor. Yanıt 10 dakika bellekte ve 5 dakika dağıtım ağında tutuluyor; bu sırada 10 dakika daha eski sürüm olarak servis edilip arka planda yenileniyor. Sesli ajanlar bunu özel bir entegrasyon olarak değil, basit bir web noktası olarak çağırıyor.
Ne çıktı
06.09.2026 tarihinde, iki bağımsız istekte doğrulandı: katalog noktası „154 sonuç” diye yanıt veriyor ve ilk ürünü fiyat ve stok durumu ile listeliyor, ikincisini ise „fiyat talep üzerine — meslektaşlar tarafından doğrulanır” diye gösteriyor; doğrudan sorgulandığında mağazanın arayüzü `x-wp-total: 154` döndürüyor. Birbirini tanımayan iki kaynaktan gelen aynı sayı — doğrulama budur, bizim beyanımız değil.
Vakanın söylemedikleri
Teslim edilen katalog noktasının mağazaya yapılan istekte maksimum bekleme süresi yok: mağaza çok yavaş yanıt verirse istek temizce düşmek yerine uzuyor. Bu, kodun yeniden okunmasında tespit edilen gerçek bir eksikliktir ve onarım listesinde yer alır — işlev listesinde değil. Ayrı olarak: yukarıda açıklanan boş kelime filtresi teslim edilen noktada ve sesli widget’taki aramada aktiftir; platforma gömülü sürümde henüz taşınmamıştır, bu yüzden orada çok sayıda bağlaç içeren bir arama daha geniş sonuçlar verir.
Sorular
İnsanların aramadan önce bize sordukları
„Canlı katalog” ne demek ve bunun bir laf olmadığını nasıl doğrularım?
Bu, ajanın mağazayı sorunun sorulduğu anda okuması demektir. İki istekte, biz olmadan doğrulanır: bir distribütör için bizim katalog noktamız „154 sonuç” yanıtını verir ve onun mağazasının herkese açık arayüzü doğrudan sorgulandığında başlıkta `x-wp-total: 154` döndürür. Aynı sayı, iki bağımsız kaynak, aynı tarihte. Bir kez kopyalanmış bir katalog bunu yapamaz — ilk değişiklikte senkron dışı kalır.
Bana anahtarlar ya da mağazaya erişim vermem gerekiyor mu?
WooCommerce üzerinde katalog okumak için hayır. Store API mağazanın herkese açık arayüzüdür: herhangi bir ziyaretçinin gördüğü verilerin aynısı, program tarafından okunabilir formatta sunulur; ticaret anahtarı gerekmez ve eklenti kurulması gerekmez. Bu yorum kodumuzun içine bile yazıldı, kaybolmasın diye. Ayrıcalıklı erişimi yalnızca işlevin gerçekten gerektirdiği yerlerde isteriz — örneğin siparişleri yönetim sistemine gönderirken — ve o zaman da amaç yazılı olur.
Fiyatı olmayan ürünlere ne oluyor?
Ücretsiz değil, yayımlanmamış olarak ele alınıyorlar. Mağazanın arayüzünde eksik fiyat sıfır olarak gelir ve naif bir entegrasyon bunu „0 MDL” diye gösterir. Bizde sıfır, „fiyat talep üzerine — meslektaşlar tarafından doğrulanır” oluyor ve ajan, sayı uydurmaması ve bir insanın onayını istemesi için açık talimat alıyor. Bunu herkese açık yanıtta görmek mümkün: listedeki ikinci ürün tam böyle görünür.
Fiyat ne kadar güncel, somut olarak?
Platform düzeyinde en fazla 10 dakika eski, mağaza başına; aynı mağaza için eşzamanlı istekler tek bir indirmede birleştirilir. Genel katalog noktasında dağıtım ağı 5 dakika boyunca güncel sürümü ve ardından 10 dakika boyunca eski sürümü servis eder, bu sırada arka planda yeniler. Değerler proje bazında yapılandırılabilir; gizli değil, değişken olarak yazılmıştır.
Benim mağazam WooCommerce üzerinde değil. Ne yapıyorsunuz?
Ne sunduğuna bağlı. Kendi arayüzü varsa, diğerleri gibi onu okuruz. Hiçbir şey yoksa, listeleme sayfalarını açan ve ürün kartlarını okuyan bir çıkarıcımız var; kodda yazılı bütçesi şöyledir: 20 sayfa, 200 ürün, istek başına 5 saniye, 45 saniye zaman aşımı. Önce sayfadaki yapılandırılmış verileri, sonra kartları, sonra paylaşım metaverilerini okur. Bu dürüst bir yedek çözümdür, eşdeğer bir çözüm değil: temasını değiştiren bir mağaza çıkarıcıyı bozabilir, ama bir arayüz bozmaz.
Şu anda hangi ödemeleri entegre edebilirsiniz?
İşlevsel ve kodda mevcut: tacirler için MAIB arayüzü — jeton alma, ardından ödeme isteği; her mağazanın kimlik bilgileri veritabanından okunuyor ve işlev açıkça etkinleştiriliyor — ve Stripe, tutarın küçük birimlere çevrilmesi ve tahsilatın kayda geçirilmesiyle. İşlevsel olmayanlar, sözleşmeden önce açıkça söylenir: Paynet, Netopia ve mobilPay için uygulama yoktur ve istenmeleri halinde kod açıkça reddeder; Moldindconbank yolu kimlik bilgisi olmadan hata döndüren bir iskelettir. Bunların her biri inşa edilebilir, ancak kendi riskiyle yeni bir çalışma olarak girer.
Ajan sizde olmayan bir ürünü uydurabilir mi?
Belki, eğer siz engellemezseniz — ve biz tam da bununla ilgileniyoruz. Üç engel: yayımlanmamış fiyat, icat etmeme yönünde yazılı talimatla gelir; uygun olmayan platform ya da eksik adres, aracın boş bir liste döndürmesi yerine açıkça reddetmesine yol açar; ağ kesintisi ise ajana katalog hakkında bir yanıt kurmamasını söyleyen bir mesaj döndürür. „Boş liste” ile „okuyamadım” arasındaki fark, kayıp bir sipariş ile bir cümleyle ertelenmiş sipariş arasındaki farktır.
Neden 100’e kim bölüyor diye önemli?
Çünkü arayüz „129,90” göndermiyor. Küçük birimlerde bir rakam dizisi ve ayrıca paranın kaç ondalık basamağı olduğunu gönderiyor. 100’e bölme, iki ondalıklı para birimleri için doğrudur ve diğerleri için sessizce yanlıştır — kimse hata almaz, yalnızca kötü sayılar gelir. Biz, mağazanın beyan ettiği sayı kadar 10’un kuvvetine bölüyoruz. Bu bir satır koddur ve biri belgeleri okuyup okumadığını ya da tahmin edip etmediğini gösteren tam da o tür bir satırdır.
Neleri üstlenmiyorsunuz?
Kart verilerini işlemiyoruz ve tüzel kişinin hesabını sahibinin yerine yapılandırmıyoruz. Bir sayfa ayrıştırıcısının mağazanın tema değişikliğine dayanacağını garanti etmiyoruz — bu yüzden mümkün olduğunda arayüzü tercih ediyoruz. Satış artışı vaat etmiyoruz; gösterebileceğimiz şey, ajanın söylediği sayının mağazadaki sayıyla, aynı tarihte, uyuşmasıdır. Ve kodda bir iskelet olan şeyi entegrasyon diye sunmuyoruz: yukarıdaki liste bunların hangileri olduğunu söylüyor.
Bunlardan 16 tanesi depolarımızdaki kod ve dosyalardır. Adlarını ya da satırlarını yayımlamıyoruz: hepsi bir arada, tek bir sayfada, yalnızca bize ait olmayan sistemlerin nasıl kurulduğunu fazla net anlatırdı. İstek üzerine, depoda sizinle birlikte gözden geçiriyoruz — doğrulama hâlâ mümkün, sadece bir görüşme içinde yapılıyor.