API atual/Referência completa/Catálogo: imagens e anexos

Anexos do produto

Altera os dados de um anexo para download de um produto, como manual ou ficha técnica, e apaga anexos.

Um anexo é um arquivo que o cliente pode baixar na página do produto: manual em PDF, ficha técnica, certificado, tabela de medidas. A plataforma não guarda o arquivo no anexo: ela guarda o nome, a URL (file_url) do arquivo já enviado, o tamanho e o tipo. A contagem de downloads é mantida pela vitrine.

Estas duas rotas agem sobre um anexo pelo id dele. Para listar os anexos de um produto e para criar um novo, use as rotas GET e POST /api/v1/admin/products/{id}/attachments. Exigem o privilégio manage_catalog.

Alterar um anexo

PUT/api/v1/admin/attachments/{attachmentId}Admin

Alterar os dados de um anexo

Atualiza o anexo e devolve o registro novo. As regras de gravação são mistas, e é isso que costuma surpreender:

file_name, file_url, file_size e mime_type só mudam se você enviar um valor não vazio (e file_size maior que 0).
description e position são sempre regravados. Se você não os enviar, a descrição vira vazia e a posição vira 0.

Por isso, ao alterar só o nome, reenvie também a description e a position atuais.

Parâmetros de caminho

attachmentIduuidobrigatório

Id do anexo.

Corpo da requisição

file_namestring

Nome exibido para download, por exemplo manual.pdf. Vazio mantém o atual.

file_urlstring

URL ou caminho do arquivo. Vazio mantém o atual.

file_sizeinteger

Tamanho em bytes. Zero ou ausente mantém o atual.

mime_typestring

Tipo do arquivo, por exemplo application/pdf. Vazio mantém o atual.

descriptionstring

Texto curto que acompanha o link. Ausente apaga a descrição.

positioninteger

Ordem do anexo na lista do produto, a partir de 0. Ausente vira 0.

bash

curl -X PUT "$BASE_URL/api/v1/admin/attachments/3a9c1f52-8d47-4b0e-a6d1-5e2b7c9f0a18" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"file_name":"manual-v2.pdf","description":"Manual do usuário, versão 2","position":0}'

Resposta

200Anexo atualizado

json

{
  "id": "3a9c1f52-8d47-4b0e-a6d1-5e2b7c9f0a18",
  "product_id": "d8a6c5e7-8e44-4055-a0e2-49014f5d17f6",
  "file_name": "manual-v2.pdf",
  "file_url": "/uploads/3b1f/manual-v2.pdf",
  "file_size": 482113,
  "mime_type": "application/pdf",
  "description": "Manual do usuário, versão 2",
  "position": 0,
  "download_count": 14,
  "created_at": "2026-09-02T12:00:00Z",
  "updated_at": "2026-10-11T21:30:00Z"
}

Campos da resposta

iduuid

Id do anexo.

product_iduuid

Produto dono do anexo.

file_namestring

Nome exibido.

file_urlstring

URL ou caminho do arquivo.

file_sizeinteger

Tamanho em bytes.

mime_typestring

Tipo do arquivo.

descriptionstring

Descrição curta.

positioninteger

Ordem na lista do produto.

download_countinteger

Quantas vezes foi baixado pela vitrine.

created_atstring

RFC 3339, UTC.

updated_atstring

RFC 3339, UTC.

Apagar um anexo

DELETE/api/v1/admin/attachments/{attachmentId}Admin

Apagar um anexo

Remove o anexo do produto e fecha o espaço na ordem: os anexos com posição maior sobem uma posição. Sem corpo.

Parâmetros de caminho

attachmentIduuidobrigatório

Id do anexo.

bash

curl -X DELETE "$BASE_URL/api/v1/admin/attachments/3a9c1f52-8d47-4b0e-a6d1-5e2b7c9f0a18" \
  -H "Authorization: Bearer $TOKEN"

200Anexo apagado

json

{ "message": "attachment deleted" }

Erros

