API Lojas Leve On

GET

Financeiro

Resumo financeiro e movimentos do vendedor autorizado.

/api/v1/integracoes/vendedores/{sellerId}/financeiro

GET

Extrato

Extrato financeiro para conciliação, contabilidade e BI.

/api/v1/integracoes/vendedores/{sellerId}/extrato

GET

Pós-venda

Consulta segura de pedido, recebíveis e dados de atendimento.

/api/v1/integracoes/pedidos/{pedidoId}/posvenda

Kit do integrador

Teste sem montar tudo do zero

Importe a coleção, preencha as variáveis e execute primeiro a pasta de sandbox. Isso confirma API Key, escopos, payload e assinatura HMAC antes de liberar dados reais.

API Lojas Leve On - Integracoes externas (V1)

Visao geral

A API externa da Lojas Leve On permite que outros sistemas se conectem ao marketplace de forma controlada. Ela foi pensada para ERPs, hubs de integracao, CRMs, ferramentas de BI, financeiro, contabilidade e automacoes internas de vendedores.

Base publica para integradores:

texthttps://lojasleveon.com.br

Sandbox publico para integradores:

texthttps://lojasleveon.com.br/api/v1/integracoes/sandbox

Esse endereco funciona como indice do sandbox. Para testar, envie X-API-Key com escopo sandbox:read. Sem a chave, a API responde erro de autenticacao.

Todas as respostas sao JSON, UTF-8, e as datas seguem ISO quando o dado vier da camada de integracao. A versao atual e v1.

Importante: sistemas externos nao devem usar rotas de sessao do site ou do app. A integracao correta usa API Key, escopos e webhooks.

Principios da integracao

Toda integracao deve seguir quatro regras:

Menor permissao possivel: cada sistema recebe apenas os escopos que realmente precisa.
Rastreabilidade: toda chamada fica associada a uma API Key, vendedor e sistema.
Idempotencia: eventos e futuras escritas precisam poder ser repetidos sem duplicar efeitos.
Privacidade: dados sensiveis do comprador, vendedor e pagamento so devem sair quando houver finalidade clara.

Nao integre usando usuario e senha do vendedor. Usuario e senha sao para pessoas. API Key e webhook sao para sistemas.

Entrega segura de credenciais

API Key e secret de webhook nao devem ser enviados por WhatsApp, e-mail aberto, print ou documento compartilhado sem controle.

O fluxo recomendado e:

O operador cria a API Key ou webhook no painel administrativo.
O sistema gera um link seguro temporario para o integrador.
O integrador abre o link, confirma a visualizacao e copia a credencial.
O link deixa de funcionar depois da primeira visualizacao ou quando expira.

Se o link expirar, for aberto pela pessoa errada ou a credencial for perdida, nao tente recuperar a chave antiga. Revogue a credencial e crie outra.

Depois de receber a credencial, o integrador deve guardar em cofre de senhas, variavel de ambiente ou secret manager do proprio sistema. Nunca coloque API Key em JavaScript publico, app sem protecao ou URL.

Ambientes

Publico para integradores

Use este endereco para homologacao externa e producao autorizada:

texthttps://lojasleveon.com.br

As rotas de sandbox ficam no mesmo dominio publico, mas nao gravam produto, pedido, frete, nota ou financeiro real:

textGET  https://lojasleveon.com.br/api/v1/integracoes/sandbox
https://lojasleveon.com.br/api/v1/integracoes/sandbox/status
POST https://lojasleveon.com.br/api/v1/integracoes/sandbox/produtos/validar
POST https://lojasleveon.com.br/api/v1/integracoes/sandbox/pedidos/simular
POST https://lojasleveon.com.br/api/v1/integracoes/sandbox/webhooks/assinatura

Rotas POST nao sao paginas para abrir no navegador. Elas devem ser testadas no Postman, cURL ou no sistema do integrador, sempre enviando X-API-Key.

Producao

Use rotas com dados reais somente depois da homologacao do integrador e liberacao dos escopos corretos.

O que ja esta liberado

Consultar financeiro do vendedor.
Consultar extrato do vendedor.
Consultar pos-venda de um pedido do vendedor.
Consultar produtos do vendedor.
Consultar pedidos do vendedor.
Consultar envio/rastreio de um pedido.
Consultar NF-e de um pedido.
Enviar NF-e autorizada por ERP homologado para um pedido do vendedor, com escopo nfe:write.
Criar e receber webhooks por vendedor.
Receber webhooks automaticos de pedido criado, pedido pago, envio atualizado e NF-e autorizada.
Testar webhook antes de ativar em producao.
Revogar webhooks quando uma integracao for encerrada.
Usar sandbox de API para validar produto, simular pedido e disparar webhook de teste sem gravar dados reais.
Criar produto por API externa homologada, com escopo produtos:write, Idempotency-Key e flag de escrita ativa.
Editar cadastro, preco, estoque, medidas, imagens por URL e video por URL de produto, com escopo produtos:write.
Atualizar somente estoque por endpoint dedicado, com escopo estoque:write.

Divisao de responsabilidades

