Tutorial Universal Commerce Protocol: Bangun Server UCP Pertama Anda

Dalam panduan ini, Anda akan mempelajari apa itu Universal Commerce Protocol (UCP), untuk siapa protokol ini dibuat, mengapa diperlukan standar niaga baru, dan bagaimana arsitekturnya bekerja. 

Anda juga akan mengikuti walkthrough praktis untuk menyiapkan server contoh UCP Anda sendiri, menelusuri discovery profile, membuat sesi checkout, dan menjalankan alur contoh lengkap secara lokal. 

Ini akan memberi Anda pemahaman yang jelas tentang protokol sekaligus titik awal praktis untuk menguji cara kerja UCP dalam implementasi nyata.

Pengantar Universal Commerce Protocol

Universal Commerce Protocol adalah standar terbuka yang membantu agen AI, aplikasi, bisnis, dan penyedia pembayaran bekerja bersama dalam satu alur belanja terpadu. Alih-alih membangun integrasi kustom untuk setiap mitra baru, UCP menyediakan cara umum untuk berkomunikasi.

UCP dirancang untuk belanja yang dipimpin agen masa kini, di mana orang menemukan dan membeli produk melalui asisten AI dan antarmuka percakapan. Protokol ini mendukung seluruh perjalanan, dari menemukan apa yang ditawarkan sebuah bisnis hingga memulai checkout dan mengelola pembelian secara terstruktur.

Sumber: Google Developers Blog

Secara sederhana, UCP bertindak seperti bahasa bersama untuk perdagangan. Sebuah bisnis dapat memublikasikan apa yang didukungnya, dan agen dapat membaca informasi itu lalu berinteraksi tanpa perlu integrasi API satu per satu. Shopify menggambarkannya sebagai infrastruktur yang dibangun untuk mendukung agentic commerce dalam skala besar.

UCP juga bersifat open source dan netral terhadap vendor. Protokol ini dirancang untuk bekerja dengan sistem niaga yang sudah ada, serta kompatibel dengan Agent Payments Protocol (AP2) untuk pembayaran yang dipimpin agen secara aman. Protokol ini juga dapat bekerja lintas berbagai transport, termasuk REST API, komunikasi antargen, dan MCP. 

Untuk Siapa Universal Commerce Protocol Dibuat?

UCP dibuat untuk kelompok utama yang terlibat dalam niaga digital modern. Tujuannya adalah memberi mereka semua cara berkomunikasi bersama, sehingga dapat bekerja sama tanpa membutuhkan integrasi kustom untuk setiap koneksi.

Protokol ini terutama dirancang untuk:

1. Agen AI dan platform konsumen

Ini adalah aplikasi, asisten, dan permukaan penemuan yang membantu pengguna menemukan produk dan melakukan pembelian. UCP membantu mereka memahami apa yang didukung sebuah bisnis dan berinteraksi dengannya secara terstruktur. Google menggambarkannya sebagai menghubungkan permukaan konsumen dengan backend bisnis untuk pengalaman belanja yang mulus.

2. Bisnis dan merchant

UCP membantu bisnis mengekspos produk, alur checkout, dan fitur yang didukung dalam format standar. Ini memudahkan mereka bekerja dengan berbagai platform dan agen AI tanpa membangun integrasi terpisah untuk masing-masing.

3. Penyedia pembayaran

Penyedia pembayaran juga menjadi bagian dari ekosistem UCP. Protokol ini dirancang untuk mendukung berbagai penangan pembayaran dan kredensial pembayaran secara fleksibel, sehingga pembayaran dapat ditangani secara aman di berbagai sistem.

4. Pengembang dan pembangun protokol

UCP bersifat open source, sehingga juga ditujukan bagi pengembang yang ingin mengimplementasikan, memperluas, atau berkontribusi pada standar tersebut. Proyek UCP secara eksplisit mengundang bisnis, pengembang, dan penyedia pembayaran untuk membantu membentuk masa depan protokol ini.

Singkatnya, UCP dibuat untuk siapa pun yang terlibat dalam niaga berbasis AI: platform yang membantu pengguna berbelanja, bisnis yang menjual produk, sistem pembayaran yang memproses transaksi, dan pengembang yang membangun koneksi di antara mereka.

Mengapa Diperlukan Standar Niaga yang Baru

Diperlukan standar niaga baru karena sebagian besar sistem niaga saat ini dibangun untuk situs web tradisional dan aplikasi seluler, bukan untuk asisten AI dan belanja percakapan. 

Model lama itu sering bergantung pada API kustom dan integrasi satu per satu, yang membuatnya lambat dan sulit ditingkatkan di banyak platform. UCP diciptakan untuk mengatasi hal tersebut dengan memberi bisnis, agen, dan platform satu cara bersama untuk berkomunikasi.

