Para quê serve a API de mapeamento de categorias?

Essa API permite que o integrador consulte os departamentos, categorias, subcategorias e atributos disponíveis que permitirão o cadastro de produto.

URLs

Nós disponibilizamos um ambiente de homologação para a realizarem as consultas. O Fluxo a seguir tem como base as seguintes URLs:

https://api-mktplace-hlg.viavarejo.com.br/api/v4/sandbox/api-front-categories-v3/jersey/categories

https://api-mktplace.viavarejo.com.br/api/v4/api-front-categories-v3/jersey

Collection Postman

A collection do Postman já com os endpoints está disponível no link abaixo. Link (HLG / PRD):

Consulta de todos os níveis de categorias e atributos

Método: GET

Composição do Header:

• access_token: Chave de acesso da loja
• client_id: Chave de acesso da integradora
• Accept: application/json
• Content-Type: application/json

Parâmetro:

• _limit = 50 (total de departamentos)
• _offset = 0 (Página única)

Endpoint (HLG):

https://api-mktplace-hlg.viavarejo.com.br/api/v4/sandbox/api-front-categories-v3/jersey/categories

Endpoint (PRD):

https://api-mktplace.viavarejo.com.br/api/v4/api-front-categories-v3/jersey/categories/?_limit=50&_offset=0

Consulta de categorias por departamento

Esse tipo de consulta retorna individualmente departamento a departamento, mas é necessário parametrizar corretamente o "offset e o limit". Como a busca paginada é específica, a composição de ambos os parâmetros representam o departamento, retornando todos os níveis de categoria e seus respectivos atributos.

Método: GET

Composição do Header:

• access_token: Chave de acesso da loja
• client_id: Chave de acesso da integradora
• Accept: application/json
• Content-Type: application/json

Parâmetro:

• _limit = Valor do departamento (sempre 1 número maior que o "offset")
• _offset = Valor do departamento (sempre 1 número inferior ao "limit")

Exemplo:

Response

Como retorno da chamada, a API trará todos os níveis de categoria (as categorias possuem até 3 níveis) e seus respectivos atributos (obrigatórios e complementares).

Vamos entendê-lo:

Detalhamento da request:

• "id": Exibe o código referência do departamento, categoria e subcategoria. No exemplo acima, o “id”: “2596” se refere ao departamento, o próximo “id”: “1948” se refere a categoria e o “id”: “2650” se refere a subcategoria;
• "name": Nome do departamento, categoria e subcategoria;
• "parentId": Indica se a categoria possui subníveis (ID: caso exista subnível | null: caso não exista subnível);
• "categories": Este campo sempre será aberto caso o nível tenha subníveis.

Leitura dos atributos:

Os atributos sempre estarão vinculados ao último nível da categoria, então vejamos um exemplo:

Detalhamento da request:_

• "attributes": Ficará aberto quando a categoria tiver algum tipo de atributo;
• "id": Os id’s que estiverem abaixo do campo “attributes” são os idUDA. Esses ids que devem ser preenchidos quando enviado um atributo dentro da ficha do SKU;
• "name": Nome do atributo.
• "type": Indica o tipo do preenchimento do campo, podendo ser TXN, TXL, MVM e MVU;
• "required": Indica se o atributo é obrigatório ou não, podendo esse campo ser "N" (não obrigatório) e "Y" (Obrigatório);
• "variant": Indica se o atributo é variante ou não, podendo então ser "N" (não variante) e "Y" (é variante);
• "values": Colchetes aberto: Valores pré-definidos para seleção. / Colchetes fechado: Campo livre.

Consulta de categorias por ID

Este parâmetro pode ser utilizado para consulta de categoria específica, no qual o id de qualquer nível da categoria pode ser consultado. Abaixo um exemplo de consulta:

Método: GET

Composição do Header:

• access_token: Chave de acesso da loja
• client_id: Chave de acesso da integradora
• Accept: application/json
• Content-Type: application/json

Parâmetro:

• id: Código de ID do nível de categoria desejado.

Endpoint (HLG):

https://api-mktplace-hlg.viavarejo.com.br/api/v4/api-front-categories-v3/jersey/categories/?id=

Endpoint (PRD):

https://api-mktplace.viavarejo.com.br/api/v4/api-front-categories-v3/jersey/categories/?id=

Response

Usando o ID 2596 que representa o departamento de "Bebidas (nível 1)" como exemplo, vejamos o retorno:

Como os atributos são vinculados ao último nível da categoria, conseguimos localizá-los após ele:

Como os atributos são vinculados ao último nível da categoria, conseguimos localizá-los após ele:

Detalhamento da request:_

• "attributes": Ficará aberto quando a categoria tiver algum tipo de atributo;
• "id": Os id’s que estiverem abaixo do campo “attributes” são os idUDA. Esses ids que devem ser preenchidos quando enviado um atributo dentro da ficha do SKU;
• "name": Nome do atributo.
• "type": Indica o tipo do preenchimento do campo, podendo ser TXN, TXL, MVM e MVU;
• "required": Indica se o atributo é obrigatório ou não, podendo esse campo ser "N" (não obrigatório) e "Y" (Obrigatório);
• "variant": Indica se o atributo é variante ou não, podendo então ser "N" (não variante) e "Y" (é variante);
• "values": Colchetes aberto: Valores pré-definidos para seleção. / Colchetes fechado: Campo livre.

Consulta de categorias e subcategorias (sem atributos)

Este parâmetro pode ser utilizado para consulta de categoria específica, no qual somente o id do 1º ou 2º nível podem ser consultados. Abaixo um exemplo de consulta:

Método: GET Composição do Header:

• access_token: Chave de acesso da loja
• client_id: Chave de acesso da integradora
• Accept: application/json
• Content-Type: application/json

Parâmetro:

• id: Código de ID do 1º ou 2º nível da categoria desejada (caso informe o ID de um nível que não tenha subcategoria, o retorno trará somente a subcategoria indicada).

Endpoint (HLG):

https://api-mktplace-hlg.viavarejo.com.br/api/v4/sandbox/api-front-categories-v3/jersey/categories/children

Endpoint (PRD):

https://api-mktplace.viavarejo.com.br/api/v4/api-front-categories-v3/jersey/categories/children?id=

Response

Usando o ID 2596 que representa o departamento de "Bebidas (nível 1)" como exemplo, vejamos o retorno:

Detalhamento da request:

• "levelId": Id do departamento, categoria ou subcategoria;
• "levelIdFather": Id da categoria de nível superior (Ex: Se buscar por uma categoria, aqui estará o id do departamento);
• "name": Nome do departamento, categoria ou subcategoria;
• "hasChildren": Indica se o departamento ou categoria possui subnível (true: possui subnível / false: não possui subnível).

Consulta de atributos por categoria

Este parâmetro pode ser utilizado para consulta de atributos para uma categoria específica, no qual somente o ID do último nível da categoria pode ser consultado. Abaixo um exemplo de consulta:

Método: GET

Composição do Header:

• access_token: Chave de acesso da loja
• client_id: Chave de acesso da integradora
• Accept: application/json
• Content-Type: application/json

Parâmetro:

• id: Código de ID do último nível da categoria (caso informe o ID de que não seja o último nível, o retorno será em branco).

Endpoint (HLG):

https://api-mktplace-hlg.viavarejo.com.br/api/v4/sandbox/api-front-categories-v3/jersey/categories/attribute

Endpoint (PRD):

https://api-mktplace.viavarejo.com.br/api/v4/api-front-categories-v3/jersey/categories/attribute/?id=

Response

Usando o ID 2650 que representa a categoria "Tinto (nível 3)" como exemplo, vejamos o retorno:

Detalhamento da request:

• "levelId": Id pesquisado;
• "udaGroupId": ID do grupo de atributos;
• "udaGroupName": Descrição do grupo de atributos;
• "udaId": idUDA do atributo;
• "udaName": Descrição do atributo;
• "isRequired": Indica se o atributo é obrigatório ou não, podendo esse campo ser "N" (não obrigatório) e "Y" (Obrigatório);
• "isVariant": Indica se o atributo é variante ou não, podendo então ser "N" (não variante) e "Y" (é variante);
• "udaValues": Colchetes aberto: Valores pré-definidos. / Colchetes fechado: Campo livre.

Atributo "Selecione"

O atributo "Selecione" retorna em 100% das categorias e é o único que possui idUda fixo (206509). Ele somente pode ser utilizado quando a categoria apontada no cadastro do produto, não possuir NENHUM outro atributo obrigatório ("required": "Y").

Exemplo:

O intuito deste atributo é permitir que os sellers consigam cadastrar produtos variantes, mesmo quando a Via Marketplace não exige obrigatoriedade.

Exemplo de preenchimento do selecione ao cadastrar item novo: