Análise de Vendas e Faturamento — Documentação Complementar

https://<host>:<porta>/root/dicionario?userToken=<token>

Antes da primeira consulta, confirme com o responsável pelo ERP que o período que você pretende exibir já foi processado para as empresas que interessam ao painel. O processamento é feito na tela Avaliação de Venda Líquida, pelo botão Processar Período.

Parâmetro da tela	Efeito
Empresa	Empresa base do processamento.
Tipo de Empresa	Expande a empresa base: específica, matriz, grupo SPED ou grupo econômico.
Período	Intervalo de datas a processar. Máximo de 90 dias por execução — períodos maiores são recusados com mensagem.
Ação	Processar o período (recalcula e regrava) ou Excluir o período (remove a apuração daquele intervalo).

O reprocessamento de um intervalo substitui o que havia para aquele intervalo. É a operação correta depois de qualquer acerto retroativo de custo, comissão, frete ou tributação.

O parâmetro P_TIPOANALISE é o mais importante de PRC_RES_ANALISEVENDAS2. Ele decide duas coisas ao mesmo tempo:

1. O grão do retorno — o que vira uma linha. Nos tipos agregados, os valores voltam somados por grupo; nos tipos analíticos, cada linha é um item de nota fiscal.
2. Quais colunas vêm preenchidas — as dimensões que não pertencem ao tipo escolhido são devolvidas como null. A estrutura do retorno é sempre a mesma; o conteúdo é que muda.

Valor	Tipo de análise	Grão	Dimensões preenchidas
1	Dia	Agregado	ME_ENT
2	Nota Fiscal	Agregado	Empresa, CF_TIPO, FT_COD, série, número, datas, modelo, condição de pagamento e tipo de operação
3	Item Nota Fiscal	Analítico	Todas — uma linha por item, sem soma
4	Processo de Importação	Agregado	PIM_COD, PIM_CODINTERNO, PIM_DES, DIM_NUMERODI
5	Empresa	Agregado	FL_COD, FL_DES
6	Cliente	Agregado	CF_COD, CF_RSOCIAL
7	Vendedor	Agregado	VD_COD, VD_NOM
8	Produto	Agregado	PD_COD, PD_DES, PD_CUSTOAP
9	Grupo de Produto	Agregado	GP_COD, GP_DES
10	Sub-Grupo de Produto	Agregado	GP_COD, GP_DES, SG_COD, SG_DES
11	Tipo de Produto	Agregado	TP_COD, TP_DES
12	Linha do Produto	Agregado	LP_COD, LP_DES
13	Países	Agregado	PS_COD, PS_NOME
14	Estados	Agregado	CF_ESTADO, UF_REGIAO
15	Região de Vendas	Agregado	REG_COD, REG_DES — considera apenas clientes com região definida
16	Grupo Empresarial	Agregado	CLI_CF_COD, CF_RSOCIALGRP — considera apenas clientes vinculados a um grupo
17	Grupo Econômico	Agregado	FL_GRUPO, FL_DESGRP — considera apenas empresas vinculadas a um grupo
18	Cubo de Vendas	Analítico	Todas — mesma estrutura do tipo 3

Parâmetros obrigatórios

Estes cinco não têm valor padrão e precisam vir em params:

Parâmetro	Descrição
P_TIPOANALISE	Tipo de análise, de 1 a 18 (Passo 2).
P_FL_COD	Código da empresa base.
P_TIPOEMPRESA	Como expandir a empresa base — ver quadro abaixo.
P_ME_ENT1	Data inicial do período.
P_ME_ENT2	Data final do período.

Expansão da empresa (P_TIPOEMPRESA)

Valor	Empresas consideradas
0	Somente a empresa informada em P_FL_COD.
1	A matriz e suas filiais.
2	O grupo SPED da empresa informada.
3	O grupo econômico da empresa informada.

Em qualquer valor, a lista resultante ainda é filtrada pela configuração de acesso Empresas × Usuário do usuário vinculado ao token.

Período

• O filtro incide sobre a data de movimentação da nota (ME_ENT), não sobre a data de emissão.
• Use ISO-8601 ("2026-07-01" ou "2026-07-01 00:00:00.000"). O parâmetro é do tipo data: a hora informada é ignorada, então 00:00:00.000 e 23:59:59.999 são equivalentes.
• Os dois extremos são inclusivos.
• Períodos longos custam caro. Evite intervalos amplos em horário comercial e prefira várias janelas menores, com filtros, a uma janela única sem filtro.

Filtros opcionais

Todos aceitam ausência de valor. Os numéricos só entram na consulta quando maiores que zero; os textuais, quando não vazios. Ou seja: enviar 0, null ou "" equivale a não filtrar — não existe filtro pelo código zero.

