REST API v1

Integre seu site ao estoque unificado da LOJEXA

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.

✓HTTPS + HMAC ✓Idempotente ✓Multi-canal ✓Feeds por cursor
POST /api/v1/vendas
# 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
    }]
  }
}

Integre em 3 passos

Da chave até o estoque do seu site igual ao da LOJEXA.

1
Crie a chave no painel

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ó.

2
Leia o estoque disponível

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).

3
Registre a venda do site

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.

Endpoints disponíveis

API REST com autenticação por chave (Bearer ou X-Api-Key). Base URL: https://lojexa.com/api/v1

GET /api/v1/ping

Testar a chave: devolve a empresa e os escopos. Qualquer chave ativa.

GET /api/v1/produtos

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=.

GET /api/v1/produtos/{sku}

Um produto pelo SKU: estoque por armazém, lojas vinculadas e o catálogo do anúncio.

GET /api/v1/estoque/mudancas

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).

GET /api/v1/lojas

As lojas conectadas e se a LOJEXA envia estoque para cada uma. Também: /armazens e /mapeamentos.

GET /api/v1/orders

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.

GET /api/v1/orders/{id}

Detalhe de um pedido no estado atual, com o motivo quando ele está travado por falta de estoque. Também: /orders/{id}/stock-reservations.

POST /api/v1/vendas

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.

GET /api/v1/vendas/{ref}

Consultar a venda: status, itens e o que já foi cancelado ou devolvido. É como saber, depois de um timeout, se a venda entrou.

POST /api/v1/vendas/{ref}/cancelar

Cancelar a venda toda ou só alguns itens, devolvendo ao estoque só o que saiu; o envio do novo saldo entra na fila.

POST /api/v1/vendas/{ref}/devolver

Registrar a devolução depois da entrega, toda ou em parte: o produto volta ao disponível ou, avariado, ao físico como avaria.

POST /api/v1/estoque/{sku}/ajuste

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.

POST /api/v1/estoque/ajustes

O mesmo em lote: até 500 ajustes numa chamada, cada item com o próprio resultado. Idempotency-Key obrigatória.

POST /api/v1/mapeamentos

Ligar o SKU ao anúncio de um canal, sem apagar o que o painel gravou. Também: DELETE /mapeamentos/{id}.

GET /api/v1/uso

Consumo da chave: vendas hoje e no mês, o minuto atual do limite de chamadas e a expiração.

Escopos da chave

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.

Exemplos de integração

Do servidor, com timeout e conferindo o código HTTP. A chave vem da variável LOJEXA_API_KEY.

bash
# 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
<?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]],
]);
javascript — Node 18+, no servidor
// 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 }],
});
python — requests
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)

Webhooks de venda

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.

Eventos disparados
sale.confirmed

Disparado depois de POST /api/v1/vendas registrar a venda (201). O payload inclui os itens vendidos e o estoque atualizado.

sale.reversed

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
Verificar assinatura HMAC
php — verificar X-Lojexa-Signature-V2
$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.

Casos de uso

Quem usa a API LOJEXA e como integra com o estoque centralizado.

E-commerce próprio

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.

App mobile

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.

Sistema interno

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.

Integração B2B

Vende para revendedores ou distribuidores? Abra um canal de API dedicado com escopos e limites de chamadas específicos para cada parceiro.

API disponível em todos os planos, inclusive o Gratuito

O que vem com a API

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

Perguntas frequentes

O escopo 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.

A API retorna 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.

Ao registrar uma venda com 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.

O padrão é 60 chamadas por minuto por chave de API, em qualquer plano. Ao criar a chave você escolhe de 30 a 300 req/min. Para não chegar ao limite, use os feeds por cursor em vez de reler o catálogo, 100 itens por página (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.

Não. E eles só avisam as vendas, os cancelamentos e as devoluções feitos pela própria chave. Para acompanhar o estoque, consulte 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).

Não há sandbox. A leitura pode ser testada à vontade. A venda e o ajuste de teste mexem no estoque real e o novo saldo vai para os marketplaces: teste com um SKU de teste sem vínculo com anúncio, que não seja peça de kit nem kit (ex.: TEST-SKU-001, criado no painel; dê entrada nele antes de vender) e cancele a venda depois com POST /api/v1/vendas/{ref}/cancelar.

Pronto para integrar seu site?

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