Integração | Central de Ajuda

A integração é uma funcionalidade essencial que possibilita estabelecer conexões com bases de dados externas ao cVortex e API's, o que permite a atualização e busca de informações de maneira eficiente.

Com a integração, o cVortex é capaz de se comunicar com sistemas ou plataformas externas de forma bidirecional. Isso significa que é possível não apenas buscar dados atualizados a partir de fontes externas, mas também atualizar as informações nesses sistemas, mantendo uma sincronização constante.

Disponível em: Fluxos de Atendimento Humano, Automações Inteligentes, Atendimento Digital (chatbot e IA) e Atendimento por Voz.

Propriedades

Propriedade	Descrição	Regra
Nome	Digite o nome ou atributo que se refere à mensagem. Isso facilitará a identificação do conteúdo da mensagem mais tarde.	Obrigatório
Integração	Lista os tipos de integrações permitidas no cVortex: SQL, SOAP, REST.	Obrigatório
Conexão	Liste as conexões registradas nas configurações da plataforma para a integração específica anteriormente.	Obrigatório
Operação	Lista as operações cadastradas nas configurações de plataforma para a conexão selecionada anteriormente.
URL	Exibe as transações registradas nas configurações da plataforma para a conexão previamente selecionada.
Parâmetros de Path/Query	parâmetros aplicados às integrações REST, essas configurações são especificadas durante o cadastro da integração. Este campo só deve ser preenchido se você pretende modificar dinamicamente as informações por meio do Workflow.	Opcional
Cabeçalhos	Configurações de parâmetros aplicadas às integrações REST, essas configurações são definidas durante o registro da integração. Este campo deve ser preenchido apenas se você planeja alterar dinamicamente as informações por meio do Workflow. Ele exibirá os campos que foram cadastrados no cabeçalho da integração.	Opcional
Solicitação	Neste campo, você deve especificar quais campos serão enviados para realizar uma consulta. Estes campos estão relacionados aos campos cadastrados na seção Corpo da integração.	Obrigatório
Consulta	Este campo é utilizado para especificar a consulta desejada em integrações do tipo SQL. É importante notar que essa propriedade será ignorada em integrações que não sejam do tipo SQL	Sob demanda
Resposta	Exiba uma lista de campos que foram cadastrados na integração como resposta retornada pela API.	Preenchido automaticamente
Tratamento dinâmico de erros	Configuração desativada por padrão. Quando ativada, caso a integração retorne erro, o fluxo não será interrompido ou travado e a execução continuará, permitindo que o usuário trate qualquer código de erro retornado dentro do próprio fluxo. O retorno deve disponibilizar sempre o `statusCode` e a mensagem de erro da integração.	Opcional
Recuperar uma lista de objetos	Permite que a consulta realizada retorne uma lista de até 1000 registros para cada iteração, quando ativada.	Opcional
Sempre sucesso	Configuração desativada por padrão. Quando ativada, a integração ignora falhas de comunicação e o fluxo continua a execução normalmente. A validação do resultado passa a ser responsabilidade do fluxo, por meio dos campos `status`, `statusCode` e `message`. Veja a seção Sempre sucesso.	Opcional
Manipulação de retornos	Permite receber texto puro no retorno e alocá-lo em uma variável específica quando ocorrer, por exemplo: `STRING_ONLY { "valor" }`. Também permite configurar e utilizar, no construtor de fluxos, integrações que retornem listas simples, como listas de strings `{ "end1", "end2" }` ou listas com atributos `{ "telefone": ["tel_1"], "endereco": "end1" }`.	Opcional

Sempre sucesso

Por padrão, quando uma integração falha, a execução do fluxo é interrompida naquele ponto.

Com a opção Sempre sucesso ativada, a integração ignora falhas de comunicação e o fluxo continua a execução. A função sempre retorna sucesso, independentemente do que aconteceu.

Atenção:
Ativar esta opção não significa que a integração funcionou. Significa apenas que o fluxo não será interrompido caso ela falhe. Com a opção ativada, é obrigatório validar o retorno dentro do próprio fluxo. Sem essa validação, o fluxo seguirá com dados vazios ou desatualizados sem nenhum indício de erro.

Campos disponíveis no retorno

Com a opção ativada, a integração disponibiliza três campos no contexto do fluxo:

Campo	Descrição
`status`	Indica com `true` ou `false` se a execução da integração teve sucesso.
`statusCode`	Código HTTP retornado pela integração, por exemplo, `401`, `404` ou `500`.
`message`	Descrição do erro, quando houver.

Como validar o retorno

Ative a opção Sempre sucesso na seção Resposta da função Integração.
Logo após a função Integração, adicione uma função de decisão.
Configure a condição para verificar se status é igual a true.
No caminho de sucesso, siga com o tratamento normal dos dados retornados.
No caminho de falha, defina o comportamento desejado. Por exemplo: registrar o statusCode e a message, enviar uma mensagem alternativa ao cliente, direcionar o caso para atendimento humano ou tentar uma nova consulta.

Para tratamentos mais específicos, use o statusCode para diferenciar os tipos de falha. Um 401 indica problema de autenticação, um 404 indica recurso não encontrado e um 500 indica erro no sistema externo. Cada um pode levar a um caminho diferente no fluxo.

Quando usar

Ative Sempre sucesso quando a integração for complementar e a indisponibilidade do sistema externo não puder interromper o atendimento. Por exemplo: uma consulta de dados cadastrais adicionais que enriquece o atendimento, mas não é essencial para concluí-lo.

Mantenha a opção desativada quando o dado retornado pela integração for obrigatório para as etapas seguintes do fluxo. Nesses casos, interromper a execução é o comportamento mais seguro.

Restrições

Não se aplica aos Casos com o status do tipo Final.
Recupera uma lista com até 1000 registros.
Com a opção Sempre sucesso ativada, os campos mapeados na seção Resposta podem retornar vazios em caso de falha, e o fluxo continuará a execução mesmo assim.
O tempo máximo de espera pela resposta do sistema externo é de 60 segundos por função Integração. Após esse período, a resposta é considerada erro. Consulte [Tempos limite das integrações].

Tutoriais e exemplos

Sobre uma Integração.
Como cadastrar uma integração.
Como consultar endereço do cliente.

Observação
Após realizar qualquer alteração nas propriedades de uma função, você deverá clicar no botão salvar alterações. Esse botão estará disponível na parte inferior do painel de propriedades, sempre que houver alguma alteração de função.