Criar e atualizar usuários (em massa)

Use este endpoint para registrar eventos personalizados e compras, além de atualizar atributos de perfis de usuário em massa.

Quando usar este endpoint

Assim como o endpoint /users/track, você pode usar este endpoint para atualizar perfis de usuário. Este endpoint é mais adequado para atualizações em massa:

• Solicitações maiores: envie até 1.000 usuários por solicitação, permitindo que você faça menos solicitações para grandes preenchimentos retroativos e sincronizações.
• Priorização: durante condições de pico de tráfego, as solicitações para /users/track são priorizadas em relação às solicitações para /users/track/bulk.

Use este endpoint quando estiver preenchendo retroativamente muitos perfis de usuário durante a integração, ou sincronizando grandes volumes de perfis como parte de uma sincronização diária.

Pré-requisitos

Para usar este endpoint, você precisa de uma chave de API com a permissão users.track.bulk.

Se você estiver fazendo chamadas servidor-a-servidor atrás de um firewall, pode ser necessário adicionar seu endpoint REST da Braze à lista de permissões (por exemplo, rest.iad-01.braze.com). Para saber mais, consulte Endpoints de API.

Limite de taxa

Para a maioria dos clientes, este endpoint tem um limite de velocidade base de 50 solicitações por segundo.

Clientes com contratos mais recentes podem ter limites de pico (por segundo) e estáveis (por hora) baseados nos usuários ativos mensais contratados.

Cada solicitação /users/track/bulk tem um limite de carga útil de 2 MB e pode incluir até 1.000 objetos no total entre atributos, eventos e compras, dependendo da política de limite de taxa em massa da sua conta.

Cada objeto pode atualizar um usuário, então uma única solicitação pode atualizar até o limite de objetos de solicitação da sua conta de usuários diferentes. Além disso, cada solicitação pode conter no máximo 100 objetos por perfil de usuário entre atributos, eventos e compras.

Corpo da solicitação

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

Exemplos de solicitações

Atualizar perfis de usuário em massa em uma única solicitação

Atualize até o limite de objetos de solicitação da sua conta de perfis de usuário em uma única 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/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 e eventos em uma única solicitação

Inclua atributos e eventos na mesma solicitação, até o limite total de objetos da sua conta.

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

Respostas

Mensagem de sucesso

Mensagens de sucesso retornam a seguinte resposta:

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
}

Mensagem de sucesso com erros não fatais

Se sua solicitação for bem-sucedida, mas tiver erros não fatais (por exemplo, um objeto de evento inválido em um lote grande), você receberá a seguinte resposta:

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

Mensagem com erros fatais

Se sua solicitação 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>
    }
  ]
}

Códigos de resposta de erros fatais

Para códigos de status e mensagens de erro associadas que a Braze retorna quando sua solicitação tem um erro fatal, consulte Erros fatais e respostas.

Se você receber o erro “provided external_id is blacklisted and disallowed”, sua solicitação pode incluir um “usuário fictício”. Para saber mais, consulte Bloqueio de spam.

Perguntas frequentes

Devo usar este endpoint ou /users/track?

Use ambos os endpoints com base no seu caso de uso:

• Para grandes preenchimentos retroativos e sincronizações, use /users/track/bulk.
• Para casos de uso em tempo real, use /users/track.

Quais identificadores posso usar em /users/track/bulk?

Para cada objeto de solicitação, inclua um dos seguintes: external_id, braze_id, user_alias, email ou phone.

Posso incluir atributos, eventos e compras em uma única solicitação?

Sim. Inclua qualquer combinação de atributos, eventos e compras, até o limite combinado de objetos de solicitação da sua conta.