Integrações B2B no Magento 2: Profiles, Mappings e controlo da sincronização no B2B Suite

Integrar Magento 2 com ERP, PIM, WMS ou CRM exige mais do que enviar dados para uma API. É preciso identificar a empresa, relacionar identificadores, verificar resultados e tratar mensagens recusadas. Em B2B, isso determina se a encomenda chega ao processamento, o cliente é reconhecido e a lista acordada alcança o canal correto.

Integrations no Kowal B2B Suite organiza esse trabalho em cinco áreas: Profiles, Mappings, Sync Jobs, Dead Letter Queue e Sync Errors. Explicamos o funcionamento e a utilização diária.

A descrição corresponde à implementação verificada em novembro de 2026. Os exemplos são ilustrativos e pressupõem um adaptador implementado para o sistema e a operação indicados.

O que fornece Integrations e o que faz o adaptador?

Integrations fornece infraestrutura comum: perfis, associações de identificadores, registo de tarefas, controlo de tentativas, resultados e histórico de erros. Um adaptador realiza a ligação concreta a ERP, PIM, WMS ou CRM e conhece a API e as regras desse sistema.

O adaptador define autenticação, formatos, transformação de campos e execução. Escolher “ERP” descreve a finalidade do perfil; não instala automaticamente uma ligação pronta a qualquer ERP.

Guardar uma tarefa apenas regista trabalho. O formulário não inicia um processo periódico em segundo plano. Processamento e seleção de tarefas devem ser ligados na implementação, por exemplo através de executor, agendamento ou middleware que utilize a lógica e a API disponíveis.

Cinco ecrãs, cinco perguntas concretas

Os elementos descrevem o mesmo processo de perspetivas diferentes. O perfil define contexto, as associações ligam registos, a tarefa representa a operação e as últimas vistas ajudam a tratar falhas.

Profiles: configurar a integração para o website correto

Em B2B > Integrations > Profiles cria e edita perfis. Cada um pertence a um website Magento com B2B ativo. Pode separar canais nacionais e de exportação quando usam websites distintos.

Website é aqui a unidade organizativa de um canal Magento. Várias vistas linguísticas no mesmo website não significam várias integrações independentes.

Config JSON não tem campos universais para todas as integrações. O adaptador interpreta as chaves. O formulário valida JSON, mas não substitui um teste de ligação. Convém referenciar configuração segura para as credenciais, segundo os requisitos do adaptador.

O integrador usa um perfil com nome em vez de repetir parâmetros ERP em scripts separados. O operador identifica o sistema e a direção do processo.

Mappings: ligar identificadores Magento e externos

Uma empresa pode ter ID 42 no B2B Suite e código ERP-C-0084 no ERP. Uma pessoa reconhece o mesmo cliente; a integração precisa de uma ligação explícita para ler ou atualizar a ficha correta.

Mappings guarda website, tipo de sistema, entidade, ID local, ID externo e metadados JSON opcionais. A interface prevê empresas, clientes, produtos, categorias, listas de preços, encomendas, RFQ e documentos.

Os valores são exemplos. O adaptador decide a representação do identificador local de cada entidade. As associações podem ser procuradas por ID local ou externo.

Mappings relaciona identidades de registos; não é um editor visual para transformar campos. Regras como “nome do cliente ERP para o campo company do Magento” pertencem ao adaptador. Guardar uma associação não transfere nem sincroniza dados por si só.

O contexto inclui website, tipo de sistema e entidade, não apenas um perfil. Com várias ligações do mesmo tipo num website, o integrador deve planear identificação coerente. A base exige unicidade dos ID locais e externos nesse contexto.

Sync Jobs: registar trabalho e acompanhar a sincronização

Um Sync Job representa uma operação, como enviar uma encomenda para ERP. Em Schedule Sync Job escolhe perfil ativo, entidade e operação. Pode indicar direção, entrada JSON, chave de idempotência, limite de tentativas e data agendada. Sem alteração, a direção vem do perfil.

