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 REST API, los permisos y cómo mantenerlas seguras.

Colección de la REST API de Braze

Definiciones de la API

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

Endpoints

Braze gestiona varias instancias diferentes para nuestro panel y endpoints REST. Cuando tu cuenta es aprovisionada, inicias sesión en una de las siguientes URLs. Utiliza el endpoint REST correcto en función de la instancia a la que estés asignado. Si no estás seguro, abre un ticket de soporte o utiliza la siguiente tabla para hacer coincidir la URL del panel que utilizas con el endpoint REST correcto.

Para encontrar tu endpoint REST en Braze:

1. Inicia sesión en Braze y ve a Configuración > APIs e identificadores > Claves de API.
2. Selecciona una clave de API existente o selecciona Crear clave de API para crear una nueva.
3. Copia el endpoint REST que se muestra en esta pestaña y utiliza ese endpoint para tus solicitudes de API.

Importante

Al utilizar endpoints para llamadas a la API, usa el endpoint REST.

Para la integración de SDK, utiliza el punto final de SDK, no el endpoint 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 aplicado para manejar mejor grandes volúmenes de datos en toda la base de clientes. Para más detalles, consulta Límites de velocidad de la API

ID de usuario

• ID externo de usuario: El external_id sirve como identificador único de usuario para quien estás enviando datos. Este identificador debe ser el mismo que configuraste en el SDK de Braze para evitar crear múltiples perfiles para el mismo usuario.
• ID de usuario de Braze: braze_id sirve como identificador único de usuario que Braze establece. 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 según tu plataforma: iOS, Android y Web.

Acerca de las claves de API REST

Una clave de API REST (clave de API de interfaz de programación de aplicaciones REST) es un código único que pasas a una API para autenticar la llamada a la API e identificar la aplicación o el usuario que realiza la llamada. Accedes a la API mediante solicitudes web HTTPS al endpoint de la REST API de tu empresa. Las claves de API REST funcionan en conjunto con las claves de identificador de la aplicación para rastrear, 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 múltiples plataformas. Muchos clientes también usan espacios de trabajo para contener versiones gratuitas y de pago de sus aplicaciones en la misma plataforma. Como habrás notado, estos espacios de trabajo también hacen uso de la REST API y tienen sus propias claves de API REST. Estas claves se pueden delimitar individualmente para incluir acceso a endpoints específicos de la API. Cada llamada a la API debe incluir una clave con acceso al endpoint solicitado.

Nos referimos tanto a la clave de API REST como a la clave de API del espacio de trabajo como api_key. La api_key se incluye en cada solicitud como un encabezado de solicitud y actúa como una 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 y más. Cuando creas una nueva clave de API REST, debes otorgarle acceso a endpoints específicos. Al asignar permisos específicos a una clave de API, puedes limitar exactamente qué llamadas puede autenticar una clave de API.

Consejo

Además de las claves de API REST, también existe un tipo de clave llamada claves de identificador que se puede usar para hacer referencia a elementos específicos como aplicaciones, plantillas, Canvas, Campaigns, Content Cards y Segments desde la API. Para obtener más información, consulta Tipos de identificador de API.

Crear claves de API REST

Para crear una nueva clave de API REST:

1. Ve a Configuración > API e identificadores.
2. Selecciona Crear clave de API.
3. Asigna un nombre a tu nueva clave para identificarla fácilmente.
4. Especifica las direcciones IP incluidas en la lista blanca y las subredes para la nueva clave.
5. Selecciona qué permisos deseas asociar con tu nueva clave.

Importante

Ten en cuenta que una vez que creas una nueva clave de API, no puedes editar el alcance de los permisos ni las IP incluidas en la lista blanca. Esta limitación existe por razones de seguridad. Si necesitas cambiar el alcance de una clave, crea una nueva clave con los permisos actualizados e impleméntala en lugar de la anterior. Una vez que hayas completado la implementación, puedes eliminar la clave antigua.

Permisos de claves de API REST

Los permisos de claves 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 claves de API, ve a Configuración > API e identificadores y selecciona tu clave de API.

