> ## Documentation Index
> Fetch the complete documentation index at: https://docs-platform.services-valid.com.br/llms.txt
> Use this file to discover all available pages before exploring further.

# Anexar documento ao envelope

> Anexa um PDF ao envelope. Pode ser chamada várias vezes para múltiplos documentos.

Anexa um PDF a um envelope em rascunho. A chamada faz upload para o Google Cloud Storage e cria um registro no banco. Pode ser chamada várias vezes para anexar múltiplos documentos ao mesmo envelope.

**Autenticação**: `x-api-key` no header. Também aceita `Authorization: Bearer` com headers de projeto/organização.

## Parâmetros

<ParamField path="uuid" type="string" required>
  UUID do envelope rascunho.
</ParamField>

<ParamField body="filename" type="string" required>
  Nome do arquivo (ex.: `"contrato.pdf"`). Usado para identificação e downloads.
</ParamField>

<ParamField body="content" type="string" optional>
  Conteúdo do PDF em Base64. Obrigatório se `url` não for fornecido.
</ParamField>

<ParamField body="url" type="string" optional>
  URL remota do PDF (ex.: `"https://seu-servidor.com/doc.pdf"`). Obrigatório se `content` não for fornecido. A URL é baixada pelo servidor.
</ParamField>

## Respostas

<ResponseField name="fileUuid" type="string">
  UUID do arquivo recém-anexado. Use-o em chamadas futuras (ex.: [`DELETE .../:uuid/documents/:fileUuid`](/plataforma/assinatura-digital/api/delete-envelope-document)).
</ResponseField>

<ResponseField name="filename" type="string">
  Nome do arquivo.
</ResponseField>

<ResponseField name="sizeBytes" type="integer">
  Tamanho em bytes.
</ResponseField>

<ResponseField name="sha256" type="string">
  Hash SHA-256 do conteúdo (Base64).
</ResponseField>

## Erros

Veja [Autenticação e erros](/plataforma/assinatura-digital/api/erros-e-autenticacao).

* **400**: PDF vazio, formato inválido, ou nem `content` nem `url` fornecidos.
* **404**: Envelope não encontrado ou não pertence ao seu projeto.
* **409**: Envelope não está em rascunho.

<ResponseExample>
  ```json theme={"theme":"catppuccin-latte"}
  HTTP/1.1 201 Created
  Content-Type: application/json

  {
    "fileUuid": "6ba7b811-9dad-11d1-80b4-00c04fd430c8",
    "filename": "contrato.pdf",
    "sizeBytes": 250000,
    "sha256": "abc123def456789..."
  }
  ```

  ```json theme={"theme":"catppuccin-latte"}
  HTTP/1.1 400 Bad Request
  Content-Type: application/json

  {
    "statusCode": 400,
    "message": "PDF is empty or invalid"
  }
  ```
</ResponseExample>

## Exemplo (Content)

```bash theme={"theme":"catppuccin-latte"}
curl -X POST "https://api.valid.com/signer/v1/envelopes/550e8400-e29b-41d4-a716-446655440000/documents" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "filename": "contrato.pdf",
    "content": "JVBERi0xLjQKJeLjz9MNCjEgMCBvYmo..."
  }'
```

## Exemplo (URL)

```bash theme={"theme":"catppuccin-latte"}
curl -X POST "https://api.valid.com/signer/v1/envelopes/550e8400-e29b-41d4-a716-446655440000/documents" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "filename": "contrato.pdf",
    "url": "https://seu-servidor.com/documentos/contrato.pdf"
  }'
```

## Importante

* **Múltiplos documentos**: chame esta operação quantas vezes precisar. Todos ficam anexados ao mesmo envelope e todos serão assinados.
* **Sem mudança de estado**: anexar um documento não muda o estado do envelope (continua "Enviar arquivos"). Você avança manualmente com [`POST .../:uuid/advance`](/plataforma/assinatura-digital/api/post-envelope-advance).
* **Validação de PDF**: o arquivo é validado — PDFs corrompidos ou inválidos retornam 400.

## Próximas etapas

1. Anexe todos os PDFs necessários.
2. Quando estiver pronto, chame [`POST .../:uuid/advance`](/plataforma/assinatura-digital/api/post-envelope-advance) para ir ao passo de signatários.

## Relacionado

* [`DELETE .../:uuid/documents/:fileUuid`](/plataforma/assinatura-digital/api/delete-envelope-document) — remover documento
* [`POST .../:uuid/advance`](/plataforma/assinatura-digital/api/post-envelope-advance) — prosseguir com os signatários
* [`GET /signer/v1/envelopes/:uuid`](/plataforma/assinatura-digital/api/get-envelope-by-id) — listar documentos anexados


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.