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

Vídeos e replays

Lista os vídeos e as imagens 360 de um produto e os replays de lives em que ele foi apresentado.

A galeria de mídia da página do produto tem duas fontes além das fotos: vídeos cadastrados pelo lojista (envio próprio, YouTube, Vimeo ou um trecho de live) e replays de transmissões ao vivo em que o produto apareceu. A rota de vídeos traz também as imagens de giro 360 do produto.

Os vídeos também vêm dentro do próprio produto, em videos, quando você usa Consultar produto. Use a rota dedicada se quiser carregar a mídia depois, sem atrasar a página, ou se precisar das imagens 360.

Vídeos e imagens 360

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

Vídeos e imagens 360 do 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/videos"

Resposta

200Mídia retornada

json

{
  "spin_images": [],
  "videos": [
    {
      "id": "6f058935-6140-400c-a4a3-550a3eb60980",
      "product_id": "34a3bed9-c40d-4519-801f-5cae027eac2a",
      "video_type": "vimeo",
      "url": "https://vimeo.com/76979871",
      "thumbnail_url": "https://example.com/t.jpg",
      "title": "Vimeo",
      "position": 1
    },
    {
      "id": "acdd41ba-4f0d-4afe-bb5e-79b15cb2d8b4",
      "product_id": "34a3bed9-c40d-4519-801f-5cae027eac2a",
      "video_type": "youtube",
      "url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ",
      "thumbnail_url": "https://img.youtube.com/vi/dQw4w9WgXcQ/hqdefault.jpg",
      "title": "Novo título",
      "position": 2
    }
  ]
}

Campos da resposta

videosarray

Vídeos do produto, por position. Lista vazia se não há.

videos[].iduuid

Id do vídeo.

videos[].video_typestring

uploadyoutubevimeolive_clip

Origem: upload é arquivo hospedado pela loja, youtube e vimeo são links de incorporação, live_clip é um trecho de transmissão ao vivo.

videos[].urlstring

URL do vídeo (página do YouTube/Vimeo ou arquivo).

videos[].thumbnail_urlstring

Miniatura. Pode ser vazia.

videos[].titlestring

Título para exibir.

videos[].positioninteger

Ordem de exibição.

videos[].live_session_idstring

Em live_clip: id da sessão de live de origem. Omitido nos demais.

videos[].clip_start_sinteger

Em live_clip: início do trecho, em segundos. clip_end_s é o fim. Omitidos nos demais.

videos[].size_bytesinteger

Tamanho do arquivo em bytes, em vídeos upload. Omitido nos demais.

spin_imagesarray

Imagens do giro 360, em ordem: cada uma com id, image_url e spin_group. Lista vazia se o produto não tem giro.

Replays de lives

Devolve as transmissões ao vivo já encerradas em que o produto foi apresentado, para o comprador assistir à demonstração. Só funciona se a loja ligou "replays de live" nas configurações de mídia da página de produto; desligado, a resposta é sempre lista vazia.

GET/api/v1/storefront/products/{id}/live-replaysPública

Replays de lives que mostraram o produto

Parâmetros de caminho

iduuidobrigatório

Id do produto.

200Replays retornados (exemplo ilustrativo do formato)

json

{
  "replays": [
    {
      "session_id": "b2c1f4f0-3c2d-4e0a-9b0e-5d2a4c6e7f10",
      "title": "Live de lançamento",
      "replay_url": "https://cdn.example.com/lives/lancamento.mp4",
      "ended_at": "2026-10-09T22:30:00Z"
    }
  ]
}

200Sem replays ou recurso desligado (resposta real da loja de testes)

json

{ "replays": [] }

Campos da resposta

replaysarray

Lives encerradas com este produto. Lista vazia se não há ou se o recurso está desligado.

replays[].session_idstring

Id da sessão de live.

replays[].titlestring

Título da live.

replays[].replay_urlstring

URL do vídeo gravado.

