ניהול אותות למעקב אחר הזמנות

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

אתם יכולים לשלוח נתונים על הזמנות שהושלמו דרך האתר של המוכר. הנתונים שאתם שולחים משלימים את פרטי הגדרת המשלוח שאתם מספקים כחלק מהגדרת החשבון ב-Merchant Center. לדוגמה, אם אתם מספקים לקונים הערכות משלוח של 3-7 ימים, אבל המעקב ההיסטורי האחרון אחרי ההזמנות מצביע על כך שההזמנות שלכם מגיעות בדרך כלל תוך 3 ימים באזורים מסוימים, Google יכולה לעדכן את כרטיסי המוצר שלכם כדי לספק ללקוחות הערכה מדויקת יותר.

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

דרישות מוקדמות

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

מידע נוסף על קישור שותף לחשבון Merchant Center

שימוש במשאב ordertrackingsignals

המשאב ordertrackingsignals כולל נקודת קצה (endpoint) אחת של create, שמאפשרת לשלוח את נתוני המעקב ההיסטוריים של ההזמנות.

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

  • פרטי ההזמנה (מועד יצירת ההזמנה, המיקוד ביעד המסירה וקוד האזור), shippingInfo ומספר המעקב: מאפשרים לחשב את זמני הטיפול וזמן האספקה בפועל.

  • merchant_id ו-lineItems : משמשים להתאמת ההזמנה למוצרים שיש לכם בחשבון Merchant Center.

  • ‫customerShippingFee: עלות המשלוח שהקונה משלם.

שליחת נתונים חדשים של אותות למעקב אחר הזמנות

הנה דוגמה לבקשה לשליחת אות מעקב אחר הזמנה של הקמעונאי '123456789' עם סך של 8 פריטים.

https://merchantapi.googleapis.com/products/ordertracking/v1/accounts/{ACCOUNT_ID}/ordertrackingsignals

{
    "merchantId": {ACCOUNT_ID},
    "orderCreatedTime": {
        "year": 2025,
        "month": 1,
        "day": 2,
        "hours": 0,
        "minutes": 0,
        "seconds": 0,
        "timeZone": {
             "id": "America/Los_Angeles"
        }
    },
    "orderId": "123456789",
    "shippingInfo": [
         {
            "shipmentId": "1",
            "trackingId": "100",
            "carrier": "FEDEX",
            "carrierService": "GROUND",
            "shippedTime": {
                "year": 2025,
                "month": 1,
                "day": 3,
                "hours": 0,
                "minutes": 0,
                "seconds": 0,
                "timeZone": {
                     "id": "America/Los_Angeles"
                }
            },
            "shippingStatus": "DELIVERED"
        },
         {
            "shipmentId": "2",
            "earliestDeliveryPromiseTime": {
                "year": 2025,
                "month": 1,
                "day": 4,
                "hours": 0,
                "minutes": 0,
                "seconds": 0,
                "timeZone": {
                     "id": "America/Los_Angeles"
                }
            },
            "latestDeliveryPromiseTime": {
                "year": 2025,
                "month": 1,
                "day": 5,
                "hours": 0,
                "minutes": 0,
                "seconds": 0,
                "timeZone": {
                     "id": "America/Los_Angeles"
                }
            },
            "actualDeliveryTime": {
                "year": 2025,
                "month": 1,
                "day": 5,
                "hours": 0,
                "minutes": 0,
                "seconds": 0,
                "timeZone": {
                     "id": "America/Los_Angeles"
                }
            },
            "shippedTime": {
                "year": 2025,
                "month": 1,
                "day": 3,
                "hours": 0,
                "minutes": 0,
                "seconds": 0,
                "timeZone": {
                     "id": "America/Los_Angeles"
                }
            },
            "shippingStatus": "DELIVERED"
        }

    ],
    "lineItems": [
         {
            "lineItemId": "item1",
            "productId": "en~US~trouser",
            "quantity": "3"
        },
         {
            "lineItemId": "item2",
            "productId": "en~US~sneaker",
            "quantity": "5"
        }

    ],
    "shipmentLineItemMapping": [
         {
            "shipmentId": "1",
            "lineItemId": "item1",
            "quantity": "1"
        },
         {
            "shipmentId": "2",
            "lineItemId": "item1",
            "quantity": "2"
        },
         {
            "shipmentId": "1",
            "lineItemId": "item2",
            "quantity": "4"
        },
         {
            "shipmentId": "2",
            "lineItemId": "item2",
            "quantity": "1"
        }

    ],
    "customerShippingFee": {
        "amount_micros": 4500000,
        "currency_code": "USD"
    },
    "deliveryPostalCode": "94043",
    "deliveryRegionCode": "US"
}

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

