Skip to content

Crear y actualizar usuarios (sincrónico)

post

/users/track/sync

core endpoint

Utiliza este punto de conexión para registrar eventos personalizados y compras, y actualizar los atributos del perfil de usuario de forma sincrónica. Este punto de conexión funciona de forma similar al punto de conexión /users/track, que actualiza los perfiles de usuario de forma asíncrona.

Llamadas a la API síncronas y asíncronas

En una llamada asíncrona, la API devuelve el código de estado 201, lo que indica que tu solicitud se ha recibido, comprendido y aceptado correctamente. Sin embargo, esto no significa que tu solicitud se haya completado en su totalidad.

En una llamada sincrónica, la API devuelve un código de estado 201 que indica que tu solicitud se ha recibido, comprendido, aceptado y completado correctamente. La respuesta a la llamada muestra campos seleccionados del perfil de usuario como resultado de la operación.

Este punto de conexión tiene un límite de velocidad menor que el punto de conexión /users/track (consulta límite de velocidad más abajo). Cada solicitud de /users/track/sync solo puede contener un objeto de evento, un objeto de atributo o un objeto de compra. Este punto de conexión debe reservarse para las actualizaciones del perfil de usuario en las que se necesite una llamada sincrónica. Para una implementación saludable, te recomendamos que utilices /users/track/sync y /users/track juntos.

Por ejemplo, si envías solicitudes consecutivas para el mismo usuario durante un breve período de tiempo, es posible que se produzcan condiciones de carrera con el punto de conexión asíncrono /users/track, pero con el punto de conexión /users/track/sync puedes enviar esas solicitudes en secuencia, cada una después de recibir una respuesta 2XX.

Requisitos previos

Para utilizar este punto de conexión, necesitarás una clave de API con el permiso users.track.sync.

Es posible que los clientes que utilicen la API para llamadas de servidor a servidor tengan que incluir en la lista de permitidos rest.iad-01.braze.com si están detrás de un cortafuegos.

Límite de velocidad

Aplicamos un límite de velocidad base de 500 solicitudes por minuto a este punto de conexión para todos los clientes. Cada solicitud de /users/track/sync puede contener hasta un objeto de evento, un objeto de atributo o un objeto de compra. Cada objeto (evento, atributo y matrices de compra) puede actualizar un usuario cada uno.

Cuerpo de la solicitud

1
2

Content-Type: application/json
Authorization: Bearer YOUR_REST_API_KEY

1
2
3
4
5

{
  "attributes": (optional, one attributes object),
  "events": (optional, one event object),
  "purchases": (optional, one purchase object),
}

Parámetros de la solicitud

Respuestas

Al utilizar los parámetros de solicitud de este punto de conexión, deberías recibir una de las siguientes respuestas: un mensaje correcto o un mensaje con errores fatales.

Mensaje correcto

Los mensajes correctos devuelven la siguiente respuesta, que incluye información sobre los datos del perfil de usuario que Braze ha actualizado.

1
2
3
4
5
6
7

{
    "users": (optional, object), the identifier of the user in the request. May be empty if no users are found and _update_existing_only key is set to true,
        "custom_attributes": (optional, object), the custom attributes as a result of the request. Braze lists only custom attributes from the request,
        "custom_events": (optional, object), the custom events as a result of the request. Braze lists only custom events from the request,
        "purchase_events": (optional, object), the purchase events as a result of the request. Braze lists only purchase events from the request,
    },
    "message": "success"

Mensaje con errores fatales

Si tu mensaje 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>
    }
  ]
}

Ejemplos de solicitudes y respuestas

Actualizar un atributo personalizado por ID externo

Solicitud

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17

curl --location --request POST 'https://rest.iad-01.braze.com/users/track/sync' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer YOUR_REST_API_KEY' \
--data-raw '{
    "attributes": [
        {
            "external_id": "xyz123",
            "string_attribute": "fruit",
            "boolean_attribute_1": true,
            "integer_attribute": 25,
            "array_attribute": [
                "banana",
                "apple"
            ]
        }
    ]
}'

Respuesta

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17

