API atual/Referência completa/Página de produto

Anexos do produto

Lista os arquivos para baixar de um produto (manuais, fichas, certificados) e registra um download.

Um anexo é um arquivo ligado ao produto que o comprador pode baixar: manual, ficha técnica, certificado. O lojista cadastra os anexos no painel. Estas rotas listam os anexos de um produto e contam quando um é baixado.

A API não serve o arquivo. A listagem devolve file_url, e é nessa URL que o navegador baixa. A rota de download apenas incrementa o contador de downloads; chame-a quando o comprador clicar, antes ou depois de abrir a file_url.

Listar anexos

GET/api/v1/storefront/products/{id}/attachmentsPública

Listar anexos de um produto

Parâmetros de caminho

iduuidobrigatório

Id do produto.

Exemplo de requisição

bash

curl "$BASE_URL/api/v1/storefront/products/34a3bed9-c40d-4519-801f-5cae027eac2a/attachments"

Resposta

200Anexos retornados

json

{
  "total": 2,
  "items": [
    {
      "id": "2f9a1719-9f74-463c-8e5e-08a15328afa0",
      "product_id": "34a3bed9-c40d-4519-801f-5cae027eac2a",
      "file_name": "Ficha.pdf",
      "file_url": "/uploads/ficha.pdf",
      "file_size": 0,
      "mime_type": "application/octet-stream",
      "description": "",
      "position": 0,
      "download_count": 0,
      "created_at": "2026-10-11T20:55:15.840926Z",
      "updated_at": "2026-10-11T20:55:21.528944Z"
    },
    {
      "id": "fa4a22a6-2d6b-4ffa-80a2-f573f1324360",
      "product_id": "34a3bed9-c40d-4519-801f-5cae027eac2a",
      "file_name": "Manual.pdf",
      "file_url": "https://example.com/files/manual.pdf",
      "file_size": 120400,
      "mime_type": "application/pdf",
      "description": "Manual do usuário",
      "position": 1,
      "download_count": 0,
      "created_at": "2026-10-11T20:55:15.832387Z",
      "updated_at": "2026-10-11T20:55:21.530267Z"
    }
  ]
}

Campos da resposta

itemsarray

Anexos do produto, por position. Lista vazia se não há.

totalinteger

Quantidade de anexos.

items[].iduuid

Id do anexo: o attachmentId da rota de download.

items[].product_iduuid

Produto dono do anexo.

items[].file_namestring

Nome do arquivo para exibir.

items[].file_urlstring

URL do arquivo. Pode ser relativa à loja (/uploads/...) ou absoluta.

items[].file_sizeinteger

Tamanho em bytes. Pode ser 0 quando desconhecido.

items[].mime_typestring

Tipo do arquivo (application/pdf). Pode ser genérico (application/octet-stream).

items[].descriptionstring

Texto de apoio, como "Manual do usuário".

items[].positioninteger

Ordem de exibição.

items[].download_countinteger

Quantas vezes foi baixado, segundo o contador.

items[].created_atstring

Criação, RFC 3339 (UTC). updated_at é a última alteração.

Registrar um download

POST/api/v1/storefront/attachments/{attachmentId}/downloadPública

Contar um download de anexo

Parâmetros de caminho

attachmentIduuidobrigatório

Id do anexo (items[].id).

A requisição não tem corpo.

Exemplo de requisição

bash

curl -X POST "$BASE_URL/api/v1/storefront/attachments/2f9a1719-9f74-463c-8e5e-08a15328afa0/download"

Resposta

200Download contado

json

{ "message": "download counted" }

Campos da resposta

messagestring

Sempre download counted. A resposta não traz a URL nem o arquivo: use a file_url da listagem.

Erros

Status	Quando	Exemplo de corpo
400	`attachmentId` não é um UUID	`{"error":"invalid attachmentId","detail":"attachmentId must be a valid UUID"}`
404	Anexo inexistente	`{"error":"attachment not found"}`
500	Falha ao gravar o contador	`{"error":"failed to track download","detail":"..."}`

