Unidades e pegadinhas

As dez confusões mais comuns ao ler os números do OpenThor — e a frase que evita cada uma. Nenhuma delas é bug: são convenções do Winthor e do dado vivo que valem a pena conhecer de antemão.

1. Fração ou percentual?

Nem todo campo de porcentagem usa a mesma escala. A margem bruta das vendas agregadas vem como fração de 0 a 1; a margem 8128 e o atingimento de metas vêm na escala 0–100.

Como não errar: antes de multiplicar por 100, confira a família — nas vendas agregadas, 0,23 já é 23%. As três margens estão explicadas em As três margens.

O catálogo de pegadinhas

2. O período corrente é parcial — e a série pula meses zerados

O mês em andamento sempre parece “queda”, porque ainda não acabou. E get_monthly_sales_trend não emite linha de R$ 0: um mês sem venda some do gráfico em vez de aparecer zerado.

Como não errar: compare só períodos fechados; mês ausente na série = período sem venda, não dado faltando.

3. R$ 0 de manhã cedo é honesto

“Quanto vendi hoje?” antes de o faturamento do dia processar pode responder R$ 0 — e o zero é real, não erro. O OpenThor nunca inventa número para preencher o vazio.

Como não errar: pergunte de novo mais tarde — por exemplo com get_sales_summary — e confira o data_as_of da resposta.

4. Números absolutos oscilam durante o dia

Cada resposta carrega data_as_of: quando aquele dado foi atualizado. Cancelamentos e lançamentos retroativos mexem nos valores absolutos ao longo do dia — a mesma pergunta de manhã e à tarde pode dar centavos (ou notas inteiras) de diferença.

Como não errar: conferências contra o Winthor sempre no mesmo dia, rotina e OpenThor lado a lado. Sobre o frescor: Resposta e metadados.

5. A sua chave estreita a visão em silêncio

Uma credencial recortada a um vendedor responde “o total da empresa” como o total daquele vendedor — por desenho, sem aviso de erro. O recorte é aplicado no servidor e nunca se alarga.

Como não errar: saiba o recorte da credencial que está respondendo. Veja Segurança e privacidade e o que a chave enxerga.

6. Redes têm vários códigos de cliente

A mesma rede de lojas costuma existir com vários códigos de cliente. O seu “maior cliente” pode estar fatiado em cinco linhas do ranking — e nenhuma delas aparecer no topo.

Como não errar: peça para agrupar pela razão social ou somar os códigos da rede antes de ranquear.

7. Inadimplente não é o mesmo que vencido

Título vencido de PIX/cartão costuma ser atraso de liquidação bancária, não calote. Por isso a inadimplência (delinquent_amount) exclui essas cobranças; o vencido (overdue_amount) não exclui.

Como não errar: use o vencido para a cobrança do dia (find_overdue_receivables) e a inadimplência para risco de calote (top_debtors).

8. Pedido não é venda

Pedido é o carrinho cheio; nota fiscal é o caixa passado. E o funil de pedidos não traz valor em R$ — mostra quantidade, status e idade.

Como não errar: para dinheiro, pergunte por vendas; para a fila, use get_order_pipeline — sempre com uma janela de datas, para não arrastar pedidos antigos esquecidos.

9. Estoque e catálogo olham a filial principal — e vazio significa “nunca”

As consultas de estoque e catálogo cobrem a filial principal configurada para a sua empresa. E em find_dead_stock, um days_since_sale vazio significa que o produto nunca vendeu — caso mais crítico, não menos.

Como não errar: trate o vazio como o pior caso, e confirme de qual filial se trata antes de comparar com a contagem física (get_stock_position).

10. “Todos” tem teto

As ferramentas devolvem no máximo um número fixo de linhas. “Todos os clientes” volta como os N mais relevantes segundo a ordenação — não como a lista completa.

Como não errar: refine em vez de paginar — filtre por vendedor, fornecedor ou cidade até a resposta caber no teto. Veja Refinar e continuar a conversa.