SC 2 Prospeccao Pessoas

Area_Business_Intelligence#Smart_Components

Este documento detalha o funcionamento do Smart Componente de Prospecção de Pessoas. Com base no cadastro de clientes e seu histórico de compras e seu respectivo periodo de inatividade, gera novas solicitações de prospecção a serem realizadas pelos usuários do time comercial.

Logo, este componente **SCExecProspeccaoPessoas** tem como objetivo automatizar a **criação de prospecções comerciais** (novas oportunidades de venda) para clientes da base, com base em critérios de inatividade, filtros geográficos, segmentos, representantes e outros parâmetros definidos.

Ele analisa clientes que **não compram há determinado período** (com base em pedidos ou notas fiscais) e cria automaticamente **registros de prospecção** para que a equipe comercial possa realizar o contato.

O sistema também distribui as prospecções automaticamente entre os usuários disponíveis do grupo comercial, respeitando o **limite máximo de prospecções por usuário**.

Ao final da execução, é gerado um **arquivo Excel** com as prospecções criadas, contendo as informações principais (pessoa, CNPJ, observação, relacionamento, etc.).

Atenção: Gere o Smart usando o modo "Pré Visualizar", como todos os parâmetros desejados. Avalie quais parâmetros a serem utilizados, ativados. Ao ter certeza sobre estes, gere o Smart pelo Executar. Somente após avaliar o sucesso executando o Smart por alguns dias, agende sua execução automática pelo recurso de tarefas.

2. Pré-requisitos

Antes de executar o componente, certifique-se de que:

• A **empresa**, **grupo de usuários**, **campanha de vendas** e **tipo de prospecção** estejam cadastrados.
• Os **usuários** do grupo informado estejam **ativos** e vinculados à empresa.
• As **naturezas de operação** de venda estejam corretamente configuradas.
• A **fase comercial** e o **funil de vendas** estejam definidos.
• Exista **pelo menos um representante padrão** para atribuição automática.
• As **regras de feriados** estejam cadastradas (usadas no agendamento do CRM).
• O serviço de prospecção (`ServiceProspeccaoPessoasImpl`) esteja ativo e integrado.

3. Parâmetros Principais

Os parâmetros são configurados na interface de execução do componente (Smart Components) ou via integração. Abaixo, os principais:

Principais Parâmetros

Texto do cabeçalho	Texto do cabeçalho
P_ID_EMPRESA	Empresa responsável pela prospecção
P_ID_GRUPO_USUARIOS_PROSPECCAO	Grupo de usuários que receberá as prospecções
P_ID_CAMPANHA_VENDAS	Campanha de vendas vinculada
P_ID_TIPO_PROSPECCAO	Tipo de prospecção (Ex: Reativação, Nova Venda)
P_ID_REPRESENTANTE_PADRAO	Representante padrão para clientes sem vínculo
P_ID_FUNIL_VENDAS	Funil de vendas associado
P_ID_FASE_COMERCIAL	Fase inicial da prospecção
P_ID_ORIGEM_PROSPECCAO	Origem da prospecção (Ex: Automática, Campanha)
P_ID_NATUREZA_OPERACAO_VENDAS	Naturezas de operação consideradas
P_DIAS_SEM_COMPRA_INICIAL	Dias sem compra inicial
P_DIAS_SEM_COMPRA_FINAL	Dias sem compra final
P_QTD_MAX_PROSPECCOES_USUARIO	Máximo de prospecções abertas por usuário
P_DIAS_DESLOCAMENTO_AGENDAMENTO	Dias até o primeiro agendamento no CRM
P_EFETUAR_ANALISE_FIN	Realiza análise financeira antes de gerar a prospecção (`1=Sim`)
P_CLIENTES_ATIVOS_INATIVOS	Considera clientes ativos/inativos (`1=Ativo`, `0=Inativo`, `9=Todos`)
P_TIPO_FONTE_PEDIDO_NOTA_FISCAL	Fonte de dados (`0=Nota Fiscal`, `1=Pedido`)
P_TIPO_ORDENACAO	Ordem de seleção (`0=Maior Valor`, `1=Mais Antigo`, `2=Mais Recente`)
P_MODELO_MENSAGEM	Modelo da observação da prospecção

