Evrensel Ticaret Protokolü Eğitimi: İlk UCP Sunucunuzu Kurun

Bu rehberde Evrensel Ticaret Protokolü (UCP) nedir, kimin için geliştirildi, neden yeni bir ticaret standardına ihtiyaç var ve mimarisi nasıl çalışır konularını öğreneceksiniz. 

Ayrıca kendi UCP örnek sunucunuzu kurmak, keşif profilini incelemek, bir ödeme (checkout) oturumu oluşturmak ve yerelde uçtan uca bir akışı çalıştırmak için uygulamalı bir adım adım yürütmeyi takip edeceksiniz. 

Bu sayede hem protokolü açıkça anlayacak hem de UCP’nin gerçek bir uygulamada nasıl çalıştığını test etmek için pratik bir başlangıç noktasına sahip olacaksınız.

Evrensel Ticaret Protokolüne Giriş

Evrensel Ticaret Protokolü, AI ajanları, uygulamalar, işletmeler ve ödeme sağlayıcılarının tek bir paylaşılan alışveriş akışında birlikte çalışmasına yardımcı olan açık bir standarttır. Her yeni iş ortağı için özel bir entegrasyon kurmak yerine, UCP ortak bir iletişim yolu sunar.

UCP, insanların ürünleri AI asistanları ve sohbet tabanlı arayüzler aracılığıyla keşfettiği ve satın aldığı modern ajan öncülüğündeki alışveriş için tasarlanmıştır. Bir işletmenin sunduklarını keşfetmekten ödeme başlatmaya ve satın alımı yapılandırılmış biçimde yönetmeye kadar tüm yolculuğu destekler.

Kaynak: Google Developers Blog

Basitçe söylemek gerekirse, UCP ticaret için ortak bir dil gibi çalışır. Bir işletme desteklediklerini yayımlar; bir ajan bu bilgiyi okur ve tek seferlik bir API entegrasyonuna ihtiyaç duymadan etkileşim kurar. Shopify bunu, ölçekli ajan temelli ticareti destekleyecek altyapı olarak tanımlar.

UCP ayrıca açık kaynaklı ve satıcıdan bağımsızdır. Mevcut ticaret sistemleriyle çalışacak şekilde tasarlanmıştır ve güvenli ajan yönlendirmeli ödemeler için Agent Payments Protocol (AP2) ile uyumludur. REST API’leri, ajanlar arası iletişim ve MCP dahil olmak üzere farklı taşıma katmanlarında da çalışabilir. 

Evrensel Ticaret Protokolü Kimin İçin Geliştirildi?

UCP, modern dijital ticarette yer alan ana gruplar için geliştirilmiştir. Amacı, her bağlantı için özel entegrasyonlara gerek kalmadan birlikte çalışmalarını sağlamak üzere hepsine ortak bir iletişim yolu sunmaktır.

Başlıca şu gruplar için tasarlanmıştır:

1. AI ajanları ve tüketici platformları

Bunlar, kullanıcıların ürün bulmasına ve satın alma işlemi yapmasına yardımcı olan uygulamalar, asistanlar ve keşif yüzeyleridir. UCP, bir işletmenin neyi desteklediğini anlamalarına ve yapılandırılmış biçimde etkileşim kurmalarına yardımcı olur. Google bunu, kesintisiz alışveriş için tüketici yüzeylerini işletme arka uçlarına bağlamak olarak tanımlar.

2. İşletmeler ve satıcılar

UCP, işletmelerin ürünlerini, ödeme (checkout) akışlarını ve desteklenen özelliklerini standart bir formatta sunmalarına yardımcı olur. Bu da, her biri için ayrı entegrasyon geliştirmeden farklı AI platformları ve ajanlarla çalışmayı kolaylaştırır.

3. Ödeme sağlayıcıları

Ödeme sağlayıcıları da UCP ekosisteminin bir parçasıdır. Protokol, farklı ödeme işleyicilerini ve ödeme kimlik bilgilerini esnek biçimde desteklemek üzere tasarlanmıştır; böylece ödemeler farklı sistemlerde güvenli biçimde işlenebilir.

