Conecte seu e-commerce ou sistema ao mesmo estoque que a LOJEXA envia aos seus marketplaces. Mostre o disponível, acompanhe o que mudou e registre a venda do site: o novo saldo vai para as lojas com o envio de estoque ligado.
# Registrar venda no seu site curl -X POST https://lojexa.com/api/v1/vendas \ -H "Authorization: Bearer lj_live_***" \ -H "Content-Type: application/json" \ -d '{ "reference": "PEDIDO-9934", "channel": "site", "items": [ { "sku": "CAMISETA-P", "quantity": 2 } ] }' # Resposta (HTTP 201) — a mesma reference de novo devolve 200 already_processed { "success": true, "data": { "sale_id": 456, "reference": "PEDIDO-9934", "status": "confirmed", "items_processed": [{ "sku": "CAMISETA-P", "quantity": 2, "stock_after": 13 }] } }
Da chave até o estoque do seu site igual ao da LOJEXA.
O administrador acessa /configuracoes/api-keys no painel e clica em "Criar nova chave". Marque só os escopos necessários e guarde a chave no servidor — ela aparece uma vez só.
GET /api/v1/produtos?fields=stock traz o disponível para venda de cada SKU,
por armazém. Depois, GET /api/v1/estoque/mudancas traz só o que mudou
desde a última consulta (atraso de até ~2 min; SKU de cadastro antigo, sem saldo por armazém: até ~3 h, pelo
feed do catálogo — veja o passo 4).
Um POST /api/v1/vendas baixa o estoque central, e o novo saldo vai
para as lojas com o envio de estoque ligado. Repetir a mesma reference
não baixa duas vezes.
API REST com autenticação por chave (Bearer ou X-Api-Key). Base URL: https://lojexa.com/api/v1
Testar a chave: devolve a empresa e os escopos. Qualquer chave ativa.
Produtos com o estoque disponível do saldo por armazém (a conta que a venda confere), por armazém e com kits pelas peças. Até 100 SKUs por chamada com ?skus=.
Um produto pelo SKU: estoque por armazém, lojas vinculadas e o catálogo do anúncio.
Só os SKUs cujo estoque mudou desde o último cursor, com o estoque atual. Também: /estoque/movimentos (o motivo de cada mudança) e /produtos?updated_since= (catálogo).
As lojas conectadas e se a LOJEXA envia estoque para cada uma. Também: /armazens e /mapeamentos.
Ler os pedidos de Shopee, Mercado Livre, TikTok, SHEIN, Magalu, Temu, Nuvemshop e os pedidos próprios criados na LOJEXA (painel, PDV, app; a Amazon fica fora; a venda de POST /vendas não aparece), somente leitura: status, prazo de envio, rastreio, valores, taxas do repasse e NF-e. Sincronização por cursor.
Detalhe de um pedido no estado atual, com o motivo quando ele está travado por falta de estoque. Também: /orders/{id}/stock-reservations.
Registrar a venda do seu site e baixar o estoque no mesmo armazém do stock.available (kit pelas peças). Idempotente pela reference. O envio do novo saldo às lojas com o envio de estoque ligado entra na fila.
Consultar a venda: status, itens e o que já foi cancelado ou devolvido. É como saber, depois de um timeout, se a venda entrou.
Cancelar a venda toda ou só alguns itens, devolvendo ao estoque só o que saiu; o envio do novo saldo entra na fila.
Registrar a devolução depois da entrega, toda ou em parte: o produto volta ao disponível ou, avariado, ao físico como avaria.
Entrada de mercadoria, saída (perda, avaria) ou o físico contado (set), no armazém da leitura. Idempotente com o cabeçalho Idempotency-Key.
O mesmo em lote: até 500 ajustes numa chamada, cada item com o próprio resultado. Idempotency-Key obrigatória.
Ligar o SKU ao anúncio de um canal, sem apagar o que o painel gravou. Também: DELETE /mapeamentos/{id}.
Consumo da chave: vendas hoje e no mês, o minuto atual do limite de chamadas e a expiração.
Cada chave recebe só o que você marcar ao criá-la. Nenhum escopo vem marcado: para um programa que apenas recebe pedidos, marque somente read:orders.
| Escopo | O que libera | Altera dados? |
|---|---|---|
read:products |
Ler produtos e estoque Produtos, estoque disponível e mapeamentos SKU ↔ canal. Não altera nada. |
Não |
read:orders |
Ler pedidos — somente leitura; dados do comprador mascarados Pedidos de Shopee, Mercado Livre, TikTok, SHEIN, Magalu, Temu, Nuvemshop e os pedidos próprios criados na LOJEXA (painel, PDV, app; a Amazon fica fora; a venda de POST /vendas não aparece) com status, prazos de envio, rastreio, valores, taxas do repasse e NF-e. Não altera nada. Nome e usuário do comprador chegam mascarados; telefone, endereço e documento nunca saem. |
Não |
write:sales |
Registrar, consultar, cancelar e devolver vendas Registra a venda feita fora da LOJEXA e baixa o estoque; o novo saldo vai às lojas com o envio de estoque ligado. O cancelamento e a devolução, totais ou parciais, devolvem ao estoque só o que saiu. |
Sim |
write:stock |
Ajustar estoque (entrada, saída e contagem) Entrada de mercadoria, perda, avaria e contagem de um SKU, avulso ou em lote, com o motivo gravado no histórico. Idempotente com Idempotency-Key. |
Sim |
manage:mappings |
Criar e remover mapeamentos SKU ↔ canal Liga e desliga o SKU do estoque ao anúncio de cada canal. |
Sim |
Não existe escopo que entregue telefone, e-mail, endereço ou CPF/CNPJ do comprador.
Do servidor, com timeout e conferindo o código HTTP. A chave vem da variável LOJEXA_API_KEY.
# 1. O disponível de até 100 SKUs numa chamada
curl -sS --max-time 30 -H "Authorization: Bearer $LOJEXA_API_KEY" \
"https://lojexa.com/api/v1/produtos?skus=CAMISETA-M-AZUL,BONE-PRETO&fields=stock"
# 2. Registrar a venda (sem seguir redirecionamento; timeout de 30 s)
curl -sS --max-time 30 -w '\nHTTP %{http_code}\n' -X POST https://lojexa.com/api/v1/vendas \
-H "Authorization: Bearer $LOJEXA_API_KEY" \
-H "Content-Type: application/json" \
-d '{"reference": "PEDIDO-9934", "channel": "site",
"items": [{"sku": "CAMISETA-M-AZUL", "quantity": 2}]}'
# HTTP 201: registrada. HTTP 200 com "already_processed": true: já estava registrada.
# Timeout, 5xx, 409 STOCK_RACE_CONDITION (corrida no estoque) ou 429 (espere o Retry-After):
# repita a MESMA chamada, com a mesma reference. Outro 4xx: corrija antes (repetir não resolve).
<?php
function venda(array $venda): array
{
$ch = curl_init('https://lojexa.com/api/v1/vendas');
curl_setopt_array($ch, [
CURLOPT_POST => true,
CURLOPT_RETURNTRANSFER => true,
CURLOPT_TIMEOUT => 30,
CURLOPT_FOLLOWLOCATION => false,
CURLOPT_HTTPHEADER => [
'Authorization: Bearer ' . getenv('LOJEXA_API_KEY'),
'Content-Type: application/json',
],
CURLOPT_POSTFIELDS => json_encode($venda),
]);
$cabecalhos = [];
curl_setopt($ch, CURLOPT_HEADERFUNCTION, static function ($ch, string $linha) use (&$cabecalhos): int {
if (str_contains($linha, ':')) {
[$nome, $valor] = explode(':', $linha, 2);
$cabecalhos[strtolower(trim($nome))] = trim($valor);
}
return strlen($linha);
});
$corpo = curl_exec($ch);
$status = (int) curl_getinfo($ch, CURLINFO_RESPONSE_CODE); // 0 = timeout ou rede
if ($status === 201 || $status === 200) {
return json_decode($corpo, true); // 200 = "already_processed": true (já estava)
}
$erro = json_decode((string) $corpo, true)['error'] ?? [];
if ($status === 429) {
sleep((int) ($cabecalhos['retry-after'] ?? 5)); // o que o servidor pediu
throw new RuntimeException('Limite de chamadas: repita agora com a MESMA reference.');
}
if ($status === 0 || $status >= 500 || ($erro['code'] ?? '') === 'STOCK_RACE_CONDITION') {
throw new RuntimeException('Repita com a MESMA reference: a venda não baixa duas vezes.');
}
throw new RuntimeException(($erro['code'] ?? "HTTP {$status}") . ': ' . ($erro['message'] ?? ''));
}
venda([
'reference' => 'PEDIDO-9934',
'channel' => 'site',
'items' => [['sku' => 'CAMISETA-M-AZUL', 'quantity' => 2]],
]);
// No SERVIDOR (Node 18+): a chave nunca vai para o navegador.
async function venda(venda) {
let r;
try {
r = await fetch('https://lojexa.com/api/v1/vendas', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.LOJEXA_API_KEY}`,
'Content-Type': 'application/json',
},
body: JSON.stringify(venda),
redirect: 'manual',
signal: AbortSignal.timeout(30_000),
});
} catch {
throw new Error('Timeout ou rede: repita com a MESMA reference (a venda não baixa duas vezes).');
}
if (r.status === 201 || r.status === 200) return r.json(); // 200 = "already_processed": true
if (r.status === 429) {
await new Promise((ok) => setTimeout(ok, 1000 * Number(r.headers.get('Retry-After') ?? 5)));
throw new Error('Limite de chamadas: repita agora com a MESMA reference.');
}
if (r.status >= 500) throw new Error('Erro do servidor: repita com a MESMA reference.');
const { error = {} } = await r.json().catch(() => ({ error: {} }));
if (error.code === 'STOCK_RACE_CONDITION') throw new Error('Corrida no estoque: repita com a MESMA reference.');
throw new Error(`${error.code ?? 'HTTP ' + r.status}: ${error.message ?? ''}`);
}
await venda({
reference: 'PEDIDO-9934',
channel: 'site',
items: [{ sku: 'CAMISETA-M-AZUL', quantity: 2 }],
});
import os
import time
import requests
def venda(dados):
try:
r = requests.post(
'https://lojexa.com/api/v1/vendas',
headers={'Authorization': f"Bearer {os.environ['LOJEXA_API_KEY']}"},
json=dados,
timeout=30,
allow_redirects=False,
)
except requests.RequestException:
raise RuntimeError('Timeout ou rede: repita com a MESMA reference (a venda não baixa duas vezes).')
if r.status_code in (200, 201):
return r.json() # 200 = "already_processed": True (já estava registrada)
if r.status_code == 429:
time.sleep(int(r.headers.get('Retry-After', '5'))) # o que o servidor pediu
raise RuntimeError('Limite de chamadas: repita agora com a MESMA reference.')
if r.status_code >= 500:
raise RuntimeError('Erro do servidor: repita com a MESMA reference.')
erro = r.json().get('error', {})
if erro.get('code') == 'STOCK_RACE_CONDITION':
raise RuntimeError('Corrida no estoque: repita com a MESMA reference.')
raise RuntimeError(f"{erro.get('code')}: {erro.get('message')}")
venda({
'reference': 'PEDIDO-9934',
'channel': 'site',
'items': [{'sku': 'CAMISETA-M-AZUL', 'quantity': 2}],
})
Guia ponta a ponta: do zero à produção, em 11 passos (cURL, Python, Node.js e PHP)
Aviso das vendas, cancelamentos e devoluções feitos pela própria chave, pela fila, assinado e com novas tentativas. É um aviso: a fonte da verdade continua sendo o feed de estoque.
Disparado depois de POST /api/v1/vendas registrar a venda (201).
O payload inclui os itens vendidos e o estoque atualizado.
Disparado quando uma venda é cancelada ou devolvida (toda ou parte) via
/cancelar ou /devolver. Traz os itens e o que voltou ao estoque.
Como configurar
Em /configuracoes/api-keys, informe a URL (https, endereço público) ao criar a chave. O Webhook Secret aparece uma vez, junto da chave; "Nova senha dos avisos" (Novo secret), no cartão da chave, gera outro. A mesma tela mostra cada aviso entregue, na fila ou recusado, com o motivo.
Abrir Chaves de API$webhookSecret = (string) getenv('LOJEXA_WEBHOOK_SECRET'); if ($webhookSecret === '') { // sem o secret, qualquer um assinaria: recuse tudo http_response_code(500); exit; } $sig = $_SERVER['HTTP_X_LOJEXA_SIGNATURE_V2'] ?? ''; $ts = $_SERVER['HTTP_X_LOJEXA_TIMESTAMP'] ?? ''; $payload = file_get_contents('php://input'); $expected = 'sha256=' . hash_hmac('sha256', $ts . '.' . $payload, $webhookSecret); if (!hash_equals($expected, $sig) || abs(time() - (int) $ts) > 300) { http_response_code(401); exit; } $event = json_decode($payload, true); // Pode chegar mais de uma vez: deduplique pelo event_id switch ($event['event']) { case 'sale.confirmed': // Venda confirmada — atualizar seu sistema processarVenda($event['data']); break; case 'sale.reversed': // Venda cancelada — reverter no seu sistema reverterVenda($event['data']); break; } http_response_code(200); // Responder 2xx em < 10 s
Use hash_equals() para prevenir timing attacks.
Responda 2xx em menos de 10 segundos; sem 2xx, a LOJEXA tenta de novo (até 10 vezes em ~24 h) e não segue redirect.
Corpo de cada evento e exemplos em Python e Node em /docs.
Quem usa a API LOJEXA e como integra com o estoque centralizado.
Site WooCommerce, Magento ou customizado? Mostre o disponível da LOJEXA, acompanhe as mudanças pelo feed (atraso de até ~2 min; SKU de cadastro antigo: até ~3 h, pelo feed do catálogo) e registre as vendas do site no mesmo estoque dos marketplaces.
Aplicativo React Native ou Flutter? O seu servidor consulta a API e o app fala com o seu servidor: a chave nunca vai dentro do app.
ERP legado, planilha avançada ou sistema próprio? Integre via API para manter o estoque LOJEXA sempre atualizado e receber os pedidos dos marketplaces, somente leitura, sem migrar de plataforma.
Vende para revendedores ou distribuidores? Abra um canal de API dedicado com escopos e limites de chamadas específicos para cada parceiro.
O acesso é o mesmo em qualquer plano: o que muda entre os planos são os limites do ERP, não a API.
| Funcionalidade | Todos os planos |
|---|---|
| Acesso à API REST | |
| Escopos de leitura (produtos, pedidos) | |
| Rate limit | 30 a 300 req/min por chave — você escolhe ao criar |
| Webhooks | (vendas registradas pela API) |
| Chaves | Várias — uma por integração |
| Suporte | Chat do site |
read:products permite apenas consultas — listar produtos, verificar estoque e
mapeamentos. Não altera nada no sistema. O GET /ping funciona com qualquer chave ativa, sem
escopo específico. O read:orders também é só de leitura: entrega os pedidos do painel de
pedidos, exceto Amazon (status, prazo de envio, rastreio, valores, taxas do repasse e NF-e) com o
nome e o usuário do comprador mascarados — telefone, endereço e documento nunca saem. O
write:sales habilita o registro e cancelamento de vendas, o que altera o estoque. Use
apenas os escopos necessários para reduzir o risco em caso de vazamento da chave.
HTTP 422 com "code": "INSUFFICIENT_STOCK", e
error.details.items traz, por SKU, o disponível no armazém da venda. A venda não
é processada parcialmente — é tudo ou nada. O stock_available de
GET /api/v1/produtos/{sku} é o mesmo número que a venda confere: consulte antes
de confirmar o checkout ao cliente. Atenção: esse número já desconta o pedido pago que
reservou no armazém, mas hoje não desconta o pedido da Shopee pago e ainda não
enviado que entrou sem reserva (ele fica no contador antigo do produto e só cai no envio). Num
SKU com pouco estoque e muita venda na Shopee, desconte no seu sistema os itens dos pedidos
pagos e não enviados sem reserva ativa (GET /api/v1/orders e
/orders/{id}/stock-reservations) — veja
o que a API não faz.
POST /api/v1/vendas, envie uma
reference única (o id do pedido no seu sistema). Se a mesma
reference for enviada de novo — por exemplo, ao repetir depois de um timeout —
a API responde HTTP 200 com "already_processed": true e o estado
da venda, sem baixar o estoque de novo. Trate como sucesso. A reference diferencia
maiúsculas; a mesma reference com outros itens responde 409 REFERENCE_CONFLICT.
Uma reference cancelada não volta a valer: para vender de novo, use outra.
No ajuste de estoque (POST /api/v1/estoque/{sku}/ajuste), a idempotência vem do
cabeçalho Idempotency-Key: o mesmo ajuste com a mesma chave devolve o mesmo resultado,
sem lançar de novo; no lote (POST /api/v1/estoque/ajustes) a chave é obrigatória.
per_page nos produtos;
limit e cursor nos feeds e nos pedidos) e acompanhe o cabeçalho
X-RateLimit-Remaining. Ao passar do limite, a API responde HTTP 429 com o código
RATE_LIMIT_EXCEEDED: espere os segundos de Retry-After e repita, com backoff e jitter.
GET /api/v1/estoque/mudancas a cada
1 a 5 minutos com o cursor guardado: cada chamada traz só o que mudou (passo a passo em
/docs).
TEST-SKU-001, criado no painel; dê entrada nele antes de vender) e
cancele a venda depois com POST /api/v1/vendas/{ref}/cancelar.
Plano Gratuito para sempre, sem cartão de crédito — a API vem em todos os planos. Configure sua primeira API Key em minutos.
Criar conta gratuita Ver a documentação