> For the complete documentation index, see [llms.txt](https://docs.voa.health/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.voa.health/api-reference/chaves-de-api.md). # Chaves de API ### Visão Geral {% hint style="success" %} Quer integrar seu sistema à Voa? Use o [Plugin](https://docs.voa.health/integracao/plugin), a forma ideal de embarcar a Voa na sua aplicação. {% endhint %} 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. {% hint style="info" %} 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_`. {% endhint %} *** ### 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](https://docs.voa.health/integracao/plugin) para gravar atendimentos e gerar documentos. {% hint style="warning" %} **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. {% endhint %} ### 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](https://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 {% hint style="warning" %} **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. {% endhint %} 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 {% hint style="danger" %} A exclusão de uma chave é **permanente e imediata**. Qualquer serviço ou integração que utilize esta chave deixará de funcionar instantaneamente. Certifique-se de que nenhum sistema depende da chave antes de excluí-la. {% endhint %} *** ### Boas Práticas de Segurança #### Armazenamento seguro * **Nunca** exponha suas chaves em código-fonte público (GitHub, GitLab, etc.) * Utilize **variáveis de ambiente** ou **cofres de segredos** (como AWS Secrets Manager, HashiCorp Vault ou .env files) * **Nunca** inclua chaves diretamente no código da sua aplicação #### Rotação de chaves * Crie novas chaves periodicamente e substitua as antigas * Após a troca, exclua a chave anterior para prevenir 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: * **Email:** * **Documentação geral:** [docs.voa.health](https://docs.voa.health/) --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.voa.health/api-reference/chaves-de-api.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.