Ctrlk
For the complete documentation index, see llms.txt. This page is also available as Markdown.

Chaves de API

As Chaves de API permitem que você integre serviços externos diretamente com a sua conta Voa, sem a necessidade de compartilhar suas credenciais de login.

Visão Geral

Quer integrar seu sistema à Voa? Use o Plugin, a forma ideal de embarcar a Voa na sua aplicação.

As Chaves de API do Usuário permitem que você integre serviços externos diretamente com a sua conta Voa, sem a necessidade de compartilhar suas credenciais de login. Cada chave fornece acesso autenticado à API da Voa, vinculado à sua conta pessoal.

As chaves de API do usuário são diferentes das chaves de organização. Elas são vinculadas à sua conta pessoal e possuem o prefixo sk_user_.

Uma Chave de API é uma credencial de longa duração. Nunca a envie ao navegador nem a passe diretamente para VoaPlugin.instance.init(). Para usar o Plugin, mantenha a chave no backend e troque-a por tokens de sessão temporários conforme descrito em Autenticação do Plugin.

O que a Chave de API permite (e o que não permite)

O objetivo da Chave de API é permitir que seus usuários utilizem a Voa dentro do seu sistema — por exemplo, embarcar a Voa no seu prontuário eletrônico via Plugin para gravar atendimentos e gerar documentos.

A Voa não disponibiliza API pública de consulta de dados. A Chave de API não permite ler ou exportar dados da sua conta — como lista de pacientes, consultas, transcrições ou documentos gerados.

Criando uma Chave de API

Passo 1: Acesse as configurações de Integrações

  1. Faça login na plataforma Voa em app.voa.health

  2. No menu lateral esquerdo, clique no ícone de Configurações (engrenagem)

  3. Selecione Integrações — é o último item na lista de configurações

Passo 2: Crie uma nova chave

  1. Na seção Chaves de API, clique no botão + Nova chave

  2. Digite um nome descritivo para a chave (entre 3 e 50 caracteres)

    • Exemplo: Integração com sistema X, Meu App de Prontuário, Automação Zapier

  3. Clique em Criar chave

Passo 3: Copie e guarde a chave

Importante: A chave completa será exibida apenas uma vez, imediatamente após a criação. Copie e guarde em um local seguro. Não será possível visualizá-la novamente.

Após a criação, uma tela será exibida com:

  • A chave no formato mascarado (ex.: sk_user_04••••••••e192e)

  • Um ícone de olho para alternar entre mostrar e ocultar a chave completa

  • Um botão de copiar para copiar a chave para a área de transferência

Clique no botão de copiar ou revele a chave e copie manualmente. Em seguida, armazene-a em um gerenciador de senhas ou cofre de segurança.

Gerenciando suas Chaves

Visualizando chaves existentes

Na página de Integrações, a seção Chaves de API exibe todas as suas chaves ativas com as seguintes informações:

Informação
Descrição

Nome

O nome descritivo que você definiu ao criar a chave

Key Tip

Os primeiros e últimos caracteres da chave (ex.: sk_user_04...e192e)

Data de criação

Quando a chave foi criada

Último uso

Quando a chave foi utilizada pela última vez

Uso total

Número total de requisições feitas com esta chave

Excluindo uma chave

  1. Localize a chave que deseja excluir na lista

  2. Clique no ícone de lixeira (vermelho) à direita da chave

  3. Confirme a exclusão no diálogo de confirmação

A exclusão de uma chave é permanente e impede imediatamente novas autenticações e novas emissões de tokens de sessão. Tokens de sessão já emitidos permanecem válidos até a própria expiração; use validade curta para reduzir essa janela. Confirme que nenhum sistema ainda depende da chave antes de excluí-la.

Boas Práticas de Segurança

Armazenamento seguro

  • Nunca exponha suas chaves em código-fonte público (GitHub, GitLab, etc.)

  • Nunca inclua chaves em HTML, JavaScript, bundles, aplicativos cliente ou armazenamento do navegador

  • Utilize variáveis de ambiente ou cofres de segredos (como AWS Secrets Manager ou HashiCorp Vault) no backend

  • Para o Plugin, exponha ao navegador apenas tokens de sessão temporários; veja Autenticação do Plugin

Rotação de chaves

  • Crie novas chaves periodicamente e substitua as antigas

  • Após a troca, exclua a chave anterior para prevenir novos acessos não autorizados

  • Recomendamos rotacionar suas chaves a cada 90 dias

Princípio do menor privilégio

  • Crie chaves separadas para cada serviço ou integração

  • Use nomes descritivos para facilitar a identificação (ex.: Zapier - Sincronização, App Mobile - Produção)

  • Exclua chaves que não estão mais em uso

Monitoramento

  • Acompanhe o uso total e a data do último uso de cada chave na página de Integrações

  • Se notar uso anômalo, exclua a chave imediatamente e crie uma nova

  • Verifique periodicamente se há chaves não utilizadas que possam ser removidas

Diferenças: Chave de Usuário vs. Chave de Organização

Característica

Chave de Usuário (sk_user_)

Chave de Organização

Prefixo

sk_user_

Sem prefixo padrão

Vinculação

Conta pessoal do usuário

Organização (múltiplos usuários)

Criação

Pelo próprio usuário na aba Integrações

Por administradores da organização

Header

X-VOA-TOKEN

X-VOA-TOKEN

Escopo de acesso

Dados do usuário

Dados da organização

Uso típico

Automações pessoais, integrações individuais

Integrações institucionais, EHRs

Suporte

Para dúvidas ou problemas com chaves de API, entre em contato:

AnteriorEndpoints
PróximoTestes de Carga

Atualizado

Isto foi útil?