VenddorDocumentação API
API atualAPI legada
Guia rápidoReferência completa
Carregando índice…
API atual/Guia rápido/Mídia do produto

Vídeos do produto

Lista, adiciona (YouTube, Vimeo, arquivo ou trecho de live), edita, reordena e remove os vídeos da galeria de um produto.

Além das imagens, a galeria de um produto pode ter até 3 vídeos. Eles aparecem como slides ao lado das fotos na página do produto. Cada vídeo tem um tipo, uma miniatura (sempre obrigatória, é o que o cliente vê antes de dar play) e uma posição.

Todas as rotas desta página exigem o privilégio view_catalog (leitura) ou manage_catalog (escrita).

Pontos-chave
  • Máximo de 3 vídeos por produto. O quarto é recusado com 422 max 3 videos per product.
  • Quatro tipos (video_type): youtube e vimeo (link), upload (arquivo MP4 ou WebM de até 200 MB) e live_clip (trecho da gravação de uma transmissão ao vivo).
  • Só YouTube e Vimeo são aceitos como link. Qualquer outro endereço é recusado.
  • Para youtube a miniatura é gerada sozinha; nos demais tipos você precisa enviá-la.
  • Apagar um vídeo upload também apaga o arquivo hospedado.

Listar os vídeos

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

Lista os vídeos de um produto

Devolve os vídeos 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/videos" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Vídeos do produto
json
{
  "videos": [
    {
      "id": "7c0d3b52-6e1f-4f8a-9d57-0a4b1c2e8f31",
      "product_id": "c3f92551-9dda-4fc7-b518-353d1c4e4035",
      "video_type": "youtube",
      "url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ",
      "thumbnail_url": "https://img.youtube.com/vi/dQw4w9WgXcQ/hqdefault.jpg",
      "title": "Demonstração",
      "position": 0
    },
    {
      "id": "b19e4a07-3c85-42d0-8e6b-5f7a9c1d2e44",
      "product_id": "c3f92551-9dda-4fc7-b518-353d1c4e4035",
      "video_type": "vimeo",
      "url": "https://vimeo.com/76979871",
      "thumbnail_url": "https://cdn.minhaloja.com.br/p/video-capa.jpg",
      "title": "Detalhes",
      "position": 1
    }
  ]
}

Response fields

videosarray

Vídeos em ordem de position. Lista vazia quando não há vídeos.

iduuid
Id do vídeo.
product_iduuid
Produto dono do vídeo.
video_typestring
uploadyoutubevimeolive_clip
Tipo do vídeo.
urlstring
Endereço do vídeo. Para youtube e vimeo é a forma canônica do link (https://www.youtube.com/watch?v=ID, https://vimeo.com/ID). Para upload é o endereço do arquivo hospedado pela plataforma.
thumbnail_urlstring
Endereço da miniatura.
titlestring
Título exibido. Pode ser vazio.
positioninteger
Posição de exibição, a partir de 0. Ao apagar um vídeo, as posições dos demais não são renumeradas.
live_session_iduuid
Só em live_clip: a transmissão de origem.
clip_start_sinteger
Só em live_clip: segundo em que o trecho começa.
clip_end_sinteger
Só em live_clip: segundo em que o trecho termina.
size_bytesinteger
Só em upload: tamanho do arquivo em bytes.

Erros

StatusQuandoCorpo
401Sem token.{"error":"missing authorization header"}
403Sem view_catalog nem manage_catalog.{"error":"insufficient privileges","privilege_required_any":["manage_catalog","view_catalog"]}
500O id não é um UUID válido.{"error":"failed to get product videos","detail":"..."}

Um UUID de produto que não existe devolve 200 com "videos": [].

Adicionar um vídeo

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

Adiciona um vídeo (link ou clipe ao vivo, em JSON)

Exige manage_catalog. O corpo é JSON para os tipos youtube, vimeo e live_clip. Para enviar um arquivo (upload) use a variante multipart logo abaixo.

Path parameters

iduuidobrigatório
Id do produto.

Request body (JSON)

video_typestringobrigatório
youtubevimeolive_clip
Tipo. Qualquer outro valor devolve 422 invalid video_type. Para enviar um arquivo (upload) use a variante multipart abaixo.
urlstringobrigatório
Link do vídeo. YouTube: youtube.com/watch?v=..., youtube.com/embed/..., youtube.com/shorts/... ou youtu.be/.... Vimeo: vimeo.com/ID ou vimeo.com/video/ID. A plataforma troca o link pela forma canônica. Em live_clip pode ser omitido quando você envia live_session_id (veja abaixo).
thumbnail_urlstring
Endereço da miniatura. Obrigatório em vimeo e live_clip. Em youtube, se omitido, a plataforma usa a miniatura do próprio YouTube.
titlestring
Título exibido.
live_session_iduuid
Só em live_clip: a transmissão ao vivo de origem. Quando você a envia sem url, a plataforma copia o endereço da gravação (a transmissão precisa estar encerrada e ter gravação; senão 422 invalid live clip).
clip_start_sinteger
Só em live_clip, obrigatório: segundo em que o trecho começa (0 ou mais).
clip_end_sinteger
Só em live_clip, obrigatório: segundo em que o trecho termina. Precisa ser maior que clip_start_s.

Exemplo de requisição (link do YouTube)

bash
curl -X POST "$BASE_URL/api/v1/admin/products/$PRODUCT_ID/videos" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "video_type": "youtube",
  "url": "https://youtu.be/dQw4w9WgXcQ",
  "title": "Demonstração"
}'

