Ver código fonte para BI 230 - Relatorio Clientes Sem Giro

'''Módulo''': [[Modulo Faturamento]]

== Objetivo ==

O relatório '''230 - Clientes Sem Giro''' identifica clientes que já compraram da empresa em algum momento, mas que não tiveram nenhuma compra válida (Nota Própria e/ou NFCe) dentro de um período específico informado pelo usuário — ou seja, uma lista de clientes que "esfriaram": compravam e pararam de comprar nesse período.

Um cliente que nunca teve nenhuma compra registrada '''não''' entra nesse relatório — ele não tem giro para "perder", então não se encaixa no conceito de "sem giro".

Para cada cliente sem giro listado, o relatório traz o representante responsável, os dados de contato e localização, informações sobre a última compra realizada (podendo restringir a busca dessa última compra a uma janela de datas própria, diferente do período usado para apurar o giro) e os totais de quantidade e valor de todas as compras válidas do cliente, sujeitos aos demais filtros aplicados.

== Filtros Disponíveis ==
{| class="wikitable"
|+
!Filtro
!Descrição
!Observação
!Referência Técnica
|-
|Filtrar Período Compra
|Ativa a possibilidade de restringir a uma janela de datas específica a busca pela última compra do cliente, exibida nas colunas Documento, Número, Série, Data Última Compra e Valor Última Compra.
|Quando ativado, exige o preenchimento de Início e Final do Período de Compras. Quando desativado, o sistema busca a compra mais recente do cliente sem limite de data. '''Não tira nenhum cliente do relatório''': quem decide a lista é só o período de Data Inicial/Data Final (Opções do Relatório). Se o cliente não tiver nenhuma compra dentro da janela deste filtro, ele continua listado — só as colunas de última compra ficam em branco.
|P_FILTRAR_DT_COMPRA
|-
|Início do Período de Compras
|Data inicial da janela usada para localizar a última compra do cliente.
|Obrigatório apenas quando Filtrar Período Compra está ativado.
|P_DT_COMPRA_IN
|-
|Final do Período de Compras
|Data final da janela usada para localizar a última compra do cliente.
|Obrigatório apenas quando Filtrar Período Compra está ativado.
|P_DT_COMPRA_FI
|-
|Filtrar Representante
|Restringe tanto a apuração de quem é "sem giro" quanto o relatório final aos clientes atendidos pelos representantes selecionados, cadastrados no recurso 72 - Representantes.
|Quando ativado, exige a seleção de ao menos um representante.
|P_FILTRAR_REPRES
|-
|Identificador Representante
|Lista de representantes considerados quando o filtro Filtrar Representante está ativo.
|—
|P_ID_REPRES
|-
|Filtrar Empresa
|Restringe quais clientes sem giro aparecem no relatório e os totais apresentados às empresas selecionadas, cadastradas no recurso 49 - Empresas.
|Não influencia o cálculo de quem tem ou não giro no período — só filtra a exibição final. Um cliente sem giro pode não aparecer no relatório se nenhuma nota dele bater com a empresa filtrada.
|P_FILTRAR_EMP
|-
|Identificador Empresa
|Lista de empresas consideradas quando o filtro Filtrar Empresa está ativo.
|—
|P_ID_EMP
|-
|Filtrar UF
|Restringe quais clientes sem giro aparecem no relatório e os totais apresentados à UF selecionada, cadastrada no recurso 150 - Unidade Federativa.
|Não influencia o cálculo de quem tem ou não giro no período. Aceita apenas uma UF por vez.
|P_FILTRAR_UF
|-
|Identificador UF
|UF considerada quando o filtro Filtrar UF está ativo.
|—
|P_ID_UF
|-
|Filtrar Cidade
|Restringe quais clientes sem giro aparecem no relatório e os totais apresentados à cidade selecionada, cadastrada no recurso 151 - Cidade.
|Não influencia o cálculo de quem tem ou não giro no período. Aceita apenas uma cidade por vez.
|P_FILTRAR_CIDADE
|-
|Identificador Cidade
|Cidade considerada quando o filtro Filtrar Cidade está ativo.
|—
|P_ID_CIDADE
|-
|Opções do Relatório
|Ativa o período que define o critério de "sem giro": o cliente só entra no relatório se não tiver nenhuma compra válida dentro desse período.
|Quando ativado, exige o preenchimento de Data Inicial, Data Final, Tipo Documento, Considerar Somente CFOP Receita Venda, Exibir Endereço e Considerar Somente Cliente Ativo.
|P_OPCOES_REL
|-
|Data Inicial
|Data inicial do período analisado para verificar se o cliente teve movimentação (giro).
|O cliente só aparece no relatório se não tiver nenhuma compra válida entre a Data Inicial e a Data Final.
|P_DATA_IN
|-
|Data Final
|Data final do período analisado para verificar se o cliente teve movimentação (giro).
|Ver observação de Data Inicial.
|P_DATA_FI
|-
|Tipo Documento
|Define quais documentos fiscais são considerados: apenas Nota Própria, ou Nota Própria e NFCe juntas ("Todos os Documentos").
|Vale tanto para apurar se o cliente teve giro no período quanto para localizar a última compra.
|P_TIPO_DOC
|-
|Considerar Somente CFOP Receita Venda
|Restringe os documentos considerados nos totais e na última compra àqueles cujo CFOP esteja marcado como CFOP de receita de venda.
|Não influencia o cálculo de quem tem ou não giro no período — só filtra a exibição final. Um cliente sem giro pode não aparecer no relatório se só tiver notas com CFOP fora dessa marcação.
|P_CFOP_VENDA
|-
|Exibir Endereço
|Controla se o relatório imprime, logo abaixo de cada cliente, uma linha adicional com o endereço completo.
|—
|P_EXIBE_END
|-
|Considerar Somente Cliente Ativo
|Restringe tanto a apuração de quem é "sem giro" quanto o relatório final aos clientes com cadastro marcado como ativo, no recurso 76 - Clientes.
|—
|P_CLI_ATIVO
|}

