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

# Integrando com API

Pré-requisitos:

* [Ter um canvas publicado](/pt/publishing)

## Obtenha os dados do seu canvas

Precisamos de duas coisas para começar a usar nosso canvas:

1. Chave de API
2. Canvas ID

Podemos achar os dois no mesmo local.

<Steps>
  <Step title="Abrir opções de Deploy">
    Primeiro clique no botão de implantação no canto superior direito da interface do aplicativo.
    Isso abrirá as opções de implantação.

    <img class="rounded-2xl" src="https://mintcdn.com/meistrari/pblu7JGV78zF0-_0/images/guides/integrating-api/deploy-focus.png?fit=max&auto=format&n=pblu7JGV78zF0-_0&q=85&s=5a5e6d43de646d4c00efb562f0d2f46a" alt="Deploy" width="1300" height="338" data-path="images/guides/integrating-api/deploy-focus.png" />
  </Step>

  <Step title="Abrir modal de conexão com a API">
    Lá você encontrará como implantar aplicativos e como se conectar à API, clique em "Or connect directly via API" na parte inferior do modal.

    <img class="rounded-2xl" src="https://mintcdn.com/meistrari/pblu7JGV78zF0-_0/images/guides/integrating-api/deploy-options-focus.png?fit=max&auto=format&n=pblu7JGV78zF0-_0&q=85&s=ea9ad7886e820cce01907e7e10ec4e53" alt="Deploy" width="1921" height="1525" data-path="images/guides/integrating-api/deploy-options-focus.png" />
  </Step>

  <Step title="Pegue os dados">
    Aqui você encontrará todas as informações necessárias para começar a integrar! Escolha sua linguagem preferida para começar.

    <img class="rounded-2xl" src="https://mintcdn.com/meistrari/pblu7JGV78zF0-_0/images/guides/integrating-api/api-connect-focus.png?fit=max&auto=format&n=pblu7JGV78zF0-_0&q=85&s=2e253c80fb47b991232bb18b187487aa" alt="Deploy" width="2001" height="1794" data-path="images/guides/integrating-api/api-connect-focus.png" />
  </Step>
</Steps>

## Construindo o Corpo da Chamada do Canvas

Para alcançar o comportamento desejado para o seu negócio e integração, sua chamada de canvas pode incluir variáveis, mensagens históricas, streaming e respostas de webhook para integrações assíncronas.
<Tip>Confira a [Referência da API](/api-reference/completion/create) para mais detalhes sobre nosso SDK e especificações da API.</Tip>

### Usando Variáveis

Variáveis são um conceito chave na construção de prompts com o Tela. Elas são usadas para armazenar e reutilizar dados ao longo dos seus prompts e podem ser uma entrada manual ou um arquivo.

<Note>Para informações sobre formato de arquivos suportados, visite [Formato suportados](/en/supported-file-formats).</Note>

Quando definimos variáveis em nosso prompt, o modal de conexão gerará os trechos de código para nós já preenchidos com as chaves das variáveis.

<img class="rounded-2xl" src="https://mintcdn.com/meistrari/pblu7JGV78zF0-_0/images/guides/integrating-api/variables-focus.png?fit=max&auto=format&n=pblu7JGV78zF0-_0&q=85&s=ece9ca7c2dc4794b77b2ce86f59ac56f" alt="Deploy" width="2001" height="1058" data-path="images/guides/integrating-api/variables-focus.png" />

Preencha as chaves com os valores que você deseja, pode ser um texto, uma URL de arquivo ou uma string base64 de arquivo.

<CodeGroup>
  ```typescript Typescript Tela SDK theme={null}
  variables: {
      document: tela.createFile('https://www.wmaccess.com/downloads/sample-invoice.pdf'), // It is possible to pass a URL, Buffer, Blob, etc.
  },
  ```

  ```python Python Tela SDK theme={null}
  variables={
      "document": client.create_file("https://www.wmaccess.com/downloads/sample-invoice.pdf"),
  }
  ```

  ```typescript File Url theme={null}
  variables: {
      document: {
          file_url: 'https://www.wmaccess.com/downloads/sample-invoice.pdf',
      }
  }
  ```

  ```typescript Base 64 theme={null}
  variables: {
      document: {
          file_url: 'data:application/pdf;base64,JVBERi0xLjUKJeLjz9MKNCAwIG9ia...',
      }
  }
  ```

  ```typescript Text theme={null}
  variables: {
      document: "Document Content!"
  }
  ```
