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 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).
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
- Só o administrador da conta cria chaves (subconta não tem acesso à tela).
- 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. - 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). - 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… | Escopo | Endpoints |
|---|---|---|
| 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 |
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 /vendasbaixa 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 doavailable(entra emstock.reserved). O da Shopee costuma entrar sem essa reserva: fica no contador antigo do produto, e ostock.availabledeGET /produtos— e o quePOST /vendasaceita — 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 reservaactiveemGET /orders/{id}/stock-reservationsjá está fora doavailable. 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 emGET /orders, escoporead:orders), ou use uma margem fixa. Exceção: no SKU de cadastro antigo (sem saldo por armazém) o contador antigo já entra emstock.reserved— não desconte nada. (O Estoque mínimo da ficha do produto só entra noavailabledo 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_enabledemchannelse emGET /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:
Authorization: Bearer lj_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
X-Api-Key: lj_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
Bearervale em qualquer caixa (bearer,BEARER).- A API não usa cookie nem sessão: nenhuma resposta de
/api/v1trazSet-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 recusas401e403nã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 -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_SCOPEe403 COMPANY_SUSPENDEDnão gastam cota. - Quanto custa sincronizar 1.000 SKUs: a carga inicial com
per_page=100são 10 chamadas; conferir 1.000 SKUs por?skus=são 10 chamadas (100 por vez); depois, uma chamada a/estoque/mudancasa cada 1 a 5 minutos traz até 500 SKUs alterados.
Toda resposta contada traz os cabeçalhos:
| Cabeçalho | O que é |
|---|---|
X-RateLimit-Limit | Chamadas permitidas por minuto para esta chave |
X-RateLimit-Remaining | Quantas ainda cabem neste minuto |
X-RateLimit-Reset | Instante Unix (segundos) em que o minuto vira e a cota zera |
Retry-After | No 429 e no 409 BATCH_IN_PROGRESS (o lote de ajustes ainda gravando): segundos até poder repetir |
X-Request-Id | Em 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).
{
"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": …}.metasó existe onde está na tabela abaixo. Nas escritas (vendas, estornos e ajustes),"already_processed"vem no topo, ao lado desuccess—true= a mesma chamada já tinha sido feita e nada foi gravado de novo. - Erro:
{"success": false, "error": {"code", "message", "request_id", "details"}}. Decida pelocode(a tabela de erros); amessageé para pessoas e pode mudar.detailssó 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;nullquando 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 entreA-Z a-z 0-9 . _ : -), ele volta igual — útil para casar o seu log com o do suporte.
| Endpoint | meta |
|---|---|
GET /produtos (lista), GET /mapeamentos | current_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, /orders | limit, count, has_more, next_cursor, sync_horizon (e status no catálogo, warehouse em /estoque/mudancas) |
GET /armazens | default_warehouse_id |
GET /ping, /uso, /produtos/{sku}, /lojas, /orders/{id} | sem meta |
{
"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.
| HTTP | Código | Quando acontece | Repetir? | 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
{
"success": false,
"error": {
"code": "MISSING_API_KEY",
"message": "API key ausente. Envie via Authorization: Bearer <key> ou X-Api-Key: <key>.",
"request_id": "8f14e45fceea167a5a36dedd4bea2543"
}
}
{
"success": false,
"error": {
"code": "INSUFFICIENT_SCOPE",
"message": "Scope obrigatório ausente: read:products.",
"request_id": "8f14e45fceea167a5a36dedd4bea2543"
}
}
{
"success": false,
"error": {
"code": "INVALID_PARAMETER",
"message": "per_page deve ser um inteiro de 1 a 100.",
"request_id": "8f14e45fceea167a5a36dedd4bea2543"
}
}
{
"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"
}
}
{
"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.
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.mjsoulojexa.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 scriptbashcom 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 compython -X utf8, inclusive no Agendador de Tarefas: com a saída indo para um arquivo ou log, oprintde 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
- 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:stockeread:orders(veja qual escopo para qual caso).manage:mappingssó se for vincular anúncios pela API. - Limite por minuto: 30, 60, 120, 300 (padrão 60). 60 dá folga para este guia inteiro com milhares de SKUs.
- 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. - A chave (
lj_live_…) e o secret aparecem UMA vez, logo depois de criar. Copie e guarde no ambiente do servidor:LOJEXA_API_KEYeLOJEXA_WEBHOOK_SECRET(noEnvironment=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. - Salve o cliente abaixo ao lado dos outros passos. Ele lê
LOJEXA_API_KEYe, se existir,LOJEXA_API_BASE(padrãohttps://lojexa.com/api/v1; em produção, não defina).
O que o cliente faz em cada resposta:
| Resposta | O cliente |
|---|---|
200 / 201 | Devolve o JSON ({"success": true, "data": …}). |
429 RATE_LIMIT_EXCEEDED | Espera os segundos de Retry-After (mais um aleatório) e repete a mesma chamada. |
409 STOCK_RACE_CONDITION / 409 BATCH_IN_PROGRESS | Nada foi gravado: espera (2 s, 4 s, 8 s… com jitter, até 60 s) e repete igual. |
5xx, timeout (30 s) ou queda de rede | Repete 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 4xx | Lanç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.
# 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"
"""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)
// 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);
}
}
<?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.
# 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
"""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')
// 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
// 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;
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
- Pegue os dois cursores ANTES da carga:
GET /estoque/mudancas?updated_since=<agora>eGET /produtos?updated_since=<agora>&fields=stock. Eles vêm vazios, commeta.next_cursor2 minutos atrás: o que mudar durante a carga entra no passo 4, nada se perde. - Leia todas as páginas de
GET /produtos?fields=stock&status=all&per_page=100, depage=1atémeta.last_page.fields=stockdeixa a resposta leve (sem catálogo nem imagens);status=alltraz os inativos (comavailable0) para você saber que saíram. - Grave pelo
sku_master_id: osku_codepode 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. - Reescreva o seu cadastro inteiro com o que veio: o SKU que não veio foi apagado ou renomeado.
- 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).
# 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"
"""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')
// 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
// 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;
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=500traz 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 comGET /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_cursornovo — 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.
# 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
"""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})
// 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
// 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);
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 responde200com"already_processed": truee não baixa duas vezes. Por isso, no timeout, no5xxou no409 STOCK_RACE_CONDITION, repita igual (o cliente faz isso) — ou pergunte comGET /vendas/{reference}.422 INSUFFICIENT_STOCK: nada foi baixado.error.details.itemstraz, por SKU, oavailabledo 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: essareferencejá é de outra venda (outros itens). Não repita: é defeito da integração ou outro pedido com o mesmo id.channels[].pushdiz, 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.
# 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"
"""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')
// 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
// 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;
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; comitems, só aqueles. - Voltou depois da entrega:
POST /vendas/{reference}/devolver, comcondition:sellable(volta a vender) oudamaged(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": truee não estorna duas vezes. - Volta ao estoque só o que saiu por esta venda, no armazém de onde saiu; o
statusda venda vai apartially_reversede, quando tudo voltou, areversed.
# 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"
"""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')
// 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
// 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');
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}/ajustecomtype:in(entrada),out(saída, até o disponível) ouset(o físico contado). Oreason_codediz o que aconteceu:purchase(compra),return,damage(avaria),loss(perda),count(contagem) ouother(comreason).- Sempre com
Idempotency-Key, montada do seu documento e dosku_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:
setcom o que você contou eexpected_on_handcom o físico que a LOJEXA mostrava quando a contagem começou: se alguém vendeu ou mexeu no meio,409 STOCK_CHANGEDe nada é gravado — conte de novo. - Lote:
POST /estoque/ajustes, até 500 itens,Idempotency-Keyobrigató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, oBONE-PRETOestáinactivena carga do passo 3.
# 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)
"""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']}")
// 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
// 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;
}
}
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 ocursorguardado. Grave peloid(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 antigoPOST /orders(api). Ochannelsai sempre normalizado: minúsculo, sem espaço,_nem-. A venda dePOST /vendasnã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 antigoPOST /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.
# 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"
"""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']}
// 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
// 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']);
198734 shopee READY_TO_SHIP 2026-10-25T23:59:59-03:00
9. Receber os webhooks
- Eventos:
sale.confirmed(venda registrada por esta chave) esale.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 (Pythonhmac.compare_digest, Nodecrypto.timingSafeEqual, PHPhash_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
2xxem 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.
# 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"
"""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()
// 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)
<?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
{"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
| Resposta | O que quer dizer | O que fazer |
|---|---|---|
400, 404, 422 | A 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, 403 | Chave ausente, errada, revogada, expirada, sem o escopo ou empresa suspensa | Pare e corrija a chave (crie outra no painel). Não gasta cota |
409 | Conflito: STOCK_RACE_CONDITION e BATCH_IN_PROGRESS passam repetindo; REFERENCE_CONFLICT, IDEMPOTENCY_MISMATCH, STOCK_CHANGED e MAPPING_CONFLICT não | Repita só os dois primeiros, com backoff; os outros pedem outra chave, outra reference ou uma nova contagem |
429 | Passou do limite do minuto | Espere Retry-After e repita. Para não chegar lá, olhe X-RateLimit-Remaining |
5xx, timeout, rede | Falha do servidor ou do caminho | Repita 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 pelamessage(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-Idde toda chamada que falhou (vem no cabeçalho e emerror.request_id): é o que o suporte precisa para achar a chamada. - Limite:
X-RateLimit-Limit,X-RateLimit-RemainingeX-RateLimit-Resetvê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).
# 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"
"""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}')
// 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
// 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;
}
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 dois409retentáveis; venda com a mesmareference; estorno com a mesmareversal_reference; ajuste sempre comIdempotency-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 oavailable) e consulteGET /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,2xxrápido, e o feed como fonte da verdade. - Log: guarde, de cada falha, o método, o caminho, o status, o
error.codee oX-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-azulachaCAMISETA-M-AZUL. - No caminho, codifique o SKU: JavaScript
encodeURIComponent(sku), Pythonurllib.parse.quote(sku, safe=""), PHPrawurlencode($sku). Ex.:007-Preto-G1 (48 ao 52)vira007-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): useGET /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 emmeta.not_found. SKU com vírgula vai por?sku=.
curl -H "Authorization: Bearer $LOJEXA_API_KEY" \
"https://lojexa.com/api/v1/produtos/007-Preto-G1%20(48%20ao%2052)?fields=stock"
{
"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.
| Campo | O que é |
|---|---|
stock.available / stock_available | on_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.warehouse | O armazém dos números do topo: o padrão da empresa, ou o de warehouse= |
stock.on_hand | Físico no armazém |
stock.reserved | Reservado no armazém para pedidos ainda não enviados (hoje, o pedido da Shopee costuma entrar sem essa reserva: veja) |
stock.damaged | Avariado: está no armazém mas não vende |
stock.allocated_mobile | Alocado para o app offline da LOJEXA (fica reservado para o aparelho) |
stock.safety_stock | Estoque 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_warehouses | A soma de todos os armazéns |
stock.is_kit / stock.kit_components[] | Kit: veja abaixo |
stock_total / stock_reserved | Legado, 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[].stock | Estoque do anúncio na Shopee (a última leitura do canal), não o da LOJEXA |
available_before / available_after | Em /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 /armazenslista 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, campowarehouse;null= o padrão). Se a sua integração vende de outro armazém, passewarehouse. - 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.warehousevemnull,by_warehousevem vazio e o número está emstock.availablee emall_warehouses. - Trocar o armazém padrão, ou ativar e desativar um armazém, muda o topo de
stockde 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 emstock.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).
{
"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:
- O SKU está vinculado ao anúncio, com a loja. Confira em
channelsdo SKU ou emGET /mapeamentos?sku=(store_idpreenchido). - 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. - Confira pela API:
stock_push_enabled: truena loja, emGET /lojase emchannelsde cada SKU. - O armazém de onde a loja vende tem o saldo (
GET /lojas→warehouse, estock.by_warehousedo 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
Confere a chave e devolve a empresa e os escopos.
curl -sS --max-time 30 \
-H "Authorization: Bearer $LOJEXA_API_KEY" \
"https://lojexa.com/api/v1/ping"
{
"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
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_monthsã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 -sS --max-time 30 \
-H "Authorization: Bearer $LOJEXA_API_KEY" \
"https://lojexa.com/api/v1/uso"
{
"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
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).
| Nome | Onde | Tipo | Obrig. | Padrão | Limites | Exemplo |
|---|---|---|---|---|---|---|
page | query | inteiro | Não | 1 | 1 a 1.000.000 | 1 |
| Só na lista paginada | ||||||
per_page | query | inteiro | Não | 50 | 1 a 100 | 100 |
| Só na lista paginada | ||||||
search | query | texto | Não | — | até 100 caracteres | camiseta |
| Trecho do nome ou do SKU (só na lista paginada) | ||||||
sku | query | texto | Não | — | até 100 caracteres | CAMISETA-M-AZUL |
| UM SKU exato, inclusive com "/" ou ",". Vem com variations, como o detalhe. | ||||||
skus | query | texto | Não | — | — | CAMISETA-M-AZUL,BONE-PRETO |
| Até 100 SKUs exatos separados por vírgula. | ||||||
include_variations | query | booleano | Não | false | — | true |
| true/false ou 1/0: inclui todas as variações do anúncio. | ||||||
category obsoleto | query | texto | Não | — | — | — |
| OBSOLETO: aceito e ignorado (nunca filtrou nada). | ||||||
status | query | texto | Não | — | um de: active, inactive, all | all |
| Padrão active na listagem; all no feed (updated_since/cursor) e na consulta por sku/skus. SKU inativo vem com available 0. | ||||||
warehouse | query | texto | Nã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. | ||||||
fields | query | texto | Não | — | um de: stock | stock |
| stock = só identificação, status, estoque e canais (sem catálogo nem imagens). | ||||||
updated_since | query | texto | Nã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. | ||||||
cursor | query | texto | Não | — | até 200 caracteres | eyJ1IjoiMjAyNi0xMC0yMyAxNDo1ODowMCIsImkiOjkyMjMzNzIwMzY4NTQ3NzU4MDd9 |
| 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. | ||||||
limit | query | inteiro | Não | 50 | 1 a 100 | 100 |
| Só no feed (com updated_since/cursor). | ||||||
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
| HTTP | Código | Quando acontece | O que fazer |
|---|---|---|---|
| 422 | INVALID_PARAMETER | Parâ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. |
| 422 | INVALID_CURSOR | O cursor foi alterado, cortado ou veio de outro endpoint. | Repasse meta.next_cursor exatamente como veio. Para recomeçar, use updated_since. |
| 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. | 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
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:
200com"status": "inactive"eavailable0 (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.
| Nome | Onde | Tipo | Obrig. | Padrão | Limites | Exemplo |
|---|---|---|---|---|---|---|
sku | caminho | texto | Sim | — | até 100 caracteres | 007-Preto-G1 (48 ao 52) |
| O SKU codificado (ex.: 007-Preto-G1%20(48%20ao%2052)) | ||||||
warehouse | query | texto | Nã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. | ||||||
fields | query | texto | Não | — | um de: stock | stock |
| stock = só identificação, status, estoque e canais (sem catálogo nem imagens). | ||||||
curl -sS --max-time 30 \
-H "Authorization: Bearer $LOJEXA_API_KEY" \
"https://lojexa.com/api/v1/produtos/CAMISETA-M-AZUL"
{
"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
| HTTP | Código | Quando acontece | O que fazer |
|---|---|---|---|
| 400 | INVALID_SKU | O SKU do caminho está vazio ou, decodificado, não é texto UTF-8. | Codifique o SKU (JavaScript encodeURIComponent, Python quote(sku, safe=""), PHP rawurlencode). |
| 422 | INVALID_PARAMETER | Parâ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. |
| 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. | 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 | 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). | 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)
?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 -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"
{
"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)
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_cursoraponta 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_atestá no relógio deste feed (o mesmo deupdated_since,cursoresync_horizon) e não é o instante exato — a gravação pelo contador antigo aparece até 3 h à frente. Não useupdated_atpara 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 mesmosku_master_idcom osku_codenovo — o código antigo não vem como inativo.
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"
{
"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)
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.
| Nome | Onde | Tipo | Obrig. | Padrão | Limites | Exemplo |
|---|---|---|---|---|---|---|
limit | query | inteiro | Não | 100 | 1 a 500 | 500 |
| Itens por página. Com has_more true, chame de novo na hora com o next_cursor. | ||||||
cursor | query | texto | Não | — | até 200 caracteres | eyJ1IjoiMjAyNi0xMC0yMyAxNDo1ODowMCIsImkiOjkyMjMzNzIwMzY4NTQ3NzU4MDd9 |
| Opaco: copie meta.next_cursor. Não vem junto com updated_since. | ||||||
updated_since | query | texto | Não | — | — | 2026-10-23T00:00:00-03:00 |
| ISO 8601, inclusivo. Só na primeira chamada. | ||||||
warehouse | query | texto | Nã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. | ||||||
GET /produtos?fields=stock&status=all (veja o guia).
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"
{
"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
| HTTP | Código | Quando acontece | O que fazer |
|---|---|---|---|
| 422 | INVALID_PARAMETER | Parâ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. |
| 422 | INVALID_CURSOR | O cursor foi alterado, cortado ou veio de outro endpoint. | Repasse meta.next_cursor exatamente como veio. Para recomeçar, use updated_since. |
| 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. | 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)
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) ouapi_stock_adjust(ajuste e lote), esource.id= areferenceda venda ou oadjustment_iddo ajuste. Concilie porsource, não porkind: a venda pela API sai comobaixae o cancelamento comodevolucao(o estoque volta), o mesmokinddos movimentos do painel. - Avaria:
qty_deltaconta a peça avariada (+1= uma peça a mais separada como avariada), não o disponível (que cai 1 numa avaria: confira emGET /produtos/{sku}). Não someqty_deltade avaria com o das vendas.
| Nome | Onde | Tipo | Obrig. | Padrão | Limites | Exemplo |
|---|---|---|---|---|---|---|
sku | query | texto | Não | — | até 100 caracteres | CAMISETA-M-AZUL |
| Só os movimentos deste SKU (maiúsculas e minúsculas não importam; aceita "/"). Inexistente: 404 PRODUCT_NOT_FOUND. | ||||||
limit | query | inteiro | Não | 100 | 1 a 500 | 500 |
| Itens por página. Com has_more true, chame de novo na hora com o next_cursor. | ||||||
cursor | query | texto | Não | — | até 200 caracteres | eyJ1IjoiMjAyNi0xMC0yMyAxNDo1ODowMCIsImkiOjkyMjMzNzIwMzY4NTQ3NzU4MDd9 |
| Opaco: copie meta.next_cursor. Não vem junto com updated_since. | ||||||
updated_since | query | texto | Não | — | — | 2026-10-23T00:00:00-03:00 |
| ISO 8601, inclusivo. Só na primeira chamada. | ||||||
warehouse | query | texto | Nã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. | ||||||
kind | kind_label |
|---|---|
entrada | Entrada |
saida | Saída |
reserva | Reserva |
liberacao | Liberação |
baixa | Baixa por envio |
ajuste | Ajuste |
transferencia | Transferência |
devolucao | Devolução |
cancelamento | Cancelamento |
contagem | Contagem |
avaria | Avaria |
outro | Outro |
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"
{
"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
| HTTP | Código | Quando acontece | O que fazer |
|---|---|---|---|
| 422 | INVALID_PARAMETER | Parâ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. |
| 422 | INVALID_CURSOR | O cursor foi alterado, cortado ou veio de outro endpoint. | Repasse meta.next_cursor exatamente como veio. Para recomeçar, use updated_since. |
| 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. | 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 | 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). | 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
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 -sS --max-time 30 \
-H "Authorization: Bearer $LOJEXA_API_KEY" \
"https://lojexa.com/api/v1/armazens"
{
"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
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 -sS --max-time 30 \
-H "Authorization: Bearer $LOJEXA_API_KEY" \
"https://lojexa.com/api/v1/lojas"
{
"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)
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).
| Nome | Onde | Tipo | Obrig. | Padrão | Limites | Exemplo |
|---|---|---|---|---|---|---|
platform | query | texto | Não | — | até 50 caracteres | shopee |
| Filtra pela plataforma exata (shopee, mercadolivre, magalu, nuvemshop, shopify, amazon, tiktok, shein, temu) | ||||||
sku | query | texto | Não | — | até 100 caracteres | CAMISETA-M-AZUL |
| Só os vínculos deste SKU (maiúsculas e minúsculas não importam) | ||||||
page | query | inteiro | Não | 1 | 1 a 1.000.000 | 1 |
| A página, de 1 até meta.last_page. | ||||||
per_page | query | inteiro | Não | 50 | 1 a 100 | 100 |
| Vínculos por página. | ||||||
curl -sS --max-time 30 \
-H "Authorization: Bearer $LOJEXA_API_KEY" \
"https://lojexa.com/api/v1/mapeamentos?sku=CAMISETA-M-AZUL"
{
"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
| HTTP | Código | Quando acontece | O que fazer |
|---|---|---|---|
| 422 | INVALID_PARAMETER | Parâ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
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 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)
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_atcrescente e, no empate,idcrescente. - Horizonte: só entram pedidos com
updated_ataté 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 emGET /orders/{id}. - Paginação: por
cursor. Os parâmetrospageeper_pagesão recusados com422 INVALID_PARAMETER. - O cursor sempre anda: sem mais páginas (
has_more=false),next_cursoraponta 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 delimitpedidos, até vazia, ehas_more=true: continue chamando com o cursor.
Parâmetros (todos opcionais)
| Nome | Onde | Tipo | Obrig. | Padrão | Limites | Exemplo |
|---|---|---|---|---|---|---|
limit | query | inteiro | Não | 50 | 1 a 100 | 100 |
| Pedidos por página. | ||||||
cursor | query | texto | Não | — | até 200 caracteres | eyJ1IjoiMjAyNi0xMC0yMyAxNDo1ODowMCIsImkiOjkyMjMzNzIwMzY4NTQ3NzU4MDd9 |
| Opaco: copie meta.next_cursor e repita os mesmos filtros. Não pode vir junto com updated_since. | ||||||
updated_since | query | texto | Não | — | — | 2026-10-23T00:00:00-03:00 |
| ISO 8601, inclusivo. Só na primeira chamada (codifique o "+" do fuso como %2B). | ||||||
status | query | texto | Não | — | — | READY_TO_SHIP,SHIPPED |
| Status do canal, separados por vírgula (até 20). | ||||||
lojexa_status | query | texto | Não | — | — | paid,packed |
| Status do fluxo LOJEXA, separados por vírgula (até 20). | ||||||
channel | query | texto | Não | — | — | shopee |
| shopee, mercadolivre, tiktok, shein, magalu, temu, nuvemshop, manual, api... Aceita os apelidos ml e tiktok_shop. | ||||||
store_id | query | inteiro | Não | — | ≥ 1 | 3 |
| ID da loja na LOJEXA (store.id). Exige channel. | ||||||
created_from | query | texto | Não | — | — | 2026-10-01 |
| Criados a partir de (data ou data e hora ISO 8601). | ||||||
created_to | query | texto | Não | — | — | 2026-10-23 |
| Criados até (inclusivo; só data = o dia inteiro). | ||||||
paid_from | query | texto | Não | — | — | 2026-10-01 |
| Pagos a partir de (data ou data e hora ISO 8601). | ||||||
paid_to | query | texto | Não | — | — | 2026-10-23 |
| Pagos até (inclusivo; só data = o dia inteiro). | ||||||
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"
{
"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
| HTTP | Código | Quando acontece | O que fazer |
|---|---|---|---|
| 422 | INVALID_PARAMETER | Parâ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. |
| 422 | INVALID_CURSOR | O 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
| Campo | Regra |
|---|---|
| datas | ISO 8601 com o fuso -03:00; null quando o pedido não tem a data |
created_at | Data 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_id | Número do pedido no canal (external_order_id; se faltar, order_sn) |
store.id | ID da loja na LOJEXA — é o valor do filtro store_id |
status.channel / status.lojexa | Status 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.total | Total informado pelo canal; items_subtotal = soma de quantidade × preço dos itens |
amounts.shipping_fee / amounts.discount | Valor 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 |
fees | Taxas 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_sku | SKU do estoque LOJEXA; null quando o item não está vinculado. original_price zero vira null |
shipping | carrier = transportadora (ou provedor logistico); tracking_code = código de rastreio |
invoice | A ú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 |
buyer | Sempre mascarado; cidade e UF em claro. Telefone, e-mail, endereço e CPF/CNPJ nunca saem — não existe escopo que os revele |
id) está em Sincronizar pedidos.
Detalhe do pedido
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 -sS --max-time 30 \
-H "Authorization: Bearer $LOJEXA_API_KEY" \
"https://lojexa.com/api/v1/orders/198734"
{
"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
}
}
{
"success": false,
"error": {
"code": "ORDER_NOT_FOUND",
"message": "Pedido não encontrado.",
"request_id": "8f14e45fceea167a5a36dedd4bea2543"
}
}
Erros deste endpoint
| HTTP | Código | Quando acontece | O que fazer |
|---|---|---|---|
| 404 | ORDER_NOT_FOUND | Pedido 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
As reservas do estoque da LOJEXA feitas para os itens do pedido. Pedido inexistente ou de outra empresa: 404 ORDER_NOT_FOUND.
curl -sS --max-time 30 \
-H "Authorization: Bearer $LOJEXA_API_KEY" \
"https://lojexa.com/api/v1/orders/198734/stock-reservations"
{
"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
| HTTP | Código | Quando acontece | O que fazer |
|---|---|---|---|
| 404 | ORDER_NOT_FOUND | Pedido 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.channel | O que significa |
|---|---|
UNPAIDAguardando pagamento | O comprador ainda não pagou. Não separe. |
READY_TO_SHIPPronto para envio | Pago: pronto para separar, emitir NF-e e enviar. |
PROCESSEDEm processamento | Envio já programado no canal (etiqueta gerada); falta postar ou a coleta passar. |
RETRY_SHIPReenvio pendente | O canal pediu um novo envio. |
READY_TO_PICKUPAguardando coleta | Aguardando a coleta da transportadora. |
SHIPPEDEnviado | Enviado ao comprador. |
TO_CONFIRM_RECEIVEAguardando confirmação | Entregue; o canal espera o comprador confirmar. |
DELIVEREDEntregue | Entregue. |
COMPLETEDConcluído | Concluído no canal (fim do pedido). |
IN_CANCELCancelamento solicitado | O comprador pediu o cancelamento: não envie até o canal decidir. |
CANCELLEDCancelado | Cancelado. |
INVOICE_PENDINGNF pendente | O canal espera a NF-e para liberar o envio. |
TO_RETURNEm devolução | Devolução em andamento. |
JUDGE_RETURN_REFUNDAvaliação de reembolso | O canal está avaliando um pedido de devolução ou reembolso. |
RETURNEDDevolvido | Devolvido. |
REFUNDEDReembolsado | Reembolsado ao comprador. |
VOIDEDAnulado | Anulado pelo canal. |
status.lojexa | O que significa |
|---|---|
awaiting_paymentAguardando pagamento | Aguardando o pagamento. |
pending_reservationAguardando reserva | Pago, esperando a reserva do estoque. |
reservedEstoque reservado | Estoque reservado para o pedido. |
paidPago | Pago e pronto para o fluxo (separar, NF-e, etiqueta). |
fiscal_pendingFiscal pendente | NF-e pendente. |
fiscal_authorizedFiscal autorizado | NF-e autorizada. |
pickingEm separacao | Em separação. |
packedEmbalado | Embalado. |
shippedEnviado | Enviado. |
deliveredEntregue | Entregue. |
cancelledCancelado | Cancelado. |
returnedDevolvido | Devolvido. |
stock_conflictConflito de estoque | Travado por falta de estoque (o motivo vem em stock_issue de GET /orders/{id}). |
product_mapping_requiredMapeamento 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.
- Chave: crie uma só com
read:productse guarde no ambiente do servidor (LOJEXA_API_KEY). - Teste:
GET /ping(empresa e escopos) eGET /uso(limite por minuto). - Pegue os cursores ANTES da carga:
GET /estoque/mudancas?updated_since=<agora>eGET /produtos?updated_since=<agora>&fields=stock. Vêm vazios, comnext_cursor2 minutos atrás: assim, o que mudar durante a carga entra no primeiro laço. - Carga inicial:
GET /produtos?fields=stock&status=all&per_page=100, depage=1atémeta.last_page. Grave, porsku_master_id, osku_code, ostock.availablee ostatus— o código do SKU pode ser trocado na ficha; o id não muda. - Laço de estoque, a cada 1 a 5 minutos:
GET /estoque/mudancas?cursor=…&limit=500. Grave cada SKU (upsert pelosku_master_id), na ordem em que chega, e guarde o novometa.next_cursor— ele sempre vem, mesmo com a página vazia. Comhas_more: true, chame de novo na hora. - Laço do catálogo: o mesmo com
GET /produtos?cursor=…&fields=stock: SKU novo, alterado e inativado ("status": "inactive",available0). A troca de código vem como o mesmosku_master_idcom osku_codenovo. Não descarte item peloupdated_at: ele não decide qual versão é a mais nova. - 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.
- Erros:
429→ espere oRetry-After;5xx, timeout ou queda de rede → repita a MESMA chamada (o mesmo cursor) com backoff;4xx→ pare e corrija (mande oX-Request-Idao 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, passewarehousenas 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.
# 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"
"""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
// 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
// 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):
- Primeira carga: chame
GET /orders?updated_since=...com a data a partir da qual quer os pedidos. - Guarde
meta.next_cursorde cada resposta (no banco ou num arquivo do seu programa). - Enquanto
has_morefortrue, chame de novo comcursor=<o cursor guardado>e os mesmos filtros. - Depois, a cada 1 a 5 minutos, chame de novo com o último cursor guardado. Resposta vazia é normal: guarde o
next_cursormesmo assim (ele avança até o horizonte). - 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. Oupdated_attambé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 emGET /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, useGET /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 enquantohas_morefortrue, 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
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
Registrar venda
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).
| Nome | Onde | Tipo | Obrig. | Padrão | Limites | Exemplo |
|---|---|---|---|---|---|---|
reference | corpo | texto | Sim | — | 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}. | ||||||
warehouse | corpo | id ou code | Nã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. | ||||||
items | corpo | lista | Sim | — | 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[].sku | corpo | texto | Sim | — | até 100 caracteres | CAMISETA-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[].quantity | corpo | inteiro | Sim | — | 1 a 1.000.000 | 1 |
| Inteiro: 3, 3.0 e "3" valem; 2.5 e "3abc" dão 422 INVALID_ITEM_QTY. No kit, quantos kits. | ||||||
items[].unit_price | corpo | número | Não | — | ≥ 0 | 49.9 |
| Opcional; fica guardado na venda, não muda o estoque | ||||||
items[].warehouse | corpo | id ou code | Não | — | — | SP |
| O armazém DESTE item (vale mais que o da venda). Sem ele, o da venda. | ||||||
channel | corpo | texto | Não | api | até 50 caracteres | site |
| Rótulo livre da origem da venda (ex.: site, loja-fisica). Até 50 caracteres; acima, 422 INVALID_FIELD. | ||||||
customer_name | corpo | texto | Não | — | até 100 caracteres | João Silva |
| Fica guardado na venda (não sai no webhook). Acima do limite: 422 INVALID_FIELD. | ||||||
customer_email | corpo | texto | Não | — | até 150 caracteres | joao@email.com |
| Fica guardado na venda. Precisa ter "@"; fora disso, 422 INVALID_FIELD. | ||||||
- Estoque: a conta é a de
stock.availableno 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_STOCKe nada é baixado;error.details.itemstraz, por SKU,warehouse,requested,required(o total do SKU na venda),availablee, no kit,components. Use oavailablepara corrigir o seu site; não repita igual. - Idempotência: o mesmo pedido com a mesma
reference(o SKU, a quantidade e owarehousecomo enviados; preço e cliente não contam) devolve200com"already_processed": truee o estado da venda — nada é baixado de novo, e não é erro. A mesmareferencecom outro pedido:409 REFERENCE_CONFLICT(não repita; se é outra venda, use outrareference). Uma venda cancelada continua com areferencedela: 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_FAILEDou409 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, voltaalready_processed. Ou consulteGET /vendas/{reference}. - Resposta:
itemsé o estado (uma linha por SKU e armazém, comreversed_quantity).items_processed(só no201) trazavailable_after(o disponível no armazém da venda, o mesmo deGET /produtos),on_hand_after(o físico; no kit,null),stock_after(igual aavailable_after) echannels: por loja vinculada,stock_push_enabledepush—queued(o envio entrou na fila),disabled(a loja está com o envio de estoque desligado) ounot_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.channelslista 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 -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
{
"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"
}
]
}
]
}
}
{
"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": []
}
}
{
"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"
}
}
{
"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
| HTTP | Código | Quando acontece | O que fazer |
|---|---|---|---|
| 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). | Envie Content-Type: application/json e um objeto JSON, ex.: {"type": "in", "quantity": 1, "reason": "Compra"}. |
| 422 | MISSING_REFERENCE | Venda sem o campo "reference". | Envie o id do pedido no seu sistema em "reference" (até 100 caracteres, sem "/"). |
| 422 | REFERENCE_TOO_LONG | "reference" com mais de 100 caracteres. | Encurte a referência para até 100 caracteres. |
| 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. | Corrija o campo citado. Os limites de cada campo estão na tabela do endpoint. |
| 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). | 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. | 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. | 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). | Envie "quantity" como inteiro positivo. |
| 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. | Liste os armazéns em GET /armazens e use o id ou o code. Sem warehouse, vale o armazém padrão da empresa. |
| 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. | 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 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 | 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 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. |
| 409 | 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. |
| 500 | TRANSACTION_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
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.
| Nome | Onde | Tipo | Obrig. | Padrão | Limites | Exemplo |
|---|---|---|---|---|---|---|
reference | caminho | texto | Sim | — | até 100 caracteres | PEDIDO-123 |
| A reference da venda, codificada (PED 77 -> PED%2077). Diferencia maiúsculas. | ||||||
curl -sS --max-time 30 \
-H "Authorization: Bearer $LOJEXA_API_KEY" \
"https://lojexa.com/api/v1/vendas/PEDIDO-123"
{
"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
| HTTP | Código | Quando acontece | O que fazer |
|---|---|---|---|
| 400 | INVALID_REFERENCE | A referência do caminho está vazia ou, decodificada, não é texto UTF-8. | Codifique a referência (encodeURIComponent / quote(ref, safe="")). |
| 404 | SALE_NOT_FOUND | Nenhuma 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
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).
| Nome | Onde | Tipo | Obrig. | Padrão | Limites | Exemplo |
|---|---|---|---|---|---|---|
reference | caminho | texto | Sim | — | até 100 caracteres | PEDIDO-123 |
| A reference da venda, codificada (PED 77 -> PED%2077). Diferencia maiúsculas. | ||||||
items | corpo | lista | Nã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[].sku | corpo | texto | Sim | — | até 100 caracteres | CAMISETA-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[].quantity | corpo | inteiro | Sim | — | 1 a 1.000.000 | 1 |
| Inteiro: 3, 3.0 e "3" valem; 2.5 e "3abc" dão 422 INVALID_ITEM_QTY. No kit, quantos kits. | ||||||
items[].warehouse | corpo | id ou code | Não | — | — | SP |
| Só quando o mesmo SKU saiu de dois armazéns nesta venda. | ||||||
reversal_reference | corpo | texto | Não | — | até 100 caracteres | CANC-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. | ||||||
reason | corpo | texto | Não | — | até 255 caracteres | Cliente desistiu |
| O motivo do estorno, guardado com ele. | ||||||
condition | corpo | texto | Não | sellable | um 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_reversedenquanto restar algo;reversedquando tudo voltou. O cancelamento total de uma venda já toda cancelada devolve200com"already_processed": true(não é erro). - Resposta: o estado da venda e
reversal, comitems[].restocked(o que voltou ao físico; na devolução comcondition: damaged, entra como avaria e não volta ao disponível — confiraavailable_after),available_after,on_hand_afterechannels(o envio do novo saldo, como na venda).restockedsó é menor quequantityem venda antiga que não chegou a baixar o estoque.
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
{
"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
| HTTP | Código | Quando acontece | O que fazer |
|---|---|---|---|
| 400 | INVALID_REFERENCE | A referência do caminho está vazia ou, decodificada, não é texto UTF-8. | Codifique a referência (encodeURIComponent / quote(ref, safe="")). |
| 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). | Envie Content-Type: application/json e um objeto JSON, ex.: {"type": "in", "quantity": 1, "reason": "Compra"}. |
| 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. | Corrija o campo citado. Os limites de cada campo estão na tabela do endpoint. |
| 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). | 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. | 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. | 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). | Envie "quantity" como inteiro positivo. |
| 422 | MISSING_REVERSAL_REFERENCE | Cancelamento 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. |
| 404 | SALE_NOT_FOUND | Nenhuma 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. |
| 409 | INVALID_STATUS_FOR_CANCEL | A venda está com status failed: nada foi baixado e não há o que estornar. | Nada a fazer. |
| 422 | SKU_NOT_IN_SALE | O 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. |
| 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. | Peça até remaining. GET /vendas/{reference} mostra reversed_quantity de cada item. |
| 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 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. |
| 409 | 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. |
| 500 | CANCEL_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
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).
| Nome | Onde | Tipo | Obrig. | Padrão | Limites | Exemplo |
|---|---|---|---|---|---|---|
reference | caminho | texto | Sim | — | até 100 caracteres | PEDIDO-123 |
| A reference da venda, codificada (PED 77 -> PED%2077). Diferencia maiúsculas. | ||||||
items | corpo | lista | Nã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[].sku | corpo | texto | Sim | — | até 100 caracteres | CAMISETA-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[].quantity | corpo | inteiro | Sim | — | 1 a 1.000.000 | 1 |
| Inteiro: 3, 3.0 e "3" valem; 2.5 e "3abc" dão 422 INVALID_ITEM_QTY. No kit, quantos kits. | ||||||
items[].warehouse | corpo | id ou code | Não | — | — | SP |
| Só quando o mesmo SKU saiu de dois armazéns nesta venda. | ||||||
reversal_reference | corpo | texto | Não | — | até 100 caracteres | CANC-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. | ||||||
reason | corpo | texto | Não | — | até 255 caracteres | Cliente desistiu |
| O motivo do estorno, guardado com ele. | ||||||
condition | corpo | texto | Não | sellable | um 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 -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
{
"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
| HTTP | Código | Quando acontece | O que fazer |
|---|---|---|---|
| 400 | INVALID_REFERENCE | A referência do caminho está vazia ou, decodificada, não é texto UTF-8. | Codifique a referência (encodeURIComponent / quote(ref, safe="")). |
| 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). | Envie Content-Type: application/json e um objeto JSON, ex.: {"type": "in", "quantity": 1, "reason": "Compra"}. |
| 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. | Corrija o campo citado. Os limites de cada campo estão na tabela do endpoint. |
| 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). | 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. | 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. | 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). | Envie "quantity" como inteiro positivo. |
| 422 | MISSING_REVERSAL_REFERENCE | Cancelamento 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. |
| 404 | SALE_NOT_FOUND | Nenhuma 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. |
| 409 | INVALID_STATUS_FOR_CANCEL | A venda está com status failed: nada foi baixado e não há o que estornar. | Nada a fazer. |
| 422 | SKU_NOT_IN_SALE | O 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. |
| 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. | Peça até remaining. GET /vendas/{reference} mostra reversed_quantity de cada item. |
| 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 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. |
| 409 | 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. |
| 500 | CANCEL_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
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).
| Nome | Onde | Tipo | Obrig. | Padrão | Limites | Exemplo |
|---|---|---|---|---|---|---|
sku | caminho | texto | Sim | — | — | CAMISETA-M-AZUL |
| O SKU codificado (com "/": use POST /estoque/ajustes) | ||||||
Idempotency-Key | cabeçalho | texto | Não | — | até 100 caracteres; ASCII visível, sem espaço | compra-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. | ||||||
type | corpo | texto | Sim | — | um de: in, out, set | in |
| in = entrada; out = saída (até o disponível no armazém); set = o físico CONTADO (on_hand absoluto no armazém). | ||||||
quantity | corpo | inteiro | Sim | — | 0 a 1.000.000 | 10 |
| in/out: unidades (de 1 a 1.000.000); set: o físico contado (0 vale). 2.5 e "3abc" são recusados. | ||||||
reason_code | corpo | texto | Não | — | um de: purchase, count, loss, damage, return, other | purchase |
| 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. | ||||||
reason | corpo | texto | Não | — | até 255 caracteres | NF 4512 |
| Texto livre (até 255). Obrigatório com reason_code other (ou sem reason_code em in/out). | ||||||
warehouse | corpo | id ou code | Não | — | — | SP |
| O armazém do ajuste. Sem ele, o padrão da empresa — o mesmo de stock.available em GET /produtos. | ||||||
expected_on_hand | corpo | inteiro | Não | — | ≥ 0 | 5 |
| 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_code | type | O que grava | Quando usar |
|---|---|---|---|
purchase | in | Entrada de compra (purchase_entry) | Chegou mercadoria do fornecedor |
return | in | Devolução (return_entry) | Peça devolvida que volta a vender. A devolução de uma venda da API vai por /vendas/{reference}/devolver |
damage | out | Avaria (damaged_in): a peça continua no físico e sai do disponível | Peça com defeito, separada |
loss | out | Saída (manual_adjustment negativo) | Perda, quebra, furto |
count | in, out, set | Contagem (manual_adjustment) | Inventário. É o padrão do set |
other | in, out, set | Entrada ou saída manual (no set, acerto de saldo) | O resto — com reason. É o padrão de in e out |
- Idempotência: mande
Idempotency-Keyem todo ajuste. Deu timeout, queda de rede,500 STOCK_ADJUST_FAILEDou409 STOCK_RACE_CONDITION? Repita a mesma chamada com a mesma chave: se o ajuste entrou, volta200com"already_processed": truee 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, comavailableeon_handemerror.details.items. Para acertar o físico de uma contagem, useset. - Contagem (
set): mande o físico contado; a API grava a diferença. Comexpected_on_hand, a contagem não atropela uma venda feita enquanto você contava (409 STOCK_CHANGED, com oon_handde agora emerror.details). Osetigual ao físico não grava movimento ("movement": null) nem reenvia o saldo às lojas:pushsaiunchanged(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 oPOST /mapeamentosdo vínculo (o vínculo que já existe respondecreated: falsee reenvia; exige o escopomanage: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:
beforeeafter(on_hand,damagedeavailableno armazém do ajuste),delta(a mudança do físico; na avaria, 0),movementemovement_id(o movimento no razão),stock_after(igual aafter.available, o número deGET /produtos) echannels(pushpor loja, como na venda).
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.
{
"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"
}
}
{
"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"
}
}
{
"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 -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
{
"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"
}
}
{
"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"
}
}
{
"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
| HTTP | Código | Quando acontece | O que fazer |
|---|---|---|---|
| 400 | INVALID_SKU | O SKU do caminho está vazio ou, decodificado, não é texto UTF-8. | Codifique o SKU (JavaScript encodeURIComponent, Python quote(sku, safe=""), PHP rawurlencode). |
| 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). | Envie Content-Type: application/json e um objeto JSON, ex.: {"type": "in", "quantity": 1, "reason": "Compra"}. |
| 400 | INVALID_IDEMPOTENCY_KEY | Cabeç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. |
| 422 | INVALID_TYPE | "type" diferente de "in" (entrada), "out" (saída) ou "set" (definir o físico contado). | 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. | 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. | 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". | 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. | Encurte o motivo para até 255 caracteres. |
| 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. | Corrija o campo citado. Os limites de cada campo estão na tabela do endpoint. |
| 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. | 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 | 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. | 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 | 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. | Ajuste cada peça (error.details.components). O disponível do kit acompanha. |
| 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 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_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 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). |
| 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 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 | 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. |
| 500 | 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. |
Mais os de toda chamada — 401 (chave), 403 (escopo ou empresa suspensa), 429 (limite) e 500: tabela de erros.
Ajuste em lote
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-Keyobrigatória (400 MISSING_IDEMPOTENCY_KEY): a chave do lote inteiro. O mesmo lote de novo devolve200com"already_processed": truee 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 oRetry-Aftere 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,failede, por item,statusok(comadjustment, o mesmo objeto do ajuste avulso) ouerror(comcode,messageedetails, 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(owarehousedo topo),INVALID_REASON_CODEouREASON_TOO_LONGdo 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[].pushde cada item diz o que aconteceu.
| Nome | Onde | Tipo | Obrig. | Padrão | Limites | Exemplo |
|---|---|---|---|---|---|---|
Idempotency-Key | cabeçalho | texto | Sim | — | até 100 caracteres; ASCII visível, sem espaço | compra-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. | ||||||
items | corpo | lista | Sim | — | 1 a 500 itens | — |
| Aplicados NA ORDEM, cada um na própria gravação. O mesmo SKU pode aparecer mais de uma vez. | ||||||
items[].sku | corpo | texto | Sim | — | até 100 caracteres | CAMISETA-M-AZUL |
| O sku_code (maiúsculas, minúsculas e acento não importam; "/" vale aqui) | ||||||
items[].type | corpo | texto | Sim | — | um de: in, out, set | in |
| in = entrada; out = saída (até o disponível no armazém); set = o físico CONTADO (on_hand absoluto no armazém). | ||||||
items[].quantity | corpo | inteiro | Sim | — | 0 a 1.000.000 | 10 |
| 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_code | corpo | texto | Não | — | um de: purchase, count, loss, damage, return, other | purchase |
| 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[].reason | corpo | texto | Não | — | até 255 caracteres | NF 4512 |
| Texto livre (até 255). Obrigatório com reason_code other (ou sem reason_code em in/out). | ||||||
items[].warehouse | corpo | id ou code | Nã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_hand | corpo | inteiro | Não | — | ≥ 0 | 5 |
| 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). | ||||||
warehouse | corpo | id ou code | Não | — | — | SP |
| O armazém padrão dos itens. Inválido: 422 WAREHOUSE_NOT_FOUND e nada é gravado. | ||||||
reason_code | corpo | texto | Não | — | um de: purchase, count, loss, damage, return, other | count |
| O motivo dos itens que não trazem o seu. | ||||||
reason | corpo | texto | Não | — | até 255 caracteres | Conferência diária do ERP |
| O texto dos itens que não trazem o seu. | ||||||
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
{
"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
| HTTP | Código | Quando acontece | O que fazer |
|---|---|---|---|
| 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). | Envie Content-Type: application/json e um objeto JSON, ex.: {"type": "in", "quantity": 1, "reason": "Compra"}. |
| 400 | MISSING_IDEMPOTENCY_KEY | POST /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. |
| 400 | INVALID_IDEMPOTENCY_KEY | Cabeç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. |
| 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). | 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. | 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. | Envie o sku_code da LOJEXA como texto em cada item. |
| 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. | Use um reason_code da tabela do ajuste em /docs. Sem reason_code: in e out = other (com reason obrigatório), set = count. |
| 422 | REASON_TOO_LONG | "reason" com mais de 255 caracteres. | Encurte o motivo para até 255 caracteres. |
| 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. | Corrija o campo citado. Os limites de cada campo estão na tabela do endpoint. |
| 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. | Liste os armazéns em GET /armazens e use o id ou o code. Sem warehouse, vale o armazém padrão da empresa. |
| 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 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 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. |
| 409 | 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. |
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)
| HTTP | Código | Quando acontece | O que fazer |
|---|---|---|---|
| — | 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. | 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_REASON | Ajuste 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_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. | Corrija o campo citado. Os limites de cada campo estão na tabela do endpoint. |
| — | 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. | 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_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. | 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_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. | Ajuste cada peça (error.details.components). O disponível do kit acompanha. |
| — | 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 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_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 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
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_skuna mesma loja atualiza o vínculo que existe; o mesmo anúncio e variação (platform_product_id+platform_sku_id) com outroplatform_skutambé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, olisting_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 emerror.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_iddiferente, o vínculo novo nasce com o texto desambiguado ("<texto> [<anúncio>]", o original emlisting_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,fisicaeoutroforam removidos em 24/10/2026 (422 INVALID_PLATFORM): nada no sistema lia esse vínculo. Outra:422 INVALID_PLATFORM.
| Nome | Onde | Tipo | Obrig. | Padrão | Limites | Exemplo |
|---|---|---|---|---|---|---|
sku | corpo | texto | Sim | — | até 100 caracteres | CAMISETA-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. | ||||||
platform | corpo | texto | Sim | — | um de: shopee, mercadolivre, magalu, nuvemshop, shopify, amazon, tiktok, shein, temu | shopee |
| 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_sku | corpo | texto | Sim | — | até 100 caracteres | CAMISETA-M-AZUL |
| O SKU do anúncio (ou da variação) no canal, como aparece lá. Sem ele: 422 MISSING_PLATFORM_SKU. | ||||||
store_id | corpo | inteiro | Nã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_id | corpo | texto | Não | — | até 100 caracteres | 23847719012 |
| O id do anúncio no canal (item_id da Shopee, MLB do Mercado Livre...). | ||||||
platform_sku_id | corpo | texto de dígitos (até 19) ou inteiro | Nã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_sku | corpo | texto | Não | — | até 200 caracteres | B0CXYZ1234-M |
| O SKU da listagem, quando o canal tem um (Amazon). | ||||||
quantity_factor | corpo | inteiro | Não | — | 1 a 10.000 | 1 |
| 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 -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
{
"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"
}
]
}
}
{
"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"
}
]
}
}
{
"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"
}
}
{
"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
| HTTP | Código | Quando acontece | O que fazer |
|---|---|---|---|
| 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). | Envie Content-Type: application/json e um objeto JSON, ex.: {"type": "in", "quantity": 1, "reason": "Compra"}. |
| 422 | MISSING_SKU | Mapeamento sem "sku". | Envie o sku_code da LOJEXA em "sku". |
| 422 | MISSING_PLATFORM | Mapeamento sem "platform". | Envie o canal em "platform" (ex.: shopee). |
| 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. | Use um dos canais do envio de estoque: shopee, mercadolivre, magalu, nuvemshop, shopify, amazon, tiktok, shein ou temu. |
| 422 | MISSING_PLATFORM_SKU | Mapeamento sem "platform_sku". | Envie o código do anúncio no canal em "platform_sku". |
| 422 | MISSING_STORE | Mapeamento 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). |
| 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. | Corrija o campo citado. Os limites de cada campo estão na tabela do endpoint. |
| 404 | 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. | Confira o sku_code em GET /produtos (maiúsculas, minúsculas e acento não importam). SKU inativo não vende: tire do site. |
| 404 | STORE_NOT_FOUND | A 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). |
| 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. | 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
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.
| Nome | Onde | Tipo | Obrig. | Padrão | Limites | Exemplo |
|---|---|---|---|---|---|---|
id | caminho | inteiro | Sim | — | — | 18 |
| id do mapeamento (GET /mapeamentos) | ||||||
curl -sS --max-time 30 -X DELETE \
-H "Authorization: Bearer $LOJEXA_API_KEY" \
"https://lojexa.com/api/v1/mapeamentos/18"
{
"success": true,
"data": {
"deleted_id": 18
}
}
Erros deste endpoint
| HTTP | Código | Quando acontece | O que fazer |
|---|---|---|---|
| 400 | INVALID_ID | Id do mapeamento no caminho não é inteiro positivo. | Use o "id" que veio em GET /mapeamentos. |
| 404 | MAPPING_NOT_FOUND | Mapeamento 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,disabledounot_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 dizpushpor loja (unchangedquando nada mudou). - Mapeamento: o vínculo gravado por
POST /mapeamentospõe o envio do saldo do SKU na fila, pelos mesmos critérios (só com loja de envio ligado). A resposta dizpushpor 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}.
| Evento | Quando | data |
|---|---|---|
sale.confirmed | Depois 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.reversed | Depois de POST /vendas/{reference}/cancelar ou /devolver que estornou agora, total ou parcial | reference, 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.
{
"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"
}
}
]
}
}
{
"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.reversedpode chegar antes dosale.confirmedda mesma venda). Ordene poroccurred_ate, na dúvida, consulteGET /vendas/{reference}. - Cabeçalhos:
Content-Type: application/json,X-Lojexa-Event(o evento),X-Lojexa-Event-Id(o mesmoevent_iddo corpo),X-Lojexa-Timestamp(instante Unix desta tentativa),X-Lojexa-Delivery-Attempt(1 a 10),X-Lojexa-SignatureeX-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
2xxrá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,408ou429), 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 resposta2xxa 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: um422dele, 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 nenhum2xxno meio (secret ou URL errados: tudo volta401ou404), 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
$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']);
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
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ó comread: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-keyse crie outra. - Decida pelo
error.code, não pela mensagem. Guarde oX-Request-Idde toda chamada que falhar: é o que o suporte precisa. - Timeout de 30 s e backoff exponencial com jitter em
429,5xx,409 STOCK_RACE_CONDITIONe queda de rede. Leitura, venda (mesmareference), estorno (mesmareversal_reference) e ajuste (mesmaIdempotency-Key) podem ser repetidos; ajuste semIdempotency-Key, nunca. - Feeds em vez de varrer o catálogo:
/estoque/mudancase/produtos?updated_sincecom 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 comoreference.
Changelog
| Versão | Data | Mudanç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:
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:
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.
POST /mapeamentos). Pode exigir ajuste na sua integração:
|
| v1.3 | 2026-10-23 |
Pode exigir ajuste na sua integração:
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
|