{
  "orderCreatedTime": {
    "year": 2025,
    "month": 1,
    "day": 2,
    "timeZone": {
      "id": "America/Los_Angeles"
    }
  },
  "orderId": "15e2b0d3c33891ebb0f1ef609ec419420c20e320ce94c65fbc8c3312448eb225",
  "shippingInfo": [
    {
      "shipmentId": "6b86b273ff34fce19d6b804eff5a3f5747ada4eaa22f1d49c01e52ddb7875b4b",
      "trackingId": "100",
      "carrier": "FEDEX",
      "carrierService": "GROUND",
      "shippedTime": {
        "year": 2025,
        "month": 1,
        "day": 3,
        "timeZone": {
          "id": "America/Los_Angeles"
        }
      },
      "shippingStatus": "DELIVERED"
    },
    {
      "shipmentId": "d4735e3a265e16eee03f59718b9b5d03019c07d8b6c51f90da3a666eec13ab35",
      "shippedTime": {
        "year": 2025,
        "month": 1,
        "day": 3,
        "timeZone": {
          "id": "America/Los_Angeles"
        }
      },
      "earliestDeliveryPromiseTime": {
        "year": 2025,
        "month": 1,
        "day": 4,
        "timeZone": {
          "id": "America/Los_Angeles"
        }
      },
      "latestDeliveryPromiseTime": {
        "year": 2025,
        "month": 1,
        "day": 5,
        "timeZone": {
          "id": "America/Los_Angeles"
        }
      },
      "actualDeliveryTime": {
        "year": 2025,
        "month": 1,
        "day": 5,
        "timeZone": {
          "id": "America/Los_Angeles"
        }
      },
      "shippingStatus": "DELIVERED"
    }
  ],
  "lineItems": [
    {
      "lineItemId": "item1",
      "productId": "en~US~8465944842",
      "quantity": "3"
    },
    {
      "lineItemId": "item2",
      "productId": "en~US~8465944842",
      "quantity": "5"
    }
  ],
  "shipmentLineItemMapping": [
    {
      "shipmentId": "6b86b273ff34fce19d6b804eff5a3f5747ada4eaa22f1d49c01e52ddb7875b4b",
      "lineItemId": "item1",
      "quantity": "1"
    },
    {
      "shipmentId": "d4735e3a265e16eee03f59718b9b5d03019c07d8b6c51f90da3a666eec13ab35",
      "lineItemId": "item1",
      "quantity": "2"
    },
    {
      "shipmentId": "6b86b273ff34fce19d6b804eff5a3f5747ada4eaa22f1d49c01e52ddb7875b4b",
      "lineItemId": "item2",
      "quantity": "4"
    },
    {
      "shipmentId": "d4735e3a265e16eee03f59718b9b5d03019c07d8b6c51f90da3a666eec13ab35",
      "lineItemId": "item2",
      "quantity": "1"
    }
  ],
  "customerShippingFee": {
    "amountMicros": "4500000",
    "currencyCode": "USD"
  },
  "deliveryPostalCode": "94043",
  "deliveryRegionCode": "US",
  "orderTrackingSignalId": "2424724582881888160",
  "merchantId": "1234"
}

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

Java

