Chaves de API

A página Chaves de API permite gerenciar as credenciais usadas por sistemas externos para se autenticar no Power ATA. Atualmente, essas chaves podem autorizar a criação de reuniões a partir de arquivos de áudio ou transcrições gerados externamente.

Proteja a chave

Qualquer pessoa com uma chave válida pode se autenticar como um sistema externo. Mantenha a credencial em sigilo, armazene-a em um cofre de segredos e nunca a publique em código, documentação, logs ou screenshots.

Como acessar

No Centro de Administração, selecione Chaves de API no menu lateral.

Lista de chaves

A tela apresenta as credenciais criadas para a organização.

Coluna	Descrição
Tipo	Finalidade autorizada para a chave
Chave	Identificação mascarada da credencial
Status	Indica se a chave está ativa ou revogada
Criado em	Data e horário de criação ou rotação
Ações	Comandos administrativos disponíveis para a chave

Criar ou rotacionar uma chave

1. Selecione Criar / Rotacionar Chave.
2. Revise a confirmação apresentada pelo sistema.
3. Confirme a operação.
4. Copie a chave exibida.
5. Armazene-a imediatamente em um local seguro.
6. Atualize o sistema externo que utilizará a credencial.

A chave é exibida em texto plano apenas uma vez, no momento da criação ou rotação. Depois disso, a interface apresenta somente uma versão mascarada.

WARNING

A rotação invalida a credencial anterior. Atualize os sistemas integrados para evitar interrupções nas chamadas da API.

Revogar uma chave

Revogue a chave quando ela não for mais necessária ou quando houver suspeita de exposição.

1. Localize a chave na lista.
2. Abra as ações disponíveis.
3. Selecione a opção de revogação.
4. Confirme a operação.
5. Verifique se o status foi alterado para Revogada.

Uma chave revogada não pode mais autenticar requisições e recebe 401 Unauthorized ao ser utilizada.

Integração externa de áudio ou transcrição

Esta referência é destinada a parceiros e clientes que precisam criar reuniões no Power ATA a partir de arquivos de áudio ou transcrições gerados por sistemas externos.

Endpoint

POST /api/meetings/external

• Content-Type: multipart/form-data
• Autenticação: header x-api-key
• Limite de tamanho da requisição: 500 MB

Substitua o domínio nos exemplos pelo endereço informado para o ambiente da sua organização.

Autenticação

Todas as chamadas devem incluir o header:

x-api-key: azbr_sk_XXXX...

Requisições sem o header ou com uma chave inválida ou revogada recebem 401 Unauthorized.

Campos do formulário

Campo	Tipo	Obrigatório	Observações
audioFile	Arquivo	Sim, se audioFiles não for enviado	Caminho de arquivo único
audioFiles	Arquivo múltiplo	Sim, se audioFile não for enviado	Áudio em partes; tem prioridade quando também houver audioFile
userPrincipalName	String	Sim	E-mail do usuário da organização que será o dono da reunião
title	String	Não	Nome da reunião
meetingDate	Data yyyy-MM-dd	Não	Requer meetingTime
meetingTime	Hora	Não	Requer meetingDate
timezone	String	Não	Identificador IANA ou Windows; o padrão é UTC

Formatos aceitos

Arquivo único: audioFile

Formatos aceitos:

.mp3, .wav, .m4a, .aac, .ogg, .flac, .wma, .webm, .vtt

• Os formatos de áudio criam uma reunião com fonte de áudio.
• Um arquivo .vtt é tratado como uma transcrição pronta, não como áudio.
• O conteúdo da transcrição é criptografado antes do armazenamento.

Múltiplos arquivos: audioFiles

Formatos aceitos:

.mp3, .wav, .m4a, .aac, .ogg, .flac, .wma, .opus, .webm, .mp4, .qta

Limites:

• Máximo de 20 arquivos.
• Máximo de 500 MB por arquivo.
• Máximo de 500 MB no total da requisição.

Transcrições em VTT

O formato .vtt não é aceito no envio por audioFiles. Uma transcrição deve ser enviada como arquivo único no campo audioFile. Caso contrário, a API retorna 400 Bad Request.

Exemplos de requisição

Áudio único

curl -X POST https://SEU_DOMINIO/api/meetings/external \
  -H "x-api-key: azbr_sk_XXXX..." \
  -F "audioFile=@input.wav" \
  -F "userPrincipalName=usuario@empresa.com" \
  -F "title=Teste External Audio"

Transcrição VTT

curl -X POST https://SEU_DOMINIO/api/meetings/external \
  -H "x-api-key: azbr_sk_XXXX..." \
  -F "audioFile=@transcript.vtt" \
  -F "userPrincipalName=usuario@empresa.com"

A transcrição é criptografada e passa a ser o transcript da reunião criada.

Áudio dividido em múltiplos arquivos

curl -X POST https://SEU_DOMINIO/api/meetings/external \
  -H "x-api-key: azbr_sk_XXXX..." \
  -F "audioFiles=@parte1.wav" \
  -F "audioFiles=@parte2.wav" \
  -F "userPrincipalName=usuario@empresa.com"

Requisição sem chave

curl -i -X POST https://SEU_DOMINIO/api/meetings/external \
  -F "audioFile=@input.wav"

O resultado esperado é 401 Unauthorized.

Resposta de sucesso

Uma requisição aceita retorna 200 OK com o identificador e o nome da reunião:

{
  "id": "guid-da-reuniao",
  "name": "Nome da Reunião"
}

Erros

HTTP	Causa
400 Bad Request	Nenhum arquivo enviado, extensão não permitida, .vtt no caminho multi-arquivo, fuso horário inválido, excesso de arquivos ou tamanho acima do limite
401 Unauthorized	Header x-api-key ausente, chave inválida ou chave revogada
404 Not Found	userPrincipalName não corresponde a um usuário da organização da chave
429 Too Many Requests	Limite de requisições excedido por chave ou por endereço IP

Limites de requisição

A API aplica os seguintes limites:

• Por chave de API: 10 requisições por minuto.
• Por endereço IP: 30 requisições por minuto.

Ao exceder qualquer um dos limites, a API retorna 429 Too Many Requests.

Testar o limite

for i in $(seq 1 12); do
  curl -s -o /dev/null -w "%{http_code}\n" \
    -X POST https://SEU_DOMINIO/api/meetings/external \
    -H "x-api-key: azbr_sk_XXXX..." \
    -F "audioFile=@input.wav" \
    -F "userPrincipalName=usuario@empresa.com"
done

Após aproximadamente 10 chamadas em um minuto com a mesma chave, o retorno esperado é 429. Quando chaves diferentes são usadas no mesmo endereço, também se aplica o limite aproximado de 30 chamadas por minuto por IP.

Checklist para integração

Antes de colocar a integração em produção:

• Armazene a chave em um cofre de segredos.
• Confirme que o usuário informado pertence à organização da chave.
• Valide o tamanho e a extensão antes do envio.
• Envie meetingDate e meetingTime sempre em conjunto.
• Trate os códigos 400, 401, 404 e 429.
• Planeje a atualização da credencial quando houver rotação.