Visão geral da API
Este artigo de referência aborda os conceitos básicos da API, incluindo a terminologia comum e uma visão geral das chaves da API REST, permissões e como mantê-las seguras.
Coleção da API do Braze REST
| Coleção | Finalidade |
|---|---|
| Catálogos | Crie e gerencie catálogos e itens de catálogo para fazer referência em suas campanhas no Braze. |
| Ingestão de dados na nuvem | Gerencie as integrações e sincronizações de seu data warehouse. |
| Listas e endereços de e-mail | Configure e gerencie a sincronização bidirecional entre o Braze e seus sistemas de e-mail. |
| Exportar | Acesse e exporte várias informações de suas campanhas, canvas, KPIs e muito mais. |
| Biblioteca de mídia | Gerencie ativos dentro do Braze. |
| Mensagens | Programe, envie e gerencie suas campanhas e Canvas. |
| Central de Preferências | Crie sua Central de Preferências e atualize o estilo dela. |
| SCIM | Gerencie identidades de usuários em aplicativos e serviços baseados em nuvem. |
| SMS | Gerencie os números de telefone de seus usuários em seus grupos de inscrições. |
| Grupos de inscrições | Liste e atualize os grupos de inscrições para e-mail e SMS armazenados no dashboard do Braze. |
| Modelos | Crie e atualize modelos para envio de mensagens de e-mail e blocos de conteúdo. |
| Dados de usuários | Identifique, rastreie e gerencie seus usuários. |
Definições da API
A seguir, uma visão geral dos termos que você poderá ver na documentação da Braze REST API.
Endpoints
A Braze gerencia várias instâncias diferentes para nosso dashboard e endpoints REST. Quando sua conta for provisionada, você faz login em uma das seguintes URLs. Use o endpoint REST correto com base na instância para a qual você está provisionado. Se você não tiver certeza, abra um ticket de suporte ou use a tabela a seguir para corresponder a URL do painel que você usa ao Endpoint REST correto.
Para encontrar seu endpoint REST no Braze:
- Faça login no Braze e acesse Configurações > APIs e Identificadores > Chaves de API.
- Selecione uma chave de API existente ou selecione Criar Chave de API para criar uma nova chave.
- Copie o endpoint REST mostrado nesta guia e use esse endpoint para suas solicitações de API.
Ao usar endpoints para chamadas de API, use o endpoint REST.
Para integração de SDK, use o endpoint de SDK, não o endpoint de REST.
| Instância | URL | Ponto final REST | Endpoint de SDK |
| |— | — | — | |
| US-01 | https://dashboard-01.braze.com |
https://rest.iad-01.braze.com |
sdk.iad-01.braze.com |
| US-02 | https://dashboard-02.braze.com |
https://rest.iad-02.braze.com |
sdk.iad-02.braze.com |
| US-03 | https://dashboard-03.braze.com |
https://rest.iad-03.braze.com |
sdk.iad-03.braze.com |
| US-04 | https://dashboard-04.braze.com |
https://rest.iad-04.braze.com |
sdk.iad-04.braze.com |
| US-05 | https://dashboard-05.braze.com |
https://rest.iad-05.braze.com |
sdk.iad-05.braze.com |
| US-06 | https://dashboard-06.braze.com |
https://rest.iad-06.braze.com |
sdk.iad-06.braze.com |
| US-07 | https://dashboard-07.braze.com |
https://rest.iad-07.braze.com |
sdk.iad-07.braze.com |
| US-08 | https://dashboard-08.braze.com |
https://rest.iad-08.braze.com |
sdk.iad-08.braze.com |
| US-10 | https://dashboard.us-10.braze.com |
https://rest.us-10.braze.com |
sdk.us-10.braze.com |
| EU-01 | https://dashboard-01.braze.eu |
https://rest.fra-01.braze.eu |
sdk.fra-01.braze.eu |
| EU-02 | https://dashboard-02.braze.eu |
https://rest.fra-02.braze.eu |
sdk.fra-02.braze.eu |
| AU-01 | https://dashboard.au-01.braze.com |
https://rest.au-01.braze.com |
sdk.au-01.braze.com |
| ID-01 | https://dashboard.id-01.braze.com |
https://rest.id-01.braze.com |
sdk.id-01.braze.com |
| JP-01 | https://dashboard.jp-01.braze.com |
https://rest.jp-01.braze.com |
sdk.jp-01.braze.com |
Limites da API
Para a maioria das APIs, a Braze tem um limite de frequência padrão de 250.000 solicitações por hora. No entanto, certos tipos de solicitações têm seu próprio limite de frequência aplicado para melhor lidar com altos volumes de dados em toda a base de clientes. Para obter informações, consulte os limites de frequência da API
IDs de usuário
- ID de usuário externo: O endereço
external_idserve como um identificador exclusivo do usuário para o qual você está enviando dados. Esse identificador deve ser o mesmo que você definiu no SDK do Braze para evitar a criação de vários perfis para o mesmo usuário. - ID do usuário do Braze:
braze_idserve como um identificador único de usuário que o Braze define. Você pode usar esse identificador para excluir usuários através da API REST, além de external_ids.
Para saber mais, consulte os seguintes artigos com base em sua plataforma: iOS, Android e Web.
Sobre as chaves da API REST
Uma chave de interface de programação de aplicativo REST (chave da API REST) é um código único que você passa para uma API para autenticar a chamada da API e identificar o aplicativo ou usuário que está chamando. Você acessa a API usando solicitações web HTTPS para o endpoint REST da sua empresa. As chaves da API REST funcionam em conjunto com as chaves de Identificador de App para rastrear, acessar, enviar, exportar e analisar dados para ajudar a garantir que tudo esteja funcionando sem problemas.
Os espaços de trabalho e as chaves de API andam de mãos dadas no Braze. Os espaços de trabalho são projetados para abrigar versões do mesmo aplicativo em várias plataformas. Muitos clientes também usam espaços de trabalho para conter versões gratuitas e premium de seus aplicativos na mesma plataforma. Como você pode notar, esses espaços de trabalho também estão usando a API REST e têm suas próprias chaves de API REST. Estas chaves podem ter escopo individual para incluir acesso a endpoints específicos na API. Cada chamada para a API precisa incluir uma chave com acesso ao endpoint atingido.
Referimo-nos tanto à chave da API REST quanto à chave da API do espaço de trabalho como api_key. O api_key é incluído em cada solicitação como um cabeçalho de solicitação e atua como uma chave de autenticação que lhe permite usar nossas APIs REST. Essas APIs REST são usadas para rastrear usuários, enviar mensagens, exportar dados de usuários e muito mais. Quando você cria uma nova chave da API REST, deve conceder acesso a endpoints específicos. Ao atribuir permissões específicas a uma chave de API, você pode limitar exatamente quais chamadas uma chave de API pode autenticar.
Além das chaves da API REST, também existe um tipo de chave chamado Chaves de identificador que pode ser usado para fazer referência a itens específicos, como aplicativos, modelos, Canvas, campanhas, cartões de conteúdo e segmentos da API. Para saber mais, consulte Tipos de identificadores da API.
Criação de chaves da API REST
Para criar uma nova chave da API REST:
- Acesse Configurações > APIs e identificadores.
- Selecione Create API Key (Criar chave de API).
- Dê um nome à sua nova chave para identificá-la rapidamente.
- Especifique endereços de IP na lista de permissões e subredes para a nova chave.
- Selecione as permissões que deseja associar à sua nova chave.
Lembre-se: depois de criar uma nova chave de API, você não poderá editar o escopo das permissões ou os IPs permitidos. Essa limitação está em vigor por motivos de segurança. Se você precisar alterar o escopo de uma chave, crie uma nova chave com as permissões atualizadas e implemente essa chave no lugar da antiga. Depois de concluir a implementação, você pode excluir a chave antiga.
Permissões de chave de API REST
As permissões de chave de API são permissões que podem ser atribuídas a um usuário ou grupo para limitar seu acesso a determinadas chamadas de API. Para visualizar sua lista de permissões de chave de API, acesse Settings (Configurações) > APIs and Identifiers (APIs e identificadores) e selecione sua chave de API.
| Permissão | Endpoint | Descrição |
|---|---|---|
users.track |
/users/track |
Registre atributos do usuário, eventos personalizados e compras. |
users.delete |
/users/delete |
Exclua qualquer usuário. |
users.alias.new |
/users/alias/new |
Crie um novo alias para um usuário existente. |
users.identify |
/users/identify |
Identifique um usuário somente de alias com um ID externo. |
users.export.ids |
/users/export/ids |
Faça uma consulta para obter informações do perfil do usuário por ID do usuário. |
users.export.segment |
/users/export/segment |
Consulta de informações de perfil de usuário por segmento. |
users.merge |
/users/merge |
Mescla dois usuários existentes um no outro. |
users.external_ids.rename |
/users/external_ids/rename |
Altere o ID externo de um usuário existente. |
users.external_ids.remove |
/users/external_ids/remove |
Remova o ID externo de um usuário existente. |
users.alias.update |
/users/alias/update |
Atualize um alias de um usuário existente. |
users.export.global_control_group |
/users/export/global_control_group |
Faça uma consulta para obter informações do perfil do usuário no grupo de controle global. |
| Permissão | Endpoint | Descrição |
|---|---|---|
email.unsubscribe |
/email/unsubscribes |
Faça uma consulta para obter endereços de e-mail com cancelamento de inscrição. |
email.status |
/email/status |
Altere o status do endereço de e-mail. |
email.hard_bounces |
/email/hard_bounces |
Faça uma consulta para obter endereços de e-mail com hard bounce. |
email.bounce.remove |
/email/bounce/remove |
Remova endereços de e-mail da sua lista de hard bounce. |
email.spam.remove |
/email/spam/remove |
Remova endereços de e-mail da sua lista de spam. |
email.blacklist |
/email/blacklist |
Endereços de e-mail da lista de bloqueio. |
| Permissão | Endpoint | Descrição |
|---|---|---|
campaigns.trigger.send |
/campaigns/trigger/send |
Disparar o envio de uma campanha existente. |
campaigns.trigger.schedule.create |
/campaigns/trigger/schedule/create |
Agende o envio de uma campanha com entrega acionada por API. |
campaigns.trigger.schedule.update |
/campaigns/trigger/schedule/update |
Atualize uma campanha programada com entrega disparada por API. |
campaigns.trigger.schedule.delete |
/campaigns/trigger/schedule/delete |
Exclua uma campanha programada com entrega disparada por API. |
campaigns.list |
/campaigns/list |
Consulta de uma lista de campanhas. |
campaigns.data_series |
/campaigns/data_series |
Consulta para análise de dados de campanha em um intervalo de tempo. |
campaigns.details |
/campaigns/details |
Consulta de detalhes de uma campanha específica. |
sends.data_series |
/sends/data_series |
Faça uma consulta para obter análise de dados de envios de mensagens ao longo de um período. |
sends.id.create |
/sends/id/create |
Criar ID de envio para rastreamento de mensagens. |
campaigns.url_info.details |
/campaigns/url_info/details |
Faça uma consulta para obter informações do URL de uma variação de mensagem específica dentro de uma campanha. |
transactional.send |
/transactional/v1/campaigns/{campaign_id}/send |
Permite a capacidade de enviar mensagens transacionais usando o endpoint de mensagens transacionais. |
| Permissão | Endpoint | Descrição |
|---|---|---|
canvas.trigger.send |
/canvas/trigger/send |
Dispare o envio de um canva existente. |
canvas.trigger.schedule.create |
/canvas/trigger/schedule/create |
Agende o envio de um Canvas com entrega acionada por API. |
canvas.trigger.schedule.update |
/canvas/trigger/schedule/update |
Atualize um canva agendado com entrega disparada pela API. |
canvas.trigger.schedule.delete |
/canvas/trigger/schedule/delete |
Exclua um canva agendado com entrega disparada pela API. |
canvas.list |
/canvas/list |
Faça uma consulta para obter uma lista de canvas. |
canvas.data_series |
/canvas/data_series |
Faça uma consulta para obter análise de dados do canva em um período. |
canvas.details |
/canvas/details |
Faça uma consulta para obter informações de um canva específico. |
canvas.data_summary |
/canvas/data_summary |
Faça uma consulta para obter resultados consolidados sobre a análise de dados do canva em um período. |
canvas.url_info.details |
/canvas/url_info/details |
Consulta de detalhes de URL de uma variação de mensagem específica em uma etapa do Canva. |
| Permissão | Endpoint | Descrição |
|---|---|---|
segments.list |
/segments/list |
Consulta de uma lista de segmentos. |
segments.data_series |
/segments/data_series |
Consulta para análise de dados de segmento em um intervalo de tempo. |
segments.details |
/segments/details |
Consulta de detalhes de um segmento específico. |
| Permissão | Endpoint | Descrição |
|---|---|---|
purchases.product_list |
/purchases/product_list |
Faça uma consulta para obter uma lista de produtos comprados em seu app. |
purchases.revenue_series |
/purchases/revenue_series |
Faça uma consulta para obter o valor total gasto por dia em seu app em um período. |
purchases.quantity_series |
/purchases/quantity_series |
Consulte o número total de compras por dia em seu app em um intervalo de tempo. |
| Permissão | Endpoint | Descrição |
|---|---|---|
events.list |
/events/list |
Consulta de uma lista de eventos personalizados. |
events.data_series |
/events/data_series |
Consulte as ocorrências de um evento personalizado em um intervalo de tempo. |
| Permissão | Endpoint | Descrição |
|---|---|---|
sessions.data_series |
/sessions/data_series |
Faça uma consulta para obter a quantidade de sessões por dia em um período. |
| Permissão | Endpoint | Descrição |
|---|---|---|
kpi.dau.data_series |
/kpi/dau/data_series |
Faça uma consulta para obter a quantidade de usuários ativos únicos por dia em um período. |
kpi.mau.data_series |
/kpi/mau/data_series |
Faça uma consulta para obter o total de usuários ativos únicos em um intervalo de 30 dias ao longo de um período. |
kpi.new_users.data_series |
/kpi/new_users/data_series |
Faça uma consulta para obter a quantidade de usuários novos por dia em um período. |
kpi.uninstalls.data_series |
/kpi/uninstalls/data_series |
Faça uma consulta para obter a quantidade de desinstalações de app por dia em um período. |
| Permissão | Endpoint | Descrição |
|---|---|---|
templates.email.create |
/templates/email/create |
Crie um novo modelo de e-mail no dashboard. |
templates.email.info |
/templates/email/info |
Faça uma consulta para obter informações de um modelo específico. |
templates.email.list |
/templates/email/list |
Consulte uma lista de modelos de e-mail. |
templates.email.update |
/templates/email/update |
Atualizar um modelo de e-mail armazenado no dashboard. |
| Permissão | Descrição |
|---|---|
sso.saml.login |
Configure o login iniciado pelo provedor de identidade. Para saber mais, consulte o login iniciado pelo prestador de serviço (SP). |
| Permissão | Endpoint | Descrição |
|---|---|---|
content_blocks.info |
/content_blocks/info |
Faça uma consulta para obter informações de um modelo específico. |
content_blocks.list |
/content_blocks/list |
Faça uma consulta para obter uma lista de blocos de conteúdo. |
content_blocks.create |
/content_blocks/create |
Crie um novo bloco de conteúdo no dashboard. |
content_blocks.update |
/content_blocks_update |
Atualize um bloco de conteúdo existente no dashboard. |
| Permissão | Endpoint | Descrição |
|---|---|---|
preference_center.get |
/preference_center/v1/{preferenceCenterExternalId} |
Obtenha uma Central de Preferências. |
preference_center.list |
/preference_center/v1/list |
Liste as Centrais de Preferências. |
preference_center.update |
/preference_center/v1/preference_center/v1/{preferenceCenterExternalID} |
Crie ou atualize uma Central de Preferências. |
preference_center.user.get |
/preference_center/v1/{preferenceCenterExternalId}/url/{userId} |
Obtenha o link de uma Central de Preferências para um usuário. |
| Permissão | Endpoint | Descrição |
|---|---|---|
subscription.status.set |
/subscription/status/set |
Definir o status do grupo de inscrições. |
subscription.status.get |
/subscription/status/get |
Obtenha o status do grupo de inscrições. |
subscription.groups.get |
/subscription/user/status |
Obtenha o status dos grupos de inscrições nos quais usuários específicos estão explicitamente inscritos e cancelaram a inscrição. |
| Permissão | Endpoint | Descrição |
|---|---|---|
sms.invalid_phone_numbers |
/sms/invalid_phone_numbers |
Faça uma consulta para obter números de telefones inválidos. |
sms.invalid_phone_numbers.remove |
/sms/invalid_phone_numbers/remove |
Remova a sinalização de número de telefone inválido de usuários. |
| Permissão | Endpoint | Descrição |
|---|---|---|
catalogs.add_items |
/catalogs/{catalog_name}/items |
Adicione vários itens a um catálogo existente. |
catalogs.update_items |
/catalogs/{catalog_name}/items |
Atualize vários itens de um catálogo existente. |
catalogs.delete_items |
/catalogs/{catalog_name}/items |
Exclua vários itens de um catálogo existente. |
catalogs.get_item |
/catalogs/{catalog_name}/items/{item_id} |
Obtenha um único item de um catálogo existente. |
catalogs.update_item |
/catalogs/{catalog_name}/items/{item_id} |
Atualize um único item de um catálogo existente. |
catalogs.create_item |
/catalogs/{catalog_name}/items/{item_id} |
Crie um item único em um catálogo existente. |
catalogs.delete_item |
/catalogs/{catalog_name}/items/{item_id} |
Exclua um item único de um catálogo existente. |
catalogs.replace_item |
/catalogs/{catalog_name}/items/{item_id} |
Substitua um item de um catálogo existente. |
catalogs.create |
/catalogs |
Criar um catálogo. |
catalogs.get |
/catalogs |
Obter uma lista de catálogos |
catalogs.delete |
/catalogs/{catalog_name} |
Excluir um catálogo. |
catalogs.get_items |
/catalogs/{catalog_name}/items |
Obtenha uma prévia de itens de um catálogo existente. |
catalogs.replace_items |
/catalogs/{catalog_name}/items |
Substituir itens em um catálogo existente. |
| Permissão | Endpoint | Descrição |
|---|---|---|
sdk_authentication.create |
/app_group/sdk_authentication/create |
Crie uma nova chave de autenticação do SDK para seu app. |
sdk_authentication.primary |
/app_group/sdk_authentication/primary |
Marque uma chave de autenticação do SDK como a chave principal para seu app. |
sdk_authentication.delete |
/app_group/sdk_authentication/delete |
Exclua uma chave de autenticação do SDK para seu app. |
sdk_authentication.keys |
/app_group/sdk_authentication/keys |
Obtenha todas as chaves de autenticação do SDK para seu app. |
Gerenciamento de chaves da API REST
Você pode visualizar detalhes ou excluir chaves de API REST existentes na guia Configurações > APIs e identificadores > Chaves de API. Observe que você não pode editar as chaves da API REST depois de criá-las.
A guia Chaves de API inclui as seguintes informações para cada chave:
| Campo | Descrição |
|---|---|
| Nome da chave de API | O nome dado à chave na criação. |
| Identificador | A chave de API. |
| Criado por | O endereço de e-mail do usuário que criou a chave. Este campo aparece como “N/A” para chaves criadas antes de junho de 2023. |
| Data de criação | A data em que essa chave foi criada. |
| Último envio | A data em que essa chave foi usada pela última vez. Este campo aparece como “N/A” para chaves que nunca foram usadas. |
Para visualizar os detalhes de uma chave de API, passe o mouse sobre a chave e selecione View. Isso inclui todas as permissões que essa chave tem, IPs na lista de permissões (se houver) e se essa chave foi aceita na lista de permissões de IP do Braze.
Nota ao deletar um usuário, o Braze não exclui as chaves de API associadas que o usuário criou. Para excluir uma chave, passe o mouse sobre a chave e selecione Delete.
Segurança da chave da API REST
As chaves de API são usadas para autenticar uma chamada de API. Ao criar uma nova chave da API REST, você precisa dar a ela acesso a endpoints específicos. Ao atribuir permissões específicas a uma chave de API, você pode limitar exatamente quais chamadas uma chave de API pode autenticar.
Como as chaves da API REST permitem o acesso a endpoints da API REST potencialmente confidenciais, proteja essas chaves e compartilhe-as apenas com parceiros confiáveis. Elas nunca devem ser expostas publicamente. Por exemplo, não use essa chave para fazer chamadas AJAX em seu site nem a exponha de qualquer outra forma pública.
Uma boa prática de segurança é atribuir a um usuário apenas o acesso necessário para concluir seu trabalho: esse princípio também pode ser aplicado às chaves de API atribuindo permissões a cada chave. Essas permissões proporcionam mais segurança e controle sobre as diferentes áreas da sua conta.
Como as chaves da API REST permitem o acesso a endpoints da API REST potencialmente confidenciais, certifique-se de que elas sejam armazenadas e usadas com segurança. Por exemplo, não use essa chave para fazer chamadas AJAX em seu site nem a exponha de qualquer outra forma pública.
Se você expuser acidentalmente uma chave, pode excluí-la no console de desenvolvedor. Para ajuda com esse processo, abra um ticket de suporte.
Lista de permissões de IP da API
Para maior segurança, você pode especificar uma lista de endereços IP e sub-redes que têm permissão para fazer solicitações de API REST para uma determinada chave de API REST. Isso é chamado de lista de permissões. Para permitir endereços IP ou sub-redes específicos, adicione-os à seção Lista de permissões de IPs ao criar uma nova chave da API REST:
Se você não especificar nenhum, as solicitações poderão ser enviadas de qualquer endereço IP.
Se você estiver criando um webhook Braze para Braze e usando lista de permissões, veja a lista de IPs a serem permitidos.
Autenticação e segurança da API
Autenticação por token Bearer
O Braze autentica as solicitações da API REST usando a chave da API REST passada como um token Bearer no cabeçalho da Authorization da solicitação. Ao enviar uma solicitação, inclua sua chave de API no seguinte formato:
1
Authorization: Bearer YOUR_REST_API_KEY
Em cada solicitação, o Braze realiza as seguintes verificações de validação do lado do servidor:
- Validade do token: Verifica se a chave da API REST existe no Braze e está ativa (por exemplo, não revogada ou desativada).
- Autorização do token: Confirma se a chave da API tem as permissões necessárias para o endpoint solicitado.
Se a autenticação falhar, a API retorna uma resposta de erro com um código de status HTTP. Por exemplo, 401 Unauthorized indica uma chave inválida ou ausente, enquanto 403 Forbidden indica que a chave não tem permissão para o endpoint solicitado. Para saber mais, veja erros da API.
Segurança em nível de rede
As solicitações da API REST para o Braze são protegidas por criptografia de Segurança de Camada de Transporte (TLS) ao longo de todo o caminho da solicitação. A tabela a seguir descreve o fluxo de rede para uma solicitação de API do seu servidor para o Braze:
| Etapa | Componente | Descrição |
|---|---|---|
| 1 | Seu servidor | Inicia uma solicitação HTTPS com criptografia TLS. |
| 2 | Cloudflare | Termina a conexão TLS do cliente e aplica proteções em nível de rede. |
| 3 | Balanceador de Carga de Rede (NLB) | Encaminha pacotes para a infraestrutura da aplicação. Os NLBs operam na Camada 4, o que significa que não há proxy na Camada 7. Os pacotes são encaminhados sem inspeção ou modificação em nível HTTP. |
| 4 | ingress do NGINX | Termina a conexão TLS interna e roteia a solicitação. |
| 5 | Unicorn (servidor de aplicação) | Processa a solicitação autenticada. |
A criptografia TLS cobre cada link na cadeia. Seu servidor se conecta ao Cloudflare via TLS, e o Cloudflare estabelece uma conexão TLS separada através do NLB para o ingress do NGINX, assim sua chave de API e os dados da solicitação permanecem criptografados em trânsito.
Recursos adicionais
Biblioteca de cliente Ruby
Se você estiver implementando o Braze usando Ruby, pode usar a biblioteca cliente Ruby para reduzir o tempo de importação de dados. Uma biblioteca de cliente é uma coleção de códigos específicos de uma linguagem de programação - neste caso, Ruby - que facilita o uso de uma API.
A biblioteca do cliente Ruby é compatível com os endpoints do usuário.
Esta biblioteca cliente está em beta. Para ajudar a melhorar esta biblioteca, envie feedback para [email protected].
Editar esta página no GitHub