Agentic Commerce Mimarisi: ACP, UCP/AP2 ve MPP'yi Birarada Uygulamak

Agentic commerce dört ayrı protokol katmanı gerektiriyor: ürün keşfi, ürün bağlamı, ödeme dispatch, uzlaşma. Bu rehber dördünü birarada nasıl uygulayacağınızı, hangisinin hangi sorunu çözdüğünü ve AIDE'nin commerce-* check ailesinin tam olarak ne aradığını anlatıyor.

Mimari haritası

┌─────────────┐
│  Ajan       │
│  (Claude /  │
│   ChatGPT)  │
└──────┬──────┘
       │
       │  1. Ürün keşfi
       ▼
┌─────────────┐      ┌─────────────────────┐
│ Product     │◄─────│ Google Merchant     │
│ Feed (.xml/ │      │ Center / Schema.org │
│ schema.org) │      │ Product             │
└──────┬──────┘      └─────────────────────┘
       │
       │  2. Bağlam — fiyat, stok, fee
       ▼
┌─────────────┐      ┌─────────────────────┐
│ ACP         │◄─────│ Stripe Agent Toolkit│
│ /agent/     │      │ + product-context   │
│ products    │      └─────────────────────┘
└──────┬──────┘
       │
       │  3. Ödeme dispatch — hangi cüzdan, ne kadar
       ▼
┌─────────────┐      ┌─────────────────────┐
│ UCP/AP2     │◄─────│ Google Pay Agent    │
│ /agent/     │      │ Payments / Apple    │
│ checkout    │      │ Agent Wallet        │
└──────┬──────┘      └─────────────────────┘
       │
       │  4. Uzlaşma — settlement
       ▼
┌─────────────┐      ┌─────────────────────┐
│ MPP         │◄─────│ Visa Trusted Agent  │
│ /merchant/  │      │ + Mastercard Agent  │
│ payment     │      │ Pay                 │
└─────────────┘      └─────────────────────┘

Dört katman, dört well-known yolu, dört AIDE check'i. Hepsi gerekli — biri eksikse ajan akışı bir noktada kırılır.

Katman 1 — Product feed (`commerce-product-feed`)

Ajan önce ürünü bulmalı. İki standart yan yana çalışır:

Schema.org Product (HTML inline)

<script type="application/ld+json">
{
  "@context": "https://schema.org",
  "@type": "Product",
  "name": "AIDE Pro Plan",
  "description": "Aylık 100 tarama + leaderboard erişimi",
  "sku": "PLAN-PRO-MONTHLY",
  "offers": {
    "@type": "Offer",
    "price": "49.00",
    "priceCurrency": "USD",
    "availability": "https://schema.org/InStock",
    "url": "https://aide.tr/pricing/pro"
  }
}
</script>

XML feed — Google Merchant uyumlu

<!-- /products.xml -->
<rss xmlns:g="http://base.google.com/ns/1.0">
  <channel>
    <item>
      <g:id>PLAN-PRO-MONTHLY</g:id>
      <g:title>AIDE Pro Plan</g:title>
      <g:link>https://aide.tr/pricing/pro</g:link>
      <g:price>49.00 USD</g:price>
      <g:availability>in stock</g:availability>
      <g:condition>new</g:condition>
      <g:google_product_category>Software</g:google_product_category>
    </item>
  </channel>
</rss>

İkisi de var olmalı — ajan dispatcher'lar farklı önceliklerle birini ya da diğerini tercih eder.

AIDE commerce-product-feed check'i: feed URL erişilebilir mi, en az 1 ürün var mı, fiyat + para birimi geçerli mi?

Katman 2 — ACP (`commerce-acp`)

Agentic Commerce Protocol — ajanın "bu ürünün bağlamı nedir, fiyat hâlâ geçerli mi" sorusuna cevap veren katman.

# /agent/products endpoint
from fastapi import APIRouter, Query

router = APIRouter()


@router.get("/agent/products/{sku}")
async def get_product_context(sku: str, agent_id: str | None = Query(None)):
    """ACP-uyumlu ürün bağlamı."""
    product = await db.products.find_one({"sku": sku})

    return {
        "sku": product.sku,
        "title": product.title,
        "description": product.description,
        "current_price": {
            "amount": str(product.price),
            "currency": product.currency,
            "valid_until": (datetime.utcnow() + timedelta(minutes=15)).isoformat(),
        },
        "availability": "in_stock" if product.stock > 0 else "out_of_stock",
        "shipping": {
            "estimated_days": product.shipping_days,
            "regions": ["TR", "EU", "US"],
        },
        "agent_fees": {
            "fee_share_pct": 5.0,  # ajan komisyon %
            "tracking_pixel": f"https://aide.tr/agent/track?sku={sku}&agent={agent_id}",
        },
        "checkout_endpoint": "/agent/checkout",  # UCP'ye yönlendirme
    }