O adaptador deve compreender a entidade e o nome da operação. export_order pode integrar a solução acordada, mas introduzir esse nome não implementa a exportação.

View mostra resumo, entrada, resultado do adaptador, registos e erros. Permite verificar website, perfil, direção, entidade, operação, tentativas, chave e horas de agendamento, início e fim.

Interprete success segundo o contrato do adaptador. Se a API externa só aceita mensagens para processamento posterior, defina se o resultado confirma receção ou conclusão da operação comercial.

A data agendada informa o executor. Defini-la não substitui o processo de execução nem as regras para selecionar tarefas prontas.

Idempotência: limitar tarefas duplicadas

Após uma interrupção, o middleware pode submeter novamente a mesma operação. Uma chave de idempotência reconhece a tarefa existente. Publicar com a mesma chave no mesmo website devolve esse registo em vez de criar outro.

A chave deve identificar uma operação concreta, como exportar uma versão da encomenda. É comum ao website: inclua contexto reconhecível de sistema e operação. Reutilizar uma chave antiga não atualiza a entrada da tarefa existente.

Isto evita registos duplicados de tarefas. Prevenir efeitos repetidos no ERP, como um segundo documento após uma resposta incerta, exige também medidas no adaptador e possibilidades da API externa.

Dead Letter Queue: tarefas que exigem uma decisão

Dead Letter Queue mostra tarefas dead. É uma vista dos mesmos registos, não uma segunda cópia das mensagens. Separa operações que não terminaram dentro do limite permitido.

Com três tentativas, a terceira execução falhada define dead. O módulo não lança automaticamente três tentativas consecutivas. Execuções seguintes e intervalos dependem do mecanismo de repetição e do executor implementados.

O operador abre a tarefa, analisa e corrige a causa, por exemplo uma associação de cliente em falta ou a ligação. Depois pode usar Retry Job.

A repetição está disponível para failed e dead. Não cria outra tarefa nem reinicia o histórico de tentativas. Define retry, agenda o momento atual e limpa as horas anteriores de início e fim. Se o limite foi esgotado, aumenta-o para permitir outra tentativa. Só o processamento posterior executa o adaptador.

Sync Errors: histórico de erros com contexto

Sync Errors mostra erros do adaptador: código, mensagem, hora e possibilidade de repetição. Associa-os ao contexto atual de tarefa, perfil e website, distinguindo um problema individual de uma falha geral.

Os detalhes incluem erros e registos técnicos, como início, conclusão e agendamento das repetições. Os dados de erro guardam também um rasto técnico útil ao integrador.

Uma tarefa pode acumular erros de várias tentativas. O número de erros não corresponde às operações pendentes. Uma tarefa concluída mais tarde pode conservar erros anteriores.

Retryable depende das tentativas restantes no momento do erro. Não deteta automaticamente causas temporárias. Um ID errado não se corrige repetindo, mesmo que haja outra tentativa permitida.

A distinção principal: Sync Errors ajuda a analisar causas; Dead Letter Queue lista tarefas com tentativas esgotadas.

Cenário 1: ligar a empresa B2B ao cliente ERP

A Alfa tem conta Magento e uma ficha ERP existente. A equipa quer evitar duplicar o cliente.

1. O integrador prepara o adaptador ERP e o perfil do website correto.
2. Mappings liga a empresa 42 a ERP-C-0084.
3. A tarefa do adaptador usa a associação para o registo existente.
4. O operador confirma resultado e identificadores devolvidos em Sync Jobs.

A identidade do cliente mantém-se coerente. Os campos atualizados e o sistema que os gere fazem parte do âmbito acordado.

Cenário 2: enviar uma encomenda B2B após interrupção

O cliente encomenda e o mecanismo cria uma tarefa de exportação. O ERP está temporariamente indisponível. O adaptador falha, o erro é guardado e a tarefa recebe failed ou, esgotadas as tentativas, dead.

