הטמעה של מחזור החיים של הזמנה

במדריך הזה מפורטים מאמרי העזרה של ה-API הטכניים וסכימות המטען הייעודי (payload) להעברת עדכונים מלאים של סטטוס ההזמנה, אירועי ביצוע הזמנה והתאמות אל Google באמצעות ווּבְּהוּקים (webhooks) לגרסה 2026-04-08 של Universal Commerce Protocol‏ (UCP).

לפני שיוצרים את נקודות הקצה, חשוב לעיין בסקירה הכללית של מחזור החיים של ההזמנה כדי להבין את המושגים ברמה גבוהה, האירועים שחובה להגדיר ופרטים על נקודות הקצה של ה-webhook.

אימות וחתימה על בקשות

השינויים העיקריים בגרסה 2026-04-08 כוללים הוספה של כותרות חובה חדשות של webhook ושל נהלים ספציפיים לחתימה על בקשות.

כותרות חובה של תגובה לפעולה מאתר אחר (webhook)

כותרות ה-HTTP הבאות הן חובה בכל הבקשות ל-webhook:

  • ‫Webhook-Id: מזהה ייחודי של אירוע ה-webhook הספציפי הזה. המזהה הזה צריך להיות זהה ל-id של האירוע הראשי שנשלח (לדוגמה, מזהה אירוע השלמת ההזמנה או מזהה אירוע ההתאמה).
  • ‫Webhook-Timestamp: חותמת הזמן שמציינת מתי התרחש האירוע.

הכותרות האלה מחליפות את השדות id ו-created_time שנדרשו בעבר ב-payload של ההזמנה.

בקשת חתימה

  1. מחשבים את תקציר הגיבוב (digest) מסוג SHA-256 של גוף הבקשה הגולמי ומגדירים את הכותרת Content-Digest.
  2. בוחרים מפתח חתימה מתוך signing_keys בפרופיל UCP.
  3. יוצרים בסיס לחתימה בהתאם ל-RFC 9421.
    • עיון במפרט של רכיבים חתומים
  4. הגדרת הכותרות UCP-Agent, Signature-Input ו-Signature.
    • ‫UCP-Agent הוא קישור לפרופיל ה-UCP שלכם בפורמט profile="https://merchant.example.com/.well-known/ucp".
    • ‫Signature-Input הוא שדה מובנה של מילון שמתאר את הרכיבים שכלולים בחתימה, וגם את keyid ששימש לחתימה, שחייב להיות זהה ל-kid של מפתח החתימה שבחרתם מתוך signing_keys בפרופיל UCP.
    • הכותרת Signature מכילה את בסיס החתימה שלכם, שחתום באמצעות המפתח הפרטי שלכם ומקודד ב-base64.

מידע נוסף מופיע בהוראות החתימה בכתובת ucp.dev.

אירוע יצירת הזמנה

  • טריגר: מיד אחרי אישור ההזמנה (status: processing).

השינויים העיקריים בגרסה הזו:

  • השדה currency הוא עכשיו שדה חובה ברמה העליונה של אובייקט ההזמנה.
  • השדה type בכל אובייקט במערך totals הוא עכשיו מחרוזת פתוחה (לדוגמה, subtotal,‏ tax,‏ fee,‏ total).
  • הכותרת Webhook-Id היא חובה ומכילה מזהה ייחודי של אירוע ה-webhook. שימו לב: עדיין נדרש השדה id במטען הייעודי (payload) שמכיל את מזהה אישור ההזמנה.
  • הכותרת Webhook-Timestamp היא חובה ומספקת את זמן היצירה, במקום השדה created_time הקודם במטען הייעודי (payload).

דוגמה: בדוגמה הזו מוצגת הזמנה שנוצרה אחרי שהקונה השלים את תהליך התשלום.

כותרות חובה:

  • Webhook-Id: order_01
  • Webhook-Timestamp: 2026-03-23T19:00:00Z
{
  "ucp": {
    "version": "2026-04-08",
    "capabilities": {
      "dev.ucp.shopping.order": [{"version": "2026-04-08"}]
    }
  },
  "id": "order_01",
  "checkout_id": "checkout_01",
  "currency": "USD",
   // Always include all line items, even for single-item checkouts. This ensures any add-ons, gifts, or separate charges are accounted for.
  "line_items": [
    {
      "id": "line_1",
      "item":
        {
          "id": "product_123",
          "title": "Running Shoes",
          "price": 10000
        },
      "quantity": { "total": 1, "fulfilled": 0 },
      "totals": [
        {"type": "subtotal", "display_text": null, "amount": 10000},
        {"type": "total", "display_text": null, "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", "display_text": "Subtotal", "amount": 10000}, // Tax-inclusive markets: Set display_text to "Subtotal (including taxes)". Amount must include tax.
    {"type": "fee", "display_text": "Service Fee", "amount": 100},
    {"type": "tax", "display_text": "Tax", "amount": 800}, // Tax-inclusive markets: Omit this entry.
    {"type": "total", "display_text": "Total", "amount": 10900}
  ],
  "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",  // Maximum length: 200 characters.
        "fulfillable_on": "now"
      }
    ]
  },
  "permalink_url": "https://merchant.example.com/orders/789"
}

