במדריך הזה מפורטים הפניות הטכניות ל-API וסכימות של מטען ייעודי (payload) להעברת עדכונים מלאים של סטטוס ההזמנה, אירועי ביצוע ושינויים ל-Google באמצעות ווּבְּהוּקים (webhooks) לגרסה 2026-01-23 של פרוטוקול המסחר האוניברסלי (UCP).
לפני שיוצרים את נקודות הקצה, חשוב לעיין בסקירה הכללית של מחזור החיים של ההזמנה כדי להבין את המושגים ברמה גבוהה, האירועים שחובה להגדיר ופרטים על נקודות הקצה של ה-webhook.
אימות וחתימה על בקשות
אתם יכולים לחתום על מפתחות סימטריים באמצעות מפתח HMAC ש-Google שיתפה איתכם.
לחלופין, אפשר לפעול לפי ההוראות הבאות ליצירת חתימה אסימטרית:
- בוחרים מפתח ממערך
signing_keysבפרופיל UCP. - יוצרים JWT מנותק (RFC 7797) על גוף הבקשה באמצעות המפתח שנבחר.
- כוללים את ה-JWT בכותרת
Request-Signature. - כדי שהמקבל יוכל לזהות באיזה מפתח להשתמש לאימות, צריך לכלול את מזהה המפתח בהצהרה
kidבכותרת ה-JWT.
אימות חותמת זמן
כש-Google בודקת אם עדכון הזמנה ישן יותר מהעדכון האחרון שנרשם (מה שגורם לדחיית עדכון ההזמנה), היא בודקת את חותמת הזמן באמצעות המאפיין created_time במטען הייעודי (payload).
אירוע יצירת הזמנה
- הפעלה: מיד אחרי אישור ההזמנה (
status: processing).
דוגמה: בדוגמה הזו מוצגת הזמנה שנוצרה אחרי שהקונה השלים את תהליך התשלום.
{
"ucp": {
"version": "2026-01-23",
"capabilities": {
"dev.ucp.shopping.order": [{"version": "2026-01-23"}]
}
},
"id": "order_01",
"checkout_id": "checkout_01",
"created_time": "2026-03-23T19:00:00Z",
// Full line items must be included
"line_items": [
{
"id": "line_1",
"item":
{
"id": "product_123",
"title": "Running Shoes",
"price": 10000
},
"quantity": { "total": 1, "fulfilled": 0 },
"totals": [
{"type": "subtotal", "amount": 10000},
{"type": "total", "amount": 10000}
],
// The status of a line item must match total and fulfilled quantities (e.g., total 1, fulfilled 0 -> status: processing).
"status": "processing"
}
],
"totals": [
{"type": "subtotal", "amount": 10000},
{"type": "total", "amount": 10000}
],
"fulfillment": {
"expectations": [
{
"id": "exp_1",
"line_items": [{ "id": "line_1", "quantity": 1 }],
"method_type": "shipping",
"destination": {
"first_name": "Alice",
"last_name": "Example",
"street_address": "123 Main St",
"address_locality": "Austin",
"address_region": "TX",
"address_country": "US",
"postal_code": "78701"
},
"description": "Arrives in 2-3 business days",
"fulfillable_on": "now"
}
]
},
"permalink_url": "https://merchant.example.com/orders/789"
}
אירועים שקשורים להכנה להפצה
האירועים האלה נשלחים כחלק מהמערך fulfillment.events.
ההזמנה נשלחה
כשהפריטים בהזמנה נשלחו. השדות tracking_number ו-tracking_url הם שדות חובה לאירועים מסוג 'נשלח', כי הם נדרשים כדי לקבץ פריטים בדף 'ההזמנות שלי' בצורה מדויקת.
ההזמנה נמסרה
כשהפריטים בהזמנה נמסרו.
דוגמה (shipped ו-delivered): בדוגמה הזו מוצג עדכון הזמנה אחרי שהפריט נשלח ואז נמסר.
{
"ucp": {
"version": "2026-01-23",
"capabilities": {
"dev.ucp.shopping.order": [{"version": "2026-01-23"}]
}
},
"id": "order_01",
"checkout_id": "checkout_01",
"created_time": "2026-03-23T19:00:00Z",
"line_items": [
{
"id": "line_1",
"item":
{
"id": "product_123",
"title": "Running Shoes",
"price": 10000
},
"quantity": { "total": 1, "fulfilled": 1 },
"totals": [
{"type": "subtotal", "amount": 10000},
{"type": "total", "amount": 10000}
],
"status": "fulfilled"
}
],
"totals": [
{"type": "subtotal", "amount": 10000},
{"type": "total", "amount": 10000}
],
// Updated fulfillment details.
"fulfillment": {
"events": [
{
"id": "fulfill_evt_1",
"occurred_at": "2026-02-08T10:30:00Z",
"type": "shipped",
"line_items": [{ "id": "line_1", "quantity": 1 }],
"tracking_number": "123456789",
"tracking_url": "https://fedex.com/track/123456789",
"carrier": "FedEx",
"description": "Shipping departed from warehouse"
},
{
"id": "fulfill_evt_2",
"occurred_at": "2026-02-10T14:00:00Z",
"type": "delivered",
"line_items": [{ "id": "line_1", "quantity": 1 }],
"tracking_number": "123456789",
"tracking_url": "https://fedex.com/track/123456789",
"carrier": "FedEx",
"description": "Package delivered"
}
],
"expectations": [{ "...": "..." }]
},
"permalink_url": "https://merchant.example.com/orders/123"
}
דוגמאות להזמנות של כמה פריטים
בדוגמאות הבאות אפשר לראות איך לעדכן הזמנות עם כמה פריטים ומשלוחים מפוצלים. כאן מוסבר איך נקבע סטטוס החבילה.
הזמנה של כמה פריטים, משלוח באותה חבילה
בדוגמה הזו מוצג עדכון הזמנה של חבילה אחת שמכילה כמה פריטים. כל פריטי הקמפיין מקובצים בתוך אירוע shipped אחד עם אותו מספר מעקב.
{
"ucp": {
"version": "2026-01-23",
"capabilities": {
"dev.ucp.shopping.order": [{"version": "2026-01-23"}]
}
},
"id": "order_multi_01",
"checkout_id": "checkout_multi_01",
"created_time": "2026-02-07T09:00:00Z",
"line_items": [
{
"id": "line_1",
"item": { "id": "product_1", "title": "Item 1", "price": 5000 },
"quantity": { "total": 1, "fulfilled": 1 },
"totals": [
{"type": "subtotal", "amount": 5000},
{"type": "total", "amount": 5000}
],
"status": "fulfilled"
},
{
"id": "line_2",
"item": { "id": "product_2", "title": "Item 2", "price": 5000 },
"quantity": { "total": 1, "fulfilled": 1 },
"totals": [
{"type": "subtotal", "amount": 5000},
{"type": "total", "amount": 5000}
],
"status": "fulfilled"
}
],
"totals": [
{"type": "subtotal", "amount": 10000},
{"type": "fee", "amount": 500},
{"type": "total", "amount": 10500}
],
"fulfillment": {
"expectations": [
{
"id": "exp_1",
"line_items": [
{ "id": "line_1", "quantity": 1 },
{ "id": "line_2", "quantity": 1 }
],
"method_type": "shipping",
"destination": {
"first_name": "Alice",
"last_name": "Example",
"street_address": "123 Main St",
"address_locality": "Austin",
"address_region": "TX",
"address_country": "US",
"postal_code": "78701"
},
"description": "Standard Shipping",
"fulfillable_on": "now"
}
],
"events": [
{
"id": "fulfill_evt_1",
"occurred_at": "2026-02-08T10:30:00Z",
"type": "shipped",
"line_items": [
{ "id": "line_1", "quantity": 1 },
{ "id": "line_2", "quantity": 1 }
],
"tracking_number": "123456789",
"tracking_url": "https://fedex.com/track/123456789",
"carrier": "FedEx",
"description": "Both items shipped together"
}
]
},
"permalink_url": "https://merchant.example.com/orders/456"
}
הזמנה של כמה פריטים, משלוח מפוצל
בדוגמה הזו מוצג עדכון לגבי הזמנה שכוללת משלוחים מפוצלים. יש כמה אירועים מסוג shipped, שכל אחד מהם מתייחס לline_items הספציפי בחבילה הרלוונטית, עם מספרי מעקב שונים. מכיוון שכל חבילה מייצגת התחייבות שונה לביצוע ההזמנה (למשל, מהירויות ועלויות שונות בתהליך תשלום עם כמה קבוצות), גם המאפיינים expectations מחולקים.
{
"ucp": {
"version": "2026-01-23",
"capabilities": {
"dev.ucp.shopping.order": [{"version": "2026-01-23"}]
}
},
"id": "order_multi_02",
"checkout_id": "checkout_multi_02",
"created_time": "2026-02-07T09:00:00Z",
"line_items": [
{
"id": "line_1",
"item": { "id": "product_1", "title": "Item 1", "price": 5000 },
"quantity": { "total": 1, "fulfilled": 1 },
"totals": [
{"type": "subtotal", "amount": 5000},
{"type": "total", "amount": 5000}
],
"status": "fulfilled"
},
{
"id": "line_2",
"item": { "id": "product_2", "title": "Item 2", "price": 5000 },
"quantity": { "total": 1, "fulfilled": 1 },
"totals": [
{"type": "subtotal", "amount": 5000},
{"type": "total", "amount": 5000}
],
"status": "fulfilled"
}
],
"totals": [
{"type": "subtotal", "amount": 10000},
{"type": "fee", "amount": 1500},
{"type": "total", "amount": 11500}
],
"fulfillment": {
"expectations": [
{
"id": "exp_1",
"line_items": [{ "id": "line_1", "quantity": 1 }],
"method_type": "shipping",
"destination": {
"first_name": "Alice",
"last_name": "Example",
"street_address": "123 Main St",
"address_locality": "Austin",
"address_region": "TX",
"address_country": "US",
"postal_code": "78701"
},
"description": "Standard Shipping",
"fulfillable_on": "now"
},
{
"id": "exp_2",
"line_items": [{ "id": "line_2", "quantity": 1 }],
"method_type": "shipping",
"destination": {
"first_name": "Alice",
"last_name": "Example",
"street_address": "123 Main St",
"address_locality": "Austin",
"address_region": "TX",
"address_country": "US",
"postal_code": "78701"
},
"description": "Express Shipping",
"fulfillable_on": "now"
}
],
"events": [
{
"id": "fulfill_evt_1",
"occurred_at": "2026-02-08T10:30:00Z",
"type": "shipped",
"line_items": [{ "id": "line_1", "quantity": 1 }],
"tracking_number": "PKG1_TRACKING",
"tracking_url": "https://fedex.com/track/PKG1_TRACKING",
"carrier": "FedEx",
"description": "First item shipped in package 1"
},
{
"id": "fulfill_evt_2",
"occurred_at": "2026-02-09T14:00:00Z",
"type": "shipped",
"line_items": [{ "id": "line_2", "quantity": 1 }],
"tracking_number": "PKG2_TRACKING",
"tracking_url": "https://fedex.com/track/PKG2_TRACKING",
"carrier": "FedEx",
"description": "Second item shipped in package 2"
}
]
},
"permalink_url": "https://merchant.example.com/orders/457"
}
דוגמאות לאירועי התאמה
בדוגמאות הבאות מוסבר איך לעדכן החזרים כספיים, החזרות וביטולים. רשימה של אירועים נתמכים וההגדרות שלהם מופיעה במאמר אירועי התאמה בסקירה הכללית של מחזור החיים של הזמנה.
ביטול הזמנה וקבלת החזר כספי
בדוגמה הזו אפשר לראות הזמנה שבוטלה וההחזר הכספי עליה בוצע זמן קצר אחרי שהיא בוצעה.
{
"ucp": {
"version": "2026-01-23",
"capabilities": {
"dev.ucp.shopping.order": [{"version": "2026-01-23"}]
}
},
"id": "order_02",
"checkout_id": "checkout_02",
"created_time": "2026-03-23T19:00:00Z",
"line_items": [
{
"id": "line_2",
"item": {
"id": "product_456",
"title": "Smart Watch",
"price": 29900
},
"quantity": { "total": 1, "fulfilled": 0 },
"totals": [
{"type": "subtotal", "amount": 29900},
{"type": "tax", "amount": 2400},
{"type": "total", "amount": 32300}
],
"status": "processing"
}
],
"totals": [
{"type": "subtotal", "amount": 29900},
{"type": "tax", "amount": 2400},
{"type": "total", "amount": 32300}
],
"adjustments": [
{
"id": "adj_cancel_1",
"type": "cancellation",
"description": "Customer changed mind",
"line_items": [{ "id": "line_2", "quantity": 1 }],
"occurred_at": "2026-02-09T11:00:00Z",
"status": "completed"
},
{
"id": "adj_refund_1",
"type": "refund",
"description": "Refund for cancelled item",
"line_items": [{ "id": "line_2", "quantity": 1 }],
"amount": 32300,
"occurred_at": "2026-02-09T11:05:00Z",
"status": "completed"
}
],
"permalink_url": "https://merchant.example.com/orders/12345"
}
החזרת הזמנה וקבלת החזר כספי
בדוגמה הזו מוצגת הזמנה שבה הפריט נשלח, סופק, ואז הוחזר וההחזר הכספי עליו אושר.
{
"ucp": {
"version": "2026-01-23",
"capabilities": {
"dev.ucp.shopping.order": [{"version": "2026-01-23"}]
}
},
"id": "order_03",
"checkout_id": "checkout_03",
"created_time": "2026-03-23T19:00:00Z",
"line_items": [
{
"id": "line_3",
"item": {
"id": "product_789",
"title": "Wireless Earbuds",
"price": 14900
},
"quantity": { "total": 1, "fulfilled": 1 },
"totals": [
{"type": "subtotal", "amount": 14900},
{"type": "tax", "amount": 1200},
{"type": "total", "amount": 16100}
],
"status": "fulfilled"
}
],
"totals": [
{"type": "subtotal", "amount": 14900},
{"type": "tax", "amount": 1200},
{"type": "total", "amount": 16100}
],
"fulfillment": {
"events": [
{
"id": "fulfill_evt_1",
"occurred_at": "2026-02-05T09:00:00Z",
"type": "shipped",
"line_items": [{ "id": "line_3", "quantity": 1 }],
"tracking_number": "987654321",
"tracking_url": "https://fedex.com/track/987654321",
"carrier": "FedEx",
"description": "Item shipped"
},
{
"id": "fulfill_evt_2",
"occurred_at": "2026-02-07T16:00:00Z",
"type": "delivered",
"line_items": [{ "id": "line_3", "quantity": 1 }],
"tracking_number": "987654321",
"tracking_url": "https://fedex.com/track/987654321",
"carrier": "FedEx",
"description": "Item delivered"
},
{
"id": "fulfill_evt_3",
"occurred_at": "2026-02-09T09:00:00Z",
"type": "returned",
"line_items": [{ "id": "line_3", "quantity": 1 }],
"tracking_number": "987654321",
"tracking_url": "https://fedex.com/track/987654321",
"carrier": "FedEx",
"description": "Item returned"
}
],
"expectations": [{ "...": "..." }]
},
"adjustments": [
{
"id": "adj_return_1",
"type": "return",
"description": "Item not compatible",
"line_items": [{ "id": "line_3", "quantity": 1 }],
"occurred_at": "2026-02-09T09:00:00Z",
"status": "completed"
},
{
"id": "adj_refund_2",
"type": "refund",
"description": "Refund for returned item",
"line_items": [{ "id": "line_3", "quantity": 1 }],
"amount": 16100,
"occurred_at": "2026-02-10T10:00:00Z",
"status": "completed"
}
],
"permalink_url": "https://merchant.example.com/orders/67890"
}