Gestão de Produtos

A Gestão de Produto via API visa controlar os produtos de forma massiva, proporcionando mais agilidade e praticidade no gerenciamento.

A gestão de produtos possui alguns pontos importantes, conforme listados abaixo:

Na inserção do produto, ao enviar zero para o campo "centroDistribuicaoId" do objeto de estoque, será feita a inserção do estoque para o Centro de Distribuição principal.

Outro ponto importante do cadastro de produtos é a relação entre produtos e atributos e a forma como os produtos se relacionam entre si. Um produto pode ter diversas modificações como cores, tamanhos, preços, voltagens, pesos, etc. Para este caso, existem duas formas para agrupar variações, que seria agrupar produtos diferentes pelo Parent Id ou agrupar diversos variantes a um único produto;

Caso o produto não possua variações, também é possível inserir um produto sem agrupá-lo a nenhum outro.

Produto sem Variações

Um produto sem variações não possui opções como cor, tamanho ou voltagem para serem selecionados pelo usuário. O cadastrado do produto deve ser inserido sem agrupamento algum e com a sua lista de atributos vazia, neste caso, quando o usuário acessar a página do produto será apresentada apenas a opção de quantidade de itens desejados para a compra.

Agrupamento por Parent Id

O Parent Id é um código interno utilizado para identificar produtos diferentes que devem ser exibidos em conjunto na tela de produto. Desta forma, é possível ter produtos que possuem URL´s diferentes e que aparecem separados no resultado da busca, sendo exibidos como um único produto quando visualizado na página do produto.

Agrupamento por Produto Variante

No agrupamento por produto variante existirá apenas um único produto e suas variações. Ao agrupar dessa forma, no resultado da busca será exibido apenas um item do produto, mesmo que existam diversas variações. A URL do produto será somente uma e suas variações são exibidas na página do produto da mesma forma que no agrupamento por Parent ID.

Os campos referente as formas de agrupamento são: "IdPaiExterno", "IdVinculoExterno" e "SKU".

Produto sem Variação

A inserção de um produto sem atributos pode ser realizada de duas formas:

• A mais simples é não preencher os campos "IdPaiExterno" e "IdVinculoExterno", enviar um "SKU" único e não enviar nada no campo "listaAtributos". Desta forma, o produto será cadastrado sem vínculo nenhum com outro e ele será apresentado como na imagem abaixo:

• Outra forma é seguir a mesma regra descrita acima para os campos "SKU" e "listaAtributos", porém enviar os campos "IdPaiExterno" e "IdVinculoExterno" preenchidos com valores únicos (que não tenham sido utilizados para outro produto).
  É importante saber que esses campos, quando não enviados, são preenchidos com o "SKU" do produto. Isso é feito para que se houver necessidade de inserir uma variação do produto no futuro, seja possível através do "SKU" do primeiro produto como "IdPaiExterno" ou "IdVinculoExterno".

Produto agrupado por Variantes

Para inserir um produto que possui diversas combinações de atributos utilizando o agrupamento por produto variante, é necessário preencher corretamente o campo "IdPaiExterno". Esse será o campo chave para identificar se um produto deve ser cadastrado como um produto inteiramente novo ou como um produto que representa uma variação de um produto já existente na plataforma.

Digamos que seja necessário inserir um produto, como o do exemplo abaixo, com várias opções de cor e grau. Para cada uma das variações seria necessário realizar um POST no endpoint /produtos e para que os produtos sejam agrupados corretamente, seria necessário enviar em todos o mesmo valor no campo "idPaiExterno". Outra opção, seria inserir o primeiro produto sem preencher o campo "idPaiExterno", onde internamente a API irá preencher o campo com o valor enviado no "SKU", e para os produtos seguintes bastaria enviar o "SKU" do primeiro produto no campo "idPaiExterno".

O exemplo abaixo mostra como pode ser feita a apresentação de um produto com diversas variações:

O produto acima possui diversas combinações possíveis quando observadas as opções de cor e grau. Para cada uma dessas combinações existe um produto variante.

Para cadastrar o produto dessa forma, permitindo que seja possível comprar um item da cor azul e qualquer um dos graus, é necessário realizar uma chamada para o endpoint /produtos para cada combinação.

Isso significa inserir um produto que possui em sua lista de atributos a cor azul e o grau -8.00, outro produto a cor azul e o grau -7.50, e assim por diante, até que fossem inseridos todos os graus possíveis para a cor azul.