== Campos Corpo ==
{| class="wikitable"
|+
!Campo
!Descrição
!Observação
!Referência Técnica
|-
|Cliente (ID - Nome)
|Identificador e nome do cliente sem giro, vindos do cadastro do recurso 76 - Clientes.
|—
|F_ID_CLI, F_NOME_CLI — exibidos como "&lt;ID&gt; - &lt;Nome&gt;"
|-
|Tel. / Cel.
|Telefone fixo do cliente; quando não cadastrado, mostra o celular.
|—
|F_FONE_CLI — quando nulo, usa F_CEL_CLI
|-
|Representante (ID - Nome)
|Identificador e nome do representante responsável pelo cliente, cadastrado no recurso 72 - Representantes.
|—
|F_ID_REPRES, F_NOME_REPRES — exibidos como "&lt;ID&gt; - &lt;Nome&gt;"
|-
|Cidade
|Cidade cadastrada no endereço do cliente.
|—
|F_NOME_CIDADE_CLI
|-
|U.F.
|Sigla da UF cadastrada no endereço do cliente.
|—
|F_SIGLA_UF_CLI
|-
|Documento
|Tipo do documento da última compra localizada para o cliente: "Nota Própria", "NFCe" ou "Sem Documentos".
|"Sem Documentos" só aparece quando Tipo Documento = Todos os Documentos e não é encontrada nenhuma Nota Própria nem NFCe no critério de última compra. Quando Tipo Documento = Apenas Nota Própria, o campo sempre mostra "Nota Própria", mesmo quando nenhuma é encontrada — nesse caso as demais colunas da última compra ficam em branco.
|F_TIPO_ULT_DOC
|-
|Número
|Número do documento da última compra do cliente.
|—
|F_NUM_ULT_DOC
|-
|Série
|Série do documento da última compra do cliente.
|—
|F_SERIE_ULT_DOC
|-
|Data Última Compra
|Data de emissão do documento mais recente do cliente, respeitando o filtro Filtrar Período Compra (quando ativo) e o Tipo Documento selecionado.
|Quando Tipo Documento = Todos os Documentos, o sistema compara a Nota Própria e a NFCe mais recentes do cliente e mostra a data da mais nova das duas.
|F_DATA_ULT_DOC
|-
|Valor Última Compra
|Valor total do documento da última compra do cliente.
|—
|F_VLR_TOT_ULT_DOC
|-
|Emissões (Quant.)
|Quantidade total de notas válidas emitidas para o cliente, considerando os filtros Representante, Empresa, UF, Cidade, CFOP Receita Venda e Cliente Ativo.
|Não se limita ao período de "Opções do Relatório" — soma todo o histórico de documentos válidos do cliente que atende aos demais filtros, não apenas o período usado para apurar o giro.
|F_COUNT_NOTA_CLI
|-
|Valor Total Compras
|Soma do valor de todos os itens das notas contadas em Emissões (Quant.).
|Mesmo critério de período do campo Emissões (Quant.) — soma todo o histórico, não apenas o período de apuração do giro.
|F_TOTAL_NOTA_CLI
|-
|Endereço
|Endereço completo do cliente (logradouro, número, bairro, complemento quando houver, cidade, UF e país), impresso em uma linha abaixo dos dados do cliente.
|Só aparece quando o filtro Exibir Endereço está ativado.
|F_END_CLI, F_NUM_END_CLI, F_BAIRRO_CLI, F_COMPLEM_END_CLI, F_NOME_CIDADE_CLI, F_NOME_UF_CLI, F_NOME_PAIS_CLI
|}

