Criar e atualizar usuários
Use esse endpoint para registrar eventos personalizados e compras, além de atualizar atributos do perfil de usuário.

Cada atributo personalizado enviado em uma solicitação para /users/track consome um ponto de dados. Para saber mais, consulte Pontos de dados.
A Braze processa os dados passados por meio da API pelo valor nominal. Por isso, você deve passar apenas deltas (dados alterados) para minimizar o registro desnecessário de pontos de dados.

Se o /users/track retornar 400 com um erro de análise ou de sintaxe, o corpo da solicitação não é um JSON válido. Verifique se há vírgulas finais e envie JSON codificado em UTF-8 com o cabeçalho Content-Type: application/json. Consulte Por que recebo 400 Bad Request com um erro de sintaxe ou de análise? e a tabela de erros fatais em Erros da API.
Precisa atualizar usuários em massa?
Use o endpoint /users/track/bulk para enviar lotes maiores e reduzir o volume de solicitações.
Rastrear status de processamento de solicitações

O status de processamento de solicitações está em beta. Se você tiver interesse em participar do beta, entre em contato com o seu gerente de conta da Braze.
A Braze processa as solicitações /users/track de forma assíncrona. Uma resposta de sucesso significa que a Braze recebeu sua solicitação e a colocou na fila para processamento, mas os dados podem ainda não estar no perfil do usuário. Para confirmar quando o processamento é concluído, adicione um group_id às suas solicitações e verifique o status do grupo com o endpoint /users/track/status.
Use o status de processamento de solicitações para:
- Confirmar que atualizações de atributos ou inscrições estão no perfil antes de disparar um Canvas ou uma Campaign que dependa delas
- Confirmar que um preenchimento retroativo ou importação foi concluído antes de lançar o envio de mensagens para os usuários afetados
- Manter um registro de que atualizações de alta prioridade, como alterações de consentimento, concluíram o processamento
Como funciona
- Escolha um
group_idpara um conjunto de solicitações relacionadas. Por exemplo, use um únicogroup_idpara todas as solicitações de um preenchimento retroativo, ou umgroup_idexclusivo para uma única solicitação que você deseja confirmar. - Inclua o
group_idno nível superior do corpo de cada solicitação/users/track. A Braze contabiliza cada solicitação aceita no grupo. - Chame o endpoint
/users/track/statuscom ogroup_id. Quando ostatusdo grupo forcompleted, a Braze terá concluído o processamento de todas as solicitações do grupo.
Se você enviar outra solicitação com o mesmo group_id depois que o grupo estiver completed, o status do grupo retornará a processing até que a Braze termine de processar a nova solicitação.
A Braze rastreia o status de cada grupo como um todo. Um grupo fica completed quando a Braze termina de processar todas as solicitações do grupo, incluindo solicitações em que a Braze rejeitou alguns objetos. A Braze lista os objetos rejeitados no vetor errors de cada resposta de /users/track.
O rastreamento de status está disponível apenas para o endpoint /users/track. A Braze não rastreia o status de solicitações para o endpoint /users/track/bulk ou para o endpoint /users/track/sync.
Requisitos do group ID
Um group_id deve ter de 1 a 128 caracteres e pode conter apenas letras, números, pontos (.), sublinhados (_), tis (~) e hífens (-).
O escopo dos group IDs é o espaço de trabalho. O mesmo group_id em dois espaços de trabalho se refere a dois grupos separados.
Use um novo group_id para cada conjunto de solicitações que você deseja rastrear. Reutilizar um group_id adiciona solicitações ao grupo existente e não estende o período de retenção.
Limites e retenção
| Limite | Valor |
|---|---|
| Retenção | 24 horas A Braze retém o status do grupo por 24 horas a partir do momento da primeira solicitação com um group_id. Após o período de retenção, o endpoint /users/track/status retorna um vetor results vazio para esse group_id. |
| Solicitações por grupo | 6.000.000 |
| Grupos ativos por espaço de trabalho | 100.000. Um grupo fica ativo até o fim do período de retenção. |
Limite de frequência do /users/track/status |
1.500 solicitações por minuto por espaço de trabalho. Esse limite é separado do limite de frequência do /users/track. |
Erros de rastreamento de status
Em alguns casos, a Braze não consegue rastrear o status de uma solicitação, como quando o espaço de trabalho atingiu o número máximo de grupos ativos. Quando isso acontece, a resposta de /users/track ainda é bem-sucedida e a Braze ainda processa os atributos, eventos e compras da solicitação. A resposta inclui uma entrada no vetor errors que descreve por que a Braze não está rastreando a solicitação:
{
"message": "success",
"errors": [
{
"type": "request_status_group_full"
}
]
}
| Tipo de erro | Descrição |
|---|---|
invalid_group_id |
O group_id não é uma string, está vazio, tem mais de 128 caracteres ou contém caracteres não permitidos. Para saber mais, consulte Requisitos do group ID. |
request_status_active_group_limit_exceeded |
O espaço de trabalho atingiu o limite de grupos ativos. Aguarde os grupos existentes expirarem ou envie a solicitação sem um group_id. |
request_status_group_full |
O grupo atingiu o limite de solicitações. Use um novo group_id para solicitações adicionais. |
request_status_not_tracked |
A Braze não conseguiu rastrear a solicitação. Por exemplo, o período de retenção do grupo terminou ou o rastreamento de status não está ativado para o espaço de trabalho. |
Perguntas frequentes

