Alışveriş sepeti API'sinin uygulanması

Bu kılavuzda, 2026-04-08 sürümünde Evrensel Ticaret Protokolü (UCP) Sepet API'sinin entegrasyonu için teknik API referansı ve yük şemaları sağlanmaktadır.

Uç noktalarınızı oluşturmadan önce, üst düzey kavramlar ve ön koşullar için Cart API'ye genel bakış bölümünü incelediğinizden emin olun.

Alışveriş sepeti oluşturma

Bu uç nokta, yeni bir alışveriş sepeti oturumu oluşturulmasına olanak tanır. Entegrasyon için CreateCart uç noktasını (POST /carts) uygulayın. Kullanıcı alışveriş sepetini aktarmayı seçtiğinde Google, bu uç noktayı tüm satır öğesi ayrıntılarıyla birlikte çağırır. Sisteminiz, kullanıcıyı sitenizdeki önceden doldurulmuş alışveriş sepetine yönlendiren bir continue_url ile yanıt vermelidir.

• Uç nokta: POST /carts
• Tetikleyici: Tek bir CreateCart (POST /carts) isteği yalnızca kullanıcı, alışveriş sepetini mağazanıza aktarmak için aktarım düğmesini (örneğin, satıcıda ödeme) tıkladığında tetiklenir.

Alışveriş sepeti akışı

Alışveriş sepeti akışı ve durumu şu şekilde işler:

• Google'da biriktirme: Kullanıcı alışveriş sepetine öğe eklediğinde Google bu öğeleri yerel olarak biriktirir. Google, öğeler eklendikçe birden fazla API çağrısı yapmaz.
• Yük: Tek POST /carts isteği, birikmiş tüm line_items'lerin dizisini aynı anda içerir.
• Yönlendirme ve durum: Satıcının arka ucu, web sitesindeki önceden doldurulmuş alışveriş sepetine yönlendiren bir continue_url ile yanıt verir.

İstek: Google, alışveriş sepetine eklenecek line_items dizisini gönderir.

İstek örneği:

{
  "line_items": [
    {
      "item": {
        "id": "item_123"
      },
      "quantity": 2
    }
  ]
}

Yanıt: Satır öğesi ayrıntıları, toplamlar ve continue_url dahil olmak üzere başlatılan alışveriş sepeti oturumunu döndürürsünüz. Yanıtın continue_url alanında, kullanıcının alışveriş sepetini yönetmeye devam edebileceği sitenizdeki bir sayfaya yönlendirme yapılmalıdır. Bu bağlantı genellikle id ile tanımlanan oturum önceden yüklenmiş şekilde alışveriş sepetinize veya ödeme sayfanıza yönlendirir.

Yanıt örneği:

{
  "ucp": {
    "version": "2026-04-08",
    "capabilities": {
      "dev.ucp.shopping.cart": [{"version": "2026-04-08"}]
    }
  },
  "id": "cart_abc123",
  "line_items": [
    {
      "id": "li_1",
      "item": {
        "id": "item_123",
        "title": "Red T-Shirt",
        "price": 2500
      },
      "quantity": 2,
      "totals": [
        {"type": "subtotal", "amount": 5000},
        {"type": "total", "amount": 5000}
      ]
    }
  ],
  "currency": "USD",
  "totals": [
    {
      "type": "subtotal",
      "amount": 5000
    },
    {
      "type": "total",
      "amount": 5000,
      "display_text": "Estimated total (taxes calculated at checkout)"
    }
  ],
  // Used for redirecting the user back to the merchant's cart experience from Google surfaces.
  "continue_url": "https://business.example.com/checkout?cart=cart_abc123",
  // Indicate the timestamp at which the cart session will expire and become invalid.
  "expires_at": "2026-01-16T12:00:00Z"
}

Hata işleme

Hata mesajlarının nasıl biçimlendirileceği ve protokol ile iş mantığı hataları arasındaki fark hakkında eksiksiz yönergeler için Hata kodları bölümüne bakın.