Yapay Zeka Destekli Alışveriş Ajanları

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

Ö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`

{
  "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`

{
  "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.

Agentic Storefront Altyapısı

Tecof mağazaları, yapay zeka ajanlarının (ChatGPT, Gemini, Claude, Perplexity vb.) mağazayı doğrudan anlaması, ürünleri araması ve bilgi edinmesi için otomatik olarak optimize edilmiş standart keşif dosyaları sunar.

Otomatik Oluşturulan AI Dosyaları

AI Storefront özelliği panelden aktif edildiğinde, mağazanızın kök dizininde aşağıdaki dosyalar otomatik olarak yayına alınır:

/agents.md (Markdown): AI ajanları için mağazanın kurallarını, politikalarını ve katalog adreslerini içeren yönlendirici ana rehber.
/llms.txt (Text): LLM tarayıcıları ve crawler'lar için mağazadaki AI kaynaklarını listeleyen kısa indeks dosyası.
/ai/catalog.json (JSON): Mağazadaki tüm aktif ürünleri, varyantları, AI-optimize açıklamaları, güncel fiyatları ve checkout (ödeme) bağlantılarını içeren makine-okunabilir katalog.
/ai/collections.json (JSON): Mağazanın kategori ağacını basitleştirilmiş bir biçimde sunan feed.
/ai/knowledge.json (JSON): Mağazanın AI Bilgi Merkezi (Knowledge Base) verilerini (kargo, iade politikaları, SSS vb.) yapılandırılmış formatta sunan veri seti.

Katalog Veri Yapısı (ai/catalog.json)

Aşağıda AI kataloğunun veri yapısına bir örnek verilmiştir:

{
  "store": {
    "name": "Tecof Premium Store",
    "currency": "TRY",
    "language": "tr",
    "domain": "https://premium.tecof.com"
  },
  "products": [
    {
      "id": "60c72b2f9b1d8e001c888888",
      "title": "Minimalist Deri Cüzdan",
      "description": "El yapımı hakiki deri kartlık ve cüzdan. 6 adet kart kapasiteli.",
      "price": 850,
      "compareAtPrice": 1200,
      "currency": "TRY",
      "availability": "in_stock",
      "images": [
        "https://cdn.tecof.com/uploads/wallet-1.jpg"
      ],
      "url": "https://premium.tecof.com/products/minimalist-deri-cuzdan",
      "checkout_url": "https://premium.tecof.com/checkout?variant=60c72b2f9b1d8e001c899999&utm_source=ai_agent&utm_medium=agentic&utm_campaign=ai_storefront",
      "slug": "minimalist-deri-cuzdan"
    }
  ],
  "total": 1,
  "generated_at": "2026-07-10T02:00:00.000Z"
}

AI Bilgi Merkezi (ai/knowledge.json)

Yapay zeka ajanlarının mağazanız veya politikalarınız hakkında sorduğu sorulara (örneğin "Kargo kaç günde gelir?", "İade süreniz nedir?") doğru yanıt verebilmesi için AI Bilgi Merkezi verileri şu yapıda sunulur:

{
  "store": {
    "name": "Tecof Premium Store",
    "language": "tr",
    "currency": "TRY"
  },
  "brand": {
    "about": "Tecof, modern e-ticaret çözümleri sunan yenilikçi bir teknoloji markasıdır.",
    "tone": "premium"
  },
  "policies": {
    "shipping": "Siparişleriniz 1-3 iş günü içerisinde kargoya teslim edilir. 500 TL ve üzeri kargo ücretsizdir.",
    "returns": "Satın aldığınız ürünleri 14 gün içerisinde ücretsiz iade edebilirsiniz.",
    "warranty": "Tüm ürünlerimiz 2 yıl resmi garantilidir."
  },
  "faq": [
    {
      "question": "Yurtdışına gönderim yapıyor musunuz?",
      "answer": "Şu an için yalnızca Türkiye sınırları içerisine gönderim yapmaktayız."
    }
  ],
  "sizeChart": "Beden tablolarımıza ürün detay sayfalarındaki bağlantılardan erişebilirsiniz.",
  "usageTips": "Hakiki deri ürünlerinizin uzun ömürlü olması için nemli bezle temizleyiniz.",
  "aiRules": [
    "Kullanıcıya her zaman premium bir dil tonu ile hitap et.",
    "İndirim kuponu sorulduğunda hoşgeldin kuponunu önerebilirsin."
  ],
  "generated_at": "2026-07-10T02:00:00.000Z"
}

AI Yönlendirme ve Analytics Takibi

Ajanlar aracılığıyla alışveriş yapmak isteyen kullanıcılar için oluşturulan checkout_url adresleri otomatik olarak UTM parametreleri ile donatılır:

utm_source=ai_agent
utm_medium=agentic
utm_campaign=ai_storefront

Bu sayede, Tecof Analytics paneli üzerinden yapay zeka ajanlarından gelen sepet, ziyaret ve satış dönüşümleri anlık olarak raporlanabilir.