thinslatelabs/keepp-skill

Keepp 페이지 관리하기

Keepp이란?

Keepp는 크리에이터나 소규모 비즈니스의 소셜 바이오 링크를 페이지로 전환합니다: 제품 '카드'와 링크가 포함된 공유 가능한 컬렉션으로, 팔로워를 구매자와 리드로 전환하도록 설계되었습니다. Instagram, YouTube, TikTok, Pinterest, X에서 활동하는 판매자, 제휴 마케터, 코치, 강좌 제작자, 링크인바이오 크리에이터가 사용합니다.

Keepp 페이지는 다음으로 구성됩니다:

• 프로필 — 아바타, 표시 이름, 짧은 소개
• 소셜 아이콘 — 소유자의 소셜 계정 링크
• 링크 블록 — 웹사이트, 예약 페이지, WhatsApp 등으로 연결되는 버튼 (섹션 헤더 포함)
• 카탈로그 카드 — 쇼핑 가능한 제품 카드 (사진, 가격, 프로모션 코드, 행동 유도 버튼)
• 모드 — 링크만, 카탈로그만, 또는 링크와 카탈로그

이 API가 제어하는 것

이 API는 두 가지를 관리합니다:

1. 카탈로그 카드 (게시물) — 소유자의 카탈로그에 있는 제품 카드를 생성, 목록 조회, 업데이트, 삭제합니다.
2. 페이지 설정 — 페이지의 레이아웃 모드, 소개글, 히어로 CTA, 카탈로그 카드 기본값, 테마 (아래 '페이지 설정' 참조).

이 API를 통해 변경할 수 없는 것: 소셜 아이콘, 링크 블록, 프로필 세부 정보 (표시 이름, 아바타, 페이지 URL). 이들은 소유자가 Keepp 대시보드에서 설정합니다. 사용자가 요청하면 Keepp 대시보드를 안내하세요.

인증

모든 요청에는 소유자의 API 키가 Bearer 토큰으로 필요합니다:

Authorization: Bearer keepp_live_…

기본 URL: https://api.keepp.link. 키는 Pro 계정의 대시보드에서 AI Agent 아래에서 생성됩니다. 키가 없다면 사용자에게 요청하세요.

엔드포인트

메서드	경로	목적
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, 직접 공개 URL
  "userContent": {
    "name": "실크 스카프",                  // 짧은 제목 (선택사항)
    "description": "손염색 뽕나무 실크, 90×90cm.",   // 필수
    "price": "$72",                        // 자유 텍스트 — "$72", "From $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 Form). ctaUrl 필수. 전용 목적지가 있을 때 사용.
• lead_collection — 페이지에서 방문자의 연락처 정보를 캡처하는 짧은 양식 열기. 리드로 저장. 구매 준비가 안 된 사람(대기자 명단, 판매 목록, 코칭 문의)을 캡처할 때 사용. 수집되는 필드는 페이지 설정 엔드포인트의 catalogCard.leadCollection을 통해 페이지 전체에 설정됩니다 (아래 참조) — 모든 카드에 적용되며 카드별로 설정되지 않습니다.

ctaLabel을 행동에 맞게 설정: "Buy now", "Order now", "Get the lookbook", "Reserve yours", "Get notified".

페이지 설정

페이지의 전체 구성을 읽고 변경합니다.

메서드	경로	목적
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,       // preset/brandColor가 적용되려면 반드시 true여야 함
    "preset": "professional",     // "calm" | "professional" | "playful" | "dark"
    "brandColor": "#d7494c"       // 6자리 16진수
  }
}

• 부분 업데이트는 병합됩니다. PATCH {"theme":{"useCustomTheme":true,"brandColor":"#000000"}}는 테마만 변경하고, 모드, 카드 등은 그대로 유지됩니다.
• 테마 가드: useCustomTheme가 true가 아니면 preset/brandColor는 무시됩니다 — 같은 요청에 함께 보내세요.
• catalogCard는 모든 카드의 기본값입니다. 각 카드의 cardOverrides (위)가 이를 덮어씁니다. 이것을 변경하면 모든 카드의 스타일을 한 번에 변경할 수 있습니다.
• leadCollection 은 페이지 전체 리드 양식이 수집할 필드를 설정합니다 (카드별 필드 선택은 없습니다).
• 유효하지 않은 조합은 400 INVALID_STOREFRONT_CONFIG 오류로 거부됩니다 (예: ctaUrl 없이 ctaType:"link").

사용 사례 레시피

제휴 / 인플루언서 제품 + 프로모션 코드 → 외부 링크

{
  "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×90cm.", "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": "처음 5명의 고객을 유치하는 6주 프로그램.", "price": "From $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 — 이미지 URL을 가져올 수 없거나, 잘못된 유형/크기이거나, 리디렉션되거나, 공개 주소가 아님. 직접적인 공개 https 이미지 URL을 사용하세요.
• 429 RATE_LIMITED — 분당 60회 초과. 속도를 줄이고 재시도하세요.

지침

• 카드를 삭제하기 전에 사용자와 확인하세요.
• price와 promoCode가 있으면 항상 설정하세요. 카드와 상세 보기에 표시되며, 제휴 및 판매 사용 사례의 핵심입니다.
• 대량 생성 시 분당 60회 요청 미만으로 유지하세요.
• 카드는 페이지에 즉시 게시됩니다.
• 카드 및 페이지 설정(모드, 소개글, 히어로 CTA, 카드 기본값, 테마)을 관리할 수 있습니다. 링크, 소셜 아이콘, 프로필 세부 정보(이름, 아바타, 페이지 URL)는 사용자에게 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