O uso publico da API funciona assim:

Integrador externo

O integrador externo recebe uma API Key e usa somente as rotas de leitura e webhooks autorizados:

textGET /api/v1/integracoes/vendedores/{sellerId}/financeiro
GET /api/v1/integracoes/vendedores/{sellerId}/extrato
GET /api/v1/integracoes/pedidos/{pedidoId}/posvenda
GET /api/v1/integracoes/vendedores/{sellerId}/produtos
GET /api/v1/integracoes/vendedores/{sellerId}/produtos/{produtoId}
GET /api/v1/integracoes/vendedores/{sellerId}/pedidos
GET /api/v1/integracoes/vendedores/{sellerId}/pedidos/{pedidoId}
GET /api/v1/integracoes/pedidos/{pedidoId}/envio
GET /api/v1/integracoes/pedidos/{pedidoId}/nfe
POST /api/v1/integracoes/pedidos/{pedidoId}/nfe
GET /api/v1/integracoes/sandbox/status
POST /api/v1/integracoes/sandbox/produtos/validar
POST /api/v1/integracoes/sandbox/pedidos/simular
POST /api/v1/integracoes/sandbox/webhooks/test

Ele nao deve criar a propria chave, alterar escopos, revogar credenciais ou cadastrar webhook sem passar pela homologacao.

O que fica restrito

Nem tudo que existe no painel interno deve ser aberto para integradores. Administracao da plataforma, planos, permissoes, moderacao, repasses sensiveis, regras de reputacao, reembolso real, NFe operacional e etiqueta/logistica continuam em fluxos internos ou oficiais.

Para um integrador operar catalogo como um ERP, libere somente os escopos necessarios: leitura de produtos, escrita de produtos e/ou escrita de estoque. Para pedidos, fiscal, envio e financeiro, comece por leitura e webhooks.

Matriz de prontidao da V1

Pronto para integracao externa

Estas areas ja podem ser liberadas para parceiros homologados:

Financeiro do vendedor, com escopo financeiro:read.
Extrato do vendedor, com escopo extrato:read.
Pos-venda consultivo de pedidos do vendedor, com escopo posvenda:read.
Produtos do vendedor, com escopo produtos:read.
Categorias do marketplace para mapeamento de produto, com escopo produtos:read.
Criacao e edicao de produtos homologadas, com escopo produtos:write.
Atualizacao de estoque homologada, com escopo estoque:write.
Pedidos do vendedor, com escopo pedidos:read.
Envio/rastreio do pedido, com escopo envios:read.
NF-e do pedido, com escopo nfe:read.
Envio de NF-e autorizada por ERP homologado, com escopo nfe:write.
Sandbox de produto, pedido e webhook, com escopo sandbox:read.
Webhooks de mensagens e disputas, depois de teste HMAC com webhook.test.

Pronto, mas ainda operado por fluxo oficial

Estas areas ja existem no marketplace, mas ainda nao sao expostas como API generica para qualquer sistema:

Frete, etiqueta e rastreio: usar regra do marketplace, Melhor Envio e painel do pedido.
NFe emitida pelo marketplace: usar fluxo interno com NFE.io e painel administrativo.
NFe emitida por ERP homologado: pode ser devolvida pela API com nfe:write, sem permitir que o integrador mexa em financeiro, reputacao ou administracao.
Cancelamento, reembolso e disputa: usar fluxos auditados do marketplace.

Nao liberar sem nova fase de seguranca

Estas acoes ainda precisam de escopos proprios, idempotencia obrigatoria, trilha de auditoria, limites por vendedor e testes de reversao:

Criar pedido por API generica.
Gerar etiqueta por API generica.
Cancelar venda ou iniciar reembolso por API generica.
Alterar status financeiro, frete ou reputacao por API generica.

Eventos operacionais automaticos

Estes eventos ja sao disparados automaticamente pelos fluxos reais do marketplace:

pedido.created: enfileirado depois que o pedido e gravado no checkout.
pedido.paid: enfileirado quando o Mercado Pago confirma pagamento aprovado.
envio.status_changed: enfileirado quando o Melhor Envio informa mudanca de rastreio, postagem, entrega, cancelamento ou excecao.
nfe.authorized: enfileirado quando a NF-e e autorizada pela NFE.io, pelo webhook de NF-e do Bling ou por ERP homologado usando nfe:write.

O disparo e idempotente. Se o provedor externo reenviar o mesmo webhook ou o marketplace reprocessar uma etapa, o integrador nao deve processar duplicado: use sempre o campo event_id.

Eventos ja cadastraveis, mas alguns dependem do fluxo que muda o dado:

pedido.status_changed
recebivel.available
produto.created: disparado quando produto e criado por API externa homologada.
produto.updated: disparado quando produto e editado por API externa homologada.
estoque.updated: disparado quando estoque e atualizado por API externa homologada.
estoque.low: disparado quando estoque atualizado por API externa fica baixo.

Escopos liberados nesta fase

pedidos:read
produtos:read
envios:read
nfe:read
nfe:write
sandbox:read
produtos:write
estoque:write