Seiring makin banyak orang berbelanja melalui alat AI, perdagangan perlu mendukung tindakan langsung seperti penemuan produk, checkout, diskon, dan pembaruan pesanan di dalam percakapan yang sama. 

UCP dirancang untuk gaya belanja yang lebih baru ini, di mana pengalamannya lebih interaktif dan terjadi di berbagai permukaan digital.

Protokol ini juga diperlukan karena ekosistem niaga saat ini terfragmentasi. Beragam bisnis, penyedia pembayaran, dan platform sering memakai sistem yang berbeda. UCP membantu menyatukan mereka dengan standar umum, sehingga dapat bekerja bersama tanpa harus membangun ulang integrasi yang sama berulang kali.

Secara sederhana, UCP diperlukan karena alat niaga lama tidak dibangun untuk belanja yang dipimpin AI. Protokol ini memberi industri fondasi yang lebih modern dan fleksibel untuk cara orang menemukan dan membeli produk ke depan.

Memahami Arsitektur Universal Commerce Protocol

Universal Commerce Protocol (UCP) adalah sistem modular untuk agentic commerce. Protokol ini memberi bisnis, agen AI, dan penyedia pembayaran cara bersama untuk menangani perjalanan belanja, dari penemuan hingga checkout dan seterusnya. 

Alih-alih membangun integrasi kustom terpisah untuk setiap platform, UCP memungkinkan bisnis memublikasikan apa yang didukungnya agar agen dapat membaca informasi itu dan mengikuti alur standar. 

UCP dirancang modular dan dapat diperluas, mendukung transport seperti REST, MCP, dan A2A, dan bekerja dengan penangan pembayaran sehingga bisnis dapat lebih mudah menggunakan pengaturan pembayaran yang ada.

1. Bisnis memublikasikan discovery profile

Bisnis yang mendukung UCP mengekspos profil di /.well-known/ucp. Profil ini memberi tahu platform dan agen apa yang didukung bisnis sebelum transaksi dimulai, termasuk kapabilitas dan endpoint yang tersedia.

2. Agen membaca kapabilitas yang didukung

Setelah discovery, agen memeriksa layanan dan kapabilitas yang ditawarkan bisnis. Peluncuran awal UCP berfokus pada kapabilitas inti seperti Checkout, Identity Linking, dan Order Management, yang menjadi blok bangunan utama protokol.

3. Ekstensi menambahkan fitur tambahan

UCP menjaga alur inti tetap sederhana, namun bisnis dapat menambahkan ekstensi opsional bila diperlukan. Ekstensi ini dibangun di atas kapabilitas inti dan memungkinkan bisnis mendukung fitur yang lebih kaya tanpa mengubah keseluruhan protokol.

4. Alur berjalan melalui transport yang didukung

Setelah agen mengetahui apa yang didukung, agen dapat berinteraksi dengan bisnis menggunakan transport yang didukung seperti REST, MCP, atau A2A. Ini memudahkan logika niaga yang sama digunakan lintas API, alat AI, dan sistem antargen.

5. Pembayaran ditangani melalui penangan pembayaran

UCP memisahkan alur niaga dari lapisan pembayaran. Bisnis dapat mendeklarasikan penangan pembayaran yang didukung, dan protokol dirancang agar merchant dapat terus menggunakan integrasi pembayaran yang ada alih-alih membangun ulang dari nol.

6. Pembayaran aman yang dipimpin agen dapat menggunakan AP2

UCP kompatibel dengan Agent Payments Protocol (AP2), yang menambahkan lapisan keamanan untuk pembayaran yang dipimpin agen. Ini membantu mendukung otorisasi yang lebih aman saat agen AI bertindak atas nama pengguna.

Walkthrough Universal Commerce Protocol End-to-End

Panduan ini menunjukkan alur Universal Commerce Protocol lengkap menggunakan implementasi referensi Python. Anda akan menyiapkan server merchant contoh, memuat katalog toko bunga demo, menemukan kapabilitas bisnis, membuat sesi checkout, menerapkan diskon, lalu menghentikan server.

Langkah 1: Siapkan server bisnis

Pada langkah ini, Anda akan memasang uv untuk manajemen dependensi Python, lalu mengkloning UCP Python SDK dan repositori server contoh. README server contoh mengikuti pola penyiapan yang sama dan mencatat bahwa path relatif ke SDK penting untuk contoh.

Karena sistem operasi kita adalah Linux, kita akan menggunakan perintah berikut untuk memasang uv. uv adalah pengelola paket dan lingkungan Python yang cepat dan andal. Fungsinya mirip dengan alat seperti Anaconda, tetapi jauh lebih ringan dan cepat.

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

Setelah pemasangan selesai, muat ulang sesi terminal Anda agar perintah uv tersedia di shell saat ini.

