thinslatelabs/keepp-skill

Gérer une page Keepp

Ce qu'est Keepp

Keepp transforme le lien bio d'un créateur ou d'une petite entreprise en une page : une collection partageable de fiches « produits » et de liens, conçue pour transformer les abonnés en acheteurs et en prospects. Il est utilisé par les vendeurs, affiliés, coachs, créateurs de cours et créateurs de lien bio sur Instagram, YouTube, TikTok, Pinterest et X.

Une page Keepp se compose de :

• Profil — avatar, nom d'affichage, courte bio
• Icônes sociales — liens vers les comptes sociaux du propriétaire
• Blocs de liens — boutons vers un site web, une page de réservation, WhatsApp, etc. (ainsi que des en-têtes de section)
• Fiches catalogue — les fiches produits achetables (photo, prix, code promo, appel à l'action)
• Mode — links only (liens uniquement), catalog only (catalogue uniquement) ou links and catalog (liens et catalogue)

Ce que contrôle cette API

Cette API gère deux choses :

1. Fiches catalogue (posts) — créer, lister, mettre à jour et supprimer les fiches produits du catalogue du propriétaire.
2. Paramètres de la page — le mode de mise en page, le texte « À propos », le CTA principal, les valeurs par défaut des fiches catalogue et le thème (voir « Paramètres de la page » ci-dessous).

Vous NE POUVEZ PAS modifier ces éléments via cette API : icônes sociales, blocs de liens et détails du profil (nom d'affichage, avatar, URL de la page). Ceux-ci sont définis par le propriétaire dans le tableau de bord Keepp — si un utilisateur les réclame, orientez-le vers le tableau de bord Keepp.

Authentification

Chaque requête nécessite la clé API du propriétaire sous forme de jeton Bearer :

Authorization: Bearer keepp_live_…

URL de base : https://api.keepp.link. Les clés sont générées par un compte Pro sous AI Agent dans le tableau de bord. Si vous n'en avez pas, demandez-la à l'utilisateur.

Endpoints

Méthode	Chemin	Objectif
GET	/api/v1/posts?cursor=	Lister les fiches du catalogue (paginé).
POST	/api/v1/posts	Créer une fiche.
GET	/api/v1/posts/:postId	Récupérer une fiche.
PATCH	/api/v1/posts/:postId	Mettre à jour une fiche.
DELETE	/api/v1/posts/:postId	Supprimer une fiche.

Le modèle de contenu d'une fiche

Une fiche est créée/mise à jour avec trois champs de premier niveau : imageUrls, userContent et cardOverrides.

{
  "imageUrls": ["https://…/photo.jpg"],   // jusqu'à 5 ; récupérées & stockées pour vous. ≤10 Mo chacune, JPEG/PNG/WebP/GIF, URL publique directe
  "userContent": {
    "name": "Écharpe en soie",                  // titre court (optionnel)
    "description": "Soie de mûrier teinte à la main, 90×90 cm.",   // OBLIGATOIRE
    "price": "72 €",                        // texte libre — "72 €", "À partir de 50 €", "1 499 ₹" (optionnel)
    "promoCode": "SAVE15",                 // code promo / parrainage / réduction (optionnel)
    "category": "accessories",             // l'une des catégories ci-dessous (optionnel)
    "links": ["https://…"],                // liens supplémentaires affichés sur la fiche (optionnel)
    "contacts": [{ "type": "whatsapp", "value": "+33123456789" }]   // optionnel
  },
  "cardOverrides": {                       // comportement de la fiche (optionnel ; omettre pour hériter des valeurs par défaut de la page)
    "clickAction": "open_detail",          // "open_detail" | "trigger_cta"
    "ctaType": "link",                     // "message" | "link" | "lead_collection"
    "ctaUrl": "https://shop…/scarf",       // OBLIGATOIRE quand ctaType = "link"
    "ctaLabel": "Acheter maintenant"        // texte du bouton
  }
}

description est le seul champ obligatoire. Tout le reste est optionnel ; omettre cardOverrides hérite des valeurs par défaut de la page du propriétaire.

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

Types de contact : phone, email, whatsapp, telegram, other.

Comportement d'une fiche — deux décisions

1. clickAction — ce qui se passe en tapant sur la fiche :

• open_detail (par défaut) — ouvre une vue détaillée complète (toutes les photos, description complète, prix, code promo, bouton CTA). Utilisez-la lorsque l'acheteur a besoin de contexte avant d'agir.
• trigger_cta — le tap déclenche immédiatement le CTA, sans écran de détail. Utilisez-la pour les articles explicites où vous voulez le moins de friction.

2. ctaType — ce que fait le CTA :

• message — ouvre un message vers l'entreprise. Une valeur par défaut sûre lorsqu'il n'y a pas de lien de paiement.
• link — ouvre ctaUrl (une page Shopify/Etsy, un lien d'affiliation, une page de réservation, un formulaire Google). Nécessite ctaUrl. Utilisez-la lorsqu'il y a une destination dédiée.
• lead_collection — ouvre un court formulaire sur la page qui capture les coordonnées du visiteur et les enregistre comme prospect. Utilisez-la pour capturer les personnes qui ne sont pas prêtes à acheter (listes d'attente, listes de vente, demandes de coaching). Les champs collectés sont définis au niveau de la page via catalogCard.leadCollection sur l'endpoint des paramètres de page (voir ci-dessous) — ils s'appliquent à toutes les fiches, pas par fiche.

Définissez ctaLabel pour correspondre à l'action : "Acheter maintenant", "Commander maintenant", "Obtenir le lookbook", "Réservez le vôtre", "Soyez informé".

Paramètres de la page

Lire et modifier la configuration globale de la page.

Méthode	Chemin	Objectif
GET	/api/v1/storefront	Obtenir les paramètres actuels de la page.
PATCH	/api/v1/storefront	Modifier les paramètres. Envoyez uniquement les champs que vous souhaitez modifier — ils fusionnent avec la configuration actuelle.

Champs modifiables :

{
  "mode": "links_and_catalog",   // "links_only" | "catalog_only" | "links_and_catalog"
  "about": "Céramiques artisanales de mon atelier à Lisbonne.",  // courte description de la page (≤280 caractères)
  "mainCta": {                    // bouton héros en haut de la page
    "enabled": true,
    "label": "Réserver un appel",
    "url": "https://cal.com/me"   // obligatoire quand enabled
  },
  "catalogCard": {                // VALEURS PAR DÉFAUT pour chaque fiche
    "showCardDetails": true,
    "clickAction": "open_detail", // "open_detail" | "trigger_cta"
    "ctaType": "message",         // "message" | "link" | "lead_collection"
    "ctaUrl": "https://…",        // obligatoire quand ctaType = "link"
    "ctaLabel": "Commander maintenant",
    "leadCollection": { "phone": true, "email": true, "instagram": false, "message": true }
  },
  "theme": {
    "useCustomTheme": true,       // DOIT être true pour que preset/brandColor prennent effet
    "preset": "professional",     // "calm" | "professional" | "playful" | "dark"
    "brandColor": "#d7494c"       // hexadécimal à 6 chiffres
  }
}

• Les mises à jour partielles fusionnent. PATCH {"theme":{"useCustomTheme":true,"brandColor":"#000000"}} modifie uniquement le thème ; le mode, les fiches, etc. restent inchangés.
• Protection du thème : preset/brandColor sont ignorés sauf si useCustomTheme est true — envoyez-le dans la même requête.
• catalogCard est la valeur par défaut pour toutes les fiches. Les cardOverrides propres à une fiche (ci-dessus) priment sur celle-ci. Modifiez-les pour restyler toutes les fiches à la fois.
• leadCollection définit les champs que collecte le formulaire de prospects à l'échelle de la page (il n'y a pas de choix de champ par fiche).
• Les combinaisons invalides sont rejetées avec 400 INVALID_STOREFRONT_CONFIG (par exemple ctaType:"link" sans ctaUrl).

Recettes d'usage

Produit d'affiliation / influenceur avec un code promo → lien externe

{
  "imageUrls": ["https://example.com/serum.jpg"],
  "userContent": { "name": "Sérum à la vitamine C", "description": "Mon sérum quotidien éclat — 15% de réduction avec mon code.", "price": "28 €", "promoCode": "GLOW15", "category": "beauty" },
  "cardOverrides": { "clickAction": "trigger_cta", "ctaType": "link", "ctaUrl": "https://brand.com/serum?ref=me", "ctaLabel": "Acheter avec mon code" }
}

Produit de boutique vendu via votre propre boutique

{
  "imageUrls": ["https://example.com/scarf.jpg"],
  "userContent": { "name": "Écharpe en soie", "description": "Soie de mûrier teinte à la main, 90×90 cm.", "price": "72 €", "category": "accessories" },
  "cardOverrides": { "clickAction": "open_detail", "ctaType": "link", "ctaUrl": "https://maboutique.com/scarf", "ctaLabel": "Acheter maintenant" }
}

Coach / service — capturer un prospect au lieu de vendre directement

{
  "imageUrls": ["https://example.com/program.jpg"],
  "userContent": { "name": "Coaching 1:1", "description": "Programme de 6 semaines pour décrocher vos 5 premiers clients.", "price": "À partir de 400 €", "category": "services" },
  "cardOverrides": { "clickAction": "trigger_cta", "ctaType": "lead_collection", "ctaLabel": "Postuler maintenant" }
}

Réponses et erreurs

Succès : { "ok": true, "data": { … } }. Erreur : { "ok": false, "error": { "code": "…", "message": "…" } }.

• 401 NO_API_TOKEN / INVALID_API_TOKEN — clé manquante ou révoquée. Demandez à l'utilisateur une clé valide.
• 403 PLAN_REQUIRED — le compte n'est pas en Pro.
• 422 INVALID_IMAGE — une URL d'image n'a pas pu être récupérée, était du mauvais type/taille, a redirigé ou a résolu une adresse non publique. Utilisez une URL d'image https directe et publique.
• 429 RATE_LIMITED — plus de 60 requêtes par minute. Ralentissez et réessayez.

Recommandations

• Confirmez avec l'utilisateur avant de supprimer des fiches.
• Définissez price et promoCode chaque fois que vous les avez — ils s'affichent sur la fiche et dans la vue détaillée et sont centraux pour les cas d'usage d'affiliation et de vente.
• Lors de la création en masse, restez en dessous de 60 requêtes par minute.
• Les fiches sont publiées sur la page immédiatement.
• Vous pouvez gérer les fiches et les paramètres de la page (mode, à propos, CTA héros, valeurs par défaut des fiches, thème). Pour les liens, icônes sociales et détails du profil (nom, avatar, URL de la page), dites à l'utilisateur d'utiliser le tableau de bord Keepp.

Plus de contexte

Les guides pratiques de Keepp expliquent une page Keepp en profondeur :

• Choisir son mode de mise en page : https://keepp.link/blog/how-to/05-choosing-your-storefront-mode
• Aspect et comportement des fiches produits : https://keepp.link/blog/how-to/06-configuring-how-product-cards-look-and-behave
• CTA par publication et liens personnalisés : https://keepp.link/blog/how-to/07-setting-per-post-ctas-and-custom-links