Leve a sua margem para onde você trabalha

Visão geral

A API é para você (ou a ferramenta que você usa) puxar os seus dados de margem e fazer o que quiser com eles: um dashboard, uma planilha viva, um alerta, ou uma conversa com uma IA. Ela é somente leitura — nunca altera nada na sua conta.

Ela cobre bem estes cenários:

• Levar o DRE e a margem por produto/pedido para um data warehouse, Power BI, Looker ou Google Sheets.
• Montar um relatório recorrente ou um alerta (“me avise quando um produto vender no prejuízo”).
• Perguntar em linguagem natural (“meus produtos de margem negativa em junho”) direto do seu Claude ou ChatGPT, via MCP.

Comece em 3 passos

curl -H "Authorization: Bearer sk_live_SUA_CHAVE" \
  "https://www.lucras.com.br/api/v1/financials?from=2026-06-01&to=2026-06-30"

Autenticação

Envie a chave no header Authorization: Bearer sk_live_… em toda requisição. Cookies são ignorados de propósito — a chave é a única credencial, então ela nunca é confundida com uma sessão de navegador.

Authorization: Bearer sk_live_SUA_CHAVE

Cada chave é amarrada à sua organização. Se uma chave vazar, revogue e gere outra — isso não afeta as demais.

Escopos

Cada chave carrega um ou mais escopos. Siga o menor privilégio: dê a cada integração só o que ela precisa. Um dashboard de produtos, por exemplo, só precisa de products:read.

Endpoints

Base: https://www.lucras.com.br/api/v1. Filtros comuns: from, to (datas de São Paulo, YYYY-MM-DD) e company (uuid, opcional — filtra por CNPJ). Produtos e pedidos aceitam ainda channel, cursor e page_size (≤ 100).

GET /financials — resultado financeiro (DRE), mensal

O mesmo P&L da tela DRE, agregado por mês. Ideal para acompanhar o resultado do negócio.

{ "period": {"from":"2026-06-01","to":"2026-06-30","granularity":"month"}, "currency":"BRL",
  "revenue":1405447.31, "commission":202589.09, "shipping":49749.21,
  "costs":1048749.51,        // custo dos produtos + impostos (combinados)
  "ads":22490.55, "fixed_costs":30000, "profit":37030.17, "margin_pct":2.63,
  "months":[ /* um objeto por mês, mesmos campos */ ] }

GET /products/margins — por produto (paginado)

Margem de cada produto no período, já com a classificação e a confiança (veja abaixo).

{ "data":[ {"product_id":"…","sku":"VIT-0011","name":"Vinho …",
   "units":3,"revenue":189.70,"costs":191.81,"profit":-2.11,"margin_pct":-1.11,
   "classification":{"key":"maximizadores","label":"Maximizadores"},  // rótulo da tela
   "confidence":"alta"} ],   // alta | media | baixa
  "next_cursor":"eyJ2Ijox…" }   // repita com ?cursor=… até vir null

GET /orders/margins — por pedido (janela ≤ 92 dias, paginado)

Margem pedido a pedido, com o status de entrega e a confiança do dado.

{ "data":[ {"order_id":"…","placed_at":"2026-06-25T03:01:08.000Z","channel":"ml",
   "revenue":137.52,"commission":19.20,"shipping":7.50,
   "costs":132.65,          // imposto + custo (combinados)
   "profit":-21.83,"margin_pct":-15.87,"fulfillment":"entregue",
   "confidence":"alta"} ],   // "baixa" = pedido a revisar (custo/imposto faltando)
  "next_cursor":null }

Entendendo os campos

Alguns campos merecem uma palavra — eles carregam leituras nossas, não só números crus, e é aí que está boa parte do valor:

Você recebe o rótulo e a confiança prontos para usar. O que não abrimos é o método por trás deles — as faixas de margem, o cálculo de giro, a fórmula de confiança — nem a divisão de imposto vs. custo, alíquotas ou dados do comprador. Em resumo: entregamos o resultado, não o como.

O que você pode fazer com os dados

Algumas receitas prontas para copiar. Cada uma mostra o mesmo objetivo por dois caminhos: pela API (código/planilha) e por pergunta (MCP no seu Claude/ChatGPT).

GET https://www.lucras.com.br/api/v1/products/margins?from=2026-06-01&to=2026-06-30
→ do seu lado, filtre por margin_pct < 0 e ordene do pior para o melhor.

GET https://www.lucras.com.br/api/v1/products/margins?from=2026-06-01&to=2026-06-30
→ filtre por classification.key === "maximizadores".
  São seus campeões: não deixe faltar estoque nem baixe preço à toa.

GET https://www.lucras.com.br/api/v1/products/margins?from=2026-06-01&to=2026-06-30
→ filtre por confidence === "baixa" e revenue alto.
  São os que mais valem a pena arrumar (custo/imposto faltando).

