Pular para o conteúdo principal

Hub Categorias

A tela Hub Categorias — também conhecida como DE-PARA Categorias — faz a ponte entre a categoria/árvore taxonômica usada pelo canal de venda externo e a categoria cadastrada no catálogo do idworks. Cada linha é uma regra de tradução: quando um anúncio do canal X cai numa determinada categoria (e numa árvore específica como "Eletrônicos > TV > Smart TV"), qual categoria interna usar para classificar o produto no catálogo do idworks.

O nome "DE-PARA" vem do conceito clássico de integração: DE = o lado externo (canal de venda) → PARA = o lado interno (ERP idworks). A tela é uma lista CRUD simples (5 endpoints, 4 privilégios) com um modal que mostra os dois lados separados por uma seta. Diferenciais desta tela: cada linha guarda a árvore completa (CategoryFromTree) da categoria no canal (não só o ID), tem botão Reprocessar que reconsulta a categoria direto no canal, e a criação é idempotente — repostar o mesmo mapeamento atualiza a árvore sem dar erro de duplicidade.

Esta tela não tem parametrizações próprias em Configurações → Parametrizações. Tem uma proteção forward: não permite excluir um mapeamento de categoria quando existem variações vinculadas a ele em Hub Variação.

Índice​

Conceito

Cadastro e edição

Reprocessamento

Regras de negócio

Referência rápida

O que é a tela Hub Categorias?​

É a tela onde você cadastra a tradução entre a categoria usada pelo canal de venda externo e a categoria do catálogo interno do idworks. Cada linha responde à pergunta "quando um anúncio chegar do canal X na categoria Y, qual categoria interna usar?". Diferente de marca ou pagamento, este mapeamento guarda também a árvore completa (caminho até a categoria) — informação útil para identificar visualmente onde no canal a categoria está localizada.

📍 Onde: menu lateral → Integrações → Hub Categorias.

O que significa "DE" e "PARA" no mapeamento?​

DE (canal externo)PARA (ERP idworks)
Origem do códigoO canal de venda (Mercado Livre, Magalu, etc.).Cadastrado em Produtos → Categorias.
IdentificaçãoIntegração + Categoria canal (ID + árvore completa "Eletrônicos > TV > Smart TV").Categoria interna do catálogo idworks.

A direção do mapeamento é sempre canal → ERP.

Para que serve esse mapeamento na prática?​

Cada canal tem sua própria árvore de categorias com IDs próprios:

  • Mercado Livre tem categorias como MLB1648 ("Casa, Móveis e Decoração > Decoração > Quadros > Quadros Decorativos").
  • Magalu tem códigos numéricos próprios.
  • Vtex opera com categorias customizadas por loja.

Sem o DE-PARA, o idworks não saberia em qual categoria interna classificar um produto importado. Com o mapeamento, um único produto no catálogo idworks pode aparecer em categorias diferentes em cada canal (cada canal manda sua própria categoria) — e o sistema sabe que tudo cai na mesma categoria interna.

A CategoryFromTree (árvore completa) é importante porque alguns canais usam IDs numéricos curtos que sozinhos não dizem nada — ter o caminho "Eletrônicos > TV" ajuda o operador a identificar visualmente a categoria sem precisar consultar a API do canal.

Onde o mapeamento é consumido pelo sistema?​

Principal consumo: importação de ofertas/anúncios do canal. Quando um anúncio é importado e cai em determinada categoria do canal, o sistema:

  1. Consulta esta tela para descobrir a categoria interna correspondente.
  2. Classifica o SKU criado/atualizado na árvore interna.
  3. A tela Hub Variação consulta este mapeamento para validar quais campos de variação aplicam-se a cada categoria-canal.

O mapeamento também é usado quando o sistema envia produtos para o canal — para descobrir qual categoria-canal enviar baseado na categoria interna do SKU.

Como criar um novo mapeamento DE-PARA?​

  1. Acesse Integrações → Hub Categorias.
  2. Clique em Novo.
  3. Preencha o lado DE (esquerda):
    • * Integração — selecione a integração.
    • Categoria canal — escolha a categoria na lista do canal (com árvore completa visível), ou digite o código manualmente.
  4. No lado PARA (direita):
    • * Categoria — categoria interna do idworks.
  5. Salve.

Quando o operador escolhe a categoria do canal pelo dropdown, o sistema preenche automaticamente a árvore completa (CategoryFromTree) — útil para identificação visual posterior.

Pré-requisito: privilégio Criar hub categorias.

Quais campos são obrigatórios?​

São obrigatórios:

  • Integração — qual canal de venda.
  • Categoria — qual categoria interna do idworks.