import com.google.api.gax.core.FixedCredentialsProvider;
import com.google.auth.oauth2.GoogleCredentials;
import com.google.shopping.merchant.ordertracking.v1.CreateOrderTrackingSignalRequest;
import com.google.shopping.merchant.ordertracking.v1.OrderTrackingSignal;
import com.google.shopping.merchant.ordertracking.v1.OrderTrackingSignal.LineItemDetails;
import com.google.shopping.merchant.ordertracking.v1.OrderTrackingSignal.ShipmentLineItemMapping;
import com.google.shopping.merchant.ordertracking.v1.OrderTrackingSignal.ShippingInfo;
import com.google.shopping.merchant.ordertracking.v1.OrderTrackingSignal.ShippingInfo.ShippingState;
import com.google.shopping.merchant.ordertracking.v1.OrderTrackingSignalsServiceClient;
import com.google.shopping.merchant.ordertracking.v1.OrderTrackingSignalsServiceSettings;
import com.google.shopping.type.Price;
import com.google.type.DateTime;
import com.google.type.TimeZone;
import java.util.Arrays;
import java.util.List;
import shopping.merchant.samples.utils.Authenticator;
import shopping.merchant.samples.utils.Config;

/** This class demonstrates how to create an order tracking signal. */
public class CreateOrderTrackingSignalSample {
  private static String getParent(String accountId) {
    return String.format("accounts/%s", accountId);
  }