Escopos de escrita restritos

produtos:write
estoque:write
nfe:write
cancelamentos:write

Escrita real por API externa

A escrita real de catalogo possui contrato e camada de seguranca, mas fica bloqueada por padrao ate a homologacao.

Para qualquer rota de escrita, o integrador precisa:

API Key com escopo de escrita especifico.
Header Idempotency-Key unico por tentativa logica.
Payload homologado.
Logs e auditoria revisados no painel.
Flag INTEGRATION_API_WRITE_ENABLED=true somente quando a operacao estiver aprovada.

Sem essa flag, a API responde 423 Locked, nao grava dados reais e salva a tentativa na tabela de idempotencia.

Consultar categorias para mapeamento

httpGET /api/v1/integracoes/categorias?limit=300
X-API-Key: SUA_API_KEY

Escopo necessario: produtos:read.

Use esta rota antes de criar produto para mapear a categoria do ERP para o categoria_id aceito pelo marketplace.

Criar produto por API

httpPOST /api/v1/integracoes/vendedores/{sellerId}/produtos
X-API-Key: SUA_API_KEY
Idempotency-Key: produto-externo-123
Content-Type: application/json

Escopo necessario: produtos:write.

Payload minimo:

json{
  "nome": "Fone Bluetooth Modelo X",
  "descricao": "Descricao completa do produto com informacoes reais para o comprador.",
  "preco": 68.90,
  "estoque": 10,
  "categoria_id": 12,
  "peso_kg": 0.45,
  "comprimento_cm": 20,
  "largura_cm": 20,
  "altura_cm": 10,
  "sku": "ERP-123",
  "marca": "Marca",
  "image_urls": [
    "https://cdn.exemplo.com/produto-1.jpg",
    "https://cdn.exemplo.com/produto-2.jpg",
    "https://cdn.exemplo.com/produto-3.jpg"
  ],
  "video_url": "https://cdn.exemplo.com/video.mp4"
}

Status atual: escrita real liberavel por escopo e flag INTEGRATION_API_WRITE_ENABLED=true.

Editar produto por API

httpPATCH /api/v1/integracoes/vendedores/{sellerId}/produtos/{produtoId}
X-API-Key: SUA_API_KEY
Idempotency-Key: produto-externo-123-update
Content-Type: application/json

Escopo necessario: produtos:write.

Envie somente os campos que deseja alterar. Para trocar a galeria inteira, envie image_urls com 3 a 8 URLs HTTPS. Para remover video, envie "remove_video": true.

Atualizar estoque por API

httpPATCH /api/v1/integracoes/vendedores/{sellerId}/produtos/{produtoId}/estoque
X-API-Key: SUA_API_KEY
Idempotency-Key: estoque-externo-123
Content-Type: application/json

Escopo necessario: estoque:write.

Payload:

json{ "estoque": 8 }

Status atual: escrita real liberavel por escopo e flag INTEGRATION_API_WRITE_ENABLED=true.

Enviar NF-e autorizada por ERP

Use esta rota quando o vendedor emite a nota fiscal em um ERP externo e o ERP precisa devolver a NF-e para o marketplace. Ela segue o mesmo cuidado da integracao com Bling: pedido precisa pertencer ao vendedor da API Key, a chave da NF-e precisa ter 44 digitos, links de DANFE/XML precisam ser HTTPS, e o envio exige idempotencia.

httpPOST /api/v1/integracoes/pedidos/{pedidoId}/nfe
X-API-Key: SUA_API_KEY
Idempotency-Key: nfe-erp-105
Content-Type: application/json

Escopo necessario: nfe:write.

Payload minimo:

json{
  "numero": "105",
  "serie": "1",
  "chave": "33260811562906000116550010000001051701854768",
  "status": "authorized",
  "danfe_url": "https://erp.exemplo.com/danfes/105.pdf",
  "xml_url": "https://erp.exemplo.com/xmls/105.xml",
  "protocolo": "333260000123456",
  "emitida_em": "2026-08-17T15:20:23-03:00",
  "provider": "erp_homologado"
}

Ao salvar, o marketplace atualiza os dados fiscais do pedido e enfileira o webhook nfe.authorized para os sistemas cadastrados. Esta rota nao permite alterar pagamento, frete, reputacao, valores do pedido ou dados administrativos.

Status atual: escrita real liberavel por escopo e flag INTEGRATION_API_WRITE_ENABLED=true.

Solicitar cancelamento por API

httpPOST /api/v1/integracoes/pedidos/{pedidoId}/cancelamentos
X-API-Key: SUA_API_KEY
Idempotency-Key: cancelamento-externo-123
Content-Type: application/json

Escopo necessario: cancelamentos:write.

Status atual: contrato preparado, escrita real bloqueada por padrao. Cancelamento/reembolso real continua passando pelos fluxos auditados do marketplace.

Sandbox de integracao

O sandbox permite testar contrato, validacao, payload e webhook sem gravar dados reais no marketplace.

Ele usa API Key normal, mas exige o escopo sandbox:read.

Kit importavel para testes

