Google, içerikleri tercih ettiğiniz dile çevirmek için yapay zeka teknolojisini kullanır. Yapay zeka çevirilerinde hata olabilir.

Sipariş yaşam döngüsü uygulama

Bu kılavuzda, Evrensel Ticaret Protokolü (UCP) 2026-04-08 sürümü için webhook'ları kullanarak tam sipariş durumu güncellemelerini, karşılama etkinliklerini ve düzenlemeleri Google'a aktarmaya yönelik teknik API referansı ve yük şemaları sağlanmaktadır.

Uç noktalarınızı oluşturmadan önce üst düzey kavramlar, zorunlu etkinlikler ve webhook uç noktası ayrıntıları için Sipariş yaşam döngüsüne genel bakış başlıklı makaleyi incelediğinizden emin olun.

Kimlik doğrulama ve istek imzalama

2026-04-08 sürümündeki önemli değişiklikler arasında yeni zorunlu webhook üstbilgilerinin ve belirli istek imzalama prosedürlerinin kullanıma sunulması yer alıyor.

Zorunlu webhook üstbilgileri

Tüm webhook istekleri için aşağıdaki HTTP üstbilgileri zorunludur:

Webhook-Id: Bu belirli webhook etkinliğinin benzersiz tanımlayıcısı. Bu kimlik, gönderilen birincil etkinliğin id ile eşleşmelidir (örneğin, karşılama etkinliği kimliği veya düzenleme etkinliği kimliği).
Webhook-Timestamp: Etkinliğin gerçekleştiği zamanı gösteren zaman damgası.

Bu başlıklar, daha önce sipariş yükünde beklenen id ve created_time alanlarının yerini alır.

İmza iste

Ham istek gövdesinin SHA-256 özetini hesaplayın ve Content-Digest üst bilgisini ayarlayın.
UCP profilinizdeki signing_keys bölümünden bir imzalama anahtarı seçin.
RFC 9421 uyarınca imza tabanı oluşturun.
- İmzalı bileşenlerin teknik özelliklerine bakın
UCP-Agent, Signature-Input ve Signature başlıklarını ayarlayın.
- UCP-Agent, profile="https://merchant.example.com/.well-known/ucp" biçiminde UCP profilinizin bağlantısıdır.
- Signature-Input, imzada bulunan bileşenlerin yanı sıra imzalamak için kullanılan keyid'yi açıklayan sözlük yapılı bir alandır. Bu alan, UCP profilinizdeki signing_keys'den seçtiğiniz imzalama anahtarının kid ile eşleşmelidir.
- Signature başlığı, özel anahtarınız kullanılarak imzalanan ve ardından base64 kodlu hale getirilen imza tabanınızı içerir.

Daha fazla bilgi için ucp.dev adresindeki imzalama talimatlarına bakın.

Sipariş oluşturuldu etkinliği

Tetikleyici: Sipariş onaylandıktan hemen sonra (status: processing).

Bu sürümdeki önemli değişiklikler:

currency alanı artık Order nesnesinin en üst düzeyinde zorunludur.
totals dizisindeki her nesnenin type alanı artık açık bir dizedir (örneğin, "ara toplam", "vergi", "ücret", "toplam").
Zorunlu Webhook-Id başlığı, webhook etkinliğinin benzersiz tanımlayıcısını içerir. Sipariş onay kimliğini içeren yükteki id alanının hâlâ gerekli olduğunu unutmayın.
Zorunlu Webhook-Timestamp üstbilgisi, oluşturma zamanını sağlar ve yükteki eski created_time alanının yerini alır.

Örnek: Bu örnekte, alıcı ödeme işlemini tamamladıktan sonra oluşturulan bir sipariş gösterilmektedir.

Zorunlu Başlıklar:

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"
}

Tamamlama etkinlikleri

Bu etkinlikler, fulfillment.events dizisinin bir parçası olarak gönderilir.

Sipariş gönderildi

Siparişin içindeki öğeler gönderildiğinde. Gönderilen etkinlikler için tracking_number ve tracking_url alanları zorunludur. Bu alanlar, "Siparişlerim" sayfasındaki öğelerin doğru şekilde gruplandırılması için gereklidir.

Sipariş teslim edildi

