{"openapi":"3.0.3","info":{"title":"API Lojas Leve On","version":"1.0.0","description":"API oficial para integrações externas do marketplace Lojas Leve On. Integradores usam API Key, escopos mínimos, sandbox e webhooks assinados."},"x-lojas-leve-on-readiness":{"ready_for":["financeiro do vendedor","extrato do vendedor","pós-venda consultivo","leitura de produtos, pedidos, envio e NFe","criação e edição de produtos por API homologada","atualização de estoque por API homologada","sandbox sem persistência para testes","webhooks de mensagens e disputas","homologação assistida pela equipe Lojas Leve On"],"official_flow_today":["frete, etiqueta e rastreio via Melhor Envio e painel do pedido","NFe via NFE.io e fluxo fiscal oficial","cancelamento, reembolso e disputa por fluxos auditados internos"],"next_phase":["cancelamentos:write","webhooks operacionais automaticos para pedido criado, pedido pago, envio atualizado e NF-e autorizada"],"write_safety":["Idempotency-Key obrigatório","tentativas auditadas em integration_api_idempotency","escrita real liberada somente com escopo e INTEGRATION_API_WRITE_ENABLED=true"]},"servers":[{"url":"https://lojasleveon.com.br","description":"Ambiente atual"},{"url":"https://lojasleveon.com.br","description":"Produção"}],"tags":[{"name":"Financeiro","description":"Consultas financeiras por vendedor"},{"name":"Produtos","description":"Catálogo do vendedor: leitura, criação, edição e estoque por escopo homologado"},{"name":"Pedidos","description":"Leitura segura de pedidos do vendedor"},{"name":"Pós-venda","description":"Consulta segura de pedido e pós-venda"},{"name":"Envios","description":"Leitura de frete, rastreio e entrega"},{"name":"NF-e","description":"Leitura fiscal e envio de NF-e autorizada por ERP homologado"},{"name":"Sandbox","description":"Testes sem persistir dados reais"},{"name":"Webhooks","description":"Recebimento de eventos assinados e testes de assinatura"}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"X-API-Key"}},"schemas":{"ErrorResponse":{"type":"object","properties":{"ok":{"type":"boolean","example":false},"error":{"type":"string","example":"sem permissão para consultar este vendedor"}}},"IntegrationMeta":{"type":"object","properties":{"ok":{"type":"boolean","example":true},"integration_version":{"type":"integer","example":1}}},"FinanceiroResponse":{"allOf":[{"$ref":"#/components/schemas/IntegrationMeta"},{"type":"object","properties":{"data":{"type":"object","properties":{"seller_id":{"type":"integer","example":8},"saldo_total":{"type":"number","example":125.5},"movimentos":{"type":"array","items":{"type":"object"}}}}}}]},"ExtratoResponse":{"allOf":[{"$ref":"#/components/schemas/IntegrationMeta"},{"type":"object","properties":{"data":{"type":"object","properties":{"seller_id":{"type":"integer","example":8},"extrato":{"type":"array","items":{"type":"object"}}}}}}]},"PosVendaResponse":{"allOf":[{"$ref":"#/components/schemas/IntegrationMeta"},{"type":"object","properties":{"data":{"type":"object","properties":{"pedido":{"type":"object"},"posvenda":{"type":"object"},"recebiveis":{"type":"array","items":{"type":"object"}}}}}}]},"ProductWriteRequest":{"type":"object","required":["nome","descricao","preco","estoque","categoria_id","peso_kg","comprimento_cm","largura_cm","altura_cm"],"properties":{"nome":{"type":"string","example":"Fone Bluetooth Modelo X"},"descricao":{"type":"string","example":"Descrição completa do produto com informações reais para o comprador."},"preco":{"type":"number","example":68.9},"desconto":{"type":"number","example":0},"estoque":{"type":"integer","example":10},"categoria_id":{"type":"integer","example":12},"sku":{"type":"string","example":"ERP-123"},"marca":{"type":"string","example":"Marca"},"modelo":{"type":"string","example":"Modelo X"},"gtin":{"type":"string","example":"7890000000000"},"ncm":{"type":"string","example":"85183000"},"peso_kg":{"type":"number","example":0.45},"comprimento_cm":{"type":"number","example":20},"largura_cm":{"type":"number","example":20},"altura_cm":{"type":"number","example":10},"image_urls":{"type":"array","minItems":3,"maxItems":8,"items":{"type":"string"},"example":["https://cdn.exemplo.com/produto-1.jpg","https://cdn.exemplo.com/produto-2.jpg","https://cdn.exemplo.com/produto-3.jpg"]},"video_url":{"type":"string","nullable":true,"example":"https://cdn.exemplo.com/video.mp4"}}},"ProductPatchRequest":{"allOf":[{"$ref":"#/components/schemas/ProductWriteRequest"},{"type":"object","properties":{"remove_video":{"type":"boolean","example":false}}}]},"StockWriteRequest":{"type":"object","required":["estoque"],"properties":{"estoque":{"type":"integer","example":8}}},"NfeWriteRequest":{"type":"object","required":["numero","serie","chave"],"properties":{"numero":{"type":"string","example":"105"},"serie":{"type":"string","example":"1"},"chave":{"type":"string","example":"33260811562906000116550010000001051701854768"},"status":{"type":"string","example":"authorized","description":"Aceita authorized, autorizada, emitida ou approved."},"danfe_url":{"type":"string","example":"https://erp.exemplo.com/danfes/105.pdf"},"xml_url":{"type":"string","example":"https://erp.exemplo.com/xmls/105.xml"},"pdf_url":{"type":"string","example":"https://erp.exemplo.com/danfes/105.pdf"},"protocolo":{"type":"string","example":"333260000123456"},"emitida_em":{"type":"string","example":"2026-08-17T15:20:23-03:00"},"provider":{"type":"string","example":"erp_homologado"}}}}},"security":[{"ApiKeyAuth":[]}],"paths":{"/api/v1/integracoes/vendedores/{sellerId}/financeiro":{"get":{"tags":["Financeiro"],"summary":"Consulta financeiro do vendedor","security":[{"ApiKeyAuth":[]}],"parameters":[{"name":"sellerId","in":"path","required":true,"schema":{"type":"integer"}}],"responses":{"200":{"description":"Resumo financeiro","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FinanceiroResponse"}}}},"401":{"description":"API Key ausente ou inválida","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Sem permissão","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Limite de chamadas excedido","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/v1/integracoes/vendedores/{sellerId}/extrato":{"get":{"tags":["Financeiro"],"summary":"Consulta extrato do vendedor","security":[{"ApiKeyAuth":[]}],"parameters":[{"name":"sellerId","in":"path","required":true,"schema":{"type":"integer"}}],"responses":{"200":{"description":"Extrato financeiro","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExtratoResponse"}}}},"401":{"description":"API Key ausente ou inválida","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Sem permissão","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Limite de chamadas excedido","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/v1/integracoes/pedidos/{pedidoId}/posvenda":{"get":{"tags":["Pós-venda"],"summary":"Consulta pós-venda de um pedido","security":[{"ApiKeyAuth":[]}],"parameters":[{"name":"pedidoId","in":"path","required":true,"schema":{"type":"integer"}}],"responses":{"200":{"description":"Resumo de pós-venda","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PosVendaResponse"}}}},"401":{"description":"API Key ausente ou inválida","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Pedido não pertence ao vendedor da API Key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Pedido não encontrado","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Limite de chamadas excedido","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/v1/integracoes/vendedores/{sellerId}/produtos":{"get":{"tags":["Produtos"],"summary":"Lista produtos do vendedor","security":[{"ApiKeyAuth":[]}],"parameters":[{"name":"sellerId","in":"path","required":true,"schema":{"type":"integer"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":200,"default":100}},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","default":0}},{"name":"status","in":"query","required":false,"schema":{"type":"string"}},{"name":"updated_since","in":"query","required":false,"schema":{"type":"string","format":"date-time"}}],"responses":{"200":{"description":"Lista de produtos autorizados"},"403":{"description":"API Key sem permissão para o vendedor"}}},"post":{"tags":["Produtos"],"summary":"Cria produto por API externa","description":"Cria produto real para o vendedor vinculado. Exige escopo produtos:write, Idempotency-Key e ambiente com INTEGRATION_API_WRITE_ENABLED=true.","security":[{"ApiKeyAuth":[]}],"parameters":[{"name":"sellerId","in":"path","required":true,"schema":{"type":"integer"}},{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProductWriteRequest"}}}},"responses":{"201":{"description":"Produto criado"},"422":{"description":"Payload inválido"},"423":{"description":"Escrita real bloqueada por segurança no ambiente"},"428":{"description":"Idempotency-Key obrigatório"}}}},"/api/v1/integracoes/categorias":{"get":{"tags":["Produtos"],"summary":"Lista categorias para mapeamento de produto","description":"Retorna categorias do marketplace para o integrador mapear o ERP antes de criar ou editar produto. Exige escopo produtos:read.","security":[{"ApiKeyAuth":[]}],"parameters":[{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":500,"default":300}},{"name":"q","in":"query","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"Lista de categorias"},"401":{"description":"API Key ausente ou inválida"},"403":{"description":"Escopo produtos:read ausente"}}}},"/api/v1/integracoes/vendedores/{sellerId}/produtos/{produtoId}":{"get":{"tags":["Produtos"],"summary":"Consulta produto do vendedor","security":[{"ApiKeyAuth":[]}],"parameters":[{"name":"sellerId","in":"path","required":true,"schema":{"type":"integer"}},{"name":"produtoId","in":"path","required":true,"schema":{"type":"integer"}}],"responses":{"200":{"description":"Produto autorizado"},"404":{"description":"Produto não encontrado"}}},"patch":{"tags":["Produtos"],"summary":"Edita produto por API externa","description":"Atualiza cadastro, preço, estoque, medidas, imagens por URL e vídeo por URL. Exige escopo produtos:write, Idempotency-Key e ambiente com escrita liberada.","security":[{"ApiKeyAuth":[]}],"parameters":[{"name":"sellerId","in":"path","required":true,"schema":{"type":"integer"}},{"name":"produtoId","in":"path","required":true,"schema":{"type":"integer"}},{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProductPatchRequest"}}}},"responses":{"200":{"description":"Produto atualizado"},"404":{"description":"Produto não encontrado"},"422":{"description":"Payload inválido"},"423":{"description":"Escrita real bloqueada por segurança no ambiente"},"428":{"description":"Idempotency-Key obrigatório"}}}},"/api/v1/integracoes/vendedores/{sellerId}/pedidos":{"get":{"tags":["Pedidos"],"summary":"Lista pedidos do vendedor","security":[{"ApiKeyAuth":[]}],"parameters":[{"name":"sellerId","in":"path","required":true,"schema":{"type":"integer"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":200,"default":100}},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","default":0}},{"name":"status","in":"query","required":false,"schema":{"type":"string"}},{"name":"updated_since","in":"query","required":false,"schema":{"type":"string","format":"date-time"}}],"responses":{"200":{"description":"Lista de pedidos autorizados"},"403":{"description":"API Key sem permissão para o vendedor"}}}},"/api/v1/integracoes/vendedores/{sellerId}/pedidos/{pedidoId}":{"get":{"tags":["Pedidos"],"summary":"Consulta pedido do vendedor","security":[{"ApiKeyAuth":[]}],"parameters":[{"name":"sellerId","in":"path","required":true,"schema":{"type":"integer"}},{"name":"pedidoId","in":"path","required":true,"schema":{"type":"integer"}}],"responses":{"200":{"description":"Pedido autorizado com itens"},"404":{"description":"Pedido não encontrado"}}}},"/api/v1/integracoes/pedidos/{pedidoId}/envio":{"get":{"tags":["Envios"],"summary":"Consulta envio e rastreio de pedido","security":[{"ApiKeyAuth":[]}],"parameters":[{"name":"pedidoId","in":"path","required":true,"schema":{"type":"integer"}}],"responses":{"200":{"description":"Envio autorizado"},"404":{"description":"Pedido não encontrado para esta API Key"}}}},"/api/v1/integracoes/pedidos/{pedidoId}/nfe":{"get":{"tags":["NF-e"],"summary":"Consulta NF-e de pedido","security":[{"ApiKeyAuth":[]}],"parameters":[{"name":"pedidoId","in":"path","required":true,"schema":{"type":"integer"}}],"responses":{"200":{"description":"NF-e autorizada para consulta"},"404":{"description":"Pedido não encontrado para esta API Key"}}},"post":{"tags":["NF-e"],"summary":"Envia NF-e autorizada pelo ERP","description":"Use quando o ERP homologado emitir a nota fiscal fora do marketplace e precisar devolver número, série, chave e links HTTPS da DANFE/XML. Requer escopo nfe:write, pedido do vendedor da API Key, Idempotency-Key e escrita real liberada.","security":[{"ApiKeyAuth":[]}],"parameters":[{"name":"pedidoId","in":"path","required":true,"schema":{"type":"integer"}},{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/NfeWriteRequest"}}}},"responses":{"200":{"description":"NF-e gravada e webhook nfe.authorized enfileirado"},"400":{"description":"Payload inválido"},"403":{"description":"Sem escopo nfe:write ou pedido de outro vendedor"},"423":{"description":"Escrita real da API externa bloqueada"}}}},"/api/v1/integracoes/sandbox/status":{"get":{"tags":["Sandbox"],"summary":"Consulta status do sandbox","security":[{"ApiKeyAuth":[]}],"responses":{"200":{"description":"Sandbox disponível"}}}},"/api/v1/integracoes/sandbox/produtos/validar":{"post":{"tags":["Sandbox"],"summary":"Valida payload de produto sem salvar","security":[{"ApiKeyAuth":[]}],"responses":{"200":{"description":"Produto sandbox validado sem persistência"}}}},"/api/v1/integracoes/sandbox/pedidos/simular":{"post":{"tags":["Sandbox"],"summary":"Simula pedido sem salvar","description":"Aceita Idempotency-Key para testar fluxo do integrador sem gravar pedido real.","security":[{"ApiKeyAuth":[]}],"responses":{"200":{"description":"Pedido sandbox simulado sem persistência"}}}},"/api/v1/integracoes/sandbox/webhooks/test":{"post":{"tags":["Sandbox"],"summary":"Enfileira webhook sandbox","security":[{"ApiKeyAuth":[]}],"responses":{"200":{"description":"Webhook sandbox enfileirado"}}}},"/api/v1/integracoes/sandbox/webhooks/assinatura":{"post":{"tags":["Sandbox"],"summary":"Simula assinatura HMAC de webhook","description":"Gera raw_body, headers e X-Llon-Signature para o integrador validar HMAC sem receber uma entrega real.","security":[{"ApiKeyAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["secret"],"properties":{"secret":{"type":"string","example":"secret_copiado_ao_criar_webhook"},"event":{"type":"string","example":"pedido.paid"},"payload":{"type":"object"}}}}}},"responses":{"200":{"description":"Assinatura gerada para comparação segura"},"400":{"description":"Secret ausente ou inválido"}}}},"/api/v1/integracoes/vendedores/{sellerId}/produtos/{produtoId}/estoque":{"patch":{"tags":["Produtos"],"summary":"Atualiza estoque por API externa","description":"Atualiza somente o estoque do produto. Exige escopo estoque:write, Idempotency-Key e ambiente com escrita liberada.","security":[{"ApiKeyAuth":[]}],"parameters":[{"name":"sellerId","in":"path","required":true,"schema":{"type":"integer"}},{"name":"produtoId","in":"path","required":true,"schema":{"type":"integer"}},{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/StockWriteRequest"}}}},"responses":{"200":{"description":"Estoque atualizado"},"404":{"description":"Produto não encontrado"},"423":{"description":"Escrita real bloqueada por segurança no ambiente"},"428":{"description":"Idempotency-Key obrigatório"}}}}}}