Após restabelecer a ligação, o operador verifica o resultado anterior no ERP e agenda Retry da mesma tarefa. O adaptador deve reconhecer documentos existentes para evitar duplicação se o pedido inicial foi aceite apesar da resposta perdida.

O resultado concluído pode incluir o ID do documento ERP e o adaptador pode guardar uma associação. Conteúdo e momento dependem da implementação.

Cenário 3: atualizar preços do canal B2B correto

O ERP é a fonte das condições comerciais. O canal grossista tem perfil de importação e associação da lista 7 a ERP-PRICELIST-DEALERS.

O adaptador lê o ERP, verifica SKU, moeda e escalões e guarda segundo Pricing. Sync Job acompanha a operação; o resultado pode resumir entradas processadas. Perante problemas, o operador tem contexto e mensagem.

Integrations gere o fluxo; Pricing escolhe o preço. Veja listas B2B e Price List no Magento 2. Validação, escritas parciais e atualizações do índice devem ser definidas no adaptador.

Cenário 4: um erro recorrente exige corrigir dados

O armazém recusa a operação porque não reconhece um produto. Repetir não altera a situação. A tarefa esgota as tentativas e aparece em Dead Letter Queue.

O operador abre View Job, lê a mensagem e verifica os ID. Se falta uma ligação, corrige Mappings. Resolvida a causa, escolhe Retry Job e verifica o resultado seguinte.

O cenário demonstra a necessidade de associações e histórico. A fila permite retomar a operação; o diagnóstico indica o que corrigir antes da nova tentativa.

Implementar Integrations passo a passo

1. Escolha o primeiro processo. Comece pela exportação de encomendas, em vez de ligar todas as áreas.
2. Defina as fontes. Decida quem gere cliente, lista ou estado e como resolver conflitos.
3. Prepare adaptador e executor. Defina operações, formatos, autenticação, execução e repetições.
4. Configure Profiles e Mappings. Verifique website, direção e ID com casos reais.
5. Teste sucessos e falhas. Inclua API indisponível, dados inválidos, pedidos repetidos e tentativas esgotadas.
6. Verifique o resultado comercial. Confirme o registo correto no destino, além do estado.
7. Atribua responsabilidades. Defina quem acompanha Sync Errors e Dead Letter Queue e corrige dados ou ligações.

Assim avalia operações bem tratadas e tempo de resolução, não apenas a existência de uma ligação API.

Perguntas frequentes sobre Integrations no B2B Suite

Um perfil ERP fornece integração pronta com qualquer ERP?

Não. Guarda contexto e configuração. Um adaptador para a API e os processos acordados assegura a comunicação.

Mappings transforma campos de importação?

Liga identificadores locais e externos. Transformação de campos e formatação de dados cabem ao adaptador.

Retry envia dados imediatamente?

Não. Reagenda a tarefa existente. Envio ou recolha ocorrem na execução seguinte do processo ligado.

Qual a diferença entre Dead Letter Queue e Sync Errors?

A primeira mostra tarefas dead; o segundo, erros contextualizados. O histórico pode manter erros de operações concluídas depois.

O módulo repete automaticamente de poucos em poucos minutos?

Guarda datas, estados e contadores e permite repetir. Calendário, intervalos e seleção automática devem ser configurados na solução executora.

A integração pode ser gerida por API?

A API B2B Suite gere perfis, associações, publicação, processamento e repetição de tarefas e consulta de tarefas, registos e erros. Exige permissões de integração e contexto de website quando necessário.

Integração B2B sob controlo da equipa

Profiles organiza configuração, Mappings identidades, Sync Jobs progresso e Dead Letter Queue e Sync Errors falhas. Em conjunto, formam uma base extensível para integrar Magento 2 com adaptadores adequados à empresa.

Conheça Kowal B2B Suite para Magento 2 Open Source ou descreva o processo a ligar a ERP, PIM, WMS ou CRM. Comece pelo sistema, direção e uma operação hoje manual.

Leia também: reduzir o tratamento manual das vendas B2B e o custo do tratamento manual de encomendas B2B.