Resposta

201Vídeo criado
json
{
  "id": "7c0d3b52-6e1f-4f8a-9d57-0a4b1c2e8f31",
  "product_id": "c3f92551-9dda-4fc7-b518-353d1c4e4035",
  "video_type": "youtube",
  "url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ",
  "thumbnail_url": "https://img.youtube.com/vi/dQw4w9WgXcQ/hqdefault.jpg",
  "title": "Demonstração",
  "position": 0
}

O vídeo entra na última posição. Os campos são os da listagem.

Enviar um arquivo (multipart)

Para um vídeo upload, a mesma rota recebe multipart/form-data (o Content-Type com boundary é montado pela sua biblioteca HTTP; não o escreva à mão).

Request body (multipart/form-data)

filefileobrigatório
O vídeo, em MP4 ou WebM, de até 200 MB. A plataforma confere o conteúdo do arquivo, não só a extensão.
thumbnailfileobrigatório
A miniatura, uma imagem. Em geral é um quadro do vídeo.
titlestring
Título exibido.
bash
curl -X POST "$BASE_URL/api/v1/admin/products/$PRODUCT_ID/videos" \
  -H "Authorization: Bearer $TOKEN" \
  -F "file=@demo.mp4;type=video/mp4" \
  -F "thumbnail=@capa.jpg;type=image/jpeg" \
  -F "title=Demonstração"

A resposta é a mesma (201), com video_type "upload", url apontando para o arquivo hospedado pela plataforma e size_bytes preenchido.

Erros

StatusQuandoCorpo
400Corpo JSON inválido, ou multipart ilegível.{"error":"invalid request body","detail":"..."} / {"error":"failed to parse upload","detail":"..."}
400Upload sem o campo file.{"error":"file is required","detail":"..."}
404Produto não encontrado.{"error":"product not found"}
422Já há 3 vídeos. Esta checagem vem antes das demais: com 3 vídeos, qualquer envio responde isto.{"error":"max 3 videos per product"}
422video_type desconhecido.{"error":"invalid video_type"}
422Link que não é do YouTube ou do Vimeo.{"error":"invalid youtube url"} ou {"error":"invalid vimeo url"}
422url vazia.{"error":"url is required"}
422Sem miniatura (Vimeo, live_clip, upload).{"error":"thumbnail is required"}
422live_clip com clip_start_s ausente ou não menor que clip_end_s.{"error":"live clip requires 0 <= start_s < end_s"}
422Transmissão sem gravação, ou ainda no ar.{"error":"invalid live clip","detail":"session has no replay"}
422Arquivo que não é MP4/WebM, ou acima de 200 MB.{"error":"invalid video file","detail":"unrecognized video container (only mp4/webm allowed)"}
401 / 403Sem token / sem manage_catalog.{"error":"insufficient privileges","required":"manage_catalog"}

Editar título e posição

PUT/api/v1/admin/products/{id}/videos/{videoId}Admin

Altera o título ou a posição de um vídeo