4. Geliştiriciler ve protokol oluşturucular

UCP açık kaynaklıdır; bu nedenle standardı uygulamak, genişletmek veya katkıda bulunmak isteyen geliştiriciler için de tasarlanmıştır. UCP projesi, protokolün geleceğini şekillendirmeye yardımcı olmaları için işletmeleri, geliştiricileri ve ödeme sağlayıcılarını açıkça davet eder.

Kısacası, UCP AI destekli ticarette yer alan herkes için geliştirildi: Kullanıcıya alışverişte yardımcı olan platform, ürünü satan işletme, işlemi işleyen ödeme sistemi ve aradaki bağlantıları kuran geliştiriciler.

Neden Yeni Bir Ticaret Standardı Gerekli

Yeni bir ticaret standardına ihtiyaç var çünkü mevcut sistemlerin çoğu geleneksel web siteleri ve mobil uygulamalar için geliştirildi; AI asistanları ve sohbet tabanlı alışveriş için değil. 

Bu eski model, çoğunlukla özel API’lere ve tek seferlik entegrasyonlara dayanır; bu da birçok platformda ölçeklemeyi yavaş ve zor hale getirir. UCP, işletmelere, ajanlara ve platformlara ortak bir iletişim yolu sunarak bunu çözmek için oluşturuldu.

Daha fazla insan alışverişi AI araçları üzerinden yapmaya başladıkça, ticaretin aynı sohbet içinde ürün keşfi, ödeme, indirimler ve sipariş güncellemeleri gibi canlı eylemleri desteklemesi gerekir. 

UCP, deneyimin daha etkileşimli olduğu ve farklı dijital yüzeylerde gerçekleştiği bu yeni alışveriş tarzı için tasarlanmıştır.

Ayrıca günümüzün ticaret ekosistemi parçalıdır. Farklı işletmeler, ödeme sağlayıcıları ve platformlar çoğu zaman farklı sistemler kullanır. UCP, aynı entegrasyonları tekrar tekrar inşa etmek zorunda kalmadan birlikte çalışmalarını sağlamak için ortak bir standartla onları bir araya getirir.

Özetle, UCP’ye ihtiyaç var çünkü eski ticaret araçları AI öncülüğündeki alışveriş için inşa edilmedi. İnsanların bundan sonra ürünleri keşfetme ve satın alma biçimi için daha modern ve esnek bir temel sunar.

Evrensel Ticaret Protokolü Mimarısını Anlamak

Evrensel Ticaret Protokolü (UCP), ajan temelli ticaret için modüler bir sistemdir. İşletmelere, AI ajanlarına ve ödeme sağlayıcılarına, keşiften ödemeye ve ötesine uzanan alışveriş yolculuğunu ortak bir biçimde ele alma imkânı sunar. 

Her platform için ayrı özel entegrasyonlar kurmak yerine, UCP bir işletmenin desteklediklerini yayımlamasına ve bir ajanın bu bilgiyi okuyup standart bir akışı izlemesine olanak tanır. 

UCP modüler ve genişletilebilir olacak şekilde tasarlanmıştır; REST, MCP ve A2A gibi taşıma katmanlarını destekler ve işletmelerin mevcut ödeme kurulumlarını daha kolay kullanabilmesi için ödeme işleyicileriyle çalışır.

1. İşletme bir keşif profili yayımlar

UCP etkin bir işletme, /.well-known/ucp yolunda bir profil sunar. Bu profil, herhangi bir işlem başlamadan önce işletmenin hangi yetenekleri ve uç noktaları desteklediğini platformlara ve ajanlara bildirir.

2. Ajan desteklenen yetenekleri okur

Keşiften sonra, ajan işletmenin sunduğu hizmetleri ve yetenekleri kontrol eder. UCP’nin ilk sürümü, protokolün ana yapı taşları olarak işlev gören Checkout, Kimlik Bağlama (Identity Linking) ve Sipariş Yönetimi (Order Management) gibi temel yeteneklere odaklanır.

3. Uzantılar ek özellikler katar

