Produtos

Um produto no Mobiari é algo que você vende na sua loja. Todo produto tem uma ou mais variantes. Até um produto "simples" tem uma variante padrão oculta por baixo dos panos, então preço e estoque ficam sempre na variante, nunca no próprio produto.

Modelo mental

product                              ← title, description, brand, SEO
├── variants[]                       ← sku, price_cents, stock, fulfillment_mode
│   ├── option_values[]              ← e.g. size=M, color=blue
│   └── shipping_box                 ← physical box for freight calc
├── product_images[]                 ← gallery items (images and videos)
│   └── image_variants[]             ← srcset sizes (thumbnail/small/medium/large)
├── highlight_video                  ← one short video → bottom-left widget on PDP
├── product_specs[]                  ← long-form specs (key/value, grouped)
└── reviews[]

Alguns termos importantes:

product_type: "single" (uma única configuração) ou "variable" (várias variantes com opções). Define como o painel administrativo se comporta.
fulfillment_mode na variante: stocked, on_demand ou stocked_or_on_demand. Decide se a disponibilidade é calculada a partir do estoque ou se o item é sempre tratado como "em estoque".
media_type em um item da galeria: "image" (padrão) ou "video". Itens de imagem passam pelo pipeline de redimensionamento; itens de vídeo pulam essa etapa e apontam direto para a URL.

Endpoints

Todos os caminhos abaixo são relativos a https://api.mobiari.com/v1/stores/{store_id}.

Método	Caminho	Finalidade
`GET`	`/products`	Lista paginada. Veja Listagem.
`POST`	`/products`	Cria. Retorna o novo `id`, o `title` e o `slug`.
`GET`	`/products/{id}`	Um produto com variantes e estoque.
`PUT`	`/products/{id}`	Atualiza. Os campos que você omitir não são alterados.
`DELETE`	`/products/{id}`	Exclusão definitiva. Remove também variantes e galeria.
`GET`	`/products/{id}/images`	Galeria completa com as variações (tamanhos).
`POST`	`/products/{id}/images`	Envia uma imagem (multipart).
`POST`	`/products/{id}/images/associate`	Vincula um arquivo que já está na biblioteca.
`POST`	`/products/{id}/videos`	Vincula um vídeo por URL (próxima seção).
`PATCH`	`/products/{id}/images/{img_id}`	Reordena, define como principal, troca o texto alternativo.
`DELETE`	`/products/{id}/images/{img_id}`	Remove um item da galeria.

Criar um produto

curl -X POST "https://api.mobiari.com/v1/stores/$STORE_ID/products" \
  -H "Authorization: Bearer $BP_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "title": "Iced Matcha",
    "description": "Stone-ground ceremonial grade.",
    "product_type": "single",
    "default_price_cents": 1890
  }'

Quando você envia default_price_cents, produtos simples ganham uma variante "Default" oculta, criada na mesma transação. Para produtos variáveis, omita default_price_cents e crie cada variante com POST /v1/product-variants, enviando product_id, sku, title e price_cents no corpo.

Envie um Idempotency-Key nas criações para que uma requisição repetida não crie o produto duas vezes. Veja Idempotência.

Vincular um vídeo de destaque

Um produto pode ter um vídeo de destaque: um clipe curto que a loja virtual exibe como um pequeno widget flutuante no canto inferior esquerdo da página do produto. Ao clicar, ele abre em tela cheia com som.

Defina o vídeo no próprio produto, não na galeria:

curl -X PUT "https://api.mobiari.com/v1/stores/$STORE_ID/products/$PRODUCT_ID" \
  -H "Authorization: Bearer $BP_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "highlight_video_url": "https://youtu.be/abc123",
    "highlight_video_poster_url": "https://files.example.com/poster.jpg"
  }'

O provedor (youtube, vimeo, upload, external) é detectado automaticamente a partir da URL. Você pode sobrescrevê-lo definindo highlight_video_provider explicitamente.

Adicionar um vídeo à galeria

Os vídeos da galeria ficam ao lado das imagens da galeria e são úteis para apresentar o produto, mostrar "como é feito" ou demonstrar caimento e tamanhos. Diferente do vídeo de destaque, eles tocam ao clicar dentro da galeria, em vez de aparecer em um widget com reprodução automática.

curl -X POST "https://api.mobiari.com/v1/stores/$STORE_ID/products/$PRODUCT_ID/videos" \
  -H "Authorization: Bearer $BP_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://files.example.com/video.mp4",
    "poster_url": "https://files.example.com/poster.jpg",
    "position": 2
  }'

Se você definir product_variant_id na requisição, o vídeo só aparece quando essa variante está selecionada na página do produto, a mesma regra das imagens vinculadas a uma variante.

Listagem

Os produtos são ordenados por priority (crescente) e, em seguida, pelos atualizados mais recentemente. Filtros:

Parâmetro de query	Significado
`search`	Trecho do título ou do `sku_prefix`, sem diferenciar maiúsculas e minúsculas.
`status`	Somente produtos neste status.
`include_drafts`	Rascunhos ficam ocultos, a menos que seja `true` (ou que você filtre por `status`).
`limit`, `offset`	Paginação. `limit` vai de 1 a 200, padrão 50.

curl "https://api.mobiari.com/v1/stores/$STORE_ID/products?search=matcha" \
  -H "Authorization: Bearer $BP_TOKEN"

Migração para o envelope Page

A listagem de produtos está sendo migrada para a resposta padrão Page (data, has_more, next_cursor) com paginação por cursor. Até Produtos aparecer na referência da API, ela responde {"products": [...], "total": ..., "page": ...}.

Resumo de permissões

Ação	Permissão
Listar, consultar	`products.read`
Criar	`products.write`
Atualizar, vincular mídia	`products.edit`
Excluir	`products.delete`
Publicar (status → ativo)	`products.publish`