Findy
Findy

TROUVEZ. VENDEZ.

Documentation complète

Intégrer, personnaliser et facturer Findy

Cette page rassemble les informations nécessaires pour installer le widget, connecter le catalogue, régler le style, comprendre les tarifs et expliquer la consommation des requêtes à un client ou à une équipe technique.

Produit

Vue d'ensemble

Recherche

Findy affiche une barre ou se branche sur un champ existant, puis ouvre une expérience de recherche produits connectée au catalogue marchand.

Style

Le design se règle dans le dashboard: templates, couleurs, typographie, logo, disposition, fenêtre et comportements panier.

Tarifs

Chaque plan inclut un volume mensuel de requêtes. Les plans payants peuvent continuer au-delà avec un tarif pay-as-you-go.

Usage

Les recherches, clics et ajouts panier sont suivis dans les analytics et alimentent le compteur mensuel de consommation.

Source de vérité

Les snippets de cette page expliquent comment brancher Findy. Les couleurs, templates, limites produits et options visuelles viennent ensuite de la configuration sauvegardée dans le dashboard Findy.

Snippet

Installation rapide

Poser le conteneur à l'endroit où la recherche doit apparaître, charger le script avant</body>, puis appeler Findy.init. Remplacer VOTRE_CLE_WIDGET_FINDY par la clé widget du client.

<div id="findy-search"></div>

<script src="https://findysearch.com/widget-v2/findy-widget.js"></script>
<script>
  Findy.init({
    apiKey: 'VOTRE_CLE_WIDGET_FINDY',
    containerId: 'findy-search',
    apiBaseUrl: 'https://findysearch.com'
  });
</script>
  • Récupérer l'URL publique Findy, généralement https://findysearch.com.
  • Créer ou récupérer la clé widget du client dans le dashboard.
  • Vérifier que le catalogue est connecté ou en cours de synchronisation.
  • Tester desktop, mobile, clic produit, ajout panier et remontée analytics.
  • Ne jamais exposer de clés WooCommerce, PrestaShop ou API serveur dans le code du site marchand.

Findy.init

Options JavaScript

OptionTypeRôle
apiKeystring, requisClé widget publique qui identifie l'organisation Findy.
langstringLangue de l'interface et des résultats : fr, en, es, it, de. Valeur 'auto' pour la lire depuis l'attribut lang de la page. Sans cette option, le widget reste en français.
translationsobjetSurcharge de libellés, par exemple { 'product.addToCart': 'Acheter' }. Les valeurs sont échappées avant insertion.
containerIdstringID du conteneur où Findy rend sa barre de recherche.
triggerSelectorstringSélecteur CSS d'un champ ou bouton existant qui ouvre Findy.
mobileTriggerSelectorstringSélecteur spécifique mobile si le thème utilise un DOM différent.
triggerModesearchbar ou selectorForce le comportement d'ouverture souhaité.
apiBaseUrlstringURL de l'instance Findy à appeler.
logoUrl, logoTextstringBranding optionnel si la configuration serveur ne définit pas déjà le logo.
popularSearchesstring[]Suggestions de secours côté client.
adaptivebooleanLaisse Findy adapter le mode d'affichage selon le contexte.
closeOnClickOutside, closeOnEscapebooleanContrôle de fermeture de l'overlay.
priceModeauto, net ou grossSuit le sélecteur HT/TTC du site ou propose un mode local; une règle fixe définie dans Findy reste prioritaire.
priceModeDetectorfunctionDétection personnalisée du mode HT/TTC pour une plateforme headless ou propriétaire.
onContextChangefunction(context)Callback appelé en mode adaptive quand le contexte viewport change.
onAddToCartasync function(params)Intégration panier custom côté site marchand.

Synchroniser le choix HT / TTC du site

En mode auto (valeur par défaut), Findy détecte le réglage natif PrestaShop. Sur toute autre plateforme, placezdata-findy-price-mode="net" oudata-findy-price-mode="gross" sur la balisehtml. Après un changement sans rechargement, appelezFindy.setPriceMode('net') ou émettez l’événementfindy:price-mode-change. Les résultats et filtres prix sont alors rechargés dans la bonne base.

Cette API constitue le bridge universel pour WooCommerce, Shopify, Magento, BigCommerce, Shopware, un site headless ou un switcher propriétaire. Findy ne cherche pas le bouton HT/TTC dans le DOM : le site lui transmet son état. UtilisezFindy.getPriceModeDiagnostics() pour connaître le mode, la source détectée et savoir si le fallback est utilisé.

Pendant l’installation, démarrez d’abord une fenêtre de test depuis l’onboarding ou les paramètres. Rechargez ensuite le site, ouvrez-le une fois dans chaque mode, puis confirmez explicitement le contrôle avec un compte administrateur. La fenêtre expire après 30 minutes et chaque nouveau test crée une révision différente. Une clé widget publique ne peut pas valider seule cette étape.

Exemple avec événements publics

Les événements de lecture se branchent avec Findy.on aprèsFindy.init. Les callbacks d'analyticsonSearch et onProductClick ne font pas partie du contrat public actuel.

<script>
  Findy.on('open', function() {
    console.log('Findy opened');
  });

  Findy.on('searchStart', function(event) {
    console.log('Findy search:', event.query);
  });

  Findy.on('searchComplete', function(event) {
    console.log('Findy results:', event.total);
  });

  Findy.on('addToCartSuccess', function(event) {
    console.log('Findy add to cart:', event.productId);
  });
</script>

Design

Style et personnalisation

