Catálogo de produtos

Envie e mantenha seu catálogo por SKU a partir do seu próprio sistema (ERP, PIM, loja).

Endpoints

Endpoint	O que faz
`GET /v1/products`	Lista paginada (limit ≤ 200, offset, busca q, status). Scope catalog:read.
`GET /v1/products/{id}`	Detalhe de um produto, incluindo seu source_data. Scope catalog:read.
`POST /v1/products`	Upsert em massa por SKU, até 500 por request. Scope catalog:write.
`PATCH /v1/products/{id}`	Edição parcial de sku, name, brand ou category. Scope catalog:write.
`DELETE /v1/products/{id}`	Exclusão suave (204). Mantém o histórico; oculto de listas e do export. Scope catalog:write.
`GET /v1/products/{id}/revisions`	O que mudou na ficha: versões, com o que mudou em cada uma. Scope catalog:read.

Upsert em massa por SKU

O POST é idempotente por (organização, SKU): reenviar o mesmo lote deixa o catálogo igual, e um SKU excluído anteriormente é revivido. A resposta detalha quantos foram criados, atualizados ou ignorados.

POST /v1/products
{
  "products": [
    {
      "sku": "CAMISA-001",
      "name": "Camisa de lino",
      "brand": "Acme",
      "category": "Ropa/Camisas",
      "source_data": { "color": "azul", "talla": "M" }
    }
  ]
}

{ "total": 1, "created": 1, "updated": 0, "skipped": 0 }

Um novo upsert SUBSTITUI o produto inteiro por SKU (incluindo seu source_data). Envie sempre o produto completo, não só os campos que mudaram — para edições pontuais use PATCH.

source_data

source_data é seu: um objeto JSON livre com os atributos extras do seu produto (cor, tamanho, material, especificações…). O motor de geração o usa como contexto para escrever descrições melhores — quanto mais rico, melhor o resultado.

Editar e excluir

PATCH edita campos isolados sem tocar no resto. O status do produto NÃO é editável pela API (o ciclo de geração cuida dele). Se o novo SKU já existir em outro produto, responde 409.

DELETE é uma exclusão suave: o produto some das listas e do export mas seu histórico é mantido, e um upsert posterior com o mesmo SKU o revive. Repetir o DELETE responde 404.

O histórico de uma ficha

Se você sincroniza com a sua loja, isto diz o que olhar sem baixar a ficha inteira de novo: cada versão traz o que mudou em relação à anterior — campos, atributos (por código e idioma), categorias e família. Dos dados importados são reportados os nomes das colunas que mudaram, nunca o seu conteúdo.

GET /v1/products/7f3a…/revisions

{
  "revisions": [
    {
      "version": 7,
      "reason": "import",
      "created_at": "2026-09-12T05:03:11Z",
      "changes": {
        "base": { "name": ["Crema hidratante", "Crema hidratante 50 ml"] },
        "values": { "tamano": { "": [["1.7 OZ"], ["50 ml"]] } },
        "source_data": { "changed": ["precio"] }
      }
    }
  ],
  "total": 7,
  "limit": 20
}

A paginação vai para trás: limit (1–50, 20 por padrão) e before_version, ao qual você passa a versão mais baixa que recebeu. changes vem vazio na primeira versão de um produto, que não tem com o que se comparar; e se uma mudança for enorme, chega cortada, com _truncated e contagens.

Não traz quem fez a mudança —é dado interno da sua organização e aparece no aplicativo— nem o estado completo da ficha em cada versão, que você pede com o detalhe do produto. Voltar a uma versão anterior também não dá pela API: isso se faz no aplicativo, onde requer papel de administrador.