Imagens

A galeria de imagens centraliza todos os arquivos de mídia da sua loja. As imagens enviadas podem ser vinculadas como capa de produtos, variantes e categorias através do shopImageId.

Os arquivos são armazenados com um hash único e ficam disponíveis publicamente através da uri retornada no upload.

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 imagem contém as seguintes informações principais:

Campo	Tipo	Descrição
hash	UUID	Identificador único do arquivo, gerado no upload.
name	String	Nome original do arquivo enviado.
extension	String	Extensão do arquivo (ex: jpg).
size	Number	Tamanho do arquivo em bytes.
mime	String	Tipo MIME do arquivo (ex: image/jpeg).
uri	String	URL pública da imagem.

---

Listar Imagens

Lista todas as imagens da loja, com paginação e busca.

GET /v1/shop/user/images

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 do arquivo.
orderBy	enum	Não	Ordena por id, name ou createdAt.
orderDirection	enum	Não	Direção da ordenação: asc ou desc.

Exemplo de Requisição

curl -X GET "https://api.us.basis.tavares.in/v1/shop/user/images?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 imagens.

{
  "meta": {
    "currentPage": 1,
    "perPage": 25
  },
  "data": [
    {
      "id": "3",
      "hash": "123e4567-e89b-42d3-a456-426614174000",
      "name": "camiseta-preta-frente.jpg",
      "extension": "jpg",
      "size": 285674,
      "mime": "image/jpeg",
      "uri": "https://cdn.exemplo.com/images/123e4567-e89b-42d3-a456-426614174000.jpg",
      "createdAt": "2026-06-24T00:08:53.818+00:00"
    }
  ]
}

---

Enviar Nova Imagem

Faz o upload de um arquivo de imagem para a galeria da loja. A requisição deve ser enviada como multipart/form-data.

POST /v1/shop/user/images

Payload (Body — multipart/form-data)

Atributo	Tipo	Obrigatório	Descrição
image	file	Sim	Arquivo de imagem (JPG, JPEG, PNG, WEBP ou GIF, máx. 5 MB).

Exemplo de Requisição

curl -X POST "https://api.us.basis.tavares.in/v1/shop/user/images" \
  -H "X-Shop-Id: 3fa85f64-5717-4562-b3fc-2c963f66afa6" \
  -H "Authorization: Bearer {token}" \
  -F "image=@/caminho/para/camiseta-preta-frente.jpg"

Respostas

201 Created

Retorna o ID e a URL pública da imagem enviada.

{
  "id": "1",
  "uri": "https://cdn.exemplo.com/images/123e4567-e89b-42d3-a456-426614174000.jpg"
}

422 Unprocessable Entity

Erro de validação no arquivo enviado.

{
  "errors": [
    {
      "message": "Imagem não suportada, apenas JPG, JPEG, PNG, WEBP e GIF",
      "rule": "file.extnames",
      "field": "image"
    }
  ]
}

---

Obter Imagem por ID

Recupera os metadados de uma imagem da galeria.

GET /v1/shop/user/images/:id

Parâmetros de Rota

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

Exemplo de Requisição

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

Respostas

200 OK

Retorna os metadados da imagem.

{
  "id": "2",
  "hash": "123e4567-e89b-42d3-a456-426614174000",
  "name": "camiseta-preta-frente.jpg",
  "extension": "jpg",
  "size": 285674,
  "mime": "image/jpeg",
  "uri": "https://cdn.exemplo.com/images/123e4567-e89b-42d3-a456-426614174000.jpg",
  "createdAt": "2026-06-23T22:22:29.395+00:00"
}

404 Not Found

Ocorre quando a imagem não existe na loja.

---

Remover Imagem

Exclui uma imagem da galeria da loja.

DELETE /v1/shop/user/images/:id

Exemplo de Requisição

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

Respostas

204 No Content

Remoção concluída com sucesso.