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 des API tierces directement dans vos Fin Procedures.

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 obligatoire lors de l'utilisation des connecteurs de données dans les Procedures. 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 automatiquement listés en haut du menu déroulant (par exemple, Obtenir commande de livraison > statut, Obtenir 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 Procedure

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 Procedure, y compris toutes les étapes et sous-procédures. Vous n'avez besoin d'appeler chaque connecteur qu'une seule fois par Procedure, 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 fictifs pour tester et commencer à construire votre procédure

Vous n'avez pas besoin d'une API live 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 fictive. 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 peuvent affecter les performances. En général, plus c'est petit et précis, mieux c'est.

Si une transformation des 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 Procedures, « contexte » fait référence à l'exécution complète de la Procedure. 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 différentes é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 à demander explicitement à Fin 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 constatez 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 Procedure 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 entièrement la collecte ou le raisonnement de Fin et restent intactes.

Surveillance de la santé des connecteurs

Les Procedures utilisant des connecteurs de données affichent un indicateur Problèmes de connecteur 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. La pastille 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 Procedures sans connecteurs de données n'affichent aucun indicateur ; les connecteurs sans exécution sont considérés comme sains.

Note : L'indicateur Problèmes de connecteur sur la liste des procédures reflète toujours les 14 derniers jours. Les taux de réussite dans le tableau de bord de santé d'un connecteur de données suivent le filtre temporel que vous sélectionnez. Après avoir corrigé un problème, vous devrez peut-être attendre de nouvelles données ou ajuster ce filtre temporel pour confirmer que le connecteur fonctionne correctement.

Statuts de santé

Statut	Critère	Implication
🟡 Dégradé	Un connecteur a un taux de réussite de 80 à 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 de grandes réponses 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 l'indicateur Problèmes de connecteur ouvre un panneau avec une carte par connecteur affecté, montrant son statut (Dégradé ou Non sain), le taux de réussite, le nombre d'exécutions et la taille de la réponse. Les noms des connecteurs renvoient directement à leur page de paramètres pour un débogage 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 commandes > items

Mais vous ne verrez pas :

Obtenir commandes > items > title
Obtenir 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 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 : @Lire Obtenir 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 Fin Procedures