Não envie e-mails de transação legalmente exigidos para gateways de SMS, pois há uma grande probabilidade de que esses e-mails não sejam entregues.
Embora os e-mails que você envia usando um número de telefone e o domínio de gateway do provedor (conhecido como MM3) possam resultar no recebimento do e-mail como uma mensagem SMS (texto), alguns dos nossos provedores de e-mail não oferecem suporte a esse comportamento. Por exemplo, se você enviar um e-mail para um número de telefone da T-Mobile (como “[email protected]”), sua mensagem SMS será enviada para o proprietário desse número de telefone na rede T-Mobile.
Lembre-se de que, embora esses e-mails possam não ser entregues ao gateway de SMS, eles ainda contarão para a sua fatura de e-mail. Para evitar o envio de e-mails para gateways sem suporte, consulte a lista de nomes de domínio de gateway sem suporte.
O que acontece quando são encontrados vários perfis com o mesmo endereço de e-mail?
Se o external_id existir, a Braze priorizará o perfil atualizado mais recentemente com um ID externo para atualizações. Se o external_id não existir, a Braze priorizará o perfil atualizado mais recentemente para atualizações.
O que acontece se não houver nenhum perfil com o endereço de e-mail?
A Braze cria um perfil e um usuário somente de e-mail e define o campo de e-mail como [email protected], conforme indicado no exemplo de solicitação para atualizar um perfil de usuário por endereço de e-mail. A Braze não cria um alias.
Como usar o /users/track para importar dados de usuários antigos?
Você pode enviar dados por meio da API da Braze para um usuário que ainda não tenha usado seu app móvel, gerando um perfil de usuário. Se o usuário usar o aplicativo posteriormente, todas as informações após a identificação pelo SDK serão mescladas com o perfil de usuário existente que você criou com a chamada da API. Qualquer comportamento de usuário registrado anonimamente pelo SDK antes da identificação é perdido ao ser mesclado com o perfil de usuário existente gerado pela API.
A ferramenta de segmentação inclui esses usuários independentemente de terem interagido com o app. Se você quiser excluir usuários enviados pela API de usuário que ainda não interagiram com o app, adicione o filtro Session Count > 0.
Como evitar a criação de perfis de usuário duplicados?
Perfis duplicados podem ocorrer quando uma solicitação inclui um identificador primário (como external_id) que não corresponde a nenhum perfil existente, junto com um valor de email ou phone que corresponde a um perfil existente. Como os identificadores primários são usados para a busca de usuários, a Braze cria um novo perfil para o external_id não reconhecido em vez de atualizar o perfil existente somente de e-mail ou somente de telefone.
Para evitar duplicatas:
- Ao fazer a transição de usuários de perfis somente de e-mail ou somente de telefone para perfis identificados, use o endpoint
/users/identifypara atribuir umexternal_idao perfil existente, em vez de enviar ambos para/users/track. - Se já existirem duplicatas, mescle-as usando o endpoint
/users/merge.
Como o /users/track lida com eventos duplicados?
Cada objeto de evento no vetor de eventos representa uma única ocorrência de um evento personalizado por um usuário em um momento designado. Isso significa que cada evento ingerido pela Braze tem seu próprio ID de evento. Portanto, eventos “duplicados” são tratados como eventos separados e exclusivos.
Como o /users/track lida com atributos personalizados aninhados inválidos?
Quando um atributo personalizado aninhado contém valores inválidos (como formatos de hora inválidos ou valores nulos), a Braze descarta do processamento todas as atualizações de atributos personalizados aninhados na solicitação. Isso se aplica a todas as estruturas aninhadas dentro desse atributo específico. Para garantir o processamento bem-sucedido, verifique se todos os valores dentro dos atributos personalizados aninhados são válidos antes do envio.
As solicitações ao /users/track são garantidamente processadas em ordem?
Quando você faz várias chamadas de API separadas ao /users/track em rápida sucessão, a Braze não pode garantir que as solicitações sejam processadas na ordem exata em que foram enviadas ou recebidas. Isso ocorre porque a Braze usa processamento assíncrono para maximizar a velocidade e a flexibilidade.
Por exemplo, se você enviar várias solicitações de atualização para o mesmo usuário em poucos segundos — algumas com valores de atributo nulos e outras com valores válidos — as solicitações com valores nulos podem ser processadas depois das solicitações com valores válidos, mesmo que tenham sido enviadas antes. Isso pode fazer com que os valores dos atributos pareçam reverter ou não reflitam a atualização enviada mais recentemente.
Para evitar condições de corrida ao atualizar dados de usuários:
- Agrupe atualizações em uma única solicitação: inclua todas as atualizações de atributos de um usuário em uma única chamada de API, em vez de fazer chamadas consecutivas separadas.
- Adicione postergações entre solicitações: se você precisar fazer chamadas separadas para o mesmo usuário, adicione uma postergação (de alguns segundos) entre as solicitações para que a primeira termine de ser processada antes do envio da próxima.
- Evite atualizações sobrepostas para o mesmo campo: se duas solicitações atualizam o mesmo atributo com valores diferentes, envie essas atualizações em uma única solicitação ou separe-as com uma postergação para reduzir a chance de resultados fora de ordem.
- Confirme o processamento antes da próxima solicitação (beta): inclua um
group_idna primeira solicitação e aguarde até que o endpoint/users/track/statusretornecompletedantes de enviar a solicitação dependente. Para saber mais, consulte Rastrear status de processamento de solicitações.
Para saber mais sobre condições de corrida e práticas recomendadas, consulte Condições de corrida.
Como saber quando a Braze terminou de processar minha solicitação?
Inclua um group_id nas suas solicitações /users/track e depois chame o endpoint /users/track/status com esse group_id. Quando o status do grupo for completed, a Braze terá concluído o processamento de todas as solicitações do grupo. Esse recurso está em beta. Para saber mais, consulte Rastrear status de processamento de solicitações.
Com que frequência devo verificar o status de um grupo?
Consulte o endpoint /users/track/status em um intervalo regular, como a cada poucos segundos, e pare quando o status do grupo for completed. Mantenha a frequência de consultas dentro do limite de frequência do endpoint, de 1.500 solicitações por minuto por espaço de trabalho.
Por que meu grupo ainda está em processamento?
Um grupo permanece em processing até que a Braze termine de processar todas as solicitações aceitas do grupo. Se uma solicitação falhar durante o processamento, a Braze fará uma nova tentativa, e o grupo permanecerá em processing até que a nova tentativa seja bem-sucedida. Se você adicionar solicitações a um grupo depois que ele estiver completed, o status retornará a processing. Em casos raros, um grupo pode permanecer em processing até o fim do período de retenção. Se um grupo permanecer em processing por muito mais tempo do que o seu tempo de processamento habitual, entre em contato com o suporte da Braze.
Por que o /users/track/status retorna um vetor results vazio?
O vetor results fica vazio quando a Braze não encontra o grupo no seu espaço de trabalho. Isso acontece quando o período de retenção de 24 horas do grupo terminou, o group_id não corresponde ao usado nas suas solicitações ou você enviou as solicitações para outro espaço de trabalho. Também acontece quando a Braze não rastreou nenhuma solicitação para esse group_id. Verifique cada resposta de /users/track em busca de erros de rastreamento de status.
Por que a resposta do /users/track está mais lenta do que eu esperava?
Chamadas bem-sucedidas ao /users/track geralmente são aceitas rapidamente, mas a Braze ainda processa atualizações de atributos, eventos e compras de forma assíncrona. A latência percebida pode aumentar quando as cargas úteis são grandes ou quando o roteamento de rede até o seu endpoint REST é lento. Se você precisar de uma confirmação síncrona por usuário ou de uma ordenação mais rigorosa entre chamadas, consulte /users/track/sync (beta limitado).
Por que o /users/track retorna 429 Too Many Requests?
Quando o volume de solicitações excede o limite de frequência, o /users/track retorna uma resposta HTTP 429 Too Many Requests. Para voltar a enviar solicitações:
- Pause as solicitações pelo número de segundos especificado no cabeçalho de resposta
X-RateLimit-Retry-After. - Retome as solicitações em uma taxa menor para reduzir a probabilidade de outra resposta
429. - Combine atualizações sempre que possível e siga o limite de objetos por solicitação da sua conta.
- Use o dashboard de uso da API para identificar picos de solicitações e tendências de respostas
429. Para os limites padrão do espaço de trabalho e os limites de outros endpoints, consulte Limites de frequência da API.
Para respostas diferentes de 429 em contratos compatíveis, use os cabeçalhos de resposta X-RateLimit-* descritos em Cabeçalhos de limite de frequência para Monthly Active Users CY 24-25, Universal MAU, Web MAU e Mobile MAU para verificar as solicitações restantes na janela atual.
Por que recebo 400 Bad Request com um erro de sintaxe ou de análise?
Um HTTP 400 com um erro de sintaxe ou de análise geralmente significa que o corpo da solicitação não é um JSON válido. Causas comuns incluem vírgulas finais, comentários dentro do JSON, strings com aspas simples, uma chave { extra antes da carga útil ou o envio de um corpo que não é JSON enquanto o cabeçalho Content-Type é application/json. Valide as cargas úteis com um linter de JSON antes de enviar, confirme que seu cliente HTTP codifica os objetos em JSON (em vez de concatenar strings brutas) e confirme que o corpo está codificado em UTF-8. Para outras respostas 400 (por exemplo, tamanho da carga útil e limites de objetos por solicitação), consulte Erros fatais e respostas e a tabela de Erros específicos do endpoint nesta página.
Monthly Active Users CY 24-25, Universal MAU, Web MAU e Mobile MAU
Para clientes com os novos preços, os limites de frequência são aplicados no nível da empresa. Os clientes podem definir limites de frequência por hora para cada espaço de trabalho, mas os limites de pico (burst) continuam compartilhados entre todos os espaços de trabalho.
Para os clientes que adquiriram Monthly Active Users CY 24-25, Universal MAU, Web MAU ou Mobile MAU, a Braze gerencia limites de frequência diferentes no endpoint /users/track:
- Os limites de frequência por hora são definidos de acordo com a atividade esperada de ingestão de dados na sua conta, que pode corresponder ao número de usuários ativos mensais que você adquiriu, ao setor, à sazonalidade ou a outros fatores.
- Além do limite por hora, a Braze impõe um limite de pico ao número de solicitações que podem ser enviadas a cada três segundos.
- Cada solicitação pode agrupar até 75 atualizações combinadas entre objetos de atributo, evento ou compra.
Os limites atuais baseados na ingestão esperada podem ser encontrados no dashboard em Configurações > APIs e identificadores > Dashboard de uso da API. Podemos modificar os limites de frequência para proteger a estabilidade do sistema ou permitir um aumento na taxa de transferência de dados na sua conta. Entre em contato com o suporte da Braze ou com o seu gerente de sucesso do cliente em caso de dúvidas ou preocupações sobre o limite de solicitações por hora ou por segundo e as necessidades da sua empresa.
Cabeçalhos de limite de frequência para Monthly Active Users CY 24-25, Universal MAU, Web MAU e Mobile MAU
Todas as respostas sem limitação de frequência (ou seja, diferentes de 429) contêm os seguintes cabeçalhos de resposta HTTP, que indicam ao cliente o estado da janela de limite de frequência por hora. Use esses cabeçalhos para gerenciar sua taxa de solicitações:
| Nome do cabeçalho | Descrição |
|---|---|
X-RateLimit-Limit |
O número de solicitações permitidas por período de tempo |
X-RateLimit-Remaining |
O número aproximado de solicitações restantes em uma janela |
X-RateLimit-Reset |
O número de segundos restantes até a reinicialização da janela atual |
Observe que os cabeçalhos RateLimit-Limit, RateLimit-Remaining e RateLimit-Reset não são retornados quando você recebe um erro HTTP 429. Quando o erro ocorre, esses cabeçalhos são substituídos por um cabeçalho X-RateLimit-Retry-After, que retorna um número inteiro indicando quantos segundos faltam para você poder voltar a fazer solicitações.
Você pode baixar o documento OpenAPI e usá-lo para validar esquemas. Para saber como, consulte Usar esquemas OpenAPI para validação de solicitações.