> 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

### 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`, `success`, `error`).

### Como utilizar

#### Para permitir o upload pela UI 

1. Inicialize e monte o plugin seguindo o [Fluxo de uso](https://app.gitbook.com/o/ecmHHcmJZnUA45HQ7O36/s/NbyT4Nmc4kxRl74PaKL4/~/edit/~/changes/68/integracao/plugin/fluxo-de-uso)
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

Agora 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://app.gitbook.com/o/ecmHHcmJZnUA45HQ7O36/s/NbyT4Nmc4kxRl74PaKL4/~/edit/~/changes/68/integracao/plugin/fluxo-de-uso)
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://app.gitbook.com/o/ecmHHcmJZnUA45HQ7O36/s/NbyT4Nmc4kxRl74PaKL4/~/edit/~/changes/68/integracao/plugin/fluxo-de-uso)
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.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.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></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.


---

# 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/integracao/plugin/upload-de-arquivos.md?ask=<question>&goal=<endgoal>
```

`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.