Para evitar erro de configuracao, o integrador pode importar uma colecao pronta no Postman ou Insomnia:

textGET /api/docs/postman.json

Caminhos equivalentes:

textGET /api/docs/postman
GET /api/docs/collection.json

Variaveis que precisam ser preenchidas depois da importacao:

Variavel	O que colocar
`apiKey`	API Key criada no painel de integracoes
`sellerId`	ID do vendedor autorizado
`pedidoId`	Pedido real do vendedor para consultas de pedido/envio/NF-e
`produtoId`	Produto real do vendedor para consulta de produto
`webhookSecret`	Secret exibido uma unica vez ao criar o webhook

Ordem recomendada na colecao:

Rodar Status do sandbox.
Rodar Validar produto sem salvar.
Rodar Simular pedido sem salvar.
Rodar Simular assinatura HMAC de webhook.
Criar webhook real no painel e enviar webhook.test.
Somente depois testar rotas com dados reais do vendedor.

Se qualquer chamada retornar 401, confira a API Key. Se retornar 403, confira escopo, vendedor ou IP permitido. Se retornar 429, reduza a frequencia e respeite Retry-After.

Consultar status do sandbox

httpGET /api/v1/integracoes/sandbox/status
X-API-Key: SUA_API_KEY

Validar produto sem salvar

httpPOST /api/v1/integracoes/sandbox/produtos/validar
X-API-Key: SUA_API_KEY
Content-Type: application/json

Corpo:

json{
  "sku": "TESTE-001",
  "nome": "Produto de teste",
  "preco": 99.9,
  "estoque": 10,
  "peso_kg": 0.5,
  "largura": 20,
  "altura": 10,
  "comprimento": 30
}

Resposta:

json{
  "ok": true,
  "data": {
    "produto": {
      "id": "sandbox_prod_1001",
      "persisted": false
    },
    "validation": {
      "ok": true,
      "persisted": false
    }
  }
}

Simular pedido sem salvar

httpPOST /api/v1/integracoes/sandbox/pedidos/simular
X-API-Key: SUA_API_KEY
Idempotency-Key: teste-pedido-001
Content-Type: application/json

Corpo:

json{
  "seller_id": 8,
  "subtotal": 199.8,
  "frete": 24.5,
  "metodo": "pix",
  "servico": "PAC"
}

Disparar webhook sandbox

httpPOST /api/v1/integracoes/sandbox/webhooks/test
X-API-Key: SUA_API_KEY
Content-Type: application/json

Corpo:

json{
  "event": "pedido.paid"
}

O evento e enfileirado para os webhooks ativos do vendedor que aceitarem o evento informado.

Simular assinatura de webhook

Use esta rota para conferir se o sistema externo valida HMAC corretamente antes de receber uma entrega real.

httpPOST /api/v1/integracoes/sandbox/webhooks/assinatura
X-API-Key: SUA_API_KEY
Content-Type: application/json

Corpo:

json{
  "secret": "secret_copiado_ao_criar_webhook",
  "event": "pedido.paid"
}

Resposta:

json{
  "ok": true,
  "data": {
    "signature": "sha256=...",
    "raw_body": "{\"event_id\":\"sandbox:pedido.paid:assinatura\"}",
    "headers": {
      "X-Llon-Event": "pedido.paid",
      "X-Llon-Signature": "sha256=..."
    },
    "validation": {
      "algorithm": "HMAC-SHA256"
    }
  }
}

O integrador deve calcular HMAC-SHA256(secret, raw_body) e comparar com X-Llon-Signature usando comparacao segura.

Nenhuma rota sandbox altera produto, estoque, pedido, frete, NF-e, reputacao ou financeiro real.

Webhooks automaticos

Quando um webhook esta ativo para um vendedor, o marketplace enfileira eventos aceitos por aquele webhook. O sistema externo deve responder HTTP 2xx. Respostas fora de 2xx, timeout ou erro de conexao entram em nova tentativa.

Cada entrega recebe cabecalhos:

textX-Llon-Event: pedido.paid
X-Llon-Event-Id: pedido.paid:pedido:123:paid
X-Llon-Delivery-Id: 456
X-Llon-Signature: sha256=...

Valide a assinatura HMAC usando o secret do webhook e o corpo bruto da requisicao. Depois, salve event_id no seu sistema para evitar processamento duplicado.

Eventos automaticos ligados

Evento	Quando dispara	Dados enviados
`pedido.created`	Pedido gravado no checkout do site ou app	Pedido, valores, status inicial e envio selecionado quando disponivel
`pedido.paid`	Pagamento aprovado pelo Mercado Pago	Pedido, status de pagamento, valores e data de pagamento
`envio.status_changed`	Melhor Envio muda status de rastreio/postagem/entrega	Pedido, status logistico, rastreio e servico
`nfe.authorized`	NF-e autorizada pela NFE.io, Bling ou ERP homologado	Pedido, status da NF-e, numero, serie e chave
`produto.created`	Produto criado por API externa homologada	Produto, imagens, medidas, estoque e origem
`produto.updated`	Produto editado por API externa homologada	Produto atualizado, imagens, medidas, estoque e origem
`estoque.updated`	Estoque alterado por API externa homologada	Produto, estoque atual e origem
`estoque.low`	Estoque ficou baixo depois de atualização por API	Produto, estoque atual e origem
`financeiro.reembolso_criado`	Reembolso administrativo registrado	Pedido, vendedor, valor, tipo e status do lancamento
`financeiro.ajuste_frete_criado`	Ajuste financeiro de frete em pos-venda	Pedido, vendedor, valor e motivo
`financeiro.saldo_alterado`	Movimento altera saldo do vendedor	Pedido quando houver, vendedor, origem e valor do movimento

