Imagens

Cada Product pode ter múltiplas imagens. Uma é marcada como isDefault: true e aparece em hosted checkout, fatura por email, link de compartilhamento e OG tags.

Upload

Endpoint: POST /v1/products/:id/images (multipart)

curl -X POST https://prometheus.zhex.io/v1/products/prd_xyz/images \
  -H "Authorization: Bearer $ZHEX_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -F "files=@hero.jpg" \
  -F "is_default=true"

Limites

Imagem default

is_default: true substitui automaticamente a default anterior — você não precisa chamar update extra.

A imagem default aparece em:

• Hosted checkout (lado esquerdo, hero do produto)
• Email de fatura (cabeçalho)
• Link de compartilhamento (OG image em redes sociais)
• App mobile do cliente (lista de transações)

Sem imagem default, o checkout usa um placeholder genérico — converte ~12% pior em A/B testing interno.

Ordem das imagens

A ordem das imagens é controlada via campo existing_image_ids[] em endpoint multipart dedicado para gestão de mídia (em desenvolvimento — ver nota abaixo).

// Em breve: POST /v1/products/:id/images (multipart/form-data)
// Forma planejada do payload:
//
// existing_image_ids = ['img_2', 'img_1', 'img_3']  // ordem desejada
// new_images = [File, File, ...]                    // novas imagens via multipart
//
// img_2 vira a primeira da galeria; imagens fora da lista são desativadas
// (`deactivated_at = now`). Nunca são apagadas: histórico de transação
// preserva a URL original.

Status: o endpoint de upload e reordenação de imagens é exposto hoje apenas em superfície interna (dashboard). A versão pública sob /v1/... será publicada junto com o serviço /v1/files. Até lá, manipule imagens via dashboard.

Substituir imagem default

import { randomUUID } from 'node:crypto';

const formData = new FormData();
formData.append('files', newHeroFile);
formData.append('is_default', 'true');

await fetch(`https://prometheus.zhex.io/v1/products/${id}/images`, {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.ZHEX_SECRET_KEY}`,
    'Idempotency-Key': randomUUID(),
  },
  body: formData,
});
// A default anterior fica como imagem secundária automaticamente

Remover imagem

// Em breve: POST /v1/products/:id/images (multipart/form-data)
// Forma planejada do payload:
//
// removed_image_ids = ['img_old']                       // desativa essas
// existing_image_ids = ['img_keep_1', 'img_keep_2']     // ordem das que ficam
//
// Imagens fora de `existing_image_ids` são desativadas (`deactivated_at = now`)
// — nunca apagadas, para preservar histórico de transação.

Status: o endpoint público de remoção/manutenção de imagens não está exposto sob /v1/... ainda. Use o dashboard até a publicação de /v1/files.

Boas práticas

• Imagem default em 1200×800 (3:2). Crop automático em outras proporções pode cortar texto.
• Sem texto pesado na imagem. Hosted checkout já mostra Product.name e description ao lado.
• WebP > JPEG > PNG. WebP economiza ~30% banda no checkout mobile.
• Não use stock genérico. A Zhex faz pHash similarity check — imagens repetidas em N produtos diferentes (multiplos merchants) levam o produto a PENDING por mais tempo.
• Para PHYSICAL, suba 4–6 imagens (frente, verso, embalagem, in-use). Aumenta conversão em ~22% no funil.