Crear y actualizar usuarios (masivo)

Utiliza este punto de conexión para registrar eventos personalizados y compras, y actualizar atributos de perfiles de usuario de forma masiva.

Importante

Este punto de conexión se encuentra actualmente en beta limitada. Aunque no estamos añadiendo nuevos clientes a la beta en este momento, comunícale a tu director de cuentas de Braze si crees que esta característica podría ser útil para tu integración con Braze.

Cuándo usar este punto de conexión

Al igual que el punto de conexión /users/track, puedes usar este punto de conexión para actualizar perfiles de usuario. Este punto de conexión es más adecuado para actualizaciones masivas:

• Solicitudes más grandes: Envía hasta 1000 usuarios por solicitud, de modo que puedas hacer menos solicitudes para grandes rellenos de datos y sincronizaciones.
• Priorización: Durante condiciones de tráfico pico, las solicitudes a /users/track tienen prioridad sobre las solicitudes a /users/track/bulk.

Usa este punto de conexión cuando estés rellenando muchos perfiles de usuario durante la incorporación, o sincronizando grandes volúmenes de perfiles como parte de una sincronización diaria.

Nota

Los límites del objeto de solicitud del punto de conexión /users/track varían según el modelo de precios y la configuración. Usa /users/track/bulk para la ingesta masiva.

Requisitos previos

Para usar este punto de conexión, necesitas una clave de API con el permiso users.track.bulk.

Si estás realizando llamadas de servidor a servidor detrás de un firewall, es posible que necesites incluir en la lista de permitidos tu punto de conexión REST de Braze (por ejemplo, rest.iad-01.braze.com). Para más información, consulta Puntos de conexión de API.

Límite de velocidad

Nota

Cada atributo personalizado enviado en una solicitud a /users/track/bulk consume un punto de datos. Para más información, consulta Puntos de datos.

Para la mayoría de los clientes, este punto de conexión tiene un límite de velocidad base de 50 solicitudes por segundo.

Los clientes con contratos más recientes pueden tener en su lugar límites de ráfaga (por segundo) y estables (por hora) basados en los usuarios activos al mes contratados.

Cada solicitud a /users/track/bulk tiene un límite de carga útil de 2 MB y puede incluir hasta 1000 objetos en total entre atributos, eventos y compras, dependiendo de la política de límite de velocidad masivo de tu cuenta.

Cada objeto puede actualizar un usuario, por lo que una sola solicitud puede actualizar hasta el límite de objetos de solicitud de tu cuenta de usuarios diferentes. Además, cada solicitud puede contener un máximo de 100 objetos por perfil de usuario entre atributos, eventos y compras.

Cuerpo de la solicitud

1
2
Content-Type: application/json
Authorization: Bearer YOUR_REST_API_KEY

1
2
3
4
5
{
  "attributes": (optional, array of attributes object),
  "events": (optional, array of event object),
  "purchases": (optional, array of purchase object)
}

Parámetros de la solicitud

Importante

Para cada objeto de solicitud, debes incluir uno de los siguientes: external_id, user_alias, braze_id, email o phone.

Ejemplos de solicitudes

Actualizar perfiles de usuario de forma masiva en una solicitud

Actualiza hasta el límite de objetos de solicitud de tu cuenta de perfiles de usuario en una sola solicitud.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
curl --location --request POST 'https://rest.iad-01.braze.com/users/track/bulk' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer YOUR_REST_API_KEY' \
--data-raw '{
  "attributes": [
    {
      "external_id": "user1",
      "string_attribute": "fruit",
      "boolean_attribute_1": true,
      "integer_attribute": 25,
      "array_attribute": [
        "banana",
        "apple"
      ]
    },
    {
      "external_id": "user2",
      "string_attribute": "vegetables",
      "boolean_attribute_1": false,
      "integer_attribute": 25,
      "array_attribute": [
        "broccoli",
        "asparagus"
      ]
    }
  ]
}'

Enviar atributos y eventos en una solicitud

Incluye atributos y eventos en la misma solicitud, hasta el límite total de objetos de tu cuenta.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
curl --location --request POST 'https://rest.iad-01.braze.com/users/track/bulk' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer YOUR_REST_API_KEY' \
--data-raw '{
  "attributes": [
    {
      "external_id": "user1",
      "string_attribute": "fruit",
      "boolean_attribute_1": true,
      "integer_attribute": 25,
      "array_attribute": [
        "banana",
        "apple"
      ]
    }
  ],
  "events": [
    {
      "external_id": "user2",
      "app_id": "your_app_identifier",
      "name": "rented_movie",
      "time": "2022-12-06T19:20:45+01:00",
      "properties": {
        "release": {
          "studio": "FilmStudio",
          "year": "2022"
        },
        "cast": [
          {
            "name": "Actor1"
          },
          {
            "name": "Actor2"
          }
        ]
      }
    }
  ]
}'

Respuestas

Mensaje de éxito

Los mensajes exitosos devuelven la siguiente respuesta:

1
2
3
4
5
6
{
  "message": "success",
  "attributes_processed": (optional, integer), if attributes are included in the request, this returns an integer of the number of external IDs with attributes that Braze queued for processing,
  "events_processed": (optional, integer), if events are included in the request, this returns an integer of the number of events that Braze queued for processing,
  "purchases_processed": (optional, integer), if purchases are included in the request, this returns an integer of the number of purchases that Braze queued for processing
}

Mensaje de éxito con errores no fatales

Si tu solicitud es exitosa pero tiene errores no fatales (por ejemplo, un objeto de evento no válido en un lote grande), recibirás la siguiente respuesta:

1
2
3
4
5
6
7
8
{
  "message": "success",
  "errors": [
    {
      <minor error message>
    }
  ]
}

Mensaje con errores fatales

Si tu solicitud tiene un error fatal, recibirás la siguiente respuesta:

1
2
3
4
5
6
7
8
{
  "message": <fatal error message>,
  "errors": [
    {
      <fatal error message>
    }
  ]
}

Códigos de respuesta de errores fatales

Para los códigos de estado y los mensajes de error asociados que Braze devuelve cuando tu solicitud tiene un error fatal, consulta Errores fatales y respuestas.

Si recibes el error “provided external_id is blacklisted and disallowed”, tu solicitud puede incluir un “usuario ficticio”. Para más información, consulta Bloqueo de correo no deseado.

Preguntas frecuentes

¿Debo usar este punto de conexión o /users/track?

Usa ambos puntos de conexión según tu caso de uso:

• Para grandes rellenos de datos y sincronizaciones, usa /users/track/bulk.
• Para casos de uso en tiempo real, usa /users/track.

¿Qué identificadores puedo usar en /users/track/bulk?

Para cada objeto de solicitud, incluye uno de los siguientes: external_id, braze_id, user_alias, email o phone.

¿Puedo incluir atributos, eventos y compras en una solicitud?

Sí. Incluye cualquier combinación de atributos, eventos y compras, hasta el límite combinado de objetos de solicitud de tu cuenta.