</CodeGroup>

<Tip>[Confira](/api-reference/completion/create#files) os detalhes de uso de arquivos com nosso SDK</Tip>

### Usando Mensagens

A API do Tela permite que você inclua mensagens em suas requisições, estendendo o corpo da requisição com a chave `messages`.
Esse recurso permite que você forneça contexto ou informações adicionais ao modelo, melhorando a interação e a qualidade da saída.

<CodeGroup>
  ```typescript Typescript Tela SDK theme={null}
  const completion = await tela.completions.create<{ document: TelaFile }, { fileSummary: string }>({
      canvasId: process.env.TELA_CANVAS_ID,
      variables: {
          document: tela.createFile('https://www.wmaccess.com/downloads/sample-invoice.pdf')
      },
      messages: [
          {
              role: 'user',
              content: {
                  type: 'text',
                  text: 'Hello, how can I assist you today?'
              }
          },
          {
              role: 'assistant',
              content: {
                  type: 'image_url',
                  image_url: {
                      url: 'https://example.com/image.png',
                      detail: 'high'
                  }
              }
          }
      ]
  })
  ```

  ```typescript Javascript Tela SDK theme={null}
  const completion = await tela.completions.create({
      ...,
      messages: [
          {
              role: 'user',
              content: {
                  type: 'text',
                  text: 'Hello, how can I assist you today?'
              }
          },
          {
              role: 'assistant',
              content: {
                  type: 'image_url',
                  image_url: {
                      url: 'https://example.com/image.png',
                      detail: 'high'
                  }
              }
          }
      ]
  })
  ```

  ```python Python Tela SDK theme={null}
  completion = client.completions.create(
      ...,
      messages=[
          {
              "role": "user",
              "content": {
                  "type": "text",
                  "text": "Hello, how can I assist you today?"
              }
          },
          {
              "role": "assistant",
              "content": {
                  "type": "image_url",
                  "image_url": {
                      "url": "https://example.com/image.png",
                      "detail": "high"
                  }
              }
          }
      ]
  )
  ```

  ```sh Curl theme={null}
  curl -XPOST https://api.tela.com/v2/chat/completions \
      -H 'Content-Type: application/json' \
      -H 'Authorization: Bearer API-KEY' \
      -d '{
          ...,
          "messages": [
              {
                  "role": "user",
                  "content": {
                      "type": "text",
                      "text": "Hello, how can I assist you today?"
                  }
              },
              {
                  "role": "assistant",
                  "content": {
                      "type": "image_url",
                      "image_url": {
                          "url": "https://example.com/image.png",
                          "detail": "high"
                      }
                  }
              }
          ],
      }'
  ```
</CodeGroup>

<Tip>A sequência de mensagens no array é crucial, pois representa o fluxo cronológico da conversa. Cada ciclo começa com a mensagem de um usuário e é seguido pela resposta do assistente, mantendo o contexto e a coerência do diálogo.</Tip>

<Tip>Confira a [Referência da API](/api-reference/completion/create) para mais detalhes sobre o esquema do campo mensagens.</Tip>

### Streaming

Para habilitar o streaming na chamada do canvas, basta incluir a chave `stream` definida como `true` no corpo da requisição.

<CodeGroup>
  ```typescript Typescript Tela SDK theme={null}
  const completion = await tela.completions.create<{ document: TelaFile }, { fileSummary: string }>({
      canvasId: process.env.TELA_CANVAS_ID,
      variables: {
          document: tela.createFile('https://www.wmaccess.com/downloads/sample-invoice.pdf')
      },
      stream: true
  })
  ```

  ```typescript Javascript Tela SDK theme={null}
  const completion = await tela.completions.create({
      canvasId: process.env.TELA_CANVAS_ID,
      variables: {
          document: tela.createFile('https://www.wmaccess.com/downloads/sample-invoice.pdf')
      },
      stream: true
  })
  ```

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

  ```sh Curl theme={null}
  curl -XPOST https://api.tela.com/v2/chat/completions \
      -H 'Content-Type: application/json' \
      -H 'Authorization: Bearer API-KEY' \
      -d '{
          "canvas_id": "95cec438-6080-44fe-8275-28b16bd40178",
          "variables": {
              "document": "data:application/pdf;base64,JVBERi0xLjUKJeLjz9MKNCAwIG9ia..."
          },
          "stream": true
      }'
  ```
</CodeGroup>

<Tip>Veja a [Referência da API de Streaming](/api-reference/completion/create#streaming) para mais detalhes sobre o consumo do stream.</Tip>

### Async

Para alcançar um comportamento assíncrono, você tem duas opções:

* Usando a flag `async`
* Usando um webhook

#### Usando a Flag Async

Para usar a flag `async`, basta incluí-la no corpo da requisição e defini-la como `true`. Isso fará com que a execução seja assíncrona, permitindo que você continue com outras tarefas enquanto aguarda a conclusão. Um `id` sera retornado para que você possa monitorar o status da chamada.

<CodeGroup>
  ```sh Curl theme={null}
  curl -XPOST https://api.tela.com/v2/chat/completions \
      -H 'Content-Type: application/json' \
      -H 'Authorization: Bearer API-KEY' \
      -d '{
          ...,
          "async": true
      }'
  ```
</CodeGroup>

<Tip>Veja a [Referência da API de Obtenção de Completion Assíncrona](/api-reference/completion/get) para mais detalhes de como consumir a completion com o `id` recebido</Tip>

#### Usando Webhook

Você pode passar uma URL de webhook para nossa API, estendendo o corpo com uma chave `webhook_url`, isso tornará a chamada assíncrona, e você receberá a resposta quando a completion for finalizada com uma requisição POST na URL fornecida.

<CodeGroup>
  ```typescript Typescript Tela SDK theme={null}
  const completion = await tela.completions.create<{ document: TelaFile }, { fileSummary: string }>({
      canvasId: process.env.TELA_CANVAS_ID,
      variables: {
          document: tela.createFile('https://www.wmaccess.com/downloads/sample-invoice.pdf')
      },
      webhook_url: "https://example.com/webhook"
  })
  ```

  ```typescript Javascript Tela SDK theme={null}
  const completion = await tela.completions.create({
      ...,
      webhook_url: "https://example.com/webhook"
  })
  ```

  ```python Python Tela SDK theme={null}
  completion = client.completions.create(
      ...,
      webhook_url="https://example.com/webhook"
  )
  ```

  ```sh Curl theme={null}
  curl -XPOST https://api.tela.com/v2/chat/completions \
      -H 'Content-Type: application/json' \
      -H 'Authorization: Bearer API-KEY' \
      -d '{
          ...,
          "webhook_url": "https://example.com/webhook"
      }'
  ```
</CodeGroup>

<Note>Quando a chave `webhook_url` é usada, a chamada se torna assíncrona automaticamente, eliminando a necessidade de incluir a flag `async`.</Note>

# Estrutura do Payload do Webhook

Quando sua completion é finalizada, o Tela enviará uma requisição POST para sua URL de webhook com a seguinte estrutura:

**Headers:**

* `x-completion-run-id`: O identificador único da execução da completion
* `Content-Type`: `application/json`

**Body:**
O payload do webhook contém o resultado bruto da completion:

```
{
    "usage": {
        "total_tokens": <number>,
        "prompt_tokens": <number>,
        "completion_tokens": <number>
    },
    "object": "chat.completion",
    "choices": [
        {
            "message": {
                "role": "assistant",
                "content": <... conteúdo da sua completion>
            }
        }
    ],
    "created": <timestamp>
}
```

<Note>
  Você pode usar o header `x-completion-run-id` para correlacionar a
  resposta do webhook com sua requisição original e acompanhar o status da completion em sua
  aplicação.
</Note>