API: Módulo Catálogo (catalog)

O módulo catalog lê e altera o catálogo (extensão 5): produtos, categorias, marcas, variações planas, estoque, +Campos e layouts.

⚠️ A API precisa estar habilitada para utilizá-la. Veja o passo a passo em API - Como habilitar.

Endpoint: https://app.interago.com.br/App/Api/index.php

Todas as chamadas são POST com:

• Cabeçalho Authorization: Bearer SEU_TOKEN
• websiteId no corpo
• module e method identificando o recurso

Ative a API e gere o token em #api.main?general (veja API - Como habilitar). Limite: 60 requisições autenticadas por minuto por website. Trate o token como senha.

No painel, o testador e a documentação do método ficam em #api.main?{módulo}&{método}.

No painel, o testador fica em #api.main?catalog e em #api.main?catalog&{método} (por exemplo #api.main?catalog&applyProductVariations).

Leitura

Escrita (propose / apply)

O padrão da API é propose (valida sem gravar) e apply (grava). Exemplos: proposeProduct/applyProduct, proposeCategory/applyCategory, proposeProductVariations/applyProductVariations, status, estoque e filtros.

• Em produto novo use productId=new. Em categoria nova use categoryId=new.
• proposeCategory/applyCategory: a raiz (parentId=0) não pode ser alterada; a URL pública é /cat/{slug}; googleCategoryName vazio não apaga o mapeamento.
• additionalCategoryIds: omitir = não altera; [] remove todas. Outros campos omitidos na edição tendem a zerar/limpar — envie o estado desejado.
• Após mudanças que afetam o site público, chame applyCatalogRefresh (equivalente ao Refresh do painel).

Variações de produto (opções planas)

A API v1 cria e atualiza opções planas (parentId=0, lastChild=0). Combinações aninhadas continuam no painel e devolvem 422 PRODUCT_HAS_NESTED_VARIATIONS.

• Informe variationId da loja ou name do tipo. Tipo inexistente é criado pelo nome.
• applyProductVariations é upsert: não remove opções omitidas no JSON.
• SKU informado que já existe na loja (outro produto ou outra opção) → 422 (mesmo contrato do applyProduct). A opção dona do SKU pode reenviá-lo.
• SKU omitido ou vazio → {skuProduto}-{slug}. Se o candidato estiver ocupado, o plan avisa e usa sufixo (skuRequested vs sku).
• Produto simples (productType=0) passa a productType=1. Depois disso applyProductStock deixa de valer no pai; estoque por opção via applyProductStocks com o SKU da variação.
• price da opção é valor adicional sobre o preço do produto, não o preço final.
• Máximo 50 opções por requisição. image grava só a capa (variationoptImage); sem upload e sem galeria extra.
• Escrita bloqueada em loja free-tier (403 FREE_TIER_DENIED). Não dispara applyCatalogRefresh sozinho.

curl -X POST 'https://app.interago.com.br/App/Api/index.php' \ -H 'Authorization: Bearer SEU_TOKEN' \ -H 'Content-Type: application/x-www-form-urlencoded' \ -d 'websiteId=SEU_WEBSITE_ID&module=catalog&method=proposeProductVariations&productId=100&variations=%5B%7B%22name%22%3A%22Tamanho%22%2C%22options%22%3A%5B%7B%22name%22%3A%22P%22%2C%22sku%22%3A%22CAM-P%22%2C%22price%22%3A0%2C%22stockQty%22%3A5%7D%2C%7B%22name%22%3A%22M%22%2C%22sku%22%3A%22CAM-M%22%2C%22stockQty%22%3A8%7D%5D%7D%5D'

curl -X POST 'https://app.interago.com.br/App/Api/index.php' \ -H 'Authorization: Bearer SEU_TOKEN' \ -H 'Content-Type: application/x-www-form-urlencoded' \ -d 'websiteId=SEU_WEBSITE_ID&module=catalog&method=applyProductVariations&productId=100&variations=%5B%7B%22name%22%3A%22Tamanho%22%2C%22options%22%3A%5B%7B%22name%22%3A%22P%22%2C%22sku%22%3A%22CAM-P%22%2C%22price%22%3A0%2C%22stockQty%22%3A5%7D%5D%7D%5D'

Preço e estoque em massa

proposeProductPrices/applyProductPrices e proposeProductStocks/applyProductStocks aceitam até 100 itens por request.

• identifyBy: productId ou sku (vale para o lote inteiro).
• Variações (lastChild=0) só via identifyBy=sku com o SKU da opção.
• Sucesso parcial: updated, unchanged (mesmo valor) e errors.
• Preço de variação = preço final de venda (a API grava o adicional em relação ao preço base do pai).

curl -X POST 'https://app.interago.com.br/App/Api/index.php' \ -H 'Authorization: Bearer SEU_TOKEN' \ -H 'Content-Type: application/x-www-form-urlencoded' \ -d 'websiteId=SEU_WEBSITE_ID&module=catalog&method=applyProductPrices&identifyBy=sku&items=%5B%7B%22sku%22%3A%22SKU-001%22%2C%22price%22%3A99.9%7D%5D'

curl -X POST 'https://app.interago.com.br/App/Api/index.php' \ -H 'Authorization: Bearer SEU_TOKEN' \ -H 'Content-Type: application/x-www-form-urlencoded' \ -d 'websiteId=SEU_WEBSITE_ID&module=catalog&method=listProducts&page=1&pageSize=20&status=1'

Layouts

Há métodos para baixar/validar/salvar layouts (home, list, menu, product, data) e listar versões. Use com cuidado: alteram o template compilado da loja.