UCP, çekirdek akışı basit tutar; fakat işletmeler ihtiyaç duyduklarında isteğe bağlı uzantılar ekleyebilir. Bu uzantılar temel yetenekler üzerine inşa edilir ve tüm protokolü değiştirmeden daha zengin özelliklerin desteklenmesine imkân verir.

4. Akış desteklenen bir taşıma katmanından yürütülür

Ajan nelerin desteklendiğini öğrendikten sonra, işletmeyle REST, MCP veya A2A gibi desteklenen bir taşıma katmanını kullanarak etkileşime girebilir. Bu, aynı ticaret mantığını API’ler, AI araçları ve ajan-ajan sistemler arasında kullanmayı kolaylaştırır.

5. Ödeme, ödeme işleyicileri üzerinden gerçekleştirilir

UCP, ticaret akışını ödeme katmanından ayırır. İşletmeler destekledikleri ödeme işleyicilerini beyan edebilir; protokol, satıcıların her şeyi sıfırdan kurmak yerine mevcut ödeme entegrasyonlarını kullanmaya devam edebilmesi için tasarlanmıştır.

6. Güvenli ajan öncülüğündeki ödemeler AP2 ile yapılabilir

UCP, Agent Payments Protocol (AP2) ile uyumludur; bu da ajan yönlendirmeli ödemeler için güvenli bir katman ekler. Bir AI ajanı kullanıcı adına işlem yaparken daha güvenli yetkilendirmeyi desteklemeye yardımcı olur.

Uçtan Uca Evrensel Ticaret Protokolü Yürütmesi

Bu rehber, Python başvuru uygulamasını kullanarak tam bir Evrensel Ticaret Protokolü akışını gösterir. Örnek satıcı sunucusunu kuracak, bir demo çiçekçi kataloğunu yükleyecek, işletme yeteneklerini keşfedecek, bir ödeme oturumu oluşturacak, bir indirim uygulayacak ve ardından sunucuyu durduracaksınız.

Adım 1: İşletme sunucusunu kurun

Bu adımda Python bağımlılık yönetimi için uv kuracak, ardından UCP Python SDK ile örnek sunucu deposunu klonlayacaksınız. Örnek sunucunun README dosyası aynı kurulum desenini izler ve örnekler için SDK’ya giden göreli yolun önemli olduğunu belirtir.

İşletim sistemimiz Linux olduğundan, uv kurmak için aşağıdaki komutu kullanacağız. uv hızlı ve güvenilir bir Python paket ve ortam yöneticisidir. Amaca göre Anaconda gibi araçlara benzer, ancak çok daha hafif ve hızlıdır.

curl -LsSf https://astral.sh/uv/install.sh | sh

Kurulum tamamlandıktan sonra, uv komutunun geçerli kabukta kullanılabilir olması için terminal oturumunuzu yeniden yükleyin.

source ~/.bashrc

Sonra sdk adlı yeni bir klasör oluşturun. Bu klasör, GitHub deposundan klonladığımızda Evrensel Ticaret Protokolü Python SDK’sını barındıracaktır. 

mkdir sdk
git clone https://github.com/Universal-Commerce-Protocol/python-sdk.git 
sdk/python

Şimdi SDK deposunun klonlandığı sdk/python dizinine geçin.

pushd sdk/python

SDK dizinine girdikten sonra, uv sync kullanarak SDK için gerekli tüm Python bağımlılıklarını kurun.

uv sync

Bağımlılıklar kurulduktan sonra, önceki çalışma dizininize geri dönün.

popd

Şimdi bu yürütmede kullanılan Python başvuru satıcı sunucusunu içeren örnekler deposunu klonlayın.

git clone https://github.com/Universal-Commerce-Protocol/samples.git

Ardından, örnekler deposu içindeki Python sunucu örneğine geçin.

cd samples/rest/python/server

Son olarak, örnek sunucuyu çalıştırmak için gerekli tüm Python bağımlılıklarını kurun.

uv sync

Bu noktada, örnek işletme sunucusu çalışma alanınızda hazırdır. Bu sunucu UCP tarafından tanımlanan temel alışveriş yeteneklerini zaten uygular.

Adım 2: Örnek bir ürün veritabanı oluşturun

Bu adımda, örnek işletme için yerel, SQLite tabanlı bir demo mağaza oluşturacaksınız. Bu dersteki örnek işletme bir çiçekçidir ve bu komut, sunucunun kullanacağı örnek ürün kataloğunu ve işlem veritabanını yükler.

Önce, veritabanı dosyalarının saklanacağı geçici bir klasör oluşturun.

mkdir /tmp/ucp_test

Ardından, ürün ve işlem veritabanlarını oluşturmak ve doldurmak için içe aktarma komut dosyasını çalıştırın.

uv run import_csv.py \
  --products_db_path=/tmp/ucp_test/products.db \
  --transactions_db_path=/tmp/ucp_test/transactions.db \
  --data_dir=../test_data/flower_shop

Bu komut şunları yapar:

• --products_db_path ürün kataloğu veritabanını oluşturur.
• --transactions_db_path ödeme (checkout) durumu için kullanılan işlem veritabanını oluşturur.
• --data_dir=../test_data/flower_shop depoda yer alan örnek çiçekçi verilerini işaret eder.

Bu adım tamamlandığında, yerel örnek mağaza verileriniz hazır olacak ve sunucu bunları kullanabilecektir.

Adım 3: İşletme sunucusunu başlatın

Bu adımda, örnek UCP işletme sunucusunu başlatacaksınız. Bu sunucu, önceki adımda oluşturduğunuz ürün ve işlem veritabanlarını kullanacak ve UCP alışveriş API’lerini 8182 portunda sunacaktır.

Sunucuyu arka planda başlatmak için aşağıdaki komutu çalıştırın.

uv run server.py \
  --products_db_path=/tmp/ucp_test/products.db \
  --transactions_db_path=/tmp/ucp_test/transactions.db \
  --port=8182 &
SERVER_PID=$!

Bu komut şunları yapar:

• uv run server.py örnek Python sunucusunu başlatır.
• --products_db_path sunucuyu ürün veritabanına bağlar.
• --transactions_db_path sunucuyu işlem veritabanına bağlar.
• --port=8182 sunucunun 8182 portunda çalışmasını söyler.
• & işlemi arka planda çalıştırır; böylece terminali kullanmaya devam edebilirsiniz.
• SERVER_PID=$! süreç kimliğini kaydeder; böylece sunucuyu daha sonra durdurabilirsiniz.

Bu noktada işletme sunucusu çalışıyor ve bir ajandan gelecek isteklere hazır.

Adım 4: İşletme yeteneklerini keşfedin

Bu adımda UCP keşif uç noktasını sorgulayacaksınız. UCP etkin her işletme, /.well-known/ucp yolunda bir keşif belgesi yayımlar; bu da ajanların herhangi bir istekte bulunmadan önce işletmenin neyi desteklediğini anlamasına olanak tanır.

Önce, sonraki komutların okunmasını kolaylaştırmak için sunucu URL’sini bir değişkende saklayın.

export SERVER_URL=http://localhost:8182

Şimdi işletme sunucusundan UCP keşif belgesini alın.

curl -s $SERVER_URL/.well-known/ucp

Bu yanıt ajana şunları bildirir:

• sunucunun hangi UCP sürümünü desteklediğini,
• hangi hizmetlerin mevcut olduğunu,
• hangi yeteneklerin (ör. checkout ve indirimler) uygulandığını,
• ve hangi ödeme işleyicilerinin veya şemalarının desteklendiğini.

Bu keşif adımı, sabit kodlanmış özel entegrasyonlara duyulan ihtiyacı ortadan kaldırdığı için önemlidir. Ajan önce sunucuyu inceleyebilir ve ardından nasıl etkileşim kuracağına karar verebilir.

Adım 5: Bir ödeme (checkout) oturumu oluşturun

Bu adımda, UCP checkout yeteneğini kullanarak yeni bir ödeme oturumu oluşturacaksınız. Bu noktada ajan, seçilen ürünü, alıcı bilgilerini ve ödeme yapısını işletme sunucusuna gönderir.

