VenddorDocumentação API
API atualAPI legada
Guia rápidoReferência completa
Carregando índice…
API atual/Referência completa/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

Resposta

200Vídeos do produto

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)

Resposta

201Vídeo criado

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.

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

Resposta

200Vídeo atualizado

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

Resposta

200Vídeos reordenados

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

Resposta

200Vídeo removido

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
bash
curl "$BASE_URL/api/v1/admin/products/$PRODUCT_ID/videos" \
  -H "Authorization: Bearer $TOKEN"
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"
}'
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"
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"
}'
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"
  ]
}'
bash
curl -X DELETE "$BASE_URL/api/v1/admin/products/$PRODUCT_ID/videos/$VIDEO_ID" \
  -H "Authorization: Bearer $TOKEN"
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
    }
  ]
}
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
}
json
{ "message": "updated" }
json
{ "message": "reordered" }
json
{ "message": "deleted" }