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.

Resposta

200Anexo atualizado

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.

200Anexo apagado

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.

Resposta

200Anexo atualizado

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.

200Anexo apagado

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":"..."}`