> 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/integracao/plugin/fluxo-de-uso.md).

# Fluxo de uso

## Instalação

Para utilizar o Plugin, importe o script no HTML da página. Você pode adicioná-lo diretamente ao HTML ou carregá-lo programaticamente com JavaScript.

* **Adicionar diretamente no HTML**

```html
<script type="module" src="https://integration.voa.health/plugin.js"></script>
```

* **Adicionar programaticamente com JavaScript**

```html
<script>
    (() => {
        const script = document.createElement("script");
        script.src = "https://integration.voa.health/plugin.js";
        script.type = "module";

        document.head.appendChild(script);

        script.onload = () => {
            // VoaPlugin.instance estará disponível no escopo global da página.
        };
    })();
</script>
```

Ao carregar o script, `VoaPlugin.instance` é adicionado ao contexto global da página.

## Inicialização

{% hint style="warning" %}
Nunca passe uma Chave de API ao Plugin no navegador. Mantenha essa chave no seu backend e use um token de sessão temporário. Consulte [Autenticação](https://docs.voa.health/integracao/plugin/autenticacao.md) para implementar a troca e a renovação segura.
{% endhint %}

Inicialize o Plugin com um provider que busca tokens de sessão no backend da sua aplicação:

```javascript
async function getVoaSessionToken() {
    const response = await fetch("/api/voa/session-token", {
        method: "POST",
        credentials: "include"
    });

    if (!response.ok) {
        throw new Error("Não foi possível autenticar o Plugin Voa");
    }

    const { access } = await response.json();
    return access;
}

VoaPlugin.instance.init({ getToken: getVoaSessionToken });

await VoaPlugin.instance.mount({
    doctorId: "", // Identificador do médico
    patientId: "", // Identificador do paciente
    consultationId: "", // Identificador da consulta
    options: {
        darkMode: false,
        allowCreateModels: false,
        enableFillEhr: true,
        consultationType: "IN_PERSON",
        allowChangeConsultationType: true
    }
});
```

Para inicializar com um token já obtido e ainda permitir renovação, passe `token` e `getToken` juntos. Veja as opções e o comportamento de renovação em [Autenticação](https://docs.voa.health/integracao/plugin/autenticacao.md).

Não é possível abrir mais de uma instância do Plugin na mesma página. Chamadas a `mount()` enquanto já existe uma instância aberta não surtirão efeito.

#### Parâmetros de configuração

O argumento *options* pode receber os seguintes parâmetros:

<table><thead><tr><th width="208.09375">Option</th><th>Descrição</th><th width="156.484375">Tipo</th><th width="129.61328125">Default</th></tr></thead><tbody><tr><td>renderElement</td><td>Elemento HTML do DOM no qual o plugin será renderizado. Caso nenhum elemento seja informado, o plugin será uma janela flutuante na página com botões de fechar e minimizar/maximizar.</td><td>HTMLElement</td><td>undefined</td></tr><tr><td>openMinimized</td><td>Abre o Plugin minimizado. Funciona apenas sem <code>renderElement</code>.</td><td>Boolean</td><td>false</td></tr><tr><td>darkMode</td><td>Habilita o modo noturno da UI.</td><td>Boolean</td><td>false</td></tr><tr><td>allowCreateModels</td><td>Permite que o usuário crie modelos de documento.</td><td>Boolean</td><td>true</td></tr><tr><td>consultationType</td><td>Permite pré-selecionar o tipo da consulta.</td><td>"TELEMEDICINE" ou "IN_PERSON"</td><td>"IN_PERSON"</td></tr><tr><td>defaultTemplateId</td><td>Id (UUID) do modelo de documento que o Plugin usa como padrão neste atendimento. Ordem de prioridade: preferência salva do usuário → <code>defaultTemplateId</code> → "Anamnese padrão". Um id inexistente ou sem acesso é ignorado, com um aviso no console. Vale só para este <code>mount</code>. O id fica no menu do card do modelo, em Modelos → "Copiar ID do modelo". <a href="#modelo-padrao-do-documento">Veja mais</a>.</td><td>String</td><td>undefined</td></tr><tr><td>allowChangeConsultationType</td><td>Habilita a troca do tipo da consulta por parte do usuário.</td><td>Boolean</td><td>true</td></tr><tr><td>allowCopyDocument</td><td>Exibe um botão de "Copiar Documento" para área de transferência.</td><td>Boolean</td><td>true</td></tr><tr><td>enableFillEhr</td><td>Exibe um botão de preencher prontuário ao gerar documentos que dispara um evento com os dados do documento gerado.</td><td>Boolean</td><td>false</td></tr><tr><td>allowScreenSharing</td><td>Caso desabilitado, a opção de compartilhar o áudio da tela para consultas de telemedicina não será exibida para os usuários. A única forma de captar áudio passa a ser enviando programaticamente um mediaStream para o plugin. <a href="https://docs.voa.health/integracao/plugin/mensagens.md#adicionar-media-stream-de-audio">Veja mais</a>.</td><td>Boolean</td><td>true</td></tr><tr><td>enableTelemetry</td><td>Permite que a Voa colete dados de uso do Plugin para identificação de bugs e melhorias.</td><td>Boolean</td><td>true</td></tr><tr><td>enableFileUpload</td><td>Exibe o upload de arquivos na UI do Plugin. <a href="https://docs.voa.health/integracao/plugin/upload-de-arquivos.md">Veja mais</a>.</td><td>Boolean</td><td>false</td></tr><tr><td>includeUploadStartedContent</td><td>Inclui o arquivo em <code>eventData.content</code> do evento <code>voa.plugin.file.upload.started</code>.</td><td>Boolean</td><td>false</td></tr><tr><td>structuredOutputSchema</td><td>Objeto JavaScript correspondente ao schema desejado de documento<br>estruturado da consulta. Se informado, ao usar "Preencher prontuário" o<br>plugin envia a mensagem <a href="https://docs.voa.health/integracao/plugin/mensagens.md">voa.plugin.ehr.fill</a> com o documento em texto; os dados estruturados são enviados em<br>mensagem separada <a href="https://docs.voa.health/integracao/plugin/mensagens.md">voa.plugin.ehr.structured_output</a> com o formato especificado. <a href="https://docs.voa.health/integracao/plugin/output-estruturado.md">Veja como criar o schema</a>.</td><td>Object</td><td>undefined</td></tr><tr><td>editorOptions</td><td>Objeto Javascript com configurações do editor de documentos do Plugin.<br>Opções:<br><br>- disableCopy<br>Desabilita a cópia de blocos no editor.<br><br>- disableDragAndDrop<br>Desabilita a feature de arrastar componentes do editor.</td><td>Object</td><td><pre><code>{
    disableCopy: false,
    disableDragAndDrop: false
}
</code></pre></td></tr><tr><td>messageSubscriptions</td><td>Envia as mensagens do Plugin à página. Se <code>false</code>, nenhuma mensagem é enviada. <a href="https://docs.voa.health/integracao/plugin/mensagens.md">Veja mais</a>.</td><td>Boolean</td><td>true</td></tr></tbody></table>

### Modelo padrão do documento

Com a option `defaultTemplateId`, o prontuário informa qual modelo de documento o Plugin usa como padrão naquele atendimento, por exemplo o modelo da especialidade da consulta. Assim o médico já começa com o modelo certo: o botão "Gerar documento" usa esse modelo e, na lista de modelos, ele aparece com a tag "Padrão".

#### Ordem de prioridade

O Plugin escolhe o modelo padrão nesta ordem:

1. **Preferência salva do usuário**: o modelo que o próprio médico marcou como padrão, se ainda estiver disponível para ele.
2. **`defaultTemplateId`**: o modelo enviado pelo prontuário, se estiver disponível para o usuário.
3. **"Anamnese padrão"**: o modelo padrão da Voa.

{% hint style="info" %}
O valor de `defaultTemplateId` nunca é salvo como preferência do usuário. O médico continua podendo marcar outro modelo como padrão, e essa escolha passa a valer nos próximos atendimentos, acima do modelo enviado pelo prontuário. Por isso, um médico que já marcou um modelo padrão continua vendo o modelo dele.
{% endhint %}

#### Id inválido ou sem acesso

Se o id não existir ou o modelo não estiver disponível para o usuário (por exemplo, um modelo apagado ou de outra organização), o Plugin ignora o valor, registra um aviso no console do navegador e segue a ordem acima sem ele. O `mount` não falha.

#### Validade

O valor vale só para o `mount` em que foi enviado. Ao montar o Plugin para outro atendimento, envie o id do modelo daquele atendimento. Um `mount` sem `defaultTemplateId` volta à regra padrão e não herda o valor do `mount` anterior.

#### Onde encontrar o id

* **Na plataforma Voa**: acesse **Modelos**, abra o menu do card do modelo e clique em **"Copiar ID do modelo"**. O id é copiado para a área de transferência.
* **Modelos criados pela Voa para a sua organização**: peça os ids à nossa equipe de integração em <integration@voahealth.com>.

Os modelos da organização ficam disponíveis para todos os usuários dela. O id não muda quando o modelo é editado ou renomeado, então ele pode ficar guardado na configuração do prontuário.

Exemplo, com o prontuário guardando o modelo de cada especialidade:

```javascript
const modelosPorEspecialidade = {
    pediatria: "3f2b8c1e-7d4a-4b9e-a1c2-5e6f7a8b9c0d", // Id do modelo "Pediatria"
    obstetricia: "9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c6d" // Id do modelo "Obstetrícia"
};

await VoaPlugin.instance.mount({
    doctorId: "", // Identificador do médico
    patientId: "", // Identificador do paciente
    consultationId: "", // Identificador da consulta
    options: {
        consultationType: "IN_PERSON",
        defaultTemplateId: modelosPorEspecialidade[especialidadeDaConsulta] // Sem id, vale a regra padrão
    }
});
```

***

### Desmontagem

Para fechar uma instância aberta do Plugin, chame `unmount()`. Sempre utilize essa função em vez de remover o Plugin manualmente do DOM, garantindo a sincronização dos dados e a limpeza dos recursos de autenticação e memória.

Caso o usuário feche o Plugin manualmente, a desmontagem também é realizada. A opção de fechar manualmente só é exibida quando nenhum `renderElement` é utilizado.

```javascript
VoaPlugin.instance.unmount();
```