Parâmetro	Filtra por
P_CF_COD	Cliente da nota.
P_CLI_CF_COD	Grupo empresarial do cliente.
P_REG_COD	Região de vendas do cliente.
P_CF_ESTADO	Estado (UF) do cliente. Texto de 2 caracteres.
P_VD_COD	Vendedor da nota.
P_GV_COD	Supervisor do vendedor.
P_PD_COD	Produto.
P_GP_COD / P_SG_COD	Grupo e subgrupo de produto.
P_TP_COD / P_LP_COD	Tipo e linha de produto.
P_FT_COD	Um documento específico.
P_NP_COD	CFOP (natureza da operação). Texto.
P_PIM_COD	Processo de importação. Só é considerado nos tipos de análise 3, 4 e 18.

Parâmetros que mudam o que entra na conta

Estes três não são recortes: eles alteram o universo somado. São a origem mais comum de divergência entre um painel e o relatório do ERP.

Parâmetro	Valor	Comportamento
P_BONIFICACAO	0	Padrão. Exclui as operações marcadas como bonificação.
	1	Inclui as bonificações no resultado.
P_ABATEDEVOLUCAO	0	Padrão. Considera apenas as saídas; devoluções ficam de fora.
	1	Abate as devoluções ocorridas no período consultado.
	2	Abate a devolução no mês da venda de origem — a devolução só entra quando a nota de saída correspondente é do mesmo mês e ano.
P_TIPORESULTADO	0	Padrão. Todos os resultados.
	1	Somente resultado zero ou positivo.
	2	Somente resultado negativo — atalho para achar venda com margem negativa.

Há ainda P_PAIS, que separa mercado interno de externo: 1 traz apenas clientes do Brasil, 2 apenas do exterior, e a ausência traz os dois. Esse parâmetro não existe na tela do ERP — só é alcançável pela API.

Com o tipo e os filtros definidos, monte o corpo com "method": "GET", "objectType": "PROCEDURE RESULT" e os valores em params.

Exemplo — faturamento por produto no mês

{
    "method": "GET",
    "objectType": "PROCEDURE RESULT",
    "objectName": "PRC_RES_ANALISEVENDAS2",
    "params": [
        { "name": "P_TIPOANALISE",  "value": 8 },
        { "name": "P_FL_COD",       "value": 1 },
        { "name": "P_TIPOEMPRESA",  "value": 0 },
        { "name": "P_ME_ENT1",      "value": "2026-07-01" },
        { "name": "P_ME_ENT2",      "value": "2026-07-31" }
    ],
    "fields": [
        "PD_COD", "PD_DES", "ME_QTDEST", "ME_VLRPRODUTO", "ME_VLRESULTADO", "ME_PCTRESULTADO"
    ],
    "orderBy": [ "ME_VLRPRODUTO DESC" ],
    "limit": 20
}

Valores ilustrativos. Os códigos de empresa, produto e período acima são exemplos. Use os cadastros da sua instância. A lista completa e autoritativa de parâmetros e colunas está no dicionário oficial.

Exemplo — margem negativa por cliente, com devoluções abatidas

{
    "method": "GET",
    "objectType": "PROCEDURE RESULT",
    "objectName": "PRC_RES_ANALISEVENDAS2",
    "params": [
        { "name": "P_TIPOANALISE",    "value": 6 }   // Cliente
        ,{ "name": "P_FL_COD",         "value": 1 }
        ,{ "name": "P_TIPOEMPRESA",    "value": 1 }  // matriz e filiais
        ,{ "name": "P_ME_ENT1",        "value": "2026-01-01" }
        ,{ "name": "P_ME_ENT2",        "value": "2026-06-30" }
        ,{ "name": "P_ABATEDEVOLUCAO", "value": 1 }  // abate devoluções do período
        ,{ "name": "P_TIPORESULTADO",  "value": 2 }  // somente resultado negativo
    ],
    "fields": [ "CF_COD", "CF_RSOCIAL", "ME_VLRPRODUTO", "ME_CUSTO", "ME_VLRESULTADO" ],
    "orderBy": [ "ME_VLRESULTADO ASC" ]
}

Boas práticas de consulta

• Peça só o que vai usar. São mais de 90 colunas; fields (ou fieldsIgnore) reduz a resposta e o tempo de transferência de forma expressiva.
• Informe limit explicitamente e pagine com offset. Consulta sem limite declarado fica sujeita ao limite padrão do servidor, e um painel pode exibir uma amostra achando que é o total.
• Deixe o corte no servidor. where, groupBy, having e orderBy se aplicam sobre o resultado da procedure — use-os em vez de trazer tudo e reduzir no cliente.
• Não use % em calculatedFields. A requisição falha com 400. Para testar a presença de um trecho de texto, use LOCATE(CAMPO, 'texto'). Em where, o LIKE com % funciona normalmente.
• Prefira o agrupamento da procedure ao groupBy da consulta. Escolher o P_TIPOANALISE certo faz a soma acontecer antes, sobre menos linhas.

