Resumen de la API

Este artículo de referencia cubre los conceptos básicos de la API, incluida la terminología común y un resumen de las claves de la API REST, los permisos y cómo mantenerlas seguras.

Colección API REST de Braze

Definiciones de la API

A continuación encontrarás un resumen de los términos que puedes ver en la documentación de la API REST de Braze.

Puntos finales

Braze gestiona varias instancias diferentes para nuestro dashboard y puntos finales REST. Cuando tu cuenta esté aprovisionada, iniciarás sesión en una de las siguientes URL. Utiliza el punto final REST correcto en función de la instancia a la que estés aprovisionado. Si no estás seguro, abre un ticket de soporte o utiliza la siguiente tabla para emparejar la URL del dashboard que utilizas con el punto final REST correcto.

Para encontrar tu punto final REST en Braze:

1. Inicia sesión en Braze y ve a Settings > APIs and Identifiers > API Keys.
2. Selecciona una clave de API existente o selecciona Create API Key para crear una nueva.
3. Copia el punto final REST que se muestra en esta pestaña y utilízalo para tus solicitudes de API.

Importante

Cuando utilices puntos finales para las llamadas a la API, utiliza el punto final REST.

Para la integración de SDK, utiliza el punto final de SDK, no el punto final REST.

Límites de la API

Para la mayoría de las API, Braze tiene un límite de velocidad predeterminado de 250 000 solicitudes por hora. Sin embargo, ciertos tipos de solicitudes tienen su propio límite de velocidad para gestionar mejor los grandes volúmenes de datos de la base de clientes. Para más detalles, consulta los límites de velocidad de la API.

ID de usuario

• ID externo de usuario: El external_id sirve como identificador único del usuario cuyos datos envías. Este identificador debe ser el mismo que el que estableciste en el SDK de Braze para evitar crear varios perfiles para el mismo usuario.
• ID de usuario de Braze: braze_id sirve como identificador único de usuario establecido por Braze. Puedes utilizar este identificador para eliminar usuarios a través de la REST API, además de los external_ids.

Para más información, consulta los siguientes artículos en función de tu plataforma: iOS, Android y Web.

Acerca de las claves de API REST

Una clave de API REST (clave de interfaz de programación de aplicaciones REST) es un código único que se pasa a una API para autenticar la llamada e identificar la aplicación o el usuario que realiza la llamada. Accedes a la API mediante solicitudes web HTTPS al punto final de la REST API de tu empresa. Las claves de API REST funcionan en conjunto con las claves identificadoras de aplicaciones para realizar el seguimiento, acceder, enviar, exportar y analizar datos con el fin de garantizar que todo funcione correctamente.

Los espacios de trabajo y las claves de API van de la mano en Braze. Los espacios de trabajo están diseñados para albergar versiones de la misma aplicación en varias plataformas. Muchos clientes también utilizan espacios de trabajo para contener versiones gratuitas y premium de sus aplicaciones en la misma plataforma. Como puedes observar, estos espacios de trabajo también utilizan la REST API y tienen sus propias claves de API REST. Se puede definir individualmente el ámbito de estas claves para que incluyan acceso a puntos finales específicos de la API. Cada llamada a la API tiene que incluir una clave con acceso al punto final correspondiente.

Nos referimos tanto a la clave de la API REST como a la clave de la API del espacio de trabajo como api_key. El api_key se incluye en cada solicitud como encabezado de solicitud y actúa como clave de autenticación que te permite utilizar nuestras REST API. Estas REST API se utilizan para rastrear usuarios, enviar mensajes, exportar datos de usuario, etc. Cuando crees una nueva clave de API REST, debes darle acceso a puntos finales específicos. Al asignar permisos específicos a una clave de API, puedes limitar exactamente qué llamadas puede autenticar dicha clave.

Consejo

Además de las claves de API REST, también existe un tipo de clave llamada clave identificadora que puede utilizarse para hacer referencia a elementos concretos como aplicaciones, plantillas, Canvas, Campaigns, Content Cards y Segments desde la API. Para más información, consulta Tipos de identificadores de API.

Crear claves de API REST

Para crear una nueva clave de API REST:

1. Ve a Settings > APIs and Identifiers.
2. Selecciona Create API Key.
3. Asigna un nombre a tu nueva clave para identificarla de un vistazo.
4. Especifica las direcciones IP y subredes permitidas para la nueva clave.
5. Selecciona los permisos que quieres asociar a tu nueva clave.

Importante

Ten en cuenta que después de crear una nueva clave de API, no puedes editar el alcance de los permisos ni las IP permitidas. Esta limitación se aplica por motivos de seguridad. Si necesitas cambiar el alcance de una clave, crea una nueva con los permisos actualizados e implementa esa clave en lugar de la anterior. Cuando hayas completado la implementación, puedes eliminar la clave antigua.

Permisos de la clave de API REST

Los permisos de clave de API son permisos que puedes asignar a un usuario o grupo para limitar su acceso a determinadas llamadas de API. Para ver tu lista de permisos de clave de API, ve a Settings > APIs and Identifiers y selecciona tu clave de API.