A listagem (GET) não devolve 404 para produto inexistente: responde 200 com items: []. Um {id} que não é UUID dá 500.

Veja também

Anexos do produto

Lista os arquivos para baixar de um produto (manuais, fichas, certificados) e registra um download.

Listar anexos

GET/api/v1/storefront/products/{id}/attachmentsPública

Listar anexos de um produto

Parâmetros de caminho

iduuidobrigatório

Id do produto.

Exemplo de requisição

bash

curl "$BASE_URL/api/v1/storefront/products/34a3bed9-c40d-4519-801f-5cae027eac2a/attachments"

Resposta

200Anexos retornados

json

{
  "total": 2,
  "items": [
    {
      "id": "2f9a1719-9f74-463c-8e5e-08a15328afa0",
      "product_id": "34a3bed9-c40d-4519-801f-5cae027eac2a",
      "file_name": "Ficha.pdf",
      "file_url": "/uploads/ficha.pdf",
      "file_size": 0,
      "mime_type": "application/octet-stream",
      "description": "",
      "position": 0,
      "download_count": 0,
      "created_at": "2026-10-11T20:55:15.840926Z",
      "updated_at": "2026-10-11T20:55:21.528944Z"
    },
    {
      "id": "fa4a22a6-2d6b-4ffa-80a2-f573f1324360",
      "product_id": "34a3bed9-c40d-4519-801f-5cae027eac2a",
      "file_name": "Manual.pdf",
      "file_url": "https://example.com/files/manual.pdf",
      "file_size": 120400,
      "mime_type": "application/pdf",
      "description": "Manual do usuário",
      "position": 1,
      "download_count": 0,
      "created_at": "2026-10-11T20:55:15.832387Z",
      "updated_at": "2026-10-11T20:55:21.530267Z"
    }
  ]
}

Campos da resposta

itemsarray

Anexos do produto, por position. Lista vazia se não há.

totalinteger

Quantidade de anexos.

items[].iduuid

Id do anexo: o attachmentId da rota de download.

items[].product_iduuid

Produto dono do anexo.

items[].file_namestring

Nome do arquivo para exibir.

items[].file_urlstring

URL do arquivo. Pode ser relativa à loja (/uploads/...) ou absoluta.

items[].file_sizeinteger

Tamanho em bytes. Pode ser 0 quando desconhecido.

items[].mime_typestring

Tipo do arquivo (application/pdf). Pode ser genérico (application/octet-stream).

items[].descriptionstring

Texto de apoio, como "Manual do usuário".

items[].positioninteger

Ordem de exibição.

items[].download_countinteger

Quantas vezes foi baixado, segundo o contador.

items[].created_atstring

Criação, RFC 3339 (UTC). updated_at é a última alteração.

Registrar um download

POST/api/v1/storefront/attachments/{attachmentId}/downloadPública

Contar um download de anexo

Parâmetros de caminho

attachmentIduuidobrigatório

Id do anexo (items[].id).

A requisição não tem corpo.

Exemplo de requisição

bash

curl -X POST "$BASE_URL/api/v1/storefront/attachments/2f9a1719-9f74-463c-8e5e-08a15328afa0/download"

Resposta

200Download contado

json

{ "message": "download counted" }

Campos da resposta

messagestring

Sempre download counted. A resposta não traz a URL nem o arquivo: use a file_url da listagem.

Erros

Status	Quando	Exemplo de corpo
400	`attachmentId` não é um UUID	`{"error":"invalid attachmentId","detail":"attachmentId must be a valid UUID"}`
404	Anexo inexistente	`{"error":"attachment not found"}`
500	Falha ao gravar o contador	`{"error":"failed to track download","detail":"..."}`

A listagem (GET) não devolve 404 para produto inexistente: responde 200 com items: []. Um {id} que não é UUID dá 500.