Guia do Seller — Criar e Publicar Produto

Guia completo para um seller criar e publicar um produto. O seller trabalha sobre o catálogo já configurado pelo admin — ele não cria ProductTypes, Assets ou Templates.

Visão geral

Upload da artwork

Use o fluxo de presign para fazer upload da arte.

Endpoints:

POST /uploads/artworks/presign                    — pedir URL de upload
POST /uploads/artworks/{artworkId}/complete        — confirmar e criar registro

Criar produto

O SellerProduct é criado já com pelo menos 1 variante.

aviso

A criação NÃO gera renders automaticamente. O seller deve configurar o placement e disparar o render explicitamente.

POST /seller-products/me

{
  "productTypeId": "uuid-product-type",
  "artworkId": "uuid-artwork",
  "title": "Caneca Arte Abstrata",
  "slug": "caneca-arte-abstrata",
  "description": "Caneca com arte exclusiva",
  "variants": [
    {
      "productVariantId": "uuid-variante-350ml-glossy",
      "priceCents": 4990,
      "allowedOptions": {
        "color": ["black", "white", "red", "blue"]
      }
    },
    {
      "productVariantId": "uuid-variante-350ml-matte",
      "priceCents": 4990,
      "allowedOptions": {
        "color": ["black", "white"]
      }
    }
  ]
}

Campos do produto

Campo	Obrigatório	Descrição
`title`	Sim	Nome do produto
`slug`	Não	Slug para URL. Auto-convertido para lowercase
`description`	Não	Descrição do produto

Campos da variante

Campo	Obrigatório	Descrição
`productVariantId`	Sim	UUID da ProductVariant do catálogo
`priceCents`	Sim	Preço de venda em centavos
`allowedOptions`	Não	Quais options permitir. `{}` = todas
`sku`	Não	SKU do seller (controle próprio)

Regras do allowedOptions

Cenário	O que acontece
`{}` (vazio)	Herda todas as options ativas do ProductType
`{"color": ["black", "white"]}`	Comprador só pode escolher preto ou branco
`{"color": []}`	Erro 400 se `color` é required
`{"corErrada": ["x"]}`	Erro 400 — key não existe
`{"color": ["roxo"]}`	Erro 400 — value não existe

Adicionar variante depois

POST /seller-products/me/{sellerProductId}/variants

{
  "productVariantId": "uuid-variante-700ml-glossy",
  "priceCents": 6990,
  "allowedOptions": { "color": ["black", "blue"] }
}

Criar para terceiros (admin)

POST /seller-products/admin

Mesma lógica, mas inclui sellerProfileId no body.

Renders

Conceito

O render não é automático. O seller decide quais templates renderizar e controla o posicionamento.

Sistema de coordenadas

Todas as coordenadas são em pixels do sourceImage, com referência no canto superior esquerdo da arte (igual ao Figma).

Campo	Unidade	Descrição
`x`	px	Posição X do canto superior esquerdo da arte
`y`	px	Posição Y do canto superior esquerdo da arte
`scale`	multiplicador	`1.0` = tamanho original, `0.5` = metade
`rotation`	graus	Sentido horário. `0` = sem rotação

Pré-visualização (sem salvar)

POST /products/templates/{templateId}/preview-placement

{
  "artworkId": "uuid-da-artwork",
  "x": 95,
  "y": 110,
  "scale": 0.14,
  "rotation": 0
}

Retorna imagem PNG diretamente. Headers de resposta indicam fit:

Header	Descrição
`X-Fits-Within-Print-Area`	`true` ou `false`
`X-Overflow-Top/Right/Bottom/Left`	Overflow em pixels por direção
`X-Bleed-Tolerance`	Tolerância aceita em pixels (ex: `{"width": 4, "height": 4}`)
`X-Artwork-Bounds`	Bounding box da arte (JSON)
`X-Print-Area-Bounds`	Retângulo da printArea (JSON)

Disparar render

POST /seller-products/me/{sellerProductId}/render

{
  "templateId": "caneca-350ml-preta-v1",
  "x": 95,
  "y": 110,
  "scale": 0.14,
  "rotation": 0
}

O que acontece:

Valida que o template existe
Valida que a arte cabe na printArea (tolerância de 5% de sangria). Se não cabe, retorna 400 com detalhes do overflow em pixels por lado
Cria/atualiza o placement
Gera o mockup (compõe arte + layers)
Salva no S3 como WebP
Cria/atualiza o registro de Render no banco
Retorna o produto com todos os renders

:::tip Consistência O preview-placement e o render usam exatamente a mesma função de validação. Se o preview aprova, o render aceita. :::

:::warning PUT /artworks/.../placements/{templateId} NÃO dispara re-render Atualizar o placement via PUT só atualiza os valores de posicionamento no banco. Para gerar a imagem com o novo posicionamento, chame POST /seller-products/me/{sellerProductId}/render novamente. :::

Endpoints alternativos de render (via artwork)

Quando você quer gerar render sem passar pelo SellerProduct (ex: admin gerando render direto da artwork):

POST /artworks/{artworkId}/renders        — 1 template
POST /artworks/{artworkId}/renders/batch  — vários templates de uma vez

Estes retornam a lista de renders gerados (não o produto inteiro). Placement é por (artwork, template) — não por variante — então um mesmo render pode aparecer em múltiplas variantes cujo template casa por subset.

Publicar

O produto é criado com status draft. Para publicar:

PATCH /seller-products/me/{sellerProductId}

{ "status": "active" }

Validações ao ativar:

Produto deve ter um slug
Produto deve ter pelo menos um render

Ciclo de vida

Status	Visível na loja	Descrição
`draft`	Não	Sendo configurado (default)
`active`	Sim	Publicado e à venda
`paused`	Não	Temporariamente oculto
`archived`	Não	Soft delete

Preview antes de publicar

GET /seller-products/me/{sellerProductId}/preview

Retorna o mesmo formato do endpoint público — funciona para qualquer status.

Referência de endpoints

Artwork

POST   /uploads/artworks/presign                    — pedir URL de upload
POST   /uploads/artworks/{artworkId}/complete        — confirmar upload
GET    /artworks/me                                  — listar minhas artes
GET    /artworks/{artworkId}                         — obter por ID
PATCH  /artworks/{artworkId}                         — atualizar
DELETE /artworks/{artworkId}                         — desativar
GET    /artworks/check-slug?slug=minha-arte          — verificar slug
GET    /artworks/{artworkId}/placements              — listar placements
PUT    /artworks/{artworkId}/placements/{templateId} — criar/atualizar placement (NÃO dispara render)
GET    /artworks/{artworkId}/renders                 — listar renders
POST   /artworks/{artworkId}/renders                 — gerar render (1 template)
POST   /artworks/{artworkId}/renders/batch           — gerar renders (vários)

Públicos (sem autenticação):

GET /artworks/public/{artworkId}                   — detalhes da arte
GET /artworks/public/by-slug/{artistSlug}/{slug}   — por slug
GET /artworks/public/{artworkId}/products          — produtos usando essa arte
GET /artworks/public/related/artist/{artistSlug}   — artes relacionadas do artista

Seller Product

POST   /seller-products/me                                         — criar produto
GET    /seller-products/me                                         — listar meus produtos
GET    /seller-products/me/{id}                                    — obter produto
PATCH  /seller-products/me/{id}                                    — atualizar
POST   /seller-products/me/{id}/variants                           — adicionar variante
PATCH  /seller-products/me/{id}/variants/{variantId}               — atualizar variante
DELETE /seller-products/me/{id}/variants/{variantId}                — desativar variante
POST   /seller-products/me/{id}/variants/generate-skus             — gerar SKUs
POST   /seller-products/me/{id}/render                             — render template
GET    /seller-products/me/{id}/preview                            — preview página pública
DELETE /seller-products/me/{id}                                    — arquivar (soft delete)
DELETE /seller-products/admin/{sellerProductId}                    — deletar permanentemente (admin only)

Visão geral​

Upload da artwork​

Criar produto​

Campos do produto​

Campos da variante​

Regras do allowedOptions​

Adicionar variante depois​

Criar para terceiros (admin)​

Renders​

Conceito​

Sistema de coordenadas​

Pré-visualização (sem salvar)​

Disparar render​

Endpoints alternativos de render (via artwork)​

Publicar​

Ciclo de vida​

Preview antes de publicar​

Referência de endpoints​

Artwork​

Seller Product​