Skip to content

Criar e atualizar usuários (síncrono)

post

/users/track/sync

core endpoint

Use esse endpoint para registrar eventos personalizados e compras e atualizar atributos do perfil de usuário de forma síncrona. Esse endpoint funciona de forma semelhante ao endpoint /users/track, que atualiza perfis de usuário de forma assíncrona.

Chamadas síncronas e assíncronas à API

Em uma chamada assíncrona, a API retorna o código de status 201, indicando que sua solicitação foi recebida, compreendida e aceita com sucesso. No entanto, isso não significa que sua solicitação tenha sido totalmente concluída.

Em uma chamada síncrona, a API retorna o código de status 201, indicando que sua solicitação foi recebida, compreendida, aceita e concluída com sucesso. A resposta da chamada mostra campos selecionados do perfil do usuário como resultado da operação.

Esse endpoint tem um limite de taxa menor do que o endpoint /users/track (consulte o limite de taxa abaixo). Cada solicitação /users/track/sync pode conter apenas um objeto de evento, um objeto de atributo ou um objeto de compra. Esse endpoint deve ser reservado para atualizações de perfil de usuário em que uma chamada síncrona é necessária. Para uma implementação saudável, recomendamos usar /users/track/sync e /users/track juntos.

Por exemplo, se você estiver enviando solicitações consecutivas para o mesmo usuário em um curto período de tempo, condições de corrida são possíveis com o endpoint assíncrono /users/track, mas com o endpoint /users/track/sync você pode enviar essas solicitações em sequência, cada uma após receber uma resposta 2XX.

Pré-requisitos

Para usar esse endpoint, você precisará de uma chave de API com a permissão users.track.sync.

Os clientes que usam a API para chamadas de servidor para servidor podem precisar adicionar rest.iad-01.braze.com à lista de permissões se estiverem protegidos por um firewall.

Limite de taxa

Aplicamos um limite de velocidade base de 500 solicitações por minuto para esse endpoint para todos os clientes. Cada solicitação /users/track/sync pode conter até um objeto de evento, um objeto de atributo ou um objeto de compra. Cada objeto (evento, atributo e arrays de compra) pode atualizar um usuário cada.

Corpo da solicitação

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 solicitação

Respostas

Ao usar os parâmetros de solicitação desse endpoint, você deve receber uma das seguintes respostas: uma mensagem de sucesso ou uma mensagem com erros fatais.

Mensagem de sucesso

Mensagens de sucesso retornam a seguinte resposta, que inclui informações sobre os dados do perfil de usuário que a Braze atualizou.

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"

Mensagem com erros fatais

Se sua mensagem tiver um erro fatal, você receberá a seguinte resposta:

1
2
3
4
5
6
7
8

{
  "message": <fatal error message>,
  "errors": [
    {
      <fatal error message>
    }
  ]
}

Exemplos de solicitações e respostas

Atualizar um atributo personalizado por ID externo

Solicitação

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"
            ]
        }
    ]
}'

Resposta

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"
}

Atualizar um evento personalizado por e-mail

Solicitação

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"
                    }
                ]
            }
        }
    ]
}'

Resposta

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"
}

Atualizar um evento de compra por alias de usuário

Solicitação

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
            }
          ]
      }
   }
  ]
}'

Resposta

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"
}

Perguntas frequentes

Devo usar o endpoint assíncrono ou síncrono?

Para a maioria das atualizações de perfil, o endpoint /users/track funciona melhor devido ao seu limite de taxa mais alto e à flexibilidade para agrupar solicitações em lote. No entanto, o endpoint /users/track/sync é útil se você estiver enfrentando condições de corrida devido a solicitações rápidas e consecutivas para o mesmo usuário.

O tempo de resposta é diferente do endpoint /users/track?

Com uma chamada síncrona, a API espera até que a Braze conclua a solicitação para retornar uma resposta. Como resultado, solicitações síncronas levam mais tempo em média do que solicitações assíncronas para /users/track. Para a maioria das solicitações, você pode esperar uma resposta em segundos.

Posso enviar várias solicitações ao mesmo tempo?

Sim, desde que as solicitações sejam para usuários diferentes ou que cada solicitação atualize atributos, eventos ou compras diferentes para um mesmo usuário.

Se você estiver enviando várias solicitações para um mesmo usuário, para o mesmo atributo, evento ou compra, a Braze recomenda aguardar uma resposta bem-sucedida entre cada solicitação para evitar a ocorrência de condições de corrida.

Por que o valor da resposta não corresponde ao da minha solicitação original?

Embora sua solicitação tenha sido concluída, é possível que o valor do atributo personalizado não tenha sido atualizado. Isso pode acontecer quando a atualização do atributo personalizado excede o número máximo de caracteres, excede os limites do array ou se o usuário não existe na Braze e você definiu _update_existing_only = true.

Nessas situações, considere a resposta como um sinal de que sua solicitação foi concluída, mas a atualização desejada não foi efetuada. Investigue os possíveis motivos descritos acima para solucionar o problema.
New Stuff!