VenddorDocumentação API
API atualAPI legada
Guia rápidoReferência completa
Carregando índice…
API atual/Referência completa/Produtos do seller

Imagens do produto

Adiciona, reordena, define a principal e monta a sequência 360 graus das imagens de um produto do seller.

A galeria de um produto é uma lista ordenada de imagens; uma delas é a principal. As imagens também aparecem no campo images de Consultar produto. Para enviar um arquivo de imagem à loja, use o upload de mídia da plataforma e depois registre aqui o caminho /uploads/... devolvido.

Adicionar imagem

Registra uma imagem na galeria do produto a partir de uma URL. A plataforma não baixa o arquivo nesta chamada: ela guarda e serve a URL. A primeira imagem de um produto vira a principal sozinha.

POST/api/v1/vendor/products/{id}/imagesSeller

Adicionar uma imagem

Cabeçalhos

Authorizationstringobrigatório
Bearer $TOKEN. Token de acesso do usuário seller (veja Tokens).

Parâmetros de caminho

idstring (uuid)obrigatório
Id do produto.

Corpo da requisição

urlstringobrigatório
URL http(s), caminho /uploads/... de um arquivo já enviado à loja, ou data: de imagem (até 5 MB). Outros esquemas são recusados.
alt_textstring
Texto alternativo.
positioninteger
Posição. Omitido, vai para o fim; 0 coloca no início.
is_primaryboolean
true torna esta a imagem principal e desmarca a anterior.

Exemplo de requisição (adicionar)

bash
curl -X POST "$BASE_URL/api/v1/vendor/products/$PRODUCT_ID/images" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "url": "https://cdn.minhaloja.com.br/camiseta-frente.png",
  "alt_text": "Camiseta preta, frente",
  "is_primary": true
}'

Resposta (adicionar)

201Imagem criada
json
{
  "id": "b0b5a3d6-3d1d-4c9e-8b0d-6f1f0a2c7e11",
  "image_url": "/uploads/dfe2555e-bfd0-41a8-9fa1-9586999f3798/product/7bc1d5e9/frente.png",
  "alt_text": "Camiseta preta, frente",
  "position": 0,
  "is_primary": true
}

Campos da resposta

idstring (uuid)
Id da imagem.
image_urlstring
URL da imagem.
alt_textstring
Texto alternativo.
positioninteger
Posição na galeria, a partir de 0.
is_primaryboolean
Se é a imagem principal.

Erros (adicionar)

StatusQuandoCorpo
401Token ausente, inválido ou expirado.{"error":"missing authorization header"}
403Token que não é de seller, ou usuário sem o privilégio exigido pela rota.{"error":"insufficient vendor privileges","privilege_required_any":["vendor_catalog"]}
400url ausente, ou URL recusada (esquema, caminho com .., tipo de imagem fora da lista).{"error":"invalid image url","detail":"..."}
403O produto existe mas é de outro seller (ou da loja).{"error":"you do not have access to this product"}
404Produto não existe.{"error":"product not found"}

Reordenar imagens

Define a ordem de exibição. Envie os ids na ordem desejada; o primeiro fica na posição 0.

PUT/api/v1/vendor/products/{id}/images/reorderSeller

Reordenar as imagens

Cabeçalhos

Authorizationstringobrigatório
Bearer $TOKEN. Token de acesso do usuário seller (veja Tokens).

Parâmetros de caminho

idstring (uuid)obrigatório
Id do produto.

Corpo da requisição

image_idsarray of stringobrigatório
Ids das imagens do produto, na ordem desejada. Id que não é deste produto aborta a operação.

Exemplo de requisição (reordenar)

bash
curl -X PUT "$BASE_URL/api/v1/vendor/products/$PRODUCT_ID/images/reorder" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "image_ids": [
    "b0b5a3d6-3d1d-4c9e-8b0d-6f1f0a2c7e11",
    "e2a4c7d1-61a8-4b53-9a5e-0c8b7f3d2a90"
  ]
}'

Resposta (reordenar)

200Imagens na nova ordem
json
{
  "images": [
    {
      "id": "b0b5a3d6-3d1d-4c9e-8b0d-6f1f0a2c7e11",
      "image_url": "/uploads/dfe2555e-bfd0-41a8-9fa1-9586999f3798/product/7bc1d5e9/frente.png",
      "alt_text": "Camiseta preta, frente",
      "position": 0,
      "is_primary": true
    }
  ],
  "total": 1
}

Campos da resposta

imagesarray
Imagens na nova ordem.
totalinteger
Quantidade de imagens.

Erros (reordenar)