replays[].ended_atstring

Fim da transmissão, em texto de data/hora.

Erros

Status	Quando	Exemplo de corpo
500	Falha ao ler a mídia (`/videos` ou `/live-replays`)	`{"error":"failed to list videos","detail":"..."}`

Produto inexistente não gera 404: as listas vêm vazias. Um {id} que não é UUID cai no 500.

Veja também

Vídeos e replays

Lista os vídeos e as imagens 360 de um produto e os replays de lives em que ele foi apresentado.

Vídeos e imagens 360

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

Vídeos e imagens 360 do 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/videos"

Resposta

200Mídia retornada

json

{
  "spin_images": [],
  "videos": [
    {
      "id": "6f058935-6140-400c-a4a3-550a3eb60980",
      "product_id": "34a3bed9-c40d-4519-801f-5cae027eac2a",
      "video_type": "vimeo",
      "url": "https://vimeo.com/76979871",
      "thumbnail_url": "https://example.com/t.jpg",
      "title": "Vimeo",
      "position": 1
    },
    {
      "id": "acdd41ba-4f0d-4afe-bb5e-79b15cb2d8b4",
      "product_id": "34a3bed9-c40d-4519-801f-5cae027eac2a",
      "video_type": "youtube",
      "url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ",
      "thumbnail_url": "https://img.youtube.com/vi/dQw4w9WgXcQ/hqdefault.jpg",
      "title": "Novo título",
      "position": 2
    }
  ]
}

Campos da resposta

videosarray

Vídeos do produto, por position. Lista vazia se não há.

videos[].iduuid

Id do vídeo.

videos[].video_typestring

uploadyoutubevimeolive_clip

Origem: upload é arquivo hospedado pela loja, youtube e vimeo são links de incorporação, live_clip é um trecho de transmissão ao vivo.

videos[].urlstring

URL do vídeo (página do YouTube/Vimeo ou arquivo).

videos[].thumbnail_urlstring

Miniatura. Pode ser vazia.

videos[].titlestring

Título para exibir.

videos[].positioninteger

Ordem de exibição.

videos[].live_session_idstring

Em live_clip: id da sessão de live de origem. Omitido nos demais.

videos[].clip_start_sinteger

Em live_clip: início do trecho, em segundos. clip_end_s é o fim. Omitidos nos demais.

videos[].size_bytesinteger

Tamanho do arquivo em bytes, em vídeos upload. Omitido nos demais.

spin_imagesarray

Imagens do giro 360, em ordem: cada uma com id, image_url e spin_group. Lista vazia se o produto não tem giro.

Replays de lives

GET/api/v1/storefront/products/{id}/live-replaysPública

Replays de lives que mostraram o produto

Parâmetros de caminho

iduuidobrigatório

Id do produto.

200Replays retornados (exemplo ilustrativo do formato)

json

{
  "replays": [
    {
      "session_id": "b2c1f4f0-3c2d-4e0a-9b0e-5d2a4c6e7f10",
      "title": "Live de lançamento",
      "replay_url": "https://cdn.example.com/lives/lancamento.mp4",
      "ended_at": "2026-10-09T22:30:00Z"
    }
  ]
}

200Sem replays ou recurso desligado (resposta real da loja de testes)

json

{ "replays": [] }

Campos da resposta

replaysarray

Lives encerradas com este produto. Lista vazia se não há ou se o recurso está desligado.

replays[].session_idstring

Id da sessão de live.

replays[].titlestring

Título da live.

replays[].replay_urlstring

URL do vídeo gravado.

replays[].ended_atstring

Fim da transmissão, em texto de data/hora.

Erros

Status	Quando	Exemplo de corpo
500	Falha ao ler a mídia (`/videos` ou `/live-replays`)	`{"error":"failed to list videos","detail":"..."}`

Produto inexistente não gera 404: as listas vêm vazias. Um {id} que não é UUID cai no 500.