開始使用 Conciar API

Conciar 有兩個 API。可以用它們在您的 Conciar 帳號之上，打造自己的顧客 App、網站後端或整合服務。

API	用途	金鑰	Base URL
Connect API	據點、餐廳菜單與外帶訂單、顧客登入與會員集點、網路商店商品目錄、購物車、結帳與訂閱。	需要	https://api.conciar.com/connect/v1
公開訂位 API（Public booking API）	餐廳訂位：可訂時段、訂位（可收訂金或信用卡擔保）、客人自己的訂位、售票活動與禮物卡。	不需要	https://api.conciar.com/public/v1

公開訂位 API 不需要金鑰。您以餐廳的 guid 指定餐廳。如果只想在網站上接受訂位，不需要開發任何東西：嵌入訂位小工具即可。

1. 建立 API 金鑰

1. 以 Admin 或 Manager 身分登入 my.conciar.com。
2. 開啟 Management → API Keys，點選 New API Key。
3. 輸入 Key Name，例如「顧客 App」，然後點選 Create Key。
4. 立即複製金鑰的兩個部分：可公開金鑰（pk_…）和私密金鑰（cnct_…）。它們只會顯示一次。

兩個部分的差異以及如何妥善保管，請參閱 API 金鑰與驗證。

2. 找到銷售通路權杖

您銷售的每個據點或商店都是一個銷售通路。呼叫 /store/… 和 /app/init 時，需要在 X-Sales-Channel 標頭中帶入該通路的權杖（cnct_ch_…）。通路決定菜單或商品目錄、價格、幣別、語言和付款方式。

權杖可以在兩個地方找到：

• 在 my.conciar.com 的 Settings → Sales channels 中，名稱為 Channel token；
• 在 GET /locations 的回應中，欄位為 sales_channel_token。

3. 送出第一個請求

用可公開金鑰列出您的據點：

curl "https://api.conciar.com/connect/v1/locations" \
  -H "Accept: application/json" \
  -H "X-Api-Key: pk_your_publishable_key"

回應（節錄）：

{
  "data": {
    "timezone": "Europe/Amsterdam",
    "locations": [
      {
        "sales_channel_token": "cnct_ch_your_channel_token",
        "name": "Bistro Example",
        "is_test": false,
        "address": "Example Street 1, 1000 AA Example City",
        "is_open_now": true
      }
    ]
  }
}

GET /locations 會列出您啟用中的銷售通路。外送平台通路（例如 Uber Eats）不在清單中。

請求標頭

標頭	使用時機	值
X-Api-Key	每個 Connect 呼叫	您的可公開金鑰（pk_…）或私密金鑰（cnct_…）。
X-Sales-Channel	每個 /store/… 呼叫和 /app/init	通路權杖（cnct_ch_…）。
Accept-Language	選用	例如 nl 或 zh-TW。預設為通路的語言。
X-Currency	選用	預設為通路的幣別。無法辨識的值會被忽略。
Authorization	代表已登入顧客的呼叫	來自 /auth/otp/verify 的 Bearer <access_token>。
Idempotency-Key	選用，下餐廳訂單時	1–64 個字元。用相同的值重試時，會回傳第一筆訂單。
X-Order-Token	訪客查詢、支付或取消餐廳訂單時	下單時取得的 order_token。

已登入的顧客

顧客透過電子郵件收到的 6 位數驗證碼登入：

1. POST /auth/otp/request 寄送驗證碼。
2. POST /auth/otp/verify 驗證並回傳 access_token。權杖有效期為 6 個月。

把權杖以 Authorization: Bearer … 與 API 金鑰一起送出。/store/customer/… 端點必須帶入權杖。餐廳訂單則為選用：帶入時，訂單會歸屬於該顧客，並累積會員集章與點數。

免寫程式：訂位小工具

若要在網站上接受餐廳訂位，請把以下程式碼貼到訂位表單要出現的位置。把 guid 換成您餐廳的 guid；完整程式碼可在 my.conciar.com 的 Settings → Restaurant 中找到。

<div class="conciar-widget"
     data-widget-type="restaurant-reservation"
     data-guid="YOUR_RESTAURANT_GUID"
     data-lang="auto"></div>
<script src="https://widget.conciar.com/conciar-widget.iife.js" defer></script>

data-lang 接受語言代碼，例如 en 或 nl，或用 auto 採用訪客瀏覽器的語言。

下一步

• API 金鑰與驗證：金鑰類型、錯誤與速率限制。
• API 參考文件：所有端點，附範例。
• 程式碼範例：外帶訂單、顧客登入和餐廳訂位，逐步說明。