Gerenciar Produtos

Este guia cobre todas as operações para consultar, criar, atualizar e excluir produtos e suas sub-entidades.

Regras Importantes

Antes de começar, tenha em mente estas regras que se aplicam a toda a gestão de produtos:

• Status do produto: Atualmente o único valor suportado é "published". O status é retornado igual nas respostas.
• option_values é imutável: Uma vez criada a variante, você não pode alterar seus option_values via PATCH. Se precisar corrigi-los, exclua a variante e crie-a novamente.
• Moedas suportadas: MXN, PEN, COP, CLP, ARS, BRL, VES, BOB, USD, PYG, UYU, CRC, EUR.
• A moeda deve coincidir com a do catálogo: Todas as variantes de um produto devem usar a mesma moeda configurada no catálogo. Usar uma moeda diferente pode causar inconsistências internas.
• Respostas: PATCH retorna 200 com o recurso atualizado. DELETE retorna 204 sem body.
• Todo produto requer pelo menos uma variante: Mesmo produtos simples (sem tamanhos ou cores) precisam de no mínimo uma opção e uma variante. Use um nome genérico como "Apresentação" ou "Unidade".
• Não existem endpoints batch: Cada entidade deve ser criada individualmente.

Consultar Produtos

Listar produtos

Retorna uma lista paginada de produtos com todas as suas sub-entidades.

A resposta inclui paginação:

{
  "data": [ /* array de produtos */ ],
  "pagination": {
    "page": 1,
    "limit": 25,
    "total_pages": 4,
    "total_items": 100,
    "has_more": true
  }
}

Obter um produto

Retorna um produto com todas as suas opções, variantes (com media) e categorias.

Exemplo de resposta:

{
  "id": 9876,
  "created_at": "2026-01-15T10:00:00Z",
  "name": "Polo Negro",
  "description": "Polo de algodón pima de alta calidad",
  "characteristics": "Material: 100% algodón pima. Peso: 180g/m².",
  "status": "published",
  "categories": [
    { "id": 1, "name": "Ropa" }
  ],
  "options": [
    {
      "id": 10,
      "name": "Talla",
      "values": [
        { "id": 100, "name": "S" },
        { "id": 101, "name": "M" },
        { "id": 102, "name": "L" }
      ]
    }
  ],
  "variants": [
    {
      "id": 500,
      "name": "Polo Negro - Talla M",
      "base_price": 49.90,
      "currency": "PEN",
      "status": "available",
      "media": [
        {
          "id": 1000,
          "title": "Front view",
          "url": "https://cdn.example.com/polo-negro-m-front.jpg"
        }
      ]
    }
  ]
}

Criar um Produto Completo

1. Criar o produto

2. Adicionar opções

A resposta inclui os IDs dos valores criados. Guarde esses IDs para usá-los ao criar variantes.

3. Criar variantes

Cada variante deve incluir option_values com pelo menos um ID de valor de opção.

4. Adicionar media à variante

5. Atribuir categorias

Este endpoint é idempotente: se um tag já está atribuído, ele é ignorado e a resposta é 200. Só retorna 201 quando novos tags são atribuídos.

Atualizar Entidades

Excluir Entidades

Produto Simples (sem variações)

Nem todos os produtos têm tamanhos ou cores. Mesmo assim, todo produto requer pelo menos uma opção e uma variante. Use um nome genérico para a opção.

Erros Comuns

Erros de validação (422) retornam um body com detalhes do campo que falhou:

{
  "detail": [
    {
      "loc": ["body", "option_values"],
      "msg": "List should have at least 1 item",
      "type": "too_short"
    }
  ]
}