Le style du widget est configuré côté Findy et livré au widget via l'API de configuration. Le site marchand garde uniquement le snippet d'intégration; les équipes peuvent donc ajuster le design sans redéployer le thème.

RéglageValeursImpact
TemplateMINIMAL, ELEGANT, BOLD, ECOMMERCEBase visuelle du widget.
CouleursprimaryColor, buttonColor, buttonTextColor, iconColor, badgeColor, availabilityLabelColor, inStockLabelColorCouleurs principales, boutons, icônes d'action, promotions et délais de disponibilité.
TypographiefontFamily, fontBold, fontItalic, priceFontBold, priceFontItalic, buttonFontBold, buttonFontItalic, titleFontSize, refFontSize, priceFromFontSize, priceValueFontSize, priceTaxFontSizePolice, styles gras/italique par zone et tailles indépendantes pour « À partir de », la valeur du prix et la mention fiscale.
RayonborderRadius de 0 à 32Arrondi des champs, cartes et boutons.
LogologoUrlLogo client dans l'overlay de résultats.
DispositionlayoutMode: grid ou sliderAffichage produits en grille ou carrousel.
FenêtrewindowMode: fullscreen, compact, megamenuComportement de l'overlay sur desktop.
Volume affiché10, 20, 50, 100 ou scroll infiniNombre de produits demandés par page.
GrillegridColumns: auto ou 2 à 8Contrôle du nombre de colonnes desktop.
Design par élémentdesign (JSON v1), mode Avancé de l'onglet DesignRéglages par élément (Offres & sélections, grille, carte, image, badges, textes, boutons), par appareil et au survol, et ordre des blocs de la carte. Passe devant les réglages ci-dessus.
CommerceaddToCartBehavior, showQuantitySelector, showVariantSelector, uniformProductButtonsAprès un ajout réussi : REDIRECT_TO_CART, SHOW_POPUP ou CONTINUE_SHOPPING. uniformProductButtons applique les couleurs configurées à toutes les actions produit (désactivé par défaut). Les anciens champs showCartPopup et closeOnAddToCart restent compatibles mais sont dépréciés.

Templates disponibles

Minimal pour un rendu sobre, Elegant pour une boutique premium, Bold pour un accent plus marqué, E-commerce pour un rendu marchand plus direct.

Comportement mobile

Sur mobile, Findy force une expérience plein écran, grille, scroll infini et filtre prix afin de préserver une recherche lisible et stable.

Conseil de recette design

Après un changement de style, tester au moins une recherche avec produits en promotion, produits sans stock, variantes, images longues et titres produits très longs.

Thème de la boutique

Le widget isole ses styles de ceux du thème (vérifié sur Dawn, Horizon, Debut, Storefront, Astra et Classic), interligne compris. Ne pas surcharger les classes findy-… depuis le thème : ces règles ne sont pas garanties d'une version à l'autre. Les réglages passent par l'onglet Design.

Plans

Tarifs publics et requêtes incluses

PlanAbonnementRequêtes incluses / moisHors forfaitAssistant IAUsage conseillé
Free0 €1 0000 €Non inclus — disponible dès StarterPour découvrir Findy gratuitement
Starter29 €/mois10 0000,0050 €/requêteInclus — chaque conversation vaut 10 requêtesIdéal pour les petites boutiques qui démarrent
Pro99 €/mois150 0000,0040 €/requêteInclus — 250 conversations/mois, puis 10 requêtes par conversationPour les boutiques en croissance
Business199 €/mois400 0000,0030 €/requêteInclus — 500 conversations/mois, puis 10 requêtes par conversationPour les grandes boutiques à fort trafic

Offres commerciales

Une offre commerciale acceptée peut définir un volume inclus et un tarif pay-as-you-go spécifiques. Dans ce cas, l'offre prévaut sur les valeurs standards du plan public.

Usage

Consommation des requêtes

Le compteur Findy est conçu pour refléter les interactions qui ont une valeur produit: recherche, clic et ajout panier. Les appels techniques nécessaires au chargement du widget ne sont pas tous facturés, mais certains vérifient le quota pour éviter de servir une expérience inactive.

ActionConsomme ?Détail
Recherche produitOui1 requête par appel à /api/widget/search, y compris pagination, filtres et scroll infini.
Clic produitOui1 requête quand l'événement CLICK est traité et que le quota est disponible. Au-delà de 10 clics d'un même visiteur sur un même produit dans la journée, les suivants ne sont ni enregistrés ni facturés : ils ne relèvent plus d'un comportement humain et fausseraient le classement.
Ajout panierOui1 requête quand l'événement ADD_TO_CART est traité. Selon le bouton et le template, un CLICK produit peut aussi être enregistré avant l'ajout panier. Un même appel au serveur facture au plus 3 clics et ajouts panier : le widget envoie chaque clic dès qu'il a lieu, et les événements au-delà restent comptés dans les statistiques sans être facturés.
Conversation avec l'assistant IAOui, au-delà de l'inclus10 requêtes par conversation, débitées à la première réponse ; les messages suivants de la même conversation ne coûtent rien. Free n'ouvre pas l'assistant ; Starter l'ouvre sans volume inclus, chaque conversation est décomptée du quota ; Pro inclut 250 conversations par période de facturation et Business 500, hors quota. Une conversation ouverte sans réponse n'est jamais comptée. Un plafond mensuel de conversations, réglable dans le dashboard, met l'assistant en pause au-delà.
Configuration widgetNonCharge le design et les réglages serveur. Ne décrémente pas le quota.
Trending, recherches populaires, catégories, collectionsNon directVérifie le quota pour éviter de servir le widget sans crédit, mais ne décrémente pas directement.
OPTIONS CORSNonPréflight navigateur ignoré par la facturation et par le quota fonctionnel.