valid_until kritik — fiyatlar 15 dakika geçerli, sonra ajan refresh ister.

agent_fees.fee_share_pct — ajan başarısı için ek motivasyon. Stripe Agent Toolkit bunu otomatik tracking'e koyuyor.

AIDE commerce-acp check'i: /agent/products endpoint var mı, valid bir bağlam dönüyor mu, valid_until mantıklı mı?

Katman 3 — UCP/AP2 (`commerce-ucp-ap2`)

Universal Commerce Protocol (Apple) + AP2 (Google) — ödeme dispatch katmanı. "Hangi cüzdandan, ne kadar, kime?" sorusuna cevap veriyor.

@router.post("/agent/checkout")
async def initiate_checkout(req: CheckoutRequest):
    """UCP/AP2-uyumlu checkout başlatma."""
    # Ajanın seçtiği ürün + fiyat valid mi?
    if not await validate_price(req.sku, req.amount, req.currency):
        return {"error": "price_changed", "current": await get_current_price(req.sku)}

    payment_intent = await create_intent(
        amount=req.amount,
        currency=req.currency,
        sku=req.sku,
    )

    return {
        "intent_id": payment_intent.id,
        "supported_methods": [
            {"type": "card", "scheme": "visa-trusted-agent"},
            {"type": "card", "scheme": "mastercard-agent-pay"},
            {"type": "wallet", "scheme": "apple-agent-pay"},
            {"type": "wallet", "scheme": "google-pay-agent"},
            {"type": "crypto", "scheme": "x402-base-usdc"},
        ],
        "merchant_payment_endpoint": f"https://aide.tr/merchant/payment/{payment_intent.id}",
        "ttl_seconds": 600,
    }

Beş ödeme method'u — biri çalışmazsa diğeri devreye girer. merchant_payment_endpoint MPP katmanına yönlendiriyor.

