利用 WordPress 實現 WooCommerce 與 Ragic 訂單資料自動同步技術筆記

內容目錄

前言

在電子商務系統中，訂單資料的管理與整合是提升營運效率的重要環節。WooCommerce 作為 WordPress 上熱門的電商插件，能有效管理訂單，但若要進一步分析與整合資料，將訂單同步至 Ragic 雲端資料庫是一個實用方案。本文適合具備基礎 PHP 與 WordPress 開發經驗的工程師或自學者，說明如何自動將 WooCommerce 訂單資料同步至 Ragic。

為什麼要同步 WooCommerce 訂單至 Ragic？

Ragic 是一款靈活的雲端資料庫工具，方便用戶集中管理與分析業務資料。透過自動同步 WooCommerce 訂單資料，可以：

減少手動輸入，提升工作效率
降低人為錯誤，確保資料正確性
集中管理訂單數據，方便後續分析與決策

教學步驟

1. 啟用訂單完成後的同步觸發

利用 WooCommerce 的鉤子 woocommerce_order_status_completed，當訂單狀態變更為「已完成」時觸發同步函式：

add_action('woocommerce_order_status_completed', 'sync_order_to_ragic');

2. 擷取 WooCommerce 訂單資料

使用 WooCommerce API 取得訂單詳細資訊，包括用戶姓名、電話、地址及訂單商品：

$order = wc_get_order($order_id);
$email = $order->get_billing_email();
$first_name = $order->get_billing_first_name();
$last_name = $order->get_billing_last_name();
$phone = $order->get_billing_phone();
$address = $order->get_billing_address_1() . ', ' . $order->get_billing_city() . ', ' . $order->get_billing_state() . ', ' . $order->get_billing_postcode();

3. 整理訂單商品資料格式

將訂單中每項商品名稱、數量與價格組合成字串，方便傳輸：

$items = [];
foreach ($order->get_items() as $item) {
  $items[] = $item->get_name() . ' x ' . $item->get_quantity() . ' (' . $item->get_total() . ')';
}
$items_string = implode('; ', $items);

4. 組織符合 Ragic API 欄位結構的資料

根據 Ragic 表單欄位 ID，將資料映射成陣列格式：

$ragic_data = [
  '1000686' => '網站',
  '1000595' => $first_name . ' ' . $last_name,
  '1000596' => $phone,
  '1000563' => $address,
  '1000634' => $email,
  '1000597' => $items_string,
  '1000610' => $order->get_total(),
  '1000594' => $order->get_date_created()->date('Y-m-d H:i:s'),
];

5. 使用 Ragic API 同步資料

透過 wp_remote_post 發送 POST 請求，將資料以 JSON 格式送至 Ragic：

$response_ragic = wp_remote_post(
  $ragic_url,
  [
    'method' => 'POST',
    'headers' => [
      'Content-Type' => 'application/json',
      'Authorization' => 'Basic YOUR_RAGIC_API_CREDENTIAL',
    ],
    'body' => json_encode($ragic_data),
  ]
);

6. 檢查 API 回應並記錄錯誤

確保同步成功，並在失敗時記錄錯誤訊息以利除錯：

if (is_wp_error($response_ragic)) {
  error_log('Ragic 同步失敗：' . $response_ragic->get_error_message());
} else {
  $status_code_ragic = wp_remote_retrieve_response_code($response_ragic);
  $body_ragic = wp_remote_retrieve_body($response_ragic);

  if ($status_code_ragic == 200 || $status_code_ragic == 201) {
    error_log('Ragic 同步成功：' . $body_ragic);
  } else {
    error_log("Ragic API 回應錯誤 (狀態碼: $status_code_ragic)：$body_ragic");
  }
}

注意事項

API Key 安全性：避免將 API Key 明文寫入程式碼，建議使用環境變數或安全存取方式。
欄位對應檢查：確認 Ragic 表單欄位 ID 與程式碼中對應正確，避免資料錯置。
測試與效能優化：正式上線前充分測試同步流程，確保資料完整且效能穩定。

完整程式碼

add_action('woocommerce_order_status_completed', 'sync_order_to_ragic');

function sync_order_to_ragic($order_id) {
  $order = wc_get_order($order_id);
  $email = $order->get_billing_email();
  $first_name = $order->get_billing_first_name();
  $last_name = $order->get_billing_last_name();
  $phone = $order->get_billing_phone();
  $address = $order->get_billing_address_1() . ', ' . $order->get_billing_city() . ', ' . $order->get_billing_state() . ', ' . $order->get_billing_postcode();

  $items = [];
  foreach ($order->get_items() as $item) {
    $items[] = $item->get_name() . ' x ' . $item->get_quantity() . ' (' . $item->get_total() . ')';
  }
  $items_string = implode('; ', $items);

  $ragic_data = [
    '1000686' => '網站',
    '1000595' => $first_name . ' ' . $last_name,
    '1000596' => $phone,
    '1000563' => $address,
    '1000634' => $email,
    '1000597' => $items_string,
    '1000610' => $order->get_total(),
    '1000594' => $order->get_date_created()->date('Y-m-d H:i:s'),
  ];

  $ragic_url = 'https://www.ragic.com/your_ragic_url'; // 請替換為實際 Ragic API URL

  $response_ragic = wp_remote_post(
    $ragic_url,
    [
      'method' => 'POST',
      'headers' => [
        'Content-Type' => 'application/json',
        'Authorization' => 'Basic YOUR_RAGIC_API_CREDENTIAL', // 請替換為實際授權資訊
      ],
      'body' => json_encode($ragic_data),
    ]
  );

  if (is_wp_error($response_ragic)) {
    error_log('Ragic 同步失敗：' . $response_ragic->get_error_message());
  } else {
    $status_code_ragic = wp_remote_retrieve_response_code($response_ragic);
    $body_ragic = wp_remote_retrieve_body($response_ragic);

    if ($status_code_ragic == 200 || $status_code_ragic == 201) {
      error_log('Ragic 同步成功：' . $body_ragic);
    } else {
      error_log("Ragic API 回應錯誤 (狀態碼: $status_code_ragic)：$body_ragic");
    }
  }
}

前言