Por privacidade, os webhooks operacionais nao enviam documento, telefone, e-mail ou endereco completo do comprador. Se uma integracao precisar desses dados, isso deve ser avaliado em escopo especifico e contrato proprio.

Payload exemplo:

json{
  "event_id": "pedido.paid:pedido:123:paid",
  "event": "pedido.paid",
  "event_at": "2026-08-16T11:20:00.000Z",
  "integration_version": 1,
  "seller_id": 8,
  "data": {
    "pedido": {
      "id": 123,
      "status": "pago",
      "pagamento_status": "approved",
      "total": 93.4,
      "subtotal": 68.9,
      "frete": 24.5,
      "criado_em": "2026-08-16T10:55:00.000Z",
      "pago_em": "2026-08-16T11:20:00.000Z"
    },
    "envio": {
      "status": "em_separacao",
      "rastreio": null,
      "servico": "PAC"
    },
    "nfe": {
      "status": null,
      "numero": null,
      "chave": null
    },
    "origem": "mercadopago_webhook"
  }
}

Modelo de homologacao

Antes de liberar um sistema externo em producao, siga este processo:

Registrar nome do integrador, responsavel tecnico e e-mail de suporte.
Definir quais vendedores serao atendidos.
Definir quais escopos o integrador precisa.
Criar API Key temporaria ou com IP permitido.
Criar webhook de teste com evento webhook.test.
Validar assinatura HMAC no sistema externo.
Confirmar que o integrador salva event_id e nao processa duplicado.
Confirmar que os testes ficaram sem falhas recorrentes.
Ativar producao com chave definitiva.
Documentar quem pode pedir revogacao da chave.

Se qualquer etapa falhar, nao avance para producao.

Checklist sandbox antes da producao

Use esta ordem para validar um parceiro sem tocar dados reais:

Criar API Key com sandbox:read e apenas os escopos de leitura necessarios.
Chamar GET /api/v1/integracoes/sandbox/status.
Validar produto com POST /sandbox/produtos/validar.
Simular pedido com POST /sandbox/pedidos/simular usando Idempotency-Key.
Simular assinatura com POST /sandbox/webhooks/assinatura.
Solicitar a ativacao do webhook HTTPS real.
Validar o evento webhook.test com a equipe.
Confirmar resposta HTTP 2xx no teste de webhook.
Confirmar que o integrador salvou event_id.
Liberar eventos automaticos reais somente depois do teste HMAC aprovado.

Critérios mínimos para aprovar:

API Key sem escopo *.
Webhook HTTPS público validado.
HMAC validado no integrador.
Resposta HTTP 2xx em teste.
Logs sem 401, 403, 429 ou falha de webhook.
Responsável técnico registrado para suporte e revogação.

Autenticacao

A API usa chave por vendedor.

Envie a chave em um destes formatos:

textX-API-Key: llon_live_xxxxxxxxx

ou:

textAuthorization: ApiKey llon_live_xxxxxxxxx

A API Key e exibida apenas uma vez no momento da criacao. Se perder, revogue e crie outra.

Escopos

Cada chave deve receber apenas os escopos necessarios. Exemplos:

textfinanceiro:read
extrato:read
posvenda:read
produtos:read
produtos:write
estoque:write
pedidos:read
envios:read
nfe:read
nfe:write
sandbox:read

Para um ERP no padrao Bling, normalmente a chave final usa:

produtos:read, para comparar catalogo.
produtos:write, para criar ou editar produto.
estoque:write, para manter estoque sincronizado.
pedidos:read, para buscar pedidos do vendedor.
envios:read, para consultar frete e rastreio.
nfe:read, para consultar nota ja registrada.
nfe:write, para devolver NF-e autorizada emitida no ERP.
sandbox:read, para homologacao e reteste.

O escopo * deve ser reservado para uso interno e nao deve ser entregue a integradores externos.

Perfis recomendados de liberacao

Use estes perfis como ponto de partida. O operador pode reduzir escopos quando a integracao precisar de menos acesso.

