# Integração com APIs de terceiros
Você pode criar bots que interagem com outros serviços via APIs. Por exemplo, bots podem fazer solicitações para verificar a disponibilidade para uma data específica ou encontrar um produto em uma loja online.
## Como interagir com APIs de terceiros usando a Dadata como exemplo
Vamos usar uma API de sugestão de endereço como exemplo: **o link será diferente**
{% hint style="info" %}
Leia a documentação das APIs de terceiros com atenção.
{% endhint %}
{% hint style="warning" %}
Atenção! As APIs de terceiros exigem os endereços IP a partir dos quais as solicitações serão enviadas: 158.160.49.208 – site.
{% endhint %}
No campo "Request URL", insira `https://suggestions.dadata.ru/suggestions/api/4_1/rs/suggest/address`.
Na **campo "Request header"** insira o cabeçalho em formato JSON: `{"Content-Type": "application/json", "Accept": "application/json", "Authorization": "Token " + token}`.
Na **campo "JSON parameters"** insira a própria solicitação: `{"query": "#{CurrencyType}"}`.
Para obter o resultado da solicitação, preencha o **"Saved values"** .
Um exemplo da solicitação é mostrado na ilustração abaixo.
### Como salvar valores de variáveis
Pode não ficar totalmente claro na primeira vez — você realmente precisa tentar por conta própria.
Primeiro, insira #{custom\_answer} no campo "Answer". (A variável #{custom\_answer} contém a resposta recebida do servidor especificado no campo "Response URL".)
Execute o bloco de solicitação para enviar a solicitação e obter a resposta. A resposta recebida precisa ser analisada, e você precisa configurar quais variáveis serão extraídas dela. Para isso, use o campo "Saved Values".
Vamos analisar o exemplo descrito acima.
A melhor maneira de entender como acessar dados em JSON é por meio de um exemplo. Como resultado da nossa solicitação, a resposta recebida em #{custom\_answer} fica assim:
`{
"suggestions": [
{
"value": "US Dollar",
"unrestricted_value": "US Dollar",
"data": {
"code": "840",
"strcode": "USD",
"name": "US Dollar",
"country": "United States"
}
}
]
}`
No campo "Saved values", insira VALUE -> VARIABLE:
`suggestions|0|value->CurrencyType;` \
`suggestions|0|data|code->CurrencyDigCode;` \
`suggestions|0|data|strcode->CurrencyStrCode;` \
`suggestions|0|data|country->CurrencyCountry`
**suggestions -** chave para o array \[{"value": "US Dollar", "unrestricted\_value": "US Dollar", "data": {"code": "840", "strcode": "USD", "name": "US Dollar", "country": "United States"}}]
**sugestões|0** - chave para o primeiro elemento do array {"value": "US Dollar", "unrestricted\_value": "US Dollar", "data": {"code": "840", "strcode": "USD", "name": "US Dollar", "country": "United States"}}
**sugestões|0|value** - chave para o valor "US Dollar"
A chave mais longa neste JSON:
**sugestões|0|data|strcode** - chave para o valor "USD"
{% hint style="success" %}
As chaves são separadas por uma barra vertical (|). Se um elemento JSON for um array, você acessa seus itens por índice, começando de 0, e isso também é escrito usando uma barra vertical.
{% endhint %}
{% hint style="info" %}
Você precisa repetir todo o aninhamento. Para conveniência, você pode visualizar o JSON usando um aplicativo visualizador de JSON.
{% endhint %}
O nível de aninhamento é separado por uma barra vertical. Ou seja, você precisa listar todas as chaves para chegar ao valor, separando-as com uma barra vertical.
{% hint style="info" %}
Se o JSON contiver um array, use o índice do elemento em vez de uma chave, começando por zero.
{% endhint %}
Separe as expressões para obter nossas variáveis com ponto e vírgula ;.
Cada expressão consiste no caminho para os dados na resposta e no nome da variável para salvá-la, separados por ->.
A consulta de pesquisa representa o caminho no JSON até o valor necessário.
### Desenvolvimento de API para bots
O bot suporta solicitações GET e POST, que são os principais tipos usados na maioria das APIs públicas.
**GET** é uma solicitação que acontece quando você clica em um link ou abre uma URL no navegador. Os parâmetros dessa solicitação são passados na URL.
Sintaxe para passar parâmetros: após a URL, coloque um ponto de interrogação ?, depois separe cada parâmetro com um E comercial &. Cada parâmetro consiste em um nome seguido de = e seu valor.
Exemplo de uma URL com um parâmetro:
Aqui, um único parâmetro q é passado com o valor "good music". %20 representa um espaço.
Ao trabalhar com o construtor, você pode simplesmente usar um espaço — o bot o substituirá automaticamente.
**POST** é uma solicitação mais frequentemente enviada ao submeter um formulário em um site. Os parâmetros são enviados no corpo da solicitação. Embora também possam ser enviados na URL como nas solicitações GET, isso é incomum. Os parâmetros no corpo podem estar em formato JSON ou como pares chave-valor. Formulários geralmente enviam pares chave-valor, enquanto APIs costumam usar JSON.
**Cabeçalho da solicitação** - você pode adicionar um cabeçalho a cada solicitação. Na maioria das vezes, ele especifica o formato dos dados e as chaves de acesso. Normalmente, esse campo é deixado em branco, mas, em casos raros, você precisa incluir um token de API ou um tipo de solicitação, por exemplo, "Content-Type": "application/json".
**JSON** (JavaScript Object Notation, geralmente pronunciado /ˈdʒeɪsən/ JAY-sən) é um formato de troca de dados baseado em texto, baseado em JavaScript. Como muitos outros formatos de texto, o JSON é fácil para os humanos lerem. Para trabalhar com APIs no bot, você precisa entender esse formato, pois ele está na base de todas as interações.
Antes de continuar, leia os seguintes artigos:
\
Além disso, tente criar seu próprio arquivo JSON neste site:
**Prática**
As solicitações podem ser executadas por blocos e condições. As solicitações condicionais são projetadas para verificar se um diálogo pode seguir um determinado ramo no site. Nesse caso, a solicitação é enviada toda vez que a condição do ramo é avaliada. Já as solicitações em blocos são executadas apenas quando o diálogo entra naquele estado.
Antes de criar uma solicitação, você precisa escolher seu tipo:
POST-data e POST-JSON diferem na forma como os parâmetros são enviados, como mencionado anteriormente (seja em formato JSON ou como pares chave-valor). Se você escolher JSON, os parâmetros só poderão ser enviados no corpo da solicitação. Um campo adicional aparecerá para os parâmetros JSON de POST.
**Importante!** Os parâmetros devem ser escritos apenas em formato JSON, pois o bot trabalha exclusivamente com ele. Você já praticou a escrita de JSON.
A resposta do servidor pode ser analisada e salva em variáveis.
{% hint style="info" %}
Você só pode analisar uma resposta se ela estiver em formato JSON.
{% endhint %}
As variáveis salvas são registradas no último formulário não preenchido. Se o formulário for enviado por um bloco vermelho, as variáveis são descartadas. Portanto, se você precisar salvar esses dados, passe as variáveis para o sistema de CRM por meio de um bloco amarelo.
Você também pode ver o que o bot registrou nas variáveis na seção "Leads".
### Passar variáveis não como uma string
Por padrão, os valores das variáveis devem ser strings no formato "#{}", mas, neste caso, a variável é enviada como uma string. Para passar uma variável como número, você precisa desativar a verificação do formato dos parâmetros nas configurações do projeto:
Depois, você pode simplesmente usar o nome da variável, por exemplo: `{"key": #{variable_name}}`onde variable\_name é a própria variável — sem aspas ao redor.
{% hint style="warning" %}
É recomendável ativar novamente a verificação do formato após definir os parâmetros.
{% endhint %}
---
# Agent Instructions: Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter:
```
GET https://docs.mavibot.ai/doc/pt/trabalhando-com-a-api/integracao-com-apis-de-terceiros.md?ask=
```
The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.