  private static void createOrderTrackingSignal(Config config, List<String> productIds)
      throws Exception {
    GoogleCredentials credentials = new Authenticator().authenticate();
    OrderTrackingSignalsServiceSettings orderTrackingSignalsServiceSettings =
        OrderTrackingSignalsServiceSettings.newBuilder()
            .setCredentialsProvider(FixedCredentialsProvider.create(credentials))
            .build();

    String parent = getParent(config.getAccountId().toString());

    String firstProductId = productIds.get(0);
    String secondProductId = productIds.get(1);

    DateTime orderCreatedTime =
        DateTime.newBuilder()
            .setYear(2025)
            .setMonth(3)
            .setDay(24)
            .setHours(12)
            .setMinutes(2)
            .setSeconds(22)
            .setTimeZone(TimeZone.newBuilder().setId("America/Los_Angeles"))
            .build();
    DateTime shippedTime1 =
        DateTime.newBuilder()
            .setYear(2025)
            .setMonth(3)
            .setDay(25)
            .setHours(16)
            .setMinutes(22)
            .setTimeZone(TimeZone.newBuilder().setId("America/Los_Angeles"))
            .build();
    DateTime shippedTime2 =
        DateTime.newBuilder()
            .setYear(2025)
            .setMonth(3)
            .setDay(26)
            .setHours(16)
            .setMinutes(22)
            .setTimeZone(TimeZone.newBuilder().setId("America/Los_Angeles"))
            .build();
    DateTime earliestDeliveryPromiseTime =
        DateTime.newBuilder()
            .setYear(2025)
            .setMonth(3)
            .setDay(27)
            .setTimeZone(TimeZone.newBuilder().setId("America/Los_Angeles"))
            .build();
    DateTime latestDeliveryPromiseTime =
        DateTime.newBuilder()
            .setYear(2025)
            .setMonth(3)
            .setDay(30)
            .setTimeZone(TimeZone.newBuilder().setId("America/Los_Angeles"))
            .build();
    DateTime actualDeliveryTime =
        DateTime.newBuilder()
            .setYear(2025)
            .setMonth(3)
            .setDay(29)
            .setHours(16)
            .setMinutes(22)
            .setTimeZone(TimeZone.newBuilder().setId("America/Los_Angeles"))
            .build();

    ShippingInfo shippingInfo1 =
        ShippingInfo.newBuilder()
            .setShipmentId("shipment_id1")
            .setCarrier("UPS")
            .setCarrierService("Ground")
            .setTrackingId("1Z23456789")
            .setShippedTime(shippedTime1)
            .setEarliestDeliveryPromiseTime(earliestDeliveryPromiseTime)
            .setLatestDeliveryPromiseTime(latestDeliveryPromiseTime)
            .setActualDeliveryTime(actualDeliveryTime)
            .setShippingStatus(ShippingState.DELIVERED)
            .setOriginPostalCode("94043")
            .setOriginRegionCode("US")
            .build();
    ShippingInfo shippingInfo2 =
        ShippingInfo.newBuilder()
            .setShipmentId("shipment_id2")
            .setCarrier("USPS")
            .setCarrierService("Ground Advantage")
            .setTrackingId("987654321")
            .setShippedTime(shippedTime2)
            .setShippingStatus(ShippingState.SHIPPED)
            .setOriginPostalCode("94043")
            .setOriginRegionCode("US")
            .build();

    try (OrderTrackingSignalsServiceClient orderTrackingSignalsServiceClient =
        OrderTrackingSignalsServiceClient.create(orderTrackingSignalsServiceSettings)) {
      CreateOrderTrackingSignalRequest request =
          CreateOrderTrackingSignalRequest.newBuilder()
              .setParent(parent)
              .setOrderTrackingSignal(
                  OrderTrackingSignal.newBuilder()
                      // Unique order ID across all merchants orders.
                      .setOrderId("unique_order_id443455")
                      // If sending signal on behalf of another merchant use setMerchantId to
                      // indicate the merchant.
                      // .setMerchantId(123L)
                      .setOrderCreatedTime(orderCreatedTime)
                      .addShippingInfo(shippingInfo1)
                      .addShippingInfo(shippingInfo2)
                      // Details of the line items in the order including quantity and fields
                      // identifying the product.
                      .addLineItems(
                          LineItemDetails.newBuilder()
                              .setQuantity(2)
                              .setProductId(firstProductId)
                              .setLineItemId("item1"))
                      .addLineItems(
                          LineItemDetails.newBuilder()
                              .setQuantity(1)
                              .setProductId(secondProductId)
                              .setLineItemId("item2")
                              // Optional fields used to identify the product when product ID is not
                              // sufficient.
                              .setMpn("00638HAY")
                              .setProductTitle("Tshirt-small-blue")
                              .setBrand("Brand1")
                              // Any GTIN associated with the product.
                              .addGtins("001234567890"))
                      // Mapping of line items to shipments.
                      .addShipmentLineItemMapping(
                          ShipmentLineItemMapping.newBuilder()
                              .setShipmentId("shipment_id1")
                              .setLineItemId("item2")
                              .setQuantity(1))
                      .addShipmentLineItemMapping(
                          ShipmentLineItemMapping.newBuilder()
                              .setShipmentId("shipment_id2")
                              .setLineItemId("item1")
                              .setQuantity(1))
                      .addShipmentLineItemMapping(
                          ShipmentLineItemMapping.newBuilder()
                              .setShipmentId("shipment_id1")
                              .setLineItemId("item1")
                              .setQuantity(1))
                      // The price represented as a number in micros (1 million micros is an
                      // equivalent to one's currency standard unit, for example, 1 USD = 1000000
                      // micros).
                      .setCustomerShippingFee(
                          Price.newBuilder()
                              // Equivalent to 5 USD.
                              .setAmountMicros(5000000)
                              .setCurrencyCode("USD"))
                      .setDeliveryPostalCode("10011"))
              .build();
      System.out.println("Sending Create OrderTrackingSignal request.");
      OrderTrackingSignal response =
          orderTrackingSignalsServiceClient.createOrderTrackingSignal(request);
      System.out.println("Created OrderTrackingSignal below.");
      System.out.println(response);

    } catch (Exception e) {
      System.out.println(e);
    }
  }

  public static void main(String[] args) throws Exception {
    Config config = Config.load();
    // All products in the order. Replace with actual products in the order. Be sure to include all
    // products in the order.
    String productId1 = "en~us~sku123";
    String productId2 = "en~us~skuabc";
    List<String> productIds = Arrays.asList(productId1, productId2);
    createOrderTrackingSignal(config, productIds);
  }
}

שליחת נתונים חדשים של אותות למעקב אחר הזמנות בשם קמעונאי

כדי לשלוח נתונים חדשים של אותות למעקב אחר הזמנות בשם קמעונאי, פועלים לפי השלבים הבאים:

  1. כדי לשלוח נתונים בשם עסק אחר, צריך לוודא שהחשבון שלכם מופעל. כדי לבקש גישה, פנו אלינו בכתובת OrderTrackingSignals@google.com.
  2. מגדירים את השדה merchant_id ושולחים נתונים בשם העסק.

עדכון נתונים קיימים של אותות מעקב אחר הזמנות

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