O processo de criação de produtos dentro da VTEX envolve múltiplos passos obrigatórios e quem em alguns casos devem ser feitos em uma ordem específica. Devido a isso, temos um tutorial completo sobre Catálogo em nosso Help Center e disponibilizamos múltiplas formas para adicionar produtos a uma loja. Neste tutorial, compartilho um passo a passo de quais requests devem ser utilizados para a criação de produtos via API, utilizando os endpoints disponibilizados pela VTEX em nossa documentação de APIs.
Se você tem dúvidas sobre o que é uma API e quais são suas funcionalidades, veja nosso tutorial Dúvidas Frequentes: O que são APIs, quais seus métodos e como funcionam?. Por outro lado, se você tem dúvidas sobre como começar a utilizar APIs como as descritas abaixo, veja nosso tutorial Dúvidas Frequentes: Como utilizar APIs?. Após seguir os passos lá listados, você pode utilizar os requests na seguinte ordem:
1- Criar Produto
O primeiro passo obrigatório da criação de um produto é, obviamente, a criação do produto em si através do request Create product with category and brand. Conforme sua documentação, esta API permite a criação simultânea de um Produto, uma Categoria e uma Marca (sendo as duas últimas uma informação essencial e obrigatória para a criação de um Produto) e descrevo abaixo os campos disponíveis para tal cenário:
Id- Identificador númerico do Produto. Se não informado, um número será gerado automaticamente.Name- Nome do Produto. Campo obrigatório e com valor máximo de 150 caractéres.CategoryPath- Mapeamento da categoria dentro da árvore de categorias, feito com os nomes de cada categoria em ordem hierárquica separados por/(ex: Departamento/Categoria/Sub-Categoria). O último valor deve ser o nome da nova categoria. Campo obrigatório se uma nova categoria está sendo criada.DepartmentId- Identificador númerico do departamento desejado para a categoria. Para mais detalhes, veja nossa documentação sobre Departamentos.BrandName- Nome da Marca. Campo obrigatório se uma nova marca está sendo criada.LinkId- Rota da URL do produto. Se não informado, uma rota será gerada automaticamente com o nome do produto.RefId- Código de referência do produto, para identificação externa. Deve ser único.IsVisible- Flag de visibilidade do produto. Se o valor estiver como falso (false) o produto não aparecerá na busca, em vitrines ou na página de produto, mas ainda pode ser adicionado ao carrinho.Description- Descrição do Produto. Pode conter formatação em HTML.DescriptionShort- Descrição resumida do Produto, que pode ser exibida em sessões específicas do front end com os controles$product.DescriptionShort(para VTEX IO) e<vtex.cmc:productDescriptionShort/>(para CMS Legado)ReleaseDate- Data de lançamento do produto. Afeta a ordenação por lançamento e pode ser uma condição para coleções.Title- Título do produto que aparecerá na aba do navegador. Valor máximo de 150 caractéres e relevante para SEO.IsActive- Flag de ativação do produto. Se o valor estiver como falso (false) o produto não ficará visível no site e não poderá ser adicionado ao carrinho.TaxCode- Código fiscal. Valor máximo de 150 caractéres e relevante para SEO.MetaTagDescription- Descrição curta de produto. Relevante para SEO. Não é recomendado ultrapassar 150 caractéres.ShowWithoutStock- Define se a página de produto ficará visível se o produto não tiver estoque. Se o valor estiver como verdadeiro (true) a página de produto terá uma opção de “Avise-me quando houver estoque.”Score- Valor numérico que define a prioridade do produto.
Enquanto isso, se você já tiver criado uma categoria e uma marca, todos os campos acima podem ser utilizados exceto os campos CategoryPath e BrandName. Em seu lugar, utilize os seguintes campos:
CategoryId- Identificador numérico da Categoria ao qual o Produto fará parte.BrandId- Identificador numérico da Marca a qual o Produto fará parte.
2- Criar SKU
Após a criação do Produto, é necessário que pelo menos um SKU seja criado e associado a este Produto. Para tal fim, o request Create SKU pode ser utilizado. Segue abaixo uma descrição dos diferentes campos disponíveis para esta API:
-
Id- Identificador númerico do SKU. Se não informado, um número será gerado automaticamente. -
ProductId- Id do Produto criado no passo anterior. Campo Obrigatório. -
ActivateIfPossible- Flag que define que o SKU deve ser ativado se possível. Recomendamos que seja definido como verdadeiro (true) exceto se houver um fluxo interno para ativação de SKUs. -
Name- Nome do SKU. Campo obrigatório e com valor máximo de 200 caractéres. Este campo será adicionado ao nome do Produto, na página de produto (ex: Nome de Produto = “Camiseta”, Nome de SKU = “Azul”, Nome final = “Camiseta Azul”) -
RefId- Código de referência do produto, para identificação externa. Deve ser único. -
Ean- Código de identificação único do SKU (código de barras), aceita até 13 caracteres numéricos. Os campos RefId e Ean podem ser utilizados em conjunto e pelo menos um destes campos deve estar preenchido obrigatóriamente. -
PackagedHeight- Altura utilizada no cálculo de logística. Campo numérico e obrigatório. -
PackagedLength- Comprimento utilizado no cálculo de logística. Campo numérico e obrigatório. -
PackagedWidth- Largura utilizada no cálculo de logística. Campo numérico e obrigatório. -
PackagedWeightKg- Peso utilizado no cálculo de logística. Campo numérico e obrigatório. Este campo e todos os outros campos de logística acima devem ter um valor maior do que 0 para pleno funcionamento do módulo de logística. -
Height- Altura real do SKU. -
Length- Comprimento real SKU -
Width- Largura real do SKU -
WeightKg- Peso real do SKU. Todos os valores de tamanho e peso acima utilizam as unidades de medida definidas nas Configurações da Loja. -
CubicWeight- Peso cúbico, conforme definido em nosso tutorial sobre fator cúbico de peso. -
IsKit- Define se o SKU em questão é composto de um ou mais SKUs (parte de um kit. Obrigatório se o SKU criado for um kit e, depois de definido, não pode ser alterado. -
CreationDate- Dia e data de criação do SKU. Segue o formatoAAAA-MM-DDTHH:MM:SS(ex: 2023-01-25T15:51:29) -
RewardValue- Crédito que o cliente recebe ao concluir uma compra de 1 unidade de um determinado SKU. Ao colocar “1,00” neste campo, o cliente ganha um crédito de R$ 1,00 no site. Para mais detalhes, veja nossa documentação sobre Programa de Fidelidade. -
EstimatedDateArrival- Data de lançamento do SKU. Utilizado para configurar pré-vendas. -
ManufacturerCode- Fornecido pelo fabricante para identificar seu produto. Caso algum produto tenha um código específico, esse campo deve se preenchido. -
CommercialConditionId- Identificador número de condição comercial, se houver. Utilizar o valor1caso não haja nenhuma condição comercial desejada. Mais detalhes em nossa documentação sobre Condições Comerciais. -
MeasurementUnit- Unidade de medida do SKU, utilizável em cenários específicos. Os valores disponíveis são metro quadrado (m²) E unidade (un). -
UnitMultiplier- Multiplicador de unidade, para cenários em que o SKU deve ser comprado em pacotes com múltiplas unidades. -
ModalType- relaciona um produto não usual a uma transportadora especializada na entrega desse tipo de produto. Para saber mais sobre essa funcionalidade, leia nossos artigos Como funciona o modal e Configurar modal para transportadoras. -
KitItensSellApart- Flag que define se componentes de um kit podem ser vendidos separadamente. Não preencher se o produto não for um Kit. -
Videos- Permite a inserção de URLs de video no SKU, adicionados entre colchetes ([ URL1, URL2])
3- Criar arquivo de SKU
Para que um produto fique ativo no site, ele também precisa de ao menos uma imagem. O mesmo se aplica a cada SKU que faz parte deste produto. Levando isso em conta, o próximo passo é adicionar uma imagem ao SKU criado no passo 2, utilizando o request Create SKU file.
Diferente dos requests anteriores, o Id do SKU neste caso deve ser adicionado a URL do request:
Os campos deste request são:
IsMain- Flag que define se o arquivo em questão será a imagem principal do SKU.Label- “Etiqueta” usada para facilitar na organização do template das páginas do seu site, através do referenciamento do valor preenchido nesta. Ex.: Frontal, lateral, superior etc.Name- Nome do arquivo da imagem. Campo Obrigatório.Text- Texto que se associa a sua imagem e fica registrado no cadastro do SKU na aba “Imagens”, no campo “Texto”. Não é permitido o uso de caracteres especiais e acentosUrl- URL external da imagem, que será utilizada como fonte. A URL deve começar comhttp://ouhttps://e terminar com o tipo de arquivo (.jpg,.pngou.gif).
4- Associar Especificações
É possível que, se o produto criado fizer parte de uma categoria pré-existente, que existam especificações configuradas nesta categoria para os Produtos e/ou SKUs dentro dela. Se houverem, os requests Associate product specification e Associate SKU specification podem ser utilizados para associar estas especificações ao produto e SKU, respectivamente. Se as especificações estiverem configuradas como obrigatórias, é necessário fazer isso para que o produto fique ativo. Os campos disponíveis para estes requests são:
FieldId- Id da especificação a ser associadaFieldValueId/Text- Valor da especificação. O campo FieldValueId é utilizado para especificações do tipo Combo, Radio e Checkbox, que tem valores pré-configurados. O campo Text é utilizado para todos os outros tipos de especificações. Para mais informações sobre tipos de especificação, veja nossa documentação sobre Especificações de produto e de SKU.
Se deseja criar novas especificações, temos um artigo sobre como fazer isso via API: Dúvidas Frequentes: Como criar e associar especificações de produto e/ou SKU via API?
5- Ativação de SKUs
É possível que, após todos os passos anteriores, os SKUs criados ainda estejam desativados. Num geral, se a flag ActivateIfPossible estiver definida como verdadeira (true) a ativação ocorrerá dentro de alguns minutos. Porém, se isso não ocorrer (ou caso a flag tenha sido intencionalmente definida como false) você pode manualmente ativar o SKU. Recomendamos antes de tudo utilizar o request Get SKU para obter os dados atuais configurados para o SKU em questão, e que podem ser utilizados para confirmar que todos os campos estão corretos. A resposta deste request pode então ser enviada de volta com o request Update SKU, sendo necessário apenas alterar o campo IsActive para true.
Seguindo todos estes passos, o produto e seus SKUs estarão criados com todas as informações básicas do módulo de catálogo e podem então ter um preço e inventário definidos nos módulos de Preços e de Logística.
Eduardo Luciano
Field Software Engineer | VTEX