Este artigo é para Proprietários e Administradores de estúdio que ligam outras ferramentas ao bsport. Aborda a criação, o acompanhamento e a revogação de chaves API em Definições. Para notificações de eventos, consulte "Gerir os seus webhooks".
Para mais informações sobre a API pública do bsport, consulte a documentação dedicada
Visão geral
Uma chave API permite que uma ferramenta de confiança leia e atualize os dados do seu estúdio através da API do bsport. Ferramentas de relatórios, integrações personalizadas e plataformas de automação usam chaves para se ligarem.
Gira as chaves em Definições > Webhooks e APIs, no separador API. Cada chave pertence ao seu estúdio e está associada a um nome de ferramenta, para que possa ver qual ferramenta usa qual chave.
Quem pode utilizá-la:
Condição | O que vê |
A sua função é Proprietário ou Administrador, e o seu plano bsport inclui a API Pública (Build, Engage ou Elevate) | O separador API com as suas chaves e o botão Criar chave API. |
A sua função é Proprietário ou Administrador, e o seu plano bsport não inclui a API Pública | A mensagem "Atualize o seu plano para usar a API". Contacte o bsport para atualizar. |
Qualquer outra função | Sem separador API. O separador Webhooks permanece disponível se a sua função tiver a permissão de Webhook. |
A API Pública também pode ser adicionada a um estúdio fora destes planos. Contacte o bsport para saber mais.
O que pode fazer
Criar uma chave API para uma ferramenta.
Escolher durante quanto tempo a chave permanece válida: 3 meses, 6 meses ou 1 ano.
Ver todas as chaves com a respetiva ferramenta, data de expiração, data de criação, contacto e estado.
Revogar uma chave quando deixa de usar uma ferramenta ou suspeita de uma fuga.
Abrir a documentação da API através do link no canto superior direito da página.
Casos de uso comuns
Como criar uma chave API
Vá a Definições > Webhooks e APIs e abra o separador API.
Selecione Criar chave API.
Preencha o formulário:
Nome da ferramenta (obrigatório): até 24 carateres, usando letras minúsculas, dígitos, hífenes ou sublinhados, por exemplo
reporting-tool. Uma chave ativa não pode partilhar o nome da ferramenta com outra chave ativa.Expira em: 3 meses (predefinição), 6 meses ou 1 ano. A chave deixa de funcionar no final desse período.
E-mail de contacto (opcional): quem o bsport contacta acerca desta chave. Deixe em branco para usar o e-mail do proprietário do estúdio.
Selecione Criar.
Leia o aviso no formulário. Uma chave dá acesso total de administrador ao seu estúdio, incluindo dados de clientes e pagamentos. Partilhe-a apenas com ferramentas e pessoas em quem confia.
Como guardar a sua chave
Depois de selecionar Criar, a janela Guarde a sua chave API mostra a chave. Esta é a única vez que a vê.
Selecione Copiar chave e guarde-a num gestor de palavras-passe. Não a partilhe por e-mail ou chat.
Selecione Copiar cabeçalhos para copiar o que a sua ferramenta deve enviar com cada pedido.
Selecione Fechar.
Se fechar a janela antes de copiar, o bsport pede-lhe para confirmar. Se fechar mesmo assim, não poderá voltar a ver a chave: crie uma nova chave e revogue a primeira.
Como ligar a sua ferramenta
A sua ferramenta envia dois cabeçalhos com cada pedido à API do bsport:
Cabeçalho | Valor |
| O nome da ferramenta que escolheu. |
| A chave que copiou. |
Os endpoints e exemplos estão na documentação da API.
Como revogar uma chave
No separador API, encontre a chave na lista.
Selecione Revogar chave.
Confirme na janela Revogar chave API?
A ferramenta deixa de funcionar de imediato e não é possível anular esta ação. A chave permanece na lista com o estado Revogada e a data de revogação. O nome da ferramenta volta a ficar disponível.
Como substituir uma chave antes de expirar
As chaves não podem ser editadas nem prolongadas. Para renovar uma:
Crie uma nova chave com um novo nome de ferramenta, por exemplo
reporting-tool-2, ou reutilize o nome assim que a chave antiga tiver expirado ou sido revogada.Atualize a sua ferramenta com a nova chave.
Revogue a chave antiga.
Como funciona
Configuração. Um Proprietário ou Administrador cria a chave e copia-a uma vez.
Ativação. A chave funciona assim que existe. A sua ferramenta envia os dois cabeçalhos com cada pedido.
Utilização normal. A lista mostra o estado de cada chave.
Após a ação. Revogue uma chave para a parar de imediato, ou deixe-a expirar.
Estados das chaves
Estado | Significado |
Ativa | A chave funciona e expira em mais de 30 dias. |
Expira em breve | A chave funciona e expira dentro de 30 dias. Planeie a sua substituição. |
Expirada | A chave atingiu a data de expiração e já não funciona. |
Revogada | Revogou a chave. Já não funciona. |
Na coluna Contacto, Você assinala as chaves que listam o seu próprio e-mail.
Comportamentos importantes
Exibição única. O bsport não guarda a chave num formato legível. Ninguém pode voltar a mostrá-la, incluindo o bsport.
Limite de 50 chaves. Um estúdio pode ter 50 chaves que não estejam revogadas. As chaves expiradas contam até que as revogue. Ao atingir o limite, a página mostra um aviso e o formulário de criação não pode ser enviado: revogue uma chave expirada para criar outra.
Nomes de ferramentas únicos. O nome não pode coincidir com o de uma chave ativa. As chaves expiradas e revogadas libertam o respetivo nome.
Acesso total. Uma chave não está limitada a uma área do seu estúdio. Crie uma chave por ferramenta, para poder revogar uma única ferramenta sem afetar as outras.
Alterações de plano. Se o seu plano bsport deixar de incluir a API Pública, o separador API mostra a mensagem de atualização e o bsport recusa novas chaves.
Os webhooks são separados. As chaves API não criam webhooks. Consulte "Gerir os seus webhooks".
Perguntas frequentes
Perdi a minha chave. Posso voltar a vê-la?
Não. Crie uma nova chave, atualize a sua ferramenta e revogue a chave perdida.
Porque não tenho um separador API?
O separador é apenas para Proprietários e Administradores. Peça a um deles para criar a chave.
Porque vejo "Atualize o seu plano para usar a API"?
O seu plano bsport não inclui a API Pública. Esta vem incluída nos planos Build, Engage e Elevate. Contacte o bsport para atualizar ou adicionar esta funcionalidade.
Para que serve o e-mail de contacto?
É a pessoa que o bsport contacta acerca da chave. Se o deixar em branco, o bsport usa o e-mail do proprietário do estúdio.
Posso escolher uma data de expiração?
O formulário oferece 3 meses, 6 meses ou 1 ano.
Revogar uma chave demora tempo?
Não. A ferramenta é recusada de imediato.