openthorDocumentação

API REST /v1

A API REST serve os mesmos dados das ferramentas MCP, para quem constrói planilhas, integrações ou scripts — hoje são 65 endpoints, todos somente-leitura (GET). Comece por Autenticação e Sintaxe de consulta.

Nota

Base: https://api.openthor.dev · autenticação por chave ot_live_… no cabeçalho Authorization: Bearer · respostas em JSON com o envelope { data, meta }.

Vendas · 40

GET /v1/invoices

Notas fiscais de saída, uma a uma, com valor, custo e margem.

GET /v1/invoice-items

Linhas (itens) de cada nota, com receita, custo e margem por produto.

GET /v1/find/invoices-by-number

Busca notas fiscais pelo número (NUMNOTA), em lote, com itens e códigos de barras; reporta não encontrados.

GET /v1/invoice-items-bi

Linhas de venda em massa (RCA, supervisor, fornecedor, produto) para carga em lote de um motor analítico associativo no navegador — recurso interno dedicado, sem margem, não vinculado a chaves de vendas existentes.

GET /v1/agg/sales/by-rep

Vendas agregadas por vendedor (RCA).

GET /v1/agg/sales/by-supervisor

Vendas agregadas por supervisor (equipe).

GET /v1/reps

Cadastro de vendedores (RCAs), com supervisor e status.

GET /v1/agg/sales/summary

Resumo de vendas do período em uma linha — faturado, líquido de devoluções, notas, clientes e ticket médio.

GET /v1/agg/sales/by-month

Série temporal de vendas por mês, semana ou dia.

GET /v1/agg/sales/by-supplier

Vendas agregadas por fornecedor (indústria).

GET /v1/agg/devolucao/by-customer

Devoluções de clientes agregadas por cliente — inclui valor, quantidade e nº de NFs devolvidas.

GET /v1/agg/devolucao/by-product

Devoluções de clientes agregadas por produto — inclui valor, quantidade e nº de NFs devolvidas.

GET /v1/agg/devolucao/by-motivo

Devoluções de clientes agregadas por motivo (pedido em desacordo, produto avariado, etc.) — o motivo separa falha comercial de falha logística.

GET /v1/agg/sales/by-customer

Vendas agregadas por cliente.

GET /v1/agg/sales/by-product

Vendas agregadas por produto.

GET /v1/agg/sales/by-category

Vendas agregadas por categoria de produto.

GET /v1/agg/sales/by-line

Vendas agregadas por linha de produto (a categoria real do fornecedor; exclui FORA DE LINHA).

GET /v1/agg/sales/line-summary

Total de vendas por linha de produto (agregado único, sem FORA DE LINHA) — a linha Total do sell-through.

GET /v1/agg/campaign/sell-out-by-rep-line

Caixas de venda (exclui bonificação) por RCA × linha de produto, para apuração de campanha.

GET /v1/agg/campaign/positivacao-by-rep

Positivação (clientes distintos) e caixas de venda por RCA, para apuração de campanha (exclui bonificação).

GET /v1/agg/campaign/positivacao-summary

Positivação distinta total (empresa/segmento) num agregado único — não somável entre RCAs.

GET /v1/agg/sales/by-praca

Vendas agregadas por praça (praça do cliente).

GET /v1/agg/sales/by-city

Vendas agregadas por cidade (município do cliente).

GET /v1/agg/sales/by-state

Vendas agregadas por estado (UF do cliente).

GET /v1/agg/sales/by-branch

Vendas agregadas por filial.

GET /v1/products

Cadastro de produtos vendáveis.

GET /v1/product-cadastro

Cadastro completo de produtos, incluindo bloqueados e fora de linha (auditoria).

GET /v1/product-packaging

Embalagens por produto: descrição, unidade, fator de conversão e código de barras.

GET /v1/tax-situations

Cadastro de situações tributárias de ICMS (CST, CFOP, alíquotas de ICMS/ST/FCP, redução de base).

GET /v1/product-tax

Tributação de ICMS de um produto por UF de destino (CST, CFOP, ICMS, ST, FCP, PIS/COFINS).