AIDE commerce-ucp-ap2 check'i: /agent/checkout POST endpoint'i 200/400 dönüyor mu (auth'a bağlı), supported_methods içinde en az 2 method var mı, intent TTL mantıklı mı?

Katman 4 — MPP (`commerce-mpp`)

Merchant Payment Protocol — settlement + reconciliation. Ajan dispatcher ödemeyi başlattıktan sonra merchant'ın "evet, başarılı, ürün hazır" dediği son adım.

@router.post("/merchant/payment/{intent_id}/settle")
async def settle_payment(intent_id: str, settlement: SettlementProof):
    """MPP-uyumlu settlement endpoint."""
    intent = await db.intents.find_one({"id": intent_id})

    # Settlement proof verify et — tx_hash, signature, vb.
    if not await verify_settlement(settlement, intent):
        raise HTTPException(400, "settlement_invalid")

    await fulfill_order(intent.sku, intent.user_id)
    await db.intents.update({"id": intent_id}, {"$set": {"settled_at": datetime.utcnow()}})

    return {
        "status": "settled",
        "order_id": f"ORD-{intent_id}",
        "fulfillment": {
            "type": "instant",  # veya "shipped" + tracking
            "delivery_url": f"https://aide.tr/orders/ORD-{intent_id}",
        },
        "receipt": {
            "amount": str(intent.amount),
            "currency": intent.currency,
            "tx_hash": settlement.tx_hash,
            "settled_at": datetime.utcnow().isoformat(),
        },
    }

AIDE commerce-mpp check'i: /merchant/payment/* pattern'i tanınıyor mu, settlement proof verification iskelet mevcut mu, receipt obje yapısı doğru mu?

Hangisi öncelikli?

Ürün tipinize göre:

| Ürün tipi | Katman önceliği | |---|---| | Dijital subscription (SaaS) | 1 → 2 → 4 (UCP atlanabilir; subscription instant settle) | | Fiziksel ürün (e-ticaret) | 1 → 2 → 3 → 4 (dördü de zorunlu) | | API çağrı başına ücret | x402 + 1 (UCP/MPP atlanabilir, on-chain settle yeterli) | | Marketplace (Etsy benzeri) | 1 → 2 → 3 → 4 + multi-merchant routing |

aide.tr için: SaaS subscription olduğumuzdan 1+2+4. x402 çoklu pricing modeli için ek olarak.

Yaygın hatalar

| Hata | Belirti | Çözüm | |---|---|---| | Sadece schema.org var, XML feed yok | Bazı ajan dispatcher'lar XML bekliyor | İkisini de yayınla — overhead minimal | | ACP /agent/products HTML dönüyor | Ajan parser fail | Content-Type application/json zorunlu | | valid_until 5 saniye | Ajanın network latency'i nedeniyle her zaman expired | Minimum 5 dakika, ortalama 15 | | UCP'de sadece 1 ödeme method | Method down olunca akış kırılır | Minimum 3 method (kart + wallet + alternative) | | MPP settlement endpoint sync | Yavaş ödemelerde timeout | Async pattern + webhook callback |

Production için

Idempotency: Her endpoint'te Idempotency-Key header'ı support edin. Ajanlar timeout'ta retry eder; double-charge olmasın.
Rate limiting per-agent: agent_id query param'ına göre limit — kötü ajan tüm sistem dispatcher'ını ezmesin.
Refund flow: ACP/UCP/MPP refund'u standart değil. Kendi /merchant/refund/{order_id} endpoint'inizi yayınlayıp ACP yanıtında refund_endpoint alanında duyurun.
Multi-currency: Ajan dispatcher'lar genellikle USD-cinsinden konuşur. Internal currency TRY ise her endpoint'te FX rate + freshness ekleyin.
Telemetri: agentic_commerce_* metric ailesi: hangi katman fail ediyor, hangi ajan en çok dropping yapıyor — Grafana dashboard'u zorunlu.

Test akışı (uçtan uca)

# 1. Product feed
curl -s https://siteniz.com/products.xml | head -20

# 2. ACP context
curl -s 'https://siteniz.com/agent/products/PLAN-PRO?agent_id=test'

# 3. UCP checkout init
curl -X POST https://siteniz.com/agent/checkout \
  -H 'Content-Type: application/json' \
  -d '{"sku":"PLAN-PRO","amount":"49.00","currency":"USD"}'

# 4. MPP settle (settlement proof gerçek bir flow ile alınır)
curl -X POST https://siteniz.com/merchant/payment/$INTENT_ID/settle \
  -H 'Content-Type: application/json' \
  -d '{"tx_hash":"0x...","signature":"..."}'

Dördü de doğru cevap veriyorsa AIDE taramasında commerce-acp, commerce-ucp-ap2, commerce-mpp, commerce-product-feed hepsi PASS gelir.

İlgili kaynaklar

Agentic Commerce Protocol (Stripe)
Universal Commerce Protocol (Apple)
AP2 — Google Pay for Agents
Visa Trusted Agent
x402 micropayments
AIDE check detayları: /learn/commerce-acp, /learn/commerce-ucp-ap2, /learn/commerce-mpp, /learn/commerce-product-feed
Türkiye-spesifik bağlam: /learn/agentic-commerce-turkiye
x402 derin dalış: /learn/x402-odeme-protokolu-rehber

Agentic Commerce Mimarisi: ACP, UCP/AP2 ve MPP'yi Birarada Uygulamak

Mimari haritası

Katman 1 — Product feed (`commerce-product-feed`)

Schema.org Product (HTML inline)

XML feed — Google Merchant uyumlu

Katman 2 — ACP (`commerce-acp`)

Katman 3 — UCP/AP2 (`commerce-ucp-ap2`)

Katman 4 — MPP (`commerce-mpp`)

Hangisi öncelikli?

Yaygın hatalar

Production için

Test akışı (uçtan uca)

İlgili kaynaklar

Haftalık AI-Readiness bülteni

Sitenizde deneyin

Mimari haritası

Katman 1 — Product feed (commerce-product-feed)

Schema.org Product (HTML inline)

XML feed — Google Merchant uyumlu

Katman 2 — ACP (commerce-acp)

Katman 3 — UCP/AP2 (commerce-ucp-ap2)

Katman 4 — MPP (commerce-mpp)

Hangisi öncelikli?

Yaygın hatalar

Production için

Test akışı (uçtan uca)

İlgili kaynaklar

Haftalık AI-Readiness bülteni

Sitenizde deneyin

Katman 1 — Product feed (`commerce-product-feed`)

Katman 2 — ACP (`commerce-acp`)

Katman 3 — UCP/AP2 (`commerce-ucp-ap2`)

Katman 4 — MPP (`commerce-mpp`)