Qual é a sua dúvida?
Buscas em destaque:

    Gestão de Produto via API

    Publicado em: 9/25/2020, 3:11:27 PM


    A Gestão de Produto via API visa controlar os produtos de forma massiva, proporcionando mais agilidade e praticidade no gerenciamento. Com este recurso você pode criar novos produtos, atualizar o prazo de entrega e realizar diferentes consultas relacionadas ao produto.


    Inserção de Produto via API


    A operação de inserção de produtos da API da Tray Corp permite que sejam inseridos produtos de diversas maneiras. Neste artigo será apresentado quais as possibilidades e o que deve ser feito para inserir um produto de acordo com cada uma delas.


    Para inserir um produto é preciso realizar um post no endpoint /produtos, enviando os dados mínimos necessários para a criação de um novo produto na plataforma como nome, preço, fabricante, entre outros.




    Um 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. Nesse caso, é necessário escolher como você quer agrupar essas variações.


    Você pode fazer isso de duas formas:

    • Agrupando produtos diferentes pelo Parent Id;
    • Agrupando 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.


    Atenção: para uma melhor experiência de compra dos clientes, informamos que cadastros acima de 10 mil variantes em um produto, resulta em má qualidade de navegação. Portanto, se por algum motivo seu produto possui uma quantidade acima da mencionada, utilize a personalização ou outras formas de vínculo.


    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 é uma só e suas variações são exibidas na página do produto da mesma forma que no agrupamento por Parent ID.


    Na API da Tray Corp, cada uma dessas formas de agrupamento são diferenciadas pelos campos "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, a API irá cadastrar esse produto 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 da API Explorer, na seção Model, dentro do POST/Produtos, é 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


    Para saber mais sobre Informações de Produtos acesse o artigo.


    É 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.


    Definindo uma categoria de um produto como principal


    Para os produtos já cadastrados na plataforma é possível também definir uma categoria como principal. Para isso, é necessário realizar o método PUT em um determinado produto, mas primeiro é preciso adquirir o ID da categoria, acessando no menu Produtos >> Grupos de Informações >> Categorias, e localizar a categoria que deseja inserir para o produto.



    Ao clicar em uma categoria, o ID dela é apresentado através da URL é esse ID que informará na API para realizar a atualização.



    Após localizar o ID da categoria na plataforma, acesse a API e clique em "API Explorer", em que será apresentado os métodos para  integração.



    No campo "api_key", informe o token de integração com seu ERP.



    Localize o método de atualização com o endpoint PUT /produtos/{identificador}/categoriaPrincipal, informe o ID da categoria que foi localizado na plataforma e informe o SKU ou ProdutoVarianteId do produto.



    Quando o método de atualização é executado com sucesso, será apresentado no campo "Response Code" o ID 200.


    Atualização de Produto - Campo valido e exibirSite não obrigatórios


    Para a atualização de um produto é necessário realizar o método PUT, através do endpoint PUT /produtos/{identificador} e para este endpoint os campos valido e exibirSite não são obrigatórios na atualização.


    Acesse a API e clique em "API Explorer", será apresentado os métodos para  integração. No campo "api_key", informe o token de integração com seu ERP.


    Localize o método de atualização, com o endpoint informado acima, sendo PUT /produtos/{identificador}, informe o SKU ou ProdutoVarianteId do produto e no objeto coloque as informações do produto a ser atualizado, não sendo necessário informar o campo valido e exibirSite.



    Quando o método de atualização é executado com sucesso, será apresentado no campo "Response Code" o ID 200.


    • Se o produto a ser atualizado estiver ativo na plataforma e na atualização os campos valido e exibirSite forem enviados vazios ou null ou não sejam enviados no objeto, o produto permanecerá ativo, da mesma forma, ocorrerá para caso o produto esteja inativo.
    • Caso o produto a ser atualizado esteja ativo na plataforma e na atualização para os campos valido e exibirSite for informado como true, o produto permanecerá ativo e caso seja informado para os campo false, o produto será desativado.


    Atualizando o prazo de entrega de um ou mais produtos


    Para atualizar o prazo de entrega de um ou mais produtos, não tendo a necessidade de atualizar todos o produto, o procedimento pode ser realizado por meio do endpoint PUT /produtos/estoques conforme abaixo:


    Acesse a API e clique em "API Explorer", onde serão apresentados os métodos para integração. No campo "api_key", deve ser informado o token de integração com seu ERP.


    Localize o método de atualização, com o endpoint informado acima, sendo PUT /produtos/estoques, informe o SKU ou ProdutoVarianteId do produto e no objeto coloque as informações para a atualização.



    Quando o método de atualização é executado com sucesso, será apresentado no campo "Response Code" o ID 200.


    Consultando preço do produto variante e incluindo preços da tabela de preços


    Para realizar a consulta de um produto específico acesse a API, clique em API Explorer, informe o token e clique em Produto.



    Em seguida clique no endpoint "GET /produtos/{identificador}/precos" e informe o identificador e o tipo de identificador.



    Ao executar a consulta, será apresentado no "Response Body" as informações de preços do produto variante e preços de tabela de preços caso possuir o vínculo.



    Consultando um produto específico por meio do Parâmetro ID do Produto


    Para realizar a consulta de um produto específico acesse a API, clique em API Explorer, informe o token e clique em Produto.



    Para os endpoints abaixo é possível realizar a consulta também pelo Id do produto, além do SKU e do ProdutoVarianteId.


    Caso você queira consultar algum produto, clique no endpoint GET /produtos/{identificador}, informe o identificador e no tipo de identificador poderá selecionar o parâmetro ProdutoId e se desejar mais informações poderá selecionar os "camposAdicionais".



    Ao executar a consulta, será apresentado no "Response Body" as informações do produto consultado.



    Para consultar os tipos de informações de um produto, clique no endpoint GET /produtos/{identificador}/informacoes e informe o identificador e no "tipoIdentificador" poderá selecionar o parâmetro ProdutoId.



    Ao executar a consulta, será apresentado no "Response Body" os tipos de informações cadastradas no produto.



    Caso queira ainda consultar as categorias de um produto, clique no endpoint GET /produtos/{identificador}/categorias e informe o identificador e no tipoIdentificador poderá selecionar o parâmetro ProdutoId.



    Ao executar a consulta, será apresentado no "Response Body" as categorias que estão vinculadas ao produto.


    Para uma guia deste tópico, valide os itens ao lado direito.
    Esse artigo foi útil?
    thumb_up0
    thumb_down0

    Ainda não encontrou o que procura?