Tecof alışveriş ajanları için önerilen yol, mevcut storefront API'lerini güvenli bir server-side tool katmanı arkasından kullanmaktır. Ajan doğrudan browser secret key'i veya customer token'ı taşımamalı; sizin backend'iniz Tecof API ile konuşmalıdır.

Temel Akış#

sequenceDiagram
    participant User as Kullanıcı
    participant Agent as AI Ajan
    participant Tools as Tool Backend
    participant Tecof as Tecof Store API

    User->>Agent: "Kırmızı ayakkabı bul"
    Agent->>Tools: search_products(query)
    Tools->>Tecof: GET /api/store/ecommerce/products?search=...
    Tecof-->>Tools: Ürün listesi
    Tools-->>Agent: Normalize ürün sonucu
    Agent->>User: Ürünleri önerir
    User->>Agent: "Sepete ekle"
    Agent->>Tools: validate_cart(items)
    Tools->>Tecof: POST /api/store/ecommerce/cart/validate
    Tools->>Tecof: POST /api/store/ecommerce/checkout-session
    Tools-->>Agent: redirectUrl
    Agent->>User: Checkout bağlantısı verir

Diyagram

Önerilen Tool Seti#

Bu isimler ajan tarafındaki soyut tool isimleridir; altta çağırmaları gereken gerçek Tecof endpointleri tabloda verilmiştir.

Tool	Tecof endpoint	Not
`search_products`	`GET /api/store/ecommerce/products`	`search`, `category`, `brand`, `minPrice`, `maxPrice`, `tag`, `sort` destekler
`get_product`	`GET /api/store/ecommerce/products/:slug`	Ürün detayını slug ile getirir
`get_categories`	`GET /api/store/ecommerce/categories`	Kategori ağacı
`get_search_suggestions`	`GET /api/store/ecommerce/search/suggest`	Autocomplete için
`validate_cart`	`POST /api/store/ecommerce/cart/validate`	Stok, fiyat ve otomatik indirimleri doğrular
`validate_coupon`	`POST /api/store/ecommerce/coupon/validate`	Kupon/free shipping kontrolü
`get_shipping_rates`	`POST /api/store/ecommerce/shipping/rates`	Adrese göre kargo
`create_checkout_session`	`POST /api/store/ecommerce/checkout-session`	Hosted checkout redirect URL'i üretir
`get_cms_items`	`POST /api/store/cms/collections/:slug/items`	Canlı CMS içeriği

Tool Şema Örnekleri#

`search_products`#

JSON

{
  "name": "search_products",
  "description": "Tecof mağazasında aktif ürünleri arar.",
  "input_schema": {
    "type": "object",
    "properties": {
      "query": { "type": "string" },
      "locale": { "type": "string", "default": "tr" },
      "limit": { "type": "number", "default": 5 },
      "category": { "type": "string" },
      "minPrice": { "type": "number" },
      "maxPrice": { "type": "number" }
    },
    "required": ["query"]
  }
}

`create_checkout_session`#

JSON

{
  "name": "create_checkout_session",
  "description": "Doğrulanmış sepet için hosted checkout oturumu oluşturur.",
  "input_schema": {
    "type": "object",
    "properties": {
      "items": {
        "type": "array",
        "items": {
          "type": "object",
          "properties": {
            "productId": { "type": "string" },
            "variantId": { "type": "string" },
            "quantity": { "type": "number" }
          },
          "required": ["productId", "quantity"]
        }
      },
      "locale": { "type": "string", "default": "tr" },
      "successUrl": { "type": "string" },
      "failUrl": { "type": "string" }
    },
    "required": ["items"]
  }
}

Güvenlik Kuralları#

x-secret-key değerini ajan istemcisine vermeyin; tool backend içinde tutun.
Customer token gereken işlemleri sadece kullanıcı oturumu doğrulandıktan sonra yapın.
Checkout için mümkünse checkout-session üretip kullanıcıyı hosted ödeme akışına yönlendirin.
Ajanın ürün fiyatı veya stok bilgisini model hafızasından değil, her istekte cart/validate sonucundan okumasını sağlayın.
Webhook veya admin işlemlerini AI ajanına doğrudan açmayın; ayrı izin katmanı kullanın.

Analytics Eventleri#

Ajan destekli storefront deneyimlerinde checkout davranışı için mevcut analytics event tipleri kullanılabilir:

Event	Kullanım
`cart_add`	Ajan önerisiyle ürün sepete eklendiğinde
`cart_remove`	Sepetten ürün çıkarıldığında
`checkout_start`	Hosted checkout veya ödeme adımı başladığında

Bu eventler POST /api/analytics/event üzerinden toplanır ve live analytics ekranında davranış metriklerine katkı verir.

Mağazanın AI dosyaları#

Ajanların mağazayı araç çağırmadan da anlayabilmesi için Tecof mağaza kökünde agents.md, llms.txt, llms-full.txt ve /ai/*.json (katalog, koleksiyonlar, bilgi merkezi, içerik dizini) yayınlar; ajan kaynaklı ödeme bağlantıları utm_source=ai_agent taşır. Dosyaların içeriği, site türüne göre farkları ve tema proxy’si: GEO: AI Storefront.