{
    "users": [
        {
            "external_id": "xyz123",
            "custom_attributes": {
                "string_attribute": "fruit",
                "boolean_attribute_1": true,
                "integer_attribute": 25,
                "array_attribute": [
                    "banana",
                    "apple",
                ]
            }
        }
    ],
    "message": "success"
}

Actualizar un evento personalizado por correo electrónico

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/sync' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer YOUR_REST_API_KEY' \
--data-raw '{
    "events": [
        {
            "email": "[email protected]",
            "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"
                    }
                ]
            }
        }
    ]
}'

Respuesta

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

{
    "users": [
        {
            "email": "[email protected]",
            "custom_events": [
                {
                "name": "rented_movie",
                "first": "2022-01-001T00:00:00.000Z",
                "last": "2022-12-06T18:20:45.000Z",
                "count": 10
                }
            ]
        }
    ],
    "message": "success"
}

Actualizar un evento de compra por alias de usuario

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
28
29
30
31
32

curl --location --request POST 'https://rest.iad-01.braze.com/users/track/sync' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer YOUR_REST_API_KEY' \
--data-raw '{
  "purchases" : [
    {
      "user_alias" : {
          "alias_name" : "device123",
          "alias_label" : "my_device_identifier"
      }
      "app_id" : "11ae5b4b-2445-4440-a04f-bf537764c9ad",
      "product_id" : "Completed Order",
      "currency" : "USD",
      "price" : 219.98,
      "time" : "2022-12-06T19:20:45+01:00",
      "properties" : {
          "products" : [
            {
              "name": "Monitor",
              "category": "Gaming",
              "product_amount": 19.99
            },
            {
              "name": "Gaming Keyboard",
              "category": "Gaming ",
              "product_amount": 199.99
            }
          ]
      }
   }
  ]
}'

Respuesta

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19

{
    "users": [
        {
          "user_alias" : {
            "alias_name" : "device123",
            "alias_label" : "my_device_identifier"
          },
          "purchase_events": [
                {
                "product_id": "Completed Order",
                "first": "2013-07-16T19:20:30+01:00",
                "last": "2022-12-06T18:20:45.000Z",
                "count": 3
                }
            ]
        }
    ],
    "message": "success"
}

Preguntas más frecuentes

¿Debo utilizar el punto de conexión asíncrono o sincrónico?

Para la mayoría de las actualizaciones de perfiles, el punto de conexión /users/track funciona mejor debido a su mayor límite de velocidad y flexibilidad, que te permite agrupar solicitudes. Sin embargo, el punto de conexión /users/track/sync es útil si experimentas condiciones de carrera debido a solicitudes rápidas y consecutivas para el mismo usuario.

¿Difiere el tiempo de respuesta del punto de conexión /users/track?

Con una llamada sincrónica, la API espera hasta que Braze complete la solicitud para devolver una respuesta. Como resultado, las solicitudes sincrónicas tardan más tiempo en promedio que las solicitudes asíncronas a /users/track. Para la mayoría de las solicitudes, puedes esperar una respuesta en cuestión de segundos.

¿Puedo enviar varias solicitudes al mismo tiempo?

Sí, siempre que las solicitudes sean para usuarios diferentes, o que cada solicitud actualice diferentes atributos, eventos o compras para un usuario.

Si envías varias solicitudes para un usuario, para el mismo atributo, evento o compra, Braze recomienda esperar una respuesta satisfactoria entre cada solicitud para evitar que se produzcan condiciones de carrera.

¿Por qué el valor de respuesta no coincide con el de mi solicitud original?

Aunque tu solicitud se ha completado, es posible que el valor de tu atributo personalizado no se haya actualizado. Esto puede ocurrir cuando la actualización de tu atributo personalizado supera el número máximo de caracteres, supera los límites de la matriz o si el usuario no existe en Braze y tienes _update_existing_only = true.

En estos casos, trata la respuesta como una indicación de que, aunque tu solicitud se completó, la actualización deseada no se ha realizado. Investiga las posibles razones mencionadas anteriormente para resolver el problema.
New Stuff!