Estalydocs
Référence API ↗Guide d’intégration BUT
Assurance embarquée / Quickstart
ESTALY ELEMENTS

Intégrez une protection
à votre page produit.

Ajoutez Estaly.js à votre page, affichez une offre adaptée au produit et reliez le choix du client à votre panier. Sans installation npm.

JavaScript · balise scriptFiche produit & panier latéralCatégorie + prix
Ce que vous allez construire. Un bloc d’assurance sur la fiche produit ou dans le panier latéral : offre au bon prix, deux questions de conseil, documents et consentement, puis ajout de la protection au panier BUT.
Avant de commencerVotre clé publique EstalyLa catégorie et le prix du produitVotre API panier BUT
DANS VOTRE PAGE HTML

Chargez Estaly.js

Ajoutez le script avant votre code d’intégration, puis initialisez Estaly avec votre clé publique. Aucun bundler ni package npm n’est nécessaire.

La clé publique peut apparaître dans la page. Votre clé API secrète reste exclusivement côté serveur. Chargez Estaly.js une seule fois par page.

À ce stade, rien n’est affiché au client.

LES DONNÉES DE VOTRE PRODUIT

Décrivez le produit à protéger

BUT transmet category: "seats" pour un siège ou "furniture" pour un meuble, ainsi que le prix TTC du produit. Vous gardez votre propre mapping catalogue.

Les prix sont en euros par unité : 599.99, pas 59999. Utilisez une référence de ligne panier stable, distincte du SKU produit.

Les données sont prêtes. Aucun composant n’est encore affiché.

LE COMPOSANT VISIBLE PAR LE CLIENT

Affichez l’offre dans votre page

Placez un conteneur au-dessus du bouton d’achat ou dans le panier latéral, puis montez le composant. Il affiche d’abord l’offre, le prix et « Choisir cette protection ».

Après ce clic seulement, Estaly affiche les deux questions, les documents et la case de consentement. Le composant gère ce parcours : BUT ne construit pas le questionnaire.

Dans l’aperçu, cliquez sur « Choisir cette protection » pour ouvrir le conseil.

LE RACCORDEMENT AU PANIER BUT

Récupérez le choix et ajoutez l’assurance

Quand le client clique sur « Ajouter la protection », le SDK enregistre les réponses et le consentement auprès du backend Estaly. Après confirmation, il appelle onAdd(selection) avec le selection_id renvoyé par Estaly et les informations utiles au panier. Votre serveur BUT ajoute l’assurance et conserve cette référence avec la ligne panier.

Renvoyez { insurance_line_reference_id } uniquement après succès. En cas d’erreur, rejetez la promesse : Estaly conserve les réponses et propose un nouvel essai.

« Protection ajoutée » apparaît après la confirmation de votre panier.

VÉRIFIEZ LE PARCOURS COMPLET

Testez votre intégration

Dans l’aperçu : choisissez une protection, répondez aux questions, consultez les documents et cochez le consentement. Ajoutez ensuite la protection et ouvrez « Données panier » pour voir ce que reçoit BUT.

Vous pouvez aussi lire protection.getSelection() depuis votre propre bouton d’ajout au panier. Cette lecture n’ajoute rien : protection.add() déclenche le même callback onAdd.

Une seule ligne d’assurance est liée à la ligne produit. Aucun contrat n’est créé à cette étape.

UNE FRONTIÈRE CLAIRE

Estaly gère le parcours d’assurance. BUT gère son panier.

Estaly.js affiche et accompagne

Avec la clé publique, le composant récupère l’offre par catégorie et prix. Après le clic du client, il gère les questions, les documents et le consentement. Il enregistre les réponses et le consentement chez Estaly, puis vous transmet la référence de sélection via onAdd.

Votre callback relie le panier

onAdd(selection) appelle votre serveur BUT. Celui-ci vérifie la sélection, ajoute la ligne d’assurance liée au produit et renvoie sa référence. La clé publique n’autorise pas la création d’un contrat.

Deux clés, deux usages

publicKey identifie votre intégration navigateur. Votre clé API secrète authentifie les opérations serveur et ne doit jamais apparaître dans le HTML. Configurez les domaines autorisés pour votre clé publique.

Une association persistante

Conservez selection_id avec les lignes produit et assurance. Cette référence permet ensuite de rattacher le conseil au client, sans retransmettre ses réponses. Pour modifier le produit déjà protégé, retirez sa protection puis transmettez le nouveau contexte.

Les données reçues lors de l’ajout

Le callback onAdd(selection) vous transmet les informations suivantes. Conservez la référence de sélection avec la ligne d’assurance.

