Data connectors usan APIs para conectarse a sistemas externos y obtener y/o actualizar datos existentes. Por eso es importante tener en cuenta un par de cosas al configurar Data connectors en Intercom.
Uso de APIs de terceros (Shopify, WooCommerce, etc.)
Si utilizas APIs de terceros (no construidas internamente) con Data connectors en Intercom, probablemente tengas poco o ningún control sobre cómo funcionan o la respuesta que recibes de una solicitud.
Dicho esto, la guía a continuación sigue siendo útil, pero algunas secciones pueden no ser totalmente aplicables a tu caso de uso.
Uso de APIs propias
Nuestros ingenieros han compilado una lista de puntos a tener en cuenta al diseñar o modificar tus APIs existentes para trabajar con Fin y Data connectors en Intercom.
Consideraciones sobre autenticación e identidad
Cómo proteger a tus users y la entrada de users para usar en Data connectors
Importante: Tú y/o tu equipo de seguridad deben realizar una evaluación de riesgos y valorar las consecuencias de cualquier fuga de datos.
Intercom no aceptará ni puede aceptar ninguna responsabilidad por datos filtrados debido a prácticas deficientes de autenticación e identificación de tus APIs o de terceros.
Primero, recomendamos encarecidamente que actives la seguridad del Messenger con JWTs. Proteger tu Messenger es el control de seguridad más importante para configurar en tu integración.
También te permite firmar múltiples atributos a través de nuestra API de JavaScript, para que puedas enviar datos sobre tus users de forma segura a través del Messenger en lugar de tener que usar otra integración, por ejemplo: REST API.
Para aprovechar los beneficios de enviar datos de forma segura, puedes proteger tus atributos de actualizaciones inseguras del Messenger y entonces cualquier JWT enviado, que consideramos una fuente segura, seguirá actualizando ese campo en el user. Esto es crucial para Data connectors, cuando el Data connector muestra datos sensibles o manipula datos.
Por ejemplo, si tu Data connector hace una solicitud a la API usando “GET /accounts/<account_id>/invoices” entonces quieres asegurarte de que account_id esté protegido para que el user no pueda simplemente enumerar account_ids recopilando datos. Sin embargo, si tu Data connector es "GET /pizza-order-status/<order_id>" entonces puede que no te importe la confiabilidad de "order_id" y no te importa si esta información se mostró a la persona correcta.
Además, debes asegurarte de que el atributo que tu Data connector usa para identificar de forma única a tus users (correo electrónico, por ejemplo) sea confiable. Esto significa que necesitas saber que confías en la fuente de los atributos identificativos de tu Data connector. Por ejemplo, si tu Data connector identifica al user por user_id, la verificación de identidad es firmar el atributo user_id o si tu Data connector identifica al user por correo electrónico u otro atributo, entonces ese atributo está protegido y no se recopila del End User sin alguna verificación.
Esto previene que actores maliciosos puedan, por ejemplo, proporcionar la dirección de correo electrónico de otra persona y acceder a un Data connector como “Obtener extractos bancarios por correo electrónico”, lo que expondría datos financieros sensibles.
Cuando sea posible, sugerimos que no uses el correo electrónico como identificador principal para obtener datos de tus users, sino algo más aleatorio como un ID de user único y no adivinable.
Para realizar la verificación de identidad en leads, nuestro equipo está trabajando actualmente en una función de Contraseña de un solo uso (OTP) que te ayudará a verificar la identidad de alguien si contacta a tu soporte como lead. Si te interesa esta función, no dudes en contactar a nuestro equipo de Soporte vía Messenger y estarán encantados de ayudarte a activarla.
También debes asegurarte de que el user no pueda realizar Data connectors que no esté autorizado a hacer, por ejemplo, cancelar el pedido de otra persona conociendo el ID del pedido. Esta lógica no se maneja dentro de Intercom y tú/tu equipo de seguridad deben realizar una evaluación de riesgos y proponer métodos apropiados para manejar la autenticación y autorización.
Cómo configurar de forma segura la llamada API de tu Data connector
Intercom actualmente soporta tokens estáticos, tokens HTTP y OAuth (beta cerrada, contáctanos vía Messenger para más información). Sea cual sea el token que uses, es tu responsabilidad asegurarte de que se mantenga en secreto y se actualice si se filtra en algún lugar lo antes posible. Como buena práctica, recomendamos usar tokens OAuth siempre que sea posible.
Consideraciones sobre datos
Idealmente, la API solo debería devolver los datos necesarios para tu Workflow. Sin embargo, esto puede ser poco realista y la API podría devolver una buena cantidad de datos que en realidad no se requieren para llevar a cabo el Workflow donde se usa el Data connector.
Si estás construyendo APIs desde cero para ser usadas exclusivamente con Data connectors y Fin Workflows, puedes:
Construir la API de manera que te permita procesar la lógica de negocio del workflow en un solo Data connector - esto ahorra en el número de llamadas API y agrupa la lógica en un solo lugar,
Construir endpoints individuales para, por ejemplo, encontrar pedidos, obtener detalles del pedido y finalmente, reembolsar el pedido - esto está en línea con los mejores principios de diseño RESTful API pero requiere múltiples llamadas API para completar un workflow (por ejemplo, reembolso de pedido)
Algunas consideraciones que deben incluirse al decidir qué y cuántos datos devuelve tu API incluyen:
¿Realmente Fin/Workflow necesita todos los datos proporcionados para completar los pasos en el workflow? Por ejemplo, si tienes un workflow para crear un reembolso de pedido, probablemente solo necesites los detalles del pedido y no datos adicionales sobre la cuenta específica del user.
Los Data connectors tienen un tiempo de espera de 15 segundos y, por lo tanto, si la API tarda demasiado en responder, podría ser buena idea considerar reducir las operaciones detrás de ella y, potencialmente, la cantidad de datos que devuelve.
Para Data connectors que puedan tardar más en completarse, sugerimos usar la funcionalidad “Esperar por webhook” en su lugar.Los Data connectors pueden acceder fácilmente a atributos y arrays anidados de 1 a 2 niveles, pero objetos complejos que incluyen arrays profundamente anidados son más adecuados para procesarse con Fin Procedures. Si intentas usar estos tipos de objetos de respuesta con un Data connector, podrías encontrar dificultades. Sin embargo, Fin Tasks los maneja mejor.
Nota: Al usar Fin Procedures, los Data connectors tienen una ventana de tiempo de espera de 30 segundos (para ciertos espacios de trabajo elegibles), en lugar de los 15 segundos predeterminados. Esta distinción es importante al diseñar Workflows con llamadas API de larga duración.
Además, siempre debes eliminar la posibilidad de que los users proporcionen datos mal formados o simplemente escriban cosas.
Por ejemplo, no deberías pedir al user que escriba su ID de cuenta, sino mostrarle sus IDs de cuenta (basados en un identificador seguro y conocido) y dejar que elija de una lista desplegable. Más información sobre cómo recopilar datos de users se puede encontrar aquí.
Otras consideraciones
Tu API debe imponer límites específicos de la aplicación, como limitar los reembolsos a una cantidad máxima por día.
Asegúrate de que tu API sea idempotente, ya que Fin puede enviar la misma solicitud de reembolso varias veces.
Implementa validación del lado del servidor para asegurar que todas las entradas cumplan con el formato especificado en tu Data connector.
Aplica sanitización de entradas a los datos entrantes, reconociendo campos generados por IA que pueden contener contenido alucinatorio o malicioso.
Usa códigos de error HTTP estándar para ayudar a Fin a responder adecuadamente. Por ejemplo, los errores HTTP 429 o 500 pueden justificar un reintento, mientras que un HTTP 410 indica que no se deben hacer más intentos.
Versiona tu API para facilitar la migración sin problemas de los Data connectors Live Fin entre versiones (por ejemplo, /v1/orders a /v2/orders).
En resumen
Protege el Messenger con JWTs para proteger los datos y atributos de los users.
Usa identificadores confiables (por ejemplo, IDs de user firmados, no correo electrónico) para obtener datos.
Restringe las acciones de los users solo a lo que están autorizados a hacer.
Evita entradas libres — usa listas desplegables de fuentes conocidas y seguras.
Elige tokens API seguros, idealmente OAuth (en beta cerrada).
Devuelve solo los datos necesarios para evitar retrasos o exposición de datos.
Usa una estructura clara de API — respuestas simples, versionado adecuado y códigos de error estándar.
Valida todas las entradas y sanitiza todo lo generado por users o IA.