source ~/.bashrc

Selanjutnya, buat folder baru bernama sdk. Folder ini akan menyimpan Universal Commerce Protocol Python SDK saat kita mengkloningnya dari repositori GitHub. 

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

Sekarang pindah ke direktori sdk/python, tempat repositori SDK dikloning.

pushd sdk/python

Setelah berada di dalam direktori SDK, pasang semua dependensi Python yang diperlukan untuk SDK menggunakan uv sync.

uv sync

Setelah dependensi terpasang, kembali ke direktori kerja sebelumnya.

popd

Sekarang klon repositori samples, yang berisi server merchant referensi Python yang digunakan dalam walkthrough ini.

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

Berikutnya, masuk ke contoh server Python di dalam repositori samples.

cd samples/rest/python/server

Terakhir, pasang semua dependensi Python yang diperlukan untuk menjalankan server contoh.

uv sync

Pada titik ini, server bisnis contoh siap di workspace Anda. Server ini sudah mengimplementasikan kapabilitas belanja inti yang didefinisikan oleh UCP.

Langkah 2: Buat database produk contoh

Pada langkah ini, Anda akan membuat toko demo berbasis SQLite lokal untuk bisnis contoh. Bisnis contoh dalam tutorial ini adalah toko bunga, dan perintah ini memuat katalog produk contoh serta database transaksi yang akan digunakan server.

Pertama, buat folder sementara tempat file database akan disimpan.

mkdir /tmp/ucp_test

Selanjutnya, jalankan skrip impor untuk membuat dan mengisi database produk dan transaksi.

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

Perintah ini melakukan hal-hal berikut:

• --products_db_path membuat database katalog produk.
• --transactions_db_path membuat database transaksi yang digunakan untuk status checkout.
• --data_dir=../test_data/flower_shop menunjuk ke data contoh toko bunga yang disertakan dalam repositori.

Setelah langkah ini selesai, data toko contoh lokal Anda siap, dan server akan dapat menggunakannya.

Langkah 3: Mulai server bisnis

Pada langkah ini, Anda akan memulai server bisnis UCP contoh. Server ini akan menggunakan database produk dan transaksi yang Anda buat pada langkah sebelumnya dan mengekspos API belanja UCP pada port 8182.

Jalankan perintah berikut untuk memulai server di latar belakang.

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

Perintah ini melakukan hal-hal berikut:

• uv run server.py memulai server Python contoh.
• --products_db_path menghubungkan server ke database produk.
• --transactions_db_path menghubungkan server ke database transaksi.
• --port=8182 memberi tahu server untuk berjalan pada port 8182.
• & menjalankan proses di latar belakang sehingga Anda dapat terus menggunakan terminal.
• SERVER_PID=$! menyimpan ID proses sehingga Anda dapat menghentikan server nanti.

Pada titik ini, server bisnis berjalan dan siap menerima permintaan dari agen.

Langkah 4: Temukan Kapabilitas bisnis

Pada langkah ini, Anda akan melakukan kueri ke endpoint discovery UCP. Setiap bisnis yang mendukung UCP memublikasikan dokumen discovery di /.well-known/ucp, yang memungkinkan agen memahami apa yang didukung bisnis sebelum membuat permintaan apa pun.

Pertama, simpan URL server dalam variabel agar perintah berikutnya lebih mudah dibaca.

export SERVER_URL=http://localhost:8182

Sekarang ambil dokumen discovery UCP dari server bisnis.

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

Respons ini memberi tahu agen:

• versi UCP mana yang didukung server,
• layanan apa saja yang tersedia,
• kapabilitas apa yang diimplementasikan, seperti checkout dan diskon,
• dan penangan atau skema pembayaran apa yang didukung.

Langkah discovery ini penting karena menghilangkan kebutuhan integrasi kustom yang dikodekan keras. Agen dapat memeriksa server terlebih dahulu lalu memutuskan bagaimana berinteraksi dengannya.

Langkah 5: Buat sesi checkout

Pada langkah ini, Anda akan membuat sesi checkout baru menggunakan kapabilitas checkout UCP. Ini adalah titik ketika agen mengirimkan produk yang dipilih, informasi pembeli, dan struktur pembayaran ke server bisnis.

Sebelum mengirimkan permintaan, buat header permintaan yang diperlukan. Header ini membantu pelacakan permintaan, idempoten, dan validasi tanda tangan.

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"

Ini melakukan hal-hal berikut:

• REQUEST_ID membuat pengenal unik untuk permintaan.
• IDEMPOTENCY_KEY memastikan permintaan yang sama tidak diproses dua kali jika diulang.
• REQUEST_SIGNATURE menyediakan header tanda tangan yang diperlukan. Dalam demo lokal, "dev" dapat digunakan jika validasi tanda tangan ketat tidak diterapkan.

