Catálogo

Variações

Tamanho, cor, montagem: a lista COMPLETA de variações de um produto, numa chamada só.

Todas as páginas▾

Comece aqui

Catálogo

Vendas

Inteligência artificial

Servidor MCP

Parceiros

Referência

GET/v1/products/{id}/variantsOs tipos e as variações do produto.
PUT/v1/products/{id}/variantsSubstitui a lista completa de variações — estado absoluto, numa transação.

Requisição

curl -X PUT https://api.zankhapi.com.br/v1/products/PRODUTO_ID/variants \
  -H "Authorization: Bearer zk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "types": ["Cor", "Montagem"],
    "variants": [
      { "sku": "3DS-985561-PRT-M", "externalId": "985561-1",
        "values": { "Cor": "Preto", "Montagem": "Montado" },
        "regularPriceCents": 8990, "stockQuantity": 3 },
      { "sku": "3DS-985561-PRT-D", "externalId": "985561-2",
        "values": { "Cor": "Preto", "Montagem": "Desmontado" },
        "regularPriceCents": 6990, "stockQuantity": 5 }
    ]
  }'

Campos de cada variação

Campo	Tipo	Descrição
`sku`obrigatório	string	O código da variação — é o que a loja vê na separação.
`values`obrigatório	object	Um valor para CADA nome de `types`, pela grafia exata do tipo, e nada além.
`regularPriceCents`obrigatório	integer	Preço da variação, em centavos.
`stockQuantity`obrigatório	integer	Estoque da variação — é o número que vale para vender.
`externalId`	string	O id da variação no SEU sistema, único na lista. É a primeira chave de casamento. Ausente, o valor guardado é mantido (nunca apagado).
`locationName`	string	O depósito do estoque desta variação. Ausente = mantém o que a loja definiu no painel; `""` = tira o depósito; um nome = move o estoque para lá (nome novo entra em "Locais de estoque").
`compareAtPriceCents / storeInstallmentPriceCents`	integer	Preço “de” e preço parcelado exibido.
`isActive`	boolean	Pausa sem tirar da lista (padrão `true`). A pausada guarda a quantidade enviada, mas só as ativas contam em `sellableStock`.

Como a lista é aplicada

types (até 5) são os eixos, na ordem do seletor da vitrine. O tipo é achado pelo nome na loja (Cor e cor são o mesmo) e criado se faltar; valores são reaproveitados (Preto e preto são um só).
Estado absoluto: campo opcional ausente significa null/true, não "deixa como está" — com duas exceções, externalId e locationName.
Cada variação enviada é casada com uma existente por `externalId`, depois por SKU, depois pela combinação de valores (o que adota combinações criadas no painel e reativa desativadas); o resto é criado.
Variação fora da lista é desativada e zerada — nunca apagada (pedidos antigos apontam para ela). Ela guarda o externalId e o depósito: reenviá-la reativa a mesma variação, no mesmo lugar.
Com pelo menos uma variação ativa, os depósitos do PRÓPRIO produto são removidos na mesma chamada (contariam em dobro) e listados em summary.removedStockLocations — o depósito de uma variação nunca sai por essa regra. A partir daí PUT /stock e stockQuantity respondem 409 product_has_variants.
{ "types": [], "variants": [] } volta o produto a simples (todas desativadas); o estoque volta a ser definido por PUT /stock.
A resposta é { productId, types, variants, summary: { created, updated, reactivated, deactivated, removedStockLocations } }. Repetir o mesmo corpo não muda nada. O GET devolve o mesmo sem summary.
O preço do produto não muda nesta chamada: envie no produto o menor preço ativo (o "a partir de").
Variação não tem foto própria — todas as fotos (inclusive as peças de um kit desmontado) vão nas imageUrls do produto.

Erros

HTTP	Código	O que fazer
404	`product_not_found`	O produto não existe, ou é de outra loja.
409	`variant_combination_conflict`	Um SKU e uma combinação apontam para variações diferentes que já existem — em geral o esquema de SKU mudou. Reenvie com os SKUs anteriores ou arrume a combinação no painel. Traz `skus`. Nada é gravado.
409	`product_managed_by_marketplace`	A loja importou este produto de um marketplace (Shopee, Mercado Livre...), e é essa importação que mantém as variações dele. Um produto tem um dono só: gerencie os seus próprios produtos.
422	`variation_type_not_standard`	O nome do tipo pertence a um tipo de serviço de encordoamento nesta loja — use outro nome.
422	`validation_error`	Variação sem valor para algum tipo, combinação, SKU ou `externalId` repetido, ou número acima de 2147483647 — veja `issues`.