Em seguida, o mesmo teria que ser feito para a cor cinza, verde, etc. Sempre utilizando o mesmo valor no campo "IdPaiExterno", até que todas as combinações sejam.

Sempre que é inserido um produto com um "IdPaiExterno" único ou vazio, está sendo cadastrado um novo produto e quando se realiza a mesma operação enviando este campo preenchido com um valor já vinculado a um produto existente, está sendo cadastrada uma variação de produto ou Produto Variante.

Apenas o produto é exibido na página de busca ou de categorias da loja, então mesmo que um produto possua inúmeras variantes, será exibido apenas um item.

Produto agrupado por Parent Id

O agrupamento por Parent Id possui algumas diferenças do agrupamento por Produto Variante, porém é possível combinar as duas formas.

O agrupamento por Parent Id permite que se tenha um produto único, que possui sua própria URL e que representa um item no resultado da busca do site, mas que ainda assim aparece como uma opção de atributo na página do produto. Ou seja, ao agrupar produtos, os itens agrupados serão exibidos como variantes uns dos outros.

Nesse exemplo, cada uma das cores exibidas é um produto diferente, porém cada um dos tamanhos é uma variação do produto da cor branca. Quando o usuário clicar em alguma outra cor, ele será redirecionado para a página do produto da cor escolhida e os tamanhos exibidos serão os variantes da cor selecionada.

O campo utilizado para informar quando um produto deve ser agrupado a outro produto é o "IdVinculoExterno". Quando é realizado um POST no endpoint /produtos, a API verifica se há outro produto cadastrado com o mesmo valor neste campo. Caso haja, o novo produto é inserido no mesmo grupo de produtos que o produto antigo.

Caso não seja enviado nenhum valor para o campo, a API irá utilizar o valor do "SKU" como "IdVinculoExterno" e continuará a operação como se o valor tivesse sido enviado. Ou seja, será verificado se existe algum outro produto previamente cadastrado com o mesmo "IdVinculoExterno" (nesse caso, contendo o SKU do produto). Por isso, é muito importante ter valores únicos para o SKU.

Para realizar um cadastro de produto igual ao exemplo acima, é necessário inserir um produto em que sua lista de atributos possui cor e tamanho. Em seguida, inserir outros produtos variantes, utilizando o campo "IdPaiExterno" para vinculá-los, cada um deles com a mesma cor, porém tamanhos diferentes.

Após isso, é necessário repetir o mesmo processo para o produto de cor diferente, porém nesse segundo produto você deverá informar o mesmo "IdVinculoExterno" utilizado no primeiro produto.

Regras de inserção

Ao realizar a operação de inserção de um produto é necessário tomar cuidado com algumas regras:

• A formatação de dados (JSON) enviado deve possuir todos os campos considerados obrigatórios. Estes são os campos mínimos necessários para que um produto seja inserido dentro de uma loja. Através do menu Referências de API, na categoria API Pública, em Produto, dentro do endpoint Adiciona novo produto, é possível visualizar todos os campos obrigatórios, juntamente com o tipo de dado, formato e a quantidade de caracteres;

• Não é aconselhável enviar dados de um produto já existente, pois causará erro. Caso a intenção seja atualizar um produto, deve-se utilizar o endpoint PUT /produtos/{identificador};

• O fabricante enviado para o cadastro do produto, deverá ser cadastrado previamente, caso seja enviado o nome de um fabricante que não existe ocorrerá erro na inserção de produto. O mesmo acontece com os campos autor, gênero, editora, coleção e para os atributos enviados na lista de atributos do produto. Com a diferença que estes campos são opcionais, então, caso não sejam enviados não será realizada a validação.

Envios Adicionais

A API possibilita cadastrar outros dados para produtos, esses dados devem ser enviados de forma separada em outros endpoints. Isso pode ser aplicado, por exemplo, no caso das informações de produto, imagens e do vínculo entre produto e categoria.

Você encontrará esses endpoints dentro de produtos. As URL´s seguem o padrão abaixo:

POST /produtos/{identificador}/informacoes
POST /produtos/{identificador}/imagens
POST /produtos/{identificador}/categorias

É importante observar que o identificador a ser passado para nos endpoints acima, pode ser tanto o Id do produto variante quanto o SKU. Ao realizar a operação, além dos dados a serem inseridos, deve-se informar também o tipo de identificador que está sendo utilizado.

Para inserir esses dados adicionais é necessário que o produto já exista na plataforma, ou seja, quando for realizada a inserção de um novo produto é necessário realizar o POST de inserção de produto, antes de inserir suas informações adicionais.