thinslatelabs/keepp-skill

Gerenciando uma Página Keepp

O que é Keepp

Keepp transforma o link de bio de um criador ou pequeno negócio em uma página: uma coleção compartilhável de "cards" de produtos mais links, construída para converter seguidores em compradores e leads. É usado por vendedores, afiliados, coaches, criadores de cursos e criadores de link-in-bio em Instagram, YouTube, TikTok, Pinterest e X.

Uma página Keepp é composta por:

• Perfil — avatar, nome de exibição, biografia curta
• Ícones sociais — links para as redes sociais do proprietário
• Blocos de links — botões para um site, página de agendamento, WhatsApp, etc. (mais cabeçalhos de seção)
• Cards do catálogo — os cards de produto com opção de compra (foto, preço, código promocional, chamada para ação)
• Modo — links only, catalog only ou links and catalog

O que esta API controla

Esta API gerencia duas coisas:

1. Cards do catálogo (posts) — criar, listar, atualizar e excluir os cards de produto do catálogo do proprietário.
2. Configurações da página — o modo de layout da página, texto "Sobre", CTA do herói, defaults dos cards do catálogo e tema (veja "Configurações da página" abaixo).

Você NÃO pode alterar através desta API: ícones sociais, blocos de links e detalhes do perfil (nome de exibição, avatar, URL da página). Eles são definidos pelo proprietário no painel do Keepp — se um usuário pedir por eles, oriente-o a usar o painel do Keepp.

Autenticação

Cada requisição precisa da chave de API do proprietário como token Bearer:

Authorization: Bearer keepp_live_…

URL base: https://api.keepp.link. Chaves são geradas por uma conta Pro em Agente de IA no painel. Se você não tiver uma, peça ao usuário.

Endpoints

Método	Caminho	Propósito
GET	/api/v1/posts?cursor=	Listar os cards do catálogo (paginado).
POST	/api/v1/posts	Criar um card.
GET	/api/v1/posts/:postId	Buscar um card.
PATCH	/api/v1/posts/:postId	Atualizar um card.
DELETE	/api/v1/posts/:postId	Remover um card.

O modelo de conteúdo do card

Um card é criado/atualizado com três campos de alto nível: imageUrls, userContent e cardOverrides.

{
  "imageUrls": ["https://…/photo.jpg"],   // até 5; buscadas e armazenadas para você. ≤10MB cada, JPEG/PNG/WebP/GIF, URL pública direta
  "userContent": {
    "name": "Lenço de seda",                  // título curto (opcional)
    "description": "Seda de amora tingida à mão, 90×90cm.",   // OBRIGATÓRIO
    "price": "$72",                        // texto livre — "$72", "A partir de $50", "₹1.499" (opcional)
    "promoCode": "SAVE15",                 // código promocional / referral / desconto (opcional)
    "category": "accessories",             // uma das categorias abaixo (opcional)
    "links": ["https://…"],                // links extras exibidos no card (opcional)
    "contacts": [{ "type": "whatsapp", "value": "+15551234567" }]   // opcional
  },
  "cardOverrides": {                       // como o card se comporta (opcional; omitir para herdar os defaults da página)
    "clickAction": "open_detail",          // "open_detail" | "trigger_cta"
    "ctaType": "link",                     // "message" | "link" | "lead_collection"
    "ctaUrl": "https://shop…/scarf",       // OBRIGATÓRIO quando ctaType = "link"
    "ctaLabel": "Comprar agora"                  // texto do botão
  }
}

description é o único campo obrigatório. Todo o resto é opcional; omitir cardOverrides herda os defaults de toda a página do proprietário.

Categorias: clothing, jewellery, accessories, home_decor, beauty, food_beverage, art, stationery, plants, fitness, travel, real_estate, services, pets, kids_baby, books_media, crafts, other.

Tipos de contato: phone, email, whatsapp, telegram, other.

Como um card se comporta — duas decisões

1. clickAction — o que tocar no card faz:

• open_detail (padrão) — abre uma visualização completa (todas as fotos, descrição completa, preço, código promocional, botão de CTA). Use quando o comprador precisa de contexto antes de agir.
• trigger_cta — tocar dispara o CTA imediatamente, sem tela de detalhes. Use para itens autoexplicativos onde você quer o mínimo de atrito.

2. ctaType — o que o CTA faz:

• message — abre uma mensagem para o negócio. Um padrão seguro quando não há link de checkout.
• link — abre ctaUrl (uma página Shopify/Etsy, um link de afiliado, uma página de agendamento, um Google Form). Requer ctaUrl. Use quando há um destino dedicado.
• lead_collection — abre um formulário curto na página que captura os dados de contato do visitante e os salva como lead. Use para capturar pessoas que não estão prontas para comprar (listas de espera, listas de vendas, consultas de coaching). Os campos coletados são definidos em toda a página via catalogCard.leadCollection no endpoint de configurações da página (veja abaixo) — eles se aplicam a todos os cards, não por card.

Defina ctaLabel para corresponder à ação: "Comprar agora", "Pedir agora", "Baixar o lookbook", "Reserve o seu", "Seja notificado".

Configurações da página

Leia e altere a configuração geral da página.

