Imagens

O módulo de imagens é o coração da central de mídia do seu blog. Ele gerencia o processamento, armazenamento e a entrega de arquivos, integrando-se diretamente com os provedores de armazenamento (WorkspaceStorage) configurados no seu ambiente.

Pré-requisitos

Para que o upload de imagens funcione corretamente, certifique-se de que:

1. O blog está devidamente vinculado a um Workspace.
2. Um Provedor de Armazenamento foi configurado e selecionado nas definições do blog.
3. O arquivo enviado respeita as extensões e o tamanho máximo permitidos.

Autenticação

Todos os endpoints deste módulo são administrativos e exigem Authorization: Bearer {token} e X-Blog-Id.

---

Listar Imagens

Este endpoint recupera uma lista paginada de todas as imagens que foram enviadas para o blog.

Requisição HTTP

GET /v1/blog/images

Parâmetros de Query

Nome	Tipo	Obrigatório	Descrição
page	number	Não	O número da página para visualização (mínimo: 1).
perPage	number	Não	Quantidade de itens por página (mínimo: 1, máximo: 100).
search	string	Não	Busca por nome do arquivo (máx. 150 caracteres).
orderBy	enum	Não	Campo de ordenação: 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/blog/images?page=1&perPage=25" \
  -H "Authorization: Bearer {token}" \
  -H "X-Blog-Id: {blog-id}"

Respostas da API

200 OK

Retorna um objeto contendo a lista de imagens e os metadados de paginação.

{
  "meta": {
    "currentPage": "1",
    "perPage": "25"
  },
  "data": [
    {
      "id": "7",
      "hash": "4efdbdfa-b867-4821-aa63-8e135eac8bb2",
      "name": "banner-topo.jpg",
      "extension": "jpg",
      "size": 595318,
      "mime": "image/jpeg",
      "uri": "https://cdn.exemplo.com/images/4efdbdfa-b867-4821-aa63-8e135eac8bb2.jpg",
      "createdAt": "2026-03-25T10:43:25.224-03:00"
    }
  ]
}

---

Upload de Imagem

Envia um novo arquivo de imagem para o provedor de armazenamento e registra as referências necessárias no banco de dados.

Requisição HTTP

POST /v1/blog/images

Parâmetros (Multipart/Form-Data)

Atributo	Tipo	Obrigatório	Descrição
image	file	Sim	O arquivo de imagem a ser enviado (máx. 5MB; extensões: jpg, jpeg, png, webp e gif).

Exemplo de Requisição

const formData = new FormData();
formData.append('image', imageFile);

fetch('https://api.us.basis.tavares.in/v1/blog/images', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer {token}',
    'X-Blog-Id': '{blog-id}'
  },
  body: formData
})
.then(response => response.json());

Respostas da API

201 Created

A imagem foi processada e armazenada com sucesso. Retorna o ID e a URI pública do arquivo.

{
  "id": "9",
  "uri": "https://cdn.exemplo.com/images/c02539de-d804-474e-868a-96771673018e.jpg"
}

422 Unprocessable Entity

Ocorre quando o arquivo é muito grande, ausente, possui uma extensão não permitida ou quando o blog não possui um provedor de armazenamento configurado.

{
  "errors": [
    { "message": "Arquivo de imagem é obrigatório" }
  ]
}

{
  "errors": [
    { "message": "Nenhum provedor de armazenamento configurado" }
  ]
}

---

Obter Detalhes da Imagem

Recupera todas as informações técnicas de uma imagem específica através do seu identificador único.

Requisição HTTP

GET /v1/blog/images/:id

Parâmetros de Rota

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

Exemplo de Requisição

curl -X GET "https://api.us.basis.tavares.in/v1/blog/images/9" \
  -H "Authorization: Bearer {token}" \
  -H "X-Blog-Id: {blog-id}"

Respostas da API

200 OK

Retorna o objeto completo da imagem.

{
  "id": "9",
  "hash": "c02539de-d804-474e-868a-96771673018e",
  "name": "paisagem.jpg",
  "extension": "jpg",
  "size": 14692,
  "mime": "image/jpeg",
  "uri": "https://cdn.exemplo.com/images/c02539de-d804-474e-868a-96771673018e.jpg",
  "createdAt": "2026-03-25T15:38:23.804-03:00"
}

404 Not Found

Ocorre caso o ID informado não exista ou não pertença ao seu blog.

---

Remover Imagem

Exclui o registro da imagem do sistema. Dependendo da configuração do seu provedor de armazenamento, o arquivo físico também poderá ser removido do storage.

Requisição HTTP

DELETE /v1/blog/images/:id

Parâmetros de Rota

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

Comportamento de Exclusão

Se o seu WorkspaceStorage estiver com a opção destroyOnDelete ativa, o arquivo físico será permanentemente apagado do provedor (S3, Cloud Storage, etc.).

Exemplo de Requisição

fetch('https://api.us.basis.tavares.in/v1/blog/images/9', {
  method: 'DELETE',
  headers: {
    'Authorization': 'Bearer {token}',
    'X-Blog-Id': '{blog-id}'
  }
})
.then(response => {
  if (response.status === 204) console.log('Removido com sucesso');
});

Respostas da API

204 No Content

A imagem foi removida com sucesso. Não há corpo na resposta.

422 Unprocessable Entity

Ocorre quando o blog não possui um provedor de armazenamento configurado.

{
  "errors": [
    { "message": "Nenhum provedor de armazenamento configurado" }
  ]
}