Anexos do produto

Lista, cadastra e reordena os arquivos para download de um produto, como manuais, fichas técnicas e certificados.

Um anexo é um arquivo que o cliente pode baixar na página do produto: o manual, a ficha técnica, um certificado, uma tabela de medidas. Cada anexo guarda o endereço do arquivo (a API não recebe o arquivo, só a URL), o nome exibido, o tipo, o tamanho e uma posição. A plataforma também conta quantas vezes cada um foi baixado.

Leitura exige view_catalog ou manage_catalog; cadastro e reordenação exigem manage_catalog.

Listar os anexos

GET/api/v1/admin/products/{id}/attachmentsAdmin

Lista os anexos de um produto

Devolve os anexos do produto em ordem de posição.

Path parameters

iduuidobrigatório

Id do produto.

Exemplo de requisição

bash

curl "$BASE_URL/api/v1/admin/products/$PRODUCT_ID/attachments" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Anexos do produto

json

{
  "items": [
    {
      "id": "a41f7d3c-2b95-4e08-9c6d-71e0b5a3f812",
      "product_id": "c3f92551-9dda-4fc7-b518-353d1c4e4035",
      "file_name": "Manual.pdf",
      "file_url": "https://cdn.minhaloja.com.br/docs/manual.pdf",
      "file_size": 120400,
      "mime_type": "application/pdf",
      "description": "Manual do usuário",
      "position": 0,
      "download_count": 0,
      "created_at": "2026-10-11T20:55:15.832387Z",
      "updated_at": "2026-10-11T20:55:15.832387Z"
    }
  ],
  "total": 1
}

Response fields

itemsarray

Anexos em ordem de position.

iduuid

Id do anexo.

product_iduuid

Produto dono do anexo.

file_namestring

Nome exibido ao cliente, com a extensão (Manual.pdf).

file_urlstring

Endereço do arquivo.

file_sizeinteger

Tamanho em bytes. 0 quando não informado.

mime_typestring

Tipo do arquivo (application/pdf). application/octet-stream quando não informado.

descriptionstring

Descrição curta. Pode ser vazia.

positioninteger

Posição de exibição, a partir de 0.

download_countinteger

Quantas vezes clientes baixaram o arquivo pela loja.

created_atstring

Data de criação, RFC 3339 em UTC.

updated_atstring

Data da última alteração, RFC 3339 em UTC.

totalinteger

Quantidade de anexos.

Erros

Status	Quando	Corpo
401	Sem token.	`{"error":"missing authorization header"}`
403	Sem `view_catalog` nem `manage_catalog`.	`{"error":"insufficient privileges","privilege_required_any":["manage_catalog","view_catalog"]}`
500	O id não é um UUID válido.	`{"error":"failed to list attachments","detail":"..."}`

Um UUID de produto que não existe devolve 200 com lista vazia.

Cadastrar um anexo

POST/api/v1/admin/products/{id}/attachmentsAdmin

Registra um anexo para um produto

Exige manage_catalog. Registra o endereço de um arquivo que você já hospedou.

Path parameters

iduuidobrigatório

Id do produto.

Corpo da requisição

file_namestringobrigatório

Nome exibido, com a extensão.

file_urlstringobrigatório

Endereço do arquivo. A API guarda o texto como veio e não confere o esquema nem baixa o arquivo: envie sempre uma URL pública https.

file_sizeintegerpadrão: 0

Tamanho em bytes.

mime_typestringpadrão: application/octet-stream

Tipo do arquivo.

descriptionstringpadrão:

Descrição curta.

positionintegerpadrão: 0

Posição. Com 0 ou omitido, o anexo vai para o fim da lista (o primeiro anexo de um produto fica em 0).

Exemplo de requisição

bash

curl -X POST "$BASE_URL/api/v1/admin/products/$PRODUCT_ID/attachments" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "file_name": "Manual.pdf",
  "file_url": "https://cdn.minhaloja.com.br/docs/manual.pdf",
  "file_size": 120400,
  "mime_type": "application/pdf",
  "description": "Manual do usuário"
}'

Resposta

201Anexo criado

json

{
  "id": "a41f7d3c-2b95-4e08-9c6d-71e0b5a3f812",
  "product_id": "c3f92551-9dda-4fc7-b518-353d1c4e4035",
  "file_name": "Manual.pdf",
  "file_url": "https://cdn.minhaloja.com.br/docs/manual.pdf",
  "file_size": 120400,
  "mime_type": "application/pdf",
  "description": "Manual do usuário",
  "position": 0,
  "download_count": 0,
  "created_at": "2026-10-11T20:55:15.832387Z",
  "updated_at": "2026-10-11T20:55:15.832387Z"
}

Erros