İsteği göndermeden önce, gerekli istek başlıklarını oluşturun. Bu başlıklar istek izleme, idempotency ve imza doğrulamasına yardımcı olur.

export REQUEST_ID=$(uuidgen 2>/dev/null || cat /proc/sys/kernel/random/uuid)
export IDEMPOTENCY_KEY=$(uuidgen 2>/dev/null || cat /proc/sys/kernel/random/uuid)
export REQUEST_SIGNATURE="dev"

Bu şunları yapar:

• REQUEST_ID istek için benzersiz bir tanımlayıcı oluşturur.
• IDEMPOTENCY_KEY tekrarlandığında aynı isteğin iki kez işlenmemesini sağlar.
• REQUEST_SIGNATURE gerekli imza başlığını sağlar. Yerel bir demoda, katı imza doğrulaması zorunlu değilse "dev" kullanılabilir.

Şimdi checkout isteğini sunucuya gönderin.

curl -X POST "$SERVER_URL/checkout-sessions" \
  -H "Content-Type: application/json" \
  -H "UCP-Agent: profile=\"https://agent.example/profile\"" \
  -H "request-id: $REQUEST_ID" \
  -H "idempotency-key: $IDEMPOTENCY_KEY" \
  -H "request-signature: $REQUEST_SIGNATURE" \
  -d '{
    "line_items": [
      { "item": { "id": "bouquet_roses", "title": "Red Rose" }, "quantity": 1 }
    ],
    "buyer": { "full_name": "John Doe", "email": "john.doe@example.com" },
    "currency": "USD",
    "payment": { "handlers": [], "instruments": [] }
  }'

Bu istek şunları içerir:

• line_items alıcının ne satın almak istediğini tanımlar,
• item.id ürünü tanımlar,
• item.title okunabilir bir ad sağlar,
• quantity satın alınan birim sayısını belirtir,
• buyer müşteri ayrıntılarını içerir,
• currency ödeme para birimini tanımlar,
• ve payment gerekli ödeme yapısını sağlar.

Yanıt, yeni checkout kimliği, satır öğesi kimlikleri, toplamlar, alıcı bilgileri ve mevcut checkout durumunu içeren bir checkout oturumu nesnesi döndürür.

Adım 6: UCP kullanarak indirim uygulayın

Bu adımda, mevcut checkout oturumunu güncelleyip bir indirim kodu uygulayacaksınız. UCP’de indirimler, checkout yeteneğinin bir uzantısı olarak uygulanır; bu nedenle indirim, checkout güncelleme isteğinin bir parçası olarak eklenir.

Önce, önceki checkout yanıtından dönen gerçek checkout kimliğini ve satır öğesi kimliğini kaydedin.

export CHECKOUT_ID=5dd08e18-c9c1-4fa1-a0d1-885ca81cda29
export LINE_ITEM_ID=ed72ebe6-2484-4e7b-afc8-a8ff5c8f430e

Ardından, bu güncelleme isteği için yeni bir istek kimliği ve idempotency anahtarı oluşturun.

export REQUEST_ID=$(uuidgen 2>/dev/null || cat /proc/sys/kernel/random/uuid)
export IDEMPOTENCY_KEY=$(uuidgen 2>/dev/null || cat /proc/sys/kernel/random/uuid)
export REQUEST_SIGNATURE="dev"

Şimdi indirim kodunu içeren güncellenmiş checkout isteğini gönderin.

curl -X PUT "$SERVER_URL/checkout-sessions/$CHECKOUT_ID" \
  -H "Content-Type: application/json" \
  -H "UCP-Agent: profile=\"https://agent.example/profile\"" \
  -H "request-id: $REQUEST_ID" \
  -H "idempotency-key: $IDEMPOTENCY_KEY" \
  -H "request-signature: $REQUEST_SIGNATURE" \
  -d "{
    \"id\": \"$CHECKOUT_ID\",
    \"line_items\": [
      {
        \"id\": \"$LINE_ITEM_ID\",
        \"item\": { \"id\": \"bouquet_roses\", \"title\": \"Red Rose\" },
        \"quantity\": 1
      }
    ],
    \"buyer\": {
      \"full_name\": \"John Doe\",
      \"email\": \"john.doe@example.com\"
    },
    \"currency\": \"USD\",
    \"discounts\": {
      \"codes\": [\"10OFF\"]
    },
    \"payment\": {
      \"handlers\": [],
      \"instruments\": []
    }
  }"