Filtros opcionais

É possível aplicar filtros adicionais (ativando com '1'(Sim) e informando os IDs correspondentes):

• `Filtrar Ramo de Atvividade` / `Ids dos Ramos de Atividade`
• `Filtrar Região` / `Ids das Regiões`
• `Filtrar Cidade` / `Ids das Cidades`
• `Filtrar UF` / `Ids das UFs`
• `Filtrar Representante` / `Ids dos Representantes`
• `Filtrar Classificação cliente` / `Ids das Classificações`

4. Execução

1. **Preencha os parâmetros obrigatórios** na tela de configuração do componente.
2. **Revise os filtros opcionais**, se desejar limitar os clientes analisados.
3. **Execute** o componente (modo “Processar” ou “Visualizar Prévia”): “Prévia” apenas gera o relatório Excel sem salvar no banco; “Processar” grava as prospecções efetivamente.
4. **Aguarde a conclusão.** O sistema exibirá o resultado.

5. Resultados

Após a execução, será gerado um arquivo Excel:

1. • • Nome:** `dados_prospeccoes.xlsx`
     • Planilha:** `prospeccoes`

Texto da legenda

Texto do cabeçalho	Texto do cabeçalho
F_ID_PROSPECCAO	Identificador da prospecção criada (Gerado somente se Executado o Smart. Em Previsualizar, será retornado 0)
F_ID_RELACIONAMENTO	ID do relacionamento associado (Gerado somente se Executado o Smart. Em Previsualizar, será retornado 0)
F_NR_PROTOCOLO	Número de protocolo do relacionamento (Gerado somente se Executado o Smart. Em Previsualizar, será retornado 0)
F_PESSOA	Nome da pessoa ou cliente
F_CNPJ_CPF	Documento da pessoa
F_OBSERVACAO	Mensagem gerada (modelo parametrizado)

| Campo | Descrição | | --------------------- | -------------------------------------- | | `F_ID_PROSPECCAO` | Identificador da prospecção criada | | `F_ID_RELACIONAMENTO` | ID do relacionamento associado | | `F_NR_PROTOCOLO` | Número de protocolo do relacionamento | | `F_PESSOA` | Nome da pessoa ou cliente | | `F_CNPJ_CPF` | Documento da pessoa | | `F_OBSERVACAO` | Mensagem gerada (modelo parametrizado) |

Se nenhum cliente atender aos critérios, o arquivo conterá uma única linha informando que **nenhuma prospecção foi gerada**.

6. Lógica de Distribuição

• O componente identifica os **usuários disponíveis** no grupo informado.
• Verifica quantas prospecções cada um possui em andamento.
• Distribui as novas prospecções **de forma balanceada**, respeitando o limite (`P_QTD_MAX_PROSPECCOES_USUARIO`).
• Caso todos estejam no limite, nenhuma nova prospecção é criada.

7. Considerações Técnicas

• O cálculo de “dias sem compra” é feito com base nas datas de emissão de **Notas Fiscais** ou **Pedidos**, conforme o parâmetro.
• São ignorados clientes que já possuem prospecções abertas na mesma campanha.
• Clientes com **títulos vencidos** podem ser excluídos, se a análise financeira estiver ativada.
• O sistema considera **feriados e finais de semana** ao calcular a data de agendamento.

8. Mensagens de Erro Comuns

Mensagens

Mensagem	Causa provável
“Número de dias sem compra inicial não pode ser superior ao número de dias final”	Parâmetros invertidos
“Verifique os parâmetros informados. Nenhuma prospecção gerada.”	Filtros muito restritivos ou ausência de usuários disponíveis
“Parâmetro obrigatório não informado”	Campo essencial ausente na configuração

9. Boas Práticas

• Evite aplicar muitos filtros simultaneamente — pode resultar em nenhum cliente elegível.
• Utilize **pré-visualização** antes da execução definitiva.
• Atualize periodicamente os **dados de feriados** e **representantes**.
• Ajuste o **modelo de mensagem** para personalizar a comunicação.

10. Saída Esperada

Um arquivo Excel e, quando em modo de processamento, **novos registros de prospecção** criados no banco de dados, prontos para acompanhamento pela equipe de vendas.