• user data
• email
• messages
• campaigns
• canvas
• segments
• purchases
• events
• sessions
• kpis
• templates
• sso
• content blocks
• preference center
• subscription
• sms
• catalogs
• sdk authentication

Gestión de claves de API REST

Puedes ver los detalles de las claves de API REST existentes o eliminarlas desde Settings > APIs and Identifiers > pestaña API Keys. Ten en cuenta que no puedes editar las claves de API REST después de crearlas.

La pestaña API Keys incluye la siguiente información para cada clave:

Para ver los detalles de una clave de API, pasa el cursor por encima de la clave y selecciona View. Esto incluye todos los permisos que tiene esta clave, las IP de la lista blanca (si las hay) y si esta clave está incluida en la lista blanca de IP de Braze.

Ten en cuenta que, al eliminar un usuario, Braze no elimina las claves de API asociadas que ese usuario haya creado. Para eliminar una clave, pasa el cursor sobre ella y selecciona Delete.

Seguridad de la clave de API REST

Las claves de API se utilizan para autenticar una llamada a la API. Cuando creas una nueva clave de API REST, es necesario darle acceso a puntos finales específicos. Al asignar permisos específicos a una clave de API, puedes limitar exactamente qué llamadas puede autenticar dicha clave.

Dado que las claves de API REST permiten acceder a puntos finales de REST API potencialmente sensibles, protege estas claves y compártelas solo con socios de confianza. Nunca deben quedar expuestas públicamente. Por ejemplo, no utilices esta clave para hacer llamadas AJAX desde tu sitio web ni la expongas de ninguna otra forma pública.

Una buena práctica de seguridad es asignar a un usuario solo el acceso necesario para completar su trabajo: este principio también puede aplicarse a las claves de API asignando permisos a cada clave. Estos permisos te proporcionan mayor seguridad y control sobre las distintas áreas de tu cuenta.

Advertencia

Dado que las claves de API REST permiten acceder a puntos finales de REST API potencialmente sensibles, asegúrate de que se almacenan y utilizan de forma segura. Por ejemplo, no utilices esta clave para hacer llamadas AJAX desde tu sitio web ni la expongas de ninguna otra forma pública.

Si expones una clave accidentalmente, puedes eliminarla de la consola para desarrolladores. Para obtener ayuda con este proceso, abre un ticket de soporte.

Seguridad de las claves de API REST y las claves de API de SDK

Las claves de API REST y las claves de API de SDK tienen perfiles de seguridad diferentes.

Lista de direcciones IP permitidas de la API

Para mayor seguridad, puedes especificar una lista de direcciones IP y subredes a las que se permite realizar solicitudes de REST API para una clave de API REST determinada. Esto se denomina lista permitida o lista blanca. Para permitir direcciones IP o subredes específicas, añádelas a la sección Whitelist IPs al crear una nueva clave de API REST:

Si no especificas ninguna, las solicitudes pueden enviarse desde cualquier dirección IP.

Consejo

Si estás creando un webhook de Braze a Braze y utilizas listas de permitidos, consulta la lista de direcciones IP que debes incluir en la lista blanca.

Autenticación y seguridad de la API

Autenticación mediante token de portador

Braze autentica las solicitudes de la REST API utilizando la clave de API REST pasada como token Bearer en el encabezado de solicitud Authorization. Cuando envíes una solicitud, incluye tu clave de API en el siguiente formato:

1
Authorization: Bearer YOUR_REST_API_KEY

En cada solicitud, Braze realiza las siguientes comprobaciones de validación del lado del servidor:

1. Validez del token: Verifica que la clave de API REST existe en Braze y está activa (por ejemplo, que no ha sido revocada ni desactivada).
2. Autorización del token: Confirma que la clave de API tiene los permisos necesarios para el punto final solicitado.

Si la autenticación falla, la API devuelve una respuesta de error con un código de estado HTTP. Por ejemplo, 401 Unauthorized indica una clave no válida o ausente, mientras que 403 Forbidden indica que la clave no tiene permiso para el punto final solicitado. Para obtener más información, consulta Errores de API.

Seguridad a nivel de red

Las solicitudes de REST API a Braze están protegidas por el cifrado Transport Layer Security (TLS) en toda la ruta de la solicitud. La siguiente tabla describe el flujo de red para una solicitud de API desde tu servidor a Braze:

El cifrado TLS cubre todos los eslabones de la cadena. Tu servidor se conecta a Cloudflare a través de TLS, y Cloudflare establece una conexión TLS independiente a través del NLB con el ingreso NGINX, por lo que tu clave de API y los datos de la solicitud permanecen cifrados durante la transmisión.

Recursos adicionales

Biblioteca cliente Ruby

Si estás implementando Braze con Ruby, puedes utilizar la biblioteca de clientes Ruby para reducir el tiempo de importación de datos. Una biblioteca cliente es una colección de código específico de un lenguaje de programación —en este caso, Ruby— que facilita el uso de una API.

La biblioteca cliente Ruby admite los puntos finales de usuario.

Importante

Esta biblioteca de clientes se encuentra en fase beta. Para ayudar a mejorar esta biblioteca, envía tus comentarios a [email protected].