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

# Variáveis e arquivos

> Preencha as variáveis de um Canvas com texto, URLs de arquivo, conteúdo em base64 ou arquivos enviados para o Tela

[Variáveis](https://docs.tela.com/pt/craft/using-variables.md) são as entradas de um Canvas. Na requisição, elas vão no objeto `variables`, com o nome da variável exatamente como aparece no Canvas. Cada valor é um texto ou um arquivo.

O diálogo **Conectar via API** gera o snippet com as variáveis do Canvas já no lugar, então você só preenche os valores.

![Snippet com as variáveis do Canvas](https://mintcdn.com/meistrari/jZ7VrspVjrdqJJQA/images/pt/guides/integrating-api/variables-focus.png?fit=max\&auto=format\&n=jZ7VrspVjrdqJJQA\&q=85\&s=7f3f45e14aea846c275175e309797711)

## Texto

Uma variável de texto recebe uma string simples.

```typescript TypeScript Tela SDK theme={null}
variables: {
    document: 'Document content',
},
```

```python Python Tela SDK theme={null}
variables={
    "document": "Document content",
}
```

```json Corpo HTTP theme={null}
"variables": {
    "document": "Document content"
}
```

## Arquivos

Uma variável de arquivo recebe um objeto com uma `file_url`. A URL pode apontar para três tipos de conteúdo:

| `file_url` | Quando usar |
| - | - |
| `https://…` | O arquivo já está acessível na internet, como um documento no seu próprio storage. |
| `data:<mime type>;base64,…` | O arquivo está em memória e é pequeno o bastante para ir inline. |
| `vault://<id do arquivo>` | Você enviou o arquivo para o Tela antes, com os endpoints de arquivo (veja abaixo). |

```json URL de arquivo theme={null}
"variables": {
    "document": {
        "file_url": "https://www.wmaccess.com/downloads/sample-invoice.pdf"
    }
}
```

```json Base64 theme={null}
"variables": {
    "document": {
        "file_url": "data:application/pdf;base64,JVBERi0xLjUKJeLjz9MKNCAwIG9ia..."
    }
}
```

```json Arquivo enviado theme={null}
"variables": {
    "document": {
        "file_url": "vault://3fa85f64-5717-4562-b3fc-2c963f66afa6"
    }
}
```

Os formatos aceitos (PDF, imagens, áudio, vídeo, documentos Office, CSV e texto simples) estão listados em [Formatos de arquivo suportados](https://docs.tela.com/pt/supported-file-formats.md).

### Com os SDKs

Os SDKs montam o arquivo para você: `tela.createFile` (TypeScript e JavaScript) e `client.create_file` (Python) aceitam uma URL e constroem o objeto `file_url`. `createFile` também aceita um `Buffer`, um `Blob` ou um stream de leitura, e `create_file` aceita um arquivo aberto, então você envia arquivos locais sem codificá-los por conta própria.

```typescript TypeScript Tela SDK theme={null}
import fs from 'node:fs'
import type { TelaFile } from '@meistrari/tela-sdk-js'

const completion = await tela.completions.create<{ document: TelaFile }, { fileSummary: string }>({
    canvasId: process.env.TELA_CANVAS_ID,
    variables: {
        // A URL...
        document: tela.createFile('https://www.wmaccess.com/downloads/sample-invoice.pdf'),
        // ...or a local file
        // document: tela.createFile(fs.createReadStream('./sample-invoice.pdf')),
    },
})
```

```javascript JavaScript Tela SDK theme={null}
import fs from 'node:fs'

const completion = await tela.completions.create({
    canvasId: process.env.TELA_CANVAS_ID,
    variables: {
        // A URL...
        document: tela.createFile('https://www.wmaccess.com/downloads/sample-invoice.pdf'),
        // ...or a local file
        // document: tela.createFile(fs.createReadStream('./sample-invoice.pdf')),
    },
})
```

```python Python Tela SDK theme={null}
# A URL...
completion = client.completions.create(
    canvas_id=TELA_CANVAS_ID,
    variables={
        "document": client.create_file("https://www.wmaccess.com/downloads/sample-invoice.pdf"),
    },
)

# ...or a local file
with open("./sample-invoice.pdf", "rb") as file:
    completion = client.completions.create(
        canvas_id=TELA_CANVAS_ID,
        variables={
            "document": client.create_file(file),
        },
    )
```

### Vários arquivos em uma variável

Uma variável pode receber um array de objetos de arquivo. Você pode misturar arquivos públicos e enviados no mesmo array.

```typescript TypeScript Tela SDK theme={null}
variables: {
    documents: [
        { file_url: 'https://example.com/file1.pdf' },
        { file_url: 'https://example.com/file2.pdf' },
        { file_url: 'vault://550e8400-e29b-41d4-a716-446655440000' },
    ],
},
```

```python Python Tela SDK theme={null}
variables={
    "documents": [
        {"file_url": "https://example.com/file1.pdf"},
        {"file_url": "https://example.com/file2.pdf"},
        {"file_url": "vault://550e8400-e29b-41d4-a716-446655440000"},
    ],
}
```

```json Corpo HTTP theme={null}
"variables": {
    "documents": [
        { "file_url": "https://example.com/file1.pdf" },
        { "file_url": "https://example.com/file2.pdf" },
        { "file_url": "vault://550e8400-e29b-41d4-a716-446655440000" }
    ]
}
```

## Enviando um arquivo antes

Quando um arquivo não é público e é grande demais para ir inline, envie-o para o Tela e referencie-o pelo ID. O envio tem duas etapas com `POST /v3/files`, que exige o header `x-compatibility-date` (veja [Data de compatibilidade](https://docs.tela.com/api-reference/introduction.md#compatibility-date)).

**1. Solicitar uma URL de upload**

Envie o nome do arquivo. A resposta traz o `id` do arquivo e uma `uploadUrl` temporária.

```sh cURL theme={null}
curl -X POST https://api.tela.com/v3/files \
    -H "Authorization: Bearer $TELA_API_KEY" \
    -H 'x-compatibility-date: 2025-07-23' \
    -H 'Content-Type: application/json' \
    -d '{ "fileName": "sample-invoice.pdf" }'
```

```json Resposta theme={null}
{
    "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "uploadUrl": "https://file-upload-temporary.example.com/upload?token=xyz"
}
```

**2. Enviar o conteúdo**

Faça um `PUT` dos bytes para a `uploadUrl`, informando o `Content-Type` do arquivo. A URL expira em pouco tempo, então envie logo em seguida.

```sh cURL theme={null}
curl -X PUT "UPLOAD_URL_FROM_PREVIOUS_STEP" \
    -H 'Content-Type: application/pdf' \
    --data-binary @sample-invoice.pdf
```

**3. Referenciar na completion**

Use `vault://<id>` como `file_url` da variável. O arquivo só pode ser lido dentro do seu Workspace.

```json Corpo HTTP theme={null}
"variables": {
    "document": { "file_url": "vault://3fa85f64-5717-4562-b3fc-2c963f66afa6" }
}
```

`GET /v3/files/{id}` retorna os metadados de um arquivo enviado (`fileName`, `size`, `mimeType`, `createdAt` e uma `url`). O passo a passo completo, com exemplos em TypeScript e Python, está em [Upload a File (v3)](https://docs.tela.com/api-reference/file/upload.md).

> [!NOTE]
>
> O endpoint mais antigo `POST /v2/file` também retorna uma `upload_url` para o `PUT` do arquivo, junto com uma `download_url` que você pode passar como uma `file_url` comum. Veja [Upload a File](https://docs.tela.com/api-reference/file/create.md). Integrações novas devem usar `/v3/files`.

## Onde os arquivos aparecem depois

Toda execução registra as suas entradas. No resultado de uma execução assíncrona e no [histórico de execuções](https://docs.tela.com/pt/completion-api/async-and-webhooks.md#listando-execucoes-anteriores), `input_content.variables` guarda os valores que você enviou e `input_content.files` lista cada arquivo com o seu `name` (o nome da variável), a `url` e `used_at: "variables"`.


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