跟踪第三方订单

Genstore 提供了与外部平台（如外部物流公司或市场）集成的能力，使商家能够管理并跟踪来自其他平台的订单。借助自定义订单管理应用（Order Management Apps, OMA），商家不仅可以在 Genstore 平台上查看订单详情，还可以同步外部订单的跟踪信息，实现跨平台订单状态的统一管理。

前置准备

您的应用具有 write_orders、write_fulfillments。了解访问范围和如何配置您的访问范围。
已有外部订单信息。
了解订单相关 API。

跟踪流程

要跟踪其他平台的订单，您需要构建一个自定义订单管理应用，该应用的主要步骤如下：

获取订单跟踪信息
从外部平台获取订单跟踪信息，这些信息通常包括跟踪号码、运输公司和状态更新等数据。
在 Genstore 中更新订单状态
获取外部跟踪信息后，调用 Genstore API 将跟踪号码、运输公司及履约状态等信息同步更新到对应订单中。
显示跟踪信息
在订单详情页面中展示最新的跟踪信息，方便客户随时查询订单状态和物流进展。

API 总览

在跟踪第三方订单时，以下接口非常关键：

API Endpoint	功能描述
`/api/202412/orders?limit={n}`	分页查询订单列表，用于滚动加载订单数据
`/api/202412/orders/{orderId}`	获取指定订单的详细信息，包括关联履约信息

开发者可根据实际业务需求，利用这些接口查询并更新订单状态、同步外部跟踪信息。

TIP

确保外部平台的订单数据和跟踪信息能够及时同步到 Genstore，避免延迟。
可以定期检查订单状态的更新，确保客户得到及时的通知。
考虑在订单页面上提供外部平台的直达链接，方便客户查看详细的跟踪信息。

业务场景 - 获取订单列表

业务场景说明：

通过查询订单列表接口，开发者可以获取商家的所有订单，并筛选出需要进行跟踪更新的订单。

示例：

GET /api/202412/orders?limit={n}

json

curl --request GET \
  --url 'https://{your-development-store}.genmystore.com/api/202412/orders?limit=10' \
  --header 'x-genstore-access-token: {access-token}' \
'

业务场景 - 订单详情

业务场景说明：

查询订单详情接口可以获取单个订单的全部信息，包括关联的履约记录和物流跟踪信息，便于后续更新或展示。

示例：

GET /api/202412/orders/{orderId}

json

curl -X GET \ 
https://{your-development-store}.genmystore.com/api/202412/orders/{orderId}" \ 
-H "X-Genstore-Access-Token: {access_token}" \

响应结果：

json

HTTP/1.1 200 OK
{
  "order": {
    "note": "Customer changed their mind.",
    "sourceIdentifier": "ORDERID-123",
    "totalOutstanding": "5.00",
    "currentTotalDiscounts": "10.00",
    "orderId": "1001",
    "totalPrice": "409.94",
    "totalDiscounts": "0.00",
    "paymentGatewayNames": [
      "authorize_net",
      "Cash on Delivery (COD)"
    ],
    "currentTotalTax": "10.00",
    "fulfillmentStatus": "partial",
    "currentTotalPrice": "10.00",
    "currentSubtotalPrice": "10.00",
    "lineItems": [
      {
        "variantTitle": "Pink",
        "quantity": "1",
        "productId": "7513594",
        "taxable": "true",
        "title": "IPod Nano",
        "fulfillableQuantity": "1",
        "fulfillmentStatus": "fulfilled",
        "requiresShipping": "true",
        "price": "199.99",
        "giftCard": "false",
        "totalDiscount": "5.00",
        "id": "669751112",
        "variantId": "4264112",
        "grams": "500",
        "sku": "IPOD-342-N",
        "currentQuantity": "1"
      }
    ],
    "totalTax": "11.94",
    "createdAt": "2008-01-10T11:00:00-05:00",
    "fulfillments": [
      {
        "createdAt": "2022-01-01T11:00:00-01:00",
        "orderId": "3183479",
        "fulfillId": "255858046",
        "status": "failure",
        "updatedAt": "2022-01-01T11:00:00-01:00\""
      }
    ],
    "presentmentCurrency": "CAD",
    "dutiesIncluded": "false",
    "currency": "USD",
    "cancelReason": "customer",
    "closedAt": "2008-01-10T11:00:00-05:00",
    "subtotalPrice": "398.00",
    "email": "[email protected]",
    "paymentTerms": {
      "amount": "70",
      "currency": "CAD"
    },
    "updatedAt": "2012-08-24T14:02:15-04:00",
    "taxesIncluded": "false",
    "discountCodes": [
      {
        "amount": "30.00",
        "code": "SPRING30",
        "type": "fixed_amount"
      }
    ],
    "cancelledAt": "null",
    "tags": "imported, vip",
    "buyerAcceptsMarketing": "false",
    "phone": "+557734881234",
    "totalLineItemsPrice": "398.00",
    "financialStatus": "paid",
    "totalWeight": "300",
    "shippingAddress": {
      "zip": "K2P0V6",
      "country": "Canada",
      "lastName": "Bobsen",
      "address2": "Amoebobacterieae",
      "city": "Ottawa",
      "address1": "123 Amoebobacterieae St",
      "provinceCode": "ON",
      "latitude": "45.41634",
      "firstName": "Bob",
      "province": "Ontario",
      "phone": "555-625-1199",
      "countryCode": "CA",
      "name": "Bob Bobsen",
      "longitude": "-75.6868"
    },
    "billingAddress": {
      "zip": "T0E 0M0",
      "country": "Canada",
      "lastName": "Gorski",
      "address2": "Apartment 5",
      "city": "Drayton Valley",
      "address1": "2259 Park Ct",
      "provinceCode": "AB",
      "latitude": "45.41634",
      "firstName": "Christopher",
      "province": "Alberta",
      "phone": "(555)555-5555",
      "countryCode": "CA",
      "name": "Christopher Gorski",
      "longitude": "-75.6868"
    },
    "sourceName": "instagram",
    "customer": {
      "lastName": "Norman",
      "note": "A note about the customer.",
      "taxExempt": "true",
      "taxExemptions": [
        "CA_STATUS_CARD_EXEMPTION",
        "CA_BC_RESELLER_EXEMPTION"
      ],
      "tags": "loyal",
      "createdAt": "2013-06-27T08:48:27-04:00",
      "firstName": "John",
      "phone": "16135551111",
      "currency": "JPY",
      "id": "207119551",
      "state": "disabled",
      "email": "[email protected]",
      "updatedAt": "2012-08-24T14:01:46-04:00",
      "verifiedEmail": "true",
      "defaultAddress": ""
    }
  }
}

Webhook

为实现订单状态和履约信息的实时自动化管理，建议订阅以下订单相关 Webhook，以便在订单创建、支付、更新、履约或取消时及时接收通知，从而触发相应的业务处理：

Webhook 主题	描述
`orders/create`	通知订单创建
`orders/paid`	通知订单已支付
`orders/update`	通知订单更新
`orders/fulfilled`	通知订单已履约
`orders/partiallyFulfilled`	通知订单部分完成履约
`orders/cancelled`	此 Webhook 在订单被取消时触发，帮助您实时获取订单取消的信息，以便进行相应的操作或跟踪。
`refunds/create`	退款消息，主要包括退款处理中、已退款和资金变动消息

通过 Genstore CLI 构建应用

应用开发案例

跟踪第三方订单

前置准备

跟踪流程

API 总览

业务场景 - 获取订单列表

业务场景 - 订单详情

Webhook

跟踪第三方订单 ​

前置准备 ​

跟踪流程 ​

API 总览 ​

业务场景 - 获取订单列表 ​

业务场景 - 订单详情 ​

Webhook ​

跟踪第三方订单

前置准备

跟踪流程

API 总览

业务场景 - 获取订单列表

业务场景 - 订单详情

Webhook