ChampUtilisation côté BUT
selection_idRéférence renvoyée par le backend Estaly après enregistrement du choix. À conserver dans le panier, puis à transmettre avec les coordonnées client.
product.cart_line_reference_idLie la protection à la bonne ligne du panier, même si le même SKU apparaît plusieurs fois.
product.categoryCatégorie métier transmise par BUT : seats ou furniture.
insurance.offer_reference_idRéférence Estaly à associer à votre produit d’assurance.
insurance.unit_price
insurance.quantity		Prime TTC en euros par unité et nombre d’unités assurées. Le serveur vérifie le montant.
Responsabilités et erreurs du panier

Les routes /integration/cart/protection et /integration/cart/protection/remove des exemples appartiennent au serveur BUT. Adaptez-les à votre API panier et à votre protection CSRF.

Avant d’ajouter l’assurance, votre serveur vérifie le produit, le prix, la quantité et la référence de sélection. Il retrouve ou crée la ligne produit parente, puis ajoute une seule ligne d’assurance. Le prix envoyé par le navigateur n’est pas une autorité.

Le callback onAdd résout avec { insurance_line_reference_id }. Une erreur doit rejeter sa promesse : n’affichez pas une réussite avant que le panier soit écrit.

onRemove résout après le retrait confirmé. En cas d’échec, la protection reste affichée comme ajoutée. Si une requête expire après écriture, réconciliez le panier par selection_id avant de créer une autre ligne.

getSelection() renvoie null avant la validation du choix. Après consentement, il renvoie les données de sélection. add() invoque onAdd ; ne le doublez pas par un second ajout manuel.

Authentification, environnements et données

Utilisez https://api.staging.estaly.co pour votre recette et https://api.estaly.co en production. Envoyez Authorization: Bearer <ESTALY_API_KEY> depuis votre serveur uniquement.

Les exemples utilisent des prix TTC en euros, des dates ISO 8601 et des références de ligne panier stables. Les catégories utilisées dans ce guide sont seats et furniture ; BUT détermine la catégorie de chaque produit à partir de son catalogue.

N’envoyez pas de clé secrète ni de données personnelles dans les paramètres d’URL. Rattachez la sélection au client au moment de l’identification, avant le paiement. Les réponses et le consentement sont conservés chez Estaly ; BUT ne les reconstruit pas.

APRÈS L’AJOUT AU PANIER · CÔTÉ SERVEUR

Du choix de protection à la création du contrat.

Le SDK a déjà enregistré le conseil et le consentement chez Estaly. Votre serveur associe la sélection au client dès que ses coordonnées sont connues, puis crée les contrats après paiement confirmé.

1. Client identifié · leads→2. Paiement confirmé · plans→3. Livraison·Annulation de commande
Authentifiez ces appels depuis votre serveur BUT.

En recette : https://api.staging.estaly.co. En production : https://api.estaly.co. Remplacez {store_id} par votre identifiant de magasin Estaly.

Authorization: Bearer <ESTALY_API_KEY>
Content-Type: application/json

Utilisez votre clé API secrète. Ces appels ne passent pas par la clé publique d’Estaly.js.

01 · CLIENT IDENTIFIÉ, AVANT PAIEMENT

Associez la protection au client et déclenchez l’envoi des documents

Dès que le client renseigne ses coordonnées, votre serveur transmet le selection_id conservé dans le panier et les informations client. Estaly retrouve le produit, l’offre, les réponses et le consentement déjà enregistrés par le SDK.

POST /api/v2/store/{store_id}/leads

Pour chaque protection présente dans le panier, ajoutez une entrée au tableau leads : la référence de sélection et customer. Un appel accepte de 1 à 50 entrées.

Utilisez exactement le selection_id reçu dans onAdd(selection) ; remplacez la valeur d’exemple à droite. BUT n’a ni à générer cet identifiant, ni à renvoyer les réponses au devoir de conseil.

Estaly rattache le conseil au client et déclenche l’envoi des documents précontractuels par e-mail avant paiement. Aucun contrat n’est créé à cette étape.

Réponse 201 : un tableau de leads. Enregistrez la confirmation de cet appel côté BUT avant de poursuivre le paiement.

L’e-mail permet d’identifier le destinataire des documents. Transmettez également le prénom et le nom dès qu’ils sont disponibles.

Corps JSON · sélection + client
{
  "leads": [
    {
      "selection_id": "SELECTION_ID_RECU_DANS_ONADD",
      "customer": {
        "email": "camille@example.com",
        "first_name": "Camille",
        "last_name": "Martin"
      }
    }
  ]
}

Les réponses, le consentement, le produit et l’offre sont retrouvés grâce à selection_id. Le SDK a déjà enregistré ces informations chez Estaly.

02 · APRÈS PAIEMENT

Créez les contrats en bulk

