Integração — API de Catálogo

Documentação para exportar produtos, preços, estoque e categorias desta plataforma para a sua loja externa.

1. Endpoint

Um único endpoint público, somente leitura, sem autenticação (retorna apenas produtos ativos). Aceita CORS de qualquer origem, então pode ser chamado do navegador ou do servidor da sua loja.

GET

GET /api/public/catalog?loja={slug}&formato=json|csv&limite=200&pagina=1

Parâmetro	Obrigatório	Descrição
loja	sim	Slug da loja cadastrada em /lojas.
formato	não	json (padrão) ou csv para planilha.
limite	não	Itens por página. 1–500, padrão 200.
pagina	não	Página desejada, começa em 1.

2. Teste rápido com a sua loja

Slug da loja

Baixar CSV Abrir URL

URL do seu catálogo

/api/public/catalog?loja=minha-loja

3. Formato da resposta (JSON)

200 OK

{
  "loja": { "slug": "minha-loja", "nome": "Minha Loja" },
  "gerado_em": "2026-01-01T12:00:00.000Z",
  "paginacao": { "pagina": 1, "limite": 200, "total": 42, "proxima_pagina": null },
  "categorias": [{ "id": "uuid", "nome": "Cortadores", "ordem": 0 }],
  "produtos": [
    {
      "sku": "cortador-coracao",
      "id": "uuid",
      "nome": "Cortador Coração 7cm",
      "descricao": "Impresso em 3D...",
      "categoria": "Cortadores",
      "tag": "novo",
      "preco": 29.9,
      "preco_promocional": 24.9,
      "preco_final": 24.9,
      "moeda": "BRL",
      "estoque": 12,
      "controla_estoque": true,
      "disponivel": true,
      "imagem": "https://.../imagem.jpg",
      "peso_g": 300,
      "dimensoes_cm": { "c": 16, "l": 11, "a": 2 },
      "url": "https://.../loja/minha-loja/cortador-coracao",
      "atualizado_em": "2026-01-01T10:00:00.000Z"
    }
  ]
}

Use sku como chave estável do produto na sua loja e preco_final como preço de venda (já considera promoção). Quando controla_estoque é false, o campo estoque vem null e o produto deve ser tratado como disponível.

4. Erros

respostas de erro

400  { "error": "Parâmetro obrigatório: loja (slug da loja)" }
404  { "error": "Loja não encontrada" }

5. Exemplos de consumo

cURL

curl "/api/public/catalog?loja=minha-loja"

Node.js / Next.js (sincronização)

const res = await fetch("/api/public/catalog?loja=minha-loja&limite=500");
if (!res.ok) throw new Error("Falha ao ler catálogo: " + res.status);
const { produtos } = await res.json();

for (const p of produtos) {
  await minhaLoja.upsertProduto({
    sku: p.sku,
    title: p.nome,
    description: p.descricao,
    price: p.preco_final,
    compareAtPrice: p.preco_promocional ? p.preco : null,
    inventory: p.estoque,          // null = sem controle de estoque
    available: p.disponivel,
    imageUrl: p.imagem,
    category: p.categoria,
    weightGrams: p.peso_g,
  });
}

PHP (WooCommerce / loja própria)

$json = file_get_contents("/api/public/catalog?loja=minha-loja");
$data = json_decode($json, true);
foreach ($data["produtos"] as $p) {
  // atualize por SKU
  upsert_produto($p["sku"], $p["nome"], $p["preco_final"], $p["estoque"]);
}

Paginação

let pagina = 1, todos = [];
while (pagina) {
  const r = await fetch("/api/public/catalog?loja=minha-loja&limite=500&pagina=" + pagina).then(r => r.json());
  todos.push(...r.produtos);
  pagina = r.paginacao.proxima_pagina;
}

6. Boas práticas de sincronização

Sincronize por SKU (o slug do produto) — nunca por nome.
A resposta tem cache de 60 segundos; rode a sincronização a cada 5–15 minutos, não a cada requisição da sua loja.
Produtos inativos não aparecem: trate ausência como “despublicar” na sua loja.
Use atualizado_em para importar apenas o que mudou.
Pare após erros 4xx repetidos — o slug pode ter mudado.
Precisa de planilha manual? Use formato=csv ou a página Exportar Marketplaces.

7. Sobre estoque e pedidos

Este endpoint é somente leitura. O estoque é reduzido automaticamente quando o pagamento é confirmado nesta plataforma. Se a venda ocorrer na sua loja externa, o abatimento deve ser feito lá — ou avise que deseja um endpoint de baixa de estoque autenticado por token e eu implemento.

Endpoint base: /api/public/catalog