PRC_RES_BIANALISEVENDAS é um atalho para carga de painel. Ela percorre todas as empresas ativas e, para cada uma, executa a análise no grão de item de nota fiscal (equivalente ao tipo 18), no período dos últimos P_QTDDIAS dias até hoje. Não recebe empresa, nem datas, nem filtros.

Parâmetro	Padrão	Descrição
P_BONIFICACAO	0	Mesmo significado do Passo 3: 0 exclui bonificações, 1 inclui.
P_ABATEDEVOLUCAO	0	Mesmo significado do Passo 3.
P_QTDDIAS	365	Quantos dias retroagir a partir de hoje.

Dimensões de tempo que ela acrescenta

Além das colunas da análise, o retorno traz cinco campos calculados que poupam trabalho na montagem de séries:

Coluna	Conteúdo
MES_NUMERO	Mês com dois dígitos: 01 a 12.
MES_NOME	Número e nome do mês, já ordenável como texto: 01-JANEIRO.
TIPO_MES	Posição relativa ao mês corrente: mês atual, meses anteriores ou meses posteriores.
TIPO_ANO	Posição relativa ao ano corrente: ano atual, anos anteriores ou anos posteriores.
MESES	Distância em meses até hoje. É negativa para o passado: o mês anterior vale -1. Útil para eixo relativo (“últimos 12 meses”).

Exemplo — carga dos últimos 12 meses

{
    "method": "GET",
    "objectType": "PROCEDURE RESULT",
    "objectName": "PRC_RES_BIANALISEVENDAS",
    "params": [
        { "name": "P_BONIFICACAO",    "value": 0 }
        ,{ "name": "P_ABATEDEVOLUCAO", "value": 1 }
        ,{ "name": "P_QTDDIAS",        "value": 365 }
    ]
}

O retorno mistura três famílias de valores: faturamento, deduções (impostos, custos, comissões) e resultado. Confundi-las produz painel errado com número plausível.

Coluna	Significado
ME_TOT_BRUTO	Valor bruto do item, antes de desconto.
ME_VDSC	Desconto concedido.
ME_VLRPRODUTO	Valor do produto já com desconto. É o denominador do percentual de resultado e a base natural de um gráfico de faturamento.
ME_VALOR	Valor do item na nota.
ME_QTDCONV / ME_QTDEST	Quantidade na unidade de venda e na unidade de estoque. Para somar quantidade entre produtos, use a de estoque.
ME_CUSTO	Custo do item vendido, na quantidade da linha.
ME_CUSTOUNIT	Custo unitário. Preenchido apenas nos tipos 3 e 18.
ME_VLRESULTADO	Resultado líquido do item — ver fórmula abaixo.
ME_PCTRESULTADO	Resultado dividido pelo valor do produto, em percentual.

Como o resultado é apurado

O resultado é o valor do produto menos todas as deduções apuradas no processamento:

ME_VLRESULTADO = ME_VLRPRODUTO
               - custo do item
               - ICMS - ICMS ST - PIS - COFINS - CSLL - IR - ISS
               - frete
               - comissões (representante, operacional, gerência, supervisão, terceiros)
               - custo financeiro - custo fixo - contrato especial
               - bonificação

ME_PCTRESULTADO = ME_VLRESULTADO / ME_VLRPRODUTO * 100

Cada parcela também vem como coluna própria (ME_TOTICMS, ME_VPIS, ME_VCOFINS, ME_FRETE, VD_VALCOM, ME_CUSTOFIN, ME_CUSTOFIXO, entre outras), o que permite montar um gráfico de composição da margem sem recalcular nada.

Sinais e devoluções

• A coluna CF_TIPO indica o sentido: C é saída (venda), F é devolução.
• Nas devoluções os valores vêm com sinal negativo — valor, custo, impostos e resultado. Basta somar; não inverta o sinal por conta própria.
• Como devoluções só entram quando P_ABATEDEVOLUCAO é 1 ou 2, um painel de faturamento líquido precisa desse parâmetro explícito.

Formatação

• Datas e timestamps em ISO-8601.
• Números com ponto decimal, sem separador de milhar e sem símbolo de moeda.
• Colunas de valor com até 6 casas decimais — arredonde apenas na exibição, nunca antes de somar.