Produtos

O módulo de produtos é o coração do catálogo da sua loja. Ele permite criar e gerenciar produtos físicos e digitais, com controle de preço, preço promocional, preço de custo, estoque, SKU, tags e vínculo com categorias.

Cada produto pode ter variantes (tamanhos, cores etc.) e receber comentários e avaliações dos clientes na vitrine.

Headers obrigatórios

Todas as requisições (públicas ou administrativas) devem incluir o header X-Shop-Id (UUID) com o identificador da loja. Endpoints administrativos exigem também Authorization: Bearer {token}.

Estrutura de Dados Principal

Um produto contém as seguintes informações principais:

Campo	Tipo	Descrição
`name`	`String`	Nome do produto (máx. 150 caracteres).
`slug`	`String`	URL amigável gerada a partir do nome.
`description`	`String`	Descrição completa (máx. 10000 caracteres).
`manufacturer`	`String`	Fabricante/marca (máx. 150 caracteres).
`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).
`isActive`	`Boolean`	Indica se o produto está ativo.
`isDigital`	`Boolean`	Indica se é um produto digital.
`isFeature`	`Boolean`	Indica se o produto está em destaque.
`shopImageId`	`Number`	ID da imagem de capa do produto.

Endpoints Públicos

Estes endpoints são voltados para a vitrine da loja e não exigem autenticação de customer.

Listar Produtos

Retorna uma lista paginada dos produtos da loja.

http

GET /v1/shop/customer/products/public

Parâmetros de Query

Nome	Tipo	Obrigatório	Descrição
`search`	`string`	Não	Busca por termo no nome (máx. 150 caracteres).
`limit`	`number`	Não	Limite de itens (entre 1 e 300).
`orderBy`	`enum`	Não	Ordena por `id`, `name`, `sku`, `price` ou `createdAt`.
`orderDirection`	`enum`	Não	Direção da ordenação: `asc` ou `desc`.
`isActive`	`boolean`	Não	Filtra por produtos ativos/inativos.
`isDigital`	`boolean`	Não	Filtra por produtos digitais/físicos.

Exemplo de Requisição

bash

curl -X GET "https://api.us.basis.tavares.in/v1/shop/customer/products/public?orderBy=price&orderDirection=asc" \
  -H "X-Shop-Id: 3fa85f64-5717-4562-b3fc-2c963f66afa6" \
  -H "Accept: application/json"

Respostas

200 OK

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

json

{
  "meta": {
    "currentPage": 1,
    "perPage": 25
  },
  "data": [
    {
      "id": "2",
      "shopImageId": null,
      "name": "Camiseta Básica Preta",
      "price": "49.90",
      "stockQuantity": 500,
      "costPrice": "22.50",
      "description": "Camiseta 100% algodão, modelagem unissex...",
      "sku": null,
      "promotionalPrice": null,
      "isActive": true,
      "isDigital": false,
      "isFeature": true,
      "createdAt": "2026-06-26T00:01:32.784+00:00",
      "updatedAt": "2026-06-26T00:30:42.800+00:00",
      "shopImage": null
    }
  ]
}

Obter Detalhes do Produto

Recupera os detalhes completos de um produto, incluindo categorias e variantes.

http

GET /v1/shop/customer/products/public/:id

Parâmetros de Rota

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

Exemplo de Requisição

javascript

fetch('https://api.us.basis.tavares.in/v1/shop/customer/products/public/2', {
  headers: {
    'X-Shop-Id': '3fa85f64-5717-4562-b3fc-2c963f66afa6'
  }
})
  .then(response => response.json())
  .then(data => console.log(data));

Respostas

200 OK

Retorna o produto com shopCategories e shopProductVariants.

json

{
  "id": "2",
  "shopImageId": null,
  "name": "Camiseta Básica Preta",
  "slug": "Camiseta-Basica-Preta",
  "manufacturer": "Company LLC",
  "price": "49.90",
  "stockQuantity": 500,
  "sku": null,
  "isActive": true,
  "isDigital": false,
  "isFeature": true,
  "promotionalPrice": null,
  "costPrice": "22.50",
  "description": "Camiseta 100% algodão, modelagem unissex...",
  "createdAt": "2026-07-01T15:33:01.460+00:00",
  "updatedAt": "2026-07-01T15:33:01.460+00:00",
  "shopImage": null,
  "shopCategories": [
    {
      "id": "1",
      "name": "Camisetas",
      "shopImageId": null,
      "shopImage": null
    }
  ],
  "shopProductVariants": [
    {
      "id": "1",
      "shopImageId": null,
      "name": "Camiseta Básica Preta - P",
      "price": "49.90",
      "costPrice": "22.50",
      "description": "Camiseta 100% algodão, modelagem unissex...",
      "sku": null,
      "promotionalPrice": null,
      "stockQuantity": 500,
      "isActive": true,
      "hash": "123e4567-e89b-42d3-a456-426614174000",
      "slug": "Camiseta-Basica-Preta-P",
      "tags": "camiseta, básica",
      "shopProductId": "2",
      "shopImage": null
    }
  ]
}

404 Not Found

Ocorre quando o produto não existe ou não está ativo.

Listar Comentários do Produto

Retorna os comentários e avaliações de um produto, com respostas aninhadas.

http

GET /v1/shop/customer/products/public/:id/comments

Parâmetros de Rota

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

Exemplo de Requisição

bash

curl -X GET "https://api.us.basis.tavares.in/v1/shop/customer/products/public/2/comments" \
  -H "X-Shop-Id: 3fa85f64-5717-4562-b3fc-2c963f66afa6" \
  -H "Accept: application/json"

Respostas

200 OK

Retorna um objeto de paginação com os comentários e suas respostas em children.

json

{
  "meta": {
    "total": 1,
    "perPage": 25,
    "currentPage": 1,
    "lastPage": 1,
    "firstPage": 1,
    "firstPageUrl": "/?page=1",
    "lastPageUrl": "/?page=1",
    "nextPageUrl": null,
    "previousPageUrl": null
  },
  "data": [
    {
      "id": "1",
      "parentId": null,
      "shopCustomerId": "2",
      "rate": 3,
      "comment": "Produto de boa qualidade, entrega rápida.",
      "createdAt": "2026-07-01T21:53:09.428+00:00",
      "updatedAt": "2026-07-01T21:53:09.428+00:00",
      "shopCustomer": {
        "id": "2",
        "firstName": "John",
        "lastName": "Doe"
      },
      "children": [
        {
          "id": "2",
          "parentId": "1",
          "shopCustomerId": "2",
          "rate": 4,
          "comment": "Complementando minha avaliação anterior.",
          "shopCustomer": {
            "id": "2",
            "firstName": "John",
            "lastName": "Doe"
          }
        }
      ]
    }
  ]
}

Endpoints Administrativos

Endpoints protegidos para gerenciamento do catálogo. Requerem autenticação de usuário da loja (shopUser).

Listar Todos os Produtos

Lista todos os produtos da loja, com paginação, busca e filtros.

http

GET /v1/shop/user/products

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`.
`isActive`	`boolean`	Não	Filtra por produtos ativos/inativos.
`isDigital`	`boolean`	Não	Filtra por produtos digitais/físicos.