Status	Quando	Corpo
400	Corpo inválido.	`{"error":"invalid request body","detail":"..."}`
400	`file_name` vazio.	`{"error":"file_name is required"}`
400	`file_url` vazio.	`{"error":"file_url is required"}`
404	Produto não encontrado.	`{"error":"product not found"}`
500	O id do produto não é um UUID (por exemplo, um SKU).	`{"error":"failed to create attachment","detail":"..."}`
401 / 403	Sem token / sem `manage_catalog`.	`{"error":"insufficient privileges","required":"manage_catalog"}`

Reordenar os anexos

PUT/api/v1/admin/products/{id}/attachments/reorderAdmin

Define a ordem de exibição dos anexos

Exige manage_catalog. Envie os ids na ordem desejada; o primeiro fica na posição 0. Devolve a lista completa já reordenada.

Path parameters

iduuidobrigatório

Id do produto.

Corpo da requisição

attachment_idsarrayobrigatório

Ids dos anexos do produto, na ordem final. Ao menos um. Ids que não são deste produto são ignorados sem erro.

Exemplo de requisição

bash

curl -X PUT "$BASE_URL/api/v1/admin/products/$PRODUCT_ID/attachments/reorder" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "attachment_ids": [
    "a41f7d3c-2b95-4e08-9c6d-71e0b5a3f812"
  ]
}'

Resposta

200Anexos reordenados

json

{
  "items": [
    {
      "id": "a41f7d3c-2b95-4e08-9c6d-71e0b5a3f812",
      "product_id": "c3f92551-9dda-4fc7-b518-353d1c4e4035",
      "file_name": "Manual.pdf",
      "file_url": "https://cdn.minhaloja.com.br/docs/manual.pdf",
      "file_size": 120400,
      "mime_type": "application/pdf",
      "description": "Manual do usuário",
      "position": 0,
      "download_count": 0,
      "created_at": "2026-10-11T20:55:15.832387Z",
      "updated_at": "2026-10-11T20:56:02.114412Z"
    }
  ],
  "total": 1
}

Erros

Status	Quando	Corpo
400	Corpo inválido.	`{"error":"invalid request body","detail":"..."}`
400	`attachment_ids` ausente ou vazio.	`{"error":"attachment_ids is required"}`
500	Um id não é um UUID.	`{"error":"failed to reorder attachments","detail":"..."}`
401 / 403	Sem token / sem `manage_catalog`.	`{"error":"insufficient privileges","required":"manage_catalog"}`

Veja também

Mídia do produto: visão geral, limites e o mapa das rotas.
Imagens do produto
Vídeos do produto
Consultar produto

API atual/Guia rápido/Mídia do produto

Anexos do produto

Lista, cadastra e reordena os arquivos para download de um produto, como manuais, fichas técnicas e certificados.

Leitura exige view_catalog ou manage_catalog; cadastro e reordenação exigem manage_catalog.

Listar os anexos

GET/api/v1/admin/products/{id}/attachmentsAdmin

Lista os anexos de um produto

Devolve os anexos do produto em ordem de posição.

Path parameters

iduuidobrigatório

Id do produto.

Exemplo de requisição

bash

curl "$BASE_URL/api/v1/admin/products/$PRODUCT_ID/attachments" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Anexos do produto

json

{
  "items": [
    {
      "id": "a41f7d3c-2b95-4e08-9c6d-71e0b5a3f812",
      "product_id": "c3f92551-9dda-4fc7-b518-353d1c4e4035",
      "file_name": "Manual.pdf",
      "file_url": "https://cdn.minhaloja.com.br/docs/manual.pdf",
      "file_size": 120400,
      "mime_type": "application/pdf",
      "description": "Manual do usuário",
      "position": 0,
      "download_count": 0,
      "created_at": "2026-10-11T20:55:15.832387Z",
      "updated_at": "2026-10-11T20:55:15.832387Z"
    }
  ],
  "total": 1
}

Response fields

itemsarray

Anexos em ordem de position.

iduuid

Id do anexo.

product_iduuid

Produto dono do anexo.

file_namestring

Nome exibido ao cliente, com a extensão (Manual.pdf).

file_urlstring

Endereço do arquivo.

file_sizeinteger

Tamanho em bytes. 0 quando não informado.

mime_typestring

Tipo do arquivo (application/pdf). application/octet-stream quando não informado.

descriptionstring

Descrição curta. Pode ser vazia.

positioninteger

Posição de exibição, a partir de 0.

download_countinteger

Quantas vezes clientes baixaram o arquivo pela loja.

created_atstring

Data de criação, RFC 3339 em UTC.

updated_atstring

Data da última alteração, RFC 3339 em UTC.

totalinteger

Quantidade de anexos.

Erros