Bu istek şunları yapar:

• PUT kullanarak mevcut checkout’u günceller,
• orijinal checkout kimliğini içerir,
• satır öğesini tekrar ekler,
• discounts bölümünü ekler,
• 10OFF kodunu uygular.

Yanıt, aşağıdakileri içeren güncellenmiş checkout nesnesini döndürmelidir:

• yeniden hesaplanan toplamlar,
• indirim tutarı,
• nihai güncel toplam,
• ve uygulanan indirim ayrıntıları.

İndirim kodu geçerlidir; yanıtta fiyat değişikliğini görmelisiniz.

Adım 7: Sunucuyu kapatın

Son adımda, daha önce başlattığınız örnek işletme sunucusunu durduracaksınız. Sunucuyu başlatırken süreç kimliğini kaydettiğiniz için, tek komutla kolayca kapatabilirsiniz.

Sunucuyu durdurmak için aşağıdaki komutu çalıştırın.

kill $SERVER_PID

Baştan sona, yerel makinenizde tam bir uçtan uca UCP akışını başarıyla kurup test ettiniz.

Şunları yaptınız:

• uv kullanarak gerekli Python araçlarını kurdunuz,
• UCP Python SDK’sını ve örnek sunucu depolarını klonladınız,
• örnek bir çiçekçi ürün veritabanı oluşturdunuz,
• işletme sunucusunu başlattınız,
• keşif uç noktası aracılığıyla sunucunun UCP yeteneklerini keşfettiniz,
• bir ajan olarak checkout oturumu oluşturdunuz,
• o checkout’u bir indirim kodu uygulayarak güncellediniz,
• ve son olarak sunucuyu kapattınız.

Özetle, UCP etkin bir işletmeyi kurdunuz, bir ajan gibi ona bağlandınız, alışveriş checkout’u oluşturdunuz ve UCP’nin indirimler gibi güncellemeleri nasıl ele aldığını test ettiniz. Bu, bir işletme ile bir ajanın Evrensel Ticaret Protokolünü kullanarak nasıl etkileşim kurabileceğine dair tam bir temel örnek sunar.

Sonuç

Evrensel Ticaret Protokolü, sektör için AI öncülüğündeki ticarette ortak bir temel sunar. İşletmelerin, AI ajanlarının ve ödeme sistemlerinin standart bir biçimde iletişim kurmasını sağlayarak her yeni platform için özel entegrasyonları yeniden kurmaya gerek kalmadan keşif, checkout, güncellemeler ve ödemeleri desteklemeyi kolaylaştırır.

Bu rehberde UCP’nin ne olduğunu, neden önemli olduğunu, mimarisinin nasıl çalıştığını ve baştan sona yerel bir örneğin nasıl çalıştırılacağını öğrendiniz. Örnek sunucuyu kurup yeteneklerini keşfederek, bir checkout oturumu oluşturup indirim uygulayarak UCP’nin ticareti nasıl yapılandırılmış, ajan dostu bir iş akışına dönüştürdüğünü gördünüz.

UCP’nin en büyük fırsatı net: Alışverişin giderek AI asistanları ve sohbet arayüzleri üzerinden gerçekleştiği bir dünyada parçalanmayı azaltabilir ve ticareti daha birlikte çalışabilir hale getirebilir. 

Ancak asıl zorluk benimsenme olacaktır. İşletmeler yine de özel API’leri, mevcut REST tabanlı entegrasyonları, MCP tabanlı araçları veya hâlihazırda kullandıkları diğer ajan iş akışlarını tercih edebilir. UCP’nin başarılı olması için satıcılardan, platformlardan, geliştiricilerden ve ödeme sağlayıcılardan güçlü ekosistem desteğine ihtiyaç duyacaktır.