Après confirmation du paiement par votre serveur, envoyez les protections effectivement achetées. Déclenchez cet appel depuis le traitement de commande BUT, indépendamment du retour du navigateur sur la page de confirmation.

POST /api/v2/store/{store_id}/plans

Construisez un tableau plans de 1 à 50 entrées. offer_reference_id reprend selection.insurance.offer_reference_id. Remplacez la valeur d’exemple par cette référence Estaly.

order_reference_id est la référence de commande BUT. variant.price est le prix TTC du bien en euros, et non la prime d’assurance. Utilisez les données validées de la commande côté serveur.

Renseignez les coordonnées complètes du souscripteur. Ici, l’adresse se trouve dans customer.address. purchase_date est la date d’achat au format YYYY-MM-DD, distincte de la date de livraison.

Réponse 200 : un objet { plans: […] }. Conservez votre order_reference_id pour le suivi de livraison et l’annulation. Les identifiants de contrat renvoyés restent disponibles pour votre suivi, sans être nécessaires à ces deux appels.

Les correspondances entre sélection, lead, ligne de panier et contrat sont conservées par BUT ; le corps de cet appel utilise les champs présentés dans l’exemple.

Corps JSON · plans
{
  "plans": [
    {
      "offer_reference_id": "OFFRE_ESTALY_SELECTIONNEE",
      "order_reference_id": "BUT-COMMANDE-12345",
      "purchase_date": "2026-10-09",
      "variant": {
        "reference_id": "BUT-ATON-GRIS",
        "title": "Canapé 3 places ATON",
        "price": 599.99,
        "currency_code": "EUR"
      },
      "customer": {
        "email": "camille@example.com",
        "first_name": "Camille",
        "last_name": "Martin",
        "phone": "+33612345678",
        "address": {
          "address1": "10 rue de Paris",
          "city": "Lyon",
          "zip_code": "69002",
          "country": "FR"
        }
      }
    }
  ]
}
03 · À LA LIVRAISON

Transmettez la livraison par référence de commande

Lorsque BUT confirme la livraison complète de la commande, votre serveur transmet sa référence BUT et la date effective de livraison. Estaly retrouve les contrats associés et actualise leur date de prise d’effet.

PATCH /api/v2/store/{store_id}/orders/{order_reference_id}/delivery

Utilisez la même order_reference_id que lors de la création des contrats, par exemple BUT-COMMANDE-12345. Vous n’avez pas à conserver ni à transmettre les identifiants des contrats pour cet appel.

Envoyez date au format YYYY-MM-DD. Pour ce parcours BUT, cette date correspond à la livraison effective des biens assurés. La date d’achat purchase_date reste inchangée.

Cet appel applique une même date à tous les contrats actifs de la commande. Utilisez-le pour une livraison complète à la même date ; il ne décrit pas le traitement de livraisons partielles à des dates différentes.

Réponse 200 : {}. Enregistrez la confirmation avec la référence de commande côté BUT. Estaly recalcule les échéances à partir de la nouvelle date de prise d’effet.

Corps JSON · livraison
{
  "date": "2026-10-15"
}

Exemple : achat le 9 octobre, livraison complète le 15 octobre. L’URL contient la référence BUT-COMMANDE-12345.

EN CAS D’ANNULATION

Annulez les protections de la commande

Si BUT annule entièrement une commande dont les contrats ont déjà été créés, votre serveur transmet la référence de commande à Estaly. Un seul appel annule les contrats actifs associés.

PATCH /api/v2/store/{store_id}/orders/{order_reference_id}/cancel

Réutilisez la order_reference_id envoyée dans plans. Aucun identifiant de contrat ni corps JSON n’est nécessaire. Authentifiez la requête avec votre clé API secrète côté serveur.

Appelez cette route après confirmation de l’annulation chez BUT. Si la commande est abandonnée avant la création des contrats, il n’y a pas de contrat à annuler via cet appel.

Cette route concerne l’annulation complète de la commande, dans les 30 jours suivant sa création chez Estaly. Elle ne doit pas être utilisée pour annuler la protection d’un seul article conservant les autres protections.

Réponse 200 : {}. Marquez les protections de la commande comme annulées dans votre suivi BUT.

404 : la référence de commande n’est pas trouvée pour ce magasin. 422 : la commande dépasse la fenêtre d’annulation autorisée.

Requête serveur · annulation
curl --request PATCH \
  'https://api.staging.estaly.co/api/v2/store/VOTRE_STORE_ID/orders/BUT-COMMANDE-12345/cancel' \
  --header 'Authorization: Bearer VOTRE_CLE_API_SECRETE'

Remplacez le magasin, la référence de commande et la clé secrète. La méthode de cette route est PATCH.