Siparişin içindeki öğeler teslim edildiğinde

Örnek (shipped ve delivered): Bu örnekte, öğe gönderildikten ve teslim edildikten sonraki sipariş güncellemesi gösterilmektedir.

Zorunlu Başlıklar:

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"
}

Birden fazla öğe içeren sipariş örnekleri

Aşağıdaki örneklerde, birden fazla öğe içeren siparişler ve bölünmüş gönderiler için güncellemelerin nasıl yapılandırılacağı gösterilmektedir. Paket durumlarının nasıl belirlendiğiyle ilgili kurallar için Paket durumu nasıl belirlenir? başlıklı makaleyi inceleyin.

Çok öğeli sipariş, aynı pakette teslimat

Bu örnekte, birden fazla öğe içeren tek bir paket için sipariş güncellemesi gösterilmektedir. Tüm satır öğeleri, aynı takip numarasına sahip tek bir shipped etkinliğinde gruplandırılır.

Zorunlu Başlıklar:

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"
}

Birden fazla öğe içeren sipariş, bölünmüş gönderim

Bu örnekte, ayrı gönderimler için bir sipariş güncellemesi gösterilmektedir. Her biri ilgili paketteki belirli line_items öğesine referans veren ve farklı takip numaralarına sahip birden fazla shipped etkinliği vardır. Her paket farklı bir sipariş karşılama taahhüdünü (ör. çoklu grup ödemesinden kaynaklanan farklı hızlar ve maliyetler) temsil ettiğinden expectations de bölünür.

Zorunlu Başlıklar:

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"
}

Düzenleme etkinliği örnekleri

Aşağıdaki örneklerde, geri ödemeler, iadeler ve iptaller için güncellemelerin nasıl yapılandırılacağı gösterilmektedir. Desteklenen etkinliklerin ve tanımlarının listesi için Sipariş yaşam döngüsüne genel bakış bölümündeki Düzeltme etkinlikleri başlıklı makaleyi inceleyin.

Sipariş iptali ve geri ödeme

Bu örnekte, sipariş verildikten kısa süre sonra öğenin iptal edildiği ve geri ödeme yapıldığı bir sipariş gösterilmektedir.

Bu örnekteki sürümde yapılan önemli değişiklikler:

cancellation öğesinden etkilenen satır öğeleri artık ana line_items dizisinde "status": "removed" kullanıyor.
line_items.status removed olduğunda:
- line_items.quantity.total, 0 olarak ayarlanmıştır.
- Orijinal miktar, yeni line_items.quantity.original alanında depolanır.

Zorunlu Başlıklar:

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"
}

Sipariş iadesi ve geri ödemesi

Bu örnekte, öğenin gönderildiği, teslim edildiği, ardından iade edildiği ve geri ödeme yapıldığı bir sipariş gösterilmektedir.

Bu örnekteki sürümde yapılan önemli değişiklikler:

return etkilenen satır öğeleri artık ana line_items dizisinde "status": "removed" kullanıyor.
line_items.status removed olduğunda:
- line_items.quantity.total, 0 olarak ayarlanmıştır.
- Orijinal miktar, yeni line_items.quantity.original alanında depolanır.
adjustments türünde return, ayarlamadaki line_items.quantity alanı, geri alınan öğeleri belirtmek için negatif bir değer (ör. -1) kullanır.

Zorunlu Başlıklar:

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"
}

Yerel ödeme API'si

Risk sinyalleri

Sipariş yaşam döngüsü uygulama Koleksiyonlar ile düzeninizi koruyun İçeriği tercihlerinize göre kaydedin ve kategorilere ayırın.

Kimlik doğrulama ve istek imzalama

Zorunlu webhook üstbilgileri

İmza iste

Sipariş oluşturuldu etkinliği

Tamamlama etkinlikleri

Sipariş gönderildi

Sipariş teslim edildi

Birden fazla öğe içeren sipariş örnekleri

Çok öğeli sipariş, aynı pakette teslimat

Birden fazla öğe içeren sipariş, bölünmüş gönderim

Düzenleme etkinliği örnekleri

Sipariş iptali ve geri ödeme

Sipariş iadesi ve geri ödemesi

Sipariş yaşam döngüsü uygulama