Exemplo de Requisição

bash

curl -X GET "https://api.us.basis.tavares.in/v1/shop/user/products?page=1&perPage=25&isActive=true" \
  -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 produtos.

Criar Novo Produto

Cria um novo produto e o vincula a categorias.

http

POST /v1/shop/user/products

Payload (Body)

Atributo	Tipo	Obrigatório	Descrição
`product.name`	`string`	Sim	Nome do produto (máx. 150 caracteres).
`product.price`	`number`	Sim	Preço de venda (maior que zero).
`product.stockQuantity`	`number`	Sim	Quantidade em estoque (maior que zero).
`product.isActive`	`boolean`	Sim	Produto ativo ou não.
`product.isDigital`	`boolean`	Sim	Produto digital ou físico.
`product.isFeature`	`boolean`	Sim	Produto em destaque ou não.
`product.shopImageId`	`number`	Não	ID da imagem de capa.
`product.manufacturer`	`string`	Não	Fabricante (máx. 150 caracteres).
`product.sku`	`string`	Não	Código SKU (máx. 200 caracteres).
`product.promotionalPrice`	`number`	Não	Preço promocional.
`product.costPrice`	`number`	Não	Preço de custo.
`product.description`	`string`	Não	Descrição (máx. 10000 caracteres).
`product.tags`	`string`	Não	Tags separadas por vírgula (máx. 200 caracteres).
`categories`	`number[]`	Não	IDs das categorias (ex: `[1, 2]`).

Exemplo de Requisição

bash

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

Respostas

201 Created

Retorna o ID do produto criado.

json

{
  "id": "2"
}

422 Unprocessable Entity

Erro de validação nos campos enviados.

json

{
  "errors": [
    {
      "message": "Preço é obrigatório",
      "rule": "required",
      "field": "product.price"
    }
  ]
}

Obter Produto por ID

Recupera os detalhes completos de um produto, incluindo categorias, comentários e variantes.

http

GET /v1/shop/user/products/:id

Parâmetros de Rota

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