Sekarang kirim permintaan checkout ke server.

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": [] }
  }'

Permintaan ini mencakup:

• line_items untuk mendefinisikan apa yang ingin dibeli pembeli,
• item.id untuk mengidentifikasi produk,
• item.title untuk menyediakan nama yang mudah dibaca,
• quantity untuk menentukan jumlah unit yang dibeli,
• buyer untuk menyertakan detail pelanggan,
• currency untuk mendefinisikan mata uang checkout,
• dan payment untuk menyediakan struktur pembayaran yang diperlukan.

Respons akan mengembalikan objek sesi checkout. Ini mencakup ID checkout baru, ID item baris, total, informasi pembeli, dan status checkout saat ini.

Langkah 6: Terapkan diskon menggunakan UCP

Pada langkah ini, Anda akan memperbarui sesi checkout yang ada dan menerapkan kode diskon. Diskon dalam UCP diimplementasikan sebagai ekstensi dari kapabilitas checkout, sehingga diskon ditambahkan sebagai bagian dari permintaan pembaruan checkout.

Pertama, simpan ID checkout dan ID item baris nyata yang dikembalikan dari respons checkout sebelumnya.

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

Berikutnya, buat ID permintaan dan kunci idempoten baru untuk permintaan pembaruan ini.

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"

Sekarang kirim permintaan checkout yang diperbarui dengan kode diskon disertakan.

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\": []
    }
  }"

Permintaan ini melakukan hal-hal berikut:

• memperbarui checkout yang ada menggunakan PUT,
• menyertakan ID checkout asli,
• menyertakan item baris lagi,
• menambahkan bagian discounts,
• dan menerapkan kode 10OFF.

Respons seharusnya mengembalikan objek checkout yang diperbarui dengan:

• total yang dihitung ulang,
• jumlah diskon,
• total akhir yang diperbarui,
• dan detail diskon yang diterapkan.

Kode diskon valid; Anda akan melihat perubahan harga dalam respons.

Langkah 7: Matikan server

Pada langkah terakhir ini, Anda akan menghentikan server bisnis contoh yang Anda mulai sebelumnya. Karena Anda menyimpan ID proses saat memulai server, Anda dapat mematikannya dengan mudah menggunakan satu perintah.

Jalankan perintah berikut untuk menghentikan server.

kill $SERVER_PID

Dari awal hingga akhir, Anda berhasil membangun dan menguji alur UCP end-to-end lengkap di mesin lokal Anda.

Anda telah:

• memasang tooling Python yang diperlukan menggunakan uv,
• mengkloning repositori UCP Python SDK dan server contoh,
• membuat database produk toko bunga contoh,
• memulai server bisnis,
• menemukan kapabilitas UCP server melalui endpoint discovery,
• membuat sesi checkout sebagai agen,
• memperbarui checkout tersebut dengan menerapkan kode diskon,
• dan akhirnya mematikan server.

Secara sederhana, Anda menyiapkan bisnis yang mendukung UCP, terhubung seperti agen, membuat checkout belanja, dan menguji bagaimana UCP menangani pembaruan seperti diskon. Ini memberi Anda contoh dasar lengkap bagaimana bisnis dan agen dapat berinteraksi menggunakan Universal Commerce Protocol.

Kesimpulan

Universal Commerce Protocol memberi industri fondasi bersama untuk niaga yang dipimpin AI. Protokol ini menciptakan cara standar bagi bisnis, agen AI, dan sistem pembayaran untuk berkomunikasi, sehingga lebih mudah mendukung penemuan, checkout, pembaruan, dan pembayaran tanpa membangun ulang integrasi kustom untuk setiap platform baru.

Dalam panduan ini, Anda telah mempelajari apa itu UCP, mengapa penting, bagaimana arsitekturnya bekerja, dan bagaimana menjalankan contoh lokal lengkap dari awal hingga akhir. Dengan menyiapkan server contoh, menemukan kapabilitasnya, membuat sesi checkout, dan menerapkan diskon, Anda melihat bagaimana UCP mengubah niaga menjadi alur kerja terstruktur yang ramah agen.

Peluang terbesar untuk UCP jelas: protokol ini dapat mengurangi fragmentasi dan membuat niaga lebih dapat dioperasikan di dunia di mana belanja makin banyak terjadi melalui asisten AI dan antarmuka percakapan. 

Tantangan sebenarnya, bagaimanapun, adalah adopsi. Bisnis mungkin tetap memilih API kustom, integrasi berbasis REST yang ada, alat berbasis MCP, atau alur kerja agen lain yang sudah mereka gunakan saat ini. Agar UCP berhasil, diperlukan dukungan ekosistem yang kuat dari merchant, platform, pengembang, dan penyedia pembayaran.