API Reference
  1. Guide API

Vue d'ensemble

L'API Estaly permet d'intégrer des offres d'assurance personnalisées directement dans votre parcours e-commerce. Cette documentation décrit les concepts clés et le flux d'intégration.

Concepts fondamentaux

Offres d'assurance

Un contrat d'assurance est défini par :

  • Un univers de produits (smartphones, informatique, photo...)
  • Des garanties (casse, vol, panne, oxydation...)
  • Une durée de couverture (12, 24 ou 36 mois)
  • Une tranche de prix du produit assuré (ex: 3000€-4000€)

Points de contact

  • Emplacements : Points d'interaction dans le parcours client (page produit, panier, tunnel, emails...)
  • Formats : Présentation de l'offre (checkbox, pop-up, bannière, widget...)

Processus de vente

  • Souscription : Création du contrat après paiement, associant le produit assuré au client
  • Attachement : Taux de conversion des offres d'assurance, analysé par notre IA pour optimisation

Catalogue

Chaque combinaison unique (univers × garanties × durée × tranche) génère une référence distincte dans votre catalogue. Par exemple, pour l'assurance smartphone avec :

  • 3 durées (1, 2, 3 ans)
  • 10 tranches de prix
    Vous aurez 30 références à importer.

Exemples d'intégration

Pop-up sur page produit

Utilisation des bullet_points pour construire une modal informative :

const insuranceModal = {
  title: offer.category.marketing_data.modal.headline,
  content: (
    <div>
      <h3>{offer.category.marketing_data.modal.coverage_bullets_heading}</h3>
      <ul>
        {offer.category.marketing_data.modal.bullet_points.map(bullet => (
          <li>{bullet}</li>
        ))}
      </ul>
      <button>{offer.category.marketing_data.modal.buy_text}</button>
    </div>
  )
};

Documents légaux

Intégration des liens sous une checkbox de souscription :

<div class="insurance-legal">
  <input type="checkbox" required />
  <span>J'accepte les</span>
  <a href={offer.category.legal_documents.cg_url}>conditions générales</a>
  <span>et la</span>
  <a href={offer.category.legal_documents.ipid_url}>fiche IPID</a>
</div>

Flux d'intégration

1. Configuration initiale

  • Définition des offres avec l'équipe commerciale Estaly
  • Import des références dans votre catalogue
  • Définition des variables d'attachement à suivre (prix produit, catégorie, segmentation client...)

2. Parcours client

Points d'intégration

