thinslatelabs/keepp-skill

管理 Keepp 頁面

什麼是 Keepp

Keepp 將創作者或小型企業的社交媒體個人簡介連結轉變為一個頁面：一個可分享的商品「卡片」與連結集合，旨在將追蹤者轉變為買家和潛在客戶。它被 Instagram、YouTube、TikTok、Pinterest 和 X 上的賣家、聯盟行銷者、教練、課程創作者和簡介連結創作者使用。

一個 Keepp 頁面由以下部分組成：

• 個人檔案 — 頭像、顯示名稱、簡短個人簡介
• 社交圖示 — 連結到頁面擁有者的社交帳戶
• 連結區塊 — 指向網站、預約頁面、WhatsApp 等的按鈕（加上區塊標題）
• 目錄卡片 — 可購物的商品卡片（照片、價格、促銷代碼、行動呼籲）
• 模式 — 僅連結、僅目錄 或 連結與目錄

此 API 控制的功能

此 API 管理兩件事：

1. 目錄卡片（貼文） — 建立、列出、更新和刪除擁有者目錄中的商品卡片。
2. 頁面設定 — 頁面的佈局模式、關於文字、主要行動呼籲按鈕、目錄卡片的預設值以及主題（請參閱下方的「頁面設定」）。

您無法透過此 API 修改：社交圖示、連結區塊和個人檔案詳細資訊（顯示名稱、頭像、頁面網址）。這些由擁有者在 Keepp 儀表板中設定 — 如果使用者要求這些，請引導他們前往 Keepp 儀表板。

驗證

每個請求都需要擁有者的 API 金鑰作為 Bearer token：

Authorization: Bearer keepp_live_…

Base URL：https://api.keepp.link。金鑰由Pro方案帳戶在儀表板的 AI 代理程式 下產生。如果您沒有金鑰，請向使用者索取。

端點

方法	路徑	用途
GET	/api/v1/posts?cursor=	列出目錄中的卡片（分頁）。
POST	/api/v1/posts	建立一張卡片。
GET	/api/v1/posts/:postId	取得單張卡片。
PATCH	/api/v1/posts/:postId	更新一張卡片。
DELETE	/api/v1/posts/:postId	刪除一張卡片。

卡片內容模型

建立/更新卡片時需使用三個頂層欄位：imageUrls、userContent 和 cardOverrides。

{
  "imageUrls": ["https://…/photo.jpg"],   // 最多 5 張；系統會為您擷取並儲存。每張 ≤10MB，JPEG/PNG/WebP/GIF 格式，需為公開的直接網址
  "userContent": {
    "name": "絲質圍巾",                  // 簡短標題（選填）
    "description": "手工染色桑蠶絲，90×90公分。",   // 必填
    "price": "$72",                        // 自由文字 — "$72"、"從 $50 起"、"₹1,499"（選填）
    "promoCode": "SAVE15",                 // 促銷/推薦/折扣代碼（選填）
    "category": "accessories",             // 下方其中一個類別（選填）
    "links": ["https://…"],                // 顯示在卡片上的額外連結（選填）
    "contacts": [{ "type": "whatsapp", "value": "+15551234567" }]   // 選填
  },
  "cardOverrides": {                       // 卡片行為設定（選填；省略則繼承頁面預設值）
    "clickAction": "open_detail",          // "open_detail" | "trigger_cta"
    "ctaType": "link",                     // "message" | "link" | "lead_collection"
    "ctaUrl": "https://shop…/scarf",       // 當 ctaType = "link" 時為必填
    "ctaLabel": "立即購買"                  // 按鈕文字
  }
}

僅 description 為必填欄位。其他皆為選填；省略 cardOverrides 則繼承頁面擁有者的全域預設值。

類別： clothing, jewellery, accessories, home_decor, beauty, food_beverage, art, stationery, plants, fitness, travel, real_estate, services, pets, kids_baby, books_media, crafts, other。

聯絡方式類型： phone, email, whatsapp, telegram, other。

卡片行為 — 兩個決策

1. clickAction — 點擊卡片時的行為：

• open_detail（預設）— 開啟完整的詳細檢視（所有照片、完整描述、價格、促銷代碼、CTA 按鈕）。當買家在行動前需要更多背景資訊時使用。
• trigger_cta — 點擊後立即觸發 CTA，不顯示詳細畫面。適用於不言自明的商品，希望將操作摩擦降至最低時使用。

2. ctaType — CTA 的行為：

• message — 開啟傳送訊息給商家。當沒有結帳連結時，這是一個安全預設值。
• link — 開啟 ctaUrl（例如 Shopify/Etsy 頁面、聯盟行銷連結、預約頁面、Google 表單）。需要 ctaUrl。當有專屬目的地時使用。
• lead_collection — 在頁面上開啟一個簡短表單，擷取訪客的聯絡資訊並儲存為潛在客戶。用於捕捉尚未準備好購買的使用者（等候名單、銷售名單、教練諮詢）。收集的欄位是透過頁面設定端點（見下方）在頁面範圍內設定的 catalogCard.leadCollection — 它們適用於所有卡片，而非每張卡片各自設定。

設定 ctaLabel 以符合動作："立即購買"、"立即訂購"、"取得型錄"、"預約您的名額"、"取得通知"。

頁面設定