אירועים שקשורים להכנה להפצה

האירועים האלה נשלחים כחלק מהמערך fulfillment.events.

ההזמנה נשלחה

כשהפריטים בהזמנה נשלחו. השדות tracking_number ו-tracking_url הם שדות חובה לאירועים מסוג 'נשלח', כי הם נדרשים כדי לקבץ פריטים בדף 'ההזמנות שלי' בצורה מדויקת.

ההזמנה נמסרה

כשהפריטים בהזמנה נמסרו.

דוגמה (shipped ו-delivered): בדוגמה הזו מוצג עדכון הזמנה אחרי שהפריט נשלח ואז נמסר.

כותרות חובה:

  • Webhook-Id: fulfill_evt_2
  • Webhook-Timestamp: 2026-02-10T14:00:00Z
{
  "ucp": {
    "version": "2026-04-08",
    "capabilities": {
      "dev.ucp.shopping.order": [{"version": "2026-04-08"}]
    }
  },
  "id": "order_01",
  "checkout_id": "checkout_01",
  "currency": "USD",
  "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 אחד עם אותו מספר מעקב.

כותרות חובה:

  • Webhook-Id: fulfill_evt_1
  • Webhook-Timestamp: 2026-02-08T10:30:00Z
{
  "ucp": {
    "version": "2026-04-08",
    "capabilities": {
      "dev.ucp.shopping.order": [{"version": "2026-04-08"}]
    }
  },
  "id": "order_multi_01",
  "checkout_id": "checkout_multi_01",
  "currency": "USD",
  "line_items": [
    {
      "id": "line_1",
      "item": { "id": "product_1", "title": "Item 1", "price": 5000 },
      "quantity": { "total": 1, "fulfilled": 1 },
      "totals": [
        {"type": "subtotal", "display_text": null, "amount": 5000},
        {"type": "total", "display_text": null, "amount": 5000}
      ],
      "status": "fulfilled"
    },
    {
      "id": "line_2",
      "item": { "id": "product_2", "title": "Item 2", "price": 5000 },
      "quantity": { "total": 1, "fulfilled": 1 },
      "totals": [
        {"type": "subtotal", "display_text": null, "amount": 5000},
        {"type": "total", "display_text": null, "amount": 5000}
      ],
      "status": "fulfilled"
    }
  ],
  "totals": [
    {"type": "subtotal", "display_text": "Subtotal", "amount": 10000},
    {"type": "fee", "display_text": "Shipping", "amount": 500},
    {"type": "total", "display_text": "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 מחולקים.

כותרות חובה:

  • Webhook-Id: fulfill_evt_2
  • Webhook-Timestamp: 2026-02-09T14:00:00Z
{
  "ucp": {
    "version": "2026-04-08",
    "capabilities": {
      "dev.ucp.shopping.order": [{"version": "2026-04-08"}]
    }
  },
  "id": "order_multi_02",
  "checkout_id": "checkout_multi_02",
  "currency": "USD",
  "line_items": [
    {
      "id": "line_1",
      "item": { "id": "product_1", "title": "Item 1", "price": 5000 },
      "quantity": { "total": 1, "fulfilled": 1 },
      "totals": [
        {"type": "subtotal", "display_text": null, "amount": 5000},
        {"type": "total", "display_text": null, "amount": 5000}
      ],
      "status": "fulfilled"
    },
    {
      "id": "line_2",
      "item": { "id": "product_2", "title": "Item 2", "price": 5000 },
      "quantity": { "total": 1, "fulfilled": 1 },
      "totals": [
        {"type": "subtotal", "display_text": null, "amount": 5000},
        {"type": "total", "display_text": null, "amount": 5000}
      ],
      "status": "fulfilled"
    }
  ],
  "totals": [
    {"type": "subtotal", "display_text": "Subtotal", "amount": 10000},
    {"type": "fee", "display_text": "Shipping", "amount": 1500},
    {"type": "total", "display_text": "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"
}

דוגמאות לאירועי התאמה

בדוגמאות הבאות מוסבר איך לעדכן החזרים כספיים, החזרות וביטולים. רשימה של אירועים נתמכים וההגדרות שלהם מופיעה במאמר אירועי התאמה בסקירה הכללית של מחזור החיים של הזמנה.

ביטול הזמנה וקבלת החזר כספי

בדוגמה הזו אפשר לראות הזמנה שבוטלה וההחזר הכספי עליה בוצע זמן קצר אחרי שהיא בוצעה.

השינויים העיקריים בגרסה הזו בדוגמה הזו:

  • פריטים מושפעים מ-cancellation ועכשיו משתמשים ב-"status": "removed" במערך line_items הראשי.
  • כאשר line_items.status הוא removed:
    • הערך של line_items.quantity.total הוא 0.
    • הכמות המקורית מאוחסנת בשדה החדש line_items.quantity.original.

כותרות חובה:

  • Webhook-Id: adj_refund_1
  • Webhook-Timestamp: 2026-02-09T11:05:00Z
{
  "ucp": {
    "version": "2026-04-08",
    "capabilities": {
      "dev.ucp.shopping.order": [{"version": "2026-04-08"}]
    }
  },
  "id": "order_02",
  "checkout_id": "checkout_02",
  "currency": "USD",
  "line_items": [
    {
      "id": "line_2",
      "item": {
        "id": "product_456",
        "title": "Smart Watch",
        "price": 29900
      },
      "quantity": {
        "total": 0,  // Item removed from order total.
        "original": 1,  // Original quantity before removal.
        "fulfilled": 0 //  Item was not fulfilled before cancellation.
      },
      "totals": [
        {"type": "subtotal", "amount": 29900},
        {"type": "tax", "amount": 2400},
        {"type": "total", "amount": 32300}
      ],
      "status": "removed" // Item is cancelled, returned, or refunded.
    }
  ],
  "totals": [
    {"type": "subtotal", "amount": 29900},
    {"type": "tax", "amount": 2400},
    {"type": "total", "amount": 32300}
  ],
    // Fulfillment expectations should still be present even if cancelled early.
  "fulfillment": {
    "expectations": [
      {
        "id": "exp_1",
        "line_items": [{ "id": "line_2", "quantity": 1 }],
        "method_type": "shipping",
        "destination": {
          "first_name": "Bob",
          "last_name": "Consumer",
          "street_address": "456 Oak Ave",
          "address_locality": "Anytown",
          "address_region": "CA",
          "address_country": "US",
          "postal_code": "90210"
        },
        "description": "Standard Shipping",
        "fulfillable_on": "now"
      }
    ]
    // "events": [] // No fulfillment events occurred before cancellation.
    },
  "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 }],
      "totals": [
        {"type": "subtotal", "display_text": "Subtotal", "amount": -29900}, // Negative amounts indicate money returned to the buyer. Tax-inclusive markets: Set display_text to "Subtotal (including taxes)". Amount must include tax.
        {"type": "tax", "amount": -2400}, // Tax-inclusive markets: Omit this entry.
        {"type": "total", "display_text": "Total", "amount": -32300}
      ],
      "occurred_at": "2026-02-09T11:05:00Z",
      "status": "completed"
    }
  ],
  "permalink_url": "https://merchant.example.com/orders/12345"
}

החזרת הזמנה וקבלת החזר כספי

בדוגמה הזו מוצגת הזמנה שבה הפריט נשלח, סופק, ואז הוחזר וההחזר הכספי עליו אושר.

השינויים העיקריים בגרסה הזו בדוגמה הזו:

  • פריטים שהושפעו מ-return משתמשים עכשיו ב-"status": "removed" במערך הראשי line_items.
  • כאשר line_items.status הוא removed:
    • הערך של line_items.quantity.total הוא 0.
    • הכמות המקורית מאוחסנת בשדה החדש line_items.quantity.original.
  • ב-adjustments מסוג return, בשדה line_items.quantity בתוך ההתאמה נעשה שימוש בערך שלילי (לדוגמה, -1) כדי לציין פריטים שמוחזרים.

כותרות חובה:

  • Webhook-Id: adj_refund_2
  • Webhook-Timestamp: 2026-02-10T10:00:00Z
{
  "ucp": {
    "version": "2026-04-08",
    "capabilities": {
      "dev.ucp.shopping.order": [{"version": "2026-04-08"}]
    }
  },
  "id": "order_03",
  "checkout_id": "checkout_03",
  "currency": "USD",
  "line_items": [
    {
      "id": "line_3",
      "item": {
        "id": "product_789",
        "title": "Wireless Earbuds",
        "price": 14900
      },
      "quantity": {
        "total": 0,  // Item removed from order total.
        "original": 1,  // Original quantity before removal.
        "fulfilled": 1 // Was fulfilled before return.
      },
      "totals": [
        {"type": "subtotal", "amount": 14900},
        {"type": "tax", "amount": 1200},
        {"type": "total", "amount": 16100}
      ],
      "status": "removed" // Item is cancelled, returned, or refunded.
    }
  ],
  "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", // a matching fulfillment event is also added to represent return shipping.
      "description": "Item not compatible",
      "line_items": [{ "id": "line_3", "quantity": -1 }],  // Uses a negative value (such as -1) to indicate a return.
      "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 }],
      "totals": [
        {"type": "subtotal", "amount": -14900}, // Negative amounts indicate money returned to the buyer.
        {"type": "tax", "amount": -1200},
        {"type": "total", "amount": -16100}
      ],
      "occurred_at": "2026-02-10T10:00:00Z",
      "status": "completed"
    }
  ],
  "permalink_url": "https://merchant.example.com/orders/67890"
}
הקודם
Native checkout API
הבא
סימנים לרמת הסיכון