Status	Quando	Corpo
401	Sem token.	`{"error":"missing authorization header"}`
403	Sem `view_catalog` nem `manage_catalog`.	`{"error":"insufficient privileges","privilege_required_any":["manage_catalog","view_catalog"]}`
500	O id não é um UUID válido.	`{"error":"failed to list attachments","detail":"..."}`

Um UUID de produto que não existe devolve 200 com lista vazia.

Cadastrar um anexo

POST/api/v1/admin/products/{id}/attachmentsAdmin

Registra um anexo para um produto

Exige manage_catalog. Registra o endereço de um arquivo que você já hospedou.

Path parameters

iduuidobrigatório

Id do produto.

Corpo da requisição

file_namestringobrigatório

Nome exibido, com a extensão.

file_urlstringobrigatório

Endereço do arquivo. A API guarda o texto como veio e não confere o esquema nem baixa o arquivo: envie sempre uma URL pública https.

file_sizeintegerpadrão: 0

Tamanho em bytes.

mime_typestringpadrão: application/octet-stream

Tipo do arquivo.

descriptionstringpadrão:

Descrição curta.

positionintegerpadrão: 0

Posição. Com 0 ou omitido, o anexo vai para o fim da lista (o primeiro anexo de um produto fica em 0).

Exemplo de requisição

bash

curl -X POST "$BASE_URL/api/v1/admin/products/$PRODUCT_ID/attachments" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "file_name": "Manual.pdf",
  "file_url": "https://cdn.minhaloja.com.br/docs/manual.pdf",
  "file_size": 120400,
  "mime_type": "application/pdf",
  "description": "Manual do usuário"
}'

Resposta

201Anexo criado

json

{
  "id": "a41f7d3c-2b95-4e08-9c6d-71e0b5a3f812",
  "product_id": "c3f92551-9dda-4fc7-b518-353d1c4e4035",
  "file_name": "Manual.pdf",
  "file_url": "https://cdn.minhaloja.com.br/docs/manual.pdf",
  "file_size": 120400,
  "mime_type": "application/pdf",
  "description": "Manual do usuário",
  "position": 0,
  "download_count": 0,
  "created_at": "2026-10-11T20:55:15.832387Z",
  "updated_at": "2026-10-11T20:55:15.832387Z"
}

Erros

Status	Quando	Corpo
400	Corpo inválido.	`{"error":"invalid request body","detail":"..."}`
400	`file_name` vazio.	`{"error":"file_name is required"}`
400	`file_url` vazio.	`{"error":"file_url is required"}`
404	Produto não encontrado.	`{"error":"product not found"}`
500	O id do produto não é um UUID (por exemplo, um SKU).	`{"error":"failed to create attachment","detail":"..."}`
401 / 403	Sem token / sem `manage_catalog`.	`{"error":"insufficient privileges","required":"manage_catalog"}`

Reordenar os anexos

PUT/api/v1/admin/products/{id}/attachments/reorderAdmin

Define a ordem de exibição dos anexos

Exige manage_catalog. Envie os ids na ordem desejada; o primeiro fica na posição 0. Devolve a lista completa já reordenada.

Path parameters

iduuidobrigatório

Id do produto.

Corpo da requisição

attachment_idsarrayobrigatório

Ids dos anexos do produto, na ordem final. Ao menos um. Ids que não são deste produto são ignorados sem erro.

Exemplo de requisição

bash

curl -X PUT "$BASE_URL/api/v1/admin/products/$PRODUCT_ID/attachments/reorder" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "attachment_ids": [
    "a41f7d3c-2b95-4e08-9c6d-71e0b5a3f812"
  ]
}'

Resposta

200Anexos reordenados

json

{
  "items": [
    {
      "id": "a41f7d3c-2b95-4e08-9c6d-71e0b5a3f812",
      "product_id": "c3f92551-9dda-4fc7-b518-353d1c4e4035",
      "file_name": "Manual.pdf",
      "file_url": "https://cdn.minhaloja.com.br/docs/manual.pdf",
      "file_size": 120400,
      "mime_type": "application/pdf",
      "description": "Manual do usuário",
      "position": 0,
      "download_count": 0,
      "created_at": "2026-10-11T20:55:15.832387Z",
      "updated_at": "2026-10-11T20:56:02.114412Z"
    }
  ],
  "total": 1
}

Erros

Status	Quando	Corpo
400	Corpo inválido.	`{"error":"invalid request body","detail":"..."}`
400	`attachment_ids` ausente ou vazio.	`{"error":"attachment_ids is required"}`
500	Um id não é um UUID.	`{"error":"failed to reorder attachments","detail":"..."}`
401 / 403	Sem token / sem `manage_catalog`.	`{"error":"insufficient privileges","required":"manage_catalog"}`

Veja também

Mídia do produto: visão geral, limites e o mapa das rotas.
Imagens do produto
Vídeos do produto
Consultar produto