Perfil	Quando usar	Escopos principais	Webhooks recomendados
Sandbox inicial	Primeiro teste de qualquer integrador	`sandbox:read`	`webhook.test`
ERP completo homologado	ERP ou hub que precisa operar parecido com Bling	`produtos:read`, `produtos:write`, `estoque:write`, `pedidos:read`, `envios:read`, `nfe:read`, `nfe:write`, `sandbox:read`	`pedido.created`, `pedido.paid`, `pedido.status_changed`, `envio.status_changed`, `nfe.authorized`, `produto.created`, `produto.updated`, `estoque.updated`, `estoque.low`
Pedidos e logistica	WMS, expedicao ou sistema que acompanha venda e envio	`pedidos:read`, `envios:read`, `nfe:read`, `sandbox:read`	`pedido.created`, `pedido.paid`, `pedido.status_changed`, `envio.status_changed`, `nfe.authorized`
Atendimento / CRM	CRM, tickets, suporte e pos-venda	`posvenda:read`, `pedidos:read`, `sandbox:read`	`pedido_mensagem.created`, `disputa_mensagem.created`, `pedido.status_changed`
Financeiro / BI	Relatorios, contador, conciliacao e painel financeiro externo	`financeiro:read`, `extrato:read`, `pedidos:read`, `nfe:read`, `sandbox:read`	`pedido.paid`, `recebivel.available`, `financeiro.reembolso_criado`, `financeiro.ajuste_frete_criado`, `financeiro.saldo_alterado`

O JSON oficial dos perfis e do catalogo de eventos fica em:

texthttps://lojasleveon.com.br/api/docs/profiles.json

Use o campo profiles para montar presets de escopos/eventos por tipo de integrador. Use o campo events para consultar a lista publica de webhooks disponiveis, agrupada por area: testes, pedidos, envio/fiscal, catalogo/estoque, atendimento e financeiro.

Recomendado para producao:

Uma API Key por vendedor e por sistema integrado.
Definir IPs permitidos quando o integrador tiver IP fixo.
Definir data de expiracao para chaves temporarias.
Revogar chaves antigas quando trocar fornecedor.

Cabecalhos recomendados

Alem da API Key, sistemas externos devem enviar identificadores que ajudam na auditoria:

textX-API-Key: llon_live_xxxxxxxxx
X-Integration-Name: nome-do-sistema
X-Request-Id: uuid-gerado-pelo-integrador
Accept: application/json
Content-Type: application/json

X-Request-Id ainda nao e obrigatorio na V1, mas deve ser adotado desde o inicio para facilitar suporte e rastreio.

Endpoints disponiveis

Consultar financeiro do vendedor

Escopo exigido: financeiro:read

httpGET /api/v1/integracoes/vendedores/{sellerId}/financeiro
X-API-Key: llon_live_xxxxxxxxx

Exemplo:

bashcurl -H "X-API-Key: llon_live_xxxxxxxxx" \
  "https://lojasleveon.com.br/api/v1/integracoes/vendedores/8/financeiro"

Resposta resumida:

json{
  "ok": true,
  "integration_version": 1,
  "data": {
    "seller_id": 8,
    "saldo_total": 125.5,
    "movimentos": []
  }
}

Consultar extrato do vendedor

Escopo exigido: extrato:read

httpGET /api/v1/integracoes/vendedores/{sellerId}/extrato
X-API-Key: llon_live_xxxxxxxxx

Exemplo:

bashcurl -H "X-API-Key: llon_live_xxxxxxxxx" \
  "https://lojasleveon.com.br/api/v1/integracoes/vendedores/8/extrato"

Resposta resumida:

json{
  "ok": true,
  "integration_version": 1,
  "data": {
    "seller_id": 8,
    "extrato": [
      {
        "id": 101,
        "pedido_id": 55,
        "tipo": "venda",
        "status": "scheduled",
        "valor": 10.25,
        "created_at": "2026-08-15T10:00:00.000Z"
      }
    ]
  }
}

Consultar pos-venda de pedido

Escopo exigido: posvenda:read

httpGET /api/v1/integracoes/pedidos/{pedidoId}/posvenda
X-API-Key: llon_live_xxxxxxxxx

A API Key so acessa pedidos que pertencem ao vendedor da chave.

Exemplo:

bashcurl -H "X-API-Key: llon_live_xxxxxxxxx" \
  "https://lojasleveon.com.br/api/v1/integracoes/pedidos/55/posvenda"

Resposta resumida:

json{
  "ok": true,
  "integration_version": 1,
  "data": {
    "pedido": {},
    "posvenda": {},
    "recebiveis": []
  }
}

Paginacao e limites

Na V1, consultas financeiras retornam ate 300 registros por chamada. Esse limite protege o banco e evita lentidao em integracoes mal configuradas.

Quando novos endpoints de listagem forem abertos, eles devem seguir este padrao:

text?limit=100&cursor=cursor_recebido_na_resposta

Regras recomendadas:

limit maximo de 100 para endpoints novos.
Nunca puxar o historico completo a cada minuto.
Para atualizacao em tempo real, usar webhook.
Para conciliacao, fazer leitura incremental por data ou cursor.

Rate limit

Para proteger o marketplace contra lentidao e abuso, a API externa possui limite por API Key e IP.

Padrao inicial:

text120 chamadas por minuto por API Key e IP

Quando o limite for atingido, a API retorna:

textHTTP 429 Too Many Requests

Headers de controle:

textX-RateLimit-Limit: 120
X-RateLimit-Remaining: 57
Retry-After: 30

