> 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/upload-de-arquivos.md).

# Upload de Arquivos

Permite o upload de arquivos para o plugin diretamente pela interface ou programaticamente a partir da página host. O usuário ou a página host serão capazes de anexar laudos, exames e outros.

### Visão geral

O recurso de upload de arquivos do VOA Plugin permite:

* Usuários finais enviarem arquivos pela UI (arrastar e soltar, seletor de arquivos ou colar).
* A aplicação host enviar arquivos programaticamente via API JavaScript.
* Monitorar o ciclo completo de upload por eventos (`started`, `progress`, `success`, `error`).

### Como utilizar

#### Para permitir o upload pela UI

1. Inicialize e monte o plugin seguindo o [Fluxo de uso](https://docs.voa.health/integracao/plugin/fluxo-de-uso.md)
2. Ative a flag `enableFileUpload: true`
3. (Opcional) habilite as flags `messageSubscriptions` e `includeUploadStartedContent` para que a página host receba uma mensagem contendo uma cópia do arquivo

Com isso, o usuário poderá fazer upload de arquivos diretamente no VOA Plugin. Além disso, se a flag `messageSubscriptions` estiver ativa (o valor padrão é `true`) a página host irá receber eventos para monitorar o progresso do upload. Caso a flag `includeUploadStartedContent` também estiver ativa, o evento `voa.plugin.file.upload.started` irá incluir uma chave `content` com o arquivo.

#### Para fazer upload programaticamente

1. Inicialize e monte o plugin seguindo o [Fluxo de uso](https://docs.voa.health/integracao/plugin/fluxo-de-uso.md)
2. Chame a função `uploadFiles` passando os arquivos
3. Não é necessário habilitar esta feature. Se não receber as mensagens sobre o progresso do upload verifique se a flag `messageSubscriptions` não está `false`

Exemplo:

```js
const input = document.querySelector('input[type="file"]');
const files = Array.from(input.files || []);

VoaPlugin.instance.uploadFiles(files);
```

### Escutando eventos de progresso do upload

1. Inicialize e monte o plugin seguindo o [Fluxo de uso](https://docs.voa.health/integracao/plugin/fluxo-de-uso.md)
2. Chame a função `addMessageListener` passando uma *callback* para recebimento de mensagens

Exemplo:

```js
VoaPlugin.instance.addMessageListener((message) => {
  switch (message.eventName) {
    case "voa.plugin.file.upload.started":
      console.log("Upload iniciado:", message.eventData.fileId);
      break;
    case "voa.plugin.file.upload.progress":
      console.log("Processando:", message.eventData.message);
      break;
    case "voa.plugin.file.upload.success":
      console.log("Upload concluído:", message.eventData.fileId);
      break;
    case "voa.plugin.file.upload.error":
      console.error("Falha no upload:", message.eventData.error?.message);
      break;
  }
});
```

### Configurações

#### Opções no `mount` <a href="#op-c3-a7-c3-b5es-no-mount" id="op-c3-a7-c3-b5es-no-mount"></a>

<table><thead><tr><th>Opção</th><th width="112.57421875">Tipo</th><th width="106.79296875">Padrão</th><th>Descrição</th></tr></thead><tbody><tr><td><code>enableFileUpload</code></td><td><code>boolean</code></td><td><code>false</code></td><td>Exibe recursos de upload na UI do plugin para o usuário final.</td></tr><tr><td><code>messageSubscriptions</code></td><td><code>boolean</code></td><td><code>true</code></td><td>Controla se a página host recebe eventos do plugin.</td></tr><tr><td><code>includeUploadStartedContent</code></td><td><code>boolean</code></td><td><code>false</code></td><td>Quando <code>true</code>, inclui o objeto <code>File</code> bruto em <code>eventData.content</code> do evento <code>started</code>.</td></tr></tbody></table>

### Métodos da API

<table><thead><tr><th width="200.89453125">Método</th><th width="117.73046875">Parâmetro</th><th width="85.53515625">Tipo</th><th>Descrição</th></tr></thead><tbody><tr><td><code>uploadFiles(files)</code></td><td><code>files</code></td><td><code>File[]</code></td><td>Envia uma lista de arquivos para o pipeline de upload do plugin. É permitido o envio de até <strong>3 arquivos</strong> simultaneamente.</td></tr></tbody></table>

### Eventos de status de upload

| Evento                            | Quando ocorre                                   |
| --------------------------------- | ----------------------------------------------- |
| `voa.plugin.file.upload.started`  | O upload começou após obtenção de URL assinada. |
| `voa.plugin.file.upload.progress` | Atualização do processamento do arquivo.        |
| `voa.plugin.file.upload.success`  | Upload e processamento finalizados com sucesso. |
| `voa.plugin.file.upload.error`    | Falha de validação, upload ou processamento.    |

#### Campos comuns no `eventData`

<table><thead><tr><th width="139.5546875">Campo</th><th width="191.9609375">Tipo</th><th>Descrição</th></tr></thead><tbody><tr><td><code>fileId</code></td><td><code>string | null</code></td><td>ID do arquivo quando disponível. Pode ser <code>null</code> em falhas de validação.</td></tr><tr><td><code>fileName</code></td><td><code>string</code></td><td>Nome original do arquivo.</td></tr><tr><td><code>source</code></td><td><code>"user" | "host"</code></td><td>Origem do envio (UI ou página host).</td></tr></tbody></table>

#### Campos adicionais por evento <a href="#campos-adicionais-por-evento" id="campos-adicionais-por-evento"></a>

<table><thead><tr><th width="114.69140625">Evento</th><th>Campo</th><th>Tipo</th><th>Descrição</th></tr></thead><tbody><tr><td><code>error</code></td><td><code>error</code></td><td><code>{ code?: string, message: string }</code></td><td>Detalhes da falha.</td></tr><tr><td><code>started</code></td><td><code>content</code></td><td><code>File | null</code></td><td>Arquivo bruto quando <code>includeUploadStartedContent</code> for <code>true</code>.</td></tr><tr><td><code>progress</code></td><td><code>message</code></td><td><code>string</code></td><td>Mensagem de andamento do processamento.</td></tr></tbody></table>

### FAQ

#### O upload pela API depende de `enableFileUpload`? <a href="#o-upload-pela-api-depende-de-enablefileupload" id="o-upload-pela-api-depende-de-enablefileupload"></a>

Não. `uploadFiles(files)` funciona mesmo com `enableFileUpload: false`.

#### Por que recebo erro de validação antes do upload começar? <a href="#por-que-recebo-erro-de-valida-c3-a7-c3-a3o-antes-do-upload-come-c3-a7ar" id="por-que-recebo-erro-de-valida-c3-a7-c3-a3o-antes-do-upload-come-c3-a7ar"></a>

O arquivo foi rejeitado nas regras de entrada (tipo, tamanho ou estrutura do PDF ou imagem). Nesses casos, o upload não é iniciado.

#### Como saber se o arquivo veio da UI/usuário ou da aplicação host? <a href="#como-saber-se-o-arquivo-veio-da-ui-ou-da-aplica-c3-a7-c3-a3o-host" id="como-saber-se-o-arquivo-veio-da-ui-ou-da-aplica-c3-a7-c3-a3o-host"></a>

Sempre verifique `eventData.source`:

* `"user"`: upload feito na UI do plugin pelo usuário.
* `"host"`: upload feito programaticamente via `uploadFiles(files)`.

#### O `eventData.content` vem preenchido como `null` no evento `started`? <a href="#quando-eventdatacontent-vem-preenchido-no-evento-started" id="quando-eventdatacontent-vem-preenchido-no-evento-started"></a>

Somente é enviado o arquivo quando habilitada a flag: `includeUploadStartedContent: true`.\
Por padrão (`false`), o campo vai como `null`.

#### Posso enviar múltiplos arquivos de uma vez? <a href="#posso-enviar-m-c3-baltiplos-arquivos-de-uma-vez" id="posso-enviar-m-c3-baltiplos-arquivos-de-uma-vez"></a>

Sim. Eles entram na fila com processamento concorrente de até 3 arquivos.
