¶ Como configurar e utilizar a integração entre o Questor Negócio e o Q-Desk?
A integração com o Questor Negócio conecta o Q-Desk à API do Questor Negócio e permite trazer cadastros e informações financeiras para o atendimento, reduzindo a necessidade de cadastro manual de clientes.
A configuração é realizada uma única vez por conta e passa a ser utilizada pela sincronização de empresas, pela Régua de Cobrança e pelos blocos de boleto.
¶ Pré-requisitos
Antes de configurar a integração, verifique se os seguintes requisitos estão disponíveis:
- O módulo "Integração Questor Negócio (QN)" deve estar habilitado na conta.
- O usuário deve possuir perfil de administrador.
- O endereço da API do Questor Negócio deve estar disponível.
- A chave de acesso da API do Questor Negócio deve estar disponível. [CONFIRMAR COM ANALISTA] como essa chave é gerada e onde pode ser obtida no Questor Negócio.
- As inscrições federais (CNPJ) dos estabelecimentos que serão consultados devem estar disponíveis.
- Para utilizar a Régua de Cobrança, o módulo "Régua de cobrança" deve estar habilitado e as empresas devem possuir o campo "CNPJ" preenchido.
- Para utilizar os blocos de boleto, o módulo "Fluxo de conversa" deve estar habilitado e o fluxo deve estar vinculado a uma caixa de entrada.
- Para consultar as empresas sincronizadas, o módulo "Empresas" deve estar habilitado.
¶ Acessar a configuração da integração
No Q-Desk, acesse: Configurações > Avançado > Integrações
Localize o cartão "Questor Negócios" na lista de integrações e clique em "Configurar" para acessar a tela de configuração.
Na tela de configuração da integração, clique em "Conectar" para abrir o formulário de configuração.
Será exibida uma tela para informar os dados de acesso da integração:
- URL: Informe o endereço da API do Questor Negócio. Este campo é obrigatório. As barras informadas no final do endereço serão desconsideradas pelo sistema.
- API Key: Informe a chave utilizada para autenticar o Q-Desk no Questor Negócio. Este campo é obrigatório.
- Documentos da Empresa: Informe a inscrição federal (CNPJ) de cada estabelecimento que será consultado. Digite somente os números e pressione "Enter" para adicionar o documento. É possível informar mais de um documento.
⚠️ Importante!
O Q-Desk não valida a "URL" e a "API Key" no momento em que a integração é salva. A validação ocorrerá na primeira consulta ao Questor Negócio.
Após preencher os dados, clique em "Criar".
Após concluir a configuração, prossiga com as demais etapas para estabelecer a conexão entre o Q-Desk e o Questor Negócio.
¶ Como funciona a integração
O Q-Desk inicia a comunicação e funciona apenas como leitor de dados. Em cada consulta, o Q-Desk se autentica na API do Questor Negócio com a chave informada, recebe um token temporário e utiliza esse token nas consultas seguintes.
Nenhum dado é gravado no Questor Negócio.
¶ Sincronizar empresas e contatos
A sincronização é manual e executada pelo botão "Sincronizar", disponível na tela do aplicativo. Em cada execução, o Q-Desk consulta o cadastro de pessoas do Questor Negócio e cria ou atualiza os registros correspondentes.
Cada pessoa que possui inscrição federal gera uma empresa no Q-Desk com os seguintes campos preenchidos:
- Nome da Empresa: Razão social da pessoa. Quando não preenchida, o sistema utiliza o nome fantasia.
- CNPJ: Inscrição federal da pessoa.
- Endereço: Logradouro e número do primeiro endereço cadastrado.
- Número: Complemento do endereço.
- Bairro: Bairro do endereço.
- CEP: CEP do endereço.
Os contatos vinculados à pessoa são criados como contatos do Q-Desk e associados à empresa correspondente, com os seguintes campos preenchidos:
- Nome: Nome do contato cadastrado no Questor Negócio.
- Endereço de e-mail: E-mail do contato. Endereços inválidos são descartados.
- Número de telefone: Telefone celular do contato. Quando não houver celular, será utilizado o telefone fixo.
- Identificador: Código gerado no formato "questornegocio_", seguido do código do contato no Questor Negócio.
Registros já existentes são localizados e atualizados conforme as seguintes regras:
- A empresa é localizada pelo CNPJ ou pelo nome, quando não existe empresa com aquele documento.
- O contato é localizado pelo Identificador gerado pela integração.
- Os registros são atualizados somente quando existe diferença entre os dados.
- Alguns registros são ignorados durante a sincronização:
- Pessoas sem inscrição federal informada.
- Pessoas repetidas na mesma execução.
- Contatos sem nome.
- Contatos cujo e-mail ou telefone já pertença a outro contato da conta.
¶ Utilizar a integração no atendimento
¶ Atendimento de um contato sincronizado
Após a sincronização, o contato criado pela integração já fica vinculado à empresa correspondente. Abra a conversa e observe o painel lateral. O cartão "Empresa" apresenta o nome da empresa vinculada e o documento cadastrado.
¶ Envio da segunda via de boleto pelo fluxo
O envio ocorre dentro de um fluxo vinculado à caixa de entrada, sem depender de uma ação do atendente. O processo segue estas etapas:
O contato inicia a conversa na caixa de entrada vinculada ao fluxo.
Ao chegar ao bloco de boleto, o Q-Desk verifica se o contato possui uma empresa vinculada com CNPJ preenchido.
Quando o contato não possui documento, o fluxo envia uma mensagem solicitando o CNPJ ou CPF.
Quando existe apenas uma parcela em aberto, o boleto é enviado imediatamente.
Quando existem várias parcelas, o fluxo apresenta uma lista com, no máximo, dez opções. Cada opção apresenta o número da nota, o vencimento e o valor da parcela.
Após a escolha, o Q-Desk envia o PDF do boleto. No bloco "Boleto + nota", também envia o PDF da nota fiscal.
Quando não existem parcelas em aberto, o fluxo envia uma mensagem informando que não há boletos disponíveis.
¶ Consultas da Régua de Cobrança
A Régua de Cobrança utiliza a integração para consultar os títulos a receber, sem exigir configuração adicional. A execução ocorre automaticamente uma vez por dia, às 11h (horário de Brasília).
A mensagem é enviada quando a data calculada a partir do vencimento do título corresponde ao dia atual.
¶ Resolver problemas
Confira abaixo as mensagens apresentadas pelo Q-Desk e o tratamento indicado para cada situação:
- "Erro ao sincronizar com o Questor Negócios": Ocorreu uma falha na comunicação durante a sincronização. Confirme os dados informados em "URL" e "API Key" e verifique se a API está disponível.
- "Falha na autenticação com o Questor Negócios": A chave informada em "API Key" foi recusada ou o endereço informado em "URL" está incorreto. Revise os dois campos.
- "Integração Questor Negócio não configurada para esta conta.": Configure a integração na conta.
- "Nenhum estabelecimento configurado na integração (company_documents vazio).": Informe ao menos um documento no campo "Documentos da Empresa".
- "No momento não consegui consultar seus boletos. Tente novamente mais tarde.": Essa mensagem é enviada ao contato quando ocorre qualquer falha na consulta.
- "Não localizei a nota fiscal vinculada a este boleto.": Essa mensagem é enviada quando o bloco "Boleto + nota" não encontra a nota fiscal correspondente.
- Sincronização encerrada por excesso de consultas: Execute a sincronização novamente mais tarde.
- Contato não criado na sincronização: O e-mail ou telefone já pertence a outro contato, ou o contato está sem nome no Questor Negócio. Ajuste o cadastro de origem ou trate o contato duplicado.
- Empresa não criada na sincronização: A pessoa não possui inscrição federal informada no Questor Negócio.
¶ Observações e limitações
A integração funciona somente como leitura. Alterações realizadas no Q-Desk não são enviadas ao Questor Negócio.
É permitida apenas uma integração com o Questor Negócio por conta.
A sincronização de empresas e contatos é sempre manual e não possui execução automática em horário programado.
Registros excluídos no Questor Negócio não são excluídos no Q-Desk.
Somente o primeiro endereço cadastrado para a pessoa é utilizado no cadastro da empresa.
O campo "Número" da empresa recebe o complemento do endereço, e não o número do logradouro.
Todas as consultas financeiras são realizadas por estabelecimento. Documentos não informados em "Documentos da Empresa" não são consultados.
A lista de boletos apresenta, no máximo, dez opções.
Títulos, boletos e notas fiscais não ficam armazenados no Q-Desk. Cada consulta é realizada em tempo real.
Desconectar a integração não exclui as empresas e os contatos que já foram sincronizados.