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 mantenerlos seguros.
Colección API REST de Braze
| Colección | Propósito |
|---|---|
| Catálogos | Crea y administra catálogos y artículos de catálogo para referenciarlos en tus campañas Braze. |
| Ingesta de datos de Cloud | Gestiona las integraciones y sincronizaciones de tu almacén de datos. |
| Listas y direcciones de correo electrónico | Configura y gestiona la sincronización bidireccional entre Braze y tus sistemas de correo electrónico. |
| Exportar | Accede y exporta varios detalles de tus campañas, Canvases, KPIs y mucho más. |
| Mensajes | Programa, envía y gestiona tus campañas y Lienzos. |
| Centro de preferencias | Construye tu centro de preferencias y actualiza su estilo. |
| SCIM | Administra las identidades de los usuarios en aplicaciones y servicios basados en la nube. |
| SMS | Gestiona los números de teléfono de tus usuarios en tus grupos de suscripción. |
| Grupos de suscripción | Enumera y actualiza los grupos de suscripción por SMS y correo electrónico almacenados en el panel Braze. |
| Plantillas | Crea y actualiza plantillas para mensajes por correo electrónico y bloques de contenido. |
| Datos de usuario | Identifica, sigue y administra a tus usuarios. |
Definiciones de la API
Lo que sigue es 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 panel y puntos finales REST. Cuando se aprovisione tu cuenta, accederás a 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][support] o utiliza la siguiente tabla para hacer coincidir la URL del panel que utilizas con el REST Endpoint correcto.
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 SDK, no el punto final REST.
| Instancia | URL | punto final REST | punto final SDK |
| |— | — | — | |
| US-01 | https://dashboard-01.braze.com |
https://rest.iad-01.braze.com |
sdk.iad-01.braze.com |
| US-02 | https://dashboard-02.braze.com |
https://rest.iad-02.braze.com |
sdk.iad-02.braze.com |
| US-03 | https://dashboard-03.braze.com |
https://rest.iad-03.braze.com |
sdk.iad-03.braze.com |
| US-04 | https://dashboard-04.braze.com |
https://rest.iad-04.braze.com |
sdk.iad-04.braze.com |
| US-05 | https://dashboard-05.braze.com |
https://rest.iad-05.braze.com |
sdk.iad-05.braze.com |
| US-06 | https://dashboard-06.braze.com |
https://rest.iad-06.braze.com |
sdk.iad-06.braze.com |
| US-07 | https://dashboard-07.braze.com |
https://rest.iad-07.braze.com |
sdk.iad-07.braze.com |
| US-08 | https://dashboard-08.braze.com |
https://rest.iad-08.braze.com |
sdk.iad-08.braze.com |
| US-10 | https://dashboard-10.braze.com |
https://rest.us-10.braze.com |
sdk.us-10.braze.com |
| EU-01 | https://dashboard-01.braze.eu |
https://rest.fra-01.braze.eu |
sdk.fra-01.braze.eu |
| EU-02 | https://dashboard-02.braze.eu |
https://rest.fra-02.braze.eu |
sdk.fra-02.braze.eu |
| AU-01 | https://dashboard.au-01.braze.com |
https://rest.au-01.braze.com |
sdk.au-01.braze.com |
Límites de API
Para la mayoría de las API, Braze tiene un límite de velocidad predeterminado de 250 000 solicitudes por hora. Sin embargo, a determinados tipos de solicitudes se les aplica su propio límite de velocidad para gestionar mejor los grandes volúmenes de datos de nuestra base de clientes. Para más detalles, consulta los límites de velocidad de las API
ID de usuario
- ID externo del usuario: La dirección
external_idsirve 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. - Braze ID de usuario:
braze_idsirve como identificador único de usuario que establece Braze. Este identificador puede utilizarse para eliminar usuarios a través de la API REST, además de 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 interfaz de programación de aplicaciones REST (clave de REST API) es un código único que se introduce en una API para autenticar la llamada a la API e identificar la aplicación o el usuario que realiza la llamada. El acceso a la API se realiza mediante solicitudes web HTTPS al punto final de la API REST de tu empresa. En Braze utilizamos claves de API REST junto con nuestras claves de identificador de aplicaciones para realizar el seguimiento, acceder, enviar, exportar y analizar datos, con el fin de asegurarnos de que todo funciona correctamente, tanto por tu parte como por la nuestra.
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 API REST 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 en la API. Cada llamada a la API tiene que incluir una clave con acceso al punto final.
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 API REST. Estas API REST se utilizan para hacer un seguimiento de los usuarios, enviar mensajes, exportar datos de usuario, etc. Cuando crees una nueva clave de API REST, tendrás que 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.
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 cosas concretas como aplicaciones, plantillas, lienzos, campañas, tarjetas de contenido y segmentos de la API. Para más información, consulta Tipos de identificadores API.
Crear claves de API REST
Para crear una nueva clave de API REST:
- Ve a Configuración > API e identificadores.
- Selecciona Crear clave de API.
- Asigna un nombre a tu nueva clave para identificarla de un vistazo.
- Especifica las direcciones IP y subredes permitidas para la nueva clave.
- Selecciona los permisos que quieres asociar a tu nueva clave.
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 Configuración > API e identificadores, y selecciona tu clave de API.
| Permiso | Punto de conexión | Descripción |
|---|---|---|
users.track |
/users/track |
Registra atributos de usuario, eventos personalizados y compras. |
users.delete |
/users/delete |
Elimina cualquier usuario. |
users.alias.new |
/users/alias/new |
Crea un nuevo alias para un usuario existente. |
users.identify |
/users/identify |
Identifica a un usuario de sólo alias con un ID externo. |
users.export.ids |
/users/export/ids |
Consulta la información del perfil de usuario por ID de usuario. |
users.export.segment |
/users/export/segment |
Consulta la información del perfil de usuario por segmentos. |
users.merge |
/users/merge |
Fusiona dos usuarios existentes entre sí. |
users.external_ids.rename |
/users/external_ids/rename |
Cambia el ID externo de un usuario existente. |
users.external_ids.remove |
/users/external_ids/remove |
Elimina el ID externo de un usuario existente. |
users.alias.update |
/users/alias/update |
Actualiza un alias para un usuario existente. |
users.export.global_control_group |
/users/export/global_control_group |
Consulta la información del perfil de usuario en el grupo de control global. |
| Permiso | Punto de conexión | Descripción |
|---|---|---|
email.unsubscribe |
/email/unsubscribes |
Consulta las direcciones de correo electrónico que han cancelado su suscripción. |
email.status |
/email/status |
Cambia el estado de la dirección de correo electrónico. |
email.hard_bounces |
/email/hard_bounces |
Consulta las direcciones de correo electrónico en rebote duro. |
email.bounce.remove |
/email/bounce/remove |
Elimina direcciones de correo electrónico de tu lista de rebote duro. |
email.spam.remove |
/email/spam/remove |
Elimina direcciones de correo electrónico de tu lista de correo no deseado. |
email.blacklist |
/email/blacklist |
Direcciones de correo electrónico de la lista de bloqueo. |
| Permiso | Punto de conexión | Descripción |
|---|---|---|
messages.send |
/messages/send |
Envía un mensaje inmediato a usuarios concretos. |
messages.schedule.create |
/messages/schedule/create |
Programa un mensaje para que se envíe a una hora específica. |
messages.schedule.update |
/messages/schedule/update |
Actualiza un mensaje programado. |
messages.schedule.delete |
/messages/schedule/delete |
Elimina un mensaje programado. |
messages.schedule_broadcasts |
/messages/scheduled_broadcasts |
Consulta todos los mensajes emitidos programados. |
messages.live_activity.update |
/messages/live_activity/update |
Actualiza una Actividad en vivo de iOS. |
| Permiso | Punto de conexión | Descripción |
|---|---|---|
campaigns.trigger.send |
/campaigns/trigger/send |
Desencadenar el envío de una campaña existente. |
campaigns.trigger.schedule.create |
/campaigns/trigger/schedule/create |
Programa un envío futuro de una campaña con entrega desencadenada por API. |
campaigns.trigger.schedule.update |
/campaigns/trigger/schedule/update |
Actualiza una campaña programada con entrega desencadenada por API. |
campaigns.trigger.schedule.delete |
/campaigns/trigger/schedule/delete |
Elimina una campaña programada con entrega desencadenada por API. |
campaigns.list |
/campaigns/list |
Consulta una lista de campañas. |
campaigns.data_series |
/campaigns/data_series |
Consulta los análisis de la campaña en un intervalo de tiempo. |
campaigns.details |
/campaigns/details |
Consulta los detalles de una campaña concreta. |
sends.data_series |
/sends/data_series |
Consulta el análisis del envío de mensajes a lo largo de un intervalo de tiempo. |
sends.id.create |
/sends/id/create |
Crea un ID de envío para el seguimiento de la difusión de mensajes. |
campaigns.url_info.details |
/campaigns/url_info/details |
Consulta los detalles de la URL de una variación de mensaje concreta dentro de una campaña. |
transactional.send |
/transactional/v1/campaigns/{campaign_id}/send |
Permite enviar mensajes transaccionales utilizando el punto final de mensajería transaccional. |
| Permiso | Punto de conexión | Descripción |
|---|---|---|
canvas.trigger.send |
/canvas/trigger/send |
Desencadena el envío de un Canvas existente. |
canvas.trigger.schedule.create |
/canvas/trigger/schedule/create |
Programa el envío futuro de un Canvas con entrega desencadenada por API. |
canvas.trigger.schedule.update |
/canvas/trigger/schedule/update |
Actualiza un Canvas programado con entrega desencadenada por API. |
canvas.trigger.schedule.delete |
/canvas/trigger/schedule/delete |
Elimina un Canvas programado con entrega desencadenada por API. |
canvas.list |
/canvas/list |
Consulta una lista de Canvas. |
canvas.data_series |
/canvas/data_series |
Consulta el análisis de Canvas a lo largo de un intervalo de tiempo. |
canvas.details |
/canvas/details |
Consulta los detalles de un Canvas concreto. |
canvas.data_summary |
/canvas/data_summary |
Consulta el acumulado del análisis de Canvas a lo largo de un intervalo de tiempo. |
canvas.url_info.details |
/canvas/url_info/details |
Consulta los detalles de la URL de una variación específica de un mensaje dentro de un paso en Canvas. |
| Permiso | Punto de conexión | Descripción |
|---|---|---|
segments.list |
/segments/list |
Consulta una lista de segmentos. |
segments.data_series |
/segments/data_series |
Consulta el análisis de segmentos en un intervalo de tiempo. |
segments.details |
/segments/details |
Consulta los detalles de un segmento concreto. |
| Permiso | Punto de conexión | Descripción |
|---|---|---|
purchases.product_list |
/purchases/product_list |
Consulta una lista de los productos adquiridos en tu aplicación. |
purchases.revenue_series |
/purchases/revenue_series |
Consulta el total de dinero gastado al día en tu aplicación durante un intervalo de tiempo. |
purchases.quantity_series |
/purchases/quantity_series |
Consulta el número total de compras diarias en tu aplicación en un intervalo de tiempo. |
| Permiso | Punto de conexión | Descripción |
|---|---|---|
events.list |
/events/list |
Consulta una lista de eventos personalizados. |
events.data_series |
/events/data_series |
Consulta las apariciones de un evento personalizado en un intervalo de tiempo. |
News Feed is being deprecated. We recommend migrating to our Content Cards messaging channel instead—it’s more flexible, customizable, and reliable. To get started, check out Migrating from News Feed.
| Permiso | Punto de conexión | Descripción |
|---|---|---|
feed.list |
/feed/list |
Consulta una lista de tarjetas de canal de noticias. |
feed.data_series |
/feed/data_series |
Consulta el análisis de un canal de noticias a lo largo de un intervalo de tiempo. |
feed.details |
/feed/details |
Consulta los detalles de un canal de noticias concreto. |
| Permiso | Punto de conexión | Descripción |
|---|---|---|
sessions.data_series |
/sessions/data_series |
Consulta las sesiones diarias durante un intervalo de tiempo. |
| Permiso | Punto de conexión | Descripción |
|---|---|---|
kpi.dau.data_series |
/kpi/dau/data_series |
Consulta los usuarios activos únicos al día durante un intervalo de tiempo. |
kpi.mau.data_series |
/kpi/mau/data_series |
Consulta el total de usuarios activos únicos durante un período acumulado de 30 días durante un intervalo de tiempo. |
kpi.new_users.data_series |
/kpi/new_users/data_series |
Consulta los usuarios nuevos al día durante un intervalo de tiempo. |
kpi.uninstalls.data_series |
/kpi/uninstalls/data_series |
Consulta las desinstalaciones de aplicación por día durante un intervalo de tiempo. |
| Permiso | Punto de conexión | Descripción |
|---|---|---|
templates.email.create |
/templates/email/create |
Crea una nueva plantilla de correo electrónico en el panel. |
templates.email.info |
/templates/email/info |
Consulta información sobre una plantilla concreta. |
templates.email.list |
/templates/email/list |
Consulta una lista de plantillas de correo electrónico. |
templates.email.update |
/templates/email/update |
Actualiza una plantilla de correo electrónico almacenada en el panel. |
| Permiso | Descripción |
|---|---|
sso.saml.login |
Configura la sesión iniciada por el proveedor de identidad. Para más información, consulta el inicio de sesión iniciado por el proveedor de servicios (SP). |
| Permiso | Punto de conexión | Descripción |
|---|---|---|
content_blocks.info |
/content_blocks/info |
Consulta información sobre una plantilla concreta. |
content_blocks.list |
/content_blocks/list |
Consulta una lista de bloques de contenido. |
content_blocks.create |
/content_blocks/create |
Crea un nuevo bloque de contenido en el panel. |
content_blocks.update |
/content_blocks_update |
Actualiza un bloque de contenido existente en el panel. |
| Permiso | Punto de conexión | Descripción |
|---|---|---|
preference_center.get |
/preference_center/v1/{preferenceCenterExternalId} |
Consigue un centro de preferencias. |
preference_center.list |
/preference_center/v1/list |
Haz una lista de los centros de preferencias. |
preference_center.update |
/preference_center/v1/preference_center/v1/{preferenceCenterExternalID} |
Crea o actualiza un centro de preferencias. |
preference_center.user.get |
/preference_center/v1/{preferenceCenterExternalId}/url/{userId} |
Consigue un enlace a un centro de preferencias para un usuario. |
| Permiso | Punto de conexión | Descripción |
|---|---|---|
subscription.status.set |
/subscription/status/set |
Configura el estado del grupo de suscripción. |
subscription.status.get |
/subscription/status/get |
Consigue el estado del grupo de suscripción. |
subscription.groups.get |
/subscription/user/status |
Obtén el estado de los grupos de suscripción a los que están suscritos y cancelados explícitamente determinados usuarios. |
| Permiso | Punto de conexión | Descripción |
|---|---|---|
sms.invalid_phone_numbers |
/sms/invalid_phone_numbers |
Consulta los números de teléfono no válidos. |
sms.invalid_phone_numbers.remove |
/sms/invalid_phone_numbers/remove |
Retira la marca de número de teléfono no válido de los usuarios. |
| Permiso | Punto de conexión | Descripción |
|---|---|---|
catalogs.add_items |
/catalogs/{catalog_name}/items |
Añade varios elementos a un catálogo existente. |
catalogs.update_items |
/catalogs/{catalog_name}/items |
Actualiza varios elementos en un catálogo existente. |
catalogs.delete_items |
/catalogs/{catalog_name}/items |
Elimina varios elementos de un catálogo existente. |
catalogs.get_item |
/catalogs/{catalog_name}/items/{item_id} |
Consigue un elemento único de un catálogo existente. |
catalogs.update_item |
/catalogs/{catalog_name}/items/{item_id} |
Actualiza un elemento único en un catálogo existente. |
catalogs.create_item |
/catalogs/{catalog_name}/items/{item_id} |
Crea un elemento único en un catálogo existente. |
catalogs.delete_item |
/catalogs/{catalog_name}/items/{item_id} |
Elimina un elemento único de un catálogo existente. |
catalogs.replace_item |
/catalogs/{catalog_name}/items/{item_id} |
Sustituye un elemento único de un catálogo existente. |
catalogs.create |
/catalogs |
Crea un catálogo. |
catalogs.get |
/catalogs |
Obtener una lista de catálogos |
catalogs.delete |
/catalogs/{catalog_name} |
Borrar un catálogo. |
catalogs.get_items |
/catalogs/{catalog_name}/items |
Obtén una vista previa de un catálogo existente. |
catalogs.replace_items |
/catalogs/{catalog_name}/items |
Reemplazar elementos de un catálogo existente. |
Gestión de claves de API REST
Puedes ver los detalles de las claves de API REST existentes o eliminarlas desde Configuración > API e identificadores > pestaña Claves de API. Ten en cuenta que las claves de API REST no se pueden editar una vez creadas.
La pestaña Claves de API incluye la siguiente información para cada clave:
| Campo | Descripción |
|---|---|
| Nombre de clave de API | El nombre dado a la clave en el momento de su creación. |
| Identificador | La clave de API. |
| Creación a cargo de | La dirección de correo electrónico del usuario que creó la clave. Este campo aparecerá como “N/A” para las claves creadas antes de junio de 2023. |
| Fecha de creación | La fecha de creación de esta clave. |
| Visto por última vez | La fecha en que se utilizó esta clave por última vez. Este campo aparecerá como “N/A” para las claves que nunca se hayan utilizado. |
Para ver los detalles de una clave de API, pasa el ratón por encima de la clave y selecciona Ver. 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, no se eliminarán las claves de API asociadas que haya creado. Para borrar una tecla, pasa el ratón sobre ella y selecciona Borrar.
Seguridad de la clave de API REST
Las claves de API se utilizan para autenticar una llamada a la API. Cuando se crea 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 API REST potencialmente sensibles, protege estas claves y compártelas sólo con socios de confianza. Nunca pueden quedar expuestas al público. 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 sólo 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.
Dado que las claves de API REST permiten acceder a puntos finales de API REST 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 se produce una exposición accidental de una clave, puede borrarse desde la consola para desarrolladores. Si necesitas ayuda con este proceso, abre un [ticket de soporte][support].
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 API REST para una clave de API REST determinada. Esto se denomina lista blanca o lista permitida. Para permitir direcciones IP o subredes específicas, añádelas a la sección IPs de la lista blanca al crear una nueva clave de API REST:
Si no especificas ninguna, las peticiones pueden enviarse desde cualquier dirección IP.
¿Hacer un webhook Braze to Braze y utilizar allowlisting? Consulta nuestra lista blanca de IPs.
Recursos adicionales
Biblioteca cliente Ruby
Si estás implementando Braze utilizando Ruby, puedes utilizar nuestra biblioteca cliente 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 Usuario.
Esta biblioteca cliente está actualmente en fase beta. ¿Quieres ayudarnos a mejorar esta biblioteca? Envíanos tus comentarios a [email protected].
Editar esta página en GitHub