== Dicas de Análise do Relatório ==

'''O que "sem giro" realmente significa:''' um cliente só aparece nesse relatório se tiver comprado em algum momento (qualquer período) e não ter comprado nada dentro do período informado em Data Inicial / Data Final (Opções do Relatório). Um cliente que nunca comprou nada não aparece — o relatório não serve para achar clientes que nunca compraram, e sim clientes que pararam de comprar.

'''Os totais não são do período do relatório:''' Emissões (Quant.) e Valor Total Compras somam todo o histórico de compras válidas do cliente (sujeito aos filtros de Representante, Empresa, UF, Cidade, CFOP Receita Venda e Cliente Ativo), não apenas o período usado para definir o giro. Um cliente pode aparecer com números altos nesses totais mesmo estando "sem giro" recentemente — isso indica o tamanho do relacionamento passado com esse cliente e ajuda a priorizar quem vale mais a pena reativar.

'''Última compra não é necessariamente a mais recente de todas:''' se o filtro Filtrar Período Compra estiver ativo, a Data Última Compra mostrada é a mais recente '''dentro daquela janela''', que pode ser diferente do período usado para apurar o giro. Vale conferir as duas janelas de data (Opções do Relatório e Filtrar Período Compra) antes de interpretar a Data Última Compra como "a compra mais recente do cliente em toda a história".

'''Última Compra em branco não significa "sem histórico":''' quando Filtrar Período Compra está ativo, é comum ver um cliente com Emissões (Quant.) e Valor Total Compras positivos, mas Documento/Número/Série/Data Última Compra/Valor Última Compra em branco (ou Documento mostrando "Nota Própria" sem os demais dados). Isso acontece porque os totais somam '''todo''' o histórico de compras do cliente, sem limite de data, enquanto a Última Compra só é buscada '''dentro''' da janela de Filtrar Período Compra — se todas as compras desse cliente caíram fora dessa janela específica, a Última Compra fica em branco mesmo com um histórico relevante nos totais. Ver também a tabela de Problemas Comuns.

== Problemas Comuns e Como Resolver ==
{| class="wikitable"
|+
!Situação
!O que fazer
|-
|O relatório não retorna nenhum cliente
|Verificar se o filtro Opções do Relatório está ativado e se Data Inicial e Data Final foram preenchidas — sem esse período, o critério de "sem giro" não pode ser calculado.
|-
|Documento, Número, Série, Data Última Compra e Valor Última Compra aparecem em branco (ou Documento mostra "Nota Própria"/"Sem Documentos" sem os demais dados) para um cliente — mesmo que Emissões (Quant.) e Valor Total Compras estejam preenchidos e positivos para esse mesmo cliente
|Isso é esperado quando o filtro Filtrar Período Compra está ativo: ele restringe a busca da Última Compra a uma janela de datas específica (Início/Final do Período de Compras), e se nenhuma compra do cliente cair dentro dela, essas colunas ficam em branco — mesmo que o cliente tenha comprado fora dessa janela, o que os totais (que não têm limite de data) continuam contando. Não é erro de dados: para ver a última compra real do cliente, desative o filtro Filtrar Período Compra (ou amplie a janela de datas) e gere o relatório novamente.
|-
|A linha de Endereço não aparece no relatório
|Verificar se o filtro Exibir Endereço foi marcado antes de gerar o relatório — ele só imprime quando ativado.
|-
|Um cliente sem giro esperado não aparece no relatório, mesmo com Opções do Relatório preenchido corretamente
|Conferir os filtros Filtrar Empresa, Filtrar UF, Filtrar Cidade e Considerar Somente CFOP Receita Venda: eles não afetam o cálculo de quem é "sem giro", mas filtram a exibição final. Se nenhuma nota do cliente bater com esses filtros, ele fica de fora do relatório mesmo sendo tecnicamente "sem giro".
|-
|Um cliente que nunca comprou nada não aparece no relatório
|Esse comportamento é esperado: o relatório lista apenas clientes que tiveram giro em algum momento e pararam de comprar dentro do período informado — clientes sem nenhuma compra registrada não entram na lista.
|}