GET https://www.lucras.com.br/api/v1/financials?from=2026-01-01&to=2026-12-31
→ um objeto por mês em "months". No Sheets, puxe via Apps Script;
  no Excel, via Power Query. Use ?company=<uuid> para separar por CNPJ.

GET https://www.lucras.com.br/api/v1/orders/margins?from=<ontem>&to=<ontem>
→ pagine com next_cursor, filtre margin_pct < 0
  e mande a lista para o seu canal.

Conectar no Claude / ChatGPT (MCP)

O MCP (Model Context Protocol) deixa o seu assistente de IA consultar os seus números direto, com segurança. Há duas formas — comece pela remota, que é a mais simples.

Forma A — Remota, por URL (recomendada)

Nada para instalar. Você adiciona um único endereço e autoriza com login — sem colar chave nenhuma.

No Claude (Desktop ou web, plano pago):

• Abra Configurações → Connectors → Adicionar conector personalizado.
• Cole a URL https://www.lucras.com.br/api/mcp e salve.
• Na primeira vez, o Claude abre uma janela pedindo para você entrar no Lucras e autorizar (é preciso ser Admin). Clique em Autorizar — e pronto.

No ChatGPT (Plus/Pro/Business/Enterprise):

• Vá em Configurações → Connectors → Adicionar (ou, dentro de um GPT, na seção de conectores/MCP).
• Cole a mesma URL https://www.lucras.com.br/api/mcp e conclua a autorização no Lucras.

Forma B — Local, na sua máquina (stdio)

Para clientes que rodam o MCP localmente (Claude Desktop, Claude Code, n8n, scripts). Usa o servidor incluso mcp/lucras-mcp.mjs (Node 18+, sem dependências) e uma chave sk_live_….

Claude Desktop — edite o arquivo claude_desktop_config.json (menu Configurações → Desenvolvedor → Editar config) e adicione:

{
  "mcpServers": {
    "lucras": {
      "command": "node",
      "args": ["/caminho/completo/para/mcp/lucras-mcp.mjs"],
      "env": { "LUCRAS_API_KEY": "sk_live_SUA_CHAVE" }
    }
  }
}

Reinicie o Claude. As tools get_financials, get_product_margins e get_order_margins passam a aparecer.

Se preferir não baixar o arquivo, qualquer cliente stdio pode falar com o endpoint remoto via mcp-remote (faz a ponte e cuida do OAuth):

{
  "mcpServers": {
    "lucras": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://www.lucras.com.br/api/mcp"]
    }
  }
}

As tools disponíveis

São três, espelhando os endpoints — mesmos filtros (from, to, company, channel, cursor, page_size):

• get_financials — resultado financeiro (DRE) do período.
• get_product_margins — margem por produto, com classificação e confiança.
• get_order_margins — margem por pedido.

Rate limit e cotas

Há limites por chave — protegem a plataforma e você de um loop acidental. Na prática, um uso normal (algumas sincronizações por dia) fica bem abaixo deles.

Toda resposta traz X-RateLimit-Limit e X-RateLimit-Remaining. Ao estourar, você recebe 429 com Retry-After (em segundos): espere esse tempo e tente de novo.

Sob carga muito alta, a plataforma pode responder 503 (ela degrada em vez de cair) — basta repetir após o Retry-After.

Estes são os limites atuais, calibrados de forma conservadora para esta fase — eles sobem conforme a plataforma escala. Precisa de mais agora? Fale com o suporte.

Boas práticas

• Pagine sempre: siga next_cursor até vir null. Não há offset nem total — é de propósito, para evitar varredura pesada.
• Não fique fazendo polling: os números fecham por dia; puxar de minuto em minuto é desperdício. Atualize algumas vezes ao dia e cacheie do seu lado.
• Sincronização incremental: guarde o que já puxou e re-puxe só o período que ainda pode mudar (normalmente o mês corrente).
• Respeite o 429: ao recebê-lo, espere o Retry-After (backoff) — não martele.
• Uma chave por integração, com o menor escopo. Se vazar, revogue e gere outra (não afeta as demais).
• Datas são de São Paulo (YYYY-MM-DD). Não converta para UTC — a API já entende o dia de Brasília.
• Se alimentar um LLM, trate name e sku como dado (texto do vendedor), não como instrução.

Erros

Erros vêm sempre no mesmo formato: { "error": { "code": "...", "message": "..." } }.

• 401 unauthorized — chave ausente, inválida ou revogada.
• 403 out_of_scope — a chave não tem o escopo daquele endpoint.
• 403 company_forbidden — o company informado não é da sua organização.
• 400 range_too_large / invalid_cursor / invalid_date — filtro fora das regras (veja as janelas máximas acima).
• 429 rate_limited / quota_exceeded — respeite o Retry-After.
• 503 overloaded — carga alta na plataforma; repita após o Retry-After.