Pular para o conteúdo principal

Hub Pagamento

A tela Hub Pagamento — também conhecida como DE-PARA Tipo Pagamento — faz a ponte entre os códigos de forma de pagamento que o canal de venda externo envia (Mercado Livre manda "creditCard", "ticket"; Magalu manda IDs próprios; Shopee usa códigos diferentes para cada parcelamento) e os tipos de pagamento cadastrados no idworks (Boleto, PIX, Cartão de Crédito, Dinheiro, etc.). Cada linha é uma regra de tradução: quando um pedido chega da integração X com o código de pagamento Y, qual tipo de pagamento interno usar para registrar o título a receber e classificar o pedido financeiramente.

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 (4 endpoints, 4 privilégios — Visualizar, Criar, Editar, Deletar) com um modal de cadastro que mostra os dois lados separados por uma seta. Sem o mapeamento, pedidos importados com formas de pagamento desconhecidas ficam sem classificação financeira correta.

Esta tela não tem parametrizações próprias em Configurações → Parametrizações. A única regra fixa do sistema é uma exceção para algumas integrações: para integrações com tipo 23, 24, 34, 45, 53, o Código canal é gravado conforme o operador digitar; nas demais integrações, na edição (PUT) o sistema preenche automaticamente com o canal de venda da integração quando o campo está vazio.

Índice​

Conceito

Cadastro e edição

Regras de negócio

Referência rápida

O que é a tela Hub Pagamento?​

É a tela onde você cadastra a tradução entre o código de forma de pagamento usado pelo canal de venda externo (Mercado Livre, Magalu, Shopee, etc.) e o tipo de pagamento cadastrado no idworks. Cada linha responde à pergunta "quando um pedido chegar do canal X com o código de pagamento Y, qual tipo de pagamento interno usar?". A tela é puramente um catálogo de regras — não dispara processos.

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

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

DE (canal externo)PARA (ERP idworks)
Origem do códigoO canal de venda (Mercado Livre, Magalu, Shopee, etc.).Cadastrado em Financeiro → Tipo Pagamento.
IdentificaçãoIntegração (qual canal) + Código canal (string da forma de pagamento).Tipo pagamento (Boleto, PIX, Cartão, Dinheiro, etc.).

A direção do mapeamento é sempre canal → ERP: quando um pedido chega do canal com determinado código de pagamento, o sistema procura nesta tela qual tipo interno corresponde.

Para que serve esse mapeamento na prática?​

Cada canal usa códigos próprios para representar formas de pagamento:

  • Mercado Livre envia strings como "creditCard", "ticket", "pix", "account_money".
  • Magalu usa IDs numéricos próprios.
  • Shopee distingue cartão de crédito à vista de parcelado com códigos diferentes.

Sem o DE-PARA, o idworks não saberia que tipo de pagamento aplicar ao pedido importado — o título a receber sairia sem classificação e o relatório financeiro ficaria com pagamentos genéricos. O mapeamento permite ter um único tipo de pagamento interno ("Cartão de Crédito") consumido por múltiplos códigos externos — cada canal manda o seu código, e o sistema sabe que tudo cai no mesmo bucket interno.

Onde o mapeamento é consumido pelo sistema?​

Principal consumo: importação de pedidos do canal. Quando um pedido chega da integração com a forma de pagamento "creditCard", o sistema:

  1. Consulta esta tela para descobrir o tipo de pagamento interno correspondente.
  2. Aplica esse tipo de pagamento ao pedido importado.
  3. Gera o título a receber em Financeiro → Contas a Receber com a classificação correta.

Sem mapeamento para o código recebido, o pedido pode ser importado sem tipo de pagamento (genérico) ou falhar a importação, dependendo do canal.

