Imagens e Redimensionamento¶

A Gubee mantém um serviço interno de redimensionamento de imagens exposto via BFF em /integration/images/*. Pode ser usado por parceiros para:

Adequar imagens de produtos aos tamanhos exigidos por cada marketplace (ML exige 1000×1000+ para galeria, Shopee 800×800+ etc)
Gerar thumbnails próprios para exibição em sites/apps
Converter formatos (JPG ↔ PNG ↔ WebP)

Endpoints¶

1. Redimensionar — retorna binário¶

Retorna o binário da imagem já redimensionada. Útil para uso imediato (server-side caching recomendado).

GET https://api.gubee.com.br/integration/images/resize/url/{sellerId}/{dimensions}

Path params:

Param	Descrição
`sellerId`	Seu identificador de seller
`dimensions`	Tamanho alvo no formato `{width}X{height}` (ex.: `1500X1500`)

Query params:

Param	Tipo	Default	Descrição
`url`	String (URL encoded)	—	URL da imagem original a redimensionar
`format`	Enum	`png`	Formato de saída: `png`, `jpeg`, `webp`, `gif`
`minWidth`	Int	0	Largura mínima (0 = sem mínimo)
`maxWidth`	Int	0	Largura máxima (0 = sem máximo)
`minHeight`	Int	0	Altura mínima
`maxHeight`	Int	0	Altura máxima

Se você especificar min/max, o serviço redimensiona preservando aspect ratio dentro dos limites (em vez de forçar exatamente {width}X{height}).

2. Redimensionar — retorna URL pré-assinada¶

Retorna uma URL pública (válido ~1h) para a imagem redimensionada armazenada em bucket da Gubee. Útil para passar a URL diretamente para <img src=...> no frontend sem baixar o binário no seu servidor.

GET https://api.gubee.com.br/integration/images/resize/url/{sellerId}/{dimensions}/presigned

Mesmos path params e query params do endpoint anterior.

Exemplos¶

Redimensionar para 1500×1500 PNG (binário)¶

# Retorna binário (application/octet-stream)
curl -s 'https://api.gubee.com.br/integration/images/resize/url/SEU_SELLER_ID/1500X1500' \
  -H 'Authorization: Bearer $JWT' \
  -G \
  --data-urlencode 'url=https://exemplo.com/produto-1.jpg' \
  --data 'format=png' \
  -o produto-1-1500x1500.png

Redimensionar com limites (preserva aspect ratio)¶

# Força estar entre 800×800 e 1200×1200 (retorna URL presigned)
curl -s 'https://api.gubee.com.br/integration/images/resize/url/SEU_SELLER_ID/800X800/presigned' \
  -H 'Authorization: Bearer $JWT' \
  -G \
  --data-urlencode 'url=https://exemplo.com/produto-1.png' \
  --data 'format=JPEG' \
  --data 'minWidth=800' \
  --data 'maxWidth=1200' \
  --data 'minHeight=800' \
  --data 'maxHeight=1200'

Retorna texto simples com a URL pré-assinada:

https://media.gubee.com.br/resized/abc123.jpg?X-Amz-Signature=...

Erros comuns¶

HTTP	Causa
`400`	URL da imagem original inválida ou inacessível
`404`	Imagem original não encontrada (404 do servidor de origem)
`422`	Formato de saída não suportado (use `png`, `jpeg`, `webp`, `gif`)
`504`	Timeout baixando a imagem original (>15s)

Quando usar¶

Cenário	Recomendado
Marketplace exige dimensão específica (ML: 1000×1000+)	Redimensionar 1× ao criar produto/anúncio, armazenar resultado
Exibir thumbnails dinâmicos no seu app	Endpoint presigned (URL cacheável no frontend)
Conversão em lote	Loop com taxa máxima 5 req/s

Rate limit¶

Máximo recomendado: 5 requisições/segundo por seller
Cada redimensionamento é custoso (CPU + IO); abuso pode resultar em 429
Use cache no seu lado: a mesma URL + dimensões retorna sempre a mesma imagem, então cacheie por (url_original, dimensoes, formato) por 24h+.

Próximos passos¶

Upload de Vídeo: fluxo de mídia diferente (vídeos via presigned PUT + commit).
Ad vs Produto: como images[] na variação é gerenciada (CRUD via POST/PUT/DELETE/PATCH em /integration/products/{externalId}/variations/{skuId}/images/*).