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

# Blocos de integração

> Use os blocos Integração HTTP e Google Sheets para consultar sistemas externos e registrar dados em planilhas durante o fluxo

![Fluxo Status do pedido com um bloco Integração HTTP que consulta o pedido e um bloco Google Sheets que registra o atendimento](https://mintcdn.com/wizebot-d8529edc/npLQJVV8gD5vOhne/images/fluxo-blocos-integracoes/capa.png?fit=max\&auto=format\&n=npLQJVV8gD5vOhne\&q=85\&s=1658d98da7788428d0731be95c5b4de9)

Os blocos da categoria **Integrações** ligam o fluxo a sistemas de fora da WizeBot. Com eles o fluxo busca informações no sistema da sua loja, por exemplo o status de um pedido, e grava dados de atendimento numa planilha do Google.

| Bloco | O que faz | Saídas |
| - | - | - |
| **Integração HTTP** | Chama a API de outro sistema e usa a resposta nos blocos seguintes | **Próximo passo** e **Falha** |
| **Google Sheets** | Lê, adiciona, atualiza ou verifica linhas de uma planilha | **Próximo passo** |

Os exemplos desta página usam um fluxo de loja: o cliente manda "pedido", o fluxo consulta o pedido no sistema da loja, responde com o status e anota a consulta numa planilha. Para montar o fluxo do zero, veja [Criar e ativar um fluxo](https://help.wizebot.com.br/tutoriais/gerenciador-bots/fluxo.md).

## Adicionar um bloco de integração

No editor do fluxo, clique no botão **+** no canto superior direito. Role a lista até a seção **Integrações** e escolha **Google Sheets** ou **Integração HTTP**. O bloco entra no fluxo e você liga a saída do bloco anterior a ele.

![Menu de blocos aberto na seção Integrações com Google Sheets e Integração HTTP numerados](https://mintcdn.com/wizebot-d8529edc/npLQJVV8gD5vOhne/images/fluxo-blocos-integracoes/01-menu-integracoes.png?fit=max\&auto=format\&n=npLQJVV8gD5vOhne\&q=85\&s=f693d36cbbcd74e802beca0d0aa7566f)

Para configurar um bloco, clique nele no fluxo. O painel de configuração abre à esquerda.

## Integração HTTP

O bloco **Integração HTTP** faz uma chamada à API de outro sistema: o da sua loja virtual, do seu ERP ou de uma plataforma de pagamento. A chamada pode levar dados do contato, como o telefone, e a resposta pode ser usada nas mensagens seguintes ou gravada nos campos do contato.

Antes de usar o bloco, você precisa do endereço da API e, se ela pedir, da chave de acesso. Essas informações vêm do sistema que você quer consultar, normalmente na área de desenvolvedor ou de integrações dele.

### Configurar o bloco

**1. Escolha ou crie a integração**

No painel do bloco, abra a lista **Integração HTTP** e escolha uma integração que já existe. Para criar uma nova, clique em **Nova**.

A mesma integração pode ser usada em vários fluxos. As integrações também ficam em **Configurações** > **Integrações HTTP**.

![Painel do bloco Consultar pedido com a lista de integrações, Guardar a resposta, Esta chamada é obrigatória e a saída Falha do bloco numerados](https://mintcdn.com/wizebot-d8529edc/npLQJVV8gD5vOhne/images/fluxo-blocos-integracoes/02-painel-http.png?fit=max\&auto=format\&n=npLQJVV8gD5vOhne\&q=85\&s=2488be6b2be4ddae9ddb356923b5ca2e)

**2. Guarde a resposta para usar depois**

Ligue **Guardar a resposta** e preencha **Nome para essa resposta**, por exemplo `pedido`. O nome aceita letras, números e sublinhado.

Nos blocos seguintes, use esse nome entre chaves duplas para ler a resposta. Se a API devolver `{"numero": "10482", "status": "Saiu para entrega"}`, a mensagem `Seu pedido {{pedido.numero}} está: {{pedido.status}}` chega ao cliente como "Seu pedido 10482 está: Saiu para entrega". Para ler um item de uma lista, use a posição: `{{pedido.itens[0].nome}}`.

**3. Decida se a chamada é obrigatória**

Com **Esta chamada é obrigatória** desligado, uma falha não impede o fluxo de continuar. Ligue quando os próximos blocos não fazem sentido sem a resposta, por exemplo quando o fluxo vai mandar um código Pix que vem da API.

Com a opção ligada, o fluxo também para quando a chamada responde com sucesso mas não devolve algum campo mapeado na aba **Resposta**. O contato não recebe mensagem de erro.

**4. Ligue a saída Falha**

Ligue a saída **Falha** do bloco ao que deve acontecer quando a chamada não funcionar, por exemplo uma mensagem dizendo que uma pessoa da equipe vai continuar o atendimento. Evite mensagens que falem em erro ou problema técnico: para o cliente, basta saber quem vai ajudar. Veja abaixo como o bloco decide o caminho.

### Criar a integração

Ao clicar em **Nova** (ou em **Clique para editar**, numa integração já escolhida), abre a janela **Criar Integração HTTP** ou **Editar Integração HTTP**, com as abas **Básico**, **Headers**, **Body**, **Auth**, **Resposta** e **Avançado**.

**1. Preencha a aba Básico**

1. **Nome**: como a integração vai aparecer na lista, por exemplo "Consultar status do pedido".
2. **Método HTTP**: `GET`, `POST`, `PUT`, `DELETE` ou `PATCH`, conforme a documentação da API.
3. **URL da Requisição**: o endereço que será chamado. Para incluir dados do contato, use variáveis, como `{{contact.phone}}`. O ícone **{ }** mostra as variáveis disponíveis.

Em **Contato para Teste**, escolha um contato para preencher as variáveis no teste. Depois clique em **Testar** para fazer uma chamada de verdade e ver a resposta.

![Janela Editar Integração HTTP na aba Básico com Nome, URL da Requisição e o botão Testar numerados e o resultado Teste realizado com sucesso](https://mintcdn.com/wizebot-d8529edc/npLQJVV8gD5vOhne/images/fluxo-blocos-integracoes/03-integracao-basico.png?fit=max\&auto=format\&n=npLQJVV8gD5vOhne\&q=85\&s=5e6e00d763d5d373bd63f610872407bf)

**2. Configure o acesso, se a API pedir**

* **Headers**: cabeçalhos extras que a API exige.
* **Body**: o conteúdo enviado em chamadas `POST`, `PUT` e `PATCH`. Também aceita variáveis.
* **Auth**: em **Tipo de Autenticação**, escolha **Nenhuma**, **Bearer Token**, **Basic Auth** (usuário e senha) ou **API Key** (chave e **Nome do Header**).

**3. Mapeie a resposta para campos do contato**

Na aba **Resposta**, clique em **Novo campo para mapear**. À esquerda, escolha o dado da resposta; à direita, o campo personalizado do contato que vai recebê-lo. A lista de dados da resposta aparece depois de um teste com sucesso. Sem teste, digite o caminho, como `$.data.valor`.

Cada linha tem opções extras no ícone de ajustes: **Origem do valor** (**Da resposta da API** ou **Valor fixo**) e **Formato** (**Data**, **Número**, **Moeda (R\$)**, **MAIÚSCULAS**, **minúsculas** ou **Remover espaços**).

O valor fica salvo no contato. Você pode usar o campo em mensagens, condições e filtros, mesmo depois que o fluxo terminar.

![Aba Resposta com o botão Novo campo para mapear e dois mapeamentos, \$.numero para Último pedido e \$.status para Status do pedido](https://mintcdn.com/wizebot-d8529edc/npLQJVV8gD5vOhne/images/fluxo-blocos-integracoes/04-integracao-resposta.png?fit=max\&auto=format\&n=npLQJVV8gD5vOhne\&q=85\&s=ef6b5fab1ee12379cf004cfd8c78ea62)

**4. Ajuste o tempo de espera e as tentativas**

Na aba **Avançado**:

1. **Timeout (ms)**: quanto tempo esperar pela resposta, entre 1 e 30 segundos. O padrão é 10 segundos (10000).
2. **Tentativas**: quantas vezes a chamada é feita até dar certo, de 1 a 5. Entre uma tentativa e outra a espera dobra: 1, 2, 4 e 8 segundos.

![Aba Avançado com os campos Timeout (ms) e Tentativas numerados](https://mintcdn.com/wizebot-d8529edc/npLQJVV8gD5vOhne/images/fluxo-blocos-integracoes/05-integracao-avancado.png?fit=max\&auto=format\&n=npLQJVV8gD5vOhne\&q=85\&s=ef01f1c204b31865719cd110346fa6e3)

**5. Salve**

Clique em **Salvar**. A integração fica escolhida no bloco.

### Quando a chamada falha

A chamada falha quando a API não responde dentro do tempo, quando há erro de conexão ou quando a resposta tem código de erro (400 ou acima), depois de todas as tentativas. Nesse caso, o bloco segue esta ordem:

| Situação | O que acontece |
| - | - |
| **Esta chamada é obrigatória** ligado | O fluxo termina no bloco. A saída **Falha** não é usada. |
| Saída **Falha** ligada a outro bloco | O fluxo segue só pela saída **Falha**. |
| Integração bloqueada por falhas seguidas | O fluxo termina no bloco. |
| Nenhum dos casos acima | O fluxo segue pelo **Próximo passo**, sem a resposta. |

A integração fica bloqueada por um tempo quando a API falha muitas vezes seguidas por erro dela (fora do ar, tempo esgotado). Isso protege o seu sistema de receber chamadas enquanto está com problema. Erros de dados, como "pedido não encontrado", não contam para esse bloqueio.

Quando o fluxo segue depois de uma falha, o motivo fica em `{{last_integration_error.reason}}`. Os valores possíveis são `timeout`, `network_error`, `http_4xx`, `http_5xx`, `http_error` e `circuit_open`. Você pode usar esse valor num bloco **Condição** para dar respostas diferentes. O nome `last_integration_error` é reservado e não pode ser usado em **Nome para essa resposta**.

> [!WARNING]
>
> Sem a saída **Falha** ligada e com a chamada opcional, o fluxo continua pelo caminho normal mesmo quando a API falha. Mensagens que usam a resposta, como `{{pedido.status}}`, chegam ao cliente sem o valor. Ligue a saída **Falha** sempre que a mensagem seguinte depender da resposta.

## Google Sheets

O bloco **Google Sheets** trabalha com uma planilha do Google Drive: procura uma linha, adiciona uma linha nova, atualiza uma linha que já existe ou confere se um valor está na planilha. Serve para registrar leads, anotar pedidos ou consultar uma tabela de preços sem precisar de outro sistema.

Antes de usar o bloco, a conta Google que tem acesso à planilha precisa estar conectada, e a planilha precisa ter os nomes das colunas na primeira linha.

### Configurar o bloco

**1. Conecte a conta Google**

Em **Conta Google**, escolha uma conta já conectada ou clique em **Conectar nova conta Google**. Uma janela do Google abre para você entrar e autorizar o acesso às planilhas. Depois de autorizar, a conta aparece na lista.

Se a conta aparecer com "(expirada)", conecte de novo pelo mesmo botão.

![Painel do bloco Registrar na planilha com Conectar nova conta Google, a planilha escolhida, a operação Adicionar linha e as colunas da planilha numeradas](https://mintcdn.com/wizebot-d8529edc/npLQJVV8gD5vOhne/images/fluxo-blocos-integracoes/06-painel-sheets.png?fit=max\&auto=format\&n=npLQJVV8gD5vOhne\&q=85\&s=44d5ae24cf506967c43586cfa28986b8)

**2. Escolha a planilha e a aba**

Em **Planilha**, busque pelo nome e clique na planilha. Para escolher outra depois, clique em **Trocar**. Em **Aba**, escolha a aba da planilha. Se a planilha tem uma aba só, ela já vem escolhida.

**3. Escolha a operação**

Em **Operação**, escolha o que o bloco vai fazer. Cada operação está explicada na próxima seção.

**4. Preencha os dados da operação**

Para **Adicionar linha** e **Atualizar**, cada coluna da planilha aparece com uma lista ao lado. Escolha a variável que vai preencher cada coluna, por exemplo `{{contact.name}}` em "Nome" e `{{pedido.status}}` em "Status". O botão **Mapear** tenta ligar as colunas aos campos do contato com nome parecido.

### Operações

| Operação | O que faz | Campos |
| - | - | - |
| **Ler** | Procura a primeira linha em que a coluna escolhida tem o valor buscado | **Coluna de busca**, **Valor a buscar**, **Salvar resultado na variável** |
| **Adicionar linha** | Escreve uma linha nova no fim da aba | Colunas e valores |
| **Atualizar** | Procura a linha pelo valor buscado e troca os valores das colunas escolhidas | **Coluna de busca**, **Valor a buscar**, colunas e valores |
| **Verificar** | Confere se o valor buscado existe na coluna | **Coluna de busca**, **Valor a buscar**, **Salvar resultado na variável** |

* Em **Ler**, a primeira linha encontrada fica na variável que você escolheu. Leia cada coluna pelo nome dela: com a variável `dados_planilha` e uma coluna chamada Valor, use `{{dados_planilha.Valor}}`. Prefira nomes de coluna sem acento e sem espaço para usar assim. Se nada for encontrado, a variável fica vazia.
* Em **Verificar**, a variável recebe `true` (existe) ou `false` (não existe). Use um bloco **Condição** para seguir caminhos diferentes, por exemplo "cliente já cadastrado" e "cliente novo".
* Em **Adicionar linha** e **Atualizar**, a opção **Enviar todos os dados do contato** preenche a planilha com nome, telefone e todos os campos personalizados que têm valor. Colunas que ainda não existem são criadas. Com essa opção ligada em **Adicionar linha**, a WizeBot procura o telefone do contato na coluna Telefone: se encontrar, atualiza aquela linha em vez de criar uma repetida.

### Quando a planilha não responde

O bloco **Google Sheets** tem só a saída **Próximo passo**. Se a operação não der certo (conta expirada, sem permissão na planilha, planilha apagada, tempo esgotado), o fluxo continua normalmente e a variável de resultado não é preenchida. Para tratar esse caso, use a operação **Ler** ou **Verificar** e confira a variável num bloco **Condição** antes de usar o valor.

Cada conta da WizeBot pode fazer até 50 operações de planilha por minuto. Acima disso, a operação não é feita naquele momento. O tempo de espera pela resposta do Google vai de 1 a 30 segundos e fica no campo **Timeout (ms)**, no fim do painel.

## Problemas comuns

> [accordion] A mensagem chega com o espaço da variável em branco
>
> A chamada falhou ou a resposta não tem o dado com aquele nome. Clique em **Testar** na integração e confira, na resposta, o nome exato do dado. Ligue a saída **Falha** do bloco para que o cliente não receba a mensagem incompleta.

> [accordion] A lista de dados da resposta não aparece na aba Resposta
>
> A lista é montada a partir do último teste. Escolha um **Contato para Teste** na aba **Básico**, clique em **Testar** e volte para a aba **Resposta**.

> [accordion] O fluxo parou no bloco Integração HTTP
>
> Isso acontece quando **Esta chamada é obrigatória** está ligado e a chamada falhou, ou quando a integração foi bloqueada depois de várias falhas seguidas da API. Confira se o sistema que você chama está no ar e teste a integração de novo.

> [accordion] A planilha não aparece na busca
>
> A conta Google escolhida precisa ter acesso à planilha. Abra a planilha no Google Drive, compartilhe com essa conta ou conecte a conta dona da planilha em **Conectar nova conta Google**.

> [accordion] As colunas da planilha não aparecem no painel
>
> A WizeBot lê os nomes das colunas na primeira linha da aba. Escreva os nomes na primeira linha e escolha a aba de novo.

## Precisa de ajuda?

Fale com o suporte da WizeBot pelo WhatsApp ou por e-mail.

> [card] [WhatsApp](https://wa.me/559192226534)
>
> Falar com o suporte

> [card] [E-mail](mailto:suporte@wizebot.com.br)
>
> Enviar um e-mail


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