{"openapi":"3.1.0","info":{"title":"Lucras API","version":"1.0.0","description":"API de leitura dos SEUS números de margem (resultado) para você fazer a SUA análise. Expõe resultados, NÃO o método de cálculo. Não fornece: detalhamento de imposto vs custo, origem do custo, classificações (ex.: 'produto estrela'/quadrante/confiança), nem dados do comprador."},"servers":[{"url":"https://www.lucras.com.br/api/v1"}],"security":[{"bearerAuth":[]}],"paths":{"/financials":{"get":{"summary":"Resultado financeiro (DRE) do período — granularidade mensal.","parameters":[{"name":"from","in":"query","schema":{"type":"string","format":"date"},"description":"Data inicial (São Paulo, YYYY-MM-DD). Default: 30 dias atrás."},{"name":"to","in":"query","schema":{"type":"string","format":"date"},"description":"Data final (São Paulo, YYYY-MM-DD). Default: hoje."},{"name":"company","in":"query","schema":{"type":"string","format":"uuid"},"description":"Filtra por empresa (deve pertencer à sua organização)."}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Financials"}}}},"401":{"description":"Não autenticado (Bearer ausente/inválido).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Sem escopo, ou company de outra organização.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit / cota. Respeite Retry-After.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/products/margins":{"get":{"summary":"Margem por produto no período (keyset).","parameters":[{"name":"from","in":"query","schema":{"type":"string","format":"date"},"description":"Data inicial (São Paulo, YYYY-MM-DD). Default: 30 dias atrás."},{"name":"to","in":"query","schema":{"type":"string","format":"date"},"description":"Data final (São Paulo, YYYY-MM-DD). Default: hoje."},{"name":"company","in":"query","schema":{"type":"string","format":"uuid"},"description":"Filtra por empresa (deve pertencer à sua organização)."},{"name":"channel","in":"query","schema":{"type":"string","enum":["ml","shopee","amazon","magalu","tiktok","shein"]}},{"name":"cursor","in":"query","schema":{"type":"string"},"description":"Cursor de paginação (use next_cursor)."},{"name":"page_size","in":"query","schema":{"type":"integer","default":50,"maximum":100}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProductsPage"}}}},"401":{"description":"Não autenticado (Bearer ausente/inválido).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Sem escopo, ou company de outra organização.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit / cota. Respeite Retry-After.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/orders/margins":{"get":{"summary":"Margem por pedido (keyset, janela máx. 92 dias).","parameters":[{"name":"from","in":"query","schema":{"type":"string","format":"date"},"description":"Data inicial (São Paulo, YYYY-MM-DD). Default: 30 dias atrás."},{"name":"to","in":"query","schema":{"type":"string","format":"date"},"description":"Data final (São Paulo, YYYY-MM-DD). Default: hoje."},{"name":"company","in":"query","schema":{"type":"string","format":"uuid"},"description":"Filtra por empresa (deve pertencer à sua organização)."},{"name":"channel","in":"query","schema":{"type":"string","enum":["ml","shopee","amazon","magalu","tiktok","shein"]}},{"name":"cursor","in":"query","schema":{"type":"string"},"description":"Cursor de paginação (use next_cursor)."},{"name":"page_size","in":"query","schema":{"type":"integer","default":50,"maximum":100}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OrdersPage"}}}},"401":{"description":"Não autenticado (Bearer ausente/inválido).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Sem escopo, ou company de outra organização.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit / cota. Respeite Retry-After.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}},"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"sk_live_…"}},"schemas":{"Error":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}}}}},"Financials":{"type":"object","properties":{"period":{"type":"object","properties":{"from":{"type":"string"},"to":{"type":"string"},"granularity":{"type":"string"}}},"currency":{"type":"string"},"revenue":{"type":"number","description":"Receita (preço)."},"commission":{"type":"number","description":"Comissão do marketplace."},"shipping":{"type":"number","description":"Frete."},"costs":{"type":"number","description":"Custo do produto + impostos, COMBINADOS num único valor (intencional — não há detalhamento)."},"profit":{"type":"number","description":"Lucro."},"margin_pct":{"type":"number","description":"Margem % (profit/revenue)."},"ads":{"type":"number"},"fixed_costs":{"type":"number"},"months":{"type":"array","items":{"type":"object","properties":{"month":{"type":"string"},"revenue":{"type":"number","description":"Receita (preço)."},"commission":{"type":"number","description":"Comissão do marketplace."},"shipping":{"type":"number","description":"Frete."},"costs":{"type":"number","description":"Custo do produto + impostos, COMBINADOS num único valor (intencional — não há detalhamento)."},"profit":{"type":"number","description":"Lucro."},"margin_pct":{"type":"number","description":"Margem % (profit/revenue)."},"ads":{"type":"number"},"fixed_costs":{"type":"number"}}}}}},"ProductMargin":{"type":"object","properties":{"product_id":{"type":"string"},"sku":{"type":"string"},"name":{"type":"string"},"units":{"type":"integer"},"revenue":{"type":"number"},"costs":{"type":"number"},"profit":{"type":"number"},"margin_pct":{"type":"number"},"classification":{"type":["object","null"],"description":"Rótulo de quadrante atual do produto (o mesmo da tela Produtos). O método por trás dele não é exposto.","properties":{"key":{"type":"string","enum":["maximizadores","complementares","trafego","sangrando","otimizacao","cortar","aprendizado","pendente_dados"]},"label":{"type":"string"}}},"confidence":{"type":["string","null"],"enum":["alta","media","baixa",null],"description":"Nível de confiança do dado do produto."}}},"ProductsPage":{"type":"object","properties":{"period":{"type":"object","properties":{"from":{"type":"string"},"to":{"type":"string"}}},"currency":{"type":"string"},"data":{"type":"array","items":{"$ref":"#/components/schemas/ProductMargin"}},"next_cursor":{"type":["string","null"]}}},"OrderMargin":{"type":"object","properties":{"order_id":{"type":"string"},"placed_at":{"type":"string","format":"date-time"},"channel":{"type":"string"},"revenue":{"type":"number","description":"Receita (preço)."},"commission":{"type":"number","description":"Comissão do marketplace."},"shipping":{"type":"number","description":"Frete."},"costs":{"type":"number","description":"Custo do produto + impostos, COMBINADOS num único valor (intencional — não há detalhamento)."},"profit":{"type":"number","description":"Lucro."},"margin_pct":{"type":"number","description":"Margem % (profit/revenue)."},"fulfillment":{"type":["string","null"]},"confidence":{"type":"string","enum":["alta","baixa"],"description":"Confiança do dado: 'baixa' = pedido a revisar (custo/imposto faltando)."}}},"OrdersPage":{"type":"object","properties":{"period":{"type":"object","properties":{"from":{"type":"string"},"to":{"type":"string"}}},"currency":{"type":"string"},"data":{"type":"array","items":{"$ref":"#/components/schemas/OrderMargin"}},"next_cursor":{"type":["string","null"]}}}}}}