Exige manage_catalog. Atualização parcial: envie só o que muda. Não troca o link nem o arquivo: para isso, remova o vídeo e adicione outro.

Path parameters

iduuidobrigatório
Id do produto.
videoIduuidobrigatório
Id do vídeo. A API usa só este id para achar o vídeo; ela não confere se ele pertence ao produto do caminho.

Corpo da requisição

titlestring
Novo título. Omita para manter.
positioninteger
Nova posição. Não empurra os demais vídeos; para uma ordem exata use a rota de reordenar.

Exemplo de requisição

bash
curl -X PUT "$BASE_URL/api/v1/admin/products/$PRODUCT_ID/videos/$VIDEO_ID" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "title": "Novo título"
}'

Resposta

200Vídeo atualizado
json
{ "message": "updated" }

Um corpo sem title nem position também responde 200 e não altera nada.

Erros

StatusQuandoCorpo
400Corpo inválido.{"error":"invalid request body","detail":"..."}
404O vídeo não existe.{"error":"video not found"}
401 / 403Sem token / sem manage_catalog.{"error":"insufficient privileges","required":"manage_catalog"}

Reordenar os vídeos

POST/api/v1/admin/products/{id}/videos/reorderAdmin

Define a ordem de exibição dos vídeos

Exige manage_catalog. Envie os ids na ordem desejada; o primeiro fica na posição 0. É um POST (e não PUT) nesta rota.

Path parameters

iduuidobrigatório
Id do produto.

Corpo da requisição

video_idsarrayobrigatório
Ids dos vídeos do produto, na ordem final. Ids que não são deste produto são ignorados sem erro. Uma lista vazia não faz nada e responde 200.

Exemplo de requisição

bash
curl -X POST "$BASE_URL/api/v1/admin/products/$PRODUCT_ID/videos/reorder" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "video_ids": [
    "b19e4a07-3c85-42d0-8e6b-5f7a9c1d2e44",
    "7c0d3b52-6e1f-4f8a-9d57-0a4b1c2e8f31"
  ]
}'

Resposta

200Vídeos reordenados
json
{ "message": "reordered" }

Para ver a ordem nova, chame a listagem de novo.

Erros

StatusQuandoCorpo
400Corpo inválido.{"error":"invalid request body","detail":"..."}
500Um id não é um UUID.{"error":"failed to reorder videos","detail":"..."}
401 / 403Sem token / sem manage_catalog.{"error":"insufficient privileges","required":"manage_catalog"}

Remover um vídeo

DELETE/api/v1/admin/products/{id}/videos/{videoId}Admin

Remove a video

Exige manage_catalog. Remove o vídeo da galeria. Se ele era um upload, a plataforma também apaga o arquivo hospedado.

Path parameters

iduuidobrigatório
Id do produto.
videoIduuidobrigatório
Id do vídeo.

Exemplo de requisição

bash
curl -X DELETE "$BASE_URL/api/v1/admin/products/$PRODUCT_ID/videos/$VIDEO_ID" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Vídeo removido
json
{ "message": "deleted" }

Erros

StatusQuandoCorpo
404O vídeo não existe (inclusive ao repetir o DELETE).{"error":"video not found"}
401 / 403Sem token / sem manage_catalog.{"error":"insufficient privileges","required":"manage_catalog"}
O produto do caminho não é conferido

Em PUT e DELETE de vídeo, o que identifica o vídeo é o videoId. A API não verifica se ele pertence ao {id} do caminho. Guarde bem a relação produto-vídeo no seu sistema e não confie nessa checagem para isolar produtos.

Veja também

  • Mídia do produto: visão geral, limites e o mapa das rotas.
  • Imagens do produto
  • Anexos do produto
  • Consultar produto
Anterior
Ordem, giro 360 e remoção de imagens
Próxima
Anexos do produto
Nesta página
  • Listar os vídeos
  • Exemplo de requisição
  • Resposta
  • Erros
  • Adicionar um vídeo
  • Exemplo de requisição (link do YouTube)
  • Resposta
  • Enviar um arquivo (multipart)
  • Erros
  • Editar título e posição
  • Exemplo de requisição
  • Resposta
  • Erros
  • Reordenar os vídeos
  • Exemplo de requisição
  • Resposta
  • Erros
  • Remover um vídeo
  • Exemplo de requisição
  • Resposta
  • Erros
  • Veja também