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

# Execução de Código

> Transforme dados entre etapas com uma função pequena execute(input), com bibliotecas e credenciais

**Execução de Código** roda um trecho de JavaScript (ou TypeScript) sobre os dados da execução. É a etapa para tudo o que não se deve pedir a um modelo: aritmética, formatação, juntar os resultados de um Mapear, chamar um sistema externo, decidir algo determinístico.

Você não precisa ser desenvolvedor para usá-la em coisas simples, e o editor tem um **Assistente de Código IA** (`⌘ L` no macOS, `Ctrl L` nos demais) que escreve ou altera o código a partir de uma descrição. Esta página explica o que o código recebe e o que ele deve devolver, para que você consiga ler e conferir o que o assistente produz.

No exemplo desta seção, **Normalize Values** fica depois de Extract Data e transforma o número extraído em um valor formatado, monta um código de aprovação e marca os contratos acima do limite.

![Etapa de Execução de Código com o editor, as bibliotecas disponíveis e o Terminal](https://mintcdn.com/meistrari/M2w7BduKZAFA1Sbx/images/pt/workflow/code-execution.png?fit=max\&auto=format\&n=M2w7BduKZAFA1Sbx\&q=85\&s=1391fb48da0f15cf7a3e71fe89dc8706)

## A função execute

O código precisa declarar uma função chamada `execute` que recebe `input` e devolve a saída da etapa. A etapa é criada com este modelo:

```typescript theme={null}
/**
 * Required main execution function that processes the workflow state data.
 */
async function execute(input: TelaInput) {
    return 'Tela'
}
```

O que `execute` devolver vira a saída da etapa: um texto, um número, um objeto ou uma lista. Devolva um **objeto com campos nomeados** quando as etapas seguintes precisarem escolher valores dele; esses campos aparecem no menu `@` das próximas etapas.

```javascript theme={null}
// Normalize the values extracted by Extract Data for the routing and the letter.
async function execute(input) {
  const data = input["Extract Data"]
  const total = Number(data.total_value) || 0

  return {
    total_value: total,
    total_formatted: total.toLocaleString("en-US", { style: "currency", currency: "USD" }),
    is_high_value: total > 100000,
    approval_code: `CT-${new Date().getFullYear()}-${String(data.counterparty).slice(0, 3).toUpperCase()}`,
  }
}
```

Comece o código com um comentário curto dizendo o que a etapa faz, quais entradas usa e o que devolve. Quem abrir o Workflow depois, incluindo o assistente de IA, lê isso antes do código.

Se a função não existir ou tiver outro nome, a etapa falha com a mensagem: *The `execute(input)` function was not found in the code and is required.*

## O que chega em input

`input` é um objeto com uma chave por Entrada do Workflow e uma chave por etapa que rodou antes desta, **usando os nomes exatamente como escritos no editor**:

| Chave | Valor |
| - | - |
| `input["contract"]` (uma Entrada de arquivo) | um objeto com `files`, uma lista dos arquivos enviados: `{ name, mimeType, fileUrl, vaultReference }` |
| `input["requester"]` (uma Entrada de texto) | o texto |
| `input["Extract Data"]` (um Módulo de IA com Formato de Saída) | o objeto com os atributos: `input["Extract Data"].total_value` |
| `input["Draft Note"]` (um Módulo de IA sem Formato de Saída) | o texto |
| `input["Route by value"]` (uma Condição) | o nome da condição que bateu, ou `"Default"` |
| `input["Split contract"]` (um Dividir ou Recortar) | a lista de pedaços, cada um com `file`, `originalFile`, `pages`... |
| `input["Extract Page"]` (uma etapa dentro de um Mapear que já terminou) | uma lista, uma entrada por iteração |
| `input["page"]` (dentro de um Mapear, a Variável de Map) | o item atual |

Nomes com espaço precisam da forma com colchetes, `input["Extract Data"]`; nomes sem espaço podem usar `input.requester`. O editor conhece a forma do que cada etapa anterior devolve e oferece autocompletar enquanto você digita, então `input["Extract Data"].` lista os atributos do Formato de Saída dela.

> [!TIP]
>
> Adicione um `console.log(JSON.stringify(input, null, 2))` na primeira execução. O **Terminal** abaixo do editor mostra tudo o que o código escreve em stdout e stderr, com o código de saída, então você vê a estrutura real dos dados antes de escrever a lógica.

## Devolvendo valores

* Devolva um **objeto** para expor campos nomeados: `{ total_value, is_high_value }`. Cada campo fica selecionável pelas etapas seguintes e por uma Condição.
* Devolva uma **lista** para alimentar um Mapear.
* Devolva um **texto** ou **número** para um valor único.
* Não devolver nada (`undefined`) produz uma saída vazia; a etapa ainda assim é concluída com sucesso.
* Lance um erro (`throw new Error("Missing total")`) para fazer a etapa falhar de propósito. A execução falha naquela etapa e a mensagem aparece no painel de resultado e em Depurar.

Uma etapa de Execução de Código não tem Formato de Saída para preencher: os campos do objeto que você devolve são o formato de saída dela. O editor os infere a partir do código para que as próximas etapas possam oferecê-los no menu `@`.

## Trabalhando com arquivos

Valores de arquivo chegam como metadados, não como bytes. Para ler o conteúdo de um arquivo, use as bibliotecas disponíveis na etapa:

* `@meistrari/document-sdk` para processar documentos;
* `@meistrari/vault-sdk` para ler e gravar arquivos no Vault;
* `@meistrari/tela-sdk-js` para chamar a API do Tela (por exemplo executar um Canvas) a partir do código.

Essas três vêm instaladas por padrão e aparecem em **Bibliotecas Disponíveis**. Para adicionar outro pacote (por exemplo `xlsx` para ler uma planilha ou `pdf-lib` para montar um PDF), digite o nome em **Adicione uma biblioteca** e clique em **Instalar**. A instalação leva alguns segundos e o pacote passa a estar disponível com `import` ou `require`.

> [!NOTE]
>
> Como produzir um arquivo como saída de uma etapa de Execução de Código (por exemplo enviar uma planilha gerada ao Vault e devolver a referência dela) depende do SDK do Vault e não está documentado aqui. Para gerar documentos a partir de um template, use o [Document Templater](https://docs.tela.com/pt/workflow/reusing-canvases-agents-and-templates.md#document-templater).

## Usando credenciais

Nunca cole uma chave de API no código. Guarde-a como uma [Credencial](https://docs.tela.com/pt/credentials.md) e leia em tempo de execução:

```javascript theme={null}
async function execute(input) {
  const token = credential("CRM_API_TOKEN")
  const response = await fetch("https://crm.example.com/api/contracts", {
    method: "POST",
    headers: { Authorization: `Bearer ${token}`, "Content-Type": "application/json" },
    body: JSON.stringify({
      counterparty: input["Extract Data"].counterparty,
      total: input["Normalize Values"].total_value,
    }),
  })
  if (!response.ok) throw new Error(`CRM answered ${response.status}`)
  return await response.json()
}
```

`credential("NOME")` devolve o valor de uma credencial do Workspace ou com escopo do Workflow. Uma credencial ausente faz a etapa falhar com `missing_credential`. Os valores são omitidos dos logs, mas qualquer coisa que você imprimir com `console.log` de propósito ainda pode aparecer, então não os imprima. Administradores podem restringir quais credenciais um Workflow pode usar pelo botão **Credenciais** no cabeçalho; veja [Credenciais](https://docs.tela.com/pt/credentials.md#allowlist-de-credentials).

## Limites

| Limite | Valor |
| - | - |
| Linguagem | JavaScript ou TypeScript (o TypeScript é transpilado antes de rodar) |
| Tempo | até 80 minutos por execução, por padrão |
| Memória | 128 MB |
| Rede | chamadas HTTPS de saída para endereços públicos são permitidas; endereços privados, locais e link-local são bloqueados |
| Processos | o código não pode iniciar outros programas |
| Resultado | o que `execute` devolver, serializado como JSON |

Uma etapa de Execução de Código nunca usa cache: ela roda em toda execução do Workflow. Uma execução que fica 3 horas sem progresso é marcada como tempo esgotado, então mantenha esperas longas fora do código; uma espera de horas pertence a uma agenda, não a uma etapa.

## Depurando

Depois de uma execução, a seção da etapa no painel de resultado mostra o valor devolvido, e **Depurar** acrescenta o **Terminal** (stdout, stderr e código de saída) e a mensagem de erro quando o código lançou uma exceção. Quando uma etapa de Execução de Código falha, corrija o código e use **Executar Etapa N** nela para rodar de novo do início até aquela etapa sem mexer nas seguintes. Veja [Executando, testando e publicando](https://docs.tela.com/pt/workflow/running-testing-and-publishing.md#executando-apenas-uma-etapa).

> [!NOTE]
>
> Para desenvolvedores: a etapa aceita `code`, `language` (`javascript` por padrão; `typescript` é aceito) e `libraries` (especificadores de pacotes npm). O sandbox expõe o estado da execução como globais, então `input` é montado a partir das Entradas (texto reduzido ao conteúdo, arquivos como `{ files: [...] }`) e das saídas das etapas anteriores, cujas chaves são o **nome da etapa**. Referências `{{step://…}}` não são expandidas dentro do código.


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