開發者實戰：如何用 Quire API 打造雙向同步

最後更新：2026 年 10 月 14 日

當數據同時存在於兩個應用程式，每個動作都要做兩次，否則就會在不知不覺間失去同步。雙向同步透過 webhooks 讓 Quire 與另一個應用程式自動交換更新，徹底解決重複輸入的問題。Quire 的開放 API 正是為這種模式而設。

工具之間互不相連的代價，早有清楚的數據佐證。根據麥肯錫有關社交經濟的研究，知識工作者每星期有近 20% 的時間用於追查內部資訊，而不是處理真正的工作。可靠的同步機制，能自動省去其中一大部分額外負擔。

Google日曆雙向同步應用程式就是最典型的例子：Quire 任務與 Google日曆事件無需人手核對，也能保持一致。本文會教你如何針對任何其他應用程式的 API，打造同樣的機制。

Google日曆雙向同步適用於 Premium 及以上的訂閲層級。詳情請參閱我們的定價頁面。

Quire 雙向同步的組成元件

雙向同步的工作流程是怎樣的？

你可以把雙向同步想像成兩個應用程式之間的對話。當你在 Quire 更新一項任務，它會把變更告訴另一個應用程式；而當那個應用程式有內容更新時，它亦會告訴 Quire。這樣你的資訊就能在各處保持一致。

實作步驟有哪些？

第一步是設定你的 Quire 應用程式。你需要建立一個應用程式，取得透過 API 存取 Quire 專案所需的憑證。

如想了解如何用 Quire API 打造自己的應用程式的逐步指南，請參閱我們的網誌文章。

要實作雙向同步，你需要開發一個中介層應用程式（你的應用程式），作為 Quire 與目標應用程式（例如 Google日曆）之間的橋樑。你可以把它當成翻譯員：從一方取得資訊、加以處理，再把正確的指令送往另一方。整個流程如下：Quire ↔ 你的應用程式 ↔ 另一個應用程式。

如何一步一步建置？

1. 準備一個處理事件的應用程式

要啟用雙向同步，首先要架設你自己的伺服器應用程式作為中介層。這個應用程式負責接收來自 Quire 及另一應用程式的 webhook POST 請求。 你的伺服器應該能夠：

• 接收來自 Quire 及另一應用程式的 HTTP POST 請求（webhook 事件）。
• 解析事件內容，判斷需要採取哪些行動。
• 按需要呼叫相應的 API，更新 Quire 或另一應用程式中的數據。

你可以用任何喜歡的技術打造這個伺服器應用程式，例如 Node.js、Python 或 Ruby。在以下區段，我們會用 Node.js 示範如何接收及處理 webhook 事件的簡單例子。 請確保你的伺服器能從互聯網連線，讓 Quire 及另一應用程式可以把 webhook 事件送達。

以下是一個使用 Express 的簡單 Node.js 例子：

const express = require('express');
const app = express();
app.use(express.json());

app.listen(3000, () => {
  console.log('Server is running on port 3000');
});

2. 在 Quire 設定 webhook，把任務更新傳送到你的應用程式

接著，你需要在伺服器中建立一個路由，用來接收來自 Quire 的 webhook 事件。

app.post('/webhook', (req, res) => {
  console.log('Received webhook event:', req.body);
  // TODO: Handle the event and update Quire or other app via API
  res.status(200).send('Event received');
});

在這個例子中，webhook 路由是 /webhook，所以完整網址會是 ${your-host}/webhook。

複製這個 webhook 網址，貼到 Quire 應用程式設定中，Quire 就會知道要把事件通知傳送到你應用程式的哪個位置。

此外，你亦需要將你的 Quire 應用程式註冊為想同步的專案的關注者，確保你的應用程式能收到相關更新的通知。

如想了解如何透過 Quire API 接收通知的逐步指南，請參閱我們的說明文件。

3. 在另一個應用程式設定 webhook，把其更新傳送到你的應用程式

要把另一個應用程式的更新同步到 Quire，你同樣需要在伺服器中建立一個路由，接收來自該應用程式的 webhook 事件。註冊流程與上面 Quire 的例子相近。只要把另一個應用程式設定為將事件通知送到你中介應用程式的 webhook 端點，並確保你的伺服器能妥善接收及處理這些事件即可。

4. 處理傳入事件，並透過各自的 API 更新 Quire 與另一應用程式中的數據

當你的應用程式開始接收來自 Quire 及另一應用程式的 webhook 事件後，你需要實作邏輯來處理這些事件，並在兩個平台之間同步數據。這通常包括：

