Los conectores de datos permiten que Fin interactúe con sistemas externos a través de endpoints de API. Fin puede usar conectores de datos para:
Leer información del conector de datos (por ejemplo, en qué plan está el usuario).
Realizar acciones (por ejemplo, usar un POST para cancelar una suscripción en un sistema externo).
Comenzar
Agregar un conector de datos a un paso de Instrucción
Dentro de un paso de Instrucción, escriba @ para abrir el menú de herramientas.
Seleccione Llamar conector de datos.
Elija el conector específico que desea ejecutar (por ejemplo, Obtener pedidos para recuperar el historial de compras de un cliente).
Consejo: Aprenda cómo configurar conectores de datos para extraer información en vivo de sus sistemas internos o APIs de terceros directamente en sus Fin Procedures.
Acceda a la respuesta usando atributos generados automáticamente
Una vez que se agrega un conector, puede acceder inmediatamente a la respuesta en pasos posteriores. Esto está disponible para Fin como contexto en general, pero también analizamos los campos de respuesta en conectores de datos para permitirle referirse explícitamente a elementos en el cuerpo de la respuesta para la máxima fiabilidad.
Nota: No es necesario mapear la respuesta al usar conectores de datos en Procedures. Fin utiliza la respuesta de prueba que configura en el conector de datos para entender la estructura de la respuesta de la API con los nombres de campo disponibles y sus tipos. Luego puede usar lenguaje sencillo en las instrucciones del procedimiento para indicarle a Fin qué datos de la respuesta usar. En tiempo de ejecución, Fin realiza una llamada API en vivo y lee los valores reales de esos campos.
Escriba @ y seleccione Leer un atributo.
Verá los campos de respuesta del conector de datos listados automáticamente en la parte superior del menú desplegable (por ejemplo, Obtener pedido de entrega > estado, Obtener pedido de entrega > order_id).
Seleccione el atributo específico que necesita para insertarlo en su instrucción o condición.
El contexto se comparte a lo largo del Procedure
Cuando indica a Fin que use un conector de datos (@ use data connector), los datos devueltos están disponibles en todo el procedimiento.
Para mayor fiabilidad, puede acceder a estos datos usando (@ read attributes). Fin retiene los datos del conector durante toda la duración de un Procedure, incluyendo todos los pasos y subprocedimientos. Solo necesita llamar a cada conector una vez por Procedure a menos que necesite datos actualizados explícitamente.
Por ejemplo, si llama a (@ use Get_Subscription_info) en el paso uno, Fin retendrá el contexto de la suscripción del cliente para todos los pasos y subprocedimientos posteriores.
Mejores prácticas
Aproveche los conectores de datos simulados para probar y comenzar a construir su procedimiento
No necesita una API en vivo completamente construida para comenzar a crear procedimientos. Puede utilizar respuestas de ejemplo para simular datos.
Respuesta de ejemplo: En la configuración del conector de datos (en la pestaña "Respuesta de prueba"), seleccione Respuesta de ejemplo y pegue una carga útil JSON simulada. Esto le permite construir y probar el flujo del procedimiento de inmediato.
Simulación dinámica: Para escenarios más complejos, puede usar herramientas como Beeceptor para simular respuestas dinámicas de API.
Optimice sus respuestas de API para que sean el subconjunto más pequeño posible de datos relevantes que Fin necesita para el procedimiento
Demasiados datos irrelevantes pueden afectar el rendimiento. Generalmente, mientras más pequeño y claro, mejor.
Si se requiere una transformación de datos, se recomienda encarecidamente transformar los datos ya sea seleccionando un número limitado de campos o usando bloques de código de conector de datos. Esto transformará la respuesta de la API antes de que Fin la vea en el procedimiento.
Optimice para usar no más de un conector de datos por paso
Un paso está destinado a ser una unidad de trabajo única. Fin es más fiable cuando llama solo a un conector de datos en un solo paso.
Llame a los conectores de datos una vez por contexto
En Procedures, “contexto” se refiere a toda la ejecución del Procedure. Fin reutiliza automáticamente los datos del conector en todos los pasos y subprocedimientos. No necesita llamar a la misma API dos veces.
❌ No es necesario llamar al mismo conector dos veces en diferentes pasos:
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
✅ Es más simple, limpio y rápido llamar al conector solo una vez:
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 necesita datos de múltiples sistemas, divida la lógica en varios pasos en lugar de llamar a múltiples conectores en un solo paso.
No es necesario pedir a Fin que recopile datos que ya están configurados como entradas requeridas para un conector de datos
Las entradas se configuran previamente durante la configuración del conector de datos, por lo que Fin inferirá las entradas que necesita recopilar para llamar al conector de datos sin que usted tenga que indicarle explícitamente a Fin que recopile esos datos.
Por ejemplo, si el conector de datos Get Order Details ya tiene configurado el campo de entrada email:
❌ Instrucción innecesariamente compleja:
First ask the customer for their email, then call @get_order_details with that email
✅ Instrucciones claras:
Call @get_order_details
Fin infiere y recopila automáticamente las entradas requeridas según la configuración del conector, a menos que la entrada ya sea proporcionada directamente por Intercom.
Nota: Si nota problemas de rendimiento o fiabilidad con la recopilación de entradas, puede indicarle explícitamente a Fin cuándo recopilar estos datos.
Consejo profesional: Cuando un Procedure requiere datos precisos, sin modificar o seguros (por ejemplo, correo electrónico, ID de usuario o información de cuenta), inyecte esos valores directamente desde Intercom en el conector. Al configurar el atributo directamente en el conector en lugar de como una entrada recopilada por Fin, los datos evitan la recopilación o razonamiento de Fin por completo y permanecen intactos.
Monitoreo de la salud del conector
Los Procedures que usan conectores de datos muestran un indicador de salud directamente en la página de lista de procedimientos, para que pueda detectar problemas del conector de un vistazo sin abrir cada procedimiento. El sello refleja el conector con peor rendimiento usado por ese procedimiento, calculado durante los últimos 14 días (limitado a 1,000 ejecuciones por conector).
Los Procedures sin conectores de datos no muestran indicador; los conectores con cero ejecuciones se consideran saludables.
Estados de salud
Estado | Criterio | Implicación |
🟢 Saludable | Todos los conectores tienen una tasa de éxito >95% y un tamaño promedio de respuesta menor a 50KB. | Funcionando de manera óptima. |
🟡 Degradado | Cualquier conector tiene una tasa de éxito del 80–95%, o tasa de éxito >95% pero tamaño promedio de respuesta ≥50KB (~15K tokens). | Experimentando problemas o devolviendo respuestas grandes que pueden aumentar el riesgo de alucinaciones. |
🔴 No saludable | Cualquier conector tiene una tasa de éxito <80%, o tamaño promedio de respuesta ≥100KB (~30K tokens). | Problemas críticos o respuestas peligrosamente grandes que requieren atención inmediata. |
Desglose
Al hacer clic en el sello de salud se abre un panel con un desglose por conector: estado, tasa de éxito, tamaño promedio de respuesta, latencia P90 y principales errores. Los nombres de los conectores enlazan directamente a su página de configuración para una depuración rápida.
Consejo: Si un conector muestra Degradado o No saludable debido al tamaño de la respuesta, consulte la mejor práctica Optimice sus respuestas de API para que sean el subconjunto más pequeño posible de datos relevantes que Fin necesita arriba; filtrar campos o usar bloques de código para recortar la respuesta antes de que Fin la vea es la solución más rápida.
Manejo de arreglos
Cuando un conector de datos devuelve una lista, Fin expone solo el arreglo raíz como un atributo. Los elementos hijos dentro del arreglo no se exponen como atributos separados en el selector de atributos.
Por ejemplo, si un conector devuelve un arreglo items, verá:
Obtener pedidos > items
Pero no verá:
Obtener pedidos > items > titleObtener pedidos > items > price
Fin aún puede trabajar con el contenido de una lista. Por ejemplo, si proporciona la siguiente instrucción: "Si el cliente pregunta qué hay en su pedido, use Obtener pedido > items para listar los productos y sus precios."
Fin leerá el contenido completo de la lista de items y responderá con: "Su pedido incluye un Mouse inalámbrico ($24.99) y un soporte para laptop ($39.99)."
Por ejemplo: Para la carga útil de respuesta a continuación, solo el elemento del arreglo raíz items se expone como un atributo temporal y no sus hijos.
{
"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
}
]
}
Nota: @Read Obtener pedidos > items y dígale al cliente los tres artículos principales en su pedido.
Uso de arreglos en condiciones de código
Los atributos de arreglo están disponibles bajo el objeto inputs["data_connector"], agrupados por nombre de conector de datos. Los arreglos están indexados desde cero, lo que significa que el primer elemento está en el índice 0. Siempre verifique la longitud del arreglo antes de acceder a un índice específico.
Aún puede consultar valores dentro de un arreglo usando una condición de código.
En condiciones de código, los datos del arreglo se acceden usando expresiones Python, donde se hace referencia explícita a los elementos por índice o se itera sobre la lista.
Esta condición verifica que el pedido contenga al menos cuatro artículos, y que la cantidad del cuarto artículo sea mayor que tres.
Siempre valide la longitud del arreglo antes de acceder a un índice para evitar errores en tiempo de ejecución durante la evaluación de condiciones.
Nota: Las acciones disponibles dependen de cómo esté configurado su conector de datos.
Los conectores de datos soportan:
Crear: Use solicitudes POST para crear nuevos registros en un sistema externo.
Leer: Use solicitudes GET para recuperar datos existentes.
Actualizar: Use solicitudes PUT o PATCH para modificar registros existentes.
Eliminar: Use solicitudes DELETE para eliminar registros.