讀取和更改頁面的整體配置。

方法	路徑	用途
GET	/api/v1/storefront	取得目前的頁面設定。
PATCH	/api/v1/storefront	變更設定。僅發送您想變更的欄位 — 它們會合併到當前配置中。

可編輯欄位：

{
  "mode": "links_and_catalog",   // "links_only" | "catalog_only" | "links_and_catalog"
  "about": "來自里斯本工作室的手工陶瓷。",  // 頁面短標語（≤280 字元）
  "mainCta": {                    // 頁面頂部的主要行動呼籲按鈕
    "enabled": true,
    "label": "預約通話",
    "url": "https://cal.com/me"   // 啟用時為必填
  },
  "catalogCard": {                // 每張卡片的頁面範圍預設值
    "showCardDetails": true,
    "clickAction": "open_detail", // "open_detail" | "trigger_cta"
    "ctaType": "message",         // "message" | "link" | "lead_collection"
    "ctaUrl": "https://…",        // 當 ctaType = "link" 時為必填
    "ctaLabel": "立即訂購",
    "leadCollection": { "phone": true, "email": true, "instagram": false, "message": true }
  },
  "theme": {
    "useCustomTheme": true,       // 必須為 true，preset/brandColor 才會生效
    "preset": "professional",     // "calm" | "professional" | "playful" | "dark"
    "brandColor": "#d7494c"       // 6 位十六進位色碼
  }
}

• 部分更新會合併。 PATCH {"theme":{"useCustomTheme":true,"brandColor":"#000000"}} 僅更改主題；mode、cards 等保持不變。
• 主題防護： 除非 useCustomTheme 為 true，否則 preset/brandColor 會被忽略 — 請在同一個請求中發送。
• catalogCard 是所有卡片的預設值。 卡片自身的 cardOverrides（見上方）優先於這些設定。更改這些值可以一次重新設定所有卡片的樣式。
• leadCollection 設定頁面範圍內潛在客戶表單收集的欄位（沒有依卡片選擇欄位的功能）。
• 無效的組合會回傳 400 INVALID_STOREFRONT_CONFIG（例如 ctaType:"link" 但沒有 ctaUrl）。

使用案例範例

附有促銷代碼的聯盟行銷/影響者商品 → 外部連結

{
  "imageUrls": ["https://example.com/serum.jpg"],
  "userContent": { "name": "維生素 C 精華液", "description": "我的日常光澤精華液 — 使用我的代碼享 15% 折扣。", "price": "$28", "promoCode": "GLOW15", "category": "beauty" },
  "cardOverrides": { "clickAction": "trigger_cta", "ctaType": "link", "ctaUrl": "https://brand.com/serum?ref=me", "ctaLabel": "使用我的代碼購買" }
}

透過自有商店販售的精品

{
  "imageUrls": ["https://example.com/scarf.jpg"],
  "userContent": { "name": "絲質圍巾", "description": "手工染色桑蠶絲，90×90公分。", "price": "$72", "category": "accessories" },
  "cardOverrides": { "clickAction": "open_detail", "ctaType": "link", "ctaUrl": "https://myshop.com/scarf", "ctaLabel": "立即購買" }
}

教練/服務 — 捕捉潛在客戶而非直接銷售

{
  "imageUrls": ["https://example.com/program.jpg"],
  "userContent": { "name": "1:1 教練服務", "description": "為期 6 週的計劃，幫助您獲得前 5 名客戶。", "price": "從 $400 起", "category": "services" },
  "cardOverrides": { "clickAction": "trigger_cta", "ctaType": "lead_collection", "ctaLabel": "立即申請" }
}

回應與錯誤

成功：{ "ok": true, "data": { … } }。錯誤：{ "ok": false, "error": { "code": "…", "message": "…" } }。

• 401 NO_API_TOKEN / INVALID_API_TOKEN — 金鑰遺失或已撤銷。請使用者提供有效的金鑰。
• 403 PLAN_REQUIRED — 帳戶未啟用 Pro 方案。
• 422 INVALID_IMAGE — 圖片網址無法擷取、類型/大小錯誤、重新導向或解析到非公開位址。請使用直接、公開的 https 圖片網址。
• 429 RATE_LIMITED — 每分鐘超過 60 個請求。請減速後重試。

使用指引

• 在刪除卡片前，請先與使用者確認。
• 只要取得 price 和 promoCode 就請設定 — 它們會顯示在卡片和詳細檢視中，是聯盟行銷和銷售案例的核心。
• 大量建立時，請保持每分鐘低於 60 個請求。
• 卡片會立即發佈到頁面上。
• 您可以管理卡片和頁面設定（模式、關於文字、主要 CTA、卡片預設值、主題）。對於連結、社交圖示和個人檔案詳細資訊（名稱、頭像、頁面網址），請告知使用者使用 Keepp 儀表板。

更多資訊

Keepp 的操作指南深入說明了 Keepp 頁面：

• 選擇您的佈局模式：https://keepp.link/blog/how-to/05-choosing-your-storefront-mode
• 產品卡片的外觀和行為：https://keepp.link/blog/how-to/06-configuring-how-product-cards-look-and-behave
• 每篇貼文的 CTA 和自訂連結：https://keepp.link/blog/how-to/07-setting-per-post-ctas-and-custom-links