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

# Integrações de API

> Utilize integrações de API para expandir as funcionalidades do seu agente com seus sistemas externos de forma facilitada.

## Configurar Integração de API

Esta configuração permite ao seu agente executar uma função em uma API externa e aguardar por uma resposta ou a obter dados de uma API externa.

## Parâmetros

### Geral

* **Nome da Integração**: Um nome de identificação interno para sua integração dentro da listagem do agente.
* **Descrição**: Esta é a área de instruções que deve ser fornecida como uma descrição detalhada explicando quando o agente de I.A deve usar essa ação e API. Recomenda-se incluir exemplos dos dados que essa ação fornece e das consultas dos clientes que ela ajuda a responder. Ex.: Utilizar quando o usuário pedir por informações do seu cadastro.
* **Endpoint / URL**: O endpoint e URL na qual o agente deve encaminhar a chamada de API do seu serviço. Recomenda-se criar uma ação de API por endpoint caso você necessite chamar diversos no mesmo URL / API.
* **Método**: O método HTTP a ser utilizado na chamada deste endpoint.

### Headers

* Estes são os headers a serem enviados durante a requisição da sua API. Aqui você deve definir parâmetros importantes como o Content-Type, o Accept e também a Autenticação e Autorização da sua API caso possua. Cada campo de Header deve possuir dois parâmetros:
  * **Nome**: A chave / nome do campo Header que será anexado.
  * **Valor**: O valor da chave que será enviado.

### Body / Corpo da Requisição

* É aqui que você define quais parâmetros serão enviados no Body / Corpo da requisição (ou nos Query Params no caso de requisições GET). Você deve apenas informar o nome do campo a ser enviado e o tipo do campo. O robô se encarrega de obter os dados no contexto da conversa caso possua ou perguntará ao usuário sobre o dado necessário caso não possua acesso a informação ainda. Cada campo a ser enviado é composto por dois parâmetros de configuração:
  * **Nome**: A chave / nome do campo que será anexado ao corpo da requisição.
  * **Tipo**: O tipo do valor a ser obtido / enviado, podendo ser Booleano (Verdadeiro / Falso), Texto ou Número.

Você deve clicar em **Criar** somente após configurar todos os parâmetros descritos acima, sendo os **Headers** opcionais.

### Teste das Respostas da API e Dicas

* Resposta ao vivo: teste com dados ao vivo e reais da sua API para garantir que ela esteja configurada corretamente e retornando os dados conforme esperado.
* Utilize o Playground para testar sua API após configura-la.
* Resposta de exemplo: use dados JSON de exemplo se a API não estiver pronta ou em modo de testes, o mais próximo do real possível.
* Publique apenas após garantir que sua API esta funcionando conforme o esperado.

## Casos de Uso

### Atualizar Assinatura

Neste exemplo, usamos uma chamada de API de Upgrade de Assinatura para permitir que o usuário solicite ao agente de I.A o upgrade de sua assinatura para o plano Premium.

Na seção Geral, adicionamos Atualizar\_Assinatura como o nome da ação. Fornecemos as informações de “Quando usar” para que o agente de I.A use essa API sempre que o usuário quiser fazer o upgrade da assinatura.

Na seção de Header, adicionamos apenas um exemplo de Autorização / Autenticação para nossa API externa, utilizando um Token Fixo fictício.

Na seção de Body / Corpo, adicionamos os dados necessários para a atualização da assinatura. Adicionamos o status do plano e o novo plano solicitado, além do tipo de dado a ser enviado conforme descrevemos anteriormente ao agente.

Agora, estamos prontos para solicitar ao agente de I.A que atualize ou reduza a assinatura quando o usuário perguntar sobre isso na área de Playground!

### API de Clima

Neste exemplo, usamos uma API "Obter Clima" para fornecer as informações meteorológicas das cidades solicitadas pelo usuário ao agente de I.A.

Na seção Geral, adicionamos Obter\_Clima como nome da ação de API. Fornecemos as informações sobre "Quando Usar" na descrição para que o agente de I.A use essa API sempre que for questionado sobre o clima de qualquer cidade. Selecionamos aqui o método "GET" para buscar dados.

Na seção de Headers, mantemos o mesmo do exemplo anterior, apenas Autenticação.

Na seção de Corpo, adicionamos os dados usados para recuperar as informações meteorológicas. Adicionamos o nome da entrada como Cidade (city), o tipo da entrada é Texto e a descrição da entrada foi dada anteriormente ao agente na descrição geral.

Agora, estamos prontos para perguntar ao agente de I.A sobre o clima de qualquer cidade que o usuário solicitar na área Playground.