• 解析事件內容，找出有甚麼改變（例如任務建立、更新或刪除）。有關事件結構的詳情，可參考 Quire API 文件 — 通知事件。
• 判斷需要呼叫哪些 API，才能把這些改變反映到另一應用程式。
• 向 Quire 或另一應用程式發送相應的 API 請求，令數據保持同步。
• 維護 Quire 任務 ID 與你應用程式項目 ID 之間的對應關係，確保更新正確連結。

只要細心處理傳入事件，並透過 API 更新數據，你的應用程式就能確保雙方的變更都準確反映，維持可靠的雙向同步。

以下是使用 Node.js 及 axios 的例子：

const axios = require('axios');

app.post('/webhook', (req, res) => {
  const { type } = req.body.data;
  // Reference of activity types: 
  // https://github.com/quire-api/quire-api/blob/master/docs/activity_types.md
  switch (type) {
    case 0: //Quire task created
      onQuireTaskCreate();
      break; 
    case 1: //Quire task deleted
      onQuireTaskDelete();
      break;
  }
  res.status(200).send('Event received');
});

// Route for handling events from another app to Quire
app.post('/anotherwebhook', async (req, res) => {
  const { isCreate, id, name, projectId } = req.body;
  if (isCreate) {
    // Create a task in the Quire project
    await axios.post(`https://quire.io/api/task/${projectId}`, { name });
    // Optionally, store the mapping between your app's id and Quire's task id
  } else {
    // Retrieve the corresponding Quire task id using your mapping logic
    const taskOid = getTaskIdByAppEventId(id, projectId);
    // Delete the task from the Quire project
    await axios.delete(`https://quire.io/api/task/${taskOid}`);
  }
  res.status(200).send('Event processed successfully');
});

這個例子示範如何處理來自另一應用程式的建立及刪除事件，並與 Quire 同步。請務必實作妥善的錯誤處理，並維護 ID 對應，確保同步穩定可靠。

有哪些關鍵注意事項？

兩條安全守則，足以涵蓋幾乎每個初次實作都會遇到的失誤：

• 追蹤每項變更的來源。為同步流程觸發的更新加上標籤，當它以 webhook 形式反彈回來時便忽略它。否則 Quire 推送到另一應用程式，另一應用程式又觸發 webhook 回傳，你的伺服器再推送一次，如此不斷循環，永無休止。
• 保持數據格式一致。某個欄位在 Quire 中的意思（例如 Markdown 格式的描述），可能需要明確轉換，才能正確變成行事曆事件描述、純文字問題備註或其他目標格式。

第三條守則，現在 Quire 已經支援：鎖定由你的同步機制負責的自訂欄位，人手編輯就不會與下一次同步互相衝突。請參閱如何鎖定自訂欄位。

下一步應該怎樣做？

開放 API 加上 webhooks，能讓 Quire 與你的其他工具合而為一，成為單一的真實來源，而不是兩套互相角力的數據。先從最小可行的同步範圍開始（一種事件類型、一個方向），確認整個流程能完整運作後，再逐步擴展。

相關文章：透過 Quire API 整合外部工具——以 n8n 為例——如果你想先用無程式碼自動化工具，而不是自建伺服器，這是一個可參考的實作例子。

常見問題

Quire 與其他應用程式之間的雙向同步是甚麼？

一種雙向連線，讓更新雙向流動：Quire 中的變更會推送到另一應用程式，而該應用程式中的變更亦會推送回 Quire。Google日曆雙向同步應用程式就是一個實際運作的例子。

要用 Quire API 打造雙向同步，我需要準備甚麼？

一個具備 API 憑證的 Quire 應用程式、一台能從互聯網連線以接收 webhooks 的中介層伺服器，以及在兩個 API 之間轉譯事件的邏輯。任何後端語言都適用。

中介層應用程式擔當甚麼角色？

它是 Quire 與另一項服務之間的翻譯員，負責接收 webhook 事件、決定要發出哪些 API 呼叫，並維護 Quire 任務 ID 與另一應用程式項目 ID 之間的對應關係。

如何避免無限同步迴圈？

追蹤每項變更的來源，並忽略由你自己的同步流程觸發的更新。若沒有這個防護機制，每次更新都會在兩個應用程式之間來回反彈，永無休止。

Google日曆雙向同步需要哪個 Quire 方案？

Premium 及以上。可在定價頁面查看最新的層級限制。