• datos de usuario
• correo electrónico
• mensajes
• campaigns
• canvas
• segments
• compras
• eventos
• sesiones
• indicadores clave de rendimiento
• plantillas
• sso
• content blocks
• centro de preferencias
• suscripción
• sms
• catálogos
• autenticación de sdk

Gestionar claves de API REST

Puedes ver los detalles o eliminar claves de API REST existentes desde Configuración > API e identificadores > pestaña Claves de API. Ten en cuenta que no puedes editar las claves de API REST una vez que las creas.

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

Para ver los detalles de una clave de API, pasa el cursor sobre la clave y selecciona Ver. Esto incluye todos los permisos que tiene esta clave, las IP incluidas en la lista blanca (si las hay) y si esta clave está optada 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 creó. Para eliminar una clave, pasa el cursor sobre la clave y selecciona Eliminar.

Seguridad de las claves de API REST

Las claves de API se utilizan para autenticar una llamada a la API. Cuando creas una nueva clave de API REST, necesitas otorgarle acceso a endpoints específicos. Al asignar permisos específicos a una clave de API, puedes limitar exactamente qué llamadas puede autenticar una clave de API.

Dado que las claves de API REST permiten acceso a endpoints de la REST API potencialmente sensibles, asegura estas claves y compártelas solo con partners de confianza. Nunca deben exponerse públicamente. Por ejemplo, no uses esta clave para realizar llamadas AJAX desde tu sitio web ni la expongas de ninguna otra manera 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 brindan un mejor control y seguridad sobre las diferentes áreas de tu cuenta.

Advertencia

Dado que las claves de API REST permiten acceso a endpoints de la REST API potencialmente sensibles, asegúrate de que se almacenen y utilicen de forma segura. Por ejemplo, no uses esta clave para realizar llamadas AJAX desde tu sitio web ni la expongas de ninguna otra manera pública.

Si expones una clave accidentalmente, puedes eliminarla desde 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 blanca de IP para la API

Para mayor seguridad, puedes especificar una lista de direcciones IP y subredes que tienen permiso para realizar solicitudes a la REST API para una clave de API REST determinada. Esto se conoce como lista de permitidos o lista blanca. Para permitir direcciones IP o subredes específicas, añádelas en la sección IPs en lista blanca al crear una nueva clave de API REST:

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

Consejo

Si estás creando un webhook de Braze a Braze y usas la lista de permitidos, consulta la lista de IPs a incluir en la lista blanca.

Autenticación y seguridad de la API

Autenticación con token Bearer

Braze autentica las solicitudes a la API REST utilizando la clave de API REST pasada como token Bearer en el encabezado de solicitud Authorization. Cuando envías 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 en el 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 o deshabilitada).
2. Autorización del token: Confirma que la clave de API tiene los permisos necesarios para el endpoint 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 faltante, mientras que 403 Forbidden indica que la clave no tiene permisos para el endpoint solicitado. Para más información, consulta Errores de API.

Uso de mayúsculas en los encabezados de solicitud

Los nombres de los encabezados HTTP no distinguen entre mayúsculas y minúsculas, por lo que Authorization y authorization son equivalentes. Lo mismo aplica a otros encabezados de solicitud estándar, como Content-Type. Envía el formato de mayúsculas que produzca tu cliente HTTP.

Braze también acepta cualquier variante de mayúsculas del esquema Bearer (Bearer, bearer o BEARER). Envía la clave de API REST exactamente como fue emitida.

Seguridad a nivel de red

Las solicitudes a la API REST de Braze están protegidas por cifrado de seguridad de la capa de transporte (TLS) a lo largo de toda la ruta de la solicitud. La siguiente tabla describe el flujo de red para una solicitud a la API desde tu servidor hasta Braze:

El cifrado TLS cubre cada enlace 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 hacia el NGINX ingress, de modo que tu clave de API y los datos de la solicitud permanecen cifrados en tránsito.

Recursos adicionales

Biblioteca cliente de Ruby

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

La biblioteca cliente de Ruby es compatible con los endpoints de usuario.

Importante

Esta biblioteca cliente está en fase beta. Para ayudar a mejorarla, envía tus comentarios a [email protected].