StatusQuandoCorpo
401Token ausente, inválido ou expirado.{"error":"missing authorization header"}
403Token que não é de seller, ou usuário sem o privilégio exigido pela rota.{"error":"insufficient vendor privileges","privilege_required_any":["vendor_catalog"]}
400image_ids ausente ou vazio.{"error":"image_ids is required"}
403O produto existe mas é de outro seller (ou da loja).{"error":"you do not have access to this product"}
404Produto não existe.{"error":"product not found"}
500Id de imagem de outro produto ou inexistente.{"error":"failed to reorder images","detail":"..."}

Imagem principal

Marca uma imagem como principal: é a que aparece na lista e na página do produto. As outras perdem a marca.

PUT/api/v1/vendor/products/{id}/images/{imageId}/primarySeller

Definir a imagem principal

Cabeçalhos

Authorizationstringobrigatório
Bearer $TOKEN. Token de acesso do usuário seller (veja Tokens).

Parâmetros de caminho

idstring (uuid)obrigatório
Id do produto.
imageIdstring (uuid)obrigatório
Id da imagem.

Exemplo de requisição (principal)

bash
curl -X PUT "$BASE_URL/api/v1/vendor/products/$PRODUCT_ID/images/$IMAGE_ID/primary" \
  -H "Authorization: Bearer $TOKEN"

Resposta (principal)

200Imagem principal atualizada
json
{
  "message": "primary image updated"
}

Campos da resposta

messagestring
Confirmação fixa.

Erros (principal)

StatusQuandoCorpo
401Token ausente, inválido ou expirado.{"error":"missing authorization header"}
403Token que não é de seller, ou usuário sem o privilégio exigido pela rota.{"error":"insufficient vendor privileges","privilege_required_any":["vendor_catalog"]}
403O produto existe mas é de outro seller (ou da loja).{"error":"you do not have access to this product"}
404Produto não existe.{"error":"product not found"}
500Imagem não existe.{"error":"failed to set primary image","detail":"image not found"}

Sequência 360 graus

Escolhe quais imagens já enviadas formam a visualização giratória (360 graus) do produto, e em que ordem. A sequência anterior é totalmente substituída; envie lista vazia para remover o giro.

PUT/api/v1/vendor/products/{id}/images/spin-groupSeller

Montar a sequência 360 graus

Cabeçalhos

Authorizationstringobrigatório
Bearer $TOKEN. Token de acesso do usuário seller (veja Tokens).

Parâmetros de caminho

idstring (uuid)obrigatório
Id do produto.

Corpo da requisição

image_idsarray of stringobrigatório
Ids de imagens do produto, na ordem dos quadros. Ids de outro produto são ignorados.

Exemplo de requisição (360)

bash
curl -X PUT "$BASE_URL/api/v1/vendor/products/$PRODUCT_ID/images/spin-group" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "image_ids": [
    "b0b5a3d6-3d1d-4c9e-8b0d-6f1f0a2c7e11",
    "e2a4c7d1-61a8-4b53-9a5e-0c8b7f3d2a90"
  ]
}'

Resposta (360)

200Sequência gravada
json
{
  "ok": true
}

Campos da resposta

okboolean
Sempre true em caso de sucesso.

Erros (360)

StatusQuandoCorpo
401Token ausente, inválido ou expirado.{"error":"missing authorization header"}
403Token que não é de seller.{"error":"insufficient permissions"}
403Produto não é do seu seller.{"error":"not your product"}
400Corpo inválido.{"error":"invalid request body","detail":"..."}
Confira o id da imagem

Em PUT .../images/{imageId}/primary a plataforma valida o produto do caminho, mas aplica a marca ao produto dono da imagem. Mande sempre um imageId que você acabou de ler da galeria deste mesmo produto.

Excluir imagem

A exclusão de imagem é DELETE /api/v1/vendor/images/{id}, uma rota fora do caminho do produto que apaga a imagem se ela for de um produto seu.

Veja também

  • Produtos do seller: visão geral
Anterior
Importar e exportar CSV
Próxima
Vídeos do produto
Nesta página
  • Adicionar imagem
  • Exemplo de requisição (adicionar)
  • Resposta (adicionar)
  • Erros (adicionar)
  • Reordenar imagens
  • Exemplo de requisição (reordenar)
  • Resposta (reordenar)
  • Erros (reordenar)
  • Imagem principal
  • Exemplo de requisição (principal)
  • Resposta (principal)
  • Erros (principal)
  • Sequência 360 graus
  • Exemplo de requisição (360)
  • Resposta (360)
  • Erros (360)
  • Veja também