GET /v1/product-tax-reform

Tratamento da reforma tributária (CBS/IBS/IS) de um produto, resolvido pelo NCM.

GET /v1/product-cest

Classificação fiscal de um produto: CEST, NCM e descrição do CEST.

GET /v1/tax-figures

Cadastro de figuras tributárias de entrada (crédito presumido, IPI, ST, IVA, reduções).

GET /v1/tax-entries

Figura tributária de entrada por NCM, UF de origem e tipo de fornecedor.

GET /v1/coverage-history

Histórico trimestral de cobertura por fornecedor e município — para achar onde a cobertura caiu vs o trimestre anterior.

GET /v1/margin/catalog

Margem de cadastro (rotina 8133) por produto — estado atual do catálogo de preços.

GET /v1/agg/margin/catalog/by-supplier

Qualidade da margem de cadastro agregada por fornecedor.

GET /v1/agg/margin/realized/by-supplier

Margem realizada líquida (rotina 8128) por fornecedor, com e sem verba.

GET /v1/agg/margin/realized/by-product

Margem realizada líquida (rotina 8128) agregada por produto.

GET /v1/margin/realized/below-threshold

Produtos com margem realizada líquida abaixo de um limite — o caça-prejuízo.

Clientes · 11

GET /v1/agg/customers/active-base-trend

Série temporal da base ativa de clientes.

GET /v1/customers

Cadastro de clientes.

GET /v1/customers/portfolio

Carteira oficial cliente × vendedor (união da rotina 8066).

GET /v1/customer-metrics

Métricas por cliente — recência, frequência, valor (RFM) e cadência de compra.

GET /v1/agg/customers/portfolio-by-rep

Tamanho da carteira por vendedor.

GET /v1/agg/customers/positivacao-by-rep

Positivação do mês corrente por vendedor.

GET /v1/agg/customers/positivacao-by-supervisor

Positivação do mês corrente por supervisor.

GET /v1/agg/customers/positivacao-summary

Positivação do mês corrente da empresa (uma linha).

GET /v1/agg/customers/coverage-by-city

Cobertura de clientes por município.

GET /v1/customer-profile

Ficha 360 do cliente — atividade dos últimos 90 dias.

GET /v1/agg/customers/churn-by-rep

Carteira em risco (churn) e valor em risco por vendedor.

Pedidos · 3

GET /v1/orders

Pedidos de venda, um a um, com status, motivo e idade.

GET /v1/agg/orders/pipeline

Funil de pedidos por status (faturado, bloqueado, pendente, cancelado).

GET /v1/agg/orders/by-rep

Pedidos agregados por vendedor.

Trade · 3

GET /v1/agg/trade/mix-penetration

Penetração do mix de um fornecedor, cliente a cliente.

GET /v1/agg/trade/penetration-scorecard

Scorecard de penetração de portfólio por fornecedor.

GET /v1/agg/trade/white-space

Lacunas produto × cliente de um fornecedor (white space) — quem ainda não compra o quê.

Financeiro · 3

GET /v1/receivables

Títulos a receber, um a um, com vencimento e dias de atraso.

GET /v1/agg/receivables/by-customer

Contas a receber agregadas por cliente — em aberto, vencido e inadimplente.

GET /v1/agg/receivables/by-rep

Contas a receber agregadas por vendedor (RCA) — em aberto, vencido, inadimplente e comportamento de pagamento.

Estoque · 1

GET /v1/stock

Posição de estoque atual por produto (retrato do momento, sem período).

Metas · 4

GET /v1/goals

Metas por período e nível (empresa, supervisor, RCA, RCA×fornecedor).

GET /v1/agg/goals/by-supplier

Meta × realizado agregado por fornecedor.

GET /v1/goals/supervisor-supplier-history

Histórico mensal de atingimento de meta por supervisor × fornecedor — para achar quedas de desempenho por equipe.

GET /v1/agg/goals/mine

Meta × realizado da PRÓPRIA marca do fornecedor (venda + positivação), murada.