سیگنال های ردیابی سفارش را مدیریت کنید

سیگنال‌های ردیابی سفارش به شما این امکان را می‌دهند که داده‌های ردیابی سفارش تاریخی خود را برای سفارش‌هایی که از طریق سایت تاجر انجام شده‌اند، در اختیار Google قرار دهید. این به خریداران تخمین های حمل و نقل دقیق تر و دقیق تری ارائه می دهد. سیگنال‌های ردیابی سفارش همچنین به شما امکان می‌دهند فهرست‌های خود را با حاشیه‌نویسی حمل و نقل رایگان و سریع ارتقا دهید.

می‌توانید داده‌های سفارش‌های تکمیل‌شده را از طریق سایت تاجر ارسال کنید. داده‌هایی که ارسال می‌کنید، اطلاعات پیکربندی حمل‌ونقل را که به‌عنوان بخشی از راه‌اندازی حساب Merchant Center ارائه می‌دهید، تحسین می‌کند. برای مثال، اگر تخمین‌های حمل‌ونقل 3 تا 7 روزه را به خریداران ارائه کنید، اما ردیابی سفارش‌های تاریخی اخیر شما نشان می‌دهد که سفارش‌های شما معمولاً ظرف 3 روز در برخی مناطق می‌رسند، Google می‌تواند فهرست‌های شما را به‌روزرسانی کند تا برآورد دقیق‌تری به مشتریان ارائه دهد.

این راهنما نحوه استفاده از منبع ordertrackingsignals را برای ارسال اطلاعات ردیابی سفارش تاریخی خود توضیح می دهد.

پیش نیازها

حساب شما باید از قبل تأیید شده باشد تا سیگنال‌های ردیابی سفارش را برای حساب دیگری ارسال کند، برای این کار باید حساب دیگر صاحب حساب را پیوند دهد.

برای اطلاعات بیشتر، به پیوند شریک با حساب Merchant Center خود مراجعه کنید.

از منبع ordertrackingsignals استفاده کنید

منبع ordertrackingsignals شامل یک نقطه پایان 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"
}

نمونه کد زیر نحوه ارسال اطلاعات سیگنال های ردیابی سفارش را نشان می دهد:

جاوا

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 = "online~en~us~sku123";
    String productId2 = "online~en~us~skuabc";
    List<String> productIds = Arrays.asList(productId1, productId2);
    createOrderTrackingSignal(config, productIds);
  }
}

داده‌های سیگنال‌های ردیابی سفارش جدید را از طرف یک خرده‌فروش ارسال کنید

برای ارسال اطلاعات سیگنال های ردیابی سفارش جدید از طرف یک خرده فروش، مراحل داده شده را دنبال کنید:

  1. قبل از اینکه بتوانید داده‌ها را از طرف یک کسب‌وکار دیگر ارسال کنید، مطمئن شوید که فعال هستید. برای درخواست دسترسی، با ما در OrderTrackingSignals@google.com تماس بگیرید.
  2. فیلد merchant_id را راه‌اندازی کنید و داده‌ها را از طرف کسب‌وکار ارسال کنید.

اطلاعات سیگنال های ردیابی سفارش موجود را به روز کنید

برای اصلاح داده‌های ردیابی سفارش ارسال‌شده از قبل، درخواستی را ارسال کنید که حاوی داده‌های جدیدی با همان orderId باشد. برای برآورد حمل و نقل و نشان سریع و رایگان، فقط از آخرین داده های ارسالی برای هر orderId استفاده می شود.