O integrador deve respeitar Retry-After antes de tentar novamente. Se precisar de volume maior, o correto e homologar o caso de uso e ajustar o limite de forma controlada.

Codigos de erro

text200 - Sucesso
400 - Requisicao invalida
401 - API Key ausente, invalida ou expirada
403 - Sem permissao para o escopo, vendedor ou pedido
404 - Registro nao encontrado
429 - Limite de chamadas excedido
500 - Erro interno

Formato padrao de erro:

json{
  "ok": false,
  "error": "mensagem resumida do erro"
}

Quando acionar suporte, envie:

Endpoint chamado.
Horario aproximado.
seller_id.
pedido_id, se houver.
X-Request-Id, quando usado.
Codigo HTTP retornado.

Webhooks

Webhooks avisam sistemas externos quando algo acontece no marketplace. O integrador cadastra uma URL HTTPS e recebe eventos com assinatura.

Eventos disponiveis

textwebhook.test
pedido_mensagem.created
disputa_mensagem.created

Eventos internos que contem dados privados do cliente nao devem ser enviados para webhooks externos sem uma regra especifica de privacidade.

Headers enviados

Toda entrega de webhook leva estes headers:

textContent-Type: application/json
User-Agent: LojasLeveOn-Webhook/1.0
X-Llon-Event: pedido_mensagem.created
X-Llon-Event-Id: pedido_mensagem.created:123
X-Llon-Delivery-Id: 456
X-Llon-Signature: sha256=...

Corpo enviado

json{
  "event_id": "pedido_mensagem.created:123",
  "event": "pedido_mensagem.created",
  "event_at": "2026-08-15T12:00:00.000Z",
  "integration_version": 1,
  "seller_id": 8,
  "data": {
    "pedido_id": 55
  }
}

Validar assinatura em Node.js

jsconst crypto = require('crypto');

function validarWebhook(rawBody, headerSignature, secret) {
  const expected = 'sha256=' + crypto
    .createHmac('sha256', secret)
    .update(rawBody)
    .digest('hex');

  return crypto.timingSafeEqual(
    Buffer.from(expected),
    Buffer.from(headerSignature || '')
  );
}

Validar assinatura em PHP

php<?php
$rawBody = file_get_contents('php://input');
$signature = $_SERVER['HTTP_X_LLON_SIGNATURE'] ?? '';
$secret = 'secret_exibido_uma_vez';

$expected = 'sha256=' . hash_hmac('sha256', $rawBody, $secret);

if (!hash_equals($expected, $signature)) {
  http_response_code(401);
  exit('assinatura invalida');
}

http_response_code(200);
echo 'ok';

Validar assinatura em Python

pythonimport hmac
import hashlib

def validar_webhook(raw_body: bytes, header_signature: str, secret: str) -> bool:
    expected = "sha256=" + hmac.new(
        secret.encode("utf-8"),
        raw_body,
        hashlib.sha256
    ).hexdigest()

    return hmac.compare_digest(expected, header_signature or "")

Regras de entrega

A URL precisa comecar com https://.
A URL precisa apontar para host publico.
Nao use usuario e senha dentro da URL.
O marketplace espera resposta em ate 10 segundos.
Respostas HTTP 2xx contam como sucesso.
Falhas sao reenviadas com tentativas progressivas.
O integrador deve salvar event_id para nao processar o mesmo evento duas vezes.
O mesmo evento pode ser entregue novamente se houver timeout ou erro temporario.

Idempotencia no webhook

O integrador deve gravar event_id antes de executar efeitos importantes.

Fluxo recomendado:

Recebe webhook.
Valida assinatura.
Verifica se event_id ja foi processado.
Se ja processou, responde 200 sem repetir a acao.
Se ainda nao processou, grava event_id.
Executa a acao.
Responde HTTP 2xx.

Isso evita duplicar ticket, mensagem, baixa financeira ou alerta quando houver reenvio.

Testar webhook

httpPOST /api/v1/integracoes/webhooks/test
Content-Type: application/json
Authorization: Bearer TOKEN_ADMIN

Corpo:

json{
  "seller_id": 8
}

Fluxos de integracao

ERP ou hub de produtos

No momento, o fluxo operacional principal de produtos, estoque e pedidos fica pelo Bling e pelo painel do marketplace. A API externa generica deve comecar lendo dados e recebendo webhooks, ate que a escrita seja liberada com escopos e idempotencia.

Fluxo recomendado:

Vendedor conecta Bling quando usar ERP.
Marketplace centraliza produto, estoque, pedido, frete, NFe e pos-venda.
Integrador externo consome financeiro, extrato, pos-venda e eventos.
Para escrita direta, abrir fase homologada por integrador.

Financeiro e contabilidade

Use financeiro:read e extrato:read para conciliacao, relatorios e fechamento do vendedor.

Atendimento e CRM

Use webhooks de mensagens e disputas para abrir ticket ou alerta no sistema externo. O sistema externo deve respeitar privacidade e nao guardar dados desnecessarios do comprador.

BI e monitoramento