Ordre de consommation

Findy consomme d'abord les requêtes bonus, puis les requêtes incluses du plan. Quand les deux compteurs sont vides, un plan payant actif bascule en hors forfait.

Hors forfait

Pour un plan payant actif, chaque requête hors forfait envoie un événement au Stripe Billing Meter afin d'être ajoutée à la facture.

Blocage

Si aucun quota n'est disponible et qu'aucun hors forfait ne peut être appliqué, le widget renvoie un état bloqué avec le message "Plus de requêtes disponibles".

Cas du bouton panier

Dans les templates où le bouton panier est rendu dans une carte produit cliquable, le clic peut produire deux événements facturables: CLICK puisADD_TO_CART. Une sélection de variante validée dans la fenêtre de variante ne déclenche que l'ajout panier.

Prix

Calcul de la facture

Le prix mensuel est la somme de l'abonnement et de la consommation hors forfait. Les requêtes incluses et bonus déjà disponibles ne génèrent pas de coût supplémentaire.

requêtes_disponibles = requêtes_plan_restantes + requêtes_bonus
requêtes_hors_forfait = overageRequestsThisPeriod
coût_hors_forfait = requêtes_hors_forfait x tarif_pay_as_you_go
total_mensuel = abonnement_mensuel + coût_hors_forfait
PlanScénarioCalcul
Free1 200 interactions facturablesLes 1 000 premières passent, puis le widget est bloqué. Pas de hors-forfait.
Starter12 500 interactions facturables29 € + 2 500 x 0,0050 € = 41,50 €.
Pro180 000 interactions facturables99 € + 30 000 x 0,0040 € = 219 €.
Business450 000 interactions facturables199 € + 50 000 x 0,0030 € = 349 €.
Pro + assistant IA350 conversationsLes 250 premières sont incluses ; les 100 suivantes valent 100 x 10 = 1 000 requêtes, prises sur le quota du plan (0 € tant que les 150 000 requêtes ne sont pas dépassées, sinon 0,0040 € l'une).
  • Le compteur mensuel d'usage s'appuie sur le compteur interne et les événements du mois en cours.
  • Les requêtes bonus sont séparées du quota du plan et consommées en priorité.
  • Les dépassements sont comptés dans overageRequestsThisPeriod.
  • La date de reset affichée vient de la période d'abonnement Stripe.
  • En cas de paiement suspendu sur un plan payant, l'accès peut être bloqué même si des compteurs existent.

CMS

Installation WooCommerce

Accès catalogue

Dans WordPress, aller dansWooCommerce > Réglages > Avancé > REST API, créer une clé dédiée Findy avec l’accès Lecture uniquement, puis copier leConsumer Key et le Consumer Secret. Dans Findy, renseigner l'URL de la boutique, tester la connexion, puis synchroniser.

Recherche existante du thème

Si le client veut conserver le champ de recherche du thème WooCommerce, utiliser un sélecteur CSS adapté au DOM desktop et mobile.

<script src="https://findysearch.com/widget-v2/findy-widget.js"></script>
<script>
  Findy.init({
    apiKey: 'VOTRE_CLE_WIDGET_FINDY',
    apiBaseUrl: 'https://findysearch.com',
    triggerSelector: '.woocommerce-product-search, input[type="search"]',
    mobileTriggerSelector: '.mobile-search input[type="search"]'
  });
</script>

Panier WooCommerce

  • Tester l'ajout panier sur un produit simple.
  • Tester un produit variable avec tailles ou couleurs.
  • Vérifier la mise à jour du mini-panier ou du compteur panier.
  • Tester les boutiques en sous-répertoire, multisite ou contexte multilingue.
  • Utiliser onAddToCart si le thème est fortement personnalisé ou headless.

CMS

Installation PrestaShop

Accès catalogue

Dans PrestaShop, aller dans Paramètres avancés > Webservice, activer le Webservice et créer une clé Findy avec des permissions de lecture.

BlocPermissionsNote
Catalogueproducts, categories, images, stock_availablesBase minimale pour indexer les produits.
DéclinaisonscombinationsRecherche par référence de déclinaison.
Fonctionnalitésspecific_prices, product_features, product_feature_values, tagsPrix spécifiques, filtres et enrichissement.
  • Ne pas accorder de droits d'écriture.
  • Ne pas activer orders, customers ou d'autres ressources sensibles si elles ne sont pas nécessaires.
  • Renseigner le taux de TVA uniquement si les prix PrestaShop remontent hors taxes. Exemple:20.

Recherche existante du thème

<script src="https://findysearch.com/widget-v2/findy-widget.js"></script>
<script>
  Findy.init({
    apiKey: 'VOTRE_CLE_WIDGET_FINDY',
    apiBaseUrl: 'https://findysearch.com',
    triggerSelector: '#search_widget form, #search_widget input[type="text"]',
    mobileTriggerSelector: '.header-mobile #search_widget input'
  });
</script>

Panier PrestaShop

Findy reconnaît les URL d'ajout panier PrestaShop générées lors de la synchronisation. Pour les produits à déclinaisons, le sélecteur transmet automatiquement l'identifiant natifid_product_attribute. La clé Webservice doit autoriser la lecture des combinaisons, groupes d'options et valeurs d'options.

CMS

Installation Shopify

En attendant l'application Shopify Findy, l'intégration passe par le canal de vente gratuit Headless de Shopify : Findy lit le catalogue côté serveur via l'API Storefront GraphQL avec un jeton d'accès privé, le widget est collé dans le thème de la boutique en ligne et l'ajout panier utilise les API panier de Shopify. L'abonnement Findy reste facturé par Findy.

Intégration transitoire

Pas encore d'extension de thème ni d'installation en un clic : le snippet est posé à la main dans un thème Liquid et le catalogue est resynchronisé toutes les heures. Une boutique Shopify entièrement headless (Hydrogen ou autre frontend) relève de l'installation custom.

Accès catalogue

Installer le canal Headless (édité par Shopify, gratuit) depuis le Shopify App Store avec un compte qui a la permission Applications et canaux de vente, cliquer sur Create storefront, vérifier que les trois permissions de lecture ci-dessous sont cochées dans Storefront API permissions, puis copier le Private access token. Avant de décocher quoi que ce soit : ces permissions sont communes à tous les storefronts Headless de la boutique. Si le canal ne sert qu'à Findy, décocher toutes les autres. S'il sert déjà à un autre site du marchand, ne rien retirer (cet autre site cesserait de fonctionner) : le jeton Findy hérite alors aussi de ses permissions supplémentaires.

Permission Storefront APIUsageNote
unauthenticated_read_product_listingsProduits, variantes et collectionsBase minimale pour indexer le catalogue.
unauthenticated_read_product_tagsTags produitsEnrichissement de la recherche.
unauthenticated_read_product_inventoryQuantités en stockStock des produits et des variantes.
  • Rendre les produits disponibles sur le storefront Headless et sur la Boutique en ligne : l'API Storefront ne renvoie que les produits publiés sur Headless, et le panier du thème exige la Boutique en ligne. Publié seulement sur Headless, un produit apparaît dans Findy mais son ajout au panier est refusé (« Ajout non confirmé ») ; publié seulement sur la Boutique en ligne, il n'est jamais trouvé par Findy.
  • Findy n'utilise jamais le jeton public du storefront.

Jeton privé = secret serveur

Le jeton privé se colle uniquement dans Findy. Ne jamais le placer dans le thème, dans le snippet du widget ou dans un outil d'injection de scripts.

Connexion dans Findy

Choisir Shopify et renseigner l'adresse https://boutique-client.myshopify.com (visible dans Paramètres > Domaines de l'admin Shopify) : un domaine personnalisé est refusé, une URL admin.shopify.com/store/… est convertie automatiquement. Coller le Jeton d’accès privé Storefront API et laisser vide le chemin de la page panier : sur la boutique, le widget ouvre alors le panier de la langue courante (/cart, /fr/cart… d'après Shopify.routes.root), sans tenir compte des liens du thème. Un autre chemin saisi est utilisé tel quel. Tester la connexion puis synchroniser. La loupe de détection reconnaît une adresse .myshopify.com, une URL d'admin Shopify et en général une boutique sur son propre domaine ; si elle propose une autre plateforme, choisir alors Shopify à la main.

  • Findy lit les produits, variantes, images, prix, prix barrés, disponibilité, stock, type de produit, collections, tags, marque (vendor), SKU et codes-barres.
  • Les cartes-cadeaux sont exclues ; les produits brouillons, archivés ou non publiés sur Headless ne sont pas renvoyés par Shopify.
  • La disponibilité suit l'état « disponible à la vente » de Shopify : un produit sans suivi de stock reste disponible.
  • Boutique multilingue : les URL produits reprennent le préfixe de langue et le handle traduit.
  • Comparer ensuite quelques prix, variantes et prix barrés avec les fiches Shopify.

Widget dans le thème

Dans Boutique en ligne > Thèmes > Personnaliser, ajouter une section Liquid personnalisé dans le groupe en-tête ou pied de page, pour qu'elle s'affiche sur toutes les pages, puis coller le snippet. Autre option : Modifier le code > layout/theme.liquid, avec le script avant </body>. Modifier le code retire le thème des mises à jour automatiques : préférer le bloc Liquid personnalisé et tester d'abord sur une copie non publiée du thème.

<div id="findy-search"></div>

<script src="https://findysearch.com/widget-v2/findy-widget.js"></script>
<script>
  Findy.init({
    apiKey: 'VOTRE_CLE_WIDGET_FINDY',
    containerId: 'findy-search',
    apiBaseUrl: 'https://findysearch.com'
  });
</script>

Recherche existante du thème

Exemple pour le thème Dawn, à adapter au DOM réel du thème. Vérifier que la recherche native ne s'ouvre pas en même temps que Findy.

<script src="https://findysearch.com/widget-v2/findy-widget.js"></script>
<script>
  Findy.init({
    apiKey: 'VOTRE_CLE_WIDGET_FINDY',
    apiBaseUrl: 'https://findysearch.com',
    triggerSelector: '.header__icon--search, predictive-search input[type="search"]'
  });
</script>

Compte collaborateur

Le marchand ouvre Paramètres > Utilisateurs > Sécurité et transmet le code de demande de collaborateur à 4 chiffres. Le prestataire envoie sa demande depuis son compte partenaire Shopify avec le domaine boutique-client.myshopify.com et ce code, puis le marchand relit les permissions et accepte la demande.

PermissionUsageNote
Applications et canaux de venteInstaller et gérer le canal HeadlessNécessaire pour créer le storefront et lire le jeton privé.
Boutique en ligne > ThèmesAjouter le widget au thèmeDupliquer le thème pour tester sur une copie non publiée.
ProduitsRecette et publication sur les canauxLa lecture suffit si le marchand publie lui-même les produits.
  • Ne jamais demander un rôle administrateur ou toutes les permissions.
  • Le compte du prestataire doit avoir l'authentification en deux étapes activée : sans 2FA, un collaborateur ne peut pas se connecter à la boutique.
  • Ne pas demander l'accès aux commandes, clients ou paiements ; le marchand retire l'accès en fin d'intervention.

Panier Shopify

Findy ajoute la variante au panier dans la boutique, avec la session du visiteur. Il utilise Shopify.actions.updateCart quand les actions standard Shopify sont disponibles : Shopify rafraîchit alors le compteur ou le drawer des thèmes qu'il reconnaît. Sinon, Findy appelle l'API AJAX Cart (/cart/add.js) en suivant window.Shopify.routes.root, puis émet cart:refresh et cart:updated. Un produit à plusieurs variantes passe par le sélecteur de variante ou par la fiche produit.

En secours, onAddToCart remplace complètement ce flux natif, par exemple pour une app de panier tierce. Le panier Shopify attend l'identifiant numérique de variante, pas l'identifiant produit.

<script src="https://findysearch.com/widget-v2/findy-widget.js"></script>
<script>
  Findy.init({
    apiKey: 'VOTRE_CLE_WIDGET_FINDY',
    containerId: 'findy-search',
    apiBaseUrl: 'https://findysearch.com',
    onAddToCart: async function({ variationId, quantity, addToCartUrl }) {
      // Variante choisie dans Findy, sinon variante par défaut du lien panier /cart/<variante>:1
      var cartPath = addToCartUrl ? new URL(addToCartUrl, window.location.href).pathname : '';
      var variantId = Number(variationId || (cartPath.split('/cart/')[1] || '').split(':')[0]);
      if (!variantId) {
        return { success: false };
      }

      var root = (window.Shopify && window.Shopify.routes && window.Shopify.routes.root) || '/';
      var response = await fetch(root + 'cart/add.js', {
        method: 'POST',
        headers: {
          'Content-Type': 'application/json',
          'Accept': 'application/json'
        },
        credentials: 'same-origin',
        body: JSON.stringify({
          items: [{ id: variantId, quantity: quantity || 1 }]
        })
      });

      // Rafraîchir ici le compteur ou le drawer du thème, y compris en cas de 422 :
      // si le stock est insuffisant, Shopify a pu ajouter la quantité disponible.
      return { success: response.ok };
    }
  });
</script>
  • Tester un produit à variante unique et un produit à variantes.
  • Variante épuisée ou quantité supérieure au stock : vérifier le contenu réel du panier, pas seulement le message Findy. Shopify peut ajuster la quantité au stock disponible (avertissement avec Shopify.actions, réponse 422, parfois après un ajout partiel, avec /cart/add.js).
  • Si le compteur ou le drawer ne se met pas à jour, choisir REDIRECT_TO_CART ou brancher onAddToCart.
  • Tester les boutiques multilingues ou multi-marchés (/fr/, /en-us/) et les apps de panier tierces.

Prix HT / TTC

L'API Storefront ne dit pas si les prix incluent les taxes : choisir dans Findy Le prix source est TTC ou Le prix source est HT selon le réglage de taxes de la boutique. Comme pour WooCommerce, l'affichage suit le bridge universel décrit dans les options JavaScript : le thème initialise data-findy-price-mode depuis Liquid, avant le script Findy, et un switcher HT/TTC appelle Findy.setPriceMode('net') ou Findy.setPriceMode('gross'). Vérifier avec Findy.getPriceModeDiagnostics(), puis valider la fenêtre de test dans l'onboarding.

<script>
  document.documentElement.dataset.findyPriceMode = {% if cart.taxes_included %}'gross'{% else %}'net'{% endif %};
</script>
LimiteImpactContournement
Synchronisation horaireUne modification produit, prix ou stock peut mettre jusqu'à une heure à apparaître.Lancer une synchronisation manuelle depuis Findy après un changement important.
Pas d'extension de thèmeTant qu'il n'y a pas d'app Findy, le snippet est lié au thème et disparaît lors d'un changement de thème.Reposer la section Liquid personnalisé sur le nouveau thème avant sa publication.
Boutique protégée par mot de passeLa synchronisation fonctionne, mais le widget et les liens panier restent derrière le mot de passe.Saisir le mot de passe de la boutique dans le navigateur pour la recette.
Canaux de venteSeuls les produits publiés sur Headless sont synchronisés, et seuls ceux publiés sur la Boutique en ligne peuvent être ajoutés au panier.Publier aussi les nouveaux produits sur les deux canaux.
Plus de 25 000 produitsLimite de pagination Shopify : la synchronisation s'arrête avec une erreur, sans supprimer de produits.Contacter l'équipe Findy.
Jeton privéDésinstaller le canal, supprimer le storefront ou supprimer le jeton coupe la synchronisation.Mettre à jour le jeton dans Findy puis relancer une synchronisation.

CMS

Installation Magento

Findy lit le catalogue côté serveur avec l'API REST d'administration de Magento Open Source ou Adobe Commerce 2.4, authentifiée par le jeton d'une intégration Magento. Findy n'installe rien dans Magento : le marchand crée l'intégration et colle le script du widget dans l'en-tête de sa vue magasin.

1. Connecter la boutique

  1. Dans l’admin Magento, ouvrez Système > Extensions > Intégrations, puis « Ajouter une nouvelle intégration » et nommez-la Findy.
  2. Dans l’onglet API, choisissez des ressources personnalisées : Catalogue, Magasins (paramètres et configuration, dont la section Inventaire) et, si elle existe, Inventaire (dont Stock de vente : sans lui, Findy n’indexe pas les quantités en stock). Enregistrez.
  3. Activez l’intégration (Enregistrer, Activer, Autoriser), puis copiez le jeton d’accès (Access Token).
  4. Dans Magasins > Configuration > Services > OAuth > Consumer Settings, passez « Allow OAuth Access Tokens to be used as standalone Bearer tokens » sur Oui (désactivé par défaut depuis Magento 2.4.4).

Dans Findy, choisir Magento, saisir l'URL de base de la vue magasin à indexer (Magasins > Configuration > Général > Web) et coller le jeton, puis tester la connexion et synchroniser. Le jeton se colle uniquement dans Findy, jamais dans l'en-tête de la boutique ni dans le script du widget.

2. Installer le widget

  1. Dans l'admin, ouvrir Contenu > Design > Configuration et modifier la vue magasin (ou le site) concerné.
  2. Dans En-tête HTML > Scripts et feuilles de style, coller le script Findy ci-dessous, puis enregistrer.
  3. Ouvrir Système > Gestion du cache et cliquer sur Vider le stockage du cache (Flush Cache Storage) : sans cela, la vitrine garde l'ancien en-tête. Purger le cache Magento ne vide pas toujours le cache des pages.
  4. Ouvrir une page catalogue de la boutique et vérifier que la recherche s'ouvre.

Recommandé : ouvrir Findy depuis la recherche de l'en-tête Magento, en mode sélecteur CSS sur #search, #menu-search-icon : soit dans Findy (Design > Mode de déclenchement), puis copier le script de l'installation, soit avec le code ci-dessous, qui fixe ce sélecteur sur la vitrine (un sélecteur changé plus tard dans Design ne s'y appliquera pas). #search est le champ de recherche de l'en-tête Luma ; #menu-search-icon est l'icône de recherche de l'en-tête Hyvä, dont le champ reste caché tant qu'on ne l'a pas cliquée. Testé sur Luma et Hyvä 1.5.4 (Magento 2.4.9).

<script src="https://findysearch.com/widget-v2/findy-widget.js"></script>
<script>
  Findy.init({
    apiKey: 'VOTRE_CLE_WIDGET_FINDY',
    apiBaseUrl: 'https://findysearch.com',
    triggerSelector: '#search, #menu-search-icon'
  });
</script>

Sinon, la barre de recherche Findy : placer <div id="findy-search"></div> dans un bloc CMS, un widget « Bloc HTML » ou Contenu > Design > Configuration > Pied de page > HTML divers.

<div id="findy-search"></div>

<script src="https://findysearch.com/widget-v2/findy-widget.js"></script>
<script>
  Findy.init({
    apiKey: 'VOTRE_CLE_WIDGET_FINDY',
    containerId: 'findy-search',
    apiBaseUrl: 'https://findysearch.com'
  });
</script>

Panier Magento

Le widget ajoute au panier Magento natif de la vitrine, avec la session du visiteur : produits simples et configurables en stock. Les produits groupés, les bundles et les produits à options personnalisées obligatoires ouvrent leur fiche produit. Après l'ajout, le mini-panier se recharge sur les thèmes Luma et Hyvä.

Prix et stock

Findy lit le prix final et le stock vendable comme un visiteur non connecté de chaque vue magasin, par l'API GraphQL publique de la vitrine : règles de prix catalogue, prix spéciaux datés et stock multi-sources (MSI) sont appliqués par Magento. Un produit que la vitrine masque (rupture de stock) reste dans Findy, hors stock. Le réglage HT ou TTC de Findy s'applique au prix saisi dans l'admin : si la vitrine affiche un autre prix normal (catalogue affiché TTC, taxe fixe), la synchronisation s'arrête en nommant le produit plutôt que de compter la taxe deux fois.

Pages de paiement et CSP

La politique de sécurité de contenu (CSP) de Magento peut bloquer le widget sur les pages de paiement (restreintes à partir de Magento 2.4.7). La recherche est pensée pour les pages catalogue. Un module d'autorisation CSP n'est nécessaire que pour l'afficher aussi au paiement.

Après la mise en place

Les modifications du catalogue (produits, prix, stock) apparaissent après la prochaine synchronisation Findy : elle n'est pas en temps réel.
LimiteImpactContournement
Prix des clients connectésSeuls les prix invités sont lus : prix par groupe de clients, par paliers et prix B2B ne sont pas indexés.Aucun : le client connecté voit son prix sur la fiche produit et au panier.
Règles de prix catalogueMagento les applique depuis un index mis à jour par son cron : sans cron actif, une règle nouvelle ou arrivée à sa date n'apparaît ni sur la vitrine ni dans Findy.Vérifier que le cron Magento tourne, puis lancer une synchronisation Findy.
Produits non visibles individuellementAbsents de l'API de la vitrine, ils gardent le prix et le stock de l'API REST (sans règle catalogue ni MSI).Aucun : ils ne s'affichent pas seuls sur la vitrine.
Catalogue affiché TTCSi la vitrine affiche les prix du catalogue TTC ou avec une taxe fixe (FPT), la synchronisation s'arrête : Findy ne peut pas savoir si la taxe est comprise.Afficher les prix du catalogue hors taxe (Magasins > Configuration > Ventes > Taxes), ou contacter Findy.
Vitrine fermée aux visiteursCatalogues partagés B2B ou droits de catégorie : la vitrine ne montre rien aux invités, tous les produits sont indexés hors stock.Aucun pour l'instant : ouvrir le catalogue aux invités.
Devise d'affichageLes prix sont lus dans la devise de base de la vue magasin, sans conversion vers une autre devise d'affichage.Aucun pour l'instant.
Thèmes HyväLe mini-panier se recharge par l'événement de Hyvä (vérifié sur Hyvä 1.5.4). Un module tiers qui charge RequireJS sur une page Hyvä la fait traiter comme une page Luma.Recharger la page si le mini-panier ne se met pas à jour, et le signaler à Findy.
SynchronisationPas de temps réel : une modification peut mettre un moment à apparaître.Lancer une synchronisation manuelle depuis Findy après un changement important.

API

Installation custom ou headless

Utiliser ce mode pour les sites Next.js, Nuxt, React, Vue, Svelte, les paniers internes ou les frontends découplés. Dans Findy, choisir Site custom / API, renseigner un endpoint catalogue HTTPS, puis valider avec l'équipe Findy comment les produits et le panier sont connectés.

  • Exposer un endpoint JSON stable, public côté serveur Findy mais protégé par token.
  • Retourner les champs requis: externalId, name, price, url et inStock.
  • Utiliser une pagination cursor via nextCursor et hasMore pour les catalogues volumineux.
  • Vérifier que productId et variationId correspondent aux identifiants attendus par l'API panier.
  • Définir la stratégie des variantes: ajout direct, sélecteur de variante ou redirection fiche produit.
  • Sur une SPA, initialiser Findy côté client après le montage du champ cible et éviter les doubles initialisations.

Contrat catalogue custom

L'endpoint configuré dans Findy doit répondre en application/json. Findy ajoute les paramètres limit et cursor à l'URL, sauf configuration spécifique. L'authentification utilise par défautAuthorization: Bearer VOTRE_TOKEN.

{
  "items": [
    {
      "externalId": "sku-123",
      "sku": "SKU-123",
      "gtins": ["3760123456784"],
      "name": "Chaussure de running",
      "description": "Modele leger pour entrainement quotidien",
      "price": 89.9,
      "originalPrice": 109.9,
      "currency": "EUR",
      "imageUrl": "https://boutique.example/products/sku-123.jpg",
      "categories": ["Running", "Chaussures"],
      "brand": "Acme",
      "tags": ["nouveaute", "route"],
      "inStock": true,
      "stockQuantity": 42,
      "url": "https://boutique.example/products/sku-123",
      "addToCartUrl": "https://boutique.example/cart/add?sku=sku-123",
      "variantAttributes": [
        { "name": "Taille", "slug": "taille", "values": ["40", "41"] }
      ],
      "variants": [
        {
          "id": "sku-123-40",
          "sku": "SKU-123-40",
          "name": "Taille 40",
          "price": 89.9,
          "inStock": true,
          "attributes": { "Taille": "40" }
        }
      ]
    }
  ],
  "hasMore": true,
  "nextCursor": "page-2",
  "total": 240
}

Mode sélecteur CSS

<script src="https://findysearch.com/widget-v2/findy-widget.js"></script>
<script>
  Findy.init({
    apiKey: 'VOTRE_CLE_WIDGET_FINDY',
    apiBaseUrl: 'https://findysearch.com',
    triggerSelector: '#site-search, .js-open-search'
  });
</script>

Panier custom

Le contrat catalogue synchronise les produits; onAddToCart branche l'action panier côté site marchand. Adapter data.success au format réel de l'API panier. Ne pas considérer un HTTP 200 comme une réussite si l'API peut retourner une erreur métier dans le JSON.

<script src="https://findysearch.com/widget-v2/findy-widget.js"></script>
<script>
  Findy.init({
    apiKey: 'VOTRE_CLE_WIDGET_FINDY',
    apiBaseUrl: 'https://findysearch.com',
    triggerSelector: '#site-search',
    onAddToCart: async function({
      productId,
      variationId,
      quantity,
      selectedAttributes,
      product,
      variant,
      price,
      currency,
      query,
      collectionSlug
    }) {
      var csrfToken = window.CSRF_TOKEN;
      if (!csrfToken) {
        throw new Error('Missing CSRF token');
      }

      var response = await fetch('/api/cart/add', {
        method: 'POST',
        headers: {
          'Content-Type': 'application/json',
          'X-CSRF-Token': csrfToken
        },
        credentials: 'include',
        body: JSON.stringify({
          productId: productId,
          variationId: variationId || null,
          quantity: quantity || 1,
          selectedAttributes: selectedAttributes || {},
          sku: variant?.sku || product?.sku || null,
          price: price || null,
          currency: currency || 'EUR',
          findyContext: {
            query: query || null,
            collectionSlug: collectionSlug || null
          }
        })
      });

      if (!response.ok) {
        return { success: false };
      }

      var data = await response.json().catch(function() {
        return {};
      });

      return { success: data.success === true };
    }
  });
</script>
  • L'API panier doit revalider côté serveur l'existence du produit et de la variante.
  • Les quantités, attributs, permissions utilisateur, stock et prix doivent être validés côté serveur.
  • La fonction doit transmettre le token CSRF, nonce ou jeton anti-fraude attendu.
  • Le site reste responsable de la mise à jour du mini-panier ou drawer panier après succès.
  • Ne jamais mettre de secrets serveur dans ce JavaScript.

Déclencher Findy manuellement

<button type="button" id="findy-open-button">Rechercher</button>

<script>
  document.getElementById('findy-open-button')?.addEventListener('click', function() {
    Findy.open();
  });
</script>

Sécurité

Sécurité, CSP et limites opérationnelles

Clé widget

La clé widget est publique et sert à identifier l'organisation. Elle ne remplace jamais une clé serveur WooCommerce, PrestaShop, CMS ou panier.

CORS et préflight

Les APIs widget acceptent les appels cross-origin nécessaires au chargement marchand. Les préflights OPTIONS sont séparés des appels fonctionnels et ne consomment pas de quota.
  • Autoriser le script Findy dans script-src, par exemple https://findysearch.com.
  • Autoriser les appels API Findy dans connect-src.
  • Charger Findy.init avec un nonce CSP, un hash CSP ou un fichier JavaScript du site déjà autorisé.
  • Prévoir style-src pour les styles injectés et fonts.googleapis.com si la police Google configurée est utilisée.
  • Prévoir font-src pour fonts.gstatic.com et img-src pour les images produits ou CDN.
  • Si une URL versionnée et un attribut integrity sont fournis, les utiliser avec crossorigin="anonymous".

Recette

Validation après installation

  • Le script findy-widget.js se charge sans erreur dans l'onglet Network.
  • La console navigateur ne contient pas d'erreur Findy is not defined.
  • La barre Findy ou le déclencheur CSS ouvre l'overlay.
  • Une recherche affiche des produits synchronisés.
  • Les filtres, les tris et la pagination ou le scroll infini fonctionnent.
  • Les images produits se chargent.
  • Le clic produit ouvre la bonne page produit.
  • L'ajout panier fonctionne quand il est activé.
  • Les variantes produits se comportent comme prévu.
  • Le mini-panier ou le compteur panier se met à jour si le thème le gère.
  • Les recherches, clics et ajouts panier remontent dans les analytics Findy après quelques minutes.
  • La consommation de requêtes correspond au scénario testé.
  • La recherche fonctionne sur mobile.
  • Les contraintes CSP sont respectées sans ajouter 'unsafe-inline' dans script-src.

Support

Dépannage rapide

SymptômeCause probableCorrection
Findy is not definedScript chargé après Findy.init ou bloquéCharger findy-widget.js avant Findy.init et vérifier la CSP.
Rien ne s'affichecontainerId absent, mauvais sélecteur ou élément monté trop tardVérifier le DOM, attendre le montage client sur SPA, tester document.querySelector(...).
Le clic ne fait rienMauvais triggerSelector ou élément remplacé par le thèmeUtiliser un sélecteur plus stable ou déclencher Findy.open manuellement.
Résultats videsCatalogue non synchronisé, filtres trop stricts ou produits masquésTester la connexion CMS, relancer une synchronisation et vérifier les règles de visibilité.
Erreur 401 widgetClé widget invalide ou révoquéeRécupérer une nouvelle clé widget Findy.
Message Plus de requêtes disponiblesQuota épuisé ou abonnement suspenduVérifier le plan, les requêtes restantes, le hors-forfait et l'état de paiement.
Facture plus élevée que prévuClics, ajouts panier ou recherches paginées générant du hors-forfaitComparer usage mensuel, overageRequestsThisPeriod et tarif pay-as-you-go du plan.
Ajout panier instableThème ou panier personnaliséUtiliser onAddToCart et valider stock, variante, prix, CSRF côté serveur.
Adresse Shopify refuséeDomaine personnalisé saisi à la place de l'adresse .myshopify.comRécupérer l'adresse xxx.myshopify.com dans Paramètres > Domaines de l'admin Shopify.
Catalogue Shopify videProduits non publiés sur le canal HeadlessInclure les produits dans le storefront Headless puis relancer une synchronisation.
Connexion Shopify refuséeJeton public collé à la place du jeton privé, jeton supprimé, canal désinstallé ou permission manquanteCopier le Private access token du storefront Headless, vérifier les trois permissions produit et mettre le jeton à jour dans Findy.
Synchronisation Shopify en échec (ACCESS_DENIED)Permission Storefront API décochée après le test de connexion, ou non vérifiable au test faute de produit publié (tags ou stock) ; le message Findy nomme la permission manquanteRe-cocher les trois permissions unauthenticated_read_product_* du storefront Headless, enregistrer puis relancer la synchronisation.
Compteur panier Shopify figéLe thème ne recharge pas son drawer après un ajout externeChoisir REDIRECT_TO_CART ou brancher onAddToCart sur la fonction panier du thème.
Connexion Magento refusée (401)Jeton faux ou intégration inactive, option Bearer désactivée, ou ressource API manquanteVérifier que l'intégration est activée, passer « Allow OAuth Access Tokens to be used as standalone Bearer tokens » sur Oui, et cocher les ressources Catalogue, Magasins et Inventaire.
Magento : « Could not create an acl object: Role 'N' not found »Magento 2.4.9 : après la suppression d'une intégration, l'admin peut échouer tant que le cache n'est pas purgéVider le cache : Système > Gestion du cache > Vider le stockage du cache (Flush Cache Storage), ou bin/magento cache:flush.
Widget absent sur la vitrine MagentoCache des pages Magento non vidé après l'ajout du script, ou script collé sur une autre vue magasinVider le stockage du cache (Système > Gestion du cache > Flush Cache Storage) et vérifier la vue magasin modifiée dans Contenu > Design > Configuration.
Widget absent au paiement MagentoCSP de Magento restreinte sur les pages de paiementPrévu pour les pages catalogue ; un module d'autorisation CSP est nécessaire pour l'afficher au paiement.

Références utiles