Notre API est conçue pour s'adapter à votre parcours client. Vous pouvez :

  1. Choisir l'emplacement

    • Page produit (avant ou après le bouton d'ajout au panier)
    • Mini-panier
    • Page panier
    • Tunnel de commande
    • Emails post-achat
    • Pages de compte client
    • Applications mobiles

  2. Définir le format

    • Checkbox simple
    • Pop-up modal
    • Bannière intégrée
    • Widget flottant
    • Onglet dans un carrousel
    • Section dédiée
    • Version mobile-first

L'API retourne toutes les données nécessaires (textes, prix, images) pour construire ces éléments :

GET /api/v2/store/{store_id}/offers?category_id={category_id}&product_reference_id={product_reference_id}&product_price={product_price}

Response:

{
  "reference_id": "1051",
  "contract_id": "CO36BI250NTA",
  "term_length": "3 ans",
  "price": 12900,
  "currency_code": "EUR",
  "price_band_min": 0,
  "price_band_max": 50000,
  "billing": "annually",
  "title": "Assurance smartphone Casse/Vol - 3 ans",
  "category_id": "smartphone",
  "category": {
    "id": "smartphone",
    "marketing_data": {
      "buttons": {
        "link_text": "En savoir plus",
        "headline": "Protégez votre smartphone contre la casse et le vol"
      },
      "modal": {
        "headline": "Protégez votre smartphone contre la casse et le vol avec Estaly",
        "coverage_bullets_heading": "Cette protection comprend :",
        "bullet_points": [
          "Couverture contre le vol total, le vol des accessoires et la casse accidentelle",
          "Indemnisation au prix d'achat du smartphone pendant 2 ans, sans décôte",
          "Franchise minimale : 0€ pour la casse, 5% du prix du smartphone pour le vol",
          "1, 2 ou 3 ans de protection, vous choisissez"
        ],
        "link_text": "Voir le détail des garanties",
        "buy_text": "Ajouter une protection",
        "decline_text": "Je ne veux pas protéger mon smartphone",
        "legal_text": "Protection proposée par Estaly",
        "image": "https://estaly-image-smartphone.png",
        "merchant_logo": "https://merchant_logo.png",
        "marketing_page_url": "https://smartphones.estaly.co"
      },
      "cart": {
        "simple_offer_button_text": "Protégez votre smartphone pour"
      }
    },
    "legal_documents": {
      "cg_url": "https://smartphones-cg-estaly.pdf",
      "ipid_url": "https://smartphones-ipid-estaly.pdf"
    }
  }
}

```http
GET /api/v2/store/{store_id}/offers?category_id={category_id}&product_reference_id={product_reference_id}&product_price={product_price}

Paramètres:

  • store_id: Identifiant unique de votre boutique
  • category_id: Catégorie du produit (ex: "smartphones")
  • product_reference_id: Référence unique du produit
  • product_price: Prix du produit en centimes

Ajout au panier

Lorsque le client sélectionne une offre, utilisez l'API de votre CMS ou plateforme e-commerce pour ajouter le contrat d'assurance au panier. Par exemple avec l'API WooCommerce :

// Récupération de l'offre Estaly
const offer = await fetch(`/api/v2/store/${storeId}/offers?category_id=smartphone&product_reference_id=IPHONE15-256GB&product_price=129900`);

// Ajout au panier via l'API WooCommerce
await fetch('/wp-json/wc/store/v1/cart/add-item', {
  method: 'POST',
  body: JSON.stringify({
    id: offer.reference_id,        // Référence du produit d'assurance dans votre catalogue
    quantity: 1
  })
});

Autres exemples courants :

// Shopify
await fetch('/cart/add.js', {
  method: 'POST',
  body: JSON.stringify({
    items: [{
      id: offer.reference_id,
      quantity: 1
    }]
  })
});

// PrestaShop
await fetch('/cart-update', {
  method: 'POST',
  body: JSON.stringify({
    id_product: offer.reference_id,
    add: 1
  })
});

Souscription

Une fois le paiement validé, la souscription doit être effectuée immédiatement :

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

{
  "offer_reference_id": "98498",
  "order_reference_id": "51965",
  "variant": {
    "reference_id": "IPHONE15-256GB",
    "price": 149.00,
    "currency_code": "EUR",
    "title": "iPhone 15 256GB"
  },
  "customer": {
    "first_name": "John",
    "last_name": "Doe",
    "email": "[email protected]",
    "phone": "+33611223344",
    "address": {
      "city": "Paris",
      "country": "France",
      "zip_code": "75001",
      "address1": "1 Rue des Champs Elysées",
      "address2": ""
    }
  }
}

Response:

{
  "contract_id": "CO12BIPASOFF",
  "status": "active",
  "activation_date": "12/01/2022",
  "expiration_date": "12/01/2023"
}

3. Analytics et optimisation

Transmission des données de vente

Transmettez les données de vos commandes pour optimiser les taux d'attachement :

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

{
  "order_reference_id": "ORD-123456",
  "purchased_at": "2024-02-03T15:30:00Z",
  "payment_method": "credit_card",
  "sales_channel": "online",
  "line_items": [{
    "reference_id": "IPHONE15-256GB",
    "price": 129999,
    "currency_code": "EUR",
    "category_id": "smartphone",
    "insurance_offered": true,
    "insurance_selected": false
  }]
}

Intelligence artificielle

Notre moteur d'IA analyse ces données pour :

  • Identifier les facteurs d'attachement clés
  • Optimiser les prix et le ciblage
  • Générer des recommandations marketing personnalisées

Liens de paiement

API disponible pour générer des liens de paiement intégrables aux emails transactionnels.

Exemple concret

Pour un smartphone à 2500€ :

  • Tranche applicable : 2000€-3000€
  • Offres disponibles :
    • 1 an : 209€
    • 2 ans : 409€
    • 3 ans : 539€

Sécurité et authentification

L'API Estaly utilise l'authentification Bearer Token. Incluez votre token dans le header HTTP Authorization de chaque requête :

Authorization: Bearer eyJhbGciOiJIUzI1NiIs...

Pour obtenir votre token :

  1. Connectez-vous à votre espace Estaly
  2. Accédez à la section Paramètres > API
  3. Générez un token pour votre environnement (test ou production)

Protégez vos tokens de production et ne les exposez jamais côté client.

Updated about 1 year ago

Did this page help you?

Updated about 1 year ago

Did this page help you?