Variantes de Produto

As variantes permitem oferecer versões diferentes de um mesmo produto — como tamanhos, cores ou acabamentos — cada uma com preço, preço de custo, estoque, SKU e imagem próprios.

Cada variante pertence a um produto (shopProductId) e recebe automaticamente um hash único e um slug gerado a partir do nome.

Endpoints administrativos

Todos os endpoints desta página são protegidos e exigem autenticação de usuário da loja (shopUser), além do header X-Shop-Id (UUID) com o identificador da loja.

Estrutura de Dados Principal

Uma variante de produto contém as seguintes informações principais:

Campo	Tipo	Descrição
`shopProductId`	`Number`	ID do produto ao qual a variante pertence.
`name`	`String`	Nome da variante (máx. 150 caracteres).
`slug`	`String`	URL amigável gerada a partir do nome.
`hash`	`UUID`	Identificador único gerado automaticamente.
`price`	`Number`	Preço de venda (maior que zero).
`promotionalPrice`	`Number`	Preço promocional (opcional).
`costPrice`	`Number`	Preço de custo (opcional).
`stockQuantity`	`Number`	Quantidade em estoque (maior que zero).
`sku`	`String`	Código SKU (máx. 200 caracteres).
`tags`	`String`	Tags separadas por vírgula (máx. 200 caracteres).
`description`	`String`	Descrição (máx. 10000 caracteres).
`isActive`	`Boolean`	Indica se a variante está ativa.
`shopImageId`	`Number`	ID da imagem da variante.

Listar Variantes

Lista todas as variantes da loja, com paginação, busca e filtro por produto.

http

GET /v1/shop/user/product-variants

Parâmetros de Query

Nome	Tipo	Obrigatório	Descrição
`page`	`number`	Não	O número da página (mínimo: 1).
`perPage`	`number`	Não	Itens por página (entre 1 e 100, padrão: 25).
`search`	`string`	Não	Busca por termo no nome.
`orderBy`	`enum`	Não	Ordena por `id`, `name`, `sku`, `price` ou `createdAt`.
`orderDirection`	`enum`	Não	Direção da ordenação: `asc` ou `desc`.
`shopProductId`	`number`	Não	Filtra variantes de um produto específico.

Exemplo de Requisição

bash

curl -X GET "https://api.us.basis.tavares.in/v1/shop/user/product-variants?shopProductId=2&page=1&perPage=25" \
  -H "X-Shop-Id: 3fa85f64-5717-4562-b3fc-2c963f66afa6" \
  -H "Authorization: Bearer {token}" \
  -H "Accept: application/json"

Respostas

200 OK

Retorna um objeto de paginação contendo a lista de variantes.

json

{
  "meta": {
    "currentPage": 1,
    "perPage": 25
  },
  "data": [
    {
      "id": "3",
      "workspaceId": "1",
      "shopId": "9",
      "shopProductId": "2",
      "shopImageId": "2",
      "name": "Camiseta Básica Preta - G",
      "price": "49.90",
      "costPrice": "22.50",
      "description": "Camiseta 100% algodão, modelagem unissex.",
      "sku": null,
      "promotionalPrice": null,
      "stockQuantity": 500,
      "createdAt": "2026-06-27T16:15:09.404+00:00",
      "updatedAt": "2026-06-27T16:15:09.405+00:00",
      "deletedAt": null,
      "hash": "123e4567-e89b-42d3-a456-426614174000",
      "slug": "Camiseta-Basica-Preta-G",
      "tags": "camiseta, básica",
      "isActive": true,
      "shopImage": {
        "id": "2",
        "uri": "https://cdn.exemplo.com/images/123e4567-e89b-42d3-a456-426614174000.jpg"
      }
    }
  ]
}

Criar Nova Variante

Cria uma nova variante vinculada a um produto existente.

http

POST /v1/shop/user/product-variants

Payload (Body)

Atributo	Tipo	Obrigatório	Descrição
`shopProductId`	`number`	Sim	ID do produto (deve existir na loja).
`name`	`string`	Sim	Nome da variante (máx. 150 caracteres).
`price`	`number`	Sim	Preço de venda (maior que zero).
`stockQuantity`	`number`	Sim	Quantidade em estoque (maior que zero).
`isActive`	`boolean`	Sim	Variante ativa ou não.
`shopImageId`	`number`	Não	ID da imagem da variante.
`costPrice`	`number`	Não	Preço de custo.
`promotionalPrice`	`number`	Não	Preço promocional.
`sku`	`string`	Não	Código SKU (máx. 200 caracteres).
`description`	`string`	Não	Descrição (máx. 10000 caracteres).
`tags`	`string`	Não	Tags separadas por vírgula (máx. 200 caracteres).

Exemplo de Requisição

bash