A Categoria canal é opcional no formulário, mas obrigatória na prática se o canal envia categoria nos seus pedidos/anúncios (sem ela, o sistema não consegue casar a regra).

Cadastros que você precisa ter antes​

  • Integração — em Configurações → Integrações.
  • Categoria interna — em Produtos → Categorias.

Como adicionar uma categoria canal que não está na lista?​

  1. Com a janela aberta, clique em Categoria canal.
  2. No fim do dropdown, há Digite... + Adicionar.
  3. Digite o código exatamente como o canal usa e clique em Adicionar.
  4. Salve.

A árvore (CategoryFromTree) fica vazia nesses casos — você pode preenchê-la depois editando o mapeamento.

Como editar um mapeamento existente?​

  1. Na lista, ícone de lápis (ou duplo clique).
  2. Edite os campos.
  3. Salve.

Pré-requisito: privilégio Editar hub categorias.

Como excluir um mapeamento?​

  1. Na lista, ícone de lixeira.
  2. Confirme.

Se a categoria tem variações vinculadas em Hub Variação, a exclusão é bloqueada — veja a regra de negócio correspondente.

Pré-requisito: privilégio Deletar hub categorias.

O que faz o botão Reprocessar?​

Similar ao reprocessamento de Hub Marcas, este botão consulta a API do canal para atualizar os dados da categoria (árvore, nome, hierarquia) — útil quando:

  • O canal reorganizou a árvore de categorias.
  • A categoria foi renomeada no canal.
  • Você precisa repopular a CategoryFromTree.
  1. Na linha, clique no ícone correspondente.
  2. Confirme em "Confirma reprocessar essa categoria?".
  3. O sistema chama o worker do canal e atualiza os dados.

Quando o reprocessamento falha com "Integração não tem recurso"?​

A operação depende de uma URL de recurso cadastrada no tipo de integração (TypeSalesChannelResource com ResourceType = "Category"). Quando essa URL não está cadastrada, falha com "Integração não tem recurso".

Solução: verificar com o suporte se o canal específico expõe o recurso de reprocessamento de categoria.

Por que repostar o mesmo mapeamento não dá erro de duplicidade?​

A criação (POST) é idempotente: o sistema executa um INSERT ... ON DUPLICATE KEY UPDATE baseado em (Integração + Categoria canal + Categoria interna). Repostar o mesmo trio não dá erro — apenas atualiza a árvore (CategoryFromTree) se mudou.

A edição (PUT) bloqueia duplicidades para evitar criar duas linhas com o mesmo mapeamento depois de editar — a mensagem é "Já existe de/para de categoria para mesma categoria e integração".

Diferente de Hub Pagamento (sempre bloqueia duplicidade) e Hub Marcas (nunca bloqueia).

Por que não consigo excluir uma categoria com variações vinculadas?​

Quando você cria mapeamentos de variação em Hub Variação vinculados a uma categoria desta tela, o sistema protege o mapeamento de categoria contra exclusão acidental. A mensagem é "Existe de/para de variação para essa categoria e a mesma não pode ser excluída".

Para destravar: vá em Hub Variação, exclua os mapeamentos de variação que apontam para esta categoria, e volte para excluir aqui.

O que acontece quando uma integração é excluída?​

Quando uma integração é excluída em Configurações → Integrações, todos os mapeamentos de categoria vinculados a ela são apagados automaticamente em cascata.

⚠️ Atenção: ao excluir uma categoria interna em Produtos → Categorias, o sistema não bloqueia automaticamente se existirem mapeamentos Hub apontando para ela. Quando precisar excluir uma categoria usada aqui, exclua primeiro os mapeamentos correspondentes.

Resumo de parametrizações​

Esta tela não tem parametrizações próprias em Configurações → Parametrizações. A configuração relevante vive em:

Onde configurarO que define
Configurações → IntegraçõesCadastra os canais de venda.
Produtos → CategoriasCadastra a árvore de categorias interna do catálogo.

A capacidade de reprocessamento por linha depende do tipo da integração ter a URL de recurso de categoria configurada internamente.

Privilégios da tela​

Esta tela tem privilégios próprios que controlam o que cada usuário pode fazer. Configure os perfis de acesso em Configurações → Perfis de Acesso vinculando os privilégios abaixo aos grupos desejados. Quando o usuário não tem o privilégio, a ação correspondente fica desabilitada na tela.

PrivilégioLibera
Visualizar hub categoriasAcesso à tela, à lista e à visualização dos mapeamentos.
Criar hub categoriasBotão Novo e o cadastro de um novo mapeamento.
Editar hub categoriasEdição de um mapeamento existente.
Deletar hub categoriasExclusão de um mapeamento.