Use consultas periodicas de financeiro e extrato. Evite chamadas agressivas. Para dados em tempo real, prefira webhooks.

Responsabilidades por tipo de sistema

ERP

Nao deve alterar financeiro diretamente.
Deve respeitar estoque e produto definidos no marketplace ou via integracao oficial autorizada.
Deve guardar logs de sincronizacao.

CRM ou atendimento

Deve receber apenas eventos necessarios.
Nao deve expor dados do cliente para operadores sem permissao.
Deve guardar historico respeitando finalidade de atendimento.

BI e relatorios

Deve usar leitura incremental.
Deve evitar consultas repetidas em intervalos muito curtos.
Deve separar dados por vendedor.

Financeiro e contabilidade

Deve usar financeiro:read e extrato:read.
Deve tratar valores negativos como estorno, reembolso ou ajuste.
Deve validar data de competencia antes de fechar relatorio.

Versionamento

A V1 fica sob o prefixo:

text/api/v1

Regras de compatibilidade:

Campos novos podem ser adicionados sem aviso.
Campos existentes nao devem mudar de significado dentro da mesma versao.
Remocao ou mudanca de contrato deve gerar nova versao.
Integradores devem ignorar campos desconhecidos.

Checklist para integrar

Definir vendedor (seller_id) e sistema que sera conectado.
Criar API Key com escopos minimos.
Guardar a API Key em cofre seguro, nunca no frontend.
Criar endpoint HTTPS para webhook.
Criar webhook com os eventos necessarios.
Validar X-Llon-Signature em toda entrega.
Salvar event_id para idempotencia.
Responder webhook rapidamente com HTTP 2xx.
Testar com webhook.test.
Monitorar erros com o contato tecnico cadastrado.
Revogar chaves e webhooks que nao forem mais usados.

Checklist de producao

Antes de liberar oficialmente:

API Key criada com nome claro.
Escopos revisados.
IP permitido configurado quando houver IP fixo.
Webhook respondendo em menos de 10 segundos.
Assinatura HMAC validada.
Reenvio testado com webhook.test.
Logs de sucesso e erro conferidos.
Responsavel tecnico registrado.
Plano de revogacao definido.

Criterios de aprovacao

Uma integracao esta aprovada quando:

A API Key tem nome identificavel e escopos minimos.
A chave nao fica no frontend, app publico ou URL.
O integrador demonstrou validacao de X-Llon-Signature.
O integrador grava event_id e ignora duplicados.
O webhook responde HTTP 2xx em ate 10 segundos.
Nao existem falhas recorrentes de 401, 403 ou 429 nos testes.
Existe contato tecnico para incidente.
Existe plano para revogar a chave sem parar o vendedor.

Se qualquer criterio falhar, manter a integracao em homologacao.

Rotacao de credenciais

Quando precisar trocar fornecedor ou chave:

Criar nova API Key.
Enviar a nova chave ao responsavel tecnico por canal seguro.
Aguardar o integrador confirmar que ja usa a nova chave.
Revogar a chave antiga.
Conferir se nao existem chamadas recentes da chave revogada.

Nunca envie API Key por print publico, grupo aberto ou documento compartilhado sem controle.

Regras para nao dar erro

Nunca colocar API Key em JavaScript publico, app sem protecao ou URL.
Nunca processar reembolso, cancelamento ou disputa por fora das regras auditaveis do marketplace.
Nunca assumir que webhook sera entregue uma unica vez.
Nunca usar webhook sem validar assinatura.
Nunca liberar escopo maior do que o integrador precisa.
Usar uma chave por vendedor e por sistema integrado.
Em caso de troca de fornecedor, revogar a chave antiga.

Exemplo completo em Node.js

jsasync function consultarFinanceiro() {
  const resp = await fetch(
    'https://lojasleveon.com.br/api/v1/integracoes/vendedores/8/financeiro',
    {
      headers: {
        'X-API-Key': process.env.LLON_API_KEY
      }
    }
  );

  if (!resp.ok) {
    throw new Error(`Erro na API: ${resp.status}`);
  }

  return resp.json();
}

OpenAPI

A especificacao tecnica fica em:

text/api/docs/openapi.json

Ela pode ser importada em ferramentas como Postman, Insomnia e documentadores OpenAPI.

Modelo de resposta para integradores

Quando um parceiro pedir acesso, envie este resumo:

textNossa integracao externa usa API Key por vendedor, escopos limitados e webhooks assinados com HMAC SHA-256.

Para iniciar, precisamos de:
- Nome do sistema
- Responsavel tecnico
- E-mail de suporte
- Seller ID do vendedor
- Escopos necessarios
- URL HTTPS do webhook
- IPs de origem, se existirem

Depois disso, criamos uma chave de homologacao, testamos o evento webhook.test e so entao liberamos producao.

Suporte

Para liberar integracao em producao, informe:

Nome do sistema integrador.
Vendedor ou sellers que serao conectados.
Escopos necessarios.
URL HTTPS do webhook.
IPs de origem, quando existirem.
Responsavel tecnico e e-mail de suporte.