curl -X POST "https://api.us.basis.tavares.in/v1/shop/user/product-variants" \
  -H "X-Shop-Id: 3fa85f64-5717-4562-b3fc-2c963f66afa6" \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "shopProductId": 2,
    "shopImageId": null,
    "name": "Camiseta Básica Preta - G",
    "price": 49.9,
    "costPrice": 22.5,
    "description": "Camiseta 100% algodão, modelagem unissex.",
    "sku": null,
    "promotionalPrice": null,
    "stockQuantity": 500,
    "tags": "camiseta, básica",
    "isActive": true
  }'

Respostas

200 OK

Retorna o ID da variante criada.

json

{
  "id": "2"
}

422 Unprocessable Entity

Erro de validação nos campos enviados.

json

{
  "errors": [
    {
      "message": "ID do produto não encontrado",
      "rule": "database.exists",
      "field": "shopProductId"
    }
  ]
}

Obter Variante por ID

Recupera os detalhes de uma variante, incluindo o produto ao qual ela pertence.

http

GET /v1/shop/user/product-variants/:id

Parâmetros de Rota

Nome	Tipo	Obrigatório	Descrição
`id`	`number`	Sim	O ID da variante.

Exemplo de Requisição

bash

curl -X GET "https://api.us.basis.tavares.in/v1/shop/user/product-variants/2" \
  -H "X-Shop-Id: 3fa85f64-5717-4562-b3fc-2c963f66afa6" \
  -H "Authorization: Bearer {token}" \
  -H "Accept: application/json"

Respostas

200 OK

Retorna a variante com os dados do produto em shopProduct.

json

{
  "id": "2",
  "shopProductId": "2",
  "shopImageId": null,
  "name": "Camiseta Básica Preta - M",
  "price": "49.90",
  "costPrice": "22.50",
  "description": "Camiseta 100% algodão, modelagem unissex.",
  "sku": null,
  "promotionalPrice": null,
  "stockQuantity": 500,
  "createdAt": "2026-06-27T16:11:04.283+00:00",
  "updatedAt": "2026-06-27T16:11:04.283+00:00",
  "shopImage": null,
  "shopProduct": {
    "id": "2",
    "shopImageId": null,
    "name": "Camiseta Básica Preta",
    "price": "49.90",
    "costPrice": "22.50",
    "description": "Camiseta 100% algodão, modelagem unissex.",
    "sku": null,
    "promotionalPrice": null,
    "stockQuantity": 500,
    "shopImage": null
  }
}

404 Not Found

Ocorre quando a variante não existe na loja.

Atualizar Variante

Atualiza os dados de uma variante existente.

http

PUT /v1/shop/user/product-variants/:id

Payload (Body)

Aceita os mesmos campos da criação.

Exemplo de Requisição

bash

curl -X PUT "https://api.us.basis.tavares.in/v1/shop/user/product-variants/3" \
  -H "X-Shop-Id: 3fa85f64-5717-4562-b3fc-2c963f66afa6" \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "shopProductId": 2,
    "shopImageId": 2,
    "name": "Camiseta Básica Preta - GG",
    "price": 54.9,
    "costPrice": 24.5,
    "description": "Camiseta 100% algodão, modelagem unissex.",
    "sku": null,
    "promotionalPrice": null,
    "stockQuantity": 500,
    "tags": "camiseta, básica",
    "isActive": true
  }'

Respostas

204 No Content

Atualização concluída com sucesso.

Remover Variante

Exclui uma variante da loja.

http

DELETE /v1/shop/user/product-variants/:id

Exemplo de Requisição

bash

curl -X DELETE "https://api.us.basis.tavares.in/v1/shop/user/product-variants/4" \
  -H "X-Shop-Id: 3fa85f64-5717-4562-b3fc-2c963f66afa6" \
  -H "Authorization: Bearer {token}"

Respostas

204 No Content

Remoção concluída com sucesso.

Variantes de Produto ​

Estrutura de Dados Principal ​

Listar Variantes ​

Parâmetros de Query ​

Exemplo de Requisição ​

Respostas ​

Criar Nova Variante ​

Payload (Body) ​

Exemplo de Requisição ​

Respostas ​

Obter Variante por ID ​

Parâmetros de Rota ​

Exemplo de Requisição ​

Respostas ​

Atualizar Variante ​

Payload (Body) ​

Exemplo de Requisição ​

Respostas ​

Remover Variante ​

Exemplo de Requisição ​

Respostas ​

Variantes de Produto

Estrutura de Dados Principal

Listar Variantes

Parâmetros de Query

Exemplo de Requisição

Respostas

Criar Nova Variante

Payload (Body)

Exemplo de Requisição

Respostas

Obter Variante por ID

Parâmetros de Rota

Exemplo de Requisição

Respostas

Atualizar Variante

Payload (Body)

Exemplo de Requisição

Respostas

Remover Variante

Exemplo de Requisição

Respostas