Bot için mağaza verileri

Sohbette YZ botu yalnızca bilgi tabanına göre değil, mağazanın canlı verileriyle de yanıt verebilir: sipariş nerede, takip numarası ne, ürün stokta mı, teslimat ne kadar tutar, ürün nasıl iade edilir. İzin verirseniz ödenmemiş bir siparişi iptal edebilir veya iade ve teslimat değişikliği taleplerini mağazaya iletebilir. Bunun için mağaza bota MCP (Model Context Protocol) protokolüyle bağlanır: bot mağazanın araçlarını çağırır, mağaza verilerle yanıt verir.

Mağaza her tarifede bağlanabilir; bot ise sohbetteki tüm YZ gibi ücretli tarifelerde çalışır: mağaza verileriyle verilen yanıtlar, normal YZ yanıtları gibi projenin bakiyesinden ödenir; bkz. Ödeme.

Bağlantı

En kolayı mağaza için modülümüzü kullanmaktır. Modül, ayarlar kaydedildiğinde sunucuyu kendisi çalıştırır ve projeye bağlar:

Modülün gizli anahtarına “Mağaza MCP sunucusunu YZ botuna bağlama” (chats.manage) yetkisi gerekir. Anahtarın yetkileri oluşturulduktan sonra değiştirilemez: modülün anahtarında bu yetki yoksa API anahtarları bölümünde önceki yetkilere ek olarak bu yetkiye de sahip yeni bir anahtar oluşturun ve onu modül ayarlarında belirtin. Aynı projenin siteleri bir kez bağlanır.

PHP veya Laravel tabanlı kendi mağazanız, PHP kütüphanesindeki ve Laravel paketindeki hazır sunucuyla bağlanır: geliştiriciye yalnızca araç işleyicilerini yazmak kalır. Mağazanın MCP sözleşmesini uygulayan başka herhangi bir sunucu elle bağlanır: Sohbetler → Sohbet ayarları → Bot → Mağaza (MCP) bölümünde https://… adresini, mağazanın verdiği erişim anahtarını ve bir ad girin. Araçların, hataların ve müşteri doğrulamasının açıklandığı sözleşme Geliştiriciler için bölümündedir.

Mağaza (MCP) bölümünde sunucunun çalışıp çalışmadığı ve mağazanın bota hangi araçlara izin verdiği görünür. Anahtar düğme sunucuyu geçici olarak devre dışı bırakır; yenileme düğmesi sunucuyu yeniden kontrol eder ve araçları tekrar okur (platform bunu günde bir kez kendisi de yapar).

Bot neler yapabilir

Bota tam olarak neye izin verileceğine mağaza, modül ayarlarında karar verir. Varsayılan olarak yalnızca okuma etkindir:

İşlemler, mağaza izin verene kadar kapalıdır:

Araçların model için açıklamalarını mağaza değil platform belirler; bot mağazanın yanıtlarını talimat olarak değil, veri olarak ele alır. Botun yanıtında mağaza verilerinde olmayan fiyatlar, süreler veya sözler varsa yanıt kontrolü yanıtın müşteriye gitmesine izin vermez.

Müşteri doğrulaması

Siparişler ve bunlarla ilgili işlemler yalnızca doğrulanmış müşteriye açıktır: bot başkasının siparişini göstermez, hatta var olduğunu bile doğrulamaz. Müşteri iki şekilde doğrulanabilir:

1. Sitede oturum açma. Müşteri mağaza hesabına giriş yaptıysa modül, sohbet widget'ına imzalı bir token iletir; bot kimin yazdığını hemen bilir.
2. Kod. Mesajlaşma uygulamalarında ve misafirler için bot, mağazada kayıtlı e-posta adresini sorar; mağaza bu adrese 6 haneli bir kod gönderir, müşteri kodu sohbete yazar. Kod 10 dakika geçerlidir; bir adrese saatte en fazla 5 kod gönderilir.

Doğrulama 24 saat geçerlidir. Operatör bunu konuşma penceresinde görür: “müşteri doğrulandı: sitede oturum açtı” veya “müşteri kodla doğrulandı”. Müşterinin token'ı konuşmada şifrelenmiş olarak saklanır; ne model ne de operatörler onu görebilir.

Mağazadaki işlemler

Bot bir işlemi yalnızca müşterinin açık onayından sonra gerçekleştirir:

1. Bot ne yapacağını (sipariş numarası, ürünler) açıklar ve onay ister.
2. Müşteri sohbette onay verir, örneğin “evet, iptal edin”.
3. Ayrı bir değerlendirme modeli, müşterinin tam olarak bu işleme onay verdiğini kontrol eder. Soru, tereddüt veya başka bir istek onay sayılmaz.
4. Mağaza işlemi gerçekleştirir; aynı işlemin tekrar çağrılması hiçbir şeyi tekrarlamaz.

Yazışmada sonuçla birlikte “Bot mağazada gerçekleştirdi: …” satırı, projenin denetim kaydında ise “Botun mağazadaki işlemi” kaydı görünür. Operatörün yanıt taslağı mağaza verilerini yalnızca okumak için kullanır: işlemleri operatör mağazada kendisi yapar.

Geliştiriciler için

Kendi sunucunuz, mağazanın MCP sözleşmesinin 1. sürümünü uyguluyorsa bağlanır. PHP ve Laravel için sözleşme zaten uygulanmıştır: PHP kütüphanesindeki StoreMcp\Server sınıfı ve Laravel paketindeki POST /onetrace/mcp rotası; geriye yalnızca araç işleyicilerini yazmak kalır.

Taşıma. MCP Streamable HTTP, protokol sürümü 2025-06-18: tek bir adres, JSON-RPC 2.0 ile POST istekleri; yanıt JSON veya tek yanıt içeren bir text/event-stream akışıdır. Adres yalnızca genel IP üzerinde https:// olmalı, yönlendirme olmamalıdır. Yanıt en fazla 10 saniye sürmeli ve 256 KB'ı aşmamalıdır. Platform initialize, notifications/initialized, tools/list ve tools/call çağırır; Mcp-Session-Id başlığı desteklenir ancak zorunlu değildir.

Erişim. Her istek Authorization: Bearer <anahtar> taşır; anahtarı mağaza oluşturur ve en az 32 rastgele karakterden oluşur. Anahtarsız veya başka bir anahtarla gelen istek 401 yanıtı alır.

Sözleşme işareti. Sunucu initialize yanıtında capabilities.experimental["onetrace/store"] = { "version": 1 } bildirir; bu olmadan sunucu bağlanmaz.

Araçlar. Adlar tam olarak tablodaki gibidir; tools/list yalnızca sahibin izin verdiği araçları döndürür. Her araçta readOnlyHint: true (okuma) veya destructiveHint: true (işlem) açıklaması ve _meta["onetrace/auth"] bulunur: customer doğrulanmış müşteri gerektiğini, none gerekmediğini belirtir. Sonuç structuredContent ve aynı JSON'un content[0].text içindeki metin hâlidir. Tutarlar { "amount": 1250.5, "currency": "RUB" } biçimindedir, tarihler ISO 8601'dir.

Sipariş durumu şunlardan biridir: pending, processing, on_hold, shipped, delivered, completed, cancelled, refunded, failed. Başka bir müşterinin siparişi, hiç yokmuş gibi not_found yanıtı alır.

Müşteri. customer_token token'ını mağaza oluşturur ve doğrular; geçerlilik süresi en fazla 24 saattir. Doğrulama kodunu mağaza kendisi gönderir ve böyle bir müşteri olsa da olmasa da aynı şekilde yanıt verir; kod 6 hanelidir, 10 dakika geçerlidir, en fazla 5 deneme hakkı vardır, bir adrese saatte en fazla 5 kod gönderilir. Oturum açmış müşteri için sayfa token'ı izleyiciye iletir: cdp.chatCustomer('…').

Çağrı bağlamı params._meta içindedir: onetrace/customer_token, onetrace/language (konuşmanın dili), onetrace/conversation; işlemlerde ayrıca onetrace/confirmed: true ve onetrace/idempotency_key. Sunucu onetrace/confirmed olmayan işlemi reddeder; aynı idempotency anahtarıyla tekrarlanan çağrı, işlemi yinelemeden aynı sonucu döndürür.

Hatalar isError: true ve structuredContent: { "error": "<kod>", "message": "<müşteriye gösterilecek metin>" } biçimindedir:

Modülden bağlantı. Modül, kendi sunucusunu chats.manage yetkisine sahip gizli bir anahtarla kaydeder: url, key, name, platform içeren PUT /api/v1/chat/store-mcp sunucuyu bağlar veya günceller, url içeren DELETE /api/v1/chat/store-mcp ise bağlantısını keser.