Como criar um novo mapeamento DE-PARA?​

  1. Acesse Integrações → Hub Pagamento.
  2. Clique em Novo.
  3. Preencha o lado DE (esquerda):
    • * Integração — selecione a integração configurada (ex.: "Mercado Livre - Loja A").
    • Código canal — escolha o código de pagamento na lista (carregada pela API do canal quando disponível), ou digite manualmente.
  4. No lado PARA (direita):
    • * Tipo de pagamento — tipo interno do idworks que deve ser usado para esse código.
  5. Clique em Salvar.

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

Quais campos são obrigatórios?​

São obrigatórios:

  • Integração — qual canal de venda.
  • Tipo de pagamento — qual tipo interno do ERP.

O Código canal é opcional no formulário, mas tem comportamento especial em algumas integrações (veja a regra de negócio sobre preenchimento automático).

Cadastros que você precisa ter antes​

O formulário usa listas de seleção que dependem de cadastros feitos em outras telas. Antes de criar o primeiro mapeamento, certifique-se de já ter:

  • Integração — em Configurações → Integrações. A integração precisa estar ativa para aparecer na lista.
  • Tipo de pagamento — em Financeiro → Tipo Pagamento.

Como adicionar um código de canal que não está na lista?​

Para canais cuja API não retorna a lista de códigos de pagamento (ou quando o operador precisa cadastrar um código novo manualmente):

  1. Com a janela de cadastro aberta, clique no campo Código canal.
  2. No final do dropdown, há um campo Digite... com um botão Adicionar.
  3. Digite o código exatamente como o canal usa e clique em Adicionar.
  4. O código aparece preenchido no campo principal.
  5. Continue preenchendo e salve.

Como editar um mapeamento existente?​

  1. Na lista, clique no ícone de lápis na linha (ou dê duplo clique).
  2. Edite os campos desejados.
  3. Clique em Salvar.

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

Como excluir um mapeamento?​

  1. Na lista, clique no ícone de lixeira na linha.
  2. Confirme na janela.
  3. O mapeamento é apagado imediatamente.

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

Por que o sistema preenche o "Código canal" automaticamente em algumas edições?​

Para a maioria das integrações, quando você edita um mapeamento e deixa o Código canal em branco, o sistema preenche automaticamente com o canal de venda da integração (campo interno). Isso garante que cada integração tenha pelo menos um mapeamento "fallback" sem código específico — útil para integrações que não enviam código de pagamento explícito em cada pedido.

A exceção: integrações dos tipos 23, 24, 34, 45, 53 mantêm o Código canal exatamente como o operador digitou, mesmo em branco — essas integrações usam o código como filtro real e o preenchimento automático criaria conflito.

Na criação (Novo Recebimento), o preenchimento automático não acontece — o operador é responsável por preencher o código quando relevante.

Por que não consigo criar duas regras com o mesmo código e integração?​

Para evitar ambiguidade, o sistema bloqueia duplicatas: dois mapeamentos com a mesma combinação de Integração + Código canal não são permitidos. A mensagem é "De/para pagamento já existe".

Quando você precisa mudar o tipo de pagamento interno para um código existente, edite o mapeamento atual em vez de tentar criar um novo. Para casos onde a mesma integração precisa mapear vários códigos para tipos diferentes (caso comum), use códigos diferentes — cada combinação Integração+Código é uma linha separada.

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

Quando uma integração é excluída em Configurações → Integrações, todos os mapeamentos vinculados a ela são apagados automaticamente em cascata — não é necessário limpar manualmente esta tela.

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 que aparecem no campo Integração.
Financeiro → Tipo PagamentoCadastra os tipos de pagamento internos que aparecem no campo Tipo pagamento.

A regra de preenchimento automático do Código canal na edição (exceto integrações tipo 23, 24, 34, 45, 53) é fixa no comportamento do sistema, não configurável.

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 pagamentoAcesso à tela, à lista e à visualização dos mapeamentos.
Criar hub pagamentoBotão Novo e o cadastro de um novo mapeamento.
Editar hub pagamentoEdição de um mapeamento existente (lápis ou duplo clique).
Deletar hub pagamentoExclusão de um mapeamento (ícone de lixeira).