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. Além do tipo, cada regra também define em quantas parcelas e com quais vencimentos o título é gerado e em qual conta bancária o recebimento fica previsto.
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
- O que é a tela Hub Pagamento?
- O que significa "DE" e "PARA" no mapeamento?
- Para que serve esse mapeamento na prática?
- Onde o mapeamento é consumido pelo sistema?
Cadastro e edição
- Como criar um novo mapeamento DE-PARA?
- Quais campos são obrigatórios?
- Como funciona a Condição de Pagamento?
- Cadastros que você precisa ter antes
- Como adicionar um código de canal que não está na lista?
- Como editar um mapeamento existente?
- Como excluir um mapeamento?
Regras de negócio
- Por que o sistema preenche o "Código canal" automaticamente em algumas edições?
- Por que não consigo criar duas regras com o mesmo código e integração?
- O que acontece quando uma integração é excluída?
Boas práticas
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ódigo | O canal de venda (Mercado Livre, Magalu, Shopee, etc.). | Cadastrado em Financeiro → Tipo Pagamento. |
| Identificação | Integração (qual canal) + Código canal (código 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 que acontece com o pedido importado depende da parametrização Validar se pedido integrado possui de/para antes de criar (Configurações → Parametrizações → Integração de Vendas):
- Com a validação desligada (padrão) — o idworks não sabe que tipo de pagamento aplicar, mas importa o pedido do mesmo jeito: o título a receber sai sem classificação e o relatório financeiro fica com pagamentos genéricos.
- Com a validação ligada — o pedido não é importado: nenhum título a receber chega a ser criado até que o código de pagamento seja mapeado.
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:
- Consulta esta tela para descobrir o tipo de pagamento interno correspondente.
- Aplica esse tipo de pagamento ao pedido importado.
- 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 por completo — dependendo da parametrização Validar se pedido integrado possui de/para antes de criar (Configurações → Parametrizações → Integração de Vendas), e não do canal em si.
Quando o mapeamento tem o Boleto automático ligado, logo depois de criar o pedido o idworks já pede a emissão do boleto — o lojista não precisa emitir um a um no Contas a Receber.
⚠️ Isso só vale para pedidos que já entram com título a receber. Quando o pedido chega num status do canal que é apenas reserva de estoque (o idworks o cria como pagamento pendente canal, à espera da confirmação do pagamento), nenhum pagamento é montado: não há título a receber e, portanto, não há boleto. Assim que o canal confirmar o pagamento e o pedido seguir, o título nasce pela regra deste DE-PARA.
Como criar um novo mapeamento DE-PARA?
- Acesse Integrações → Hub Pagamento.
- Clique em Novo.
- 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.
- * Condição de Pagamento — os prazos em dias (
30, 60, 90) ou o número de parcelas (3x). Veja Como funciona a Condição de Pagamento?. - * Banco — conta bancária de previsão do recebimento.
- No lado PARA (direita):
- * Tipo de pagamento — tipo interno do idworks que deve ser usado para esse código.
- Integração bancária — a integração bancária usada neste mapeamento. Ela tem duas funções: é a integração gravada no pagamento do pedido importado — quando preenchida, prevalece sobre a adquirente que viria da tela Integrações → DE-PARA Adquirentes — e é ela quem emite o boleto quando o Boleto automático está ligado. Só é obrigatória nesse segundo caso.
- Boleto automático — quando ligado, o boleto é emitido automaticamente logo após a criação do pedido importado, para os títulos desse mapeamento. Veja a ressalva em Onde o mapeamento é consumido pelo sistema?.
- 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.
- Condição de Pagamento — os prazos em dias ou o número de parcelas do título gerado.
- Banco — a conta bancária de previsão do recebimento.
Se algum deles ficar em branco, o Salvar é bloqueado com um aviso do tipo "Por favor, o campo *CONDIÇÃO DE PAGAMENTO é obrigatório.".
Há ainda um campo condicionalmente obrigatório: quando o Boleto automático está ligado, a Integração bancária também precisa ser preenchida — o asterisco aparece no rótulo assim que você liga a chave.
Essa dupla exigência é conferida também no servidor: salvar com o Boleto automático ligado e o Banco ou a Integração bancária em branco é recusado com a mensagem "Banco e integração são obrigatórios para boleto automático". O Banco sozinho é cobrado pela própria tela em qualquer situação — o servidor só o exige quando o Boleto automático está ligado.
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).
Como funciona a Condição de Pagamento?
A Condição de Pagamento define em quantas parcelas — e com quais vencimentos — o título a receber é gerado quando o pedido do canal é importado. O campo aceita múltiplos valores: você digita cada um e pressiona Enter, ou separa por vírgula.
Há dois formatos aceitos:
| Formato | Exemplo | O que faz |
|---|---|---|
| Prazos em dias | 30, 60, 90 | Gera uma parcela para cada prazo informado, vencendo esse número de dias após a importação do pedido. Os prazos são ordenados do menor para o maior. |
| Número de parcelas | 3x | Gera a quantidade de parcelas informada, usando o campo Dias vencimento do tipo de pagamento (Financeiro → Tipo Pagamento) como intervalo. Com Dias vencimento = 30, 3x equivale a 30, 60 e 90 dias. |
Como o Dias vencimento é opcional no cadastro do tipo de pagamento, use o formato 3x só quando ele estiver preenchido: com o campo em branco, o intervalo vira zero e todas as parcelas nascem vencendo no mesmo dia.
Na importação, o valor do pagamento é dividido igualmente entre as parcelas e cada uma entra em Financeiro → Contas a Receber com o seu próprio vencimento — você não precisa quebrar o título na mão. A diferença de centavos do arredondamento vai para a última parcela, para que a soma feche com o valor original.
Atenção ao formato: só são aceitos números (com vírgula entre eles) ou o padrão <N>x. Texto livre — como "À vista" — é recusado com a mensagem "Condição de pagamento inválida", mesmo aparecendo no texto de exemplo do campo. Para o equivalente a "à vista", informe 0: gera uma única parcela vencendo no mesmo dia da importação.
A condição cadastrada aparece na coluna Condição pagamento da lista da tela. Junto com ela entraram as colunas Banco, Integração bancária e Boleto automático, então dá para conferir a regra de cada DE-PARA — inclusive quais mapeamentos emitem boleto sozinhos — sem abrir cadastro por cadastro.
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. É lá também que fica o Dias vencimento, usado quando a Condição de Pagamento é informada no formato
3x. - Conta bancária — em Financeiro → Contas Bancárias. O campo Banco é obrigatório, então sem pelo menos uma conta cadastrada você não consegue salvar o mapeamento.
- Integração bancária (só para Boleto automático) — em Configurações → Integrações, com o banco emissor configurado.
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):
- Com a janela de cadastro aberta, clique no campo Código canal.
- No final do dropdown, há um campo Digite... com um botão Adicionar.
- Digite o código exatamente como o canal usa e clique em Adicionar.
- O código aparece preenchido no campo principal.
- Continue preenchendo e salve.
Como editar um mapeamento existente?
- Na lista, clique no ícone de lápis na linha (ou dê duplo clique).
- Edite os campos desejados.
- Clique em Salvar.
Pré-requisito: privilégio Editar hub pagamento.
Como excluir um mapeamento?
- Na lista, clique no ícone de lixeira na linha.
- Confirme na janela.
- 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 apenas quando a linha é idêntica nos três campos: Integração + Código canal + Tipo de pagamento. A mensagem "De/para pagamento já existe" só aparece nesse caso exato.
Se você criar uma nova regra com o mesmo Código canal, mas apontando para um Tipo de pagamento diferente do já cadastrado, o sistema não bloqueia — ele cria uma segunda linha ambígua para o mesmo código, o que deixa o resultado da importação imprevisível. Por isso, para mudar o tipo de pagamento interno de um código existente, edite o mapeamento atual em vez de 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+Tipo é 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.
Boas práticas para o mapeamento
Um DE-PARA de pagamento bem montado evita pedido sem classificação financeira, título a receber genérico e retrabalho no Contas a Receber. Recomendações:
- Cadastre os tipos de pagamento internos antes de começar. O lado PARA usa a lista de Financeiro → Tipo Pagamento — sem ela cadastrada, você não consegue concluir o mapeamento.
- Mapeie todos os códigos que cada canal envia. Quando chega um código sem mapeamento, o título a receber sai sem classificação correta e bagunça o relatório financeiro — cubra cartão, boleto, PIX e cada parcelamento que o canal usa.
- Aponte vários códigos do canal para o mesmo tipo interno quando fizer sentido. "creditCard", cartão à vista e cartão parcelado podem todos cair em "Cartão de Crédito" — o relatório fica limpo e você não precisa de um tipo interno para cada variação do canal.
- Para corrigir um código, edite o mapeamento em vez de criar outro. O sistema só bloqueia duas regras idênticas nos três campos (Integração + Código canal + Tipo de pagamento) — criar uma nova regra com o mesmo código apontando para um tipo de pagamento diferente não é bloqueado e gera uma segunda linha ambígua. Abra a linha existente e troque o tipo de pagamento em vez de criar uma nova.
- Digite o código exatamente como o canal usa quando precisar incluí-lo na mão. Um caractere errado faz o pedido não casar com a regra e cair sem tipo de pagamento.
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 configurar | O que define |
|---|---|
| Configurações → Integrações | Cadastra os canais de venda que aparecem no campo Integração e as integrações bancárias que aparecem no campo Integração bancária. |
| Financeiro → Tipo Pagamento | Cadastra os tipos de pagamento internos que aparecem no campo Tipo pagamento. O Dias vencimento do tipo é o intervalo usado quando a Condição de Pagamento está no formato 3x. |
| Financeiro → Contas Bancárias | Cadastra as contas que aparecem no campo Banco (previsão do recebimento). |
A regra de preenchimento automático do Código canal na edição (exceto em alguns canais específicos) é 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égio | Libera |
|---|---|
| Visualizar hub pagamento | Acesso à tela, à lista e à visualização dos mapeamentos. |
| Criar hub pagamento | Botão Novo e o cadastro de um novo mapeamento. |
| Editar hub pagamento | Edição de um mapeamento existente (lápis ou duplo clique). |
| Deletar hub pagamento | Exclusão de um mapeamento (ícone de lixeira). |