Método	Caminho	Propósito
GET	/api/v1/storefront	Obter as configurações atuais da página.
PATCH	/api/v1/storefront	Alterar configurações. Envie apenas os campos que deseja alterar — eles são mesclados na configuração atual.

Campos editáveis:

{
  "mode": "links_and_catalog",   // "links_only" | "catalog_only" | "links_and_catalog"
  "about": "Cerâmica artesanal do meu estúdio em Lisboa.",  // tagline curta da página (≤280 caracteres)
  "mainCta": {                    // botão herói no topo da página
    "enabled": true,
    "label": "Agende uma chamada",
    "url": "https://cal.com/me"   // obrigatório quando habilitado
  },
  "catalogCard": {                // defaults de TODA A PÁGINA para cada card
    "showCardDetails": true,
    "clickAction": "open_detail", // "open_detail" | "trigger_cta"
    "ctaType": "message",         // "message" | "link" | "lead_collection"
    "ctaUrl": "https://…",        // obrigatório quando ctaType = "link"
    "ctaLabel": "Pedir agora",
    "leadCollection": { "phone": true, "email": true, "instagram": false, "message": true }
  },
  "theme": {
    "useCustomTheme": true,       // DEVE ser true para que preset/brandColor tenham efeito
    "preset": "professional",     // "calm" | "professional" | "playful" | "dark"
    "brandColor": "#d7494c"       // hex de 6 dígitos
  }
}

• Atualizações parciais são mescladas. PATCH {"theme":{"useCustomTheme":true,"brandColor":"#000000"}} altera apenas o tema; modo, cards, etc. permanecem como estavam.
• Guarda do tema: preset/brandColor são ignorados a menos que useCustomTheme seja true — envie-o na mesma requisição.
• catalogCard é o padrão para todos os cards. O próprio cardOverrides do card (acima) prevalece sobre estes. Altere estes para reestilizar todos os cards de uma vez.
• leadCollection define quais campos o formulário de lead de toda a página coleta (não há escolha de campo por card).
• Combinações inválidas são rejeitadas com 400 INVALID_STOREFRONT_CONFIG (ex.: ctaType:"link" sem ctaUrl).

Receitas de casos de uso

Produto de afiliado/influenciador com código promocional → link externo

{
  "imageUrls": ["https://example.com/serum.jpg"],
  "userContent": { "name": "Soro de vitamina C", "description": "Meu soro de brilho diário — 15% de desconto com meu código.", "price": "$28", "promoCode": "GLOW15", "category": "beauty" },
  "cardOverrides": { "clickAction": "trigger_cta", "ctaType": "link", "ctaUrl": "https://brand.com/serum?ref=me", "ctaLabel": "Compre com meu código" }
}

Produto de boutique vendido através de sua própria loja

{
  "imageUrls": ["https://example.com/scarf.jpg"],
  "userContent": { "name": "Lenço de seda", "description": "Seda de amora tingida à mão, 90×90cm.", "price": "$72", "category": "accessories" },
  "cardOverrides": { "clickAction": "open_detail", "ctaType": "link", "ctaUrl": "https://myshop.com/scarf", "ctaLabel": "Comprar agora" }
}

Coach / serviço — capture um lead em vez de vender diretamente

{
  "imageUrls": ["https://example.com/program.jpg"],
  "userContent": { "name": "Coaching 1:1", "description": "Programa de 6 semanas para conseguir seus primeiros 5 clientes.", "price": "A partir de $400", "category": "services" },
  "cardOverrides": { "clickAction": "trigger_cta", "ctaType": "lead_collection", "ctaLabel": "Inscreva-se agora" }
}

Respostas e erros

Sucesso: { "ok": true, "data": { … } }. Erro: { "ok": false, "error": { "code": "…", "message": "…" } }.

• 401 NO_API_TOKEN / INVALID_API_TOKEN — chave ausente ou revogada. Peça ao usuário uma chave válida.
• 403 PLAN_REQUIRED — a conta não é Pro.
• 422 INVALID_IMAGE — uma URL de imagem não pôde ser buscada, era do tipo/tamanho errado, redirecionou ou resolveu para um endereço não público. Use uma URL de imagem https direta e pública.
• 429 RATE_LIMITED — mais de 60 requisições por minuto. Reduza a velocidade e tente novamente.

Orientações

• Confirme com o usuário antes de excluir cards.
• Defina price e promoCode sempre que tiver — eles são exibidos no card e na visualização de detalhes e são centrais para casos de uso de afiliados e vendas.
• Ao criar em lote, fique abaixo de 60 requisições por minuto.
• Cards são publicados na página imediatamente.
• Você pode gerenciar cards e configurações da página (modo, sobre, CTA herói, defaults de cards, tema). Para links, ícones sociais e detalhes do perfil (nome, avatar, URL da página), informe ao usuário para usar o painel do Keepp.

Mais contexto

Os guias de instruções do Keepp explicam uma página Keepp em profundidade:

• Escolhendo seu modo de layout: https://keepp.link/blog/how-to/05-choosing-your-storefront-mode
• Como os cards de produto se parecem e se comportam: https://keepp.link/blog/how-to/06-configuring-how-product-cards-look-and-behave
• CTAs por post e links personalizados: https://keepp.link/blog/how-to/07-setting-per-post-ctas-and-custom-links