Status	Quando	Corpo de exemplo
400	Corpo do `PUT` que não é JSON.	`{"error":"invalid request body","detail":"..."}`
401	Sem token ou token expirado.	`{"error":"invalid or expired token"}`
403	Sem `manage_catalog`.	`{"error":"insufficient privileges","required":"manage_catalog"}`
404	Nenhum anexo com esse id.	`{"error":"attachment not found"}`
500	Falha ao gravar, ou `{attachmentId}` que não é UUID.	`{"error":"failed to update attachment","detail":"..."}`

Veja também

Anexos do produto

Altera os dados de um anexo para download de um produto, como manual ou ficha técnica, e apaga anexos.

Alterar um anexo

PUT/api/v1/admin/attachments/{attachmentId}Admin

Alterar os dados de um anexo

Atualiza o anexo e devolve o registro novo. As regras de gravação são mistas, e é isso que costuma surpreender:

file_name, file_url, file_size e mime_type só mudam se você enviar um valor não vazio (e file_size maior que 0).
description e position são sempre regravados. Se você não os enviar, a descrição vira vazia e a posição vira 0.

Por isso, ao alterar só o nome, reenvie também a description e a position atuais.

Parâmetros de caminho

attachmentIduuidobrigatório

Id do anexo.

Corpo da requisição

file_namestring

Nome exibido para download, por exemplo manual.pdf. Vazio mantém o atual.

file_urlstring

URL ou caminho do arquivo. Vazio mantém o atual.

file_sizeinteger

Tamanho em bytes. Zero ou ausente mantém o atual.

mime_typestring

Tipo do arquivo, por exemplo application/pdf. Vazio mantém o atual.

descriptionstring

Texto curto que acompanha o link. Ausente apaga a descrição.

positioninteger

Ordem do anexo na lista do produto, a partir de 0. Ausente vira 0.

bash

curl -X PUT "$BASE_URL/api/v1/admin/attachments/3a9c1f52-8d47-4b0e-a6d1-5e2b7c9f0a18" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"file_name":"manual-v2.pdf","description":"Manual do usuário, versão 2","position":0}'

Resposta

200Anexo atualizado

json

{
  "id": "3a9c1f52-8d47-4b0e-a6d1-5e2b7c9f0a18",
  "product_id": "d8a6c5e7-8e44-4055-a0e2-49014f5d17f6",
  "file_name": "manual-v2.pdf",
  "file_url": "/uploads/3b1f/manual-v2.pdf",
  "file_size": 482113,
  "mime_type": "application/pdf",
  "description": "Manual do usuário, versão 2",
  "position": 0,
  "download_count": 14,
  "created_at": "2026-09-02T12:00:00Z",
  "updated_at": "2026-10-11T21:30:00Z"
}

Campos da resposta

iduuid

Id do anexo.

product_iduuid

Produto dono do anexo.

file_namestring

Nome exibido.

file_urlstring

URL ou caminho do arquivo.

file_sizeinteger

Tamanho em bytes.

mime_typestring

Tipo do arquivo.

descriptionstring

Descrição curta.

positioninteger

Ordem na lista do produto.

download_countinteger

Quantas vezes foi baixado pela vitrine.

created_atstring

RFC 3339, UTC.

updated_atstring

RFC 3339, UTC.

Apagar um anexo

DELETE/api/v1/admin/attachments/{attachmentId}Admin

Apagar um anexo

Remove o anexo do produto e fecha o espaço na ordem: os anexos com posição maior sobem uma posição. Sem corpo.

Parâmetros de caminho

attachmentIduuidobrigatório

Id do anexo.

bash

curl -X DELETE "$BASE_URL/api/v1/admin/attachments/3a9c1f52-8d47-4b0e-a6d1-5e2b7c9f0a18" \
  -H "Authorization: Bearer $TOKEN"

200Anexo apagado

json

{ "message": "attachment deleted" }

Erros

Status	Quando	Corpo de exemplo
400	Corpo do `PUT` que não é JSON.	`{"error":"invalid request body","detail":"..."}`
401	Sem token ou token expirado.	`{"error":"invalid or expired token"}`
403	Sem `manage_catalog`.	`{"error":"insufficient privileges","required":"manage_catalog"}`
404	Nenhum anexo com esse id.	`{"error":"attachment not found"}`
500	Falha ao gravar, ou `{attachmentId}` que não é UUID.	`{"error":"failed to update attachment","detail":"..."}`