OpenAPI 1.4 Guia do Desenvolvedor

Introdução

A API REST da LOJEXA liga o seu site, e-commerce, ERP ou programa ao estoque central da LOJEXA e aos pedidos dos marketplaces.

  • Ler: produtos e o estoque disponível para venda (por armazém, com kits calculados pelas peças); o que mudou no estoque e no catálogo desde a última consulta (feeds por cursor); armazéns; lojas e se o envio de estoque de cada uma está ligado; vínculos SKU ↔ anúncio; pedidos dos marketplaces (somente leitura).
  • Escrever: registrar e cancelar uma venda feita fora da LOJEXA, lançar entrada ou saída de estoque e criar ou remover vínculos.
A API está disponível em todos os planos, inclusive o Gratuito. Não há recurso da API reservado a plano pago.
Base URL https://lojexa.com/api/v1
v1.4
Versão atual (changelog)
JSON / UTF-8
Toda resposta, inclusive erro
HTTPS
Obrigatório

A especificação completa, com os schemas e os exemplos desta página, está em /api/v1/openapi.json (OpenAPI 3.0.3; importe no Postman ou no Insomnia).

Primeira integração? Siga o guia ponta a ponta: 11 passos, do zero à produção, com o código em cURL, Python, Node.js e PHP — testado contra a própria API a cada mudança.

Como ler esta página

  • Começar, autenticação, rate limit, formato e erros valem para toda chamada.
  • Cada endpoint tem a tabela de parâmetros (onde vai, tipo, se é obrigatório, padrão, limites e exemplo — a mesma do openapi.json), a requisição e a resposta reais e a tabela dos erros que ele devolve, com o que fazer.
  • Buscar: o sumário à esquerda tem um filtro; o Ctrl+F do navegador acha qualquer código de erro, campo ou trecho de código (inclusive nas abas fechadas, nos navegadores que suportam). Todo bloco de código tem o botão Copiar.

Começar

1. Criar a chave

  1. Só o administrador da conta cria chaves (subconta não tem acesso à tela).
  2. No painel, acesse /configuracoes/api-keys (só o administrador; no menu: Canais → Chaves de API) → Criar chave. A tela explica cada permissão em português e mostra, depois, tudo o que a integração fez.
  3. Dê um nome (ex.: "Site da loja"), marque só os escopos de que a integração precisa (nenhum vem marcado), escolha o limite por minuto (30, 60, 120 ou 300; padrão 60) e, se quiser, a expiração e a URL de webhook (https://, endereço público; o secret em branco é gerado pela LOJEXA).
  4. A chave (lj_live_…) aparece uma vez só, logo depois de criar. Guarde em variável de ambiente do servidor (ex.: LOJEXA_API_KEY) ou num cofre de segredos. Perdeu? Crie outra e revogue a antiga. Com Webhook URL, o secret do webhook aparece junto, também uma vez só (LOJEXA_WEBHOOK_SECRET).
  • Chave não se edita. Para mudar escopo, limite, expiração ou a URL do webhook, crie uma chave nova, troque na integração e revogue a antiga. Só o secret do webhook se troca na própria chave: Nova senha dos avisos (Novo secret), no cartão da chave.
  • Expiração: a chave vale até 23:59:59 (horário de Brasília) do dia escolhido. Depois, 401 API_KEY_EXPIRED.
  • Teste a chave com GET /ping: devolve a empresa e os escopos.

2. Qual escopo para qual caso

Quero…EscopoEndpoints
Mostrar o estoque no meu site ou manter meu sistema sincronizado read:products GET /produtos, GET /produtos/{sku}, GET /estoque/mudancas, GET /estoque/movimentos, GET /armazens, GET /lojas, GET /mapeamentos
Avisar a LOJEXA de uma venda do meu site (baixar o estoque) write:sales + read:products POST /vendas, GET /vendas/{reference}, POST /vendas/{reference}/cancelar, POST /vendas/{reference}/devolver (e a leitura para conferir antes de vender)
Lançar entrada, saída ou contagem de estoque (compra, perda, avaria, inventário) write:stock POST /estoque/{sku}/ajuste, POST /estoque/ajustes (lote de até 500)
Ler os pedidos dos marketplaces (status, prazo, rastreio, taxas, NF-e) read:orders GET /orders, GET /orders/{id}, GET /orders/{id}/stock-reservations — somente leitura; a Amazon fica fora; comprador mascarado
Vincular um SKU ao anúncio de um canal manage:mappings POST /mapeamentos, DELETE /mapeamentos/{id} (e a leitura, com read:products)
Testar a chave e ver o consumo nenhum GET /ping, GET /uso — qualquer chave ativa, sem escopo específico
Não existe escopo com os dados completos do comprador. Nome e usuário chegam mascarados; telefone, e-mail, endereço e CPF/CNPJ nunca saem da API.

3. Chamar sempre do servidor

  • Só https://. Configure o cliente HTTP para não seguir redirecionamento em POST: num redirecionamento o corpo se perde e a chamada vira outra.
  • Do servidor, nunca do navegador. A chave dá acesso ao estoque e aos pedidos da empresa: ela não pode ir para página, app distribuído ou repositório. O navegador de outro site, além disso, é barrado pelo CORS.
  • Timeout: use 30 s. Leitura que deu timeout pode ser repetida; para escrita, veja a regra de cada endpoint.

O que a API não faz hoje

Leia antes de planejar a integração. Tudo abaixo é como o sistema funciona hoje, sem data para mudar: planeje com isso. Mudança de contrato sai no changelog, com data.

  • A venda registrada pela API não vira pedido no painel. POST /vendas baixa o estoque, mas não cria pedido: não há separação, etiqueta nem NF-e para ela. Emita a nota e a etiqueta pelo seu sistema.
  • Pedido da Shopee pago e ainda não enviado, hoje, não está descontado do available. O pedido pago dos outros marketplaces (Mercado Livre, TikTok Shop, SHEIN, Magalu, Temu, Nuvemshop), com o item vinculado, reserva no saldo do armazém e já sai do available (entra em stock.reserved). O da Shopee costuma entrar sem essa reserva: fica no contador antigo do produto, e o stock.available de GET /produtos — e o que POST /vendas aceita — só cai quando ele é enviado. Ex.: 3 unidades, 3 pedidos Shopee pagos às 9h e despachados às 16h — das 9h às 16h a API ainda mostra 3 e aceita 3 vendas do site. A regra, para qualquer canal: o pedido com reserva active em GET /orders/{id}/stock-reservations já está fora do available. Num SKU com pouco estoque, desconte no seu sistema só os itens dos pedidos pagos e ainda não enviados que não têm reserva ativa (lidos em GET /orders, escopo read:orders), ou use uma margem fixa. Exceção: no SKU de cadastro antigo (sem saldo por armazém) o contador antigo já entra em stock.reserved — não desconte nada. (O Estoque mínimo da ficha do produto só entra no available do SKU de cadastro antigo; no SKU com saldo por armazém, mudá-lo no painel não muda o número.)
  • Não há webhook de estoque nem de pedido do marketplace: use os feeds por cursor (/estoque/mudancas, /produtos?updated_since, /orders) — veja o passo 4 do guia. O webhook de hoje avisa só as vendas, os cancelamentos e as devoluções feitos pela própria chave, fora da sua chamada (em geral em até ~1 minuto, com novas tentativas); as entregas de cada chave, com o motivo de cada falha, aparecem na tela Chaves de API.
  • A venda não reserva: ela baixa na hora. Não há "reservei agora, despacho depois" pela API.
  • Não cria nem edita produto (SKU, nome, preço, foto) e não transfere estoque entre armazéns: isso é feito no painel.
  • Não ajusta kit: o estoque do kit vem das peças; ajuste as peças. E o lote de ajustes não é tudo ou nada: cada item é gravado sozinho e o resultado vem por item.
  • Não liga o envio de estoque de uma loja. A API só informa (stock_push_enabled em channels e em GET /lojas); ligar é decisão do lojista no painel. Veja o checklist.
  • Não mostra o resultado do envio ao marketplace (se a Shopee aceitou o número): isso fica no painel, em Envio e estoque › Sincronização (a página "Sincronização de estoque").
  • Não é instantânea. Os feeds mostram o que foi gravado até 2 minutos atrás (o horizonte); é isso que garante que nada se perde entre as páginas. SKU de cadastro antigo, sem saldo por armazém, não aparece em /estoque/mudancas: o que muda nele chega pelo feed do catálogo, com até ~3 h de atraso em algumas gravações do painel, ou pela reconciliação diária.
  • Não há ambiente de teste (sandbox). Venda e ajuste de teste mexem no estoque real e vão para os marketplaces. Teste a escrita com um SKU de teste: crie no painel (Produtos e anúncios › Criar produto) um SKU que não tenha vínculo com anúncio e não seja peça de nenhum kit nem kit — a venda de uma peça atualiza o anúncio dos kits que a usam, mesmo sem vínculo próprio. Ele nasce com estoque 0: dê entrada nele (passo 7, type: "in") antes de vender (passo 5), e cancele a venda de teste depois.

Autenticação

Toda chamada (menos GET /openapi.json) leva a chave em um destes cabeçalhos:

HTTP — opção 1 (recomendada)
Authorization: Bearer lj_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
HTTP — opção 2
X-Api-Key: lj_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
  • Bearer vale em qualquer caixa (bearer, BEARER).
  • A API não usa cookie nem sessão: nenhuma resposta de /api/v1 traz Set-Cookie, e estar logado no painel não muda nada.
  • A ordem das checagens é: chave presente → chave existe, ativa e dentro da validade (401) → empresa ativa (403 COMPANY_SUSPENDED) → escopo (403 INSUFFICIENT_SCOPE) → cota do minuto (429). As recusas 401 e 403 não gastam cota.
  • Toda chave lê e escreve só os dados da própria empresa. SKU, pedido ou armazém de outra empresa responde como se não existisse.
cURL
curl -H "Authorization: Bearer $LOJEXA_API_KEY" \
     https://lojexa.com/api/v1/ping

Rate limit

  • Por chave, no minuto do relógio: 30, 60, 120, 300 chamadas por minuto, escolhido na criação (padrão 60), em qualquer plano (inclusive o Gratuito). O contador zera quando o minuto vira.
  • O que conta: só a chamada que passou pela chave, pela empresa e pelo escopo. 401, 403 INSUFFICIENT_SCOPE e 403 COMPANY_SUSPENDED não gastam cota.
  • Quanto custa sincronizar 1.000 SKUs: a carga inicial com per_page=100 são 10 chamadas; conferir 1.000 SKUs por ?skus= são 10 chamadas (100 por vez); depois, uma chamada a /estoque/mudancas a cada 1 a 5 minutos traz até 500 SKUs alterados.

Toda resposta contada traz os cabeçalhos:

CabeçalhoO que é
X-RateLimit-LimitChamadas permitidas por minuto para esta chave
X-RateLimit-RemainingQuantas ainda cabem neste minuto
X-RateLimit-ResetInstante Unix (segundos) em que o minuto vira e a cota zera
Retry-AfterNo 429 e no 409 BATCH_IN_PROGRESS (o lote de ajustes ainda gravando): segundos até poder repetir
X-Request-IdEm toda resposta, inclusive erro: mande ao suporte. É o mesmo de error.request_id

Se o contador estiver fora do ar, a chamada passa sem limite e os cabeçalhos X-RateLimit-* não saem: não dependa disso. No 429, espere o Retry-After e repita com backoff exponencial e jitter (2 s, 4 s, 8 s… mais um aleatório de até 1 s, até 60 s).

JSON — resposta 429
{
  "success": false,
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Rate limit excedido. Máximo 60 requisições/minuto. Tente de novo em 17 s.",
    "request_id": "8f14e45fceea167a5a36dedd4bea2543"
  }
}

Formato de resposta

Toda resposta de /api/ é JSON (Content-Type: application/json; charset=utf-8) — inclusive rota inexistente (404 ROUTE_NOT_FOUND), método errado (405 METHOD_NOT_ALLOWED, com o cabeçalho Allow) e falha interna (500 INTERNAL_ERROR, sem detalhe do banco). Corpo de POST que não é um objeto JSON válido recebe 400 INVALID_JSON.

  • Sucesso: {"success": true, "data": …, "meta": …}. meta só existe onde está na tabela abaixo. Nas escritas (vendas, estornos e ajustes), "already_processed" vem no topo, ao lado de success — true = a mesma chamada já tinha sido feita e nada foi gravado de novo.
  • Erro: {"success": false, "error": {"code", "message", "request_id", "details"}}. Decida pelo code (a tabela de erros); a message é para pessoas e pode mudar. details só vem quando há o que detalhar (ex.: INSUFFICIENT_STOCK, MAPPING_CONFLICT, STOCK_CHANGED).
  • Datas: sempre ISO 8601 com o fuso de Brasília, ex.: 2026-10-23T09:12:44-03:00; null quando não há data.
  • Números: preço e quantidade são números JSON, nunca texto. O id da variação no canal (platform_sku_id) vem como texto de dígitos: o do TikTok tem 19 dígitos, mais do que um número do JavaScript guarda sem arredondar.
  • Cursores (next_cursor) são opacos: guarde e devolva sem alterar.
  • X-Request-Id: toda resposta traz um. Se você mandar o seu (X-Request-Id, de 8 a 100 caracteres entre A-Z a-z 0-9 . _ : -), ele volta igual — útil para casar o seu log com o do suporte.
Endpointmeta
GET /produtos (lista), GET /mapeamentoscurrent_page, per_page, total, last_page (e status em /produtos)
GET /produtos?sku= / ?skus=requested, found, not_found
GET /produtos?updated_since=, /estoque/mudancas, /estoque/movimentos, /orderslimit, count, has_more, next_cursor, sync_horizon (e status no catálogo, warehouse em /estoque/mudancas)
GET /armazensdefault_warehouse_id
GET /ping, /uso, /produtos/{sku}, /lojas, /orders/{id}sem meta
JSON — erro (404 de um SKU que não existe)
{
  "success": false,
  "error": {
    "code": "PRODUCT_NOT_FOUND",
    "message": "Produto 'NAO-EXISTE' não encontrado.",
    "request_id": "8f14e45fceea167a5a36dedd4bea2543"
  }
}

Erros

Gerada do catálogo do servidor (ErrosDaApi): todo error.code que a API devolve está aqui. Repetir? diz se a MESMA chamada pode dar certo depois (com backoff). O que não é repetível só muda corrigindo a chamada, a chave ou o cadastro.

HTTPCódigoQuando aconteceRepetir?O que fazer
401 MISSING_API_KEY Nenhuma chave chegou: falta o cabeçalho Authorization: Bearer <chave> ou X-Api-Key: <chave>. Não Envie a chave em um dos dois cabeçalhos. "Bearer" pode vir em qualquer caixa.
401 INVALID_API_KEY A chave não existe (copiada errada, de outro ambiente) ou a empresa dela não existe mais. Não Confira a chave guardada na criação. Perdeu a chave? Crie outra no painel, em /configuracoes/api-keys (só administrador), e revogue a antiga.
401 API_KEY_REVOKED A chave foi revogada no painel. Não Crie uma chave nova no painel, em /configuracoes/api-keys (só administrador).
401 API_KEY_EXPIRED Passou o fim do dia de expiração escolhido na criação da chave. Não Crie uma chave nova (chave não se edita) e troque na sua integração.
403 COMPANY_SUSPENDED A empresa dona da chave está suspensa ou inativa na LOJEXA. Não Regularize a conta com o suporte LOJEXA. Repetir a chamada não resolve; ela não consome a cota.
403 INSUFFICIENT_SCOPE A chave não tem o escopo que o endpoint exige (a mensagem diz qual). Não Crie uma chave com o escopo (chave não se edita) e revogue a antiga. Essa recusa não consome a cota.
429 RATE_LIMIT_EXCEEDED A chave passou do limite de chamadas no minuto do relógio (escolhido na criação: 30, 60, 120 ou 300 nas chaves novas; o da sua chave está em GET /uso). Sim Espere os segundos de Retry-After (ou até X-RateLimit-Reset) e repita, com backoff exponencial e jitter.
404 ROUTE_NOT_FOUND O caminho não existe em /api/v1 (erro de digitação, versão, ou um "/" dentro do SKU — o servidor recusa %2F no caminho). Não Confira o caminho na documentação. SKU com "/" vai por GET /produtos?sku=<sku>.
405 METHOD_NOT_ALLOWED O caminho existe, mas não com esse método HTTP. Não Use um dos métodos do cabeçalho Allow da resposta.
401 UNAUTHORIZED A rota pediu uma autenticação que a chamada não trouxe (fora das portas da chave; os endpoints de hoje respondem MISSING_API_KEY e afins). Não Confira o caminho e a chave. Repetir igual não resolve; se persistir, mande o request_id ao suporte.
403 FORBIDDEN A rota recusou o acesso por uma regra que não é o escopo da chave (os endpoints de hoje respondem INSUFFICIENT_SCOPE ou COMPANY_SUSPENDED). Não Repetir igual não resolve; mande o request_id ao suporte.
400 / 409 / 422 REQUEST_REJECTED Recusa de uma camada antes do endpoint, sem código próprio (o status HTTP é o da recusa). Não Repetir igual não resolve; mande o request_id ao suporte.
400 INVALID_JSON O corpo do POST não é um objeto JSON válido (vírgula sobrando, aspas simples, texto solto, lista no lugar de objeto). Não Envie Content-Type: application/json e um objeto JSON, ex.: {"type": "in", "quantity": 1, "reason": "Compra"}.
422 INVALID_PARAMETER Parâmetro de consulta com tipo errado, fora do limite ou em combinação proibida (a mensagem diz qual). Não Corrija o parâmetro citado. Os limites de cada endpoint estão na tabela de parâmetros.
422 INVALID_CURSOR O cursor foi alterado, cortado ou veio de outro endpoint. Não Repasse meta.next_cursor exatamente como veio. Para recomeçar, use updated_since.
422 INVALID_FIELD Campo do corpo com tipo errado ou maior que o limite (a mensagem diz qual). Na venda: channel > 50, customer_name > 100, customer_email > 150 ou sem "@", unit_price negativo, reference com "/"; no estorno: reason > 255, condition fora de sellable/damaged; no ajuste: expected_on_hand que não é inteiro >= 0, warehouse que não é id nem code; no mapeamento: platform_sku > 100, platform_product_id > 100, listing_sku > 200, platform_sku_id que não é id numérico (texto de dígitos, até 19), store_id que não é inteiro positivo, quantity_factor fora de 1 a 10.000. Não Corrija o campo citado. Os limites de cada campo estão na tabela do endpoint.
500 INTERNAL_ERROR Falha inesperada no servidor; nada garante que foi gravado. Sim Repita com backoff só o que é seguro repetir (venda e estorno com a mesma reference, ajuste com a mesma Idempotency-Key, leituras, mapeamento) e mande ao suporte o error.request_id (o mesmo do cabeçalho X-Request-Id).
400 INVALID_SKU O SKU do caminho está vazio ou, decodificado, não é texto UTF-8. Não Codifique o SKU (JavaScript encodeURIComponent, Python quote(sku, safe=""), PHP rawurlencode).
404 PRODUCT_NOT_FOUND Nenhum SKU com esse código na empresa da chave (no detalhe e em /estoque/movimentos?sku=, ativo ou inativo; o inativo vem com status=inactive). Não Use o sku_code da LOJEXA (maiúsculas e minúsculas não importam).
422 WAREHOUSE_NOT_FOUND O warehouse da consulta (ou do corpo de POST /vendas e do ajuste, no corpo ou no item) não é o id nem o code de um armazém ativo da empresa da chave. No lote de ajustes, o warehouse padrão do lote recusa o lote inteiro; o do item, só o item. Não Liste os armazéns em GET /armazens e use o id ou o code. Sem warehouse, vale o armazém padrão da empresa.
404 ORDER_NOT_FOUND Pedido inexistente ou de outra empresa (a resposta é a mesma de propósito). Não Use o id que veio em GET /orders.
422 MISSING_REFERENCE Venda sem o campo "reference". Não Envie o id do pedido no seu sistema em "reference" (até 100 caracteres, sem "/").
422 REFERENCE_TOO_LONG "reference" com mais de 100 caracteres. Não Encurte a referência para até 100 caracteres.
400 INVALID_REFERENCE A referência do caminho está vazia ou, decodificada, não é texto UTF-8. Não Codifique a referência (encodeURIComponent / quote(ref, safe="")).
409 REFERENCE_CONFLICT A reference já tem uma venda com OUTRO pedido (outro SKU, quantidade ou warehouse) — ou a reversal_reference já foi usada nesta venda com outro estorno. Nada foi gravado. Não Não repita: se é outra venda, use outra reference; para ver a que existe, GET /vendas/{reference}. O reenvio do MESMO pedido não cai aqui: volta 200 already_processed.
422 MISSING_ITEMS "items" ausente, vazio ou que não é lista (na venda e no lote de ajustes; no estorno, "items" que não é lista). Não Envie ao menos um item {"sku": "...", "quantity": 1}. No estorno, omita "items" para estornar tudo.
422 TOO_MANY_ITEMS Mais de 50 itens na mesma venda (ou no mesmo estorno), ou mais de 500 no lote de ajustes. Não Junte as linhas do mesmo SKU (elas são somadas). Um pedido com mais de 50 SKUs diferentes: fale com o suporte — não divida o pedido em várias references. O lote de ajustes: divida em lotes de até 500, cada um com a sua Idempotency-Key.
422 INVALID_ITEM_SKU Item que não é objeto, sem "sku", ou com "sku" que não é texto (até 100 caracteres). No lote de ajustes, vira o erro daquele item. Não Envie o sku_code da LOJEXA como texto em cada item.
422 INVALID_ITEM_QTY Item com "quantity" que não é inteiro de 1 a 1.000.000 (2.5 e "3abc" não valem; 3, 3.0 e "3" valem 3). Não Envie "quantity" como inteiro positivo.
404 / 422 SKU_NOT_FOUND O SKU não existe ativo na empresa: 422 em POST /vendas (inexistente ou inativo; error.details.items lista todos, com status not_found ou inactive); 404 no ajuste de estoque (no lote, o erro do item) e no mapeamento. Não Confira o sku_code em GET /produtos (maiúsculas, minúsculas e acento não importam). SKU inativo não vende: tire do site.
422 INSUFFICIENT_STOCK Venda: o disponível no armazém da venda (o mesmo número de GET /produtos, no mesmo warehouse) é menor que o pedido. error.details.items traz, por SKU: warehouse, requested, required (o total do SKU na venda, contando kit e peça juntos), available e, no kit, components. Nada foi baixado. Ajuste "out" (perda, avaria, saída): maior que o disponível no armazém do ajuste; error.details.items traz warehouse, requested, available e on_hand. Não Não repita igual: atualize o estoque do seu site com o available devolvido e recuse a venda (ou venda só o que há). No ajuste, a reserva de pedido não sai por "out": para acertar o físico contado, use "type": "set".
409 STOCK_RACE_CONDITION Outra operação mexeu no mesmo estoque no mesmo instante (trava, deadlock ou a linha de saldo criada ao mesmo tempo). Nada foi gravado. Falta de estoque NÃO cai aqui: é 422 INSUFFICIENT_STOCK. Sim Repita a MESMA chamada (mesma reference; no ajuste, a mesma Idempotency-Key), com backoff. Se a outra chamada era a mesma venda (ou o mesmo ajuste), a repetição volta 200 already_processed.
500 TRANSACTION_FAILED A transação da venda falhou e foi desfeita (nada foi baixado). Sim Repita com a mesma reference; se persistir, mande o request_id ao suporte.
404 SALE_NOT_FOUND Nenhuma venda com essa reference nesta empresa (a reference diferencia maiúsculas: "a1B2" não acha "A1b2"). Não Use a reference exata enviada em POST /vendas, codificada no caminho.
409 INVALID_STATUS_FOR_CANCEL A venda está com status failed: nada foi baixado e não há o que estornar. Não Nada a fazer.
422 MISSING_REVERSAL_REFERENCE Cancelamento ou devolução PARCIAL (com "items") sem "reversal_reference". Não Envie em "reversal_reference" o id deste cancelamento/devolução no seu sistema (ex.: o número da troca). É ele que faz o reenvio não estornar duas vezes.
422 SKU_NOT_IN_SALE O SKU (ou o SKU naquele warehouse) do estorno parcial não está na venda. Não Use os SKUs de items[] de GET /vendas/{reference}. Kit se estorna pelo SKU do kit, não pelas peças.
422 REVERSAL_EXCEEDS_SALE O estorno pede mais unidades do que restam para estornar daquele SKU (vendidas menos as já estornadas). error.details.items traz sold, remaining e requested. Não Peça até remaining. GET /vendas/{reference} mostra reversed_quantity de cada item.
500 CANCEL_TRANSACTION_FAILED A transação do cancelamento ou da devolução falhou e foi desfeita (nada voltou ao estoque). Sim Repita a mesma chamada; se persistir, mande o request_id ao suporte.
422 INVALID_TYPE "type" diferente de "in" (entrada), "out" (saída) ou "set" (definir o físico contado). Não Envie "type": "in", "out" ou "set".
422 INVALID_QUANTITY "quantity" que não é inteiro de 1 a 1.000.000 (em "set", de 0 a 1.000.000: é o físico contado). 2.5 e "3abc" não valem. Não Envie "quantity" como inteiro.
422 INVALID_REASON_CODE "reason_code" fora da lista, ou que não combina com o "type": in aceita purchase, return, count, other; out aceita loss, damage, count, other; set aceita count, other. Não Use um reason_code da tabela do ajuste em /docs. Sem reason_code: in e out = other (com reason obrigatório), set = count.
422 MISSING_REASON Ajuste com "reason_code": "other" (ou sem reason_code em in/out) e sem "reason". Não Diga o motivo em "reason" (ex.: "Compra NF 123") ou use um reason_code (purchase, return, loss, damage, count).
422 REASON_TOO_LONG "reason" com mais de 255 caracteres. Não Encurte o motivo para até 255 caracteres.
422 KIT_NOT_ADJUSTABLE O SKU do ajuste é um KIT: o estoque do kit vem das peças (como na tela de estoque). error.details.components lista as peças. Não Ajuste cada peça (error.details.components). O disponível do kit acompanha.
409 STOCK_CHANGED O "expected_on_hand" do ajuste não é o físico de agora no armazém: o estoque mudou desde a sua leitura (uma venda, um pedido). error.details traz on_hand e available atuais. Nada foi gravado. Não Não repita igual: confira a contagem com o on_hand devolvido e mande de novo com o expected_on_hand atual (ou sem ele, para gravar o "set" mesmo assim).
400 INVALID_IDEMPOTENCY_KEY Cabeçalho Idempotency-Key com mais de 100 caracteres, espaço ou caractere fora do ASCII visível. Não Use um UUID ou um id seu (A-Z a-z 0-9 e pontuação, sem espaço), até 100 caracteres.
400 MISSING_IDEMPOTENCY_KEY POST /estoque/ajustes (lote) sem o cabeçalho Idempotency-Key: no lote ele é obrigatório. Não Envie Idempotency-Key: <um id do lote no seu sistema, ou um UUID>. Guarde-o: é ele que torna o reenvio seguro.
409 IDEMPOTENCY_MISMATCH A Idempotency-Key já foi usada nesta empresa com OUTRO ajuste (ou outro lote): SKU, type, quantity, warehouse, reason_code, reason ou expected_on_hand diferentes. Nada foi gravado. Não Não repita: para um ajuste novo, use outra chave. O reenvio do MESMO ajuste não cai aqui: volta 200 already_processed com o resultado original.
409 BATCH_IN_PROGRESS O lote desta Idempotency-Key ainda está sendo gravado por outra chamada (a primeira, que você abandonou por timeout). Sim Repita a MESMA chamada depois do Retry-After: quando o lote terminar, ela devolve 200 already_processed com o resultado de cada item.
500 STOCK_ADJUST_FAILED O ajuste falhou e foi desfeito (nada foi gravado). Sim Repita com a mesma Idempotency-Key; se persistir, mande o request_id ao suporte.
422 MISSING_SKU Mapeamento sem "sku". Não Envie o sku_code da LOJEXA em "sku".
422 MISSING_PLATFORM Mapeamento sem "platform". Não Envie o canal em "platform" (ex.: shopee).
422 MISSING_PLATFORM_SKU Mapeamento sem "platform_sku". Não Envie o código do anúncio no canal em "platform_sku".
422 INVALID_PLATFORM Canal que a API não aceita em "platform". Desde a v1.4 (24/10/2026), "api", "fisica" e "outro" foram removidos: nada no sistema lia esse vínculo. Não Use um dos canais do envio de estoque: shopee, mercadolivre, magalu, nuvemshop, shopify, amazon, tiktok, shein ou temu.
422 MISSING_STORE Mapeamento de shopee, mercadolivre, tiktok, shein, magalu ou nuvemshop sem "store_id": vínculo sem loja nunca recebe estoque nesses canais. Não Envie o id da loja de GET /lojas (na Shopee, o shop_id também vale).
404 STORE_NOT_FOUND A loja informada em "store_id" não é desta empresa nesse canal. Não Use o "store_id" de GET /lojas (na Shopee, o shop_id também vale).
409 MAPPING_CONFLICT O anúncio (o mesmo platform_sku na loja, ou a mesma variação) já está ligado a OUTRO SKU. error.details diz o vínculo e o SKU dono. Nada foi gravado. Não Repetir não resolve. Se o vínculo antigo está errado, remova-o (DELETE /mapeamentos/{error.details.mapping_id}) e crie de novo; se está certo, use outro platform_sku.
400 INVALID_ID Id do mapeamento no caminho não é inteiro positivo. Não Use o "id" que veio em GET /mapeamentos.
404 MAPPING_NOT_FOUND Mapeamento inexistente ou de outra empresa. Não Liste em GET /mapeamentos e use o "id" de lá.

Exemplos reais

JSON — 401 sem chave
{
  "success": false,
  "error": {
    "code": "MISSING_API_KEY",
    "message": "API key ausente. Envie via Authorization: Bearer <key> ou X-Api-Key: <key>.",
    "request_id": "8f14e45fceea167a5a36dedd4bea2543"
  }
}
JSON — 403 chave sem o escopo (só read:orders chamando /produtos)
{
  "success": false,
  "error": {
    "code": "INSUFFICIENT_SCOPE",
    "message": "Scope obrigatório ausente: read:products.",
    "request_id": "8f14e45fceea167a5a36dedd4bea2543"
  }
}
JSON — 422 parâmetro fora do limite (per_page=200)
{
  "success": false,
  "error": {
    "code": "INVALID_PARAMETER",
    "message": "per_page deve ser um inteiro de 1 a 100.",
    "request_id": "8f14e45fceea167a5a36dedd4bea2543"
  }
}
JSON — 422 armazém que não é da empresa (warehouse=RJ)
{
  "success": false,
  "error": {
    "code": "WAREHOUSE_NOT_FOUND",
    "message": "warehouse \"RJ\" não é um armazém ativo desta empresa. Use o id ou o code de GET /armazens: PE (id 1), SP (id 2).",
    "request_id": "8f14e45fceea167a5a36dedd4bea2543"
  }
}
JSON — 404 caminho que não existe (/api/v1/produto)
{
  "success": false,
  "error": {
    "code": "ROUTE_NOT_FOUND",
    "message": "Rota não encontrada: GET /api/v1/produto. Confira o caminho na documentação (/docs). SKU com \"/\" não cabe no caminho: use GET /api/v1/produtos?sku=<sku>.",
    "request_id": "8f14e45fceea167a5a36dedd4bea2543"
  }
}

Guia ponta a ponta: do zero à integração em produção

Este guia liga um site (ou ERP, ou programa) à LOJEXA do começo ao fim: criar a chave, carregar o catálogo, manter o estoque igual, avisar as vendas, estornar, dar entrada de mercadoria, ler os pedidos dos marketplaces e receber os webhooks. Cada passo tem o código em cURL, Python, Node.js (no servidor) e PHP — escolha a linguagem uma vez e todas as abas da página mudam juntas.

Este código roda. A cada mudança da API, um teste automático executa o texto exato desta página, nas quatro linguagens, contra a própria API, com a empresa de exemplo dos exemplos de resposta (a "Loja da Maria": CAMISETA-M-AZUL, o kit KIT-CAMISETA-2, os armazéns PE e SP). A "Saída" de cada passo é o que ele imprimiu.
  • Como o código está organizado: o passo 1 é um cliente pequeno (lojexa.py, lojexa.mjs ou lojexa.php) com timeout, retentativa segura e o tratamento de erro. Os passos 2 a 10 são arquivos que usam esse cliente. No cURL, cada passo é um script bash com as chamadas uma a uma.
  • O que você precisa: uma conta na LOJEXA (qualquer plano, inclusive o Gratuito), acesso de administrador e um servidor onde o seu código roda. Python 3.8+ com requests (pip install requests; no Windows, rode sempre com python -X utf8, inclusive no Agendador de Tarefas: com a saída indo para um arquivo ou log, o print de um SKU com letra fora do cp1252 derruba o programa — os arquivos já são gravados em UTF-8), Node.js 18+ ou PHP 8.1+ com a extensão cURL.
  • Não há ambiente de teste: as vendas e os ajustes dos passos 5 a 7 mexem no estoque real. Rode-os primeiro com um SKU de teste sem vínculo com anúncio, que não seja peça de kit nem kit (troque os SKUs do exemplo pelos seus). Ele nasce com 0 no painel: rode o passo 7 (entrada) antes do passo 5 (venda), senão a venda dá 422 INSUFFICIENT_STOCK. Veja o que a API não faz.

1. Criar a chave e o cliente

  1. No painel, como administrador, abra /configuracoes/api-keys (no menu: Canais → Chaves de API) → Criar chave. Nenhum escopo vem marcado: marque só os de que a integração precisa. Para tudo deste guia: read:products, write:sales, write:stock e read:orders (veja qual escopo para qual caso). manage:mappings só se for vincular anúncios pela API.
  2. Limite por minuto: 30, 60, 120, 300 (padrão 60). 60 dá folga para este guia inteiro com milhares de SKUs.
  3. Webhook URL (opcional, para o passo 9): o endereço https:// público do seu receptor. Deixe o Webhook Secret em branco para a LOJEXA gerar um forte.
  4. A chave (lj_live_…) e o secret aparecem UMA vez, logo depois de criar. Copie e guarde no ambiente do servidor: LOJEXA_API_KEY e LOJEXA_WEBHOOK_SECRET (no Environment= do systemd, nas variáveis do container ou do painel da hospedagem, num cofre de segredos). Nunca no código-fonte, no Git, no navegador ou em app distribuído. Perdeu? Crie outra chave e revogue a antiga.
  5. Salve o cliente abaixo ao lado dos outros passos. Ele lê LOJEXA_API_KEY e, se existir, LOJEXA_API_BASE (padrão https://lojexa.com/api/v1; em produção, não defina).

O que o cliente faz em cada resposta:

RespostaO cliente
200 / 201Devolve o JSON ({"success": true, "data": …}).
429 RATE_LIMIT_EXCEEDEDEspera os segundos de Retry-After (mais um aleatório) e repete a mesma chamada.
409 STOCK_RACE_CONDITION / 409 BATCH_IN_PROGRESSNada foi gravado: espera (2 s, 4 s, 8 s… com jitter, até 60 s) e repete igual.
5xx, timeout (30 s) ou queda de redeRepete igual só quando é seguro: leitura, venda e estorno (a reference não deixa baixar duas vezes), ajuste com Idempotency-Key e mapeamento. Ajuste sem a chave nunca é repetido.
3xx e os outros 4xxLança ErroDaLojexa com status, code, details e o X-Request-Id. Repetir igual não resolve: o seu código decide pelo code (passo 10).

Toda chamada leva um X-Request-Id gerado pelo cliente, o mesmo em todas as tentativas: o servidor devolve igual, e o suporte acha todas as tentativas por ele.

bash — cURL (variáveis de ambiente e a primeira chamada)
# Passo 1: a chave e o secret ficam no AMBIENTE do servidor, nunca no código, no Git ou no navegador.
#   export LOJEXA_API_KEY='lj_live_...'        (a chave aparece uma vez, logo depois de criar)
#   export LOJEXA_WEBHOOK_SECRET='whsec_...'   (se a chave tiver Webhook URL)
BASE="${LOJEXA_API_BASE:-https://lojexa.com/api/v1}"

# Toda chamada: só https, timeout de 30 s, sem seguir redirect (nunca use -L) e com o código HTTP no fim.
curl -sS --max-time 30 -w '\nHTTP %{http_code}\n' \
     -H "Authorization: Bearer $LOJEXA_API_KEY" \
     "$BASE/ping"
lojexa.py — Python 3 + requests
"""Passo 1 do guia: o cliente da API da LOJEXA (Python 3, no SERVIDOR). Salve como lojexa.py.

A chave e o secret ficam no AMBIENTE do servidor, nunca no código, no Git ou no navegador:
    export LOJEXA_API_KEY=lj_live_...
    export LOJEXA_WEBHOOK_SECRET=whsec_...
"""
import os
import random
import time
import uuid
from urllib.parse import quote

import requests  # pip install requests

BASE = os.environ.get('LOJEXA_API_BASE', 'https://lojexa.com/api/v1')
SESSAO = requests.Session()
SESSAO.headers.update({
    'Authorization': f"Bearer {os.environ['LOJEXA_API_KEY']}",
    'Accept': 'application/json',
})
# O 429 e os 409 que passam repetindo (nada foi gravado): o cliente espera e repete.
RETENTAVEIS = {'RATE_LIMIT_EXCEEDED', 'STOCK_RACE_CONDITION', 'BATCH_IN_PROGRESS'}


class ErroDaLojexa(Exception):
    """Resposta de erro da API. Decida pelo code, nunca pela mensagem."""

    def __init__(self, status, corpo, request_id):
        erro = (corpo or {}).get('error') or {}
        self.status = status
        self.code = erro.get('code')
        self.details = erro.get('details')
        self.request_id = request_id  # mande ao suporte
        super().__init__(f"{status} {self.code}: {erro.get('message')} (X-Request-Id {request_id})")


def segmento(texto):
    """SKU ou reference dentro do caminho: codifique (espaço, acento, parênteses...)."""
    return quote(str(texto), safe='')


def chamar(metodo, caminho, params=None, corpo=None, idempotency_key=None, tentativas=6):
    """Uma chamada com timeout de 30 s e sem seguir redirect. Devolve o JSON do 200/201.

    Repete a MESMA chamada (mesmo corpo, mesmas chaves), com backoff exponencial e jitter,
    no 429, no 409 retentável e, quando repetir é seguro, no 5xx, no timeout e na queda de rede.
    Qualquer outro erro vira ErroDaLojexa: repetir igual não resolve.
    """
    # Repetir é seguro na leitura, na venda e no estorno (a reference deduplica), no ajuste
    # COM Idempotency-Key e no mapeamento (é upsert). Ajuste SEM a chave: nunca.
    repetivel = metodo == 'GET' or idempotency_key is not None or not caminho.startswith('/estoque/')
    cabecalhos = {'X-Request-Id': uuid.uuid4().hex}  # o mesmo em toda tentativa: o suporte acha todas
    if idempotency_key is not None:
        cabecalhos['Idempotency-Key'] = idempotency_key
    for tentativa in range(1, tentativas + 1):
        espera = min(2 ** tentativa, 60) * (0.5 + random.random())  # ~2, 4, 8... s
        try:
            r = SESSAO.request(metodo, BASE + caminho, params=params, json=corpo, headers=cabecalhos,
                               timeout=30, allow_redirects=False)
        except requests.RequestException:
            if not repetivel or tentativa == tentativas:
                raise
            time.sleep(espera)
            continue
        dados = r.json() if 'json' in r.headers.get('Content-Type', '') else None
        if r.status_code in (200, 201):
            return dados
        erro = ErroDaLojexa(r.status_code, dados, r.headers.get('X-Request-Id'))
        if not (erro.code in RETENTAVEIS or (r.status_code >= 500 and repetivel)) or tentativa == tentativas:
            raise erro
        if r.headers.get('Retry-After'):
            espera = int(r.headers['Retry-After']) + random.random()  # o que o servidor pediu
        time.sleep(espera)
lojexa.mjs — Node.js 18+ (servidor)
// Passo 1 do guia: o cliente da API da LOJEXA (Node 18+, no SERVIDOR). Salve como lojexa.mjs.
// A chave e o secret ficam no AMBIENTE do servidor, nunca no código, no Git ou no navegador:
//   export LOJEXA_API_KEY=lj_live_...
//   export LOJEXA_WEBHOOK_SECRET=whsec_...
import { randomUUID } from 'node:crypto';

const BASE = process.env.LOJEXA_API_BASE ?? 'https://lojexa.com/api/v1';
const CHAVE = process.env.LOJEXA_API_KEY;
if (!CHAVE) throw new Error('Defina LOJEXA_API_KEY no ambiente do servidor.');
// O 429 e os 409 que passam repetindo (nada foi gravado): o cliente espera e repete.
const RETENTAVEIS = new Set(['RATE_LIMIT_EXCEEDED', 'STOCK_RACE_CONDITION', 'BATCH_IN_PROGRESS']);
const dormir = (ms) => new Promise((ok) => setTimeout(ok, ms));

/** Resposta de erro da API. Decida pelo code, nunca pela mensagem. */
export class ErroDaLojexa extends Error {
  constructor(status, corpo, requestId) {
    const erro = corpo?.error ?? {};
    super(`${status} ${erro.code}: ${erro.message} (X-Request-Id ${requestId})`);
    this.status = status;
    this.code = erro.code;
    this.details = erro.details;
    this.requestId = requestId; // mande ao suporte
  }
}

/** SKU ou reference dentro do caminho: codifique (espaço, acento, parênteses...). */
export const segmento = (texto) => encodeURIComponent(String(texto));

/**
 * Uma chamada com timeout de 30 s e sem seguir redirect. Devolve o JSON do 200/201.
 * Repete a MESMA chamada (mesmo corpo, mesmas chaves), com backoff exponencial e jitter,
 * no 429, no 409 retentável e, quando repetir é seguro, no 5xx, no timeout e na queda de rede.
 * Qualquer outro erro vira ErroDaLojexa: repetir igual não resolve.
 */
export async function chamar(metodo, caminho, { params, corpo, idempotencyKey, tentativas = 6 } = {}) {
  // Repetir é seguro na leitura, na venda e no estorno (a reference deduplica), no ajuste
  // COM Idempotency-Key e no mapeamento (é upsert). Ajuste SEM a chave: nunca.
  const repetivel = metodo === 'GET' || idempotencyKey !== undefined || !caminho.startsWith('/estoque/');
  const cabecalhos = {
    Authorization: `Bearer ${CHAVE}`,
    Accept: 'application/json',
    'X-Request-Id': randomUUID().replaceAll('-', ''), // o mesmo em toda tentativa: o suporte acha todas
  };
  if (idempotencyKey !== undefined) cabecalhos['Idempotency-Key'] = idempotencyKey;
  if (corpo !== undefined) cabecalhos['Content-Type'] = 'application/json';
  const url = BASE + caminho + (params ? `?${new URLSearchParams(params)}` : '');
  for (let tentativa = 1; ; tentativa++) {
    let espera = Math.min(2 ** tentativa, 60) * (0.5 + Math.random()) * 1000; // ~2, 4, 8... s
    let r;
    try {
      r = await fetch(url, {
        method: metodo,
        headers: cabecalhos,
        body: corpo === undefined ? undefined : JSON.stringify(corpo),
        redirect: 'manual',
        signal: AbortSignal.timeout(30_000),
      });
    } catch (falha) { // timeout ou queda de rede
      if (!repetivel || tentativa >= tentativas) throw falha;
      await dormir(espera);
      continue;
    }
    const dados = (r.headers.get('content-type') ?? '').includes('json') ? await r.json() : null;
    if (r.status === 200 || r.status === 201) return dados;
    const erro = new ErroDaLojexa(r.status, dados, r.headers.get('x-request-id'));
    if (!(RETENTAVEIS.has(erro.code) || (r.status >= 500 && repetivel)) || tentativa >= tentativas) throw erro;
    if (r.headers.get('retry-after')) espera = (Number(r.headers.get('retry-after')) + Math.random()) * 1000;
    await dormir(espera);
  }
}
lojexa.php — PHP 8.1+ cURL
<?php
// Passo 1 do guia: o cliente da API da LOJEXA (PHP 8.1+, no SERVIDOR). Salve como lojexa.php.
// A chave e o secret ficam no AMBIENTE do servidor, nunca no código, no Git ou no navegador:
//   LOJEXA_API_KEY=lj_live_...   LOJEXA_WEBHOOK_SECRET=whsec_...
declare(strict_types=1);

/** Resposta de erro da API. Decida pelo código ($codigo), nunca pela mensagem. */
final class ErroDaLojexa extends RuntimeException
{
    public function __construct(
        public readonly int $status,
        public readonly ?string $codigo,
        public readonly ?array $details,
        public readonly ?string $requestId, // mande ao suporte
        string $mensagem,
    ) {
        parent::__construct("{$status} {$codigo}: {$mensagem} (X-Request-Id {$requestId})");
    }
}

/** SKU ou reference dentro do caminho: codifique (espaço, acento, parênteses...). */
function segmento(string $texto): string
{
    return rawurlencode($texto);
}

/**
 * Uma chamada com timeout de 30 s e sem seguir redirect. Devolve o JSON do 200/201.
 * Repete a MESMA chamada (mesmo corpo, mesmas chaves), com backoff exponencial e jitter,
 * no 429, no 409 retentável e, quando repetir é seguro, no 5xx, no timeout e na queda de rede.
 * Qualquer outro erro vira ErroDaLojexa: repetir igual não resolve.
 */
function chamar(string $metodo, string $caminho, array $params = [], ?array $corpo = null, ?string $idempotencyKey = null, int $tentativas = 6): array
{
    $base = getenv('LOJEXA_API_BASE') ?: 'https://lojexa.com/api/v1';
    // Repetir é seguro na leitura, na venda e no estorno (a reference deduplica), no ajuste
    // COM Idempotency-Key e no mapeamento (é upsert). Ajuste SEM a chave: nunca.
    $repetivel = $metodo === 'GET' || $idempotencyKey !== null || !str_starts_with($caminho, '/estoque/');
    $cabecalhos = [
        'Authorization: Bearer ' . getenv('LOJEXA_API_KEY'),
        'Accept: application/json',
        'X-Request-Id: ' . bin2hex(random_bytes(16)), // o mesmo em toda tentativa: o suporte acha todas
    ];
    if ($idempotencyKey !== null) {
        $cabecalhos[] = 'Idempotency-Key: ' . $idempotencyKey;
    }
    if ($corpo !== null) {
        $cabecalhos[] = 'Content-Type: application/json';
    }
    $url = $base . $caminho . ($params !== [] ? '?' . http_build_query($params) : '');

    for ($tentativa = 1; ; $tentativa++) {
        $espera = min(2 ** $tentativa, 60) * (0.5 + mt_rand() / mt_getrandmax()); // ~2, 4, 8... s
        $recebidos = [];
        $ch = curl_init($url);
        curl_setopt_array($ch, [
            CURLOPT_CUSTOMREQUEST  => $metodo,
            CURLOPT_RETURNTRANSFER => true,
            CURLOPT_TIMEOUT        => 30,
            CURLOPT_FOLLOWLOCATION => false,
            CURLOPT_HTTPHEADER     => $cabecalhos,
            CURLOPT_HEADERFUNCTION => static function ($ch, string $linha) use (&$recebidos): int {
                if (str_contains($linha, ':')) {
                    [$nome, $valor] = explode(':', $linha, 2);
                    $recebidos[strtolower(trim($nome))] = trim($valor);
                }

                return strlen($linha);
            },
        ]);
        if ($corpo !== null) {
            curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($corpo, JSON_UNESCAPED_UNICODE | JSON_THROW_ON_ERROR));
        }
        $texto = curl_exec($ch);
        $status = (int) curl_getinfo($ch, CURLINFO_RESPONSE_CODE); // 0 = timeout ou queda de rede

        if ($status === 0) {
            if (!$repetivel || $tentativa >= $tentativas) {
                throw new RuntimeException('Sem resposta da LOJEXA (timeout ou rede).');
            }
            usleep((int) ($espera * 1_000_000));
            continue;
        }
        $dados = json_decode((string) $texto, true);
        if ($status === 200 || $status === 201) {
            return $dados;
        }
        $erro = is_array($dados) ? ($dados['error'] ?? []) : [];
        $e = new ErroDaLojexa($status, $erro['code'] ?? null, $erro['details'] ?? null, $recebidos['x-request-id'] ?? null, (string) ($erro['message'] ?? ''));
        $retentavel = in_array($e->codigo, ['RATE_LIMIT_EXCEEDED', 'STOCK_RACE_CONDITION', 'BATCH_IN_PROGRESS'], true);
        if (!($retentavel || ($status >= 500 && $repetivel)) || $tentativa >= $tentativas) {
            throw $e;
        }
        if (isset($recebidos['retry-after'])) {
            $espera = (int) $recebidos['retry-after'] + mt_rand() / mt_getrandmax(); // o que o servidor pediu
        }
        usleep((int) ($espera * 1_000_000));
    }
}

2. Testar a chave

GET /ping devolve a empresa e os escopos da chave; GET /uso, o limite por minuto, quanto já foi usado e se há webhook. Nenhum dos dois pede escopo nem mexe em nada. Confira que a empresa é a sua e que não falta escopo — o 403 INSUFFICIENT_SCOPE da primeira chamada de verdade costuma ser isso.

bash — cURL
# Passo 2: testar a chave (empresa e escopos) e ver o limite. Qualquer chave ativa.
BASE="${LOJEXA_API_BASE:-https://lojexa.com/api/v1}"
AUTH="Authorization: Bearer $LOJEXA_API_KEY"

curl -sS --max-time 30 -w '\nHTTP %{http_code}\n' -H "$AUTH" "$BASE/ping"

# -i mostra os cabeçalhos: X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset e X-Request-Id.
curl -sS --max-time 30 -i -H "$AUTH" "$BASE/uso"
echo
Python 3 — requests
"""Passo 2: testar a chave (GET /ping) e ver o limite (GET /uso). Qualquer chave ativa."""
from lojexa import chamar

PRECISO = {'read:products', 'write:sales', 'write:stock', 'read:orders'}  # os escopos deste guia

ping = chamar('GET', '/ping')['data']
print('Empresa:', ping['company'])
faltam = PRECISO - set(ping['scopes'])
print('Escopos:', ', '.join(sorted(ping['scopes'])), '| faltam:', ', '.join(sorted(faltam)) or 'nenhum')

uso = chamar('GET', '/uso')['data']
print(f"Limite: {uso['rate_limit']['per_minute']} chamadas por minuto")
print('Webhook configurado:', 'sim' if uso['webhook_configured'] else 'não')
Node.js 18+ — fetch nativo (servidor)
// Passo 2: testar a chave (GET /ping) e ver o limite (GET /uso). Qualquer chave ativa.
// Salve como passo2.mjs, ao lado do lojexa.mjs, e rode: node passo2.mjs (o import pede a extensão .mjs).
import { chamar } from './lojexa.mjs';

const PRECISO = ['read:products', 'write:sales', 'write:stock', 'read:orders']; // os escopos deste guia

const ping = (await chamar('GET', '/ping')).data;
console.log('Empresa:', ping.company);
const faltam = PRECISO.filter((escopo) => !ping.scopes.includes(escopo)).sort();
console.log('Escopos:', [...ping.scopes].sort().join(', '), '| faltam:', faltam.join(', ') || 'nenhum');

const uso = (await chamar('GET', '/uso')).data;
console.log(`Limite: ${uso.rate_limit.per_minute} chamadas por minuto`);
console.log('Webhook configurado:', uso.webhook_configured ? 'sim' : 'não');
PHP 8.1+ — cURL
<?php
// Passo 2: testar a chave (GET /ping) e ver o limite (GET /uso). Qualquer chave ativa.
require __DIR__ . '/lojexa.php';

$preciso = ['read:products', 'write:sales', 'write:stock', 'read:orders']; // os escopos deste guia

$ping = chamar('GET', '/ping')['data'];
echo 'Empresa: ', $ping['company'], PHP_EOL;
$escopos = $ping['scopes'];
sort($escopos);
$faltam = array_diff($preciso, $escopos);
sort($faltam);
echo 'Escopos: ', implode(', ', $escopos), ' | faltam: ', $faltam !== [] ? implode(', ', $faltam) : 'nenhum', PHP_EOL;

$uso = chamar('GET', '/uso')['data'];
echo "Limite: {$uso['rate_limit']['per_minute']} chamadas por minuto", PHP_EOL;
echo 'Webhook configurado: ', $uso['webhook_configured'] ? 'sim' : 'não', PHP_EOL;
Saída (Python, Node.js e PHP imprimem o mesmo)
Empresa: Loja da Maria
Escopos: read:orders, read:products, write:sales, write:stock | faltam: nenhum
Limite: 60 chamadas por minuto
Webhook configurado: sim

3. Carga inicial do catálogo e do estoque

  1. Pegue os dois cursores ANTES da carga: GET /estoque/mudancas?updated_since=<agora> e GET /produtos?updated_since=<agora>&fields=stock. Eles vêm vazios, com meta.next_cursor 2 minutos atrás: o que mudar durante a carga entra no passo 4, nada se perde.
  2. Leia todas as páginas de GET /produtos?fields=stock&status=all&per_page=100, de page=1 até meta.last_page. fields=stock deixa a resposta leve (sem catálogo nem imagens); status=all traz os inativos (com available 0) para você saber que saíram.
  3. Grave pelo sku_master_id: o sku_code pode ser trocado na ficha do produto; o id não muda. O número a mostrar e vender é stock.available (o que cada número quer dizer) — o mesmo que a venda do passo 5 aceita. Ele já desconta o pedido pago que reservou no armazém (stock.reserved), mas não o pedido da Shopee pago e ainda não enviado que entrou sem reserva (veja por quê e como descontar): num SKU com pouco estoque, desconte você só esses.
  4. Reescreva o seu cadastro inteiro com o que veio: o SKU que não veio foi apagado ou renomeado.
  5. Refaça este passo uma vez por dia (a reconciliação). Ela cobre o que o feed não registra: o contador de SKU sem saldo por armazém, o estoque inicial trazido do anúncio, a receita de kit, o estoque de segurança e a troca do armazém padrão.

Vende de outro armazém que não o padrão? Passe warehouse=<code> (GET /armazens) aqui, no passo 4 e na venda. Custo: 1.000 SKUs = 10 chamadas. SKU com / no código? Consulte por ?sku= (identificar o SKU).

bash — cURL
# Passo 3: carga inicial do catálogo e do estoque (read:products). Refaça uma vez por dia.
BASE="${LOJEXA_API_BASE:-https://lojexa.com/api/v1}"
AUTH="Authorization: Bearer $LOJEXA_API_KEY"

# 1. ANTES da carga, os dois cursores: vêm vazios, com meta.next_cursor 2 min atrás. Guarde os dois.
AGORA=$(date -u +%Y-%m-%dT%H:%M:%SZ)
curl -sS --max-time 30 -w '\nHTTP %{http_code}\n' -H "$AUTH" "$BASE/estoque/mudancas?updated_since=$AGORA"
curl -sS --max-time 30 -w '\nHTTP %{http_code}\n' -H "$AUTH" "$BASE/produtos?updated_since=$AGORA&fields=stock"

# 2. Página por página, de page=1 até meta.last_page, com os inativos (status=all).
#    Grave cada SKU pelo sku_master_id (o sku_code pode ser trocado na ficha) e, no fim,
#    apague no seu sistema o que não veio.
curl -sS --max-time 30 -w '\nHTTP %{http_code}\n' -H "$AUTH" \
     "$BASE/produtos?fields=stock&status=all&per_page=100&page=1"
Python 3 — requests
"""Passo 3: carga inicial do catálogo e do estoque (read:products).

Rode uma vez e, depois, uma vez por dia: é a reconciliação, que cobre o que os feeds não trazem.
"""
import json
import pathlib
from datetime import datetime, timezone

from lojexa import chamar

BANCO = pathlib.Path('estoque_local.json')  # no seu sistema, uma tabela
CURSORES = pathlib.Path('lojexa_cursores.json')


def gravar(caminho, valor):
    """Grava num arquivo temporário e troca: uma falha no meio não deixa o arquivo vazio."""
    temporario = caminho.with_suffix('.tmp')
    temporario.write_text(json.dumps(valor, ensure_ascii=False), encoding='utf-8')
    temporario.replace(caminho)

# 1. Os cursores ANTES da carga: o que mudar durante ela entra no passo 4.
agora = datetime.now(timezone.utc).strftime('%Y-%m-%dT%H:%M:%SZ')
cursores = {
    'estoque': chamar('GET', '/estoque/mudancas', {'updated_since': agora})['meta']['next_cursor'],
    'catalogo': chamar('GET', '/produtos', {'updated_since': agora, 'fields': 'stock'})['meta']['next_cursor'],
}

# 2. Todas as páginas, com os inativos (status=all), 100 por vez.
banco, pagina = {}, 1
while True:
    corpo = chamar('GET', '/produtos', {'fields': 'stock', 'status': 'all', 'per_page': 100, 'page': pagina})
    for p in corpo['data']:
        # Pelo sku_master_id: o sku_code pode ser trocado na ficha; o id não muda.
        banco[str(p['sku_master_id'])] = {'sku': p['sku_code'], 'status': p['status'], 'disponivel': p['stock']['available']}
        print(p['sku_code'], p['status'], p['stock']['available'])
    if pagina >= corpo['meta']['last_page']:
        break
    pagina += 1

# 3. O banco é reescrito inteiro: o SKU que não veio (apagado ou renomeado) sai.
gravar(BANCO, banco)
gravar(CURSORES, cursores)
print(f'Carga: {len(banco)} SKUs')
Node.js 18+ — fetch nativo (servidor)
// Passo 3: carga inicial do catálogo e do estoque (read:products).
// Salve como passo3.mjs, ao lado do lojexa.mjs, e rode: node passo3.mjs (o import pede a extensão .mjs).
// Rode uma vez e, depois, uma vez por dia: é a reconciliação, que cobre o que os feeds não trazem.
import { writeFile } from 'node:fs/promises';
import { chamar } from './lojexa.mjs';

const BANCO = 'estoque_local.json'; // no seu sistema, uma tabela
const CURSORES = 'lojexa_cursores.json';

// 1. Os cursores ANTES da carga: o que mudar durante ela entra no passo 4.
const agora = new Date().toISOString().slice(0, 19) + 'Z';
const cursores = {
  estoque: (await chamar('GET', '/estoque/mudancas', { params: { updated_since: agora } })).meta.next_cursor,
  catalogo: (await chamar('GET', '/produtos', { params: { updated_since: agora, fields: 'stock' } })).meta.next_cursor,
};

// 2. Todas as páginas, com os inativos (status=all), 100 por vez.
const banco = {};
for (let pagina = 1; ; pagina++) {
  const corpo = await chamar('GET', '/produtos', { params: { fields: 'stock', status: 'all', per_page: 100, page: pagina } });
  for (const p of corpo.data) {
    // Pelo sku_master_id: o sku_code pode ser trocado na ficha; o id não muda.
    banco[p.sku_master_id] = { sku: p.sku_code, status: p.status, disponivel: p.stock.available };
    console.log(p.sku_code, p.status, p.stock.available);
  }
  if (pagina >= corpo.meta.last_page) break;
}

// 3. O banco é reescrito inteiro: o SKU que não veio (apagado ou renomeado) sai.
await writeFile(BANCO, JSON.stringify(banco));
await writeFile(CURSORES, JSON.stringify(cursores));
console.log(`Carga: ${Object.keys(banco).length} SKUs`);
PHP 8.1+ — cURL
<?php
// Passo 3: carga inicial do catálogo e do estoque (read:products).
// Rode uma vez e, depois, uma vez por dia: é a reconciliação, que cobre o que os feeds não trazem.
require __DIR__ . '/lojexa.php';

const BANCO = __DIR__ . '/estoque_local.json'; // no seu sistema, uma tabela
const CURSORES = __DIR__ . '/lojexa_cursores.json';

// 1. Os cursores ANTES da carga: o que mudar durante ela entra no passo 4.
$agora = gmdate('Y-m-d\TH:i:s\Z');
$cursores = [
    'estoque'  => chamar('GET', '/estoque/mudancas', ['updated_since' => $agora])['meta']['next_cursor'],
    'catalogo' => chamar('GET', '/produtos', ['updated_since' => $agora, 'fields' => 'stock'])['meta']['next_cursor'],
];

// 2. Todas as páginas, com os inativos (status=all), 100 por vez.
$banco = [];
for ($pagina = 1; ; $pagina++) {
    $corpo = chamar('GET', '/produtos', ['fields' => 'stock', 'status' => 'all', 'per_page' => 100, 'page' => $pagina]);
    foreach ($corpo['data'] as $p) {
        // Pelo sku_master_id: o sku_code pode ser trocado na ficha; o id não muda.
        $banco[$p['sku_master_id']] = ['sku' => $p['sku_code'], 'status' => $p['status'], 'disponivel' => $p['stock']['available']];
        echo "{$p['sku_code']} {$p['status']} {$p['stock']['available']}", PHP_EOL;
    }
    if ($pagina >= $corpo['meta']['last_page']) {
        break;
    }
}

// 3. O banco é reescrito inteiro: o SKU que não veio (apagado ou renomeado) sai.
file_put_contents(BANCO, json_encode($banco, JSON_UNESCAPED_UNICODE | JSON_FORCE_OBJECT));
file_put_contents(CURSORES, json_encode($cursores));
echo 'Carga: ', count($banco), ' SKUs', PHP_EOL;
Saída (Python, Node.js e PHP imprimem o mesmo)
BONE-PRETO inactive 0
007-Preto-G1 (48 ao 52) active 4
CAMISETA-M-AZUL active 15
KIT-CAMISETA-2 active 7
Carga: 4 SKUs

4. Manter o estoque sincronizado

  • Rode pelo cron a cada 1 a 5 minutos (ou num laço com espera): GET /estoque/mudancas?cursor=…&limit=500 traz cada SKU cujo estoque mudou (venda na Shopee, ajuste, devolução, o kit junto com a peça), já com o número novo. Depois, o mesmo com GET /produtos?cursor=…&fields=stock: SKU novo, alterado e inativado.
  • Grave na ordem em que chega (a última versão de cada SKU vale) e só depois guarde o meta.next_cursor novo — ele sempre vem, mesmo com a página vazia. Com "has_more": true, chame de novo na hora.
  • Atraso de até ~2 minutos no SKU com saldo por armazém: o feed mostra o que foi gravado até meta.sync_horizon. É isso que garante que nada se perde entre as páginas. SKU de cadastro antigo (sem saldo por armazém) não vem em /estoque/mudancas: o que muda nele chega pelo feed do catálogo, com até ~3 h de atraso em algumas gravações do painel, ou pela reconciliação diária (passo 3 de novo). Quer o número de agora de um SKU? GET /produtos/{sku}.
  • Erro no meio? Repita com o MESMO cursor: nada se perde nem se duplica.

A saída abaixo é a de um cursor de antes da venda Shopee e da entrada em SP de hoje (os movimentos da empresa de exemplo). Prefere um programa pronto, de um arquivo só, com a carga e o laço juntos? Veja Manter o estoque sincronizado.

bash — cURL
# Passo 4: a cada 1 a 5 minutos, o que mudou desde o cursor guardado (read:products).
BASE="${LOJEXA_API_BASE:-https://lojexa.com/api/v1}"
AUTH="Authorization: Bearer $LOJEXA_API_KEY"
: "${CURSOR_DO_ESTOQUE:?guarde o meta.next_cursor do passo 3}" "${CURSOR_DO_CATALOGO:?guarde o meta.next_cursor do passo 3}"

# Estoque: grave cada SKU (pelo sku_master_id) e guarde o novo meta.next_cursor.
# Com "has_more": true, chame de novo na hora, já com ele.
curl -sS --max-time 30 -w '\nHTTP %{http_code}\n' -H "$AUTH" -G "$BASE/estoque/mudancas" \
     --data-urlencode "cursor=$CURSOR_DO_ESTOQUE" -d limit=500

# Catálogo: SKU novo, alterado e inativado ("status": "inactive").
curl -sS --max-time 30 -w '\nHTTP %{http_code}\n' -H "$AUTH" -G "$BASE/produtos" \
     --data-urlencode "cursor=$CURSOR_DO_CATALOGO" -d fields=stock -d limit=100
Python 3 — requests
"""Passo 4: manter o estoque sincronizado (read:products). Rode pelo cron a cada 1 a 5 minutos."""
import json
import pathlib

from lojexa import chamar

BANCO = pathlib.Path('estoque_local.json')
CURSORES = pathlib.Path('lojexa_cursores.json')
banco = json.loads(BANCO.read_text(encoding='utf-8'))
cursores = json.loads(CURSORES.read_text(encoding='utf-8'))


def gravar(caminho, valor):
    """Grava num arquivo temporário e troca: uma falha no meio não deixa o arquivo vazio."""
    temporario = caminho.with_suffix('.tmp')
    temporario.write_text(json.dumps(valor, ensure_ascii=False), encoding='utf-8')
    temporario.replace(caminho)


def seguir(caminho, qual, params):
    while True:
        corpo = chamar('GET', caminho, {**params, 'cursor': cursores[qual]})
        for p in corpo['data']:  # na ordem em que chega: a última versão de cada SKU vale
            banco[str(p['sku_master_id'])] = {'sku': p['sku_code'], 'status': p['status'], 'disponivel': p['stock']['available']}
            print(qual, p['sku_code'], p['status'], p['stock']['available'])
        gravar(BANCO, banco)                                # primeiro o dado...
        cursores[qual] = corpo['meta']['next_cursor']             # ...depois o cursor (sempre vem)
        gravar(CURSORES, cursores)
        if not corpo['meta']['has_more']:
            return


seguir('/estoque/mudancas', 'estoque', {'limit': 500})
seguir('/produtos', 'catalogo', {'fields': 'stock', 'limit': 100})
Node.js 18+ — fetch nativo (servidor)
// Passo 4: manter o estoque sincronizado (read:products). Rode pelo cron a cada 1 a 5 minutos.
// Salve como passo4.mjs, ao lado do lojexa.mjs, e rode: node passo4.mjs (o import pede a extensão .mjs).
import { readFile, writeFile } from 'node:fs/promises';
import { chamar } from './lojexa.mjs';

const BANCO = 'estoque_local.json';
const CURSORES = 'lojexa_cursores.json';
const banco = JSON.parse(await readFile(BANCO, 'utf8'));
const cursores = JSON.parse(await readFile(CURSORES, 'utf8'));

async function seguir(caminho, qual, params) {
  for (;;) {
    const corpo = await chamar('GET', caminho, { params: { ...params, cursor: cursores[qual] } });
    for (const p of corpo.data) { // na ordem em que chega: a última versão de cada SKU vale
      banco[p.sku_master_id] = { sku: p.sku_code, status: p.status, disponivel: p.stock.available };
      console.log(qual, p.sku_code, p.status, p.stock.available);
    }
    await writeFile(BANCO, JSON.stringify(banco)); // primeiro o dado...
    cursores[qual] = corpo.meta.next_cursor;       // ...depois o cursor (sempre vem)
    await writeFile(CURSORES, JSON.stringify(cursores));
    if (!corpo.meta.has_more) return;
  }
}

await seguir('/estoque/mudancas', 'estoque', { limit: 500 });
await seguir('/produtos', 'catalogo', { fields: 'stock', limit: 100 });
PHP 8.1+ — cURL
<?php
// Passo 4: manter o estoque sincronizado (read:products). Rode pelo cron a cada 1 a 5 minutos.
require __DIR__ . '/lojexa.php';

const BANCO = __DIR__ . '/estoque_local.json';
const CURSORES = __DIR__ . '/lojexa_cursores.json';
$banco = json_decode((string) file_get_contents(BANCO), true);
$cursores = json_decode((string) file_get_contents(CURSORES), true);

function seguir(string $caminho, string $qual, array $params, array &$banco, array &$cursores): void
{
    do {
        $corpo = chamar('GET', $caminho, $params + ['cursor' => $cursores[$qual]]);
        foreach ($corpo['data'] as $p) { // na ordem em que chega: a última versão de cada SKU vale
            $banco[$p['sku_master_id']] = ['sku' => $p['sku_code'], 'status' => $p['status'], 'disponivel' => $p['stock']['available']];
            echo "{$qual} {$p['sku_code']} {$p['status']} {$p['stock']['available']}", PHP_EOL;
        }
        file_put_contents(BANCO, json_encode($banco, JSON_UNESCAPED_UNICODE | JSON_FORCE_OBJECT)); // primeiro o dado...
        $cursores[$qual] = $corpo['meta']['next_cursor'];                                          // ...depois o cursor (sempre vem)
        file_put_contents(CURSORES, json_encode($cursores));
    } while ($corpo['meta']['has_more']);
}

seguir('/estoque/mudancas', 'estoque', ['limit' => 500], $banco, $cursores);
seguir('/produtos', 'catalogo', ['fields' => 'stock', 'limit' => 100], $banco, $cursores);
Saída (Python, Node.js e PHP imprimem o mesmo)
estoque CAMISETA-M-AZUL active 15
estoque KIT-CAMISETA-2 active 7

5. Vendeu no seu sistema: avisar a LOJEXA

  • Quando: no momento em que a venda do seu site estiver confirmada (paga), chame POST /vendas. Ela baixa o estoque na hora, tudo ou nada, no mesmo armazém da leitura, e põe o envio do novo saldo aos marketplaces na fila.
  • reference = o id do pedido no SEU sistema (até 100 caracteres, sem /, diferencia maiúsculas). Ela é a chave de idempotência: mandar de novo o mesmo pedido responde 200 com "already_processed": true e não baixa duas vezes. Por isso, no timeout, no 5xx ou no 409 STOCK_RACE_CONDITION, repita igual (o cliente faz isso) — ou pergunte com GET /vendas/{reference}.
  • 422 INSUFFICIENT_STOCK: nada foi baixado. error.details.items traz, por SKU, o available do armazém (e as peças, no kit). Mostre ao cliente e atualize o seu site com esse número; não repita igual.
  • 409 REFERENCE_CONFLICT: essa reference já é de outra venda (outros itens). Não repita: é defeito da integração ou outro pedido com o mesmo id.
  • channels[].push diz, por loja vinculada, se o envio do novo saldo entrou na fila (queued) ou se a loja está com o envio desligado (disabled) — checklist do estoque nos marketplaces.
  • Hoje a venda não vira pedido no painel (sem separação, etiqueta nem NF-e): emita a nota e a etiqueta pelo seu sistema. Veja o que a API não faz hoje.
bash — cURL
# Passo 5: vendeu no seu site, avise a LOJEXA (write:sales). A reference é o id do SEU pedido.
BASE="${LOJEXA_API_BASE:-https://lojexa.com/api/v1}"
AUTH="Authorization: Bearer $LOJEXA_API_KEY"

# O corpo num arquivo UTF-8 (--data-binary manda os bytes como estão, acentos inclusive).
cat > venda.json <<'JSON'
{
  "reference": "PEDIDO-123",
  "channel": "site",
  "customer_name": "Joao Silva",
  "items": [ { "sku": "CAMISETA-M-AZUL", "quantity": 2, "unit_price": 49.90 } ]
}
JSON

# 201: baixou. Timeout, 5xx ou 409 STOCK_RACE_CONDITION? Mande DE NOVO o mesmo corpo.
curl -sS --max-time 30 -w '\nHTTP %{http_code}\n' -X POST -H "$AUTH" -H 'Content-Type: application/json' \
     --data-binary @venda.json "$BASE/vendas"

# O reenvio responde 200 com "already_processed": true e não baixa de novo.
curl -sS --max-time 30 -w '\nHTTP %{http_code}\n' -X POST -H "$AUTH" -H 'Content-Type: application/json' \
     --data-binary @venda.json "$BASE/vendas"

# Sem estoque: 422 INSUFFICIENT_STOCK com error.details.items (o available de cada SKU). Nada é baixado.
curl -sS --max-time 30 -w '\nHTTP %{http_code}\n' -X POST -H "$AUTH" -H 'Content-Type: application/json' \
     --data-binary '{ "reference": "PEDIDO-124", "items": [ { "sku": "KIT-CAMISETA-2", "quantity": 9 } ] }' "$BASE/vendas"

# Depois de um timeout sem resposta: a venda entrou? (404 SALE_NOT_FOUND = não; mande de novo)
curl -sS --max-time 30 -w '\nHTTP %{http_code}\n' -H "$AUTH" "$BASE/vendas/PEDIDO-123"
Python 3 — requests
"""Passo 5: vendeu no seu site, avise a LOJEXA (write:sales). A reference é o id do SEU pedido."""
from lojexa import ErroDaLojexa, chamar, segmento


def avisar_venda(pedido):
    corpo = {
        'reference': pedido['id'],  # a chave de idempotência: o reenvio não baixa de novo
        'channel': 'site',
        'customer_name': pedido['cliente'],
        'items': [{'sku': i['sku'], 'quantity': i['qtd'], 'unit_price': i['preco']} for i in pedido['itens']],
    }
    try:
        r = chamar('POST', '/vendas', corpo=corpo)  # timeout, 5xx e 409 STOCK_RACE_CONDITION: repete IGUAL
    except ErroDaLojexa as e:
        if e.code == 'INSUFFICIENT_STOCK':  # nada foi baixado: atualize o seu site com o available
            for item in e.details['items']:
                print(f"{pedido['id']}: sem estoque de {item['sku']} (disponível {item['available']}, pedido {item['required']})")
            return None
        raise  # REFERENCE_CONFLICT (a reference é de OUTRA venda), SKU_NOT_FOUND...: corrija, não repita
    venda = r['data']
    if r['already_processed']:
        print(f"{venda['reference']}: já estava registrada ({venda['status']})")
    for item in venda.get('items_processed', []):
        lojas = ', '.join(f"{c['channel']} {c['push']}" for c in item['channels'])
        print(f"{venda['reference']}: baixou {item['quantity']} de {item['sku']}, disponível agora {item['available_after']} ({lojas})")
    return venda


def situacao(reference):
    """Depois de um timeout sem resposta: a venda entrou?"""
    try:
        return chamar('GET', '/vendas/' + segmento(reference))['data']['status']
    except ErroDaLojexa as e:
        if e.code == 'SALE_NOT_FOUND':
            return None  # não entrou: mande de novo, com a MESMA reference
        raise


pedido = {'id': 'PEDIDO-123', 'cliente': 'Joao Silva', 'itens': [{'sku': 'CAMISETA-M-AZUL', 'qtd': 2, 'preco': 49.90}]}
avisar_venda(pedido)
avisar_venda(pedido)  # o reenvio (depois de um timeout, por exemplo) não baixa de novo
avisar_venda({'id': 'PEDIDO-124', 'cliente': 'Ana Lima', 'itens': [{'sku': 'KIT-CAMISETA-2', 'qtd': 9, 'preco': 89.90}]})
print('PEDIDO-123:', situacao('PEDIDO-123') or 'não registrada')
print('PEDIDO-999:', situacao('PEDIDO-999') or 'não registrada')
Node.js 18+ — fetch nativo (servidor)
// Passo 5: vendeu no seu site, avise a LOJEXA (write:sales). A reference é o id do SEU pedido.
// Salve como passo5.mjs, ao lado do lojexa.mjs, e rode: node passo5.mjs (o import pede a extensão .mjs).
import { ErroDaLojexa, chamar, segmento } from './lojexa.mjs';

async function avisarVenda(pedido) {
  const corpo = {
    reference: pedido.id, // a chave de idempotência: o reenvio não baixa de novo
    channel: 'site',
    customer_name: pedido.cliente,
    items: pedido.itens.map((i) => ({ sku: i.sku, quantity: i.qtd, unit_price: i.preco })),
  };
  let r;
  try {
    r = await chamar('POST', '/vendas', { corpo }); // timeout, 5xx e 409 STOCK_RACE_CONDITION: repete IGUAL
  } catch (e) {
    if (e instanceof ErroDaLojexa && e.code === 'INSUFFICIENT_STOCK') { // nada foi baixado
      for (const item of e.details.items) {
        console.log(`${pedido.id}: sem estoque de ${item.sku} (disponível ${item.available}, pedido ${item.required})`);
      }
      return null;
    }
    throw e; // REFERENCE_CONFLICT (a reference é de OUTRA venda), SKU_NOT_FOUND...: corrija, não repita
  }
  const venda = r.data;
  if (r.already_processed) console.log(`${venda.reference}: já estava registrada (${venda.status})`);
  for (const item of venda.items_processed ?? []) {
    const lojas = item.channels.map((c) => `${c.channel} ${c.push}`).join(', ');
    console.log(`${venda.reference}: baixou ${item.quantity} de ${item.sku}, disponível agora ${item.available_after} (${lojas})`);
  }
  return venda;
}

/** Depois de um timeout sem resposta: a venda entrou? */
async function situacao(reference) {
  try {
    return (await chamar('GET', `/vendas/${segmento(reference)}`)).data.status;
  } catch (e) {
    if (e instanceof ErroDaLojexa && e.code === 'SALE_NOT_FOUND') return null; // não entrou: mande de novo
    throw e;
  }
}

const pedido = { id: 'PEDIDO-123', cliente: 'Joao Silva', itens: [{ sku: 'CAMISETA-M-AZUL', qtd: 2, preco: 49.9 }] };
await avisarVenda(pedido);
await avisarVenda(pedido); // o reenvio (depois de um timeout, por exemplo) não baixa de novo
await avisarVenda({ id: 'PEDIDO-124', cliente: 'Ana Lima', itens: [{ sku: 'KIT-CAMISETA-2', qtd: 9, preco: 89.9 }] });
console.log('PEDIDO-123:', (await situacao('PEDIDO-123')) ?? 'não registrada');
console.log('PEDIDO-999:', (await situacao('PEDIDO-999')) ?? 'não registrada');
PHP 8.1+ — cURL
<?php
// Passo 5: vendeu no seu site, avise a LOJEXA (write:sales). A reference é o id do SEU pedido.
require __DIR__ . '/lojexa.php';

function avisarVenda(array $pedido): ?array
{
    $corpo = [
        'reference'     => $pedido['id'], // a chave de idempotência: o reenvio não baixa de novo
        'channel'       => 'site',
        'customer_name' => $pedido['cliente'],
        'items'         => array_map(static fn (array $i): array => ['sku' => $i['sku'], 'quantity' => $i['qtd'], 'unit_price' => $i['preco']], $pedido['itens']),
    ];
    try {
        $r = chamar('POST', '/vendas', corpo: $corpo); // timeout, 5xx e 409 STOCK_RACE_CONDITION: repete IGUAL
    } catch (ErroDaLojexa $e) {
        if ($e->codigo === 'INSUFFICIENT_STOCK') { // nada foi baixado: atualize o seu site com o available
            foreach ($e->details['items'] as $item) {
                echo "{$pedido['id']}: sem estoque de {$item['sku']} (disponível {$item['available']}, pedido {$item['required']})", PHP_EOL;
            }

            return null;
        }
        throw $e; // REFERENCE_CONFLICT (a reference é de OUTRA venda), SKU_NOT_FOUND...: corrija, não repita
    }
    $venda = $r['data'];
    if ($r['already_processed']) {
        echo "{$venda['reference']}: já estava registrada ({$venda['status']})", PHP_EOL;
    }
    foreach ($venda['items_processed'] ?? [] as $item) {
        $lojas = implode(', ', array_map(static fn (array $c): string => "{$c['channel']} {$c['push']}", $item['channels']));
        echo "{$venda['reference']}: baixou {$item['quantity']} de {$item['sku']}, disponível agora {$item['available_after']} ({$lojas})", PHP_EOL;
    }

    return $venda;
}

/** Depois de um timeout sem resposta: a venda entrou? */
function situacao(string $reference): ?string
{
    try {
        return chamar('GET', '/vendas/' . segmento($reference))['data']['status'];
    } catch (ErroDaLojexa $e) {
        if ($e->codigo === 'SALE_NOT_FOUND') {
            return null; // não entrou: mande de novo, com a MESMA reference
        }
        throw $e;
    }
}

$pedido = ['id' => 'PEDIDO-123', 'cliente' => 'Joao Silva', 'itens' => [['sku' => 'CAMISETA-M-AZUL', 'qtd' => 2, 'preco' => 49.90]]];
avisarVenda($pedido);
avisarVenda($pedido); // o reenvio (depois de um timeout, por exemplo) não baixa de novo
avisarVenda(['id' => 'PEDIDO-124', 'cliente' => 'Ana Lima', 'itens' => [['sku' => 'KIT-CAMISETA-2', 'qtd' => 9, 'preco' => 89.90]]]);
echo 'PEDIDO-123: ', situacao('PEDIDO-123') ?? 'não registrada', PHP_EOL;
echo 'PEDIDO-999: ', situacao('PEDIDO-999') ?? 'não registrada', PHP_EOL;
Saída (Python, Node.js e PHP imprimem o mesmo)
PEDIDO-123: baixou 2 de CAMISETA-M-AZUL, disponível agora 13 (shopee queued, tiktok disabled)
PEDIDO-123: já estava registrada (confirmed)
PEDIDO-124: sem estoque de KIT-CAMISETA-2 (disponível 6, pedido 9)
PEDIDO-123: confirmed
PEDIDO-999: não registrada

6. Cancelar, cancelar parte ou devolver

  • Cancelou antes de enviar: POST /vendas/{reference}/cancelar. Sem corpo, tudo o que resta; com items, só aqueles.
  • Voltou depois da entrega: POST /vendas/{reference}/devolver, com condition: sellable (volta a vender) ou damaged (fica no físico como avaria, fora do disponível).
  • No parcial, reversal_reference é obrigatória: o id do cancelamento ou da devolução no seu sistema (ex.: o número do RMA). Repetir com a mesma responde "already_processed": true e não estorna duas vezes.
  • Volta ao estoque só o que saiu por esta venda, no armazém de onde saiu; o status da venda vai a partially_reversed e, quando tudo voltou, a reversed.
bash — cURL
# Passo 6: cancelar tudo, cancelar parte ou registrar a devolução (write:sales).
BASE="${LOJEXA_API_BASE:-https://lojexa.com/api/v1}"
AUTH="Authorization: Bearer $LOJEXA_API_KEY"

# Cancelar parte: os itens e o id DESTE cancelamento (reversal_reference, obrigatório no parcial).
# Repetir com a mesma reversal_reference responde "already_processed": true e não devolve duas vezes.
curl -sS --max-time 30 -w '\nHTTP %{http_code}\n' -X POST -H "$AUTH" -H 'Content-Type: application/json' \
     --data-binary @- "$BASE/vendas/PEDIDO-123/cancelar" <<'JSON'
{ "items": [ { "sku": "CAMISETA-M-AZUL", "quantity": 1 } ], "reversal_reference": "CANC-1", "reason": "Cliente desistiu de uma" }
JSON

# Devolver o que resta, avariado (damaged = volta ao físico como avaria, não ao disponível).
curl -sS --max-time 30 -w '\nHTTP %{http_code}\n' -X POST -H "$AUTH" -H 'Content-Type: application/json' \
     --data-binary @- "$BASE/vendas/PEDIDO-123/devolver" <<'JSON'
{ "reversal_reference": "RMA-88", "condition": "damaged", "reason": "Chegou com defeito" }
JSON

# Cancelar TUDO o que resta: POST sem corpo.
#   curl -sS --max-time 30 -X POST -H "$AUTH" "$BASE/vendas/PEDIDO-123/cancelar"
Python 3 — requests
"""Passo 6: cancelar tudo, cancelar parte ou registrar a devolução (write:sales)."""
from lojexa import chamar, segmento


def estornar(acao, reference, itens=None, reversal_reference=None, condicao=None, motivo=None):
    """acao: 'cancelar' (antes de enviar) ou 'devolver' (depois da entrega). Sem itens: tudo o que resta."""
    corpo = {}
    if itens:  # parcial: quais SKUs e quantas unidades (a reversal_reference é obrigatória)
        corpo['items'] = [{'sku': sku, 'quantity': qtd} for sku, qtd in itens.items()]
    if reversal_reference:
        corpo['reversal_reference'] = reversal_reference  # o id DESTE estorno: o reenvio não estorna duas vezes
    if condicao:
        corpo['condition'] = condicao  # só na devolução: sellable (volta a vender) ou damaged (avaria)
    if motivo:
        corpo['reason'] = motivo
    r = chamar('POST', f'/vendas/{segmento(reference)}/{acao}', corpo=corpo or None)
    venda, qual = r['data'], reversal_reference or 'total'
    if r['already_processed']:
        print(f"{reference} {qual}: já processado ({venda['status']})")
        return venda
    voltou = ', '.join(f"{i['restocked']} de {i['sku']}" for i in venda['reversal']['items'])
    print(f"{reference} {qual}: {venda['status']}, voltou {voltou}")
    return venda


estornar('cancelar', 'PEDIDO-123', {'CAMISETA-M-AZUL': 1}, 'CANC-1', motivo='Cliente desistiu de uma')
estornar('cancelar', 'PEDIDO-123', {'CAMISETA-M-AZUL': 1}, 'CANC-1', motivo='Cliente desistiu de uma')  # reenvio
estornar('devolver', 'PEDIDO-123', reversal_reference='RMA-88', condicao='damaged', motivo='Chegou com defeito')
Node.js 18+ — fetch nativo (servidor)
// Passo 6: cancelar tudo, cancelar parte ou registrar a devolução (write:sales).
// Salve como passo6.mjs, ao lado do lojexa.mjs, e rode: node passo6.mjs (o import pede a extensão .mjs).
import { chamar, segmento } from './lojexa.mjs';

/** acao: 'cancelar' (antes de enviar) ou 'devolver' (depois da entrega). Sem itens: tudo o que resta. */
async function estornar(acao, reference, { itens, reversalReference, condicao, motivo } = {}) {
  const corpo = {};
  if (itens) corpo.items = Object.entries(itens).map(([sku, quantity]) => ({ sku, quantity })); // parcial
  if (reversalReference) corpo.reversal_reference = reversalReference; // o id DESTE estorno: o reenvio não estorna duas vezes
  if (condicao) corpo.condition = condicao; // só na devolução: sellable (volta a vender) ou damaged (avaria)
  if (motivo) corpo.reason = motivo;
  const r = await chamar('POST', `/vendas/${segmento(reference)}/${acao}`,
    { corpo: Object.keys(corpo).length ? corpo : undefined });
  const venda = r.data;
  const qual = reversalReference ?? 'total';
  if (r.already_processed) {
    console.log(`${reference} ${qual}: já processado (${venda.status})`);
    return venda;
  }
  const voltou = venda.reversal.items.map((i) => `${i.restocked} de ${i.sku}`).join(', ');
  console.log(`${reference} ${qual}: ${venda.status}, voltou ${voltou}`);
  return venda;
}

const cancelamento = { itens: { 'CAMISETA-M-AZUL': 1 }, reversalReference: 'CANC-1', motivo: 'Cliente desistiu de uma' };
await estornar('cancelar', 'PEDIDO-123', cancelamento);
await estornar('cancelar', 'PEDIDO-123', cancelamento); // reenvio
await estornar('devolver', 'PEDIDO-123', { reversalReference: 'RMA-88', condicao: 'damaged', motivo: 'Chegou com defeito' });
PHP 8.1+ — cURL
<?php
// Passo 6: cancelar tudo, cancelar parte ou registrar a devolução (write:sales).
require __DIR__ . '/lojexa.php';

/** $acao: 'cancelar' (antes de enviar) ou 'devolver' (depois da entrega). Sem itens: tudo o que resta. */
function estornar(string $acao, string $reference, array $itens = [], ?string $reversalReference = null, ?string $condicao = null, ?string $motivo = null): array
{
    $corpo = [];
    if ($itens !== []) { // parcial: quais SKUs e quantas unidades (a reversal_reference é obrigatória)
        $corpo['items'] = array_map(static fn (string $sku, int $qtd): array => ['sku' => $sku, 'quantity' => $qtd], array_keys($itens), $itens);
    }
    if ($reversalReference !== null) {
        $corpo['reversal_reference'] = $reversalReference; // o id DESTE estorno: o reenvio não estorna duas vezes
    }
    if ($condicao !== null) {
        $corpo['condition'] = $condicao; // só na devolução: sellable (volta a vender) ou damaged (avaria)
    }
    if ($motivo !== null) {
        $corpo['reason'] = $motivo;
    }
    $r = chamar('POST', '/vendas/' . segmento($reference) . '/' . $acao, corpo: $corpo !== [] ? $corpo : null);
    $venda = $r['data'];
    $qual = $reversalReference ?? 'total';
    if ($r['already_processed']) {
        echo "{$reference} {$qual}: já processado ({$venda['status']})", PHP_EOL;

        return $venda;
    }
    $voltou = implode(', ', array_map(static fn (array $i): string => "{$i['restocked']} de {$i['sku']}", $venda['reversal']['items']));
    echo "{$reference} {$qual}: {$venda['status']}, voltou {$voltou}", PHP_EOL;

    return $venda;
}

estornar('cancelar', 'PEDIDO-123', ['CAMISETA-M-AZUL' => 1], 'CANC-1', motivo: 'Cliente desistiu de uma');
estornar('cancelar', 'PEDIDO-123', ['CAMISETA-M-AZUL' => 1], 'CANC-1', motivo: 'Cliente desistiu de uma'); // reenvio
estornar('devolver', 'PEDIDO-123', reversalReference: 'RMA-88', condicao: 'damaged', motivo: 'Chegou com defeito');
Saída (Python, Node.js e PHP imprimem o mesmo)
PEDIDO-123 CANC-1: partially_reversed, voltou 1 de CAMISETA-M-AZUL
PEDIDO-123 CANC-1: já processado (partially_reversed)
PEDIDO-123 RMA-88: reversed, voltou 1 de CAMISETA-M-AZUL

7. Entrada de mercadoria e contagem

  • POST /estoque/{sku}/ajuste com type: in (entrada), out (saída, até o disponível) ou set (o físico contado). O reason_code diz o que aconteceu: purchase (compra), return, damage (avaria), loss (perda), count (contagem) ou other (com reason).
  • Sempre com Idempotency-Key, montada do seu documento e do sku_master_id (o da carga do passo 3), ex.: compra-nf-4512-10 (NF 4512, SKU de id 10). A chave aceita só ASCII visível, sem espaço, até 100 caracteres — por isso não use o código do SKU nela (007-Preto-G1 (48 ao 52) tem espaço e parênteses e dá 400 INVALID_IDEMPOTENCY_KEY). A mesma chave com o mesmo ajuste devolve o mesmo resultado sem gravar de novo; com outro ajuste, 409 IDEMPOTENCY_MISMATCH. Sem a chave, cada chamada é um ajuste novo — e um timeout não pode ser repetido.
  • Contagem: set com o que você contou e expected_on_hand com o físico que a LOJEXA mostrava quando a contagem começou: se alguém vendeu ou mexeu no meio, 409 STOCK_CHANGED e nada é gravado — conte de novo.
  • Lote: POST /estoque/ajustes, até 500 itens, Idempotency-Key obrigatória. Cada item é gravado sozinho e o resultado vem por item: um recusado não desfaz os outros. Corrija o recusado e mande-o num lote novo, com outra chave.
  • Kit não se ajusta (422 KIT_NOT_ADJUSTABLE): o estoque dele vem das peças — ajuste as peças. SKU inativo também não (SKU_NOT_FOUND): no exemplo, o BONE-PRETO está inactive na carga do passo 3.
bash — cURL
# Passo 7: entrada de mercadoria, contagem e lote (write:stock). Sempre com Idempotency-Key.
BASE="${LOJEXA_API_BASE:-https://lojexa.com/api/v1}"
AUTH="Authorization: Bearer $LOJEXA_API_KEY"

# Entrada da nota fiscal 4512. Com a mesma Idempotency-Key, repetir devolve o MESMO resultado.
# A chave: só ASCII visível, sem espaço, até 100 caracteres. SKU com espaço ou acento (007-Preto-G1 (48 ao 52))
# não cabe nela: use o sku_master_id da carga do passo 3 (compra-nf-4512-<sku_master_id>): a CAMISETA-M-AZUL é o 10.
curl -sS --max-time 30 -w '\nHTTP %{http_code}\n' -X POST -H "$AUTH" -H 'Content-Type: application/json' \
     -H 'Idempotency-Key: compra-nf-4512-10' \
     --data-binary '{ "type": "in", "quantity": 10, "reason_code": "purchase", "reason": "NF 4512" }' \
     "$BASE/estoque/CAMISETA-M-AZUL/ajuste"

# Contagem em SP: o físico contado; expected_on_hand recusa (409 STOCK_CHANGED) se alguém mexeu desde a contagem.
curl -sS --max-time 30 -w '\nHTTP %{http_code}\n' -X POST -H "$AUTH" -H 'Content-Type: application/json' \
     -H 'Idempotency-Key: inventario-2026-10-SP-10' \
     --data-binary @- "$BASE/estoque/CAMISETA-M-AZUL/ajuste" <<'JSON'
{ "type": "set", "quantity": 6, "expected_on_hand": 5, "warehouse": "SP", "reason": "Inventário de outubro" }
JSON

# Lote de até 500 itens (Idempotency-Key obrigatória). Cada item responde por si ("status": "ok" ou "error").
curl -sS --max-time 30 -w '\nHTTP %{http_code}\n' -X POST -H "$AUTH" -H 'Content-Type: application/json' \
     -H 'Idempotency-Key: lote-erp-2026-10-24' \
     --data-binary @- "$BASE/estoque/ajustes" <<'JSON'
{
  "reason": "Conferência diária do ERP",
  "items": [
    { "sku": "CAMISETA-M-AZUL", "type": "out", "quantity": 1, "reason_code": "damage" },
    { "sku": "007-Preto-G1 (48 ao 52)", "type": "in", "quantity": 3, "warehouse": "SP", "reason_code": "purchase", "reason": "NF 4513" },
    { "sku": "BONE-PRETO", "type": "set", "quantity": 0 }
  ]
}
JSON
# (o BONE-PRETO está inativo na carga do passo 3: SKU inativo não se ajusta, SKU_NOT_FOUND)
Python 3 — requests
"""Passo 7: entrada de mercadoria, contagem e lote (write:stock). Sempre com Idempotency-Key."""
from lojexa import ErroDaLojexa, chamar, segmento


def ajustar(sku, ajuste, chave):
    r = chamar('POST', f'/estoque/{segmento(sku)}/ajuste', corpo=ajuste, idempotency_key=chave)
    d = r['data']
    print(f"{'já gravado' if r['already_processed'] else 'gravado'}: {d['movement']} {d['sku_code']} em {d['warehouse']['code']},"
          f" físico {d['before']['on_hand']} -> {d['after']['on_hand']}, disponível {d['after']['available']}")


# Entrada da nota fiscal 4512. A chave identifica ESTA entrada: repetir não soma duas vezes.
# A chave: só ASCII visível, sem espaço, até 100 caracteres. SKU com espaço ou acento (007-Preto-G1 (48 ao 52))
# não cabe nela: use o sku_master_id da carga do passo 3 (compra-nf-4512-<sku_master_id>): a CAMISETA-M-AZUL é o 10.
entrada = {'type': 'in', 'quantity': 10, 'reason_code': 'purchase', 'reason': 'NF 4512'}
ajustar('CAMISETA-M-AZUL', entrada, 'compra-nf-4512-10')
ajustar('CAMISETA-M-AZUL', entrada, 'compra-nf-4512-10')  # o reenvio devolve o mesmo resultado

# Contagem: o físico contado em SP, conferindo que ninguém mexeu nele desde que você contou.
try:
    ajustar('CAMISETA-M-AZUL', {'type': 'set', 'quantity': 6, 'expected_on_hand': 5, 'warehouse': 'SP', 'reason': 'Inventário de outubro'},
            'inventario-2026-10-SP-10')
except ErroDaLojexa as e:
    if e.code != 'STOCK_CHANGED':
        raise
    print('O físico mudou desde a contagem: conte de novo.')

# Lote: até 500 itens numa chamada. Cada item é gravado sozinho e tem o próprio resultado.
lote = chamar('POST', '/estoque/ajustes', idempotency_key='lote-erp-2026-10-24', corpo={
    'reason': 'Conferência diária do ERP',
    'items': [
        {'sku': 'CAMISETA-M-AZUL', 'type': 'out', 'quantity': 1, 'reason_code': 'damage'},
        {'sku': '007-Preto-G1 (48 ao 52)', 'type': 'in', 'quantity': 3, 'warehouse': 'SP', 'reason_code': 'purchase', 'reason': 'NF 4513'},
        {'sku': 'BONE-PRETO', 'type': 'set', 'quantity': 0},  # inativo (passo 3): SKU inativo não se ajusta, SKU_NOT_FOUND
    ],
})['data']
for item in lote['items']:
    if item['status'] == 'ok':
        print(f"lote {item['index']}: ok, {item['sku']} disponível {item['adjustment']['stock_after']}")
    else:  # corrija e mande só esse item num lote NOVO, com outra chave
        print(f"lote {item['index']}: {item['error']['code']}, {item['sku']}")
Node.js 18+ — fetch nativo (servidor)
// Passo 7: entrada de mercadoria, contagem e lote (write:stock). Sempre com Idempotency-Key.
// Salve como passo7.mjs, ao lado do lojexa.mjs, e rode: node passo7.mjs (o import pede a extensão .mjs).
import { ErroDaLojexa, chamar, segmento } from './lojexa.mjs';

async function ajustar(sku, ajuste, chave) {
  const r = await chamar('POST', `/estoque/${segmento(sku)}/ajuste`, { corpo: ajuste, idempotencyKey: chave });
  const d = r.data;
  console.log(`${r.already_processed ? 'já gravado' : 'gravado'}: ${d.movement} ${d.sku_code} em ${d.warehouse.code},`
    + ` físico ${d.before.on_hand} -> ${d.after.on_hand}, disponível ${d.after.available}`);
}

// Entrada da nota fiscal 4512. A chave identifica ESTA entrada: repetir não soma duas vezes.
// A chave: só ASCII visível, sem espaço, até 100 caracteres. SKU com espaço ou acento (007-Preto-G1 (48 ao 52))
// não cabe nela: use o sku_master_id da carga do passo 3 (compra-nf-4512-<sku_master_id>): a CAMISETA-M-AZUL é o 10.
const entrada = { type: 'in', quantity: 10, reason_code: 'purchase', reason: 'NF 4512' };
await ajustar('CAMISETA-M-AZUL', entrada, 'compra-nf-4512-10');
await ajustar('CAMISETA-M-AZUL', entrada, 'compra-nf-4512-10'); // o reenvio devolve o mesmo resultado

// Contagem: o físico contado em SP, conferindo que ninguém mexeu nele desde que você contou.
try {
  await ajustar('CAMISETA-M-AZUL', { type: 'set', quantity: 6, expected_on_hand: 5, warehouse: 'SP', reason: 'Inventário de outubro' },
    'inventario-2026-10-SP-10');
} catch (e) {
  if (!(e instanceof ErroDaLojexa && e.code === 'STOCK_CHANGED')) throw e;
  console.log('O físico mudou desde a contagem: conte de novo.');
}

// Lote: até 500 itens numa chamada. Cada item é gravado sozinho e tem o próprio resultado.
const lote = (await chamar('POST', '/estoque/ajustes', {
  idempotencyKey: 'lote-erp-2026-10-24',
  corpo: {
    reason: 'Conferência diária do ERP',
    items: [
      { sku: 'CAMISETA-M-AZUL', type: 'out', quantity: 1, reason_code: 'damage' },
      { sku: '007-Preto-G1 (48 ao 52)', type: 'in', quantity: 3, warehouse: 'SP', reason_code: 'purchase', reason: 'NF 4513' },
      { sku: 'BONE-PRETO', type: 'set', quantity: 0 }, // inativo (passo 3): SKU inativo não se ajusta, SKU_NOT_FOUND
    ],
  },
})).data;
for (const item of lote.items) {
  if (item.status === 'ok') console.log(`lote ${item.index}: ok, ${item.sku} disponível ${item.adjustment.stock_after}`);
  else console.log(`lote ${item.index}: ${item.error.code}, ${item.sku}`); // corrija e mande num lote NOVO, com outra chave
}
PHP 8.1+ — cURL
<?php
// Passo 7: entrada de mercadoria, contagem e lote (write:stock). Sempre com Idempotency-Key.
require __DIR__ . '/lojexa.php';

function ajustar(string $sku, array $ajuste, string $chave): void
{
    $r = chamar('POST', '/estoque/' . segmento($sku) . '/ajuste', corpo: $ajuste, idempotencyKey: $chave);
    $d = $r['data'];
    echo ($r['already_processed'] ? 'já gravado' : 'gravado'), ": {$d['movement']} {$d['sku_code']} em {$d['warehouse']['code']},",
        " físico {$d['before']['on_hand']} -> {$d['after']['on_hand']}, disponível {$d['after']['available']}", PHP_EOL;
}

// Entrada da nota fiscal 4512. A chave identifica ESTA entrada: repetir não soma duas vezes.
// A chave: só ASCII visível, sem espaço, até 100 caracteres. SKU com espaço ou acento (007-Preto-G1 (48 ao 52))
// não cabe nela: use o sku_master_id da carga do passo 3 (compra-nf-4512-<sku_master_id>): a CAMISETA-M-AZUL é o 10.
$entrada = ['type' => 'in', 'quantity' => 10, 'reason_code' => 'purchase', 'reason' => 'NF 4512'];
ajustar('CAMISETA-M-AZUL', $entrada, 'compra-nf-4512-10');
ajustar('CAMISETA-M-AZUL', $entrada, 'compra-nf-4512-10'); // o reenvio devolve o mesmo resultado

// Contagem: o físico contado em SP, conferindo que ninguém mexeu nele desde que você contou.
try {
    ajustar('CAMISETA-M-AZUL', ['type' => 'set', 'quantity' => 6, 'expected_on_hand' => 5, 'warehouse' => 'SP', 'reason' => 'Inventário de outubro'],
        'inventario-2026-10-SP-10');
} catch (ErroDaLojexa $e) {
    if ($e->codigo !== 'STOCK_CHANGED') {
        throw $e;
    }
    echo 'O físico mudou desde a contagem: conte de novo.', PHP_EOL;
}

// Lote: até 500 itens numa chamada. Cada item é gravado sozinho e tem o próprio resultado.
$lote = chamar('POST', '/estoque/ajustes', idempotencyKey: 'lote-erp-2026-10-24', corpo: [
    'reason' => 'Conferência diária do ERP',
    'items'  => [
        ['sku' => 'CAMISETA-M-AZUL', 'type' => 'out', 'quantity' => 1, 'reason_code' => 'damage'],
        ['sku' => '007-Preto-G1 (48 ao 52)', 'type' => 'in', 'quantity' => 3, 'warehouse' => 'SP', 'reason_code' => 'purchase', 'reason' => 'NF 4513'],
        ['sku' => 'BONE-PRETO', 'type' => 'set', 'quantity' => 0], // inativo (passo 3): SKU inativo não se ajusta, SKU_NOT_FOUND
    ],
])['data'];
foreach ($lote['items'] as $item) {
    if ($item['status'] === 'ok') {
        echo "lote {$item['index']}: ok, {$item['sku']} disponível {$item['adjustment']['stock_after']}", PHP_EOL;
    } else { // corrija e mande só esse item num lote NOVO, com outra chave
        echo "lote {$item['index']}: {$item['error']['code']}, {$item['sku']}", PHP_EOL;
    }
}
Saída (Python, Node.js e PHP imprimem o mesmo)
gravado: purchase_entry CAMISETA-M-AZUL em PE, físico 18 -> 28, disponível 24
já gravado: purchase_entry CAMISETA-M-AZUL em PE, físico 18 -> 28, disponível 24
gravado: manual_adjustment CAMISETA-M-AZUL em SP, físico 5 -> 6, disponível 6
lote 0: ok, CAMISETA-M-AZUL disponível 23
lote 1: ok, 007-Preto-G1 (48 ao 52) disponível 3
lote 2: SKU_NOT_FOUND, BONE-PRETO

8. Ler os pedidos dos marketplaces

  • GET /orders (read:orders, somente leitura): os pedidos da Shopee, do Mercado Livre, da TikTok Shop, da SHEIN e dos outros canais do painel (a Amazon fica fora), com status, prazo de envio, rastreio, taxas e NF-e. O comprador vem mascarado.
  • Mesmo laço do passo 4: a primeira chamada com updated_since, as outras com o cursor guardado. Grave pelo id (upsert): o mesmo pedido volta quando muda (status, rastreio, NF-e, repasse).
  • Hoje, pedidos dos canais e os pedidos próprios criados na LOJEXA: no painel ("channel": "manual"), no PDV (pdv), no app (mobile), no app desktop (desktop), nas lojas próprias (siteb2c, lojab2b) e pelo antigo POST /orders (api). O channel sai sempre normalizado: minúsculo, sem espaço, _ nem -. A venda de POST /vendas não aparece em /orders. Se um dia aparecer, virá com "channel": "apivenda" (um valor que não existe hoje): essa venda já está no seu sistema — o código abaixo já a pula, para não importar duas vezes. ("channel": "api" é outra coisa: pedido criado pelo antigo POST /orders.) Mudança de contrato sai no changelog, com data.
  • O estado de agora de um pedido: GET /orders/{id}. Mais detalhes em Sincronizar pedidos e no vocabulário de status.
bash — cURL
# Passo 8: ler os pedidos dos marketplaces (read:orders, somente leitura).
BASE="${LOJEXA_API_BASE:-https://lojexa.com/api/v1}"
AUTH="Authorization: Bearer $LOJEXA_API_KEY"

# A primeira carga: a partir de quando. Guarde o meta.next_cursor (ele sempre vem).
# Pedido com "channel": "apivenda" (se um dia aparecer) é venda feita por POST /vendas: já está no seu sistema, pule.
curl -sS --max-time 30 -w '\nHTTP %{http_code}\n' -H "$AUTH" -G "$BASE/orders" \
     --data-urlencode 'updated_since=2026-10-01T00:00:00-03:00' -d limit=100

# Depois, a cada 1 a 5 minutos, com o cursor guardado (e de novo na hora enquanto "has_more": true):
#   curl -sS --max-time 30 -H "$AUTH" -G "$BASE/orders" --data-urlencode "cursor=$CURSOR_DOS_PEDIDOS" -d limit=100

# O estado atual de um pedido:
curl -sS --max-time 30 -w '\nHTTP %{http_code}\n' -H "$AUTH" "$BASE/orders/198734"
Python 3 — requests
"""Passo 8: ler os pedidos dos marketplaces (read:orders, somente leitura). Rode a cada 1 a 5 minutos."""
import json
import pathlib

from lojexa import chamar

ESTADO = pathlib.Path('lojexa_pedidos.json')  # o cursor, de uma execução para a outra
params = {'limit': 100}
if ESTADO.exists():
    params['cursor'] = json.loads(ESTADO.read_text(encoding='utf-8'))['cursor']
else:
    params['updated_since'] = '2026-10-01T00:00:00-03:00'  # a primeira carga: a partir de quando

while True:
    corpo = chamar('GET', '/orders', params)
    for pedido in corpo['data']:  # grave pelo id (upsert): o mesmo pedido volta quando muda
        if pedido['channel'] == 'apivenda':
            continue  # venda feita por POST /vendas: já está no seu sistema
        print(pedido['id'], pedido['channel'], pedido['status']['channel'], pedido['shipping']['ship_by'])
    ESTADO.write_text(json.dumps({'cursor': corpo['meta']['next_cursor']}), encoding='utf-8')  # sempre vem
    if not corpo['meta']['has_more']:
        break
    params = {'limit': 100, 'cursor': corpo['meta']['next_cursor']}
Node.js 18+ — fetch nativo (servidor)
// Passo 8: ler os pedidos dos marketplaces (read:orders, somente leitura). Rode a cada 1 a 5 minutos.
// Salve como passo8.mjs, ao lado do lojexa.mjs, e rode: node passo8.mjs (o import pede a extensão .mjs).
import { existsSync } from 'node:fs';
import { readFile, writeFile } from 'node:fs/promises';
import { chamar } from './lojexa.mjs';

const ESTADO = 'lojexa_pedidos.json'; // o cursor, de uma execução para a outra
let params = { limit: 100 };
if (existsSync(ESTADO)) params.cursor = JSON.parse(await readFile(ESTADO, 'utf8')).cursor;
else params.updated_since = '2026-10-01T00:00:00-03:00'; // a primeira carga: a partir de quando

for (;;) {
  const corpo = await chamar('GET', '/orders', { params });
  for (const pedido of corpo.data) { // grave pelo id (upsert): o mesmo pedido volta quando muda
    if (pedido.channel === 'apivenda') continue; // venda feita por POST /vendas: já está no seu sistema
    console.log(pedido.id, pedido.channel, pedido.status.channel, pedido.shipping.ship_by);
  }
  await writeFile(ESTADO, JSON.stringify({ cursor: corpo.meta.next_cursor })); // sempre vem
  if (!corpo.meta.has_more) break;
  params = { limit: 100, cursor: corpo.meta.next_cursor };
}
PHP 8.1+ — cURL
<?php
// Passo 8: ler os pedidos dos marketplaces (read:orders, somente leitura). Rode a cada 1 a 5 minutos.
require __DIR__ . '/lojexa.php';

const ESTADO = __DIR__ . '/lojexa_pedidos.json'; // o cursor, de uma execução para a outra
$params = ['limit' => 100];
if (is_file(ESTADO)) {
    $params['cursor'] = json_decode((string) file_get_contents(ESTADO), true)['cursor'];
} else {
    $params['updated_since'] = '2026-10-01T00:00:00-03:00'; // a primeira carga: a partir de quando
}

do {
    $corpo = chamar('GET', '/orders', $params);
    foreach ($corpo['data'] as $pedido) { // grave pelo id (upsert): o mesmo pedido volta quando muda
        if ($pedido['channel'] === 'apivenda') {
            continue; // venda feita por POST /vendas: já está no seu sistema
        }
        echo "{$pedido['id']} {$pedido['channel']} {$pedido['status']['channel']} {$pedido['shipping']['ship_by']}", PHP_EOL;
    }
    file_put_contents(ESTADO, json_encode(['cursor' => $corpo['meta']['next_cursor']])); // sempre vem
    $params = ['limit' => 100, 'cursor' => $corpo['meta']['next_cursor']];
} while ($corpo['meta']['has_more']);
Saída (Python, Node.js e PHP imprimem o mesmo)
198734 shopee READY_TO_SHIP 2026-10-25T23:59:59-03:00

9. Receber os webhooks

  • Eventos: sale.confirmed (venda registrada por esta chave) e sale.reversed (cancelamento ou devolução, total ou parcial). Não há webhook de estoque nem de pedido do marketplace: o webhook é um aviso; a fonte da verdade são os feeds dos passos 4 e 8.
  • Confira a assinatura com o corpo CRU, exatamente como chegou: X-Lojexa-Signature-V2 = sha256= + HMAC-SHA256 de <X-Lojexa-Timestamp>.<corpo> com o secret, comparado em tempo constante (Python hmac.compare_digest, Node crypto.timingSafeEqual, PHP hash_equals). Recuse se o timestamp estiver a mais de 300 s do seu relógio.
  • Deduplique pelo event_id (o mesmo em toda tentativa): o mesmo aviso pode chegar mais de uma vez.
  • Responda 2xx em menos de 10 s e processe depois. Qualquer outra resposta, ou timeout, é uma falha: a LOJEXA tenta de novo até 10 vezes em cerca de 24 h (como a LOJEXA entrega).
  • A aba cURL simula um aviso assinado para você testar o seu receptor antes de ligar a URL na chave.
bash — simular um aviso assinado (openssl + cURL)
# Passo 9: teste o SEU receptor de webhook simulando um aviso assinado como a LOJEXA assina.
# X-Lojexa-Signature-V2 = "sha256=" + HMAC-SHA256("<X-Lojexa-Timestamp>.<corpo cru>", secret)
URL="${URL_DO_RECEPTOR:-http://localhost:8080/webhooks/lojexa}"
CORPO='{"event":"sale.confirmed","event_id":"evt_000000000000000000000001","company_id":1,"timestamp":1792847700,"occurred_at":"2026-10-24T10:15:00-03:00","data":{"sale_id":5,"reference":"PEDIDO-123","channel":"site","items":[{"sku":"CAMISETA-M-AZUL","quantity":2,"stock_after":13,"warehouse":{"id":1,"code":"PE","name":"Pernambuco"}}]}}'
TS=$(date +%s)
ASSINATURA="sha256=$(printf '%s.%s' "$TS" "$CORPO" | openssl dgst -sha256 -hmac "$LOJEXA_WEBHOOK_SECRET" | sed 's/^.* //')"

# Assinado certo: o receptor responde 2xx (e guarda o evento uma vez só, mesmo que chegue de novo).
curl -sS --max-time 10 -w 'HTTP %{http_code}\n' -X POST -H 'Content-Type: application/json' \
     -H 'X-Lojexa-Event: sale.confirmed' -H 'X-Lojexa-Event-Id: evt_000000000000000000000001' \
     -H "X-Lojexa-Timestamp: $TS" -H "X-Lojexa-Signature-V2: $ASSINATURA" -d "$CORPO" "$URL"

# Assinatura errada: o receptor tem de recusar (401).
curl -sS --max-time 10 -w 'HTTP %{http_code}\n' -X POST -H 'Content-Type: application/json' \
     -H "X-Lojexa-Timestamp: $TS" -H 'X-Lojexa-Signature-V2: sha256=0000' -d "$CORPO" "$URL"
webhook.py — Python 3, biblioteca padrão
"""Passo 9: receber o webhook e conferir a assinatura (Python 3, só a biblioteca padrão).

PORTA=8080 python webhook.py  (atrás do seu HTTPS: nginx, Caddy, load balancer...)
"""
import hashlib
import hmac
import json
import os
import pathlib
import time
from http.server import BaseHTTPRequestHandler, HTTPServer

SECRET = os.environ['LOJEXA_WEBHOOK_SECRET'].encode()
RECEBIDOS = pathlib.Path('webhooks_recebidos.jsonl')  # no seu sistema: uma tabela com UNIQUE no event_id


def assinatura_valida(corpo_cru, timestamp, assinatura):
    if not timestamp.isdigit() or abs(time.time() - int(timestamp)) > 300:
        return False  # sem timestamp ou velho demais: pode ser um aviso antigo repetido
    esperado = 'sha256=' + hmac.new(SECRET, timestamp.encode() + b'.' + corpo_cru, hashlib.sha256).hexdigest()
    return hmac.compare_digest(esperado, assinatura)


def ja_recebido(event_id):
    linhas = RECEBIDOS.read_text(encoding='utf-8').splitlines() if RECEBIDOS.exists() else []
    return any(json.loads(linha)['event_id'] == event_id for linha in linhas)


class Receptor(BaseHTTPRequestHandler):
    def do_POST(self):
        corpo_cru = self.rfile.read(int(self.headers.get('Content-Length') or 0))  # CRU: antes de qualquer json.loads
        timestamp = self.headers.get('X-Lojexa-Timestamp', '')
        if not assinatura_valida(corpo_cru, timestamp, self.headers.get('X-Lojexa-Signature-V2', '')):
            return self.responder(401)
        evento = json.loads(corpo_cru)
        if not ja_recebido(evento['event_id']):  # o mesmo aviso pode chegar mais de uma vez
            with RECEBIDOS.open('a', encoding='utf-8') as arquivo:  # guarde e processe DEPOIS, numa fila sua
                arquivo.write(json.dumps({'event_id': evento['event_id'], 'event': evento['event'],
                                          'reference': evento['data']['reference']}) + '\n')
        self.responder(204)  # 2xx rápido (em menos de 10 s): qualquer outra resposta é falha e o aviso volta

    def responder(self, status):
        self.send_response(status)
        self.end_headers()

    def log_message(self, *args):
        pass


# Só no 127.0.0.1: o HTTPS fica no proxy da frente (nginx, Caddy), que repassa para cá.
HTTPServer(('127.0.0.1', int(os.environ.get('PORTA', '8080'))), Receptor).serve_forever()
webhook.mjs — Node.js 18+, biblioteca padrão
// Passo 9: receber o webhook e conferir a assinatura (Node 18+, só a biblioteca padrão).
// PORTA=8080 node webhook.mjs  (atrás do seu HTTPS: nginx, Caddy, load balancer...)
import { createHmac, timingSafeEqual } from 'node:crypto';
import { appendFileSync, existsSync, readFileSync } from 'node:fs';
import { createServer } from 'node:http';

const SECRET = process.env.LOJEXA_WEBHOOK_SECRET;
const RECEBIDOS = 'webhooks_recebidos.jsonl'; // no seu sistema: uma tabela com UNIQUE no event_id

function assinaturaValida(corpoCru, timestamp, assinatura) {
  if (!/^\d+$/.test(timestamp) || Math.abs(Date.now() / 1000 - Number(timestamp)) > 300) {
    return false; // sem timestamp ou velho demais: pode ser um aviso antigo repetido
  }
  const esperado = Buffer.from('sha256=' + createHmac('sha256', SECRET).update(`${timestamp}.`).update(corpoCru).digest('hex'));
  const recebido = Buffer.from(assinatura);
  return recebido.length === esperado.length && timingSafeEqual(recebido, esperado);
}

function jaRecebido(eventId) {
  const linhas = existsSync(RECEBIDOS) ? readFileSync(RECEBIDOS, 'utf8').split('\n').filter(Boolean) : [];
  return linhas.some((linha) => JSON.parse(linha).event_id === eventId);
}

createServer((req, res) => {
  const partes = [];
  req.on('data', (parte) => partes.push(parte));
  req.on('end', () => {
    const corpoCru = Buffer.concat(partes); // CRU: antes de qualquer JSON.parse
    if (req.method !== 'POST'
      || !assinaturaValida(corpoCru, req.headers['x-lojexa-timestamp'] ?? '', req.headers['x-lojexa-signature-v2'] ?? '')) {
      res.writeHead(401).end();
      return;
    }
    const evento = JSON.parse(corpoCru);
    if (!jaRecebido(evento.event_id)) { // o mesmo aviso pode chegar mais de uma vez
      appendFileSync(RECEBIDOS, JSON.stringify({ event_id: evento.event_id, event: evento.event, reference: evento.data.reference }) + '\n');
    } // guarde e processe DEPOIS, numa fila sua
    res.writeHead(204).end(); // 2xx rápido (em menos de 10 s): qualquer outra resposta é falha e o aviso volta
  });
}).listen(Number(process.env.PORTA ?? 8080), '127.0.0.1'); // só local: o HTTPS fica no proxy da frente (nginx, Caddy)
webhook.php — PHP 8 (a URL do webhook)
<?php
// Passo 9: receber o webhook e conferir a assinatura (PHP 8). Este arquivo é a URL do webhook,
// ex.: https://minhaloja.com.br/webhooks/lojexa.php (servido pelo seu Apache, nginx + PHP-FPM...).
$secret = (string) getenv('LOJEXA_WEBHOOK_SECRET');
if ($secret === '') { // sem o secret, hash_hmac com chave vazia: qualquer um assinaria. Recuse tudo.
    http_response_code(500);
    exit;
}
$recebidos = __DIR__ . '/webhooks_recebidos.jsonl'; // no seu sistema: uma tabela com UNIQUE no event_id

$corpoCru = (string) file_get_contents('php://input'); // CRU: antes de qualquer json_decode
$timestamp = $_SERVER['HTTP_X_LOJEXA_TIMESTAMP'] ?? '';
$assinatura = $_SERVER['HTTP_X_LOJEXA_SIGNATURE_V2'] ?? '';
$esperado = 'sha256=' . hash_hmac('sha256', $timestamp . '.' . $corpoCru, $secret);
if ($_SERVER['REQUEST_METHOD'] !== 'POST' || !ctype_digit($timestamp) || abs(time() - (int) $timestamp) > 300
    || !hash_equals($esperado, $assinatura)) {
    http_response_code(401); // assinatura errada, sem timestamp ou velho demais (pode ser um aviso repetido)
    exit;
}

$evento = json_decode($corpoCru, true);
$linhas = is_file($recebidos) ? file($recebidos, FILE_IGNORE_NEW_LINES | FILE_SKIP_EMPTY_LINES) : [];
$jaRecebido = in_array($evento['event_id'], array_map(static fn (string $l): string => json_decode($l, true)['event_id'], $linhas), true);
if (!$jaRecebido) { // o mesmo aviso pode chegar mais de uma vez
    file_put_contents($recebidos, json_encode(['event_id' => $evento['event_id'], 'event' => $evento['event'],
        'reference' => $evento['data']['reference']]) . "\n", FILE_APPEND | LOCK_EX); // guarde e processe DEPOIS
}
http_response_code(204); // 2xx rápido (em menos de 10 s): qualquer outra resposta é falha e o aviso volta
webhooks_recebidos.jsonl depois do aviso, da repetição dele e de um aviso com assinatura errada
{"event_id": "evt_3f9a2c7d1e0b4a5f6c8d9e01", "event": "sale.confirmed", "reference": "PEDIDO-123"}
{"event_id": "evt_8b1d4e6f2a3c5b7d9e0f1a23", "event": "sale.reversed", "reference": "PEDIDO-123"}

10. Erros, limites e retentativas

RespostaO que quer dizerO que fazer
400, 404, 422A chamada está errada ou o dado não existe (error.code diz qual)Corrija a chamada ou o cadastro. Repetir igual dá o mesmo erro. Alguns são esperados e você trata: PRODUCT_NOT_FOUND, SALE_NOT_FOUND, INSUFFICIENT_STOCK
401, 403Chave ausente, errada, revogada, expirada, sem o escopo ou empresa suspensaPare e corrija a chave (crie outra no painel). Não gasta cota
409Conflito: STOCK_RACE_CONDITION e BATCH_IN_PROGRESS passam repetindo; REFERENCE_CONFLICT, IDEMPOTENCY_MISMATCH, STOCK_CHANGED e MAPPING_CONFLICT nãoRepita só os dois primeiros, com backoff; os outros pedem outra chave, outra reference ou uma nova contagem
429Passou do limite do minutoEspere Retry-After e repita. Para não chegar lá, olhe X-RateLimit-Remaining
5xx, timeout, redeFalha do servidor ou do caminhoRepita a MESMA chamada com backoff exponencial e jitter (2 s, 4 s, 8 s… até 60 s), só quando repetir é seguro
  • Decida pelo error.code, nunca pela message (ela é para pessoas e pode mudar). Todos os códigos, com o que fazer: tabela de erros; os de cada endpoint ficam na seção dele.
  • Guarde o X-Request-Id de toda chamada que falhou (vem no cabeçalho e em error.request_id): é o que o suporte precisa para achar a chamada.
  • Limite: X-RateLimit-Limit, X-RateLimit-Remaining e X-RateLimit-Reset vêm em toda resposta contada. Se o contador estiver fora do ar, eles não vêm e não há limite — não dependa disso (rate limit).
bash — cURL
# Passo 10: tratar erros. Repita só o que é repetível, esperando o Retry-After no 429 (com jitter).
BASE="${LOJEXA_API_BASE:-https://lojexa.com/api/v1}"
AUTH="Authorization: Bearer $LOJEXA_API_KEY"
ID="$(date +%s)-$RANDOM-$RANDOM"   # o X-Request-Id desta chamada: o mesmo em toda tentativa

for tentativa in 1 2 3 4 5 6; do
  STATUS=$(curl -sS --max-time 30 -o resposta.json -D cabecalhos.txt -w '%{http_code}' \
                -H "$AUTH" -H "X-Request-Id: $ID" "$BASE/produtos?fields=stock&per_page=100&page=1")
  case "$STATUS" in
    200) echo "ok: $(head -c 80 resposta.json)..."; break ;;
    429|5??|000)   # limite, erro do servidor ou sem resposta (000): espere e repita IGUAL
      ESPERA=$(grep -i '^retry-after:' cabecalhos.txt | tr -dc '0-9')
      sleep $(( ${ESPERA:-$(( 2 ** tentativa ))} + RANDOM % 2 )) ;;
    *) echo "erro $STATUS (X-Request-Id $ID): $(cat resposta.json)"; break ;;   # 4xx: corrija, não repita
  esac
done

# Um erro de verdade: o code diz o que aconteceu e o X-Request-Id é o que o suporte pede.
curl -sS --max-time 30 -w '\nHTTP %{http_code}\n' -H "$AUTH" "$BASE/produtos?per_page=200"
Python 3 — requests
"""Passo 10: tratar erros. O cliente do passo 1 já repete o que é repetível (429, 5xx, rede)."""
from lojexa import ErroDaLojexa, chamar, segmento


def produto(sku):
    try:
        return chamar('GET', '/produtos/' + segmento(sku))['data']
    except ErroDaLojexa as e:
        if e.code == 'PRODUCT_NOT_FOUND':
            return None  # esperado: o SKU não existe nesta empresa
        raise


print('NAO-EXISTE:', 'existe' if produto('NAO-EXISTE') else 'não existe')
try:
    chamar('GET', '/produtos', {'per_page': 200})  # passa do limite (100)
except ErroDaLojexa as e:
    # Não se resolve repetindo: registre o code e o X-Request-Id (é o que o suporte pede) e corrija.
    print(f'LOJEXA {e.status} {e.code}, X-Request-Id {e.request_id}')
Node.js 18+ — fetch nativo (servidor)
// Passo 10: tratar erros. O cliente do passo 1 já repete o que é repetível (429, 5xx, rede).
// Salve como passo10.mjs, ao lado do lojexa.mjs, e rode: node passo10.mjs (o import pede a extensão .mjs).
import { ErroDaLojexa, chamar, segmento } from './lojexa.mjs';

async function produto(sku) {
  try {
    return (await chamar('GET', `/produtos/${segmento(sku)}`)).data;
  } catch (e) {
    if (e instanceof ErroDaLojexa && e.code === 'PRODUCT_NOT_FOUND') return null; // esperado: o SKU não existe nesta empresa
    throw e;
  }
}

console.log('NAO-EXISTE:', (await produto('NAO-EXISTE')) ? 'existe' : 'não existe');
try {
  await chamar('GET', '/produtos', { params: { per_page: 200 } }); // passa do limite (100)
} catch (e) {
  if (!(e instanceof ErroDaLojexa)) throw e;
  // Não se resolve repetindo: registre o code e o X-Request-Id (é o que o suporte pede) e corrija.
  console.log(`LOJEXA ${e.status} ${e.code}, X-Request-Id ${e.requestId}`);
}
PHP 8.1+ — cURL
<?php
// Passo 10: tratar erros. O cliente do passo 1 já repete o que é repetível (429, 5xx, rede).
require __DIR__ . '/lojexa.php';

function produto(string $sku): ?array
{
    try {
        return chamar('GET', '/produtos/' . segmento($sku))['data'];
    } catch (ErroDaLojexa $e) {
        if ($e->codigo === 'PRODUCT_NOT_FOUND') {
            return null; // esperado: o SKU não existe nesta empresa
        }
        throw $e;
    }
}

echo 'NAO-EXISTE: ', produto('NAO-EXISTE') !== null ? 'existe' : 'não existe', PHP_EOL;
try {
    chamar('GET', '/produtos', ['per_page' => 200]); // passa do limite (100)
} catch (ErroDaLojexa $e) {
    // Não se resolve repetindo: registre o código e o X-Request-Id (é o que o suporte pede) e corrija.
    echo "LOJEXA {$e->status} {$e->codigo}, X-Request-Id {$e->requestId}", PHP_EOL;
}
Saída (o X-Request-Id muda a cada execução)
NAO-EXISTE: não existe
LOJEXA 422 INVALID_PARAMETER, X-Request-Id 8f14e45fceea167a5a36dedd4bea2543

11. Checklist de produção

  • Chave: uma por integração, com o mínimo de escopos, no ambiente do servidor (nunca no front, no app ou no Git). Anote onde ela está para trocá-la sem pressa se vazar.
  • Só do servidor, só https://, sem seguir redirect e com timeout de 30 s em toda chamada.
  • Retentativa segura: backoff exponencial com jitter em 429, 5xx, rede e nos dois 409 retentáveis; venda com a mesma reference; estorno com a mesma reversal_reference; ajuste sempre com Idempotency-Key.
  • Estoque: carga inicial, laço dos feeds a cada 1 a 5 min (o cursor guardado depois do dado) e a reconciliação diária. Grave pelo sku_master_id.
  • Venda: trate 422 INSUFFICIENT_STOCK (mostre o available) e consulte GET /vendas/{reference} depois de um timeout.
  • Marketplaces: confira o checklist: SKU vinculado com a loja, envio de estoque da loja ligado no painel, channels[].push = queued.
  • Webhook: assinatura V2 com o corpo cru, janela de 300 s, deduplicação por event_id, 2xx rápido, e o feed como fonte da verdade.
  • Log: guarde, de cada falha, o método, o caminho, o status, o error.code e o X-Request-Id.
  • Teste com um SKU sem vínculo com anúncio antes de ligar a integração nos SKUs que vendem: não há ambiente de teste.
  • Acompanhe o changelog: mudança de contrato sai lá, com data.

Identificar o SKU

  • Use o SKU da LOJEXA (sku_code, o mesmo do cadastro em Estoque), não o código do anúncio no marketplace.
  • Maiúsculas, minúsculas e acentos não distinguem: camiseta-m-azul acha CAMISETA-M-AZUL.
  • No caminho, codifique o SKU: JavaScript encodeURIComponent(sku), Python urllib.parse.quote(sku, safe=""), PHP rawurlencode($sku). Ex.: 007-Preto-G1 (48 ao 52) vira 007-Preto-G1%20(48%20ao%2052).
  • SKU com / não cabe no caminho (codificada como %2F, o servidor web recusa antes de chegar à API, com um 404 que pode nem ser JSON; sem codificar, a barra vira outro caminho e dá 404 ROUTE_NOT_FOUND): use GET /produtos?sku=<sku>, que aceita qualquer caractere.
  • Vários SKUs de uma vez: GET /produtos?skus=A,B,C, até 100 por chamada. Os que não existem voltam em meta.not_found. SKU com vírgula vai por ?sku=.
cURL — SKU com espaço e parênteses
curl -H "Authorization: Bearer $LOJEXA_API_KEY" \
     "https://lojexa.com/api/v1/produtos/007-Preto-G1%20(48%20ao%2052)?fields=stock"
JSON — resposta 200 (um SKU sem saldo por armazém: vale o contador do cadastro, no armazém de casa)
{
  "success": true,
  "data": {
    "sku_master_id": 40,
    "sku_code": "007-Preto-G1 (48 ao 52)",
    "name": "Calça Pantalona Preta G1",
    "status": "active",
    "updated_at": "2026-10-21T10:00:00-03:00",
    "stock_available": 4,
    "stock": {
      "warehouse": {
        "id": 1,
        "code": "PE",
        "name": "Pernambuco"
      },
      "available": 4,
      "on_hand": 4,
      "reserved": 0,
      "damaged": 0,
      "allocated_mobile": 0,
      "safety_stock": 0,
      "by_warehouse": [
        {
          "warehouse_id": 1,
          "code": "PE",
          "name": "Pernambuco",
          "is_default": true,
          "available": 4,
          "on_hand": 4,
          "reserved": 0
        },
        {
          "warehouse_id": 2,
          "code": "SP",
          "name": "São Paulo",
          "is_default": false,
          "available": 0,
          "on_hand": 0,
          "reserved": 0
        }
      ],
      "all_warehouses": {
        "available": 4,
        "on_hand": 4,
        "reserved": 0
      },
      "is_kit": false
    },
    "channels": []
  }
}

Estoque: o que cada número quer dizer

Quatro palavras desta página: saldo por armazém = o estoque de um SKU num armazém (o que by_warehouse mostra e o que a venda e o ajuste mexem); cadastro antigo = SKU que ainda não tem saldo por armazém, só o contador do produto — o número aparece igual na leitura, mas o que muda nele não vem em /estoque/mudancas (chega pelo feed do catálogo, com até ~3 h de atraso em algumas gravações do painel); o primeiro ajuste ou venda pela API cria o saldo dele; armazém de casa = o Armazém escolhido na ficha do produto (sem ele, o padrão da empresa); razão = o histórico de movimentos (/estoque/movimentos).

Use stock_available (= stock.available). É o disponível para vender, pela mesma conta que a LOJEXA usa para aceitar uma venda, no armazém padrão da empresa (ou no armazém de warehouse). Os outros números explicam de onde ele vem.

CampoO que é
stock.available / stock_availableon_hand − reserved − allocated_mobile − damaged − safety_stock, nunca negativo, no armazém de stock.warehouse. SKU inativo: sempre 0 (a venda não aceita)
stock.warehouseO armazém dos números do topo: o padrão da empresa, ou o de warehouse=
stock.on_handFísico no armazém
stock.reservedReservado no armazém para pedidos ainda não enviados (hoje, o pedido da Shopee costuma entrar sem essa reserva: veja)
stock.damagedAvariado: está no armazém mas não vende
stock.allocated_mobileAlocado para o app offline da LOJEXA (fica reservado para o aparelho)
stock.safety_stockEstoque de segurança do armazém: não vende (no SKU de cadastro antigo, o Estoque mínimo da ficha do produto)
stock.by_warehouse[]Cada armazém: available, on_hand, reserved e is_default
stock.all_warehousesA soma de todos os armazéns
stock.is_kit / stock.kit_components[]Kit: veja abaixo
stock_total / stock_reservedLegado, mantidos para quem já integra: iguais a stock.on_hand e stock.reserved do armazém do topo (no kit, 0). Não use em integração nova
channels[]Cada loja vinculada ao SKU (channel, store_id, store_name) e stock_push_enabled: se a LOJEXA envia estoque para ela
variation.stock / variations[].stockEstoque do anúncio na Shopee (a última leitura do canal), não o da LOJEXA
available_before / available_afterEm /estoque/movimentos: o disponível do armazém antes e depois daquele movimento, como foi gravado

Kit

Kit não tem saldo próprio: available é quantos kits as peças montam — o menor floor(disponível da peça ÷ quantidade da peça no kit). on_hand, reserved, damaged, allocated_mobile e safety_stock vêm null, e kit_components[] traz cada peça com o available dela e os kits_possible. Na soma (all_warehouses) o kit é contado sobre a soma das peças: no exemplo abaixo, 20 camisetas montam 10 kits, e não 7 + 2.

Armazéns

  • Sem warehouse, vale o armazém padrão da empresa (o marcado como padrão; sem marcado, o primeiro ativo). GET /armazens lista os armazéns e diz qual é o padrão.
  • warehouse=<id ou code> (ex.: warehouse=SP) troca o armazém do topo em /produtos, /produtos/{sku} e nos feeds. Armazém inexistente, inativo ou de outra empresa: 422 WAREHOUSE_NOT_FOUND.
  • Cada loja vende de um armazém (GET /lojas, campo warehouse; null = o padrão). Se a sua integração vende de outro armazém, passe warehouse.
  • SKU que ainda não tem saldo por armazém (cadastro antigo) usa o contador do cadastro, no armazém de casa do SKU, sem criar nada (exemplo em Identificar o SKU).
  • Empresa sem armazém cadastrado: stock.warehouse vem null, by_warehouse vem vazio e o número está em stock.available e em all_warehouses.
  • Trocar o armazém padrão, ou ativar e desativar um armazém, muda o topo de stock de todos os SKUs sem aparecer em nenhum feed: refaça a carga completa quando isso acontecer (a reconciliação diária também pega).

Por que o número no marketplace pode ser diferente

  • A loja vende de outro armazém (GET /lojas → warehouse).
  • O envio de estoque da loja está desligado (stock_push_enabled: false): o anúncio fica com o último número que recebeu.
  • O fator do vínculo (quantity_factor): um anúncio de pacote com 3 unidades recebe o disponível dividido por 3.
  • Estoque de segurança e avaria saem do disponível antes do envio.
  • O estoque seguro da empresa (Configurações de sincronização, /sync-settings) é descontado no envio e não aparece em stock.available.
  • Uma regra de sincronização por categoria ou por loja pode trocar o número enviado.
  • Com a estratégia estoque total na sincronização, o anúncio recebe o físico do contador do cadastro, não o disponível.
  • O envio leva de segundos a alguns minutos e o marketplace pode recusar (o motivo fica no painel).
JSON — GET /produtos?search=camiseta&per_page=2: um SKU com saldo em dois armazéns e um kit de 2 dele
{
  "success": true,
  "data": [
    {
      "sku_master_id": 10,
      "sku_code": "CAMISETA-M-AZUL",
      "name": "Camiseta Básica Azul M",
      "status": "active",
      "updated_at": "2026-10-23T09:00:00-03:00",
      "stock_available": 15,
      "stock": {
        "warehouse": {
          "id": 1,
          "code": "PE",
          "name": "Pernambuco"
        },
        "available": 15,
        "on_hand": 18,
        "reserved": 2,
        "damaged": 1,
        "allocated_mobile": 0,
        "safety_stock": 0,
        "by_warehouse": [
          {
            "warehouse_id": 1,
            "code": "PE",
            "name": "Pernambuco",
            "is_default": true,
            "available": 15,
            "on_hand": 18,
            "reserved": 2
          },
          {
            "warehouse_id": 2,
            "code": "SP",
            "name": "São Paulo",
            "is_default": false,
            "available": 5,
            "on_hand": 5,
            "reserved": 0
          }
        ],
        "all_warehouses": {
          "available": 20,
          "on_hand": 23,
          "reserved": 2
        },
        "is_kit": false
      },
      "channels": [
        {
          "channel": "shopee",
          "store_id": 3,
          "store_name": "Luna Style Oficial",
          "stock_push_enabled": true
        },
        {
          "channel": "tiktok",
          "store_id": 7,
          "store_name": "Luna Style TikTok",
          "stock_push_enabled": false
        }
      ],
      "description": "100% algodão, fio 30.1",
      "barcode": "7891234567890",
      "cost_price": 29.9,
      "sale_price": 49.9,
      "brand": "Luna Style",
      "unit": "un",
      "stock_total": 18,
      "stock_reserved": 2,
      "min_stock": 0,
      "source_product_id": 23847719012,
      "source_variation_id": 198273645,
      "source_product": {
        "id": 1,
        "item_id": 23847719012,
        "name": "Camiseta Básica Algodão Luna",
        "description": "Camiseta básica 100% algodão."
      },
      "image_url": "https://cdn.exemplo.com/camiseta-azul.jpg",
      "images": [
        "https://cdn.exemplo.com/camiseta-azul.jpg"
      ],
      "colors": [
        "Azul"
      ],
      "sizes": [
        "M",
        "G"
      ],
      "variation_count": 2,
      "variation": {
        "id": 101,
        "model_id": 198273645,
        "name": "Azul,M",
        "sku": "CAMISETA-M-AZUL",
        "price": 49.9,
        "stock": 15,
        "status": "NORMAL",
        "image_url": null,
        "attributes": {
          "option_1": "Azul",
          "option_2": "M",
          "color": "Azul",
          "size": "M",
          "options": [
            {
              "name": "option_1",
              "value": "Azul"
            },
            {
              "name": "option_2",
              "value": "M"
            }
          ]
        }
      }
    },
    {
      "sku_master_id": 20,
      "sku_code": "KIT-CAMISETA-2",
      "name": "Kit 2 Camisetas Azul M",
      "status": "active",
      "updated_at": "2026-10-20T12:00:00-03:00",
      "stock_available": 7,
      "stock": {
        "warehouse": {
          "id": 1,
          "code": "PE",
          "name": "Pernambuco"
        },
        "available": 7,
        "on_hand": null,
        "reserved": null,
        "damaged": null,
        "allocated_mobile": null,
        "safety_stock": null,
        "by_warehouse": [
          {
            "warehouse_id": 1,
            "code": "PE",
            "name": "Pernambuco",
            "is_default": true,
            "available": 7,
            "on_hand": null,
            "reserved": null
          },
          {
            "warehouse_id": 2,
            "code": "SP",
            "name": "São Paulo",
            "is_default": false,
            "available": 2,
            "on_hand": null,
            "reserved": null
          }
        ],
        "all_warehouses": {
          "available": 10,
          "on_hand": null,
          "reserved": null
        },
        "is_kit": true,
        "kit_components": [
          {
            "sku_master_id": 10,
            "sku_code": "CAMISETA-M-AZUL",
            "quantity": 2,
            "available": 15,
            "kits_possible": 7
          }
        ]
      },
      "channels": [
        {
          "channel": "shopee",
          "store_id": 3,
          "store_name": "Luna Style Oficial",
          "stock_push_enabled": true
        }
      ],
      "description": null,
      "barcode": null,
      "cost_price": 59.8,
      "sale_price": 89.9,
      "brand": "Luna Style",
      "unit": "un",
      "stock_total": 0,
      "stock_reserved": 0,
      "min_stock": 0,
      "source_product_id": 23847719055,
      "source_variation_id": 198273699,
      "source_product": null,
      "image_url": null,
      "images": [],
      "colors": [],
      "sizes": [],
      "variation_count": 0,
      "variation": null
    }
  ],
  "meta": {
    "current_page": 1,
    "per_page": 2,
    "total": 2,
    "last_page": 1,
    "status": "active"
  }
}

Para o estoque chegar aos marketplaces

A venda e o ajuste pela API mudam o estoque na LOJEXA. O número só vai para o anúncio quando tudo abaixo é verdade:

  1. O SKU está vinculado ao anúncio, com a loja. Confira em channels do SKU ou em GET /mapeamentos?sku= (store_id preenchido).
  2. A sincronização de estoque da empresa está ligada e a loja está marcada para receber estoque da LOJEXA — no painel, Configurações → Config. Estoque (/sync-settings), onde o lojista escolhe as lojas que a LOJEXA controla. Isso é decisão do lojista; a API não liga.
  3. Confira pela API: stock_push_enabled: true na loja, em GET /lojas e em channels de cada SKU.
  4. O armazém de onde a loja vende tem o saldo (GET /lojas → warehouse, e stock.by_warehouse do SKU).
  • Canais que recebem estoque da LOJEXA: Shopee, Mercado Livre, Amazon, Shopify, Nuvemshop, Magalu, TikTok Shop, SHEIN e Temu.
  • Quando: o envio é disparado na gravação (venda, cancelamento, ajuste, pedido do marketplace); o anúncio costuma refletir em segundos a alguns minutos.
  • Onde ver o resultado do envio: no painel da LOJEXA, em Envio e estoque › Sincronização (filtre pelo Motivo "Venda pela API", "Ajuste pela API", "Lote de ajustes pela API" ou "Vínculo pela API"). A API não mostra se o marketplace aceitou o número: push: "queued" só diz que o envio entrou na fila.

Endpoints: produtos e estoque

Todos os parâmetros são de query string. Parâmetro conhecido com tipo errado ou fora do limite recebe 422 INVALID_PARAMETER, com a mensagem dizendo qual; parâmetro desconhecido é ignorado.

Em cada endpoint: a tabela de parâmetros (gerada do openapi.json, o mesmo contrato), a requisição e a resposta reais de uma empresa de exemplo (testadas a cada mudança da API) e os erros que ele devolve, com o que fazer.

Testar a chave

GET /api/v1/ping qualquer chave

Confere a chave e devolve a empresa e os escopos.

cURL
curl -sS --max-time 30 \
     -H "Authorization: Bearer $LOJEXA_API_KEY" \
     "https://lojexa.com/api/v1/ping"
JSON — resposta 200
{
  "success": true,
  "data": {
    "status": "ok",
    "company": "Loja da Maria",
    "scopes": [
      "read:products",
      "read:orders"
    ]
  }
}

Erros deste endpoint

Nenhum próprio: só os de toda chamada — 401 (chave), 403 (escopo ou empresa suspensa), 429 (limite) e 500: tabela de erros.

Consumo da chave

GET /api/v1/uso qualquer chave
  • rate_limit: o minuto atual, contando esta chamada (used é 0 quando o contador está fora do ar); reset_at é quando o minuto vira.
  • usage: vendas desta chave hoje e no mês, no horário de Brasília; reversed_this_month são as do mês já todas estornadas (canceladas ou devolvidas; a estornada em parte continua contando como venda); last_used_at é o uso anterior a esta chamada.
  • expires_at: fim do dia de expiração (null = não expira).
cURL
curl -sS --max-time 30 \
     -H "Authorization: Bearer $LOJEXA_API_KEY" \
     "https://lojexa.com/api/v1/uso"
JSON — resposta 200
{
  "success": true,
  "data": {
    "key_name": "Checkout do site",
    "key_prefix": "lj_live_e5f6",
    "scopes": [
      "read:products",
      "write:sales"
    ],
    "rate_limit": {
      "per_minute": 60,
      "used": 1,
      "remaining": 59,
      "reset_at": "2026-10-23T10:15:00-03:00"
    },
    "usage": {
      "sales_today": 3,
      "sales_this_month": 3,
      "reversed_this_month": 1,
      "last_used_at": "2026-10-23T10:14:31-03:00"
    },
    "webhook_configured": true,
    "expires_at": "2027-01-31T23:59:59-03:00"
  }
}

Erros deste endpoint

Nenhum próprio: só os de toda chamada — 401 (chave), 403 (escopo ou empresa suspensa), 429 (limite) e 500: tabela de erros.

Listar produtos

GET /api/v1/produtos read:products

A lista paginada dos SKUs, só ativos por padrão, em ordem de nome com desempate pelo id: paginando de 1 até last_page, nenhum SKU se repete nem fica de fora (se o catálogo não mudar no meio). Cada item traz o estoque (o que cada número quer dizer), as lojas em channels e o catálogo do anúncio de origem (imagens, cores, tamanhos, variação).

O mesmo endpoint tem mais dois modos, que não combinam com page, per_page e search: por SKU (sku/skus) e feed do catálogo (updated_since/cursor).

NomeOndeTipoObrig.PadrãoLimitesExemplo
pagequeryinteiroNão11 a 1.000.0001
Só na lista paginada
per_pagequeryinteiroNão501 a 100100
Só na lista paginada
searchquerytextoNão—até 100 caracterescamiseta
Trecho do nome ou do SKU (só na lista paginada)
skuquerytextoNão—até 100 caracteresCAMISETA-M-AZUL
UM SKU exato, inclusive com "/" ou ",". Vem com variations, como o detalhe.
skusquerytextoNão——CAMISETA-M-AZUL,BONE-PRETO
Até 100 SKUs exatos separados por vírgula.
include_variationsquerybooleanoNãofalse—true
true/false ou 1/0: inclui todas as variações do anúncio.
category obsoletoquerytextoNão———
OBSOLETO: aceito e ignorado (nunca filtrou nada).
statusquerytextoNão—um de: active, inactive, allall
Padrão active na listagem; all no feed (updated_since/cursor) e na consulta por sku/skus. SKU inativo vem com available 0.
warehousequerytextoNão——PE
id ou code de um armazém ativo (GET /armazens): o armazém do topo de stock. Sem ele, vale o armazém padrão da empresa. Outro valor: 422 WAREHOUSE_NOT_FOUND.
fieldsquerytextoNão—um de: stockstock
stock = só identificação, status, estoque e canais (sem catálogo nem imagens).
updated_sincequerytextoNão——2026-10-23T00:00:00-03:00
FEED do catálogo: SKUs criados, alterados ou inativados desde (ISO 8601). Inclusivo. Só na primeira chamada; page, per_page e search não combinam. Codifique o "+" de um fuso positivo como %2B.
cursorquerytextoNão—até 200 caractereseyJ1IjoiMjAyNi0xMC0yMyAxNDo1ODowMCIsImkiOjkyMjMzNzIwMzY4NTQ3NzU4MDd9
FEED do catálogo: copie meta.next_cursor. Algumas gravações do painel podem entrar até ~3 h depois (nunca se perdem); faça a reconciliação diária completa.
limitqueryinteiroNão501 a 100100
Só no feed (com updated_since/cursor).
cURL
curl -sS --max-time 30 \
     -H "Authorization: Bearer $LOJEXA_API_KEY" \
     "https://lojexa.com/api/v1/produtos?search=camiseta&per_page=2"

Erros deste endpoint

HTTPCódigoQuando aconteceO que fazer
422INVALID_PARAMETERParâmetro de consulta com tipo errado, fora do limite ou em combinação proibida (a mensagem diz qual).Corrija o parâmetro citado. Os limites de cada endpoint estão na tabela de parâmetros.
422INVALID_CURSORO cursor foi alterado, cortado ou veio de outro endpoint.Repasse meta.next_cursor exatamente como veio. Para recomeçar, use updated_since.
422WAREHOUSE_NOT_FOUNDO warehouse da consulta (ou do corpo de POST /vendas e do ajuste, no corpo ou no item) não é o id nem o code de um armazém ativo da empresa da chave. No lote de ajustes, o warehouse padrão do lote recusa o lote inteiro; o do item, só o item.Liste os armazéns em GET /armazens e use o id ou o code. Sem warehouse, vale o armazém padrão da empresa.

Mais os de toda chamada — 401 (chave), 403 (escopo ou empresa suspensa), 429 (limite) e 500: tabela de erros.

A resposta deste exemplo está em Estoque: o que cada número quer dizer (um SKU com saldo em dois armazéns e um kit). Com fields=stock, cada item fica só com sku_master_id, sku_code, name, status, updated_at, stock_available, stock e channels.

Detalhe de um produto

GET /api/v1/produtos/{sku} read:products

O produto completo, com todas as variações do anúncio em variations. O {sku} vai codificado; maiúsculas e minúsculas não importam. Aceita warehouse e fields=stock.

  • SKU inativo: 200 com "status": "inactive" e available 0 (a venda não o aceita).
  • SKU que não existe na empresa da chave: 404 PRODUCT_NOT_FOUND (exemplo em Formato de resposta).
  • SKU vazio, com caractere de controle ou codificação inválida: 400 INVALID_SKU.
NomeOndeTipoObrig.PadrãoLimitesExemplo
skucaminhotextoSim—até 100 caracteres007-Preto-G1 (48 ao 52)
O SKU codificado (ex.: 007-Preto-G1%20(48%20ao%2052))
warehousequerytextoNão——PE
id ou code de um armazém ativo (GET /armazens): o armazém do topo de stock. Sem ele, vale o armazém padrão da empresa. Outro valor: 422 WAREHOUSE_NOT_FOUND.
fieldsquerytextoNão—um de: stockstock
stock = só identificação, status, estoque e canais (sem catálogo nem imagens).
cURL
curl -sS --max-time 30 \
     -H "Authorization: Bearer $LOJEXA_API_KEY" \
     "https://lojexa.com/api/v1/produtos/CAMISETA-M-AZUL"
JSON — resposta 200
{
  "success": true,
  "data": {
    "sku_master_id": 10,
    "sku_code": "CAMISETA-M-AZUL",
    "name": "Camiseta Básica Azul M",
    "status": "active",
    "updated_at": "2026-10-23T09:00:00-03:00",
    "stock_available": 15,
    "stock": {
      "warehouse": {
        "id": 1,
        "code": "PE",
        "name": "Pernambuco"
      },
      "available": 15,
      "on_hand": 18,
      "reserved": 2,
      "damaged": 1,
      "allocated_mobile": 0,
      "safety_stock": 0,
      "by_warehouse": [
        {
          "warehouse_id": 1,
          "code": "PE",
          "name": "Pernambuco",
          "is_default": true,
          "available": 15,
          "on_hand": 18,
          "reserved": 2
        },
        {
          "warehouse_id": 2,
          "code": "SP",
          "name": "São Paulo",
          "is_default": false,
          "available": 5,
          "on_hand": 5,
          "reserved": 0
        }
      ],
      "all_warehouses": {
        "available": 20,
        "on_hand": 23,
        "reserved": 2
      },
      "is_kit": false
    },
    "channels": [
      {
        "channel": "shopee",
        "store_id": 3,
        "store_name": "Luna Style Oficial",
        "stock_push_enabled": true
      },
      {
        "channel": "tiktok",
        "store_id": 7,
        "store_name": "Luna Style TikTok",
        "stock_push_enabled": false
      }
    ],
    "description": "100% algodão, fio 30.1",
    "barcode": "7891234567890",
    "cost_price": 29.9,
    "sale_price": 49.9,
    "brand": "Luna Style",
    "unit": "un",
    "stock_total": 18,
    "stock_reserved": 2,
    "min_stock": 0,
    "source_product_id": 23847719012,
    "source_variation_id": 198273645,
    "source_product": {
      "id": 1,
      "item_id": 23847719012,
      "name": "Camiseta Básica Algodão Luna",
      "description": "Camiseta básica 100% algodão."
    },
    "image_url": "https://cdn.exemplo.com/camiseta-azul.jpg",
    "images": [
      "https://cdn.exemplo.com/camiseta-azul.jpg"
    ],
    "colors": [
      "Azul"
    ],
    "sizes": [
      "M",
      "G"
    ],
    "variation_count": 2,
    "variation": {
      "id": 101,
      "model_id": 198273645,
      "name": "Azul,M",
      "sku": "CAMISETA-M-AZUL",
      "price": 49.9,
      "stock": 15,
      "status": "NORMAL",
      "image_url": null,
      "attributes": {
        "option_1": "Azul",
        "option_2": "M",
        "color": "Azul",
        "size": "M",
        "options": [
          {
            "name": "option_1",
            "value": "Azul"
          },
          {
            "name": "option_2",
            "value": "M"
          }
        ]
      }
    },
    "variations": [
      {
        "id": 101,
        "model_id": 198273645,
        "name": "Azul,M",
        "sku": "CAMISETA-M-AZUL",
        "price": 49.9,
        "stock": 15,
        "status": "NORMAL",
        "image_url": null,
        "attributes": {
          "option_1": "Azul",
          "option_2": "M",
          "color": "Azul",
          "size": "M",
          "options": [
            {
              "name": "option_1",
              "value": "Azul"
            },
            {
              "name": "option_2",
              "value": "M"
            }
          ]
        }
      },
      {
        "id": 102,
        "model_id": 198273646,
        "name": "Azul,G",
        "sku": "CAMISETA-G-AZUL",
        "price": 49.9,
        "stock": 8,
        "status": "NORMAL",
        "image_url": null,
        "attributes": {
          "option_1": "Azul",
          "option_2": "G",
          "color": "Azul",
          "size": "G",
          "options": [
            {
              "name": "option_1",
              "value": "Azul"
            },
            {
              "name": "option_2",
              "value": "G"
            }
          ]
        }
      }
    ]
  }
}

Erros deste endpoint

HTTPCódigoQuando aconteceO que fazer
400INVALID_SKUO SKU do caminho está vazio ou, decodificado, não é texto UTF-8.Codifique o SKU (JavaScript encodeURIComponent, Python quote(sku, safe=""), PHP rawurlencode).
422INVALID_PARAMETERParâmetro de consulta com tipo errado, fora do limite ou em combinação proibida (a mensagem diz qual).Corrija o parâmetro citado. Os limites de cada endpoint estão na tabela de parâmetros.
422WAREHOUSE_NOT_FOUNDO warehouse da consulta (ou do corpo de POST /vendas e do ajuste, no corpo ou no item) não é o id nem o code de um armazém ativo da empresa da chave. No lote de ajustes, o warehouse padrão do lote recusa o lote inteiro; o do item, só o item.Liste os armazéns em GET /armazens e use o id ou o code. Sem warehouse, vale o armazém padrão da empresa.
404PRODUCT_NOT_FOUNDNenhum SKU com esse código na empresa da chave (no detalhe e em /estoque/movimentos?sku=, ativo ou inativo; o inativo vem com status=inactive).Use o sku_code da LOJEXA (maiúsculas e minúsculas não importam).

Mais os de toda chamada — 401 (chave), 403 (escopo ou empresa suspensa), 429 (limite) e 500: tabela de erros.

Buscar por SKU (um ou até 100)

GET /api/v1/produtos?skus=A,B,C read:products

?sku= traz UM SKU (inclusive com / ou ,), com as variações, como o detalhe. ?skus= traz até 100, sem as variações (peça com include_variations=true). A resposta vem na ordem pedida, inativo incluído (status=active o deixa de fora), e meta.not_found lista os que não existem na empresa. Não combina com page, per_page, search e limit; sku e skus não vêm juntos.

cURL
curl -sS --max-time 30 \
     -H "Authorization: Bearer $LOJEXA_API_KEY" \
     "https://lojexa.com/api/v1/produtos?skus=CAMISETA-M-AZUL,BONE-PRETO,NAO-EXISTE&fields=stock"
JSON — resposta 200
{
  "success": true,
  "data": [
    {
      "sku_master_id": 10,
      "sku_code": "CAMISETA-M-AZUL",
      "name": "Camiseta Básica Azul M",
      "status": "active",
      "updated_at": "2026-10-23T09:00:00-03:00",
      "stock_available": 15,
      "stock": {
        "warehouse": {
          "id": 1,
          "code": "PE",
          "name": "Pernambuco"
        },
        "available": 15,
        "on_hand": 18,
        "reserved": 2,
        "damaged": 1,
        "allocated_mobile": 0,
        "safety_stock": 0,
        "by_warehouse": [
          {
            "warehouse_id": 1,
            "code": "PE",
            "name": "Pernambuco",
            "is_default": true,
            "available": 15,
            "on_hand": 18,
            "reserved": 2
          },
          {
            "warehouse_id": 2,
            "code": "SP",
            "name": "São Paulo",
            "is_default": false,
            "available": 5,
            "on_hand": 5,
            "reserved": 0
          }
        ],
        "all_warehouses": {
          "available": 20,
          "on_hand": 23,
          "reserved": 2
        },
        "is_kit": false
      },
      "channels": [
        {
          "channel": "shopee",
          "store_id": 3,
          "store_name": "Luna Style Oficial",
          "stock_push_enabled": true
        },
        {
          "channel": "tiktok",
          "store_id": 7,
          "store_name": "Luna Style TikTok",
          "stock_push_enabled": false
        }
      ]
    },
    {
      "sku_master_id": 30,
      "sku_code": "BONE-PRETO",
      "name": "Boné Preto",
      "status": "inactive",
      "updated_at": "2026-10-22T18:30:00-03:00",
      "stock_available": 0,
      "stock": {
        "warehouse": {
          "id": 1,
          "code": "PE",
          "name": "Pernambuco"
        },
        "available": 0,
        "on_hand": 3,
        "reserved": 0,
        "damaged": 0,
        "allocated_mobile": 0,
        "safety_stock": 0,
        "by_warehouse": [
          {
            "warehouse_id": 1,
            "code": "PE",
            "name": "Pernambuco",
            "is_default": true,
            "available": 0,
            "on_hand": 3,
            "reserved": 0
          },
          {
            "warehouse_id": 2,
            "code": "SP",
            "name": "São Paulo",
            "is_default": false,
            "available": 0,
            "on_hand": 0,
            "reserved": 0
          }
        ],
        "all_warehouses": {
          "available": 0,
          "on_hand": 3,
          "reserved": 0
        },
        "is_kit": false
      },
      "channels": []
    }
  ],
  "meta": {
    "requested": 3,
    "found": 2,
    "not_found": [
      "NAO-EXISTE"
    ]
  }
}

Parâmetros e erros: os de GET /produtos (é o mesmo endpoint).

Feed do catálogo (SKUs novos, alterados e inativados)

GET /api/v1/produtos?updated_since=… read:products

Os SKUs criados, alterados ou inativados desde a data, em ordem de alteração, por cursor — o mesmo mecanismo de /orders. O SKU inativado vem com "status": "inactive" (é o aviso de que ele saiu). O objeto de cada item é o da lista (aceita fields=stock, warehouse e include_variations).

  • Horizonte de 2 minutos: só entra o que foi gravado até meta.sync_horizon (agora menos 2 min). Sem mais páginas (has_more: false), next_cursor aponta para o horizonte: guarde e use na próxima rodada, mesmo com a página vazia.
  • Algumas gravações do painel — o contador antigo de estoque, o app desktop, a fusão de SKUs e o produto criado a partir de um pedido — podem levar até ~3 h para entrar no feed: atrasam, nunca se perdem. O saldo por armazém chega por /estoque/mudancas; o estoque de SKU que ainda não tem saldo por armazém só chega por este feed (até ~3 h) ou pela reconciliação diária.
  • Aplique cada item na ordem em que chega: ele já traz o estado atual do SKU. O updated_at está no relógio deste feed (o mesmo de updated_since, cursor e sync_horizon) e não é o instante exato — a gravação pelo contador antigo aparece até 3 h à frente. Não use updated_at para decidir qual versão é a mais nova.
  • Guarde pelo sku_master_id: o código do SKU pode ser trocado na ficha, e a troca chega aqui como o mesmo sku_master_id com o sku_code novo — o código antigo não vem como inativo.
cURL
curl -sS --max-time 30 \
     -H "Authorization: Bearer $LOJEXA_API_KEY" \
     "https://lojexa.com/api/v1/produtos?updated_since=2026-10-22T00:00:00-03:00&fields=stock"
JSON — resposta 200
{
  "success": true,
  "data": [
    {
      "sku_master_id": 30,
      "sku_code": "BONE-PRETO",
      "name": "Boné Preto",
      "status": "inactive",
      "updated_at": "2026-10-22T18:30:00-03:00",
      "stock_available": 0,
      "stock": {
        "warehouse": {
          "id": 1,
          "code": "PE",
          "name": "Pernambuco"
        },
        "available": 0,
        "on_hand": 3,
        "reserved": 0,
        "damaged": 0,
        "allocated_mobile": 0,
        "safety_stock": 0,
        "by_warehouse": [
          {
            "warehouse_id": 1,
            "code": "PE",
            "name": "Pernambuco",
            "is_default": true,
            "available": 0,
            "on_hand": 3,
            "reserved": 0
          },
          {
            "warehouse_id": 2,
            "code": "SP",
            "name": "São Paulo",
            "is_default": false,
            "available": 0,
            "on_hand": 0,
            "reserved": 0
          }
        ],
        "all_warehouses": {
          "available": 0,
          "on_hand": 3,
          "reserved": 0
        },
        "is_kit": false
      },
      "channels": []
    },
    {
      "sku_master_id": 10,
      "sku_code": "CAMISETA-M-AZUL",
      "name": "Camiseta Básica Azul M",
      "status": "active",
      "updated_at": "2026-10-23T09:00:00-03:00",
      "stock_available": 15,
      "stock": {
        "warehouse": {
          "id": 1,
          "code": "PE",
          "name": "Pernambuco"
        },
        "available": 15,
        "on_hand": 18,
        "reserved": 2,
        "damaged": 1,
        "allocated_mobile": 0,
        "safety_stock": 0,
        "by_warehouse": [
          {
            "warehouse_id": 1,
            "code": "PE",
            "name": "Pernambuco",
            "is_default": true,
            "available": 15,
            "on_hand": 18,
            "reserved": 2
          },
          {
            "warehouse_id": 2,
            "code": "SP",
            "name": "São Paulo",
            "is_default": false,
            "available": 5,
            "on_hand": 5,
            "reserved": 0
          }
        ],
        "all_warehouses": {
          "available": 20,
          "on_hand": 23,
          "reserved": 2
        },
        "is_kit": false
      },
      "channels": [
        {
          "channel": "shopee",
          "store_id": 3,
          "store_name": "Luna Style Oficial",
          "stock_push_enabled": true
        },
        {
          "channel": "tiktok",
          "store_id": 7,
          "store_name": "Luna Style TikTok",
          "stock_push_enabled": false
        }
      ]
    }
  ],
  "meta": {
    "limit": 50,
    "count": 2,
    "has_more": false,
    "next_cursor": "eyJ1IjoiMjAyNi0xMC0yMyAxNDo1ODowMCIsImkiOjkyMjMzNzIwMzY4NTQ3NzU4MDd9",
    "sync_horizon": "2026-10-23T14:58:00-03:00",
    "status": "all"
  }
}

Parâmetros e erros: os de GET /produtos (é o mesmo endpoint).

Mudanças de estoque (feed por cursor)

GET /api/v1/estoque/mudancas read:products

Os SKUs cujo saldo mudou, lidos do razão de estoque (reserva, baixa, liberação, devolução, transferência, app, avaria e ajuste). Cada SKU vem uma vez por página, com o estoque atual (o mesmo objeto stock de /produtos) e changed_at, o último movimento dele na página. Quando uma peça muda, o kit que a usa vem junto ("change": "kit_component") e conta no limit. Mesmo horizonte e cursor do feed do catálogo.

NomeOndeTipoObrig.PadrãoLimitesExemplo
limitqueryinteiroNão1001 a 500500
Itens por página. Com has_more true, chame de novo na hora com o next_cursor.
cursorquerytextoNão—até 200 caractereseyJ1IjoiMjAyNi0xMC0yMyAxNDo1ODowMCIsImkiOjkyMjMzNzIwMzY4NTQ3NzU4MDd9
Opaco: copie meta.next_cursor. Não vem junto com updated_since.
updated_sincequerytextoNão——2026-10-23T00:00:00-03:00
ISO 8601, inclusivo. Só na primeira chamada.
warehousequerytextoNão——PE
id ou code de um armazém ativo (GET /armazens): só os movimentos dele, e o topo de stock passa a ser dele. Sem ele, vêm os movimentos de TODOS os armazéns (o topo de stock continua o armazém padrão). Outro valor: 422 WAREHOUSE_NOT_FOUND.
Ficam fora do razão, e por isso fora deste feed: o contador de SKU que ainda não tem saldo por armazém, o estoque inicial trazido do anúncio quando um SKU sem saldo é vinculado, a troca da receita de um kit, o estoque de segurança e a troca do armazém padrão (ou a ativação e desativação de um armazém). Faça uma reconciliação diária completa com GET /produtos?fields=stock&status=all (veja o guia).
cURL
curl -sS --max-time 30 \
     -H "Authorization: Bearer $LOJEXA_API_KEY" \
     "https://lojexa.com/api/v1/estoque/mudancas?updated_since=2026-10-23T00:00:00-03:00"
JSON — resposta 200 (a peça mudou e o kit acordou junto)
{
  "success": true,
  "data": [
    {
      "sku_master_id": 10,
      "sku_code": "CAMISETA-M-AZUL",
      "name": "Camiseta Básica Azul M",
      "status": "active",
      "stock_available": 15,
      "stock": {
        "warehouse": {
          "id": 1,
          "code": "PE",
          "name": "Pernambuco"
        },
        "available": 15,
        "on_hand": 18,
        "reserved": 2,
        "damaged": 1,
        "allocated_mobile": 0,
        "safety_stock": 0,
        "by_warehouse": [
          {
            "warehouse_id": 1,
            "code": "PE",
            "name": "Pernambuco",
            "is_default": true,
            "available": 15,
            "on_hand": 18,
            "reserved": 2
          },
          {
            "warehouse_id": 2,
            "code": "SP",
            "name": "São Paulo",
            "is_default": false,
            "available": 5,
            "on_hand": 5,
            "reserved": 0
          }
        ],
        "all_warehouses": {
          "available": 20,
          "on_hand": 23,
          "reserved": 2
        },
        "is_kit": false
      },
      "channels": [
        {
          "channel": "shopee",
          "store_id": 3,
          "store_name": "Luna Style Oficial",
          "stock_push_enabled": true
        },
        {
          "channel": "tiktok",
          "store_id": 7,
          "store_name": "Luna Style TikTok",
          "stock_push_enabled": false
        }
      ],
      "changed_at": "2026-10-23T10:12:00-03:00",
      "change": "movement"
    },
    {
      "sku_master_id": 20,
      "sku_code": "KIT-CAMISETA-2",
      "name": "Kit 2 Camisetas Azul M",
      "status": "active",
      "stock_available": 7,
      "stock": {
        "warehouse": {
          "id": 1,
          "code": "PE",
          "name": "Pernambuco"
        },
        "available": 7,
        "on_hand": null,
        "reserved": null,
        "damaged": null,
        "allocated_mobile": null,
        "safety_stock": null,
        "by_warehouse": [
          {
            "warehouse_id": 1,
            "code": "PE",
            "name": "Pernambuco",
            "is_default": true,
            "available": 7,
            "on_hand": null,
            "reserved": null
          },
          {
            "warehouse_id": 2,
            "code": "SP",
            "name": "São Paulo",
            "is_default": false,
            "available": 2,
            "on_hand": null,
            "reserved": null
          }
        ],
        "all_warehouses": {
          "available": 10,
          "on_hand": null,
          "reserved": null
        },
        "is_kit": true,
        "kit_components": [
          {
            "sku_master_id": 10,
            "sku_code": "CAMISETA-M-AZUL",
            "quantity": 2,
            "available": 15,
            "kits_possible": 7
          }
        ]
      },
      "channels": [
        {
          "channel": "shopee",
          "store_id": 3,
          "store_name": "Luna Style Oficial",
          "stock_push_enabled": true
        }
      ],
      "changed_at": "2026-10-23T10:12:00-03:00",
      "change": "kit_component"
    }
  ],
  "meta": {
    "limit": 100,
    "count": 2,
    "has_more": false,
    "next_cursor": "eyJ1IjoiMjAyNi0xMC0yMyAxNDo1ODowMCIsImkiOjkyMjMzNzIwMzY4NTQ3NzU4MDd9",
    "sync_horizon": "2026-10-23T14:58:00-03:00",
    "warehouse": null
  }
}

Erros deste endpoint

HTTPCódigoQuando aconteceO que fazer
422INVALID_PARAMETERParâmetro de consulta com tipo errado, fora do limite ou em combinação proibida (a mensagem diz qual).Corrija o parâmetro citado. Os limites de cada endpoint estão na tabela de parâmetros.
422INVALID_CURSORO cursor foi alterado, cortado ou veio de outro endpoint.Repasse meta.next_cursor exatamente como veio. Para recomeçar, use updated_since.
422WAREHOUSE_NOT_FOUNDO warehouse da consulta (ou do corpo de POST /vendas e do ajuste, no corpo ou no item) não é o id nem o code de um armazém ativo da empresa da chave. No lote de ajustes, o warehouse padrão do lote recusa o lote inteiro; o do item, só o item.Liste os armazéns em GET /armazens e use o id ou o code. Sem warehouse, vale o armazém padrão da empresa.

Mais os de toda chamada — 401 (chave), 403 (escopo ou empresa suspensa), 429 (limite) e 500: tabela de erros.

Movimentos de estoque (razão)

GET /api/v1/estoque/movimentos read:products

As linhas do razão, para conciliar por que o saldo mudou: kind e kind_label, qty_delta, o disponível do armazém antes e depois e, quando há, o pedido de origem (order.channel e order.order_sn). Não traz usuário, aparelho nem dados internos do movimento. Mesmo horizonte e cursor dos feeds.

  • O que você fez pela API vem com source: source.type = api_sale (venda), api_sale_cancel (cancelamento), api_sale_return (devolução) ou api_stock_adjust (ajuste e lote), e source.id = a reference da venda ou o adjustment_id do ajuste. Concilie por source, não por kind: a venda pela API sai como baixa e o cancelamento como devolucao (o estoque volta), o mesmo kind dos movimentos do painel.
  • Avaria: qty_delta conta a peça avariada (+1 = uma peça a mais separada como avariada), não o disponível (que cai 1 numa avaria: confira em GET /produtos/{sku}). Não some qty_delta de avaria com o das vendas.
NomeOndeTipoObrig.PadrãoLimitesExemplo
skuquerytextoNão—até 100 caracteresCAMISETA-M-AZUL
Só os movimentos deste SKU (maiúsculas e minúsculas não importam; aceita "/"). Inexistente: 404 PRODUCT_NOT_FOUND.
limitqueryinteiroNão1001 a 500500
Itens por página. Com has_more true, chame de novo na hora com o next_cursor.
cursorquerytextoNão—até 200 caractereseyJ1IjoiMjAyNi0xMC0yMyAxNDo1ODowMCIsImkiOjkyMjMzNzIwMzY4NTQ3NzU4MDd9
Opaco: copie meta.next_cursor. Não vem junto com updated_since.
updated_sincequerytextoNão——2026-10-23T00:00:00-03:00
ISO 8601, inclusivo. Só na primeira chamada.
warehousequerytextoNão——PE
id ou code de um armazém ativo (GET /armazens): só os movimentos dele, e o topo de stock passa a ser dele. Sem ele, vêm os movimentos de TODOS os armazéns (o topo de stock continua o armazém padrão). Outro valor: 422 WAREHOUSE_NOT_FOUND.
kindkind_label
entradaEntrada
saidaSaída
reservaReserva
liberacaoLiberação
baixaBaixa por envio
ajusteAjuste
transferenciaTransferência
devolucaoDevolução
cancelamentoCancelamento
contagemContagem
avariaAvaria
outroOutro
cURL
curl -sS --max-time 30 \
     -H "Authorization: Bearer $LOJEXA_API_KEY" \
     "https://lojexa.com/api/v1/estoque/movimentos?sku=CAMISETA-M-AZUL&updated_since=2026-10-23T00:00:00-03:00"
JSON — resposta 200
{
  "success": true,
  "data": [
    {
      "id": 901,
      "created_at": "2026-10-23T10:05:00-03:00",
      "sku_master_id": 10,
      "sku_code": "CAMISETA-M-AZUL",
      "warehouse": {
        "id": 1,
        "code": "PE",
        "name": "Pernambuco"
      },
      "type": "sale_reserve",
      "kind": "reserva",
      "kind_label": "Reserva",
      "qty_delta": -1,
      "available_before": 16,
      "available_after": 15,
      "source": {
        "type": "stock_reservation",
        "id": "5521"
      },
      "order": {
        "id": 198734,
        "channel": "shopee",
        "order_sn": "251023K7PQ2M1X"
      }
    },
    {
      "id": 902,
      "created_at": "2026-10-23T10:12:00-03:00",
      "sku_master_id": 10,
      "sku_code": "CAMISETA-M-AZUL",
      "warehouse": {
        "id": 2,
        "code": "SP",
        "name": "São Paulo"
      },
      "type": "purchase_entry",
      "kind": "entrada",
      "kind_label": "Entrada",
      "qty_delta": 5,
      "available_before": 0,
      "available_after": 5,
      "source": {
        "type": "purchase",
        "id": null
      },
      "order": null
    }
  ],
  "meta": {
    "limit": 100,
    "count": 2,
    "has_more": false,
    "next_cursor": "eyJ1IjoiMjAyNi0xMC0yMyAxNDo1ODowMCIsImkiOjkyMjMzNzIwMzY4NTQ3NzU4MDd9",
    "sync_horizon": "2026-10-23T14:58:00-03:00"
  }
}

Erros deste endpoint

HTTPCódigoQuando aconteceO que fazer
422INVALID_PARAMETERParâmetro de consulta com tipo errado, fora do limite ou em combinação proibida (a mensagem diz qual).Corrija o parâmetro citado. Os limites de cada endpoint estão na tabela de parâmetros.
422INVALID_CURSORO cursor foi alterado, cortado ou veio de outro endpoint.Repasse meta.next_cursor exatamente como veio. Para recomeçar, use updated_since.
422WAREHOUSE_NOT_FOUNDO warehouse da consulta (ou do corpo de POST /vendas e do ajuste, no corpo ou no item) não é o id nem o code de um armazém ativo da empresa da chave. No lote de ajustes, o warehouse padrão do lote recusa o lote inteiro; o do item, só o item.Liste os armazéns em GET /armazens e use o id ou o code. Sem warehouse, vale o armazém padrão da empresa.
404PRODUCT_NOT_FOUNDNenhum SKU com esse código na empresa da chave (no detalhe e em /estoque/movimentos?sku=, ativo ou inativo; o inativo vem com status=inactive).Use o sku_code da LOJEXA (maiúsculas e minúsculas não importam).

Mais os de toda chamada — 401 (chave), 403 (escopo ou empresa suspensa), 429 (limite) e 500: tabela de erros.

Armazéns

GET /api/v1/armazens read:products

Os armazéns da empresa. is_default (e meta.default_warehouse_id) marca o que vale quando a chamada não traz warehouse. Use o id ou o code no parâmetro warehouse.

cURL
curl -sS --max-time 30 \
     -H "Authorization: Bearer $LOJEXA_API_KEY" \
     "https://lojexa.com/api/v1/armazens"
JSON — resposta 200
{
  "success": true,
  "data": [
    {
      "id": 1,
      "code": "PE",
      "name": "Pernambuco",
      "is_default": true,
      "active": true
    },
    {
      "id": 2,
      "code": "SP",
      "name": "São Paulo",
      "is_default": false,
      "active": true
    }
  ],
  "meta": {
    "default_warehouse_id": 1
  }
}

Erros deste endpoint

Nenhum próprio: só os de toda chamada — 401 (chave), 403 (escopo ou empresa suspensa), 429 (limite) e 500: tabela de erros.

Lojas e envio de estoque

GET /api/v1/lojas read:products

As lojas conectadas (Shopee, Mercado Livre, TikTok Shop, SHEIN, Temu, Magalu e Nuvemshop), o armazém de onde cada uma vende (warehouse; null = o padrão) e stock_push_enabled: se a LOJEXA envia estoque para ela. Com false, a venda e o ajuste mudam o estoque na LOJEXA mas não chegam ao anúncio daquela loja. Ligar é decisão do lojista, no painel (checklist); a API só informa. Lojas Amazon e Shopify não aparecem nesta lista, mas aparecem em channels do SKU.

cURL
curl -sS --max-time 30 \
     -H "Authorization: Bearer $LOJEXA_API_KEY" \
     "https://lojexa.com/api/v1/lojas"
JSON — resposta 200
{
  "success": true,
  "data": [
    {
      "channel": "shopee",
      "store_id": 3,
      "name": "Luna Style Oficial",
      "status": "active",
      "stock_push_enabled": true,
      "warehouse": null
    },
    {
      "channel": "tiktok",
      "store_id": 7,
      "name": "Luna Style TikTok",
      "status": "active",
      "stock_push_enabled": false,
      "warehouse": {
        "id": 2,
        "code": "SP",
        "name": "São Paulo"
      }
    }
  ]
}

Erros deste endpoint

Nenhum próprio: só os de toda chamada — 401 (chave), 403 (escopo ou empresa suspensa), 429 (limite) e 500: tabela de erros.

Listar mapeamentos (vínculos SKU ↔ anúncio)

GET /api/v1/mapeamentos read:products

Os vínculos entre os SKUs da LOJEXA e os anúncios dos canais, em ordem de nome do SKU, plataforma e id. stock_available é o mesmo número de /produtos (armazém padrão); quantity_factor é quantas unidades do SKU vão em uma unidade do anúncio; platform_sku_id é a variação no canal, como texto de dígitos (o id do TikTok tem 19 dígitos, acima do que o número do JavaScript guarda sem arredondar; "0" = anúncio sem variação); listing_sku, o SKU da listagem (Amazon); store_id e store_name, a loja (a de GET /lojas).

NomeOndeTipoObrig.PadrãoLimitesExemplo
platformquerytextoNão—até 50 caracteresshopee
Filtra pela plataforma exata (shopee, mercadolivre, magalu, nuvemshop, shopify, amazon, tiktok, shein, temu)
skuquerytextoNão—até 100 caracteresCAMISETA-M-AZUL
Só os vínculos deste SKU (maiúsculas e minúsculas não importam)
pagequeryinteiroNão11 a 1.000.0001
A página, de 1 até meta.last_page.
per_pagequeryinteiroNão501 a 100100
Vínculos por página.
cURL
curl -sS --max-time 30 \
     -H "Authorization: Bearer $LOJEXA_API_KEY" \
     "https://lojexa.com/api/v1/mapeamentos?sku=CAMISETA-M-AZUL"
JSON — resposta 200
{
  "success": true,
  "data": [
    {
      "id": 17,
      "sku_master_id": 10,
      "platform": "shopee",
      "platform_sku": "CAMISETA-M-AZUL",
      "platform_product_id": "23847719012",
      "store_id": 3,
      "quantity_factor": 1,
      "created_at": "2026-10-01T10:00:00-03:00",
      "master_sku": "CAMISETA-M-AZUL",
      "master_name": "Camiseta Básica Azul M",
      "stock_available": 15,
      "platform_sku_id": "198273645",
      "listing_sku": null,
      "store_name": "Luna Style Oficial"
    },
    {
      "id": 18,
      "sku_master_id": 10,
      "platform": "tiktok",
      "platform_sku": "CAMISETA-M-AZUL",
      "platform_product_id": "1729384756",
      "store_id": 7,
      "quantity_factor": 1,
      "created_at": "2026-10-02T11:30:00-03:00",
      "master_sku": "CAMISETA-M-AZUL",
      "master_name": "Camiseta Básica Azul M",
      "stock_available": 15,
      "platform_sku_id": "0",
      "listing_sku": null,
      "store_name": "Luna Style TikTok"
    }
  ],
  "meta": {
    "current_page": 1,
    "per_page": 50,
    "total": 2,
    "last_page": 1
  }
}

Erros deste endpoint

HTTPCódigoQuando aconteceO que fazer
422INVALID_PARAMETERParâmetro de consulta com tipo errado, fora do limite ou em combinação proibida (a mensagem diz qual).Corrija o parâmetro citado. Os limites de cada endpoint estão na tabela de parâmetros.

Mais os de toda chamada — 401 (chave), 403 (escopo ou empresa suspensa), 429 (limite) e 500: tabela de erros.

Especificação OpenAPI

GET /api/v1/openapi.json público

A especificação completa no formato OpenAPI 3.0.3, sem autenticação: schemas com as chaves que cada endpoint devolve, os exemplos desta página, o escopo de cada operação (x-required-scope) e os erros. Importe a URL no Postman (File → Import → URL) ou no Insomnia.

cURL
curl https://lojexa.com/api/v1/openapi.json

Pedidos (somente leitura)

Os pedidos que chegam ao painel de pedidos da LOJEXA, para um programa que só precisa ler. Escopo read:orders; nada é alterado. O passo a passo está em Sincronizar pedidos.

Listar pedidos (sincronização por cursor)

GET /api/v1/orders read:orders

Pedidos dos canais do painel de pedidos (Shopee, Mercado Livre, TikTok, SHEIN, Magalu, Temu, Nuvemshop e os pedidos próprios criados na LOJEXA — no painel ("channel": "manual"), no PDV (pdv), no app (mobile), no app desktop (desktop), nas lojas próprias (siteb2c, lojab2b) e pelo antigo POST /orders (api); os pedidos da Amazon ficam fora; a venda registrada por POST /vendas não aparece aqui), somente leitura: status do canal e do fluxo LOJEXA, prazos de envio, rastreio, valores, taxas do repasse e NF-e. Nada é alterado na LOJEXA.

  • Ordem: sempre updated_at crescente e, no empate, id crescente.
  • Horizonte: só entram pedidos com updated_at até agora menos 2 minutos (meta.sync_horizon). Uma mudança do pedido aparece na sincronização em até cerca de 2 minutos — em troca, nenhum pedido se perde entre as páginas. Exceção: o vínculo do item ao SKU do estoque (items[].master_sku) feito depois não traz o pedido de volta; o estado atual está sempre em GET /orders/{id}.
  • Paginação: por cursor. Os parâmetros page e per_page são recusados com 422 INVALID_PARAMETER.
  • O cursor sempre anda: sem mais páginas (has_more = false), next_cursor aponta para o horizonte, mesmo com a página vazia. Guarde-o sempre e repita os mesmos filtros.
  • Com filtro (status, channel, datas...), cada chamada examina no máximo 5.000 pedidos alterados. Se o filtro casa pouco, a página pode vir com menos de limit pedidos, até vazia, e has_more = true: continue chamando com o cursor.

Parâmetros (todos opcionais)

NomeOndeTipoObrig.PadrãoLimitesExemplo
limitqueryinteiroNão501 a 100100
Pedidos por página.
cursorquerytextoNão—até 200 caractereseyJ1IjoiMjAyNi0xMC0yMyAxNDo1ODowMCIsImkiOjkyMjMzNzIwMzY4NTQ3NzU4MDd9
Opaco: copie meta.next_cursor e repita os mesmos filtros. Não pode vir junto com updated_since.
updated_sincequerytextoNão——2026-10-23T00:00:00-03:00
ISO 8601, inclusivo. Só na primeira chamada (codifique o "+" do fuso como %2B).
statusquerytextoNão——READY_TO_SHIP,SHIPPED
Status do canal, separados por vírgula (até 20).
lojexa_statusquerytextoNão——paid,packed
Status do fluxo LOJEXA, separados por vírgula (até 20).
channelquerytextoNão——shopee
shopee, mercadolivre, tiktok, shein, magalu, temu, nuvemshop, manual, api... Aceita os apelidos ml e tiktok_shop.
store_idqueryinteiroNão—≥ 13
ID da loja na LOJEXA (store.id). Exige channel.
created_fromquerytextoNão——2026-10-01
Criados a partir de (data ou data e hora ISO 8601).
created_toquerytextoNão——2026-10-23
Criados até (inclusivo; só data = o dia inteiro).
paid_fromquerytextoNão——2026-10-01
Pagos a partir de (data ou data e hora ISO 8601).
paid_toquerytextoNão——2026-10-23
Pagos até (inclusivo; só data = o dia inteiro).
cURL
curl -sS --max-time 30 \
     -H "Authorization: Bearer $LOJEXA_API_KEY" \
     "https://lojexa.com/api/v1/orders?updated_since=2026-10-23T00:00:00-03:00&limit=50"
JSON — resposta 200 (o pedido Shopee de hoje: pago, com a NF-e e o repasse)
{
  "success": true,
  "data": [
    {
      "id": 198734,
      "channel": "shopee",
      "store": {
        "id": 3,
        "name": "Luna Style Oficial"
      },
      "channel_order_id": "251023K7PQ2M1X",
      "status": {
        "channel": "READY_TO_SHIP",
        "channel_label": "Pronto para envio",
        "lojexa": "paid",
        "lojexa_label": "Pago"
      },
      "cancel_reason": null,
      "created_at": "2026-10-23T09:12:44-03:00",
      "paid_at": "2026-10-23T09:13:02-03:00",
      "updated_at": "2026-10-23T10:40:05-03:00",
      "amounts": {
        "currency": "BRL",
        "total": 49.9,
        "items_subtotal": 49.9,
        "shipping_fee": null,
        "discount": null
      },
      "fees": {
        "source": "shopee_repasse",
        "commission": 6.99,
        "transaction_fee": 0.99,
        "shipping_fee": 0.0,
        "other_deductions": 0.0,
        "order_income": 41.92,
        "settled_at": "2026-10-30T00:00:00-03:00"
      },
      "items": [
        {
          "id": 412233,
          "sku": "CAMISETA-M-AZUL",
          "master_sku": "CAMISETA-M-AZUL",
          "name": "Camiseta Básica Algodão Luna",
          "variation": "Azul,M",
          "quantity": 1,
          "unit_price": 49.9,
          "original_price": 59.9,
          "total": 49.9,
          "channel_item_id": "23847719012",
          "channel_variation_id": "198273645",
          "is_gift": false
        }
      ],
      "shipping": {
        "ship_by": "2026-10-25T23:59:59-03:00",
        "shipped_at": null,
        "expected_delivery_at": null,
        "carrier": "Shopee Xpress",
        "method": null,
        "tracking_code": "BR2645512345678",
        "status": null,
        "fulfillment": null,
        "label_status": "printed"
      },
      "invoice": {
        "status": "issued",
        "number": "1532",
        "series": "1",
        "key": "26261012345678000190550010000015321000015320",
        "issued_at": "2026-10-23T10:39:58-03:00",
        "source": "lojexa"
      },
      "buyer": {
        "username": "ma••••••",
        "name": "M••••• S••••",
        "city": "Recife",
        "state": "PE",
        "zip": "50••••••"
      }
    }
  ],
  "meta": {
    "limit": 50,
    "count": 1,
    "has_more": false,
    "next_cursor": "eyJ1IjoiMjAyNi0xMC0yMyAxNDo1ODowMCIsImkiOjkyMjMzNzIwMzY4NTQ3NzU4MDd9",
    "sync_horizon": "2026-10-23T14:58:00-03:00"
  }
}

Erros deste endpoint

HTTPCódigoQuando aconteceO que fazer
422INVALID_PARAMETERParâmetro de consulta com tipo errado, fora do limite ou em combinação proibida (a mensagem diz qual).Corrija o parâmetro citado. Os limites de cada endpoint estão na tabela de parâmetros.
422INVALID_CURSORO cursor foi alterado, cortado ou veio de outro endpoint.Repasse meta.next_cursor exatamente como veio. Para recomeçar, use updated_since.

Mais os de toda chamada — 401 (chave), 403 (escopo ou empresa suspensa), 429 (limite) e 500: tabela de erros.

Regras dos campos

CampoRegra
datasISO 8601 com o fuso -03:00; null quando o pedido não tem a data
created_atData do pedido no canal quando o canal informa (Shopee: create_time); nos pedidos próprios, a criação na LOJEXA. É o campo dos filtros created_from/created_to
channel_order_idNúmero do pedido no canal (external_order_id; se faltar, order_sn)
store.idID da loja na LOJEXA — é o valor do filtro store_id
status.channel / status.lojexaStatus do canal (vocabulário da Shopee: READY_TO_SHIP, SHIPPED...) e status do fluxo LOJEXA (paid, packed, shipped, cancelled...; pode ser null; veja o vocabulário abaixo)
amounts.totalTotal informado pelo canal; items_subtotal = soma de quantidade × preço dos itens
amounts.shipping_fee / amounts.discountValor maior que zero sai como veio; zero só sai como 0 nos canais que comprovadamente informam o campo; nos demais, null (não informado). Na Shopee saem sempre null
feesTaxas do repasse da Shopee (soma dos repasses do mesmo pedido). Chegam quando o repasse é sincronizado em Financeiro > Repasses, e o pedido volta na sincronização com elas. Sem repasse sincronizado, ou em outro canal, todos os campos são null
items[].master_skuSKU do estoque LOJEXA; null quando o item não está vinculado. original_price zero vira null
shippingcarrier = transportadora (ou provedor logistico); tracking_code = código de rastreio
invoiceA última NF-e LOJEXA do pedido (source "lojexa"); sem ela, a nota externa espelhada (source "externa"); sem nenhuma, todos os campos null. Nunca traz caminho de XML/DANFE nem mensagem de erro
buyerSempre mascarado; cidade e UF em claro. Telefone, e-mail, endereço e CPF/CNPJ nunca saem — não existe escopo que os revele
O passo a passo da sincronização (primeira carga, laço com cursor, upsert por id) está em Sincronizar pedidos.

Detalhe do pedido

GET /api/v1/orders/{id} read:orders

O mesmo objeto da listagem, no estado atual (sem o atraso de 2 minutos), mais stock_issue: {"title", "message"} quando o pedido está travado por falta de estoque; senão, null. O {id} é o campo id da listagem.

cURL
curl -sS --max-time 30 \
     -H "Authorization: Bearer $LOJEXA_API_KEY" \
     "https://lojexa.com/api/v1/orders/198734"
JSON — resposta 200
{
  "success": true,
  "data": {
    "id": 198734,
    "channel": "shopee",
    "store": {
      "id": 3,
      "name": "Luna Style Oficial"
    },
    "channel_order_id": "251023K7PQ2M1X",
    "status": {
      "channel": "READY_TO_SHIP",
      "channel_label": "Pronto para envio",
      "lojexa": "paid",
      "lojexa_label": "Pago"
    },
    "cancel_reason": null,
    "created_at": "2026-10-23T09:12:44-03:00",
    "paid_at": "2026-10-23T09:13:02-03:00",
    "updated_at": "2026-10-23T10:40:05-03:00",
    "amounts": {
      "currency": "BRL",
      "total": 49.9,
      "items_subtotal": 49.9,
      "shipping_fee": null,
      "discount": null
    },
    "fees": {
      "source": "shopee_repasse",
      "commission": 6.99,
      "transaction_fee": 0.99,
      "shipping_fee": 0.0,
      "other_deductions": 0.0,
      "order_income": 41.92,
      "settled_at": "2026-10-30T00:00:00-03:00"
    },
    "items": [
      {
        "id": 412233,
        "sku": "CAMISETA-M-AZUL",
        "master_sku": "CAMISETA-M-AZUL",
        "name": "Camiseta Básica Algodão Luna",
        "variation": "Azul,M",
        "quantity": 1,
        "unit_price": 49.9,
        "original_price": 59.9,
        "total": 49.9,
        "channel_item_id": "23847719012",
        "channel_variation_id": "198273645",
        "is_gift": false
      }
    ],
    "shipping": {
      "ship_by": "2026-10-25T23:59:59-03:00",
      "shipped_at": null,
      "expected_delivery_at": null,
      "carrier": "Shopee Xpress",
      "method": null,
      "tracking_code": "BR2645512345678",
      "status": null,
      "fulfillment": null,
      "label_status": "printed"
    },
    "invoice": {
      "status": "issued",
      "number": "1532",
      "series": "1",
      "key": "26261012345678000190550010000015321000015320",
      "issued_at": "2026-10-23T10:39:58-03:00",
      "source": "lojexa"
    },
    "buyer": {
      "username": "ma••••••",
      "name": "M••••• S••••",
      "city": "Recife",
      "state": "PE",
      "zip": "50••••••"
    },
    "stock_issue": null
  }
}
JSON — 404 (id inexistente ou de outra empresa)
{
  "success": false,
  "error": {
    "code": "ORDER_NOT_FOUND",
    "message": "Pedido não encontrado.",
    "request_id": "8f14e45fceea167a5a36dedd4bea2543"
  }
}

Erros deste endpoint

HTTPCódigoQuando aconteceO que fazer
404ORDER_NOT_FOUNDPedido inexistente ou de outra empresa (a resposta é a mesma de propósito).Use o id que veio em GET /orders.

Mais os de toda chamada — 401 (chave), 403 (escopo ou empresa suspensa), 429 (limite) e 500: tabela de erros.

Reservas de estoque do pedido

GET /api/v1/orders/{id}/stock-reservations read:orders

As reservas do estoque da LOJEXA feitas para os itens do pedido. Pedido inexistente ou de outra empresa: 404 ORDER_NOT_FOUND.

cURL
curl -sS --max-time 30 \
     -H "Authorization: Bearer $LOJEXA_API_KEY" \
     "https://lojexa.com/api/v1/orders/198734/stock-reservations"
JSON — resposta 200
{
  "success": true,
  "data": [
    {
      "id": 5521,
      "order_item_id": 412233,
      "sku": "CAMISETA-M-AZUL",
      "master_sku": "CAMISETA-M-AZUL",
      "warehouse": {
        "id": 1,
        "name": "Pernambuco"
      },
      "quantity": 1,
      "status": "active"
    }
  ]
}

Erros deste endpoint

HTTPCódigoQuando aconteceO que fazer
404ORDER_NOT_FOUNDPedido inexistente ou de outra empresa (a resposta é a mesma de propósito).Use o id que veio em GET /orders.

Mais os de toda chamada — 401 (chave), 403 (escopo ou empresa suspensa), 429 (limite) e 500: tabela de erros.

Vocabulário de status

status.channel é o status no marketplace (vocabulário da Shopee, usado para todos os canais) e status.lojexa o do fluxo da LOJEXA; channel_label e lojexa_label trazem o nome em português.

status.channelO que significa
UNPAID
Aguardando pagamento
O comprador ainda não pagou. Não separe.
READY_TO_SHIP
Pronto para envio
Pago: pronto para separar, emitir NF-e e enviar.
PROCESSED
Em processamento
Envio já programado no canal (etiqueta gerada); falta postar ou a coleta passar.
RETRY_SHIP
Reenvio pendente
O canal pediu um novo envio.
READY_TO_PICKUP
Aguardando coleta
Aguardando a coleta da transportadora.
SHIPPED
Enviado
Enviado ao comprador.
TO_CONFIRM_RECEIVE
Aguardando confirmação
Entregue; o canal espera o comprador confirmar.
DELIVERED
Entregue
Entregue.
COMPLETED
Concluído
Concluído no canal (fim do pedido).
IN_CANCEL
Cancelamento solicitado
O comprador pediu o cancelamento: não envie até o canal decidir.
CANCELLED
Cancelado
Cancelado.
INVOICE_PENDING
NF pendente
O canal espera a NF-e para liberar o envio.
TO_RETURN
Em devolução
Devolução em andamento.
JUDGE_RETURN_REFUND
Avaliação de reembolso
O canal está avaliando um pedido de devolução ou reembolso.
RETURNED
Devolvido
Devolvido.
REFUNDED
Reembolsado
Reembolsado ao comprador.
VOIDED
Anulado
Anulado pelo canal.
status.lojexaO que significa
awaiting_payment
Aguardando pagamento
Aguardando o pagamento.
pending_reservation
Aguardando reserva
Pago, esperando a reserva do estoque.
reserved
Estoque reservado
Estoque reservado para o pedido.
paid
Pago
Pago e pronto para o fluxo (separar, NF-e, etiqueta).
fiscal_pending
Fiscal pendente
NF-e pendente.
fiscal_authorized
Fiscal autorizado
NF-e autorizada.
picking
Em separacao
Em separação.
packed
Embalado
Embalado.
shipped
Enviado
Enviado.
delivered
Entregue
Entregue.
cancelled
Cancelado
Cancelado.
returned
Devolvido
Devolvido.
stock_conflict
Conflito de estoque
Travado por falta de estoque (o motivo vem em stock_issue de GET /orders/{id}).
product_mapping_required
Mapeamento necessario
Item sem vínculo com um SKU do estoque.

Guia: manter o estoque sincronizado

Para o seu sistema mostrar o mesmo disponível da LOJEXA sem reler o catálogo inteiro a cada vez. Escopo read:products; tudo do servidor.

  1. Chave: crie uma só com read:products e guarde no ambiente do servidor (LOJEXA_API_KEY).
  2. Teste: GET /ping (empresa e escopos) e GET /uso (limite por minuto).
  3. Pegue os cursores ANTES da carga: GET /estoque/mudancas?updated_since=<agora> e GET /produtos?updated_since=<agora>&fields=stock. Vêm vazios, com next_cursor 2 minutos atrás: assim, o que mudar durante a carga entra no primeiro laço.
  4. Carga inicial: GET /produtos?fields=stock&status=all&per_page=100, de page=1 até meta.last_page. Grave, por sku_master_id, o sku_code, o stock.available e o status — o código do SKU pode ser trocado na ficha; o id não muda.
  5. Laço de estoque, a cada 1 a 5 minutos: GET /estoque/mudancas?cursor=…&limit=500. Grave cada SKU (upsert pelo sku_master_id), na ordem em que chega, e guarde o novo meta.next_cursor — ele sempre vem, mesmo com a página vazia. Com has_more: true, chame de novo na hora.
  6. Laço do catálogo: o mesmo com GET /produtos?cursor=…&fields=stock: SKU novo, alterado e inativado ("status": "inactive", available 0). A troca de código vem como o mesmo sku_master_id com o sku_code novo. Não descarte item pelo updated_at: ele não decide qual versão é a mais nova.
  7. Reconciliação diária: refaça os passos 3 e 4 uma vez por dia e apague (ou zere) no seu sistema o SKU que não veio na carga — é assim que some o código antigo de um SKU renomeado. Ela cobre o que o razão não registra: contador de SKU sem saldo por armazém, estoque inicial trazido do anúncio ao vincular, receita de kit, estoque de segurança e a troca do armazém padrão (ou ativação e desativação de armazém). Trocou o armazém padrão? Refaça a carga na hora.
  8. Erros: 429 → espere o Retry-After; 5xx, timeout ou queda de rede → repita a MESMA chamada (o mesmo cursor) com backoff; 4xx → pare e corrija (mande o X-Request-Id ao suporte).
  • Atraso de até ~2 minutos (SKU com saldo por armazém): é o horizonte que garante que nada se perde entre as páginas. SKU de cadastro antigo chega pelo feed do catálogo, com até ~3 h de atraso em algumas gravações do painel.
  • Qual número usar: stock.available, do armazém padrão. Se a sua loja vende de outro armazém, passe warehouse nas duas chamadas (veja armazéns).
  • Para conciliar o motivo de uma mudança (venda Shopee, ajuste, devolução): GET /estoque/movimentos?sku=….
  • Custo: 1.000 SKUs = 10 chamadas na carga; depois, 2 chamadas por rodada (uma por laço) enquanto nada muda.
bash
# A chave fica no ambiente do servidor, nunca no código nem no navegador.
export LOJEXA_API_KEY='lj_live_...'
BASE=https://lojexa.com/api/v1
AUTH="Authorization: Bearer $LOJEXA_API_KEY"

# 1. Testar a chave (empresa e escopos) e ver o limite por minuto
curl -sS --max-time 30 -H "$AUTH" "$BASE/ping"
curl -sS --max-time 30 -H "$AUTH" "$BASE/uso"

# 2. ANTES da carga, pegue os dois cursores: vêm vazios, com next_cursor 2 min atrás
AGORA=$(date -u +%Y-%m-%dT%H:%M:%SZ)
curl -sS --max-time 30 -H "$AUTH" "$BASE/estoque/mudancas?updated_since=$AGORA"
curl -sS --max-time 30 -H "$AUTH" "$BASE/produtos?updated_since=$AGORA&fields=stock"
#    guarde os dois meta.next_cursor

# 3. Carga inicial: página por página, de 1 até meta.last_page
curl -sS --max-time 30 -H "$AUTH" "$BASE/produtos?fields=stock&status=all&per_page=100&page=1"
#    grave cada SKU pelo sku_master_id (o sku_code pode ser trocado na ficha) e,
#    no fim, apague (ou zere) o que não veio: some o código antigo de um SKU renomeado.
#    Refaça este passo uma vez por dia (reconciliação).

# 4. A cada 1 a 5 minutos: o que mudou no estoque desde o cursor guardado
curl -sS --max-time 30 -H "$AUTH" "$BASE/estoque/mudancas?cursor=CURSOR_DO_ESTOQUE&limit=500"
#    grave cada SKU (upsert pelo sku_master_id) e guarde o novo meta.next_cursor;
#    com has_more=true, chame de novo já com ele

# 5. E o catálogo: SKUs novos, alterados e inativados
curl -sS --max-time 30 -H "$AUTH" "$BASE/produtos?cursor=CURSOR_DO_CATALOGO&fields=stock&limit=100"
Python 3 — requests
"""Manter o estoque do seu sistema igual ao da LOJEXA (escopo read:products).

Roda no SERVIDOR. A chave vem do ambiente: export LOJEXA_API_KEY=lj_live_...
"""
import json, os, pathlib, random, time
from datetime import datetime, timezone

import requests

BASE = 'https://lojexa.com/api/v1'
SESSAO = requests.Session()
SESSAO.headers.update({
    'Authorization': f"Bearer {os.environ['LOJEXA_API_KEY']}",
    'Accept': 'application/json',
})
ESTADO = pathlib.Path('lojexa_estoque.json')  # os cursores, de uma execução para a outra


def chamar(caminho, params):
    """GET com timeout de 30 s. 429, 5xx e queda de rede repetem a MESMA chamada."""
    espera = 2
    while True:
        try:
            r = SESSAO.get(BASE + caminho, params=params, timeout=30, allow_redirects=False)
        except requests.RequestException:
            r = None
        if r is not None and r.status_code == 200:
            return r.json()
        if r is not None and r.status_code == 429:
            time.sleep(int(r.headers.get('Retry-After', '5')) + random.random())
            continue
        if r is not None and r.status_code < 500:
            # 3xx/4xx: repetir não resolve; corrija a chamada ou a chave
            raise RuntimeError(f"{r.status_code} {r.text[:300]} (X-Request-Id {r.headers.get('X-Request-Id')})")
        time.sleep(espera + random.random())  # 5xx ou rede: backoff exponencial com jitter
        espera = min(espera * 2, 60)


def gravar(produto):
    # upsert pelo sku_master_id no seu sistema (o sku_code pode ser trocado na ficha:
    # guarde-o como atributo); status 'inactive' = o SKU saiu (available 0)
    print(produto['sku_code'], produto['status'], produto['stock']['available'])


def remover_os_que_nao_vieram(ids):
    # No seu sistema: apague (ou zere) todo SKU cujo sku_master_id não está em ids.
    # É assim que some o código antigo de um SKU renomeado (nenhum feed avisa).
    pass


def carga_inicial():
    # Os cursores vêm ANTES da carga: o que mudar durante ela entra no primeiro laço.
    agora = datetime.now(timezone.utc).strftime('%Y-%m-%dT%H:%M:%SZ')
    cursores = {
        'estoque': chamar('/estoque/mudancas', {'updated_since': agora})['meta']['next_cursor'],
        'catalogo': chamar('/produtos', {'updated_since': agora, 'fields': 'stock'})['meta']['next_cursor'],
    }
    pagina, ids = 1, set()
    while True:
        corpo = chamar('/produtos', {'fields': 'stock', 'status': 'all', 'per_page': 100, 'page': pagina})
        for produto in corpo['data']:
            gravar(produto)
            ids.add(produto['sku_master_id'])
        if pagina >= corpo['meta']['last_page']:
            break
        pagina += 1
    remover_os_que_nao_vieram(ids)
    ESTADO.write_text(json.dumps(cursores), encoding='utf-8')


def seguir(caminho, chave, params):
    cursores = json.loads(ESTADO.read_text(encoding='utf-8'))
    while True:
        corpo = chamar(caminho, {**params, 'cursor': cursores[chave]})
        for produto in corpo['data']:
            gravar(produto)
        cursores[chave] = corpo['meta']['next_cursor']  # sempre vem, mesmo com a página vazia
        ESTADO.write_text(json.dumps(cursores), encoding='utf-8')
        if not corpo['meta']['has_more']:
            return


if not ESTADO.exists():
    carga_inicial()
ultima_reconciliacao = time.time()
while True:
    seguir('/estoque/mudancas', 'estoque', {'limit': 500})
    seguir('/produtos', 'catalogo', {'fields': 'stock', 'limit': 100})
    if time.time() - ultima_reconciliacao > 24 * 3600:
        carga_inicial()  # reconciliação diária: cobre o que o razão não registra e remove o que não veio
        ultima_reconciliacao = time.time()
    time.sleep(120)  # de 1 a 5 minutos
Node 18+ — fetch nativo
// Manter o estoque do seu sistema igual ao da LOJEXA (Node 18+, no SERVIDOR).
// A chave vem do ambiente: LOJEXA_API_KEY=lj_live_... node estoque.mjs
import { readFile, writeFile } from 'node:fs/promises';

const BASE = 'https://lojexa.com/api/v1';
const ESTADO = 'lojexa_estoque.json'; // os cursores, de uma execução para a outra
const dormir = (ms) => new Promise((ok) => setTimeout(ok, ms));

// GET com timeout de 30 s. 429, 5xx e queda de rede repetem a MESMA chamada.
async function chamar(caminho, params) {
  const url = `${BASE}${caminho}?${new URLSearchParams(params)}`;
  let espera = 2000;
  for (;;) {
    let r = null;
    try {
      r = await fetch(url, {
        headers: { Authorization: `Bearer ${process.env.LOJEXA_API_KEY}`, Accept: 'application/json' },
        redirect: 'manual',
        signal: AbortSignal.timeout(30_000),
      });
    } catch { /* timeout ou rede */ }
    if (r && r.status === 200) return r.json();
    if (r && r.status === 429) {
      await dormir((Number(r.headers.get('retry-after') ?? 5) + Math.random()) * 1000);
      continue;
    }
    if (r && r.status < 500) {
      // 3xx/4xx: repetir não resolve; corrija a chamada ou a chave
      throw new Error(`${r.status} ${(await r.text()).slice(0, 300)} (X-Request-Id ${r.headers.get('x-request-id')})`);
    }
    await dormir(espera + Math.random() * 1000); // 5xx ou rede: backoff exponencial com jitter
    espera = Math.min(espera * 2, 60_000);
  }
}

async function gravar(produto) {
  // upsert pelo sku_master_id no seu banco (o sku_code pode ser trocado na ficha:
  // guarde-o como atributo); status 'inactive' = o SKU saiu (available 0)
  console.log(produto.sku_code, produto.status, produto.stock.available);
}

async function removerOsQueNaoVieram(ids) {
  // No seu banco: apague (ou zere) todo SKU cujo sku_master_id não está em ids.
  // É assim que some o código antigo de um SKU renomeado (nenhum feed avisa).
}

async function cargaInicial() {
  // Os cursores vêm ANTES da carga: o que mudar durante ela entra no primeiro laço.
  const agora = new Date().toISOString();
  const cursores = {
    estoque: (await chamar('/estoque/mudancas', { updated_since: agora })).meta.next_cursor,
    catalogo: (await chamar('/produtos', { updated_since: agora, fields: 'stock' })).meta.next_cursor,
  };
  const ids = new Set();
  for (let pagina = 1; ; pagina++) {
    const corpo = await chamar('/produtos', { fields: 'stock', status: 'all', per_page: 100, page: pagina });
    for (const produto of corpo.data) {
      await gravar(produto);
      ids.add(produto.sku_master_id);
    }
    if (pagina >= corpo.meta.last_page) break;
  }
  await removerOsQueNaoVieram(ids);
  await writeFile(ESTADO, JSON.stringify(cursores));
}

async function seguir(caminho, chave, params) {
  const cursores = JSON.parse(await readFile(ESTADO, 'utf8'));
  for (;;) {
    const corpo = await chamar(caminho, { ...params, cursor: cursores[chave] });
    for (const produto of corpo.data) await gravar(produto);
    cursores[chave] = corpo.meta.next_cursor; // sempre vem, mesmo com a página vazia
    await writeFile(ESTADO, JSON.stringify(cursores));
    if (!corpo.meta.has_more) return;
  }
}

await readFile(ESTADO).catch(() => cargaInicial());
let ultimaReconciliacao = Date.now();
for (;;) {
  await seguir('/estoque/mudancas', 'estoque', { limit: 500 });
  await seguir('/produtos', 'catalogo', { fields: 'stock', limit: 100 });
  if (Date.now() - ultimaReconciliacao > 24 * 3600 * 1000) {
    await cargaInicial(); // reconciliação diária: cobre o que o razão não registra e remove o que não veio
    ultimaReconciliacao = Date.now();
  }
  await dormir(120_000); // de 1 a 5 minutos
}
PHP 8 — cURL
<?php
// Manter o estoque do seu sistema igual ao da LOJEXA (PHP 8, no SERVIDOR).
// Rode a cada 1 a 5 minutos (cron). A chave vem do ambiente: LOJEXA_API_KEY=lj_live_...
const BASE = 'https://lojexa.com/api/v1';
const ESTADO = __DIR__ . '/lojexa_estoque.json'; // os cursores, de uma execução para a outra

/** GET com timeout de 30 s. 429, 5xx e queda de rede repetem a MESMA chamada. */
function chamar(string $caminho, array $params): array
{
    $espera = 2;
    while (true) {
        $ch = curl_init(BASE . $caminho . '?' . http_build_query($params));
        curl_setopt_array($ch, [
            CURLOPT_RETURNTRANSFER => true,
            CURLOPT_HEADER         => true,
            CURLOPT_TIMEOUT        => 30,
            CURLOPT_FOLLOWLOCATION => false,
            CURLOPT_HTTPHEADER     => ['Authorization: Bearer ' . getenv('LOJEXA_API_KEY'), 'Accept: application/json'],
        ]);
        $resposta = (string) curl_exec($ch);
        $status = (int) curl_getinfo($ch, CURLINFO_RESPONSE_CODE); // 0 = timeout ou rede
        $tamanho = (int) curl_getinfo($ch, CURLINFO_HEADER_SIZE);
        curl_close($ch);
        $cabecalhos = substr($resposta, 0, $tamanho);
        $corpo = substr($resposta, $tamanho);

        if ($status === 200) {
            return json_decode($corpo, true);
        }
        if ($status === 429) {
            preg_match('/^Retry-After:\s*(\d+)/mi', $cabecalhos, $m);
            sleep((int) ($m[1] ?? 5) + 1);
            continue;
        }
        if ($status >= 300 && $status < 500) {
            // 3xx/4xx: repetir não resolve; corrija a chamada ou a chave
            throw new RuntimeException("{$status} " . substr($corpo, 0, 300));
        }
        sleep($espera + random_int(0, 1)); // 5xx ou rede: backoff exponencial com jitter
        $espera = min($espera * 2, 60);
    }
}

function gravar(array $produto): void
{
    // upsert pelo sku_master_id no seu banco (o sku_code pode ser trocado na ficha:
    // guarde-o como atributo); status 'inactive' = o SKU saiu (available 0)
    echo $produto['sku_code'], ' ', $produto['status'], ' ', $produto['stock']['available'], PHP_EOL;
}

function removerOsQueNaoVieram(array $ids): void
{
    // No seu banco: apague (ou zere) todo SKU cujo sku_master_id não está em $ids.
    // É assim que some o código antigo de um SKU renomeado (nenhum feed avisa).
}

function cargaInicial(): void
{
    // Os cursores vêm ANTES da carga: o que mudar durante ela entra no primeiro laço.
    $agora = gmdate('Y-m-d\TH:i:s\Z');
    $cursores = [
        'estoque'  => chamar('/estoque/mudancas', ['updated_since' => $agora])['meta']['next_cursor'],
        'catalogo' => chamar('/produtos', ['updated_since' => $agora, 'fields' => 'stock'])['meta']['next_cursor'],
    ];
    $ids = [];
    for ($pagina = 1; ; $pagina++) {
        $corpo = chamar('/produtos', ['fields' => 'stock', 'status' => 'all', 'per_page' => 100, 'page' => $pagina]);
        array_map('gravar', $corpo['data']);
        array_push($ids, ...array_column($corpo['data'], 'sku_master_id'));
        if ($pagina >= $corpo['meta']['last_page']) {
            break;
        }
    }
    removerOsQueNaoVieram($ids);
    file_put_contents(ESTADO, json_encode($cursores));
}

function seguir(string $caminho, string $chave, array $params): void
{
    $cursores = json_decode((string) file_get_contents(ESTADO), true);
    do {
        $corpo = chamar($caminho, $params + ['cursor' => $cursores[$chave]]);
        array_map('gravar', $corpo['data']);
        $cursores[$chave] = $corpo['meta']['next_cursor']; // sempre vem, mesmo com a página vazia
        file_put_contents(ESTADO, json_encode($cursores));
    } while ($corpo['meta']['has_more']);
}

// Reconciliação diária: apague o arquivo de estado uma vez por dia (a carga refaz tudo
// e remove o que não veio).
if (!is_file(ESTADO)) {
    cargaInicial();
}
seguir('/estoque/mudancas', 'estoque', ['limit' => 500]);
seguir('/produtos', 'catalogo', ['fields' => 'stock', 'limit' => 100]);

Sincronizar pedidos

Para um programa que recebe os pedidos da LOJEXA sem alterar nada (escopo read:orders, somente leitura):

  1. Primeira carga: chame GET /orders?updated_since=... com a data a partir da qual quer os pedidos.
  2. Guarde meta.next_cursor de cada resposta (no banco ou num arquivo do seu programa).
  3. Enquanto has_more for true, chame de novo com cursor=<o cursor guardado> e os mesmos filtros.
  4. Depois, a cada 1 a 5 minutos, chame de novo com o último cursor guardado. Resposta vazia é normal: guarde o next_cursor mesmo assim (ele avança até o horizonte).
  5. Grave por id (upsert): o mesmo pedido volta quando o pedido muda — status, prazo de envio, rastreio, NF-e e as taxas quando o repasse é sincronizado. O updated_at também muda quando o canal ressincroniza o pedido sem mudança real — compare os campos que importam para você. O vínculo do item ao SKU do estoque feito depois não traz o pedido de volta: releia em GET /orders/{id} se precisar.
  • Atraso de até 2 minutos: a listagem só mostra o que foi gravado até meta.sync_horizon (agora menos 2 min). É isso que garante que nenhum pedido se perde entre as páginas. Para o estado atual de um pedido específico, use GET /orders/{id}.
  • Não há webhook de pedido: os webhooks avisam só as vendas registradas pela própria API. Para pedidos, use este laço com cursor.
  • Chave só em servidor ou programa local: nunca em página de navegador ou app distribuído. Os dados do comprador vêm mascarados, mas o volume de vendas é do seu negócio.
  • Rate limit: cada chamada traz até 100 pedidos (limit=100); o laço segue enquanto has_more for true, e o padrão de 60 chamadas por minuto dá folga para isso.
  • Erro 5xx ou queda de rede: espere alguns segundos e repita a chamada com o mesmo cursor — nada se perde.

Python — laço de sincronização

Python
import json, os, pathlib, time
import requests

API_KEY = os.environ['LOJEXA_API_KEY']   # do ambiente do servidor; chave so com o escopo read:orders
BASE_URL = 'https://lojexa.com/api/v1'
HEADERS = {'Authorization': f'Bearer {API_KEY}', 'Accept': 'application/json'}
ESTADO = pathlib.Path('lojexa_cursor.json')


def gravar_pedido(pedido):
    # upsert pelo pedido['id'] no seu banco
    print(pedido['id'], pedido['channel'], pedido['status']['channel'], pedido['shipping']['ship_by'])


def sincronizar():
    cursor = json.loads(ESTADO.read_text(encoding='utf-8'))['cursor'] if ESTADO.exists() else None
    while True:
        params = {'limit': 100}
        if cursor:
            params['cursor'] = cursor
        else:
            params['updated_since'] = '2026-10-01T00:00:00-03:00'  # primeira carga
        try:
            r = requests.get(f'{BASE_URL}/orders', headers=HEADERS, params=params, timeout=30, allow_redirects=False)
        except requests.RequestException:
            time.sleep(30)  # queda de rede: tenta de novo com o mesmo cursor
            continue
        if r.status_code == 429:
            time.sleep(int(r.headers.get('Retry-After', '5')) + 1)  # o que o servidor pediu
            continue
        if r.status_code >= 500:
            time.sleep(30)  # erro do servidor: tenta de novo com o mesmo cursor
            continue
        if r.status_code != 200:
            raise RuntimeError(f'{r.status_code} {r.text[:300]}')  # 3xx/4xx: repetir nao resolve (chave ou parametros)
        corpo = r.json()
        for pedido in corpo['data']:
            if pedido['channel'] == 'apivenda':
                continue  # venda feita por POST /vendas (se um dia aparecer aqui): ja esta no seu sistema
            gravar_pedido(pedido)
        if corpo['meta']['next_cursor']:
            cursor = corpo['meta']['next_cursor']
            ESTADO.write_text(json.dumps({'cursor': cursor}), encoding='utf-8')
        if not corpo['meta']['has_more']:
            return


while True:
    sincronizar()
    time.sleep(120)  # de 1 a 5 minutos

Endpoints: vendas, ajuste e mapeamentos

Não há ambiente de teste: tudo aqui mexe 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 (a venda de uma peça atualiza os anúncios dos kits que a usam) — veja como montar o SKU de teste. Leia também o que a API não faz hoje.

Registrar venda

POST /api/v1/vendas write:sales

Registra uma venda feita fora da LOJEXA (no seu site, por exemplo) e baixa o estoque, tudo ou nada. A venda confere e baixa no mesmo armazém que a leitura mostra: sem warehouse, o armazém padrão da empresa — o stock.available de GET /produtos; com warehouse, aquele. O número que você lê é o que a venda aceita. Depois, o envio do novo saldo às lojas vinculadas entra na fila (envio aos canais). Hoje a venda não vira pedido no painel (não há separação, etiqueta nem NF-e para ela).

NomeOndeTipoObrig.PadrãoLimitesExemplo
referencecorpotextoSim—até 100 caracteres; sem /PEDIDO-123
Id do pedido no seu sistema; a chave de idempotência. Diferencia maiúsculas (A1b2 e a1B2 são duas vendas). Sem "/": a venda precisa caber no caminho de /vendas/{reference}.
warehousecorpoid ou codeNão——SP
De onde a venda sai (GET /armazens). Sem ele, o armazém padrão da empresa — o mesmo de stock.available em GET /produtos. Outro valor: 422 WAREHOUSE_NOT_FOUND.
itemscorpolistaSim—1 a 50 itens—
O mesmo SKU em mais de uma linha (em qualquer caixa ou acento) é somado: a conferência é do total e a baixa é uma só.
items[].skucorpotextoSim—até 100 caracteresCAMISETA-M-AZUL
O sku_code da LOJEXA (maiúsculas, minúsculas e acento não importam). Kit: o SKU do kit (a venda confere e baixa as peças no armazém dela; o estorno devolve as peças pela receita do momento da venda).
items[].quantitycorpointeiroSim—1 a 1.000.0001
Inteiro: 3, 3.0 e "3" valem; 2.5 e "3abc" dão 422 INVALID_ITEM_QTY. No kit, quantos kits.
items[].unit_pricecorponúmeroNão—≥ 049.9
Opcional; fica guardado na venda, não muda o estoque
items[].warehousecorpoid ou codeNão——SP
O armazém DESTE item (vale mais que o da venda). Sem ele, o da venda.
channelcorpotextoNãoapiaté 50 caracteressite
Rótulo livre da origem da venda (ex.: site, loja-fisica). Até 50 caracteres; acima, 422 INVALID_FIELD.
customer_namecorpotextoNão—até 100 caracteresJoão Silva
Fica guardado na venda (não sai no webhook). Acima do limite: 422 INVALID_FIELD.
customer_emailcorpotextoNão—até 150 caracteresjoao@email.com
Fica guardado na venda. Precisa ter "@"; fora disso, 422 INVALID_FIELD.
  • Estoque: a conta é a de stock.available no armazém da venda. Kit: quantos kits as peças montam ali; o kit e a própria peça na mesma venda disputam a mesma prateleira (a conferência é do total da peça). Falta: 422 INSUFFICIENT_STOCK e nada é baixado; error.details.items traz, por SKU, warehouse, requested, required (o total do SKU na venda), available e, no kit, components. Use o available para corrigir o seu site; não repita igual.
  • Idempotência: o mesmo pedido com a mesma reference (o SKU, a quantidade e o warehouse como enviados; preço e cliente não contam) devolve 200 com "already_processed": true e o estado da venda — nada é baixado de novo, e não é erro. A mesma reference com outro pedido: 409 REFERENCE_CONFLICT (não repita; se é outra venda, use outra reference). Uma venda cancelada continua com a reference dela: para vender de novo, use outra (ex.: PEDIDO-123-2).
  • Timeout e o que repetir: use 30 s. Deu timeout, queda de rede, 500 TRANSACTION_FAILED ou 409 STOCK_RACE_CONDITION (outra operação mexeu no mesmo estoque no mesmo instante; nada foi gravado)? Repita a mesma chamada: se a venda tiver entrado, volta already_processed. Ou consulte GET /vendas/{reference}.
  • Resposta: items é o estado (uma linha por SKU e armazém, com reversed_quantity). items_processed (só no 201) traz available_after (o disponível no armazém da venda, o mesmo de GET /produtos), on_hand_after (o físico; no kit, null), stock_after (igual a available_after) e channels: por loja vinculada, stock_push_enabled e push — queued (o envio entrou na fila), disabled (a loja está com o envio de estoque desligado) ou not_queued (não entrou na fila; a sincronização programada corrige em até ~1h30). No ajuste há um quarto valor, unchanged: nada mudou, nada é enviado. channels lista só as lojas do próprio SKU: a venda de uma peça também atualiza os anúncios dos kits que a usam (e a do kit, os das peças), e esses não aparecem aqui.
cURL
curl -sS --max-time 30 -X POST \
     -H "Authorization: Bearer $LOJEXA_API_KEY" \
     -H 'Content-Type: application/json' \
     --data-binary @- "https://lojexa.com/api/v1/vendas" <<'JSON'
{
  "reference": "PEDIDO-123",
  "channel": "site",
  "customer_name": "Joao Silva",
  "customer_email": "joao@email.com",
  "items": [
    {
      "sku": "CAMISETA-M-AZUL",
      "quantity": 2,
      "unit_price": 49.9
    }
  ]
}
JSON
JSON — 201 venda registrada
{
  "success": true,
  "already_processed": false,
  "data": {
    "sale_id": 5,
    "reference": "PEDIDO-123",
    "status": "confirmed",
    "channel": "site",
    "warehouse": {
      "id": 1,
      "code": "PE",
      "name": "Pernambuco"
    },
    "created_at": "2026-10-24T10:15:00-03:00",
    "updated_at": "2026-10-24T10:15:00-03:00",
    "reversed_at": null,
    "items": [
      {
        "sku": "CAMISETA-M-AZUL",
        "sku_master_id": 10,
        "warehouse": {
          "id": 1,
          "code": "PE",
          "name": "Pernambuco"
        },
        "quantity": 2,
        "reversed_quantity": 0,
        "is_kit": false,
        "components": []
      }
    ],
    "reversals": [],
    "items_processed": [
      {
        "sku": "CAMISETA-M-AZUL",
        "sku_master_id": 10,
        "quantity": 2,
        "warehouse": {
          "id": 1,
          "code": "PE",
          "name": "Pernambuco"
        },
        "available_after": 13,
        "on_hand_after": 16,
        "stock_after": 13,
        "channels": [
          {
            "channel": "shopee",
            "store_id": 3,
            "store_name": "Luna Style Oficial",
            "stock_push_enabled": true,
            "push": "queued"
          },
          {
            "channel": "tiktok",
            "store_id": 7,
            "store_name": "Luna Style TikTok",
            "stock_push_enabled": false,
            "push": "disabled"
          }
        ]
      }
    ]
  }
}
JSON — 200 o mesmo pedido de novo
{
  "success": true,
  "already_processed": true,
  "data": {
    "sale_id": 5,
    "reference": "PEDIDO-123",
    "status": "confirmed",
    "channel": "site",
    "warehouse": {
      "id": 1,
      "code": "PE",
      "name": "Pernambuco"
    },
    "created_at": "2026-10-24T10:15:00-03:00",
    "updated_at": "2026-10-24T10:15:00-03:00",
    "reversed_at": null,
    "items": [
      {
        "sku": "CAMISETA-M-AZUL",
        "sku_master_id": 10,
        "warehouse": {
          "id": 1,
          "code": "PE",
          "name": "Pernambuco"
        },
        "quantity": 2,
        "reversed_quantity": 0,
        "is_kit": false,
        "components": []
      }
    ],
    "reversals": []
  }
}
JSON — 409 a mesma reference com outro pedido
{
  "success": false,
  "error": {
    "code": "REFERENCE_CONFLICT",
    "message": "Já existe uma venda com a reference \"PEDIDO-123\" e outros itens (SKU, quantidade ou warehouse). Nada foi baixado. Se é outra venda, use outra reference; para ver a que existe, GET /vendas/{reference}.",
    "details": {
      "sale_id": 5
    },
    "request_id": "8f14e45fceea167a5a36dedd4bea2543"
  }
}
JSON — 422 falta de estoque (kit)
{
  "success": false,
  "error": {
    "code": "INSUFFICIENT_STOCK",
    "message": "Estoque insuficiente para o SKU \"KIT-CAMISETA-2\" no armazém PE: disponível 6, pedido 9. Nada foi baixado.",
    "details": {
      "items": [
        {
          "sku": "KIT-CAMISETA-2",
          "warehouse": {
            "id": 1,
            "code": "PE",
            "name": "Pernambuco"
          },
          "requested": 9,
          "required": 9,
          "available": 6,
          "components": [
            {
              "sku": "CAMISETA-M-AZUL",
              "quantity_per_kit": 2,
              "required": 18,
              "available": 13
            }
          ]
        }
      ]
    },
    "request_id": "8f14e45fceea167a5a36dedd4bea2543"
  }
}

Erros deste endpoint

HTTPCódigoQuando aconteceO que fazer
400INVALID_JSONO corpo do POST não é um objeto JSON válido (vírgula sobrando, aspas simples, texto solto, lista no lugar de objeto).Envie Content-Type: application/json e um objeto JSON, ex.: {"type": "in", "quantity": 1, "reason": "Compra"}.
422MISSING_REFERENCEVenda sem o campo "reference".Envie o id do pedido no seu sistema em "reference" (até 100 caracteres, sem "/").
422REFERENCE_TOO_LONG"reference" com mais de 100 caracteres.Encurte a referência para até 100 caracteres.
422INVALID_FIELDCampo do corpo com tipo errado ou maior que o limite (a mensagem diz qual). Na venda: channel > 50, customer_name > 100, customer_email > 150 ou sem "@", unit_price negativo, reference com "/"; no estorno: reason > 255, condition fora de sellable/damaged; no ajuste: expected_on_hand que não é inteiro >= 0, warehouse que não é id nem code; no mapeamento: platform_sku > 100, platform_product_id > 100, listing_sku > 200, platform_sku_id que não é id numérico (texto de dígitos, até 19), store_id que não é inteiro positivo, quantity_factor fora de 1 a 10.000.Corrija o campo citado. Os limites de cada campo estão na tabela do endpoint.
422MISSING_ITEMS"items" ausente, vazio ou que não é lista (na venda e no lote de ajustes; no estorno, "items" que não é lista).Envie ao menos um item {"sku": "...", "quantity": 1}. No estorno, omita "items" para estornar tudo.
422TOO_MANY_ITEMSMais de 50 itens na mesma venda (ou no mesmo estorno), ou mais de 500 no lote de ajustes.Junte as linhas do mesmo SKU (elas são somadas). Um pedido com mais de 50 SKUs diferentes: fale com o suporte — não divida o pedido em várias references. O lote de ajustes: divida em lotes de até 500, cada um com a sua Idempotency-Key.
422INVALID_ITEM_SKUItem que não é objeto, sem "sku", ou com "sku" que não é texto (até 100 caracteres). No lote de ajustes, vira o erro daquele item.Envie o sku_code da LOJEXA como texto em cada item.
422INVALID_ITEM_QTYItem com "quantity" que não é inteiro de 1 a 1.000.000 (2.5 e "3abc" não valem; 3, 3.0 e "3" valem 3).Envie "quantity" como inteiro positivo.
422WAREHOUSE_NOT_FOUNDO warehouse da consulta (ou do corpo de POST /vendas e do ajuste, no corpo ou no item) não é o id nem o code de um armazém ativo da empresa da chave. No lote de ajustes, o warehouse padrão do lote recusa o lote inteiro; o do item, só o item.Liste os armazéns em GET /armazens e use o id ou o code. Sem warehouse, vale o armazém padrão da empresa.
422SKU_NOT_FOUNDO SKU não existe ativo na empresa: 422 em POST /vendas (inexistente ou inativo; error.details.items lista todos, com status not_found ou inactive); 404 no ajuste de estoque (no lote, o erro do item) e no mapeamento.Confira o sku_code em GET /produtos (maiúsculas, minúsculas e acento não importam). SKU inativo não vende: tire do site.
422INSUFFICIENT_STOCKVenda: o disponível no armazém da venda (o mesmo número de GET /produtos, no mesmo warehouse) é menor que o pedido. error.details.items traz, por SKU: warehouse, requested, required (o total do SKU na venda, contando kit e peça juntos), available e, no kit, components. Nada foi baixado. Ajuste "out" (perda, avaria, saída): maior que o disponível no armazém do ajuste; error.details.items traz warehouse, requested, available e on_hand.Não repita igual: atualize o estoque do seu site com o available devolvido e recuse a venda (ou venda só o que há). No ajuste, a reserva de pedido não sai por "out": para acertar o físico contado, use "type": "set".
409REFERENCE_CONFLICTA reference já tem uma venda com OUTRO pedido (outro SKU, quantidade ou warehouse) — ou a reversal_reference já foi usada nesta venda com outro estorno. Nada foi gravado.Não repita: se é outra venda, use outra reference; para ver a que existe, GET /vendas/{reference}. O reenvio do MESMO pedido não cai aqui: volta 200 already_processed.
409STOCK_RACE_CONDITION
repita
Outra operação mexeu no mesmo estoque no mesmo instante (trava, deadlock ou a linha de saldo criada ao mesmo tempo). Nada foi gravado. Falta de estoque NÃO cai aqui: é 422 INSUFFICIENT_STOCK.Repita a MESMA chamada (mesma reference; no ajuste, a mesma Idempotency-Key), com backoff. Se a outra chamada era a mesma venda (ou o mesmo ajuste), a repetição volta 200 already_processed.
500TRANSACTION_FAILED
repita
A transação da venda falhou e foi desfeita (nada foi baixado).Repita com a mesma reference; se persistir, mande o request_id ao suporte.

Mais os de toda chamada — 401 (chave), 403 (escopo ou empresa suspensa), 429 (limite) e 500: tabela de erros.

Consultar venda

GET /api/v1/vendas/{reference} write:sales

O estado da venda: status (confirmed, partially_reversed ou reversed), os itens com o que já foi estornado de cada um e os estornos (reversals). É o jeito de saber, depois de um timeout, se a venda entrou. Vale para a venda registrada por qualquer chave da empresa. A {reference} vai codificada, como o SKU, e diferencia maiúsculas. Não existe: 404 SALE_NOT_FOUND.

NomeOndeTipoObrig.PadrãoLimitesExemplo
referencecaminhotextoSim—até 100 caracteresPEDIDO-123
A reference da venda, codificada (PED 77 -> PED%2077). Diferencia maiúsculas.
cURL
curl -sS --max-time 30 \
     -H "Authorization: Bearer $LOJEXA_API_KEY" \
     "https://lojexa.com/api/v1/vendas/PEDIDO-123"
JSON — 200 (depois de um cancelamento parcial)
{
  "success": true,
  "data": {
    "sale_id": 5,
    "reference": "PEDIDO-123",
    "status": "partially_reversed",
    "channel": "site",
    "warehouse": {
      "id": 1,
      "code": "PE",
      "name": "Pernambuco"
    },
    "created_at": "2026-10-24T10:15:00-03:00",
    "updated_at": "2026-10-24T10:42:00-03:00",
    "reversed_at": null,
    "items": [
      {
        "sku": "CAMISETA-M-AZUL",
        "sku_master_id": 10,
        "warehouse": {
          "id": 1,
          "code": "PE",
          "name": "Pernambuco"
        },
        "quantity": 2,
        "reversed_quantity": 1,
        "is_kit": false,
        "components": []
      }
    ],
    "reversals": [
      {
        "kind": "cancel",
        "reversal_reference": "CANC-1",
        "condition": null,
        "reason": "Cliente desistiu de uma",
        "created_at": "2026-10-24T10:42:00-03:00",
        "items": [
          {
            "sku": "CAMISETA-M-AZUL",
            "sku_master_id": 10,
            "warehouse": {
              "id": 1,
              "code": "PE",
              "name": "Pernambuco"
            },
            "quantity": 1,
            "restocked": 1
          }
        ]
      }
    ]
  }
}

Erros deste endpoint

HTTPCódigoQuando aconteceO que fazer
400INVALID_REFERENCEA referência do caminho está vazia ou, decodificada, não é texto UTF-8.Codifique a referência (encodeURIComponent / quote(ref, safe="")).
404SALE_NOT_FOUNDNenhuma venda com essa reference nesta empresa (a reference diferencia maiúsculas: "a1B2" não acha "A1b2").Use a reference exata enviada em POST /vendas, codificada no caminho.

Mais os de toda chamada — 401 (chave), 403 (escopo ou empresa suspensa), 429 (limite) e 500: tabela de erros.

Cancelar venda

POST /api/v1/vendas/{reference}/cancelar write:sales

Cancela a venda (por qualquer chave da empresa) e devolve ao disponível, no armazém de onde saiu, só o que saiu do estoque: o que o razão mostra como baixa desta venda, menos o que já voltou. Sem corpo, cancela tudo o que resta; com items, só aqueles (cancelamento parcial).

NomeOndeTipoObrig.PadrãoLimitesExemplo
referencecaminhotextoSim—até 100 caracteresPEDIDO-123
A reference da venda, codificada (PED 77 -> PED%2077). Diferencia maiúsculas.
itemscorpolistaNão—0 a 50 itens—
Estorno parcial: os SKUs da venda (como estão em items da venda) e quantas unidades, até o que resta. Ausente: tudo o que resta. Kit: pelo SKU do kit.
items[].skucorpotextoSim—até 100 caracteresCAMISETA-M-AZUL
O sku_code da LOJEXA (maiúsculas, minúsculas e acento não importam). Kit: o SKU do kit (a venda confere e baixa as peças no armazém dela; o estorno devolve as peças pela receita do momento da venda).
items[].quantitycorpointeiroSim—1 a 1.000.0001
Inteiro: 3, 3.0 e "3" valem; 2.5 e "3abc" dão 422 INVALID_ITEM_QTY. No kit, quantos kits.
items[].warehousecorpoid ou codeNão——SP
Só quando o mesmo SKU saiu de dois armazéns nesta venda.
reversal_referencecorpotextoNão—até 100 caracteresCANC-1
O id deste cancelamento ou devolução no seu sistema (ex.: o número do RMA). Obrigatório no parcial (422 MISSING_REVERSAL_REFERENCE): é ele que faz o reenvio não estornar duas vezes. A mesma de novo = 200 already_processed; com outro pedido = 409 REFERENCE_CONFLICT.
reasoncorpotextoNão—até 255 caracteresCliente desistiu
O motivo do estorno, guardado com ele.
conditioncorpotextoNãosellableum de: sellable, damaged—
Só em /devolver: sellable volta ao disponível; damaged volta ao físico como avaria (fora do disponível). Em /cancelar: 422 INVALID_FIELD.
  • Status: partially_reversed enquanto restar algo; reversed quando tudo voltou. O cancelamento total de uma venda já toda cancelada devolve 200 com "already_processed": true (não é erro).
  • Resposta: o estado da venda e reversal, com items[].restocked (o que voltou ao físico; na devolução com condition: damaged, entra como avaria e não volta ao disponível — confira available_after), available_after, on_hand_after e channels (o envio do novo saldo, como na venda). restocked só é menor que quantity em venda antiga que não chegou a baixar o estoque.
cURL
curl -sS --max-time 30 -X POST \
     -H "Authorization: Bearer $LOJEXA_API_KEY" \
     -H 'Content-Type: application/json' \
     --data-binary @- "https://lojexa.com/api/v1/vendas/PEDIDO-123/cancelar" <<'JSON'
{
  "items": [
    {
      "sku": "CAMISETA-M-AZUL",
      "quantity": 1
    }
  ],
  "reversal_reference": "CANC-1",
  "reason": "Cliente desistiu de uma"
}
JSON
JSON — 200 cancelamento parcial
{
  "success": true,
  "already_processed": false,
  "data": {
    "sale_id": 5,
    "reference": "PEDIDO-123",
    "status": "partially_reversed",
    "channel": "site",
    "warehouse": {
      "id": 1,
      "code": "PE",
      "name": "Pernambuco"
    },
    "created_at": "2026-10-24T10:15:00-03:00",
    "updated_at": "2026-10-24T10:42:00-03:00",
    "reversed_at": null,
    "items": [
      {
        "sku": "CAMISETA-M-AZUL",
        "sku_master_id": 10,
        "warehouse": {
          "id": 1,
          "code": "PE",
          "name": "Pernambuco"
        },
        "quantity": 2,
        "reversed_quantity": 1,
        "is_kit": false,
        "components": []
      }
    ],
    "reversals": [
      {
        "kind": "cancel",
        "reversal_reference": "CANC-1",
        "condition": null,
        "reason": "Cliente desistiu de uma",
        "created_at": "2026-10-24T10:42:00-03:00",
        "items": [
          {
            "sku": "CAMISETA-M-AZUL",
            "sku_master_id": 10,
            "warehouse": {
              "id": 1,
              "code": "PE",
              "name": "Pernambuco"
            },
            "quantity": 1,
            "restocked": 1
          }
        ]
      }
    ],
    "reversal": {
      "kind": "cancel",
      "reversal_reference": "CANC-1",
      "condition": null,
      "reason": "Cliente desistiu de uma",
      "created_at": "2026-10-24T10:42:00-03:00",
      "items": [
        {
          "sku": "CAMISETA-M-AZUL",
          "sku_master_id": 10,
          "warehouse": {
            "id": 1,
            "code": "PE",
            "name": "Pernambuco"
          },
          "quantity": 1,
          "restocked": 1,
          "available_after": 14,
          "on_hand_after": 17,
          "channels": [
            {
              "channel": "shopee",
              "store_id": 3,
              "store_name": "Luna Style Oficial",
              "stock_push_enabled": true,
              "push": "queued"
            },
            {
              "channel": "tiktok",
              "store_id": 7,
              "store_name": "Luna Style TikTok",
              "stock_push_enabled": false,
              "push": "disabled"
            }
          ]
        }
      ]
    }
  }
}

Erros deste endpoint

HTTPCódigoQuando aconteceO que fazer
400INVALID_REFERENCEA referência do caminho está vazia ou, decodificada, não é texto UTF-8.Codifique a referência (encodeURIComponent / quote(ref, safe="")).
400INVALID_JSONO corpo do POST não é um objeto JSON válido (vírgula sobrando, aspas simples, texto solto, lista no lugar de objeto).Envie Content-Type: application/json e um objeto JSON, ex.: {"type": "in", "quantity": 1, "reason": "Compra"}.
422INVALID_FIELDCampo do corpo com tipo errado ou maior que o limite (a mensagem diz qual). Na venda: channel > 50, customer_name > 100, customer_email > 150 ou sem "@", unit_price negativo, reference com "/"; no estorno: reason > 255, condition fora de sellable/damaged; no ajuste: expected_on_hand que não é inteiro >= 0, warehouse que não é id nem code; no mapeamento: platform_sku > 100, platform_product_id > 100, listing_sku > 200, platform_sku_id que não é id numérico (texto de dígitos, até 19), store_id que não é inteiro positivo, quantity_factor fora de 1 a 10.000.Corrija o campo citado. Os limites de cada campo estão na tabela do endpoint.
422MISSING_ITEMS"items" ausente, vazio ou que não é lista (na venda e no lote de ajustes; no estorno, "items" que não é lista).Envie ao menos um item {"sku": "...", "quantity": 1}. No estorno, omita "items" para estornar tudo.
422TOO_MANY_ITEMSMais de 50 itens na mesma venda (ou no mesmo estorno), ou mais de 500 no lote de ajustes.Junte as linhas do mesmo SKU (elas são somadas). Um pedido com mais de 50 SKUs diferentes: fale com o suporte — não divida o pedido em várias references. O lote de ajustes: divida em lotes de até 500, cada um com a sua Idempotency-Key.
422INVALID_ITEM_SKUItem que não é objeto, sem "sku", ou com "sku" que não é texto (até 100 caracteres). No lote de ajustes, vira o erro daquele item.Envie o sku_code da LOJEXA como texto em cada item.
422INVALID_ITEM_QTYItem com "quantity" que não é inteiro de 1 a 1.000.000 (2.5 e "3abc" não valem; 3, 3.0 e "3" valem 3).Envie "quantity" como inteiro positivo.
422MISSING_REVERSAL_REFERENCECancelamento ou devolução PARCIAL (com "items") sem "reversal_reference".Envie em "reversal_reference" o id deste cancelamento/devolução no seu sistema (ex.: o número da troca). É ele que faz o reenvio não estornar duas vezes.
404SALE_NOT_FOUNDNenhuma venda com essa reference nesta empresa (a reference diferencia maiúsculas: "a1B2" não acha "A1b2").Use a reference exata enviada em POST /vendas, codificada no caminho.
409INVALID_STATUS_FOR_CANCELA venda está com status failed: nada foi baixado e não há o que estornar.Nada a fazer.
422SKU_NOT_IN_SALEO SKU (ou o SKU naquele warehouse) do estorno parcial não está na venda.Use os SKUs de items[] de GET /vendas/{reference}. Kit se estorna pelo SKU do kit, não pelas peças.
422REVERSAL_EXCEEDS_SALEO estorno pede mais unidades do que restam para estornar daquele SKU (vendidas menos as já estornadas). error.details.items traz sold, remaining e requested.Peça até remaining. GET /vendas/{reference} mostra reversed_quantity de cada item.
409REFERENCE_CONFLICTA reference já tem uma venda com OUTRO pedido (outro SKU, quantidade ou warehouse) — ou a reversal_reference já foi usada nesta venda com outro estorno. Nada foi gravado.Não repita: se é outra venda, use outra reference; para ver a que existe, GET /vendas/{reference}. O reenvio do MESMO pedido não cai aqui: volta 200 already_processed.
409STOCK_RACE_CONDITION
repita
Outra operação mexeu no mesmo estoque no mesmo instante (trava, deadlock ou a linha de saldo criada ao mesmo tempo). Nada foi gravado. Falta de estoque NÃO cai aqui: é 422 INSUFFICIENT_STOCK.Repita a MESMA chamada (mesma reference; no ajuste, a mesma Idempotency-Key), com backoff. Se a outra chamada era a mesma venda (ou o mesmo ajuste), a repetição volta 200 already_processed.
500CANCEL_TRANSACTION_FAILED
repita
A transação do cancelamento ou da devolução falhou e foi desfeita (nada voltou ao estoque).Repita a mesma chamada; se persistir, mande o request_id ao suporte.

Mais os de toda chamada — 401 (chave), 403 (escopo ou empresa suspensa), 429 (limite) e 500: tabela de erros.

Registrar devolução

POST /api/v1/vendas/{reference}/devolver write:sales

A devolução depois da entrega, total ou parcial, com os mesmos campos e regras do cancelamento e mais condition: sellable (padrão: volta ao disponível) ou damaged (volta ao físico como avaria e não volta ao disponível — em GET /estoque/movimentos aparecem a devolução e a avaria). No cancelamento, condition é recusado (422 INVALID_FIELD).

NomeOndeTipoObrig.PadrãoLimitesExemplo
referencecaminhotextoSim—até 100 caracteresPEDIDO-123
A reference da venda, codificada (PED 77 -> PED%2077). Diferencia maiúsculas.
itemscorpolistaNão—0 a 50 itens—
Estorno parcial: os SKUs da venda (como estão em items da venda) e quantas unidades, até o que resta. Ausente: tudo o que resta. Kit: pelo SKU do kit.
items[].skucorpotextoSim—até 100 caracteresCAMISETA-M-AZUL
O sku_code da LOJEXA (maiúsculas, minúsculas e acento não importam). Kit: o SKU do kit (a venda confere e baixa as peças no armazém dela; o estorno devolve as peças pela receita do momento da venda).
items[].quantitycorpointeiroSim—1 a 1.000.0001
Inteiro: 3, 3.0 e "3" valem; 2.5 e "3abc" dão 422 INVALID_ITEM_QTY. No kit, quantos kits.
items[].warehousecorpoid ou codeNão——SP
Só quando o mesmo SKU saiu de dois armazéns nesta venda.
reversal_referencecorpotextoNão—até 100 caracteresCANC-1
O id deste cancelamento ou devolução no seu sistema (ex.: o número do RMA). Obrigatório no parcial (422 MISSING_REVERSAL_REFERENCE): é ele que faz o reenvio não estornar duas vezes. A mesma de novo = 200 already_processed; com outro pedido = 409 REFERENCE_CONFLICT.
reasoncorpotextoNão—até 255 caracteresCliente desistiu
O motivo do estorno, guardado com ele.
conditioncorpotextoNãosellableum de: sellable, damaged—
Só em /devolver: sellable volta ao disponível; damaged volta ao físico como avaria (fora do disponível). Em /cancelar: 422 INVALID_FIELD.
cURL
curl -sS --max-time 30 -X POST \
     -H "Authorization: Bearer $LOJEXA_API_KEY" \
     -H 'Content-Type: application/json' \
     --data-binary @- "https://lojexa.com/api/v1/vendas/PEDIDO-123/devolver" <<'JSON'
{
  "reversal_reference": "RMA-88",
  "condition": "damaged",
  "reason": "Chegou com defeito"
}
JSON
JSON — 200 devolução avariada
{
  "success": true,
  "already_processed": false,
  "data": {
    "sale_id": 5,
    "reference": "PEDIDO-123",
    "status": "reversed",
    "channel": "site",
    "warehouse": {
      "id": 1,
      "code": "PE",
      "name": "Pernambuco"
    },
    "created_at": "2026-10-24T10:15:00-03:00",
    "updated_at": "2026-10-24T11:05:00-03:00",
    "reversed_at": "2026-10-24T11:05:00-03:00",
    "items": [
      {
        "sku": "CAMISETA-M-AZUL",
        "sku_master_id": 10,
        "warehouse": {
          "id": 1,
          "code": "PE",
          "name": "Pernambuco"
        },
        "quantity": 2,
        "reversed_quantity": 2,
        "is_kit": false,
        "components": []
      }
    ],
    "reversals": [
      {
        "kind": "cancel",
        "reversal_reference": "CANC-1",
        "condition": null,
        "reason": "Cliente desistiu de uma",
        "created_at": "2026-10-24T10:42:00-03:00",
        "items": [
          {
            "sku": "CAMISETA-M-AZUL",
            "sku_master_id": 10,
            "warehouse": {
              "id": 1,
              "code": "PE",
              "name": "Pernambuco"
            },
            "quantity": 1,
            "restocked": 1
          }
        ]
      },
      {
        "kind": "return",
        "reversal_reference": "RMA-88",
        "condition": "damaged",
        "reason": "Chegou com defeito",
        "created_at": "2026-10-24T11:05:00-03:00",
        "items": [
          {
            "sku": "CAMISETA-M-AZUL",
            "sku_master_id": 10,
            "warehouse": {
              "id": 1,
              "code": "PE",
              "name": "Pernambuco"
            },
            "quantity": 1,
            "restocked": 1
          }
        ]
      }
    ],
    "reversal": {
      "kind": "return",
      "reversal_reference": "RMA-88",
      "condition": "damaged",
      "reason": "Chegou com defeito",
      "created_at": "2026-10-24T11:05:00-03:00",
      "items": [
        {
          "sku": "CAMISETA-M-AZUL",
          "sku_master_id": 10,
          "warehouse": {
            "id": 1,
            "code": "PE",
            "name": "Pernambuco"
          },
          "quantity": 1,
          "restocked": 1,
          "available_after": 14,
          "on_hand_after": 18,
          "channels": [
            {
              "channel": "shopee",
              "store_id": 3,
              "store_name": "Luna Style Oficial",
              "stock_push_enabled": true,
              "push": "queued"
            },
            {
              "channel": "tiktok",
              "store_id": 7,
              "store_name": "Luna Style TikTok",
              "stock_push_enabled": false,
              "push": "disabled"
            }
          ]
        }
      ]
    }
  }
}

Erros deste endpoint

HTTPCódigoQuando aconteceO que fazer
400INVALID_REFERENCEA referência do caminho está vazia ou, decodificada, não é texto UTF-8.Codifique a referência (encodeURIComponent / quote(ref, safe="")).
400INVALID_JSONO corpo do POST não é um objeto JSON válido (vírgula sobrando, aspas simples, texto solto, lista no lugar de objeto).Envie Content-Type: application/json e um objeto JSON, ex.: {"type": "in", "quantity": 1, "reason": "Compra"}.
422INVALID_FIELDCampo do corpo com tipo errado ou maior que o limite (a mensagem diz qual). Na venda: channel > 50, customer_name > 100, customer_email > 150 ou sem "@", unit_price negativo, reference com "/"; no estorno: reason > 255, condition fora de sellable/damaged; no ajuste: expected_on_hand que não é inteiro >= 0, warehouse que não é id nem code; no mapeamento: platform_sku > 100, platform_product_id > 100, listing_sku > 200, platform_sku_id que não é id numérico (texto de dígitos, até 19), store_id que não é inteiro positivo, quantity_factor fora de 1 a 10.000.Corrija o campo citado. Os limites de cada campo estão na tabela do endpoint.
422MISSING_ITEMS"items" ausente, vazio ou que não é lista (na venda e no lote de ajustes; no estorno, "items" que não é lista).Envie ao menos um item {"sku": "...", "quantity": 1}. No estorno, omita "items" para estornar tudo.
422TOO_MANY_ITEMSMais de 50 itens na mesma venda (ou no mesmo estorno), ou mais de 500 no lote de ajustes.Junte as linhas do mesmo SKU (elas são somadas). Um pedido com mais de 50 SKUs diferentes: fale com o suporte — não divida o pedido em várias references. O lote de ajustes: divida em lotes de até 500, cada um com a sua Idempotency-Key.
422INVALID_ITEM_SKUItem que não é objeto, sem "sku", ou com "sku" que não é texto (até 100 caracteres). No lote de ajustes, vira o erro daquele item.Envie o sku_code da LOJEXA como texto em cada item.
422INVALID_ITEM_QTYItem com "quantity" que não é inteiro de 1 a 1.000.000 (2.5 e "3abc" não valem; 3, 3.0 e "3" valem 3).Envie "quantity" como inteiro positivo.
422MISSING_REVERSAL_REFERENCECancelamento ou devolução PARCIAL (com "items") sem "reversal_reference".Envie em "reversal_reference" o id deste cancelamento/devolução no seu sistema (ex.: o número da troca). É ele que faz o reenvio não estornar duas vezes.
404SALE_NOT_FOUNDNenhuma venda com essa reference nesta empresa (a reference diferencia maiúsculas: "a1B2" não acha "A1b2").Use a reference exata enviada em POST /vendas, codificada no caminho.
409INVALID_STATUS_FOR_CANCELA venda está com status failed: nada foi baixado e não há o que estornar.Nada a fazer.
422SKU_NOT_IN_SALEO SKU (ou o SKU naquele warehouse) do estorno parcial não está na venda.Use os SKUs de items[] de GET /vendas/{reference}. Kit se estorna pelo SKU do kit, não pelas peças.
422REVERSAL_EXCEEDS_SALEO estorno pede mais unidades do que restam para estornar daquele SKU (vendidas menos as já estornadas). error.details.items traz sold, remaining e requested.Peça até remaining. GET /vendas/{reference} mostra reversed_quantity de cada item.
409REFERENCE_CONFLICTA reference já tem uma venda com OUTRO pedido (outro SKU, quantidade ou warehouse) — ou a reversal_reference já foi usada nesta venda com outro estorno. Nada foi gravado.Não repita: se é outra venda, use outra reference; para ver a que existe, GET /vendas/{reference}. O reenvio do MESMO pedido não cai aqui: volta 200 already_processed.
409STOCK_RACE_CONDITION
repita
Outra operação mexeu no mesmo estoque no mesmo instante (trava, deadlock ou a linha de saldo criada ao mesmo tempo). Nada foi gravado. Falta de estoque NÃO cai aqui: é 422 INSUFFICIENT_STOCK.Repita a MESMA chamada (mesma reference; no ajuste, a mesma Idempotency-Key), com backoff. Se a outra chamada era a mesma venda (ou o mesmo ajuste), a repetição volta 200 already_processed.
500CANCEL_TRANSACTION_FAILED
repita
A transação do cancelamento ou da devolução falhou e foi desfeita (nada voltou ao estoque).Repita a mesma chamada; se persistir, mande o request_id ao suporte.

Mais os de toda chamada — 401 (chave), 403 (escopo ou empresa suspensa), 429 (limite) e 500: tabela de erros.

Ajuste de estoque

POST /api/v1/estoque/{sku}/ajuste write:stock

Entrada, saída ou o físico contado de um SKU, no mesmo armazém que a leitura mostra: sem warehouse, o armazém padrão da empresa (o stock.available de GET /produtos); com warehouse, aquele. O reason_code diz o que aconteceu e decide o movimento gravado no razão (GET /estoque/movimentos) e no histórico do painel: perda e avaria não são gravadas como venda. Depois, o envio do novo saldo às lojas entra na fila (envio aos canais).

NomeOndeTipoObrig.PadrãoLimitesExemplo
skucaminhotextoSim——CAMISETA-M-AZUL
O SKU codificado (com "/": use POST /estoque/ajustes)
Idempotency-KeycabeçalhotextoNão—até 100 caracteres; ASCII visível, sem espaçocompra-nf-4512
Até 100 caracteres ASCII visíveis, sem espaço (um UUID, ou um id seu). Vale por empresa e por endpoint. O mesmo pedido com a mesma chave = 200 already_processed com o resultado original; outro pedido = 409 IDEMPOTENCY_MISMATCH. Recusa (4xx) não grava nada: a chave pode ser reusada depois de corrigir.
typecorpotextoSim—um de: in, out, setin
in = entrada; out = saída (até o disponível no armazém); set = o físico CONTADO (on_hand absoluto no armazém).
quantitycorpointeiroSim—0 a 1.000.00010
in/out: unidades (de 1 a 1.000.000); set: o físico contado (0 vale). 2.5 e "3abc" são recusados.
reason_codecorpotextoNão—um de: purchase, count, loss, damage, return, otherpurchase
O motivo, que decide o movimento no razão: purchase = entrada de compra; return = devolução; damage = avaria (fica no físico e sai do disponível); loss = perda; count = contagem; other = outro (exige reason). Por type — in: purchase, return, count, other; out: loss, damage, count, other; set: count, other. Sem ele: in/out = other, set = count.
reasoncorpotextoNão—até 255 caracteresNF 4512
Texto livre (até 255). Obrigatório com reason_code other (ou sem reason_code em in/out).
warehousecorpoid ou codeNão——SP
O armazém do ajuste. Sem ele, o padrão da empresa — o mesmo de stock.available em GET /produtos.
expected_on_handcorpointeiroNão—≥ 05
Opcional: o físico que você leu no armazém antes de ajustar. Se mudou, 409 STOCK_CHANGED e nada é gravado (a contagem não atropela uma venda feita no meio).
reason_codetypeO que gravaQuando usar
purchaseinEntrada de compra (purchase_entry)Chegou mercadoria do fornecedor
returninDevolução (return_entry)Peça devolvida que volta a vender. A devolução de uma venda da API vai por /vendas/{reference}/devolver
damageoutAvaria (damaged_in): a peça continua no físico e sai do disponívelPeça com defeito, separada
lossoutSaída (manual_adjustment negativo)Perda, quebra, furto
countin, out, setContagem (manual_adjustment)Inventário. É o padrão do set
otherin, out, setEntrada ou saída manual (no set, acerto de saldo)O resto — com reason. É o padrão de in e out
  • Idempotência: mande Idempotency-Key em todo ajuste. Deu timeout, queda de rede, 500 STOCK_ADJUST_FAILED ou 409 STOCK_RACE_CONDITION? Repita a mesma chamada com a mesma chave: se o ajuste entrou, volta 200 com "already_processed": true e o mesmo resultado — não lança duas vezes. A mesma chave com outro ajuste: 409 IDEMPOTENCY_MISMATCH (não repita; use outra chave). A chave vale por empresa e diferencia maiúsculas; recusa (4xx) não grava nada, e a chave pode ser reusada depois de corrigir. Sem a chave, cada chamada é um ajuste novo: nunca repita sem ela.
  • Saída (out): vai até o disponível no armazém — a reserva de um pedido não sai por ajuste. Mais que isso: 422 INSUFFICIENT_STOCK, com available e on_hand em error.details.items. Para acertar o físico de uma contagem, use set.
  • Contagem (set): mande o físico contado; a API grava a diferença. Com expected_on_hand, a contagem não atropela uma venda feita enquanto você contava (409 STOCK_CHANGED, com o on_hand de agora em error.details). O set igual ao físico não grava movimento ("movement": null) nem reenvia o saldo às lojas: push sai unchanged (um WMS que manda a contagem inteira a cada 15 min não reenvia o catálogo). Para reenviar o saldo de um SKU sem mudar o número, refaça o POST /mapeamentos do vínculo (o vínculo que já existe responde created: false e reenvia; exige o escopo manage:mappings) — ou, pelo painel, use Reenviar em Envio e estoque › Sincronização (gerente ou administrador).
  • SKU com / não cabe no caminho: use o lote com um item.
  • Kit: 422 KIT_NOT_ADJUSTABLE, como no painel: o estoque do kit vem das peças (error.details.components). Ajuste as peças.
  • SKU sem saldo por armazém (só o contador antigo): o primeiro ajuste grava a linha que a leitura já mostrava (o contador, no armazém de casa) e cria a do armazém escolhido vazia. O número que você lê não muda por isso.
  • Resposta: before e after (on_hand, damaged e available no armazém do ajuste), delta (a mudança do físico; na avaria, 0), movement e movement_id (o movimento no razão), stock_after (igual a after.available, o número de GET /produtos) e channels (push por loja, como na venda).
cURL — entrada de compra
curl -sS --max-time 30 -X POST \
     -H "Authorization: Bearer $LOJEXA_API_KEY" \
     -H 'Content-Type: application/json' \
     -H 'Idempotency-Key: compra-nf-4512' \
     --data-binary @- "https://lojexa.com/api/v1/estoque/CAMISETA-M-AZUL/ajuste" <<'JSON'
{
  "type": "in",
  "quantity": 10,
  "reason_code": "purchase",
  "reason": "NF 4512"
}
JSON

A repetição segura em Python, Node.js, PHP e cURL (o cliente que repete com a mesma Idempotency-Key) está no passo 7 do guia ponta a ponta.

JSON — 200 entrada de compra
{
  "success": true,
  "already_processed": false,
  "data": {
    "adjustment_id": 1,
    "idempotency_key": "compra-nf-4512",
    "sku_code": "CAMISETA-M-AZUL",
    "sku_master_id": 10,
    "type": "in",
    "reason_code": "purchase",
    "reason": "NF 4512",
    "quantity": 10,
    "warehouse": {
      "id": 1,
      "code": "PE",
      "name": "Pernambuco"
    },
    "movement": "purchase_entry",
    "movement_id": 908,
    "before": {
      "on_hand": 18,
      "damaged": 2,
      "available": 14
    },
    "after": {
      "on_hand": 28,
      "damaged": 2,
      "available": 24
    },
    "delta": 10,
    "stock_after": 24,
    "channels": [
      {
        "channel": "shopee",
        "store_id": 3,
        "store_name": "Luna Style Oficial",
        "stock_push_enabled": true,
        "push": "queued"
      },
      {
        "channel": "tiktok",
        "store_id": 7,
        "store_name": "Luna Style TikTok",
        "stock_push_enabled": false,
        "push": "disabled"
      }
    ],
    "created_at": "2026-10-24T11:20:00-03:00"
  }
}
JSON — 200 a mesma Idempotency-Key de novo (o mesmo resultado)
{
  "success": true,
  "already_processed": true,
  "data": {
    "adjustment_id": 1,
    "idempotency_key": "compra-nf-4512",
    "sku_code": "CAMISETA-M-AZUL",
    "sku_master_id": 10,
    "type": "in",
    "reason_code": "purchase",
    "reason": "NF 4512",
    "quantity": 10,
    "warehouse": {
      "id": 1,
      "code": "PE",
      "name": "Pernambuco"
    },
    "movement": "purchase_entry",
    "movement_id": 908,
    "before": {
      "on_hand": 18,
      "damaged": 2,
      "available": 14
    },
    "after": {
      "on_hand": 28,
      "damaged": 2,
      "available": 24
    },
    "delta": 10,
    "stock_after": 24,
    "channels": [
      {
        "channel": "shopee",
        "store_id": 3,
        "store_name": "Luna Style Oficial",
        "stock_push_enabled": true,
        "push": "queued"
      },
      {
        "channel": "tiktok",
        "store_id": 7,
        "store_name": "Luna Style TikTok",
        "stock_push_enabled": false,
        "push": "disabled"
      }
    ],
    "created_at": "2026-10-24T11:20:00-03:00"
  }
}
JSON — 409 a mesma Idempotency-Key com outro ajuste
{
  "success": false,
  "error": {
    "code": "IDEMPOTENCY_MISMATCH",
    "message": "A Idempotency-Key \"compra-nf-4512\" já foi usada nesta empresa com outro ajuste (SKU, type, quantity, warehouse, reason_code, reason ou expected_on_hand). Nada foi gravado. Para um ajuste novo, use outra chave.",
    "details": {
      "adjustment_id": 1
    },
    "request_id": "8f14e45fceea167a5a36dedd4bea2543"
  }
}
cURL — contagem em SP
curl -sS --max-time 30 -X POST \
     -H "Authorization: Bearer $LOJEXA_API_KEY" \
     -H 'Content-Type: application/json' \
     -H 'Idempotency-Key: inventario-2026-10-sp-0001' \
     --data-binary @- "https://lojexa.com/api/v1/estoque/CAMISETA-M-AZUL/ajuste" <<'JSON'
{
  "type": "set",
  "quantity": 6,
  "warehouse": "SP",
  "expected_on_hand": 5,
  "reason": "Inventário de outubro"
}
JSON
JSON — 200 contagem (set) com expected_on_hand
{
  "success": true,
  "already_processed": false,
  "data": {
    "adjustment_id": 2,
    "idempotency_key": "inventario-2026-10-sp-0001",
    "sku_code": "CAMISETA-M-AZUL",
    "sku_master_id": 10,
    "type": "set",
    "reason_code": "count",
    "reason": "Inventário de outubro",
    "quantity": 6,
    "warehouse": {
      "id": 2,
      "code": "SP",
      "name": "São Paulo"
    },
    "movement": "manual_adjustment",
    "movement_id": 909,
    "before": {
      "on_hand": 5,
      "damaged": 0,
      "available": 5
    },
    "after": {
      "on_hand": 6,
      "damaged": 0,
      "available": 6
    },
    "delta": 1,
    "stock_after": 6,
    "channels": [
      {
        "channel": "shopee",
        "store_id": 3,
        "store_name": "Luna Style Oficial",
        "stock_push_enabled": true,
        "push": "queued"
      },
      {
        "channel": "tiktok",
        "store_id": 7,
        "store_name": "Luna Style TikTok",
        "stock_push_enabled": false,
        "push": "disabled"
      }
    ],
    "created_at": "2026-10-24T11:20:00-03:00"
  }
}
JSON — 200 contagem igual ao físico (movement null, push "unchanged")
{
  "success": true,
  "already_processed": false,
  "data": {
    "adjustment_id": 3,
    "idempotency_key": "inventario-2026-10-sp-0002",
    "sku_code": "CAMISETA-M-AZUL",
    "sku_master_id": 10,
    "type": "set",
    "reason_code": "count",
    "reason": "Recontagem de outubro",
    "quantity": 6,
    "warehouse": {
      "id": 2,
      "code": "SP",
      "name": "São Paulo"
    },
    "movement": null,
    "movement_id": null,
    "before": {
      "on_hand": 6,
      "damaged": 0,
      "available": 6
    },
    "after": {
      "on_hand": 6,
      "damaged": 0,
      "available": 6
    },
    "delta": 0,
    "stock_after": 6,
    "channels": [
      {
        "channel": "shopee",
        "store_id": 3,
        "store_name": "Luna Style Oficial",
        "stock_push_enabled": true,
        "push": "unchanged"
      },
      {
        "channel": "tiktok",
        "store_id": 7,
        "store_name": "Luna Style TikTok",
        "stock_push_enabled": false,
        "push": "disabled"
      }
    ],
    "created_at": "2026-10-24T11:20:00-03:00"
  }
}
JSON — 422 kit não se ajusta
{
  "success": false,
  "error": {
    "code": "KIT_NOT_ADJUSTABLE",
    "message": "O SKU \"KIT-CAMISETA-2\" é um KIT: o estoque dele vem das peças. Ajuste cada peça (error.details.components). Nada foi gravado.",
    "details": {
      "sku": "KIT-CAMISETA-2",
      "components": [
        {
          "sku": "CAMISETA-M-AZUL",
          "sku_master_id": 10,
          "quantity_per_kit": 2
        }
      ]
    },
    "request_id": "8f14e45fceea167a5a36dedd4bea2543"
  }
}

Erros deste endpoint

HTTPCódigoQuando aconteceO que fazer
400INVALID_SKUO SKU do caminho está vazio ou, decodificado, não é texto UTF-8.Codifique o SKU (JavaScript encodeURIComponent, Python quote(sku, safe=""), PHP rawurlencode).
400INVALID_JSONO corpo do POST não é um objeto JSON válido (vírgula sobrando, aspas simples, texto solto, lista no lugar de objeto).Envie Content-Type: application/json e um objeto JSON, ex.: {"type": "in", "quantity": 1, "reason": "Compra"}.
400INVALID_IDEMPOTENCY_KEYCabeçalho Idempotency-Key com mais de 100 caracteres, espaço ou caractere fora do ASCII visível.Use um UUID ou um id seu (A-Z a-z 0-9 e pontuação, sem espaço), até 100 caracteres.
422INVALID_TYPE"type" diferente de "in" (entrada), "out" (saída) ou "set" (definir o físico contado).Envie "type": "in", "out" ou "set".
422INVALID_QUANTITY"quantity" que não é inteiro de 1 a 1.000.000 (em "set", de 0 a 1.000.000: é o físico contado). 2.5 e "3abc" não valem.Envie "quantity" como inteiro.
422INVALID_REASON_CODE"reason_code" fora da lista, ou que não combina com o "type": in aceita purchase, return, count, other; out aceita loss, damage, count, other; set aceita count, other.Use um reason_code da tabela do ajuste em /docs. Sem reason_code: in e out = other (com reason obrigatório), set = count.
422MISSING_REASONAjuste com "reason_code": "other" (ou sem reason_code em in/out) e sem "reason".Diga o motivo em "reason" (ex.: "Compra NF 123") ou use um reason_code (purchase, return, loss, damage, count).
422REASON_TOO_LONG"reason" com mais de 255 caracteres.Encurte o motivo para até 255 caracteres.
422INVALID_FIELDCampo do corpo com tipo errado ou maior que o limite (a mensagem diz qual). Na venda: channel > 50, customer_name > 100, customer_email > 150 ou sem "@", unit_price negativo, reference com "/"; no estorno: reason > 255, condition fora de sellable/damaged; no ajuste: expected_on_hand que não é inteiro >= 0, warehouse que não é id nem code; no mapeamento: platform_sku > 100, platform_product_id > 100, listing_sku > 200, platform_sku_id que não é id numérico (texto de dígitos, até 19), store_id que não é inteiro positivo, quantity_factor fora de 1 a 10.000.Corrija o campo citado. Os limites de cada campo estão na tabela do endpoint.
422WAREHOUSE_NOT_FOUNDO warehouse da consulta (ou do corpo de POST /vendas e do ajuste, no corpo ou no item) não é o id nem o code de um armazém ativo da empresa da chave. No lote de ajustes, o warehouse padrão do lote recusa o lote inteiro; o do item, só o item.Liste os armazéns em GET /armazens e use o id ou o code. Sem warehouse, vale o armazém padrão da empresa.
404SKU_NOT_FOUNDO SKU não existe ativo na empresa: 422 em POST /vendas (inexistente ou inativo; error.details.items lista todos, com status not_found ou inactive); 404 no ajuste de estoque (no lote, o erro do item) e no mapeamento.Confira o sku_code em GET /produtos (maiúsculas, minúsculas e acento não importam). SKU inativo não vende: tire do site.
422KIT_NOT_ADJUSTABLEO SKU do ajuste é um KIT: o estoque do kit vem das peças (como na tela de estoque). error.details.components lista as peças.Ajuste cada peça (error.details.components). O disponível do kit acompanha.
422INSUFFICIENT_STOCKVenda: o disponível no armazém da venda (o mesmo número de GET /produtos, no mesmo warehouse) é menor que o pedido. error.details.items traz, por SKU: warehouse, requested, required (o total do SKU na venda, contando kit e peça juntos), available e, no kit, components. Nada foi baixado. Ajuste "out" (perda, avaria, saída): maior que o disponível no armazém do ajuste; error.details.items traz warehouse, requested, available e on_hand.Não repita igual: atualize o estoque do seu site com o available devolvido e recuse a venda (ou venda só o que há). No ajuste, a reserva de pedido não sai por "out": para acertar o físico contado, use "type": "set".
409STOCK_CHANGEDO "expected_on_hand" do ajuste não é o físico de agora no armazém: o estoque mudou desde a sua leitura (uma venda, um pedido). error.details traz on_hand e available atuais. Nada foi gravado.Não repita igual: confira a contagem com o on_hand devolvido e mande de novo com o expected_on_hand atual (ou sem ele, para gravar o "set" mesmo assim).
409IDEMPOTENCY_MISMATCHA Idempotency-Key já foi usada nesta empresa com OUTRO ajuste (ou outro lote): SKU, type, quantity, warehouse, reason_code, reason ou expected_on_hand diferentes. Nada foi gravado.Não repita: para um ajuste novo, use outra chave. O reenvio do MESMO ajuste não cai aqui: volta 200 already_processed com o resultado original.
409STOCK_RACE_CONDITION
repita
Outra operação mexeu no mesmo estoque no mesmo instante (trava, deadlock ou a linha de saldo criada ao mesmo tempo). Nada foi gravado. Falta de estoque NÃO cai aqui: é 422 INSUFFICIENT_STOCK.Repita a MESMA chamada (mesma reference; no ajuste, a mesma Idempotency-Key), com backoff. Se a outra chamada era a mesma venda (ou o mesmo ajuste), a repetição volta 200 already_processed.
500STOCK_ADJUST_FAILED
repita
O ajuste falhou e foi desfeito (nada foi gravado).Repita com a mesma Idempotency-Key; se persistir, mande o request_id ao suporte.

Mais os de toda chamada — 401 (chave), 403 (escopo ou empresa suspensa), 429 (limite) e 500: tabela de erros.

Ajuste em lote

POST /api/v1/estoque/ajustes write:stock

Até 500 ajustes numa chamada — a conferência do seu ERP, o inventário do mês. Cada item tem os campos do ajuste avulso e mais sku (aqui vale SKU com /). warehouse, reason_code e reason no topo valem para o item que não traz o seu.

  • Idempotency-Key obrigatória (400 MISSING_IDEMPOTENCY_KEY): a chave do lote inteiro. O mesmo lote de novo devolve 200 com "already_processed": true e o resultado guardado de cada item. Outro lote com a mesma chave: 409 IDEMPOTENCY_MISMATCH. Repetiu enquanto o primeiro ainda grava (timeout no meio)? 409 BATCH_IN_PROGRESS: espere o Retry-After e repita igual.
  • Item a item, na ordem: cada item é gravado sozinho — um item recusado não desfaz os outros (o lote não é tudo ou nada). O mesmo SKU pode vir mais de uma vez. O resultado traz total, succeeded, failed e, por item, status ok (com adjustment, o mesmo objeto do ajuste avulso) ou error (com code, message e details, os mesmos códigos do avulso).
  • Item com erro que passa repetindo (STOCK_RACE_CONDITION, STOCK_ADJUST_FAILED): o lote guardado não muda; mande só esses itens num lote novo, com outra chave.
  • O lote inteiro só é recusado (nada gravado) quando o corpo não serve: 422 MISSING_ITEMS, TOO_MANY_ITEMS (mais de 500), WAREHOUSE_NOT_FOUND (o warehouse do topo), INVALID_REASON_CODE ou REASON_TOO_LONG do topo.
  • Envio: o novo saldo vai às lojas pela fila, em envios de 25 SKUs (o SKU que já está esperando um envio não entra de novo); channels[].push de cada item diz o que aconteceu.
NomeOndeTipoObrig.PadrãoLimitesExemplo
Idempotency-KeycabeçalhotextoSim—até 100 caracteres; ASCII visível, sem espaçocompra-nf-4512
OBRIGATÓRIA no lote (400 MISSING_IDEMPOTENCY_KEY): a chave do lote inteiro. Até 100 caracteres ASCII visíveis, sem espaço (um UUID, ou um id seu). Vale por empresa e por endpoint. O mesmo pedido com a mesma chave = 200 already_processed com o resultado original; outro pedido = 409 IDEMPOTENCY_MISMATCH. Recusa (4xx) não grava nada: a chave pode ser reusada depois de corrigir.
itemscorpolistaSim—1 a 500 itens—
Aplicados NA ORDEM, cada um na própria gravação. O mesmo SKU pode aparecer mais de uma vez.
items[].skucorpotextoSim—até 100 caracteresCAMISETA-M-AZUL
O sku_code (maiúsculas, minúsculas e acento não importam; "/" vale aqui)
items[].typecorpotextoSim—um de: in, out, setin
in = entrada; out = saída (até o disponível no armazém); set = o físico CONTADO (on_hand absoluto no armazém).
items[].quantitycorpointeiroSim—0 a 1.000.00010
in/out: unidades (de 1 a 1.000.000); set: o físico contado (0 vale). 2.5 e "3abc" são recusados.
items[].reason_codecorpotextoNão—um de: purchase, count, loss, damage, return, otherpurchase
O motivo, que decide o movimento no razão: purchase = entrada de compra; return = devolução; damage = avaria (fica no físico e sai do disponível); loss = perda; count = contagem; other = outro (exige reason). Por type — in: purchase, return, count, other; out: loss, damage, count, other; set: count, other. Sem ele: in/out = other, set = count.
items[].reasoncorpotextoNão—até 255 caracteresNF 4512
Texto livre (até 255). Obrigatório com reason_code other (ou sem reason_code em in/out).
items[].warehousecorpoid ou codeNão——SP
O armazém do ajuste. Sem ele, o padrão da empresa — o mesmo de stock.available em GET /produtos.
items[].expected_on_handcorpointeiroNão—≥ 05
Opcional: o físico que você leu no armazém antes de ajustar. Se mudou, 409 STOCK_CHANGED e nada é gravado (a contagem não atropela uma venda feita no meio).
warehousecorpoid ou codeNão——SP
O armazém padrão dos itens. Inválido: 422 WAREHOUSE_NOT_FOUND e nada é gravado.
reason_codecorpotextoNão—um de: purchase, count, loss, damage, return, othercount
O motivo dos itens que não trazem o seu.
reasoncorpotextoNão—até 255 caracteresConferência diária do ERP
O texto dos itens que não trazem o seu.
cURL — lote
curl -sS --max-time 30 -X POST \
     -H "Authorization: Bearer $LOJEXA_API_KEY" \
     -H 'Content-Type: application/json' \
     -H 'Idempotency-Key: lote-erp-2026-10-24' \
     --data-binary @- "https://lojexa.com/api/v1/estoque/ajustes" <<'JSON'
{
  "reason": "Conferência diária do ERP",
  "items": [
    {
      "sku": "CAMISETA-M-AZUL",
      "type": "out",
      "quantity": 1,
      "reason_code": "damage"
    },
    {
      "sku": "007-Preto-G1 (48 ao 52)",
      "type": "in",
      "quantity": 3,
      "warehouse": "SP",
      "reason_code": "purchase",
      "reason": "NF 4513"
    },
    {
      "sku": "BONE-PRETO",
      "type": "set",
      "quantity": 0
    }
  ]
}
JSON
JSON — 200 lote com um item recusado (SKU inativo)
{
  "success": true,
  "already_processed": false,
  "data": {
    "batch_id": 1,
    "idempotency_key": "lote-erp-2026-10-24",
    "status": "completed",
    "total": 3,
    "succeeded": 2,
    "failed": 1,
    "created_at": "2026-10-24T11:30:00-03:00",
    "completed_at": "2026-10-24T11:30:01-03:00",
    "items": [
      {
        "index": 0,
        "sku": "CAMISETA-M-AZUL",
        "status": "ok",
        "adjustment": {
          "adjustment_id": 4,
          "idempotency_key": null,
          "sku_code": "CAMISETA-M-AZUL",
          "sku_master_id": 10,
          "type": "out",
          "reason_code": "damage",
          "reason": "Conferência diária do ERP",
          "quantity": 1,
          "warehouse": {
            "id": 1,
            "code": "PE",
            "name": "Pernambuco"
          },
          "movement": "damaged_in",
          "movement_id": 910,
          "before": {
            "on_hand": 28,
            "damaged": 2,
            "available": 24
          },
          "after": {
            "on_hand": 28,
            "damaged": 3,
            "available": 23
          },
          "delta": 0,
          "stock_after": 23,
          "channels": [
            {
              "channel": "shopee",
              "store_id": 3,
              "store_name": "Luna Style Oficial",
              "stock_push_enabled": true,
              "push": "queued"
            },
            {
              "channel": "tiktok",
              "store_id": 7,
              "store_name": "Luna Style TikTok",
              "stock_push_enabled": false,
              "push": "disabled"
            }
          ],
          "created_at": "2026-10-24T11:30:00-03:00"
        },
        "error": null
      },
      {
        "index": 1,
        "sku": "007-Preto-G1 (48 ao 52)",
        "status": "ok",
        "adjustment": {
          "adjustment_id": 5,
          "idempotency_key": null,
          "sku_code": "007-Preto-G1 (48 ao 52)",
          "sku_master_id": 40,
          "type": "in",
          "reason_code": "purchase",
          "reason": "NF 4513",
          "quantity": 3,
          "warehouse": {
            "id": 2,
            "code": "SP",
            "name": "São Paulo"
          },
          "movement": "purchase_entry",
          "movement_id": 912,
          "before": {
            "on_hand": 0,
            "damaged": 0,
            "available": 0
          },
          "after": {
            "on_hand": 3,
            "damaged": 0,
            "available": 3
          },
          "delta": 3,
          "stock_after": 3,
          "channels": [],
          "created_at": "2026-10-24T11:30:00-03:00"
        },
        "error": null
      },
      {
        "index": 2,
        "sku": "BONE-PRETO",
        "status": "error",
        "adjustment": null,
        "error": {
          "code": "SKU_NOT_FOUND",
          "message": "SKU \"BONE-PRETO\" está inativo na empresa da chave. Nada foi gravado.",
          "details": null
        }
      }
    ]
  }
}

Erros deste endpoint

HTTPCódigoQuando aconteceO que fazer
400INVALID_JSONO corpo do POST não é um objeto JSON válido (vírgula sobrando, aspas simples, texto solto, lista no lugar de objeto).Envie Content-Type: application/json e um objeto JSON, ex.: {"type": "in", "quantity": 1, "reason": "Compra"}.
400MISSING_IDEMPOTENCY_KEYPOST /estoque/ajustes (lote) sem o cabeçalho Idempotency-Key: no lote ele é obrigatório.Envie Idempotency-Key: <um id do lote no seu sistema, ou um UUID>. Guarde-o: é ele que torna o reenvio seguro.
400INVALID_IDEMPOTENCY_KEYCabeçalho Idempotency-Key com mais de 100 caracteres, espaço ou caractere fora do ASCII visível.Use um UUID ou um id seu (A-Z a-z 0-9 e pontuação, sem espaço), até 100 caracteres.
422MISSING_ITEMS"items" ausente, vazio ou que não é lista (na venda e no lote de ajustes; no estorno, "items" que não é lista).Envie ao menos um item {"sku": "...", "quantity": 1}. No estorno, omita "items" para estornar tudo.
422TOO_MANY_ITEMSMais de 50 itens na mesma venda (ou no mesmo estorno), ou mais de 500 no lote de ajustes.Junte as linhas do mesmo SKU (elas são somadas). Um pedido com mais de 50 SKUs diferentes: fale com o suporte — não divida o pedido em várias references. O lote de ajustes: divida em lotes de até 500, cada um com a sua Idempotency-Key.
422INVALID_ITEM_SKUItem que não é objeto, sem "sku", ou com "sku" que não é texto (até 100 caracteres). No lote de ajustes, vira o erro daquele item.Envie o sku_code da LOJEXA como texto em cada item.
422INVALID_REASON_CODE"reason_code" fora da lista, ou que não combina com o "type": in aceita purchase, return, count, other; out aceita loss, damage, count, other; set aceita count, other.Use um reason_code da tabela do ajuste em /docs. Sem reason_code: in e out = other (com reason obrigatório), set = count.
422REASON_TOO_LONG"reason" com mais de 255 caracteres.Encurte o motivo para até 255 caracteres.
422INVALID_FIELDCampo do corpo com tipo errado ou maior que o limite (a mensagem diz qual). Na venda: channel > 50, customer_name > 100, customer_email > 150 ou sem "@", unit_price negativo, reference com "/"; no estorno: reason > 255, condition fora de sellable/damaged; no ajuste: expected_on_hand que não é inteiro >= 0, warehouse que não é id nem code; no mapeamento: platform_sku > 100, platform_product_id > 100, listing_sku > 200, platform_sku_id que não é id numérico (texto de dígitos, até 19), store_id que não é inteiro positivo, quantity_factor fora de 1 a 10.000.Corrija o campo citado. Os limites de cada campo estão na tabela do endpoint.
422WAREHOUSE_NOT_FOUNDO warehouse da consulta (ou do corpo de POST /vendas e do ajuste, no corpo ou no item) não é o id nem o code de um armazém ativo da empresa da chave. No lote de ajustes, o warehouse padrão do lote recusa o lote inteiro; o do item, só o item.Liste os armazéns em GET /armazens e use o id ou o code. Sem warehouse, vale o armazém padrão da empresa.
409IDEMPOTENCY_MISMATCHA Idempotency-Key já foi usada nesta empresa com OUTRO ajuste (ou outro lote): SKU, type, quantity, warehouse, reason_code, reason ou expected_on_hand diferentes. Nada foi gravado.Não repita: para um ajuste novo, use outra chave. O reenvio do MESMO ajuste não cai aqui: volta 200 already_processed com o resultado original.
409BATCH_IN_PROGRESS
repita
O lote desta Idempotency-Key ainda está sendo gravado por outra chamada (a primeira, que você abandonou por timeout).Repita a MESMA chamada depois do Retry-After: quando o lote terminar, ela devolve 200 already_processed com o resultado de cada item.
409STOCK_RACE_CONDITION
repita
Outra operação mexeu no mesmo estoque no mesmo instante (trava, deadlock ou a linha de saldo criada ao mesmo tempo). Nada foi gravado. Falta de estoque NÃO cai aqui: é 422 INSUFFICIENT_STOCK.Repita a MESMA chamada (mesma reference; no ajuste, a mesma Idempotency-Key), com backoff. Se a outra chamada era a mesma venda (ou o mesmo ajuste), a repetição volta 200 already_processed.

Mais os de toda chamada — 401 (chave), 403 (escopo ou empresa suspensa), 429 (limite) e 500: tabela de erros.

Erros de cada item (em items[].error, com o lote em 200)

HTTPCódigoQuando aconteceO que fazer
—INVALID_ITEM_SKUItem que não é objeto, sem "sku", ou com "sku" que não é texto (até 100 caracteres). No lote de ajustes, vira o erro daquele item.Envie o sku_code da LOJEXA como texto em cada item.
—INVALID_TYPE"type" diferente de "in" (entrada), "out" (saída) ou "set" (definir o físico contado).Envie "type": "in", "out" ou "set".
—INVALID_QUANTITY"quantity" que não é inteiro de 1 a 1.000.000 (em "set", de 0 a 1.000.000: é o físico contado). 2.5 e "3abc" não valem.Envie "quantity" como inteiro.
—INVALID_REASON_CODE"reason_code" fora da lista, ou que não combina com o "type": in aceita purchase, return, count, other; out aceita loss, damage, count, other; set aceita count, other.Use um reason_code da tabela do ajuste em /docs. Sem reason_code: in e out = other (com reason obrigatório), set = count.
—MISSING_REASONAjuste com "reason_code": "other" (ou sem reason_code em in/out) e sem "reason".Diga o motivo em "reason" (ex.: "Compra NF 123") ou use um reason_code (purchase, return, loss, damage, count).
—REASON_TOO_LONG"reason" com mais de 255 caracteres.Encurte o motivo para até 255 caracteres.
—INVALID_FIELDCampo do corpo com tipo errado ou maior que o limite (a mensagem diz qual). Na venda: channel > 50, customer_name > 100, customer_email > 150 ou sem "@", unit_price negativo, reference com "/"; no estorno: reason > 255, condition fora de sellable/damaged; no ajuste: expected_on_hand que não é inteiro >= 0, warehouse que não é id nem code; no mapeamento: platform_sku > 100, platform_product_id > 100, listing_sku > 200, platform_sku_id que não é id numérico (texto de dígitos, até 19), store_id que não é inteiro positivo, quantity_factor fora de 1 a 10.000.Corrija o campo citado. Os limites de cada campo estão na tabela do endpoint.
—WAREHOUSE_NOT_FOUNDO warehouse da consulta (ou do corpo de POST /vendas e do ajuste, no corpo ou no item) não é o id nem o code de um armazém ativo da empresa da chave. No lote de ajustes, o warehouse padrão do lote recusa o lote inteiro; o do item, só o item.Liste os armazéns em GET /armazens e use o id ou o code. Sem warehouse, vale o armazém padrão da empresa.
—SKU_NOT_FOUNDO SKU não existe ativo na empresa: 422 em POST /vendas (inexistente ou inativo; error.details.items lista todos, com status not_found ou inactive); 404 no ajuste de estoque (no lote, o erro do item) e no mapeamento.Confira o sku_code em GET /produtos (maiúsculas, minúsculas e acento não importam). SKU inativo não vende: tire do site.
—KIT_NOT_ADJUSTABLEO SKU do ajuste é um KIT: o estoque do kit vem das peças (como na tela de estoque). error.details.components lista as peças.Ajuste cada peça (error.details.components). O disponível do kit acompanha.
—INSUFFICIENT_STOCKVenda: o disponível no armazém da venda (o mesmo número de GET /produtos, no mesmo warehouse) é menor que o pedido. error.details.items traz, por SKU: warehouse, requested, required (o total do SKU na venda, contando kit e peça juntos), available e, no kit, components. Nada foi baixado. Ajuste "out" (perda, avaria, saída): maior que o disponível no armazém do ajuste; error.details.items traz warehouse, requested, available e on_hand.Não repita igual: atualize o estoque do seu site com o available devolvido e recuse a venda (ou venda só o que há). No ajuste, a reserva de pedido não sai por "out": para acertar o físico contado, use "type": "set".
—STOCK_CHANGEDO "expected_on_hand" do ajuste não é o físico de agora no armazém: o estoque mudou desde a sua leitura (uma venda, um pedido). error.details traz on_hand e available atuais. Nada foi gravado.Não repita igual: confira a contagem com o on_hand devolvido e mande de novo com o expected_on_hand atual (ou sem ele, para gravar o "set" mesmo assim).
—STOCK_RACE_CONDITION
repita
Outra operação mexeu no mesmo estoque no mesmo instante (trava, deadlock ou a linha de saldo criada ao mesmo tempo). Nada foi gravado. Falta de estoque NÃO cai aqui: é 422 INSUFFICIENT_STOCK.Repita a MESMA chamada (mesma reference; no ajuste, a mesma Idempotency-Key), com backoff. Se a outra chamada era a mesma venda (ou o mesmo ajuste), a repetição volta 200 already_processed.
—STOCK_ADJUST_FAILED
repita
O ajuste falhou e foi desfeito (nada foi gravado).Repita com a mesma Idempotency-Key; se persistir, mande o request_id ao suporte.

Criar ou atualizar mapeamento

POST /api/v1/mapeamentos manage:mappings

Liga um SKU da LOJEXA ao anúncio (ou à variação) de um canal — a mesma gravação da tela de Mapeamento do painel. Depois, o estoque do SKU vai às lojas vinculadas pela fila (envio aos canais).

  • O vínculo é a loja + o anúncio + a variação. O mesmo SKU + platform + platform_sku na mesma loja atualiza o vínculo que existe; o mesmo anúncio e variação (platform_product_id + platform_sku_id) com outro platform_sku também — o texto novo fica.
  • O campo que não vem fica como está. Reenviar {sku, platform, platform_sku, store_id} de um vínculo feito no painel não apaga a variação, o listing_sku, o anúncio nem o fator: só muda o que você mandou.
  • O anúncio já ligado a outro SKU responde 409 MAPPING_CONFLICT, com o vínculo e o SKU dono em error.details, e nada é gravado (a API não toma o vínculo de ninguém). Repetir não resolve: se o vínculo antigo está errado, remova-o (DELETE /mapeamentos/{id}) e crie de novo.
  • Mesmo texto em OUTRO anúncio da loja: o lojista repete SKU entre anúncios. Com platform_product_id diferente, o vínculo novo nasce com o texto desambiguado ("<texto> [<anúncio>]", o original em listing_sku), como no painel. A resposta mostra o texto como ficou.
  • Plataformas: shopee, mercadolivre, magalu, nuvemshop, shopify, amazon, tiktok, shein, temu — as que o envio de estoque atende. api, fisica e outro foram removidos em 24/10/2026 (422 INVALID_PLATFORM): nada no sistema lia esse vínculo. Outra: 422 INVALID_PLATFORM.
NomeOndeTipoObrig.PadrãoLimitesExemplo
skucorpotextoSim—até 100 caracteresCAMISETA-M-AZUL
O sku_code da LOJEXA (maiúsculas, minúsculas e acento não importam). Sem ele: 422 MISSING_SKU; inexistente ou inativo: 404 SKU_NOT_FOUND.
platformcorpotextoSim—um de: shopee, mercadolivre, magalu, nuvemshop, shopify, amazon, tiktok, shein, temushopee
O canal do anúncio, sem diferenciar caixa. Sem ele: 422 MISSING_PLATFORM. Outro valor — inclusive api, fisica e outro, removidos em 24/10/2026: 422 INVALID_PLATFORM.
platform_skucorpotextoSim—até 100 caracteresCAMISETA-M-AZUL
O SKU do anúncio (ou da variação) no canal, como aparece lá. Sem ele: 422 MISSING_PLATFORM_SKU.
store_idcorpointeiroNão—≥ 1—
A loja: o store_id de GET /lojas (na Shopee, o shop_id também vale; a resposta devolve o id interno). Obrigatório em shopee, tiktok, shein, mercadolivre, magalu, nuvemshop — sem a loja o anúncio nunca recebe o estoque (422 MISSING_STORE). Loja de outra empresa ou de outro canal: 404 STORE_NOT_FOUND.
platform_product_idcorpotextoNão—até 100 caracteres23847719012
O id do anúncio no canal (item_id da Shopee, MLB do Mercado Livre...).
platform_sku_idcorpotexto de dígitos (até 19) ou inteiroNão——198273645
O id da variação no canal (model_id; "0" = sem variação). Mande como TEXTO de dígitos, como o GET devolve: um id de 19 dígitos (TikTok) mandado como número perde os últimos dígitos no JSON do JavaScript e o vínculo iria para a variação errada. Inteiro também é aceito.
listing_skucorpotextoNão—até 200 caracteresB0CXYZ1234-M
O SKU da listagem, quando o canal tem um (Amazon).
quantity_factorcorpointeiroNão—1 a 10.0001
Unidades do SKU por unidade do anúncio: o anúncio "pacote com 3" = 3 (com 30 em estoque, o anúncio mostra 10). Padrão 1 no vínculo novo.

Campo com tipo errado ou acima do limite: 422 INVALID_FIELD, nada gravado. A resposta é sempre 201 com o vínculo como ficou gravado (os campos de GET /mapeamentos), created (true = nasceu agora; false = o que já existia) e channels: as lojas vinculadas ao SKU e o push do saldo (queued, disabled ou not_queued; a API não liga o envio de nenhuma loja).

cURL
curl -sS --max-time 30 -X POST \
     -H "Authorization: Bearer $LOJEXA_API_KEY" \
     -H 'Content-Type: application/json' \
     --data-binary @- "https://lojexa.com/api/v1/mapeamentos" <<'JSON'
{
  "sku": "007-Preto-G1 (48 ao 52)",
  "platform": "shopee",
  "platform_sku": "PANTALONA-PRETA-G1",
  "store_id": 214207009,
  "platform_product_id": "23847719100",
  "platform_sku_id": "198273700"
}
JSON
JSON — 201 vínculo novo (o shop_id 214207009 virou a loja 3)
{
  "success": true,
  "data": {
    "id": 20,
    "sku_master_id": 40,
    "platform": "shopee",
    "platform_sku": "PANTALONA-PRETA-G1",
    "platform_product_id": "23847719100",
    "store_id": 3,
    "quantity_factor": 1,
    "created_at": "2026-10-24T11:40:00-03:00",
    "master_sku": "007-Preto-G1 (48 ao 52)",
    "master_name": "Calça Pantalona Preta G1",
    "stock_available": 4,
    "platform_sku_id": "198273700",
    "listing_sku": null,
    "store_name": "Luna Style Oficial",
    "created": true,
    "channels": [
      {
        "channel": "shopee",
        "store_id": 3,
        "store_name": "Luna Style Oficial",
        "stock_push_enabled": true,
        "push": "queued"
      }
    ]
  }
}
JSON — 201 reenvio do vínculo do painel sem a variação: ela fica (created: false)
{
  "success": true,
  "data": {
    "id": 17,
    "sku_master_id": 10,
    "platform": "shopee",
    "platform_sku": "CAMISETA-M-AZUL",
    "platform_product_id": "23847719012",
    "store_id": 3,
    "quantity_factor": 1,
    "created_at": "2026-10-01T10:00:00-03:00",
    "master_sku": "CAMISETA-M-AZUL",
    "master_name": "Camiseta Básica Azul M",
    "stock_available": 23,
    "platform_sku_id": "198273645",
    "listing_sku": null,
    "store_name": "Luna Style Oficial",
    "created": false,
    "channels": [
      {
        "channel": "shopee",
        "store_id": 3,
        "store_name": "Luna Style Oficial",
        "stock_push_enabled": true,
        "push": "queued"
      },
      {
        "channel": "tiktok",
        "store_id": 7,
        "store_name": "Luna Style TikTok",
        "stock_push_enabled": false,
        "push": "disabled"
      }
    ]
  }
}
JSON — 409 MAPPING_CONFLICT (o anúncio é de outro SKU)
{
  "success": false,
  "error": {
    "code": "MAPPING_CONFLICT",
    "message": "O anúncio \"CAMISETA-M-AZUL\" de shopee já está ligado ao SKU \"CAMISETA-M-AZUL\" (vínculo 17). Nada foi gravado. Para trocar, remova o vínculo antigo (DELETE /mapeamentos/17) e crie de novo.",
    "details": {
      "mapping_id": 17,
      "sku": "CAMISETA-M-AZUL",
      "sku_master_id": 10,
      "platform": "shopee",
      "platform_sku": "CAMISETA-M-AZUL",
      "platform_product_id": "23847719012",
      "platform_sku_id": "198273645",
      "store_id": 3
    },
    "request_id": "8f14e45fceea167a5a36dedd4bea2543"
  }
}
JSON — 422 MISSING_STORE (SHEIN sem store_id)
{
  "success": false,
  "error": {
    "code": "MISSING_STORE",
    "message": "O vínculo de shein precisa de \"store_id\": o envio de estoque junta o vínculo com a loja, e sem ela o anúncio nunca recebe o saldo. Use o id de GET /lojas.",
    "request_id": "8f14e45fceea167a5a36dedd4bea2543"
  }
}

Erros deste endpoint

HTTPCódigoQuando aconteceO que fazer
400INVALID_JSONO corpo do POST não é um objeto JSON válido (vírgula sobrando, aspas simples, texto solto, lista no lugar de objeto).Envie Content-Type: application/json e um objeto JSON, ex.: {"type": "in", "quantity": 1, "reason": "Compra"}.
422MISSING_SKUMapeamento sem "sku".Envie o sku_code da LOJEXA em "sku".
422MISSING_PLATFORMMapeamento sem "platform".Envie o canal em "platform" (ex.: shopee).
422INVALID_PLATFORMCanal que a API não aceita em "platform". Desde a v1.4 (24/10/2026), "api", "fisica" e "outro" foram removidos: nada no sistema lia esse vínculo.Use um dos canais do envio de estoque: shopee, mercadolivre, magalu, nuvemshop, shopify, amazon, tiktok, shein ou temu.
422MISSING_PLATFORM_SKUMapeamento sem "platform_sku".Envie o código do anúncio no canal em "platform_sku".
422MISSING_STOREMapeamento de shopee, mercadolivre, tiktok, shein, magalu ou nuvemshop sem "store_id": vínculo sem loja nunca recebe estoque nesses canais.Envie o id da loja de GET /lojas (na Shopee, o shop_id também vale).
422INVALID_FIELDCampo do corpo com tipo errado ou maior que o limite (a mensagem diz qual). Na venda: channel > 50, customer_name > 100, customer_email > 150 ou sem "@", unit_price negativo, reference com "/"; no estorno: reason > 255, condition fora de sellable/damaged; no ajuste: expected_on_hand que não é inteiro >= 0, warehouse que não é id nem code; no mapeamento: platform_sku > 100, platform_product_id > 100, listing_sku > 200, platform_sku_id que não é id numérico (texto de dígitos, até 19), store_id que não é inteiro positivo, quantity_factor fora de 1 a 10.000.Corrija o campo citado. Os limites de cada campo estão na tabela do endpoint.
404SKU_NOT_FOUNDO SKU não existe ativo na empresa: 422 em POST /vendas (inexistente ou inativo; error.details.items lista todos, com status not_found ou inactive); 404 no ajuste de estoque (no lote, o erro do item) e no mapeamento.Confira o sku_code em GET /produtos (maiúsculas, minúsculas e acento não importam). SKU inativo não vende: tire do site.
404STORE_NOT_FOUNDA loja informada em "store_id" não é desta empresa nesse canal.Use o "store_id" de GET /lojas (na Shopee, o shop_id também vale).
409MAPPING_CONFLICTO anúncio (o mesmo platform_sku na loja, ou a mesma variação) já está ligado a OUTRO SKU. error.details diz o vínculo e o SKU dono. Nada foi gravado.Repetir não resolve. Se o vínculo antigo está errado, remova-o (DELETE /mapeamentos/{error.details.mapping_id}) e crie de novo; se está certo, use outro platform_sku.

Mais os de toda chamada — 401 (chave), 403 (escopo ou empresa suspensa), 429 (limite) e 500: tabela de erros.

Remover mapeamento

DELETE /api/v1/mapeamentos/{id} manage:mappings

Remove o vínculo pelo id (de GET /mapeamentos), só da empresa da chave. O anúncio fica com o último número que recebeu: a LOJEXA para de atualizá-lo por este vínculo. Inexistente: 404 MAPPING_NOT_FOUND; id que não é número: 400 INVALID_ID.

NomeOndeTipoObrig.PadrãoLimitesExemplo
idcaminhointeiroSim——18
id do mapeamento (GET /mapeamentos)
cURL
curl -sS --max-time 30 -X DELETE \
     -H "Authorization: Bearer $LOJEXA_API_KEY" \
     "https://lojexa.com/api/v1/mapeamentos/18"
JSON — 200 (o vínculo da TikTok removido)
{
  "success": true,
  "data": {
    "deleted_id": 18
  }
}

Erros deste endpoint

HTTPCódigoQuando aconteceO que fazer
400INVALID_IDId do mapeamento no caminho não é inteiro positivo.Use o "id" que veio em GET /mapeamentos.
404MAPPING_NOT_FOUNDMapeamento inexistente ou de outra empresa.Liste em GET /mapeamentos e use o "id" de lá.

Mais os de toda chamada — 401 (chave), 403 (escopo ou empresa suspensa), 429 (limite) e 500: tabela de erros.

Envio do estoque aos canais

Depois de uma escrita pela API, a LOJEXA envia o novo saldo de cada SKU aos anúncios vinculados:

  • Só às lojas com o envio de estoque ligado (stock_push_enabled: true) e só pelos vínculos que existem — veja o checklist. Ligar o envio de uma loja é decisão do lojista, no painel: a API só informa.
  • Venda, cancelamento e devolução: o envio entra na fila na mesma gravação da venda e não segura a sua chamada; costuma sair em poucos minutos (a fila é a mesma para todas as empresas: o envio da API passa na frente da sincronização programada até 20 SKUs a cada 10 min da sua empresa; acima disso, sai na ordem de chegada e pode demorar mais). Entram na fila o SKU vendido, as peças baixadas (kit) e os kits que usam o que foi baixado, cada um se tiver loja com o envio ligado. A resposta diz, por loja vinculada, push: queued, disabled ou not_queued.
  • Ajuste de estoque: o envio também entra na fila na mesma gravação: o SKU ajustado e os kits que o usam, cada um se tiver loja com o envio ligado. No lote, em envios de 25 SKUs; o SKU que já está esperando um envio não entra de novo (o envio que já está na fila lê o número novo) e, com um lote cheio da empresa ainda esperando (20 envios, 500 SKUs), o ajuste é gravado e sai push: "not_queued" — a sincronização programada corrige em até ~1h30 (para forçar um SKU antes, veja o reenvio na contagem). A resposta diz push por loja (unchanged quando nada mudou).
  • Mapeamento: o vínculo gravado por POST /mapeamentos põe o envio do saldo do SKU na fila, pelos mesmos critérios (só com loja de envio ligado). A resposta diz push por loja. Remover o vínculo não zera o anúncio: ele fica com o último número enviado.
  • Falha de envio a um canal não muda a resposta da API: o motivo fica em Envio e estoque › Sincronização (a página "Sincronização de estoque"), com o Motivo "Venda pela API", "Cancelamento pela API", "Devolução pela API", "Ajuste pela API", "Lote de ajustes pela API" ou "Vínculo pela API".
  • Canais: Shopee, Mercado Livre, Amazon, Shopify, Nuvemshop, Magalu, TikTok Shop, SHEIN e Temu.

Webhooks

Se a chave tiver uma URL de webhook, a LOJEXA faz um POST nela quando esta chave registra, cancela ou devolve uma venda (o reenvio que volta already_processed não avisa de novo). Não há webhook de estoque, de pedido do marketplace nem de venda feita por outra chave: o webhook é um aviso; a fonte da verdade são os feeds (/estoque/mudancas) e GET /vendas/{reference}.

EventoQuandodata
sale.confirmedDepois de POST /vendas com 201 (o estoque já foi baixado)sale_id, reference, channel, items (sku, quantity, stock_after = o disponível no armazém da venda, warehouse)
sale.reversedDepois de POST /vendas/{reference}/cancelar ou /devolver que estornou agora, total ou parcialreference, items_count (linhas deste estorno), sale_id, reversal_id, kind (cancel ou return), partial (true = ainda resta item não estornado), reversal_reference, condition (na devolução), status da venda e items (sku, quantity, restocked = o que voltou ao físico — com condition damaged, como avaria, fora do disponível: não some ao seu estoque vendável —, warehouse)

Os corpos abaixo são os que a fila grava (gerados pelo teste a partir de uma venda e de um cancelamento parcial de verdade). timestamp é o instante Unix do evento (o mesmo da v1.2) e occurred_at, o mesmo instante em ISO 8601.

JSON — corpo de sale.confirmed
{
  "event": "sale.confirmed",
  "event_id": "evt_3f9a2c7d1e0b4a5f6c8d9e01",
  "company_id": 1,
  "timestamp": 1792847700,
  "occurred_at": "2026-10-24T10:15:00-03:00",
  "data": {
    "sale_id": 5,
    "reference": "PEDIDO-123",
    "channel": "site",
    "items": [
      {
        "sku": "CAMISETA-M-AZUL",
        "quantity": 2,
        "stock_after": 13,
        "warehouse": {
          "id": 1,
          "code": "PE",
          "name": "Pernambuco"
        }
      }
    ]
  }
}
JSON — corpo de sale.reversed (cancelamento parcial)
{
  "event": "sale.reversed",
  "event_id": "evt_8b1d4e6f2a3c5b7d9e0f1a23",
  "company_id": 1,
  "timestamp": 1792849320,
  "occurred_at": "2026-10-24T10:42:00-03:00",
  "data": {
    "reference": "PEDIDO-123",
    "items_count": 1,
    "sale_id": 5,
    "reversal_id": 1,
    "kind": "cancel",
    "partial": true,
    "reversal_reference": "CANC-1",
    "condition": null,
    "status": "partially_reversed",
    "items": [
      {
        "sku": "CAMISETA-M-AZUL",
        "quantity": 1,
        "restocked": 1,
        "warehouse": {
          "id": 1,
          "code": "PE",
          "name": "Pernambuco"
        }
      }
    ]
  }
}

Como a LOJEXA entrega

  • Fora da sua chamada: o evento é gravado junto com a venda (se a venda desfaz, o aviso some junto) e sai em geral em até ~1 minuto com o seu servidor respondendo. A sua chamada não espera o webhook.
  • A ordem não é garantida: um aviso que falhou volta depois dos mais novos (um sale.reversed pode chegar antes do sale.confirmed da mesma venda). Ordene por occurred_at e, na dúvida, consulte GET /vendas/{reference}.
  • Cabeçalhos: Content-Type: application/json, X-Lojexa-Event (o evento), X-Lojexa-Event-Id (o mesmo event_id do corpo), X-Lojexa-Timestamp (instante Unix desta tentativa), X-Lojexa-Delivery-Attempt (1 a 10), X-Lojexa-Signature e X-Lojexa-Signature-V2.
  • Assinatura: X-Lojexa-Signature-V2: sha256=<hex> = HMAC-SHA256 de <X-Lojexa-Timestamp>.<corpo cru> com o secret da chave. Use esta: o timestamp assinado impede que alguém repita um aviso antigo. Recuse se a diferença para o seu relógio passar de 300 s. X-Lojexa-Signature (HMAC só do corpo) continua igual à da v1.2.
  • Responda 2xx rápido (em menos de 10 s) e processe depois, numa fila sua. Qualquer outra resposta — 3xx, 4xx, 5xx — ou timeout é uma tentativa que falhou.
  • Novas tentativas: até 10 no total, em cerca de 24 h: a primeira na hora e as outras 1 min, 5 min, 15 min, 30 min, 1 h, 2 h, 4 h, 8 h e 8 h depois da anterior (podem atrasar alguns minutos com muito aviso na vez). Depois da última, o aviso desiste — por isso, reconcilie pelos feeds.
  • Servidor fora do ar: quando a tentativa falha por causa do destino (timeout, conexão recusada, DNS, 3xx, 5xx, 408 ou 429), a LOJEXA pausa os avisos desta chave: 1 min, e a cada nova falha seguida 5 min, 15 min, 30 min, 1 h, 2 h, 4 h e até 8 h. Na pausa nenhum aviso da chave sai, nem o de uma venda nova. Vencida a pausa, vai um aviso; na primeira resposta 2xx a pausa acaba e os outros saem em seguida. Aviso que passa de 48 h sem ser entregue desiste.
  • Aviso que o seu servidor recusa (outro 4xx: um 422 dele, um evento que ele não trata): só esse aviso segue a própria espera; os outros da chave continuam saindo, e o aviso novo vai antes do reenvio do recusado. Mas 3 recusas seguidas, sem nenhum 2xx no meio (secret ou URL errados: tudo volta 401 ou 404), pausam a chave como acima.
  • Onde ver as tentativas: hoje não há tela nem endpoint com as entregas do webhook e o último erro. Confira pela GET /vendas/{reference} e pelos feeds.
  • Ao menos uma vez: o mesmo aviso pode chegar mais de uma vez (ex.: o seu servidor respondeu depois do timeout). Deduplique pelo event_id (o mesmo em toda tentativa) antes de processar.
  • Destino: a URL precisa ser https://, sem usuário e senha, com o host só de letras, números, hífen e ponto (nome acentuado em punycode, xn--; nada de % nem _), e o endereço público: o host é resolvido e conferido a cada tentativa (IP de rede interna, loopback ou de metadados é recusado, mesmo que o DNS mude depois da criação) e a LOJEXA não segue redirect — configure a URL final.
  • A URL e o secret são lidos na hora do envio: chave revogada para de avisar (as pendentes são canceladas); um secret novo já assina as tentativas que ainda não saíram e tira a chave da pausa: elas voltam a sair na próxima rodada (em até ~1 min).

O secret do webhook

  • Ao criar a chave com Webhook URL, deixe o Webhook Secret em branco (a LOJEXA gera um forte, whsec_…) ou escreva o seu (de 16 a 64 caracteres, sem espaço). Nos dois casos ele aparece uma vez, logo depois de criar, junto da chave. Guarde no ambiente do servidor (ex.: LOJEXA_WEBHOOK_SECRET).
  • Perdeu ou vazou? Em /configuracoes/api-keys (Canais → Chaves de API), no cartão da chave, o botão Nova senha dos avisos (Novo secret) gera outro (aparece uma vez). O anterior para de valer na hora: troque no seu servidor logo em seguida (os avisos recusados nesse meio-tempo voltam pela espera de cada um). A chave de API não muda.
  • Para trocar a URL, crie uma chave nova e revogue a antiga (chave não se edita).

Verificar a assinatura

Sempre com o corpo cru, exatamente como chegou (antes de decodificar o JSON), e comparação de tempo constante. O receptor completo — assinatura, janela de 300 s, deduplicação pelo event_id e o 2xx rápido —, testado em Python, Node.js e PHP, e um simulador de aviso assinado em cURL estão no passo 9 do guia.

PHP
<?php
$secret    = (string) getenv('LOJEXA_WEBHOOK_SECRET');
if ($secret === '') {                                           // sem o secret, qualquer um assina: recuse tudo
    http_response_code(500);
    exit;
}
$corpo     = file_get_contents('php://input');                 // o corpo CRU, antes de decodificar
$timestamp = $_SERVER['HTTP_X_LOJEXA_TIMESTAMP'] ?? '';
$esperado  = 'sha256=' . hash_hmac('sha256', $timestamp . '.' . $corpo, $secret);
if (!ctype_digit($timestamp) || !hash_equals($esperado, $_SERVER['HTTP_X_LOJEXA_SIGNATURE_V2'] ?? '')) {
    http_response_code(401);
    exit;
}
if (abs(time() - (int) $timestamp) > 300) {
    http_response_code(400);                                     // velho demais: pode ser repetição
    exit;
}
$evento = json_decode($corpo, true);
if (ja_processado($evento['event_id'])) {                       // deduplique pelo event_id
    http_response_code(200);
    exit;
}
http_response_code(200);                                         // responda já; processe numa fila
// enfileirar($evento['event'], $evento['data']);
Python (Flask)
import hashlib, hmac, os, time
from flask import Flask, abort, request

app = Flask(__name__)
SECRET = os.environ['LOJEXA_WEBHOOK_SECRET'].encode()

@app.post('/webhooks/lojexa')
def lojexa():
    corpo = request.get_data()  # o corpo CRU
    ts = request.headers.get('X-Lojexa-Timestamp', '')
    esperado = 'sha256=' + hmac.new(SECRET, ts.encode() + b'.' + corpo, hashlib.sha256).hexdigest()
    if not ts.isdigit() or not hmac.compare_digest(esperado, request.headers.get('X-Lojexa-Signature-V2', '')):
        abort(401)
    if abs(time.time() - int(ts)) > 300:
        abort(400)
    evento = request.get_json()
    # if ja_processado(evento['event_id']): return '', 200   (deduplique)
    # enfileirar(evento['event'], evento['data'])
    return '', 200
Node.js (Express)
import crypto from 'node:crypto';
import express from 'express';

const app = express();
app.post('/webhooks/lojexa', express.raw({ type: 'application/json' }), (req, res) => {
  const ts = req.get('X-Lojexa-Timestamp') ?? '';
  const esperado = Buffer.from('sha256=' + crypto.createHmac('sha256', process.env.LOJEXA_WEBHOOK_SECRET)
    .update(ts + '.').update(req.body).digest('hex'));
  const recebido = Buffer.from(req.get('X-Lojexa-Signature-V2') ?? '');
  if (!/^\d+$/.test(ts) || recebido.length !== esperado.length || !crypto.timingSafeEqual(recebido, esperado)) return res.sendStatus(401);
  if (Math.abs(Date.now() / 1000 - Number(ts)) > 300) return res.sendStatus(400);
  const evento = JSON.parse(req.body);
  // if (await jaProcessado(evento.event_id)) return res.sendStatus(200);   (deduplique)
  res.sendStatus(200); // responda já; processe numa fila
});

Boas práticas

  • Antes de ligar em produção: o checklist do guia.
  • Uma chave por integração, com o mínimo de escopos. Um programa que só lê pedidos usa uma chave só com read:orders; um site que só mostra estoque, só com read:products.
  • Chave no ambiente do servidor, nunca no código-fonte, no Git, no navegador ou em app distribuído. Vazou? Revogue em /configuracoes/api-keys e crie outra.
  • Decida pelo error.code, não pela mensagem. Guarde o X-Request-Id de toda chamada que falhar: é o que o suporte precisa.
  • Timeout de 30 s e backoff exponencial com jitter em 429, 5xx, 409 STOCK_RACE_CONDITION e queda de rede. Leitura, venda (mesma reference), estorno (mesma reversal_reference) e ajuste (mesma Idempotency-Key) podem ser repetidos; ajuste sem Idempotency-Key, nunca.
  • Feeds em vez de varrer o catálogo: /estoque/mudancas e /produtos?updated_since com o cursor guardado, mais uma reconciliação por dia (guia).
  • Confira o estoque antes de vender (stock.available) e use o id do pedido do seu sistema como reference.

Changelog

VersãoDataMudanças
v1.4 2026-10-24 A venda confere e baixa no mesmo armazém da leitura — o stock.available de GET /produtos é o que POST /vendas aceita. Pode exigir ajuste na sua integração:
  • Sem warehouse, a venda sai do armazém padrão (antes: conferia a soma dos armazéns e baixava o de origem do SKU).
  • Kit vende pelas peças (antes: 409 STOCK_RACE_CONDITION); o contador antigo do cadastro não veta mais a venda (vira espelho do saldo). 409 STOCK_RACE_CONDITION fica só para a corrida de verdade e passa repetindo.
  • Falta de estoque: 422 INSUFFICIENT_STOCK com o disponível de cada SKU em error.details.items.
  • A reference diferencia maiúsculas (A1b2 e a1B2 eram a mesma venda) e não aceita /. A mesma reference com outro pedido: 409 REFERENCE_CONFLICT (antes: 200 already_processed, escondendo a diferença).
  • O mesmo SKU em várias linhas é somado. channel, customer_name e customer_email acima do limite, e quantity não inteira (2.5, "3abc"), dão 422 (antes: 500, ou 2.5 virava 2).
  • items_processed[].stock_after passa a ser o disponível no armazém da venda (antes: o físico somado de todos os armazéns); o físico está em on_hand_after. A resposta e o replay trazem o estado completo da venda.
  • O cancelamento devolve só o que saiu do estoque (as vendas de teste que nunca baixaram não creditam nada). O cancelamento total de uma venda já cancelada responde 200 already_processed (antes: 409 INVALID_STATUS_FOR_CANCEL).
  • O envio aos canais da venda e do estorno vai pela fila e não segura mais a chamada; channels[].push diz o que aconteceu em cada loja.
Novidades: warehouse na venda e no item; GET /vendas/{reference}; cancelamento parcial (items + reversal_reference); POST /vendas/{reference}/devolver com condition sellable ou damaged; schemas Sale, SaleResponse, SaleReplay, SaleCancel no openapi.json, com exemplos reais.
O ajuste de estoque é idempotente e cai no armazém da leitura (POST /estoque/{sku}/ajuste). Pode exigir ajuste na sua integração:
  • Sem warehouse, o ajuste cai no armazém padrão (antes: no armazém de origem do SKU).
  • A saída não é mais gravada como "baixa por venda": reason_code (purchase, return, damage, loss, count, other) decide o movimento. Avaria fica no físico e sai do disponível.
  • Kit: 422 KIT_NOT_ADJUSTABLE (antes: aceito, gravando um saldo que o kit não usa).
  • O set igual ao físico não grava movimento nem reenvia às lojas: channels[].push sai unchanged.
  • reason vale até 255 caracteres (antes: de 101 a 255 dava 500 STOCK_ADJUST_FAILED) e só é obrigatório com reason_code other (ou sem reason_code em in/out).
  • stock_after passa a ser o disponível no armazém do ajuste (antes: o físico somado de todos os armazéns); a resposta traz before, after, delta, movement e channels.
  • O envio aos canais do ajuste vai pela fila e não segura mais a chamada.
Novidades do ajuste: cabeçalho Idempotency-Key (o mesmo ajuste de novo = 200 already_processed com o mesmo resultado; outro ajuste com a mesma chave = 409 IDEMPOTENCY_MISMATCH); "type": "set" (o físico contado) com expected_on_hand (409 STOCK_CHANGED); warehouse; POST /estoque/ajustes (lote de até 500, Idempotency-Key obrigatória, resultado por item); schemas StockAdjustRequest, StockAdjustment, StockBatch no openapi.json, com exemplos reais.
O webhook sai fora da sua chamada, com retentativa e id de evento (webhooks). Só se acrescentou: quem confere X-Lojexa-Signature continua funcionando.
  • O aviso não é mais enviado durante a sua chamada: é gravado junto com a venda/estorno e costuma sair em até ~1 minuto (antes: na hora, com 5 s de timeout segurando a resposta, e uma tentativa só).
  • Servidor fora do ar (timeout, conexão recusada, DNS, 3xx, 5xx, 408, 429): os avisos da chave entram em pausa crescente (1 min, 5 min, 15 min... até 8 h), uma tentativa por pausa; a primeira resposta 2xx libera os outros. Outro 4xx é recusa só daquele aviso (ele segue a própria espera); 3 recusas seguidas sem 2xx pausam a chave. Aviso com mais de 48 h sem entrega desiste. A ordem de chegada não é garantida: ordene por occurred_at.
  • Resposta que não é 2xx (ou timeout de 10 s) ganha nova tentativa: até 10 em ~24 h. Redirect não é seguido (3xx conta como falha) e o endereço é conferido a cada tentativa: IP de rede interna é recusado.
  • Cabeçalhos novos: X-Lojexa-Event-Id, X-Lojexa-Timestamp, X-Lojexa-Delivery-Attempt e X-Lojexa-Signature-V2 (HMAC de timestamp.corpo). Corpo: event_id e occurred_at a mais; timestamp segue Unix, agora o instante do evento (antes: o do envio).
  • sale.reversed ganha sale_id, reversal_id, kind, partial, reversal_reference, condition, status e items (antes: só reference e items_count); sale.confirmed ganha items[].warehouse.
  • O secret do webhook aparece uma vez, junto da chave, e "Novo secret" na tela gera outro (antes: o gerado nunca era mostrado). Secret escrito: de 16 a 64 caracteres.
O mapeamento não apaga mais o vínculo feito no painel (POST /mapeamentos). Pode exigir ajuste na sua integração:
  • Campo que não vem fica como está no vínculo que já existe (antes: reenviar {sku, platform, platform_sku} zerava a variação, o listing_sku e o anúncio). Novos campos: platform_sku_id e listing_sku.
  • Plataformas: as do envio de estoque (shopee, mercadolivre, magalu, nuvemshop, shopify, amazon, tiktok, shein, temu). TikTok, Magalu, Nuvemshop, Temu e Shopify eram recusados; api, fisica e outro foram removidos (422 INVALID_PLATFORM): nada no sistema lia esse vínculo.
  • store_id obrigatório em Shopee, Mercado Livre, TikTok, SHEIN, Magalu e Nuvemshop (422 MISSING_STORE; antes: SHEIN sem loja, vínculo morto) e aceita o shop_id da Shopee (antes: 404).
  • O anúncio já ligado a outro SKU: 409 MAPPING_CONFLICT com o dono em error.details (antes: 500). O mesmo anúncio e variação com outro platform_sku atualiza o vínculo dele, como no painel.
  • O vínculo gravado envia o estoque do SKU às lojas pela fila (channels[].push; antes: esperava a varredura). A resposta traz o vínculo como ficou, created e channels; GET /mapeamentos ganha platform_sku_id (como texto de dígitos: o id do TikTok tem 19 dígitos), listing_sku e store_name.
Documentação e openapi:
  • Guia ponta a ponta em 11 passos, com cURL, Python, Node.js e PHP em cada um; o código e a saída de cada passo rodam contra a API num teste automático.
  • Em cada endpoint: a tabela de parâmetros (gerada do openapi.json), a requisição e a resposta reais e a tabela dos erros dele, com o que fazer. Os exemplos dos pedidos (GET /orders, o detalhe, as reservas e o 404) passaram a ser respostas reais.
  • openapi.json: x-error-codes em cada operação (e x-item-error-codes no lote), exemplo em todo parâmetro, o corpo real de cada escrita em requestBody.examples, o schema da resposta de DELETE /mapeamentos/{id} e exemplos reais nas respostas dos pedidos.
  • A mensagem do 404 ORDER_NOT_FOUND ganhou o acento ("Pedido não encontrado."). Decida pelo code: a mensagem é para pessoas.
v1.3 2026-10-23 Pode exigir ajuste na sua integração:
  • Um número de estoque só. stock_available passa a ser o disponível do saldo por armazém, no armazém padrão (a conta que a venda confere antes de baixar), e não mais o contador antigo do cadastro — o número pode mudar (ex.: 5.000 → 4.999). Até a v1.4, a venda ainda recusava alguns SKUs que a leitura mostrava com estoque. stock_total e stock_reserved seguem o mesmo saldo (no kit, 0). Kit passa a mostrar quantos kits as peças montam (antes: 0).
  • Datas em ISO 8601 com fuso (2026-10-23T09:12:44-03:00) em vez de 2026-10-23 12:12:44: created_at do mapeamento, last_used_at e expires_at. O /uso conta o dia no horário de Brasília.
  • updated_at do produto ganha o fuso (2026-10-23 12:12:44 → 2026-10-23T12:12:44-03:00, o mesmo valor). Ele está no relógio do feed do catálogo (o de updated_since, cursor e sync_horizon) e não é o instante exato: a gravação pelo contador antigo de estoque aparece até 3 h à frente. Não compare updated_at para decidir qual versão é a mais nova — aplique os itens do feed na ordem.
  • Parâmetro inválido dá 422 INVALID_PARAMETER em vez de ser corrigido sem aviso: per_page=200, page=0, include_variations=talvez e search longo agora falham; limit na lista paginada também.
  • SKU inativo é achado: o detalhe, ?sku= e ?skus= devolvem 200 com "status": "inactive" e available 0 (antes, 404 ou not_found).
  • source_product_id e source_variation_id passam a vir do mesmo vínculo Shopee (o valor pode mudar).
  • Toda resposta de /api/ é JSON, inclusive 404 ROUTE_NOT_FOUND, 405 METHOD_NOT_ALLOWED (com Allow) e 500 INTERNAL_ERROR; corpo de POST quebrado dá 400 INVALID_JSON em todo endpoint.
  • error.request_id em todo erro (o mesmo do cabeçalho X-Request-Id).
Novidades:
  • Objeto stock (armazém, by_warehouse, all_warehouses, kit pelas peças), status, updated_at e channels (envio de estoque de cada loja, só informa) em /produtos; warehouse e fields=stock.
  • GET /produtos?sku= (SKU com /) e ?skus=A,B,C (até 100, com meta.not_found); SKU codificado no caminho (espaço, acento, parênteses); maiúsculas e minúsculas não importam.
  • Feeds por cursor: GET /estoque/mudancas, GET /estoque/movimentos e o feed do catálogo GET /produtos?updated_since=; e GET /armazens, GET /lojas (todos read:products). 422 WAREHOUSE_NOT_FOUND.
  • Cabeçalhos X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset e Retry-After; recusa de chave ou de escopo não gasta cota; o X-Request-Id que você manda volta igual.
  • Bearer em qualquer caixa; 403 COMPANY_SUSPENDED; nenhuma resposta da API traz cookie; a chave expira no fim do dia escolhido.
  • Ordem estável em /produtos e /mapeamentos (desempate por id).
  • openapi.json 1.3: esquema X-Api-Key, x-required-scope por operação, respostas de erro reutilizáveis e schemas com exemplos reais (Product, Stock, StockChange, Mapping, Usage…).
Documentação corrigida (o código não mudou; a página dizia outra coisa): category nunca filtrou (agora marcado obsoleto); o envio aos canais roda durante a chamada, não "em segundo plano"; o replay da venda é 200 already_processed, não 409 ALREADY_PROCESSED; channel tem padrão api; unit_price é opcional; o SKU que não existe dá PRODUCT_NOT_FOUND (a página citava um código que a API nunca devolveu); o corpo do webhook traz timestamp Unix e items; não existe category_name nem meta.page; a API não é instantânea (atraso de até ~2 min nos feeds).
v1.2 2026-10-23 Leitura de pedidos (escopo read:orders, somente leitura):
GET /orders — pedidos dos marketplaces e próprios, com sincronização por cursor • GET /orders/{id} — detalhe com o motivo da falta de estoque • GET /orders/{id}/stock-reservations • Comprador sempre mascarado • Criar chave exige ao menos um escopo • API em todos os planos, inclusive o Gratuito
v1.1 2026-05-08 GET /uso — estatísticas de uso da chave • GET /openapi.json — especificação OpenAPI 3.0 • Webhooks sale.confirmed e sale.reversed • Campos webhook_url e webhook_secret nas chaves
v1.0 2026-05 Lançamento da API pública: GET /ping • GET /produtos • GET /produtos/{sku} • POST /vendas • POST /vendas/{ref}/cancelar