Les connecteurs de données permettent à Fin d'interagir avec des systèmes externes via des points de terminaison API. Fin peut utiliser les connecteurs de données pour :

Lire les informations du connecteur de données (par exemple, quel plan l'utilisateur utilise).
Effectuer des actions (par exemple, utiliser un POST pour annuler un abonnement dans un système externe).

Commencer

Ajouter un connecteur de données à une étape d'instruction

Dans une étape d'instruction, tapez @ pour ouvrir le menu des outils.
Sélectionnez Appeler un connecteur de données.
Choisissez le connecteur spécifique que vous souhaitez exécuter (par exemple, Obtenir les commandes pour récupérer l'historique d'achat d'un client).

Astuce : Apprenez à configurer les connecteurs de données pour extraire des informations en temps réel de vos systèmes internes ou d'API tierces directement dans vos procédures Fin.

Accéder à la réponse en utilisant des attributs générés automatiquement

Une fois un connecteur ajouté, vous pouvez immédiatement accéder à la réponse dans les étapes suivantes. Cela est disponible pour Fin en tant que contexte général, mais nous analysons également les champs de réponse dans les connecteurs de données afin de vous permettre de faire explicitement référence aux éléments du corps de la réponse pour une fiabilité maximale.

Note : Le mappage de la réponse n'est pas requis lors de l'utilisation des connecteurs de données dans les procédures. Fin utilise la réponse de test que vous configurez dans le connecteur de données pour comprendre la structure de la réponse API avec les noms de champs disponibles et leurs types. Vous pouvez ensuite utiliser un langage simple dans vos instructions de procédure pour indiquer à Fin quelles données de la réponse utiliser. Au moment de l'exécution, Fin effectue un appel API en direct et lit les valeurs réelles de ces champs.

Tapez @ et sélectionnez Lire un attribut.
Vous verrez les champs de réponse du connecteur de données listés automatiquement en haut du menu déroulant (par exemple, Obtenir la commande de livraison > statut, Obtenir la commande de livraison > order_id).
Sélectionnez l'attribut spécifique dont vous avez besoin pour l'insérer dans votre instruction ou condition.

Le contexte est partagé dans toute la procédure

Lorsque vous demandez à Fin d'utiliser un connecteur de données (@ use data connector), les données retournées deviennent disponibles dans toute la procédure.

Pour une plus grande fiabilité, vous pouvez accéder à ces données en utilisant (@ read attributes). Fin conserve les données du connecteur pendant toute la durée d'une procédure, y compris toutes les étapes et sous-procédures. Vous n'avez besoin d'appeler chaque connecteur qu'une seule fois par procédure, sauf si vous avez explicitement besoin de données actualisées.

Par exemple, si vous appelez (@ use Get_Subscription_info) à l'étape un, Fin conservera le contexte d'abonnement du client pour toutes les étapes et sous-procédures suivantes.

Bonnes pratiques

Profitez des connecteurs de données simulés pour tester et commencer à construire votre procédure

Vous n'avez pas besoin d'une API en direct entièrement construite pour commencer à créer des procédures. Vous pouvez utiliser des réponses d'exemple pour simuler les données.

Réponse d'exemple : Dans la configuration du connecteur de données (sous l'onglet « Réponse de test »), sélectionnez Réponse d'exemple et collez une charge utile JSON simulée. Cela vous permet de construire et tester immédiatement le flux de la procédure.
Simulation dynamique : Pour des scénarios plus complexes, vous pouvez utiliser des outils comme Beeceptor pour simuler des réponses API dynamiques.

Optimisez vos réponses API pour qu'elles soient le plus petit sous-ensemble possible des données pertinentes dont Fin a besoin pour la procédure

Trop de données non pertinentes peut affecter les performances. En général, plus c'est petit et précis, mieux c'est.

Si une transformation de données est nécessaire, il est fortement recommandé de transformer les données soit en sélectionnant un nombre limité de champs, soit en utilisant des blocs de code de connecteur de données. Cela transformera la réponse API avant que Fin ne la voie dans la procédure.

Optimisez pour n'utiliser pas plus d'un connecteur de données par étape

Une étape est censée être une unité de travail unique. Fin est plus fiable lorsque vous appelez un seul connecteur de données dans une étape.

Appelez les connecteurs de données une fois par contexte

Dans les procédures, « contexte » fait référence à l'exécution complète de la procédure. Fin réutilise automatiquement les données du connecteur dans toutes les étapes et sous-procédures. Vous n'avez pas besoin d'appeler la même API deux fois.

❌ Il n'est pas nécessaire d'appeler le même connecteur deux fois dans plusieurs étapes :

Step 1: 

… (@use Get_Subscription_info) … and include @read plan status in your response so the users knows 

Step 2 

… (@use Get_Subscription_info) …  and include @read refund eligibility in your response so the users knows

✅ Il est plus simple, plus propre et plus rapide d'appeler le connecteur une seule fois :

Step 1: 

… (@use Get_Subscription_info) … include @read plan status in your response so the users knows 

Step 2 

… include @read refund eligibility in your response so the users knows

Si vous avez besoin de données provenant de plusieurs systèmes, répartissez la logique sur plusieurs étapes au lieu d'appeler plusieurs connecteurs dans une seule étape.

Il n'est pas nécessaire de demander à Fin de collecter des données déjà configurées comme entrées requises pour un connecteur de données

Les entrées sont préconfigurées lors de la configuration du connecteur de données, donc Fin déduira les entrées qu'il doit collecter pour appeler le connecteur de données sans que vous ayez à lui demander explicitement de collecter ces données.

Par exemple, si le connecteur de données Get Order Details a déjà le champ d'entrée email configuré :

❌ Instruction inutilement complexe :

First ask the customer for their email, then call @get_order_details with that email

✅ Instructions claires :

Call @get_order_details

Fin déduit et collecte automatiquement les entrées requises en fonction de la configuration du connecteur, sauf si l'entrée est déjà fournie directement par Intercom.

Note : Si vous remarquez des problèmes de performance ou de fiabilité avec la collecte des entrées, vous pouvez explicitement indiquer à Fin quand collecter ces données.

Astuce pro : Lorsqu'une procédure nécessite des données précises, non modifiées ou sécurisées (par exemple, email, ID utilisateur ou informations de compte), injectez ces valeurs directement depuis Intercom dans le connecteur. En configurant l'attribut directement dans le connecteur au lieu de le collecter via Fin, les données contournent la collecte ou le raisonnement de Fin et restent intactes.

Surveillance de la santé du connecteur

Les procédures utilisant des connecteurs de données affichent un indicateur de santé directement sur la page de liste des procédures, vous permettant de repérer les problèmes de connecteur d'un coup d'œil sans ouvrir chaque procédure. Le tampon reflète le connecteur le moins performant utilisé par cette procédure, calculé sur les 14 derniers jours (limité à 1 000 exécutions par connecteur).

Les procédures sans connecteurs de données n'affichent aucun indicateur ; les connecteurs sans exécutions sont considérés comme sains.

Statuts de santé

Statut	Critère	Implication
🟢 Sain	Tous les connecteurs ont un taux de réussite >95 % et une taille moyenne de réponse inférieure à 50 Ko.	Fonctionne de manière optimale.
🟡 Dégradé	Un connecteur a un taux de réussite entre 80 et 95 %, ou un taux de réussite >95 % mais une taille moyenne de réponse ≥50 Ko (~15K tokens).	Rencontre des problèmes ou renvoie des réponses volumineuses pouvant augmenter le risque d'hallucination.
🔴 Non sain	Un connecteur a un taux de réussite <80 %, ou une taille moyenne de réponse ≥100 Ko (~30K tokens).	Problèmes critiques ou réponses dangereusement volumineuses nécessitant une attention immédiate.

Analyse détaillée

Cliquer sur le tampon de santé ouvre un tiroir avec une ventilation par connecteur : statut, taux de réussite, taille moyenne de réponse, latence P90 et principales erreurs. Les noms des connecteurs renvoient directement à leur page de paramètres pour un débogage rapide.

Astuce : Si un connecteur affiche un statut Dégradé ou Non sain en raison de la taille de la réponse, consultez la bonne pratique Optimisez vos réponses API pour qu'elles soient le plus petit sous-ensemble possible des données pertinentes dont Fin a besoin ci-dessus, en filtrant les champs ou en utilisant des blocs de code pour réduire la réponse avant que Fin ne la voie, c'est la solution la plus rapide.

Gestion des tableaux

Lorsqu'un connecteur de données renvoie une liste, Fin expose uniquement le tableau racine en tant qu'attribut. Les éléments enfants à l'intérieur du tableau ne sont pas exposés en tant qu'attributs séparés dans le sélecteur d'attributs.

Par exemple, si un connecteur renvoie un tableau items, vous verrez :

Obtenir les commandes > items

Mais vous ne verrez pas :

Obtenir les commandes > items > title
Obtenir les commandes > items > price

Fin peut toujours travailler avec le contenu d'une liste. Par exemple, si vous donnez l'instruction suivante : « Si le client demande ce qu'il y a dans sa commande, utilisez Obtenir la commande > items pour lister les produits et leurs prix. »

Fin lira le contenu complet de la liste items et répondra : « Votre commande comprend une souris sans fil (24,99 $) et un support pour ordinateur portable (39,99 $). »

Par exemple : Pour la charge utile de réponse ci-dessous, seul l'élément de tableau racine items est exposé en tant qu'attribut temporaire et non ses enfants.

{
  "order_id": "ORD-1001",
  "status": "processing",
  "created_at": "2025-01-12T14:23:00Z",
  "items": [
    {
      "product_id": "PROD-200",
      "name": "Wireless Mouse",
      "quantity": 1,
      "unit_price": 24.99
    },
    {
      "product_id": "PROD-122",
      "name": "Laptop Stand",
      "quantity": 1,
      "unit_price": 39.99
    }
  ]
}

Note : @Read Obtenir les commandes > items et dites au client les trois premiers articles de sa commande.

Utilisation des tableaux dans les conditions de code

Les attributs de tableau sont disponibles sous l'objet inputs["data_connector"], regroupés par nom de connecteur de données. Les tableaux sont indexés à partir de zéro, ce qui signifie que le premier élément est à l'index 0. Vérifiez toujours la longueur du tableau avant d'accéder à un index spécifique.

Vous pouvez toujours interroger les valeurs à l'intérieur d'un tableau en utilisant une condition de code.
Dans les conditions de code, les données du tableau sont accessibles via des expressions Python, où vous référencez explicitement les éléments par index ou itérez sur la liste.

Cette condition vérifie que la commande contient au moins quatre articles, et que la quantité du quatrième article est supérieure à trois.

Validez toujours la longueur du tableau avant d'accéder à un index pour éviter les erreurs d'exécution lors de l'évaluation de la condition.

Note : Les actions disponibles dépendent de la configuration de votre connecteur de données.

Les connecteurs de données prennent en charge :

Créer : Utilisez des requêtes POST pour créer de nouveaux enregistrements dans un système externe.
Lire : Utilisez des requêtes GET pour récupérer des données existantes.
Mettre à jour : Utilisez des requêtes PUT ou PATCH pour modifier des enregistrements existants.
Supprimer : Utilisez des requêtes DELETE pour supprimer des enregistrements.

Comment utiliser les connecteurs de données dans les procédures Fin