Catálogo

Produtos

Criar, atualizar, listar e desativar produtos — o caminho para subir um catálogo inteiro.

Todas as páginas▾

Comece aqui

Catálogo

Vendas

Inteligência artificial

Servidor MCP

Parceiros

Referência

O catálogo é a razão de existir desta API. São cinco rotas, e a listagem é a que evita o erro mais caro de uma importação: duplicar o que já está lá.

GET/v1/productsLista produtos. Filtros: query (nome ou SKU), active=true|false, page, pageSize.
POST/v1/productsCria um produto. 201 no sucesso.
GET/v1/products/{id}Um produto, com imagens e estoque por depósito.
PATCH/v1/products/{id}Atualização parcial — só os campos enviados mudam.
DELETE/v1/products/{id}Desativa o produto (exclusão lógica).
PUT/v1/products/{id}/stockDefine o estoque absoluto de um depósito.

Criar um produto

Requisição

curl -X POST https://api.zankhapi.com.br/v1/products \
  -H "Authorization: Bearer zk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Placa de vídeo RTX 4070",
    "sku": "GPU-4070",
    "regularPriceCents": 349990,
    "compareAtPriceCents": 399990,
    "shortDescription": "12GB GDDR6X",
    "imageUrl": "https://exemplo.com/rtx4070.jpg",
    "stockQuantity": 5
  }'

Campos do produto

Campo	Tipo	Descrição
`name`obrigatório	string	O nome do produto.
`regularPriceCents`obrigatório	integer	Preço de venda em centavos.
`slug`	string	O endereço do produto na vitrine. Gerado a partir do nome quando omitido.
`sku`	string	O seu código interno. É por ele que a sua próxima importação reencontra o item.
`shortDescription`	string	Uma linha, mostrada nas listagens.
`longDescriptionHtml`	string	A descrição completa da página do produto.
`compareAtPriceCents`	integer	O preço “de”, riscado. Envie `null` num `PATCH` para encerrar a promoção.
`storeInstallmentPriceCents`	integer	Preço parcelado exibido. Não altera o que é cobrado no checkout.
`imageUrl`	string	URL pública da foto principal. A zankh copia a imagem para o armazenamento dela.
`stockQuantity`	integer	Estoque inicial. Depois disso use `PUT /stock`.
`stockLocationName`	string	O depósito do estoque. Omitido, usa o padrão da loja.
`isActive`	boolean	Se o produto aparece na vitrine. Padrão `true`.
`isPurchasable`	boolean	Se aceita compra. Um produto ativo e não comprável fica visível como vitrine.

Atualizar

PATCH é parcial: o que você não enviar fica como está. É o que permite um script de preço mexer só em preço, sem arrastar a descrição junto.

curl -X PATCH https://api.zankhapi.com.br/v1/products/PRODUTO_ID \
  -H "Authorization: Bearer zk_live_..." \
  -H "Content-Type: application/json" \
  -d '{ "regularPriceCents": 329990, "compareAtPriceCents": null }'

Desativar, não apagar

DELETE é exclusão lógica: o produto sai da vitrine e continua existindo para os pedidos que já o referenciam. Um pedido do mês passado não pode ficar sem saber o que foi vendido — por isso não existe exclusão física nesta API.

Subir um catálogo inteiro

Liste o que já existe (GET /v1/products?pageSize=200) e case pelo seu sku.
Crie o que falta, um `POST` por produto — não existe rota em lote no v1.
Para o que já existe, mande PATCH só com o que mudou.
Trate 409 slug_taken: já há um produto com esse endereço na sua loja. Envie um slug explícito ou reaproveite o produto existente.