Exemplo de Requisição

bash

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

Respostas

200 OK

Retorna o produto com shopCategories, shopProductComments e shopProductVariants.

json

{
  "id": "2",
  "shopImageId": null,
  "name": "Camiseta Básica Preta",
  "slug": "Camiseta-Basica-Preta",
  "manufacturer": "Company LLC",
  "price": "49.90",
  "stockQuantity": 500,
  "sku": null,
  "isActive": true,
  "isDigital": false,
  "isFeature": true,
  "promotionalPrice": null,
  "costPrice": "22.50",
  "description": "Camiseta 100% algodão, modelagem unissex.",
  "createdAt": "2026-06-26T00:01:32.784+00:00",
  "updatedAt": "2026-06-26T00:30:42.800+00:00",
  "shopImage": null,
  "shopCategories": [
    {
      "id": "1",
      "name": "Camisetas",
      "shopImageId": null,
      "shopImage": null
    }
  ],
  "shopProductComments": [],
  "shopProductVariants": [
    {
      "id": "1",
      "shopImageId": null,
      "name": "Camiseta Básica Preta - P",
      "price": "49.90",
      "costPrice": "22.50",
      "description": "Camiseta 100% algodão, modelagem unissex.",
      "sku": null,
      "promotionalPrice": null,
      "stockQuantity": 500,
      "isActive": true,
      "hash": "123e4567-e89b-42d3-a456-426614174000",
      "slug": "Camiseta-Basica-Preta-P",
      "tags": "camiseta, básica",
      "shopProductId": "2",
      "shopImage": null
    }
  ]
}

404 Not Found

Ocorre quando o produto não existe na loja.

Atualizar Produto

Atualiza um produto existente e seus vínculos com categorias.

http

PUT /v1/shop/user/products/:id

Payload (Body)

Aceita os mesmos campos da criação: objeto product e array categories.

Exemplo de Requisição

bash

curl -X PUT "https://api.us.basis.tavares.in/v1/shop/user/products/2" \
  -H "X-Shop-Id: 3fa85f64-5717-4562-b3fc-2c963f66afa6" \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "product": {
      "shopImageId": null,
      "name": "Camiseta Básica Preta Premium",
      "description": "Camiseta 100% algodão pima, modelagem unissex.",
      "tags": "camiseta, premium",
      "manufacturer": "Company LLC",
      "price": 59.9,
      "stockQuantity": 500,
      "sku": null,
      "isActive": true,
      "isDigital": false,
      "isFeature": true,
      "promotionalPrice": null,
      "costPrice": 28.5
    },
    "categories": [1, 2]
  }'

Respostas

204 No Content

Atualização concluída com sucesso.

Remover Produto

Exclui um produto da loja.

http

DELETE /v1/shop/user/products/:id

Exemplo de Requisição

bash

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

Respostas

204 No Content

Remoção concluída com sucesso.

Produtos ​

Estrutura de Dados Principal ​

Endpoints Públicos ​

Listar Produtos ​

Parâmetros de Query ​

Exemplo de Requisição ​

Respostas ​

Obter Detalhes do Produto ​

Parâmetros de Rota ​

Exemplo de Requisição ​

Respostas ​

Listar Comentários do Produto ​

Parâmetros de Rota ​

Exemplo de Requisição ​

Respostas ​

Endpoints Administrativos ​

Listar Todos os Produtos ​

Parâmetros de Query ​

Exemplo de Requisição ​

Respostas ​

Criar Novo Produto ​

Payload (Body) ​

Exemplo de Requisição ​

Respostas ​

Obter Produto por ID ​

Parâmetros de Rota ​

Exemplo de Requisição ​

Respostas ​

Atualizar Produto ​

Payload (Body) ​

Exemplo de Requisição ​

Respostas ​

Remover Produto ​

Exemplo de Requisição ​

Respostas ​

Produtos

Estrutura de Dados Principal

Endpoints Públicos

Listar Produtos

Parâmetros de Query

Exemplo de Requisição

Respostas

Obter Detalhes do Produto

Parâmetros de Rota

Exemplo de Requisição

Respostas

Listar Comentários do Produto

Parâmetros de Rota

Exemplo de Requisição

Respostas

Endpoints Administrativos

Listar Todos os Produtos

Parâmetros de Query

Exemplo de Requisição

Respostas

Criar Novo Produto

Payload (Body)

Exemplo de Requisição

Respostas

Obter Produto por ID

Parâmetros de Rota

Exemplo de Requisição

Respostas

Atualizar Produto

Payload (Body)

Exemplo de Requisição

Respostas

Remover Produto

Exemplo de Requisição

Respostas