訂單整合

提供高品質的訂單和購買後體驗對顧客的信任度和轉換率／留存率極為重要。確保訂單在 Meta 系統與商家系統之間處理並同步，可提升顧客體驗的準確性和可靠性，並減少顧客問題和商家問題的案例：

• 顧客問題（例如取消訂單或延遲交貨）會損害商家的聲譽，並增加顧客支援的需求。
• 商家問題（例如訂單履行同步問題）可能會導致 Meta 系統上未標記為已履行的訂單延遲或無法獲得付款。

若未能及時確認／處理退款／退貨等購買後支援，可能會導致商家需要承擔支援單位起始退款的成本。

對賣家而言，最好的訂單管理體驗是讓賣家能夠在其既有的訂單管理系統（OMS）中完成以下「需要完成的工作」（JTBD）：

• 處理和履行新訂單
• 取消整筆或部分訂單，以通知顧客發生履行問題
• 將整筆或部分訂單退款給顧客

除非產品標示為 final sale，否則您必須提供退貨支援。買家預設有 30 天的退貨期限，但賣家也可以設定商品層級的退貨政策。買家可前往訂單摘要要求退貨，這會啟動下列其中一個流程：

• 如果在商店的退貨設定中已設定 Returns URL，則會開啟賣家的退貨網站。
• 傳送電子郵件至賣家在商店設定中註冊的顧客支援聯絡地址。

如果包裝中已提供退貨標籤，顧客也可以直接退貨，而無需使用 Facebook 或 Instagram 應用程式。當賣家收到退回的商品後，應啟動退款。

若要完整瞭解與「Meta 商務」訂單相關的各種訂單狀態、轉換和操作，請參閱訂單生命週期。雖然此總覽是從直銷賣家（也稱為商家）整合的觀點來描述，但非常適用於由合作夥伴平台代理賣家的合作夥伴整合。

賣家成功在 Meta 啟用並上傳庫存後，其商品即可供消費者購買。在「商務平台」上，您可以使用訂單管理 API 將您支援之賣家的訂單轉移到您的系統中並管理其生命週期。

必備條件

您必須做到以下幾點，才能符合我們的商店整合品質標準：

需求 1：接收並確認來自 Meta 的訂單

需求 2：將訂單狀態從 OMS 同步到 Meta

準備工作

您的應用程式必須具有下列權限：

• commerce_manage_accounts 或 commerce_account_read_settings
• commerce_account_manage_orders 或 commerce_account_read_orders

需求 1：接收並確認從 Meta 傳送到 OMS 的訂單

步驟 1：接收新訂單

若要透過 API 管理訂單，應用程式必須先與代表給定商店的商務賣家設定建立關聯。此動作只需要為每個商店執行一次，並指示 Meta 商務平台將已完成的訂單保留在 CREATED 狀態供您確認。

要求範例

curl -X POST \
  -F 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/{api-version}/{cms-id}/order_management_apps

回應範例

{
    "success": true
}

在 Facebook 或 Instagram 上提交的訂單，在我們內部系統處理期間會先擱置。此延遲的設計也是為了讓買家有機會後悔並取消訂單。在 Meta 驗證給定的交易合法之後，相應的訂單就會釋出供賣家履行。當賣家履行訂單時，與該履行內容相關的資金將會留存，並開始進行付款給賣家的程序。

使用列出訂單 API 來發現新訂單，這是一種提取機制，可讓您定期輪詢 API 以搜尋需要履行的新訂單。建議的輪詢間隔為 5 到 15 分鐘。根據預設，此 API 會列出與商店相關聯的所有商務訂單，只傳回 CREATED 狀態的訂單。

要求範例

curl -X GET -G \
  -d 'state=CREATED' \
  -d 'fields=id,buyer_details,channel,merchant_order_id,order_status' \
  -d 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/{api-version}/{cms-id}/commerce_orders

回應範例

{
  "data": [
    {
      "id": "3565497390177110",
      "buyer_details": {
        "name": "John Doe",
        "email": "7dvra5wfy2@commerce.facebook.com",
        "email_remarketing_option": false
      },
      "channel": "facebook",
      "order_status": {
        "state": "CREATED"
      }
    }
  ],
  "paging": {
    "cursors": {
      "before": "--SANITIZED--",
      "after": "--SANITIZED--"
    }
  }
}

回應包含 data[].id 欄位中的 ORDER_ID 變數，在後續要求中會使用該變數來識別此特定訂單上的操作。回應中可能會有較多新訂單。為了確保您已處理所有新訂單，請使用分頁游標。進一步瞭解訂單 API。

步驟 2：確認訂單

訂單在 Meta 商務平台上處理完成（詐騙檢查等）後，其狀態會自動變更為 CREATED。進一步瞭解訂單狀態。

確認訂單即確認您已將訂單移到訂單管理系統（OMS）中，並準備好讓賣家履行訂單。您應確認賣家有足夠的庫存，而且在您確認訂單時該庫存已預留備用。確認訂單會將其狀態變更為 IN_PROGRESS。

您可以在確認期間傳遞 merchant_order_reference。這會顯示您內部 OMS 已知的專屬訂單編號。此編號會顯示在收據上，用戶可以在聯絡您的團隊以尋求支援時參考此編號。

您可以依據訂單量，使用一般或批次 API 來進行確認。此 API 可在單一要求中確認最多 100 筆訂單。如果您預期會有大量訂單，建議您批次確認。如果您個別確認每筆訂單，可能會超過我們的粉絲專頁速率限制。如果您超過速率限制，API 呼叫會遭到限速。若要批次處理訂單，請使用我們的批量確認方法。若要確認已建立的訂單，請使用 ORDER_ID 來呼叫確認 API。

要求範例

curl -X POST \
  -F '{
    "idempotency_key": "<UUID>"
  }' \
  -F 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/{api-version}/{order-id]/acknowledge_order

要求範例（非批次）

{
  "id": "3565497390177110",
  "state": "IN_PROGRESS"
}

要求範例（批次）

{
  "idempotency_key": "cb090e84-e75a-9a34-45d3-5163bec88b65",
  "orders": [
    {
      "id": "64000841790004"
    },
    {
      "id": "10100677592885259"
    }
  ]
}

如果 FB_PROCESSING 狀態的訂單很少，則無法使用 ACK 來確認訂單，您會收到例外狀況代碼。使用相同的冪等性索引鍵重試這些要求會傳回相同的結果。如果您收到例外狀況代碼，建議您使用新的冪等性索引鍵並重試。

回應範例（批次）

{
  "orders": [
    {
      "id": "64000841790004",
      "state": "IN_PROGRESS"
    },
    {
      "id": "10100677592885259",
      "error": {
        "error_code": 2361003,
        "error_message": "Invalid Order ID"
      }
    }
  ]
}

進一步瞭解確認 API。

需求 2：將訂單狀態從 OMS 同步到 Meta

步驟 1：同步訂單取消

賣家可以取消 IN_PROGRESS 狀態的訂單或訂單中的部分商品。例如，在尚未出貨的情況下，通知買家有履行問題。當賣家在您的 OMS 中起始取消時，請使用 ORDER_ID 來呼叫取消訂單 API，與 Meta 同步此訂單取消狀態。

要求範例

curl -X POST \
  -F 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/{api-version}/{order-id}/cancellations

要求範例（整筆訂單）

  "cancel_reason": {
    "reason_code": "CUSTOMER_REQUESTED",
    "reason_description": "Buyer did not need it anymore"
  },
  "restock_items": true,
  "idempotency_key": "cb090e84-e75a-9a34-45d3-5153bec88b65"
}

要求範例（部分訂單）

{
  "cancel_reason": {
    "reason_code": "OUT_OF_STOCK",
    "reason_description": "Ran out of item"
  },
  "restock_items": false,
  "items": [
    {
      "retailer_id": "FB_product_1234",
      "quantity": 1
    }
  ],
  "idempotency_key": "cb090e84-e75a-9a34-45d3-5153bec88b65"
}

回應範例

{
  "success": true
}

進一步瞭解取消 API。

步驟 2：同步訂單履行

當賣家開始履行訂單時，請使用貨運業者代碼與追蹤號碼關聯的 ORDER_ID 來呼叫貨件 API，將訂單的履行狀態從您的 OMS 同步到 Meta。

要求範例

curl -X POST \
  -F '{
    "external_shipment_id": "shipment_1",
    "items": [
      {
        "retailer_id": "FB_T_Shirt_001",
        "quantity": 1
      }
    ],
    "tracking_info": {
      "tracking_number": "1Z204E380338943508",
      "carrier": "UPS",
    },
    "idempotency_key": "<UUID>"
  }' \
  -F 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/{api-version]/{order-id}/shipments

回應範例

{
  "success": true
}

進一步瞭解履行 API。

步驟 3：同步訂單退款

賣家通常可以起始部分或全額退款（按數量或價格）來回應買家提報的商品問題。當賣家起始退款操作時，請使用 ORDER_ID 和原因代碼來呼叫退款訂單 API，將退款訂單狀態從您的 OMS 同步到 Meta。（如需可能的退款原因清單，請參閱 refund_reason_code 列舉）。這會觸發 Meta 對買家的反向付款交易，並從賣家的餘額中扣除相應的金額。

要求範例

curl -X POST \
  -F '{
   "reason_code": "WRONG_ITEM",
   "idempotency_key": "<UUID>"
}' \
  -F 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/{api-version}/{order-id}/refunds

要求範例（整筆訂單）

{
    "reason_code": "WRONG_ITEM",
    "idempotency_key": "cb090e84-e75a-9a34-45d3-5153bec88b65"
}

要求範例（部分訂單）

{
  "items": [
    {
      "item_id": "1234",
      "item_refund_quantity": 1
    },
    {
      "item_id": "38383838",
      "item_refund_amount": {
        "amount": "2.5",
        "currency": "USD"
      }
    }
  ],
  "shipping": {
    "shipping_refund": {
      "amount": "2.4",
      "currency": "USD"
    }
  },
  "deductions": [
    {
      "deduction_type": "RETURN_SHIPPING",
      "deduction_amount": {
        "amount": "5.5",
        "currency": "USD"
      }
    }
  ],
  "reason_code": "WRONG_ITEM",
  "idempotency_key": "cb090e84-e75a-9a34-45d3-5153bec88b65"
}

回應範例

{
  "success": true
}

進一步瞭解退款 API。

瞭解詳情

• 訂單管理 API
• 列出訂單 API
• 訂單狀態
• 取消訂單 API