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 tu espacio de trabajo Fin.
Uso de APIs de terceros (Shopify, WooCommerce, etc.)
Si estás utilizando APIs de terceros (no construidas internamente) con Data Connectors en tu espacio de trabajo Fin, 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 aún contiene instrucciones útiles, 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 tu espacio de trabajo Fin.
Consideraciones sobre autenticación e identidad
Cómo proteger a tus users y la entrada de users para su uso 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 tuyas o de APIs 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 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.
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 adecuados para manejar la autenticación y autorización.
Cómo configurar de forma segura la llamada API de tus Data Connectors
Actualmente soportamos tokens estáticos, tokens HTTP y OAuth. Sea cual sea el token que uses, es tu responsabilidad asegurarte de que se mantenga en secreto y se actualice lo antes posible si se filtra en algún lugar. Como buena práctica, recomendamos usar tokens OAuth siempre que sea posible.
Nota: Contáctanos vía Messenger para más información sobre el acceso a OAuth.
Consideraciones sobre datos
Idealmente, la API solo debería devolver los datos necesarios para tu Task/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 Data Connectors.
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 del 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.
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 podrían tardar más en completarse, sugerimos usar la funcionalidad “Wait for webhook” en su lugar.Data Connectors pueden acceder fácilmente a atributos y arreglos anidados de 1 a 2 niveles, pero objetos complejos que incluyen arreglos profundamente anidados son más adecuados para procesarse con Fin Tasks. Si intentas usar estos tipos de objetos de respuesta con un Data Connector podrías encontrar dificultades. Sin embargo, Fin Tasks los maneja mejor.
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 conocido y seguro) y dejar que elija de una lista desplegable.
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 saneamiento de entradas a los datos entrantes, reconociendo campos generados por AI que pueden contener contenido alucinatorio o malicioso.
Usa códigos de error HTTP estándar para ayudar a Fin a responder adecuadamente. Por ejemplo, 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 Data Connectors en vivo de Fin entre versiones (por ejemplo, /v1/orders a /v2/orders).