Sistema B2B profissional para Magento 2 Open Source

O Kowal B2B Suite é um pacote de módulos Magento 2 concebido para empresas que querem realizar vendas B2B em Magento Open Source sem abdicar do catálogo nativo, carrinho, checkout, MSI, store view, website scope e mecanismos de integração da plataforma.
Compatibilidade
2.4.9, 2.4.8, 2.4.7
Hyva Theme
Hyva Theme Redy
307,50 €
Enviar por Email a um Amigo

Pedir informações sobre este produto

Descrição / Sistema B2B profissional para Magento 2 Open Source

MAGENTO 2 · MAGENTO OPEN SOURCE · EMPRESAS · COMÉRCIO B2B

Combine vendas B2B e B2C numa única instalação Magento.

Kowal B2B Suite alarga o Magento Open Source com empresas, verificação de números de IVA intracomunitário no VIES, condições comerciais individuais, listas de compras, propostas RFQ, crédito comercial, aprovações, documentos e integrações.

Sirva os clientes empresariais através de um portal de autosserviço e gira o trabalho comercial na administração Magento.

17 módulos e um tema base · REST e GraphQL · Adaptador de conta Hyvä

COMO FUNCIONA NA PRÁTICA

01 · Defina o modelo de venda
Configure empresas, canais, preços e origens de dados.

02 · Configure o processo B2B
Atribua funções, acesso ao catálogo, condições e aprovações.

03 · Ligue os sistemas e implemente
Escolha os adaptadores e verifique cenários completos.

Todas as funcionalidades do Kowal B2B Suite

Desde o registo do cliente empresarial e a definição do preço até às propostas, encomendas, documentos e troca de dados. Escolha as áreas a ativar de acordo com as regras de venda da sua empresa.

Empresas e ciclo de vida do cliente

Gira os registos das empresas com nome, identificação fiscal, identificador externo e representante comercial.

  • Registo e aprovação de empresas, ativação, bloqueio ou rejeição.
  • Estados: pendente, ativa, inativa, bloqueada e rejeitada.
  • Ligações às contas de cliente Magento, aos grupos de clientes e aos canais de venda.
  • Histórico de alterações a empresas, utilizadores, funções, moradas e contactos.

Utilizadores, funções, moradas e contactos

Cada empresa pode ter vários compradores e funções próprias com permissões definidas.

  • Atribuição e desativação de utilizadores e alteração das suas funções.
  • Permissões separadas para efetuar encomendas, consultar encomendas da empresa, RFQ, documentos, utilizadores e moradas.
  • Moradas de faturação e entrega, predefinições por website e moradas partilhadas da empresa.
  • Contactos da empresa, incluindo um contacto principal; a edição depende das permissões.
  • Os dados e a identificação fiscal da empresa mantêm-se separados dos dados pessoais da morada do comprador.

Verificação de números de IVA intracomunitário no VIES

Verifique números de IVA intracomunitário com o prefixo do país diretamente na ficha da empresa B2B, na administração Magento. O botão «Validar no VIES» inicia a verificação e apresenta o resultado junto ao campo do identificador fiscal.

  • Números de IVA da UE com código de país, por exemplo PL1234567890; a verificação abrange os países que o Magento reconhece como membros da UE.
  • Normalização dos dados introduzidos: os espaços, pontos e hífenes são ignorados e as letras são convertidas em maiúsculas antes da verificação.
  • Suporte para o prefixo grego EL através da correspondência com o código de país GR utilizado pelo Magento.
  • Verificação do formato e do país antes de enviar o pedido ao VIES, com uma mensagem quando é necessário corrigir os dados.
  • Resultados distintos: número válido no VIES, inválido no VIES, dados de entrada incorretos ou verificação indisponível.

Um administrador autorizado inicia a verificação de uma empresa e de um número de IVA previamente guardados, no contexto de um canal B2B ativo atribuído à empresa. Um número alterado deve ser guardado primeiro.

Resultados VIES guardados e atualidade dos dados

O resultado é guardado imediatamente na empresa, juntamente com a data e hora da verificação e o número de IVA verificado. Isto facilita a identificação dos dados que precisam de ser verificados novamente.

  • Coluna de estado VIES na lista de empresas com filtros: não verificado, válido, inválido, formato incorreto ou VIES indisponível.
  • Coluna da data de verificação com filtragem por intervalo de datas.
  • Reposição após alteração do número de IVA: guardar um número diferente repõe o estado «não verificado» e elimina a data anterior e o número verificado que estava guardado.
  • Preservação do resultado quando muda apenas a formatação, como espaços, separadores ou maiúsculas e minúsculas, e ao editar outros dados da empresa.
  • Associação do resultado ao número correto: se o número de IVA mudar durante a verificação, o módulo recusa guardar o resultado do número anterior e solicita uma nova tentativa.

Quando o serviço não consegue verificar o número, o administrador recebe uma mensagem específica de verificação indisponível, com a indicação de tentar novamente mais tarde. Um erro de ligação é distinguido de um resultado VIES negativo.

B2B e B2C numa única instalação

Ative o B2B nos websites Magento selecionados. Todas as vistas de loja desse website utilizam o modo B2B, enquanto os restantes websites podem servir clientes B2C.

  • Uma empresa pode estar associada a vários websites B2B ativos.
  • O estado ativo da relação e o grupo de clientes da empresa são configurados separadamente para cada website.
  • Preços, catálogos, documentos, limites, propostas e integrações funcionam no contexto correto da empresa e do canal.
  • Adicionar uma associação a um website não move as contas de cliente Magento nem altera automaticamente os seus grupos.

Controlo de acesso e portal B2B privado

Escolha entre três modelos: loja pública, loja com autenticação obrigatória ou catálogo público com restrições para visitantes não autenticados.

  • Autenticação obrigatória com exceções para determinadas ações ou caminhos de URL.
  • Regresso à página inicialmente solicitada após a autenticação.
  • Controlos independentes para ocultar preços e impedir compras de visitantes não autenticados.
  • Mensagens personalizadas e ligação de autenticação em vez do preço ou do botão de compra.
  • Ocultação dos controlos padrão de adicionar ao carrinho e bloqueio da adição no servidor na loja clássica.
  • Registo de clientes aberto ou desativado.

A proteção da loja padrão deve ser implementada separadamente numa API pública personalizada ou numa interface headless.

Migração de clientes existentes para empresas

A ação em massa Assign or Create Company ajuda a organizar a base de clientes Magento existente.

  • Filtragem de clientes com ou sem empresa associada, incluindo em exportações e ações em massa.
  • Correspondência com uma empresa pela identificação fiscal normalizada ou criação de uma nova; as contas sem identificação fiscal recebem empresas separadas.
  • Cópia das moradas predefinidas e do contacto principal para uma empresa recém-criada.
  • Atribuição de uma função de comprador com permissões B2B básicas.
  • Preservação dos grupos de clientes existentes, exclusão das contas já associadas e apresentação dos resultados e erros de migração.

Administração e operações em massa

Gira empresas e dados associados a partir de um único menu B2B. Os registos de cliente Magento incluem um campo de associação à empresa.

  • Listas e formulários para empresas, utilizadores, funções, moradas, contactos e registos de auditoria.
  • Alterações em massa ao estado, representante comercial, associação ao website, estado ativo da relação e grupo de clientes da empresa.
  • Criação ou atualização de funções em massa, com a opção de atribuir uma função a todos os utilizadores ativos das empresas selecionadas.
  • Uma transação separada e registos de auditoria para cada empresa processada.
  • Permissões dos administradores Magento para limitar o acesso a operações individuais.

Tabelas de preços, preços contratuais e escalões de quantidade

Defina preços por empresa, website, SKU, moeda e quantidade. Os preços contratuais têm prioridade, seguidos da tabela B2B atribuída e, por fim, dos preços do catálogo Magento.

  • Várias tabelas de preços e atribuições às empresas com prioridades.
  • Preços contratuais e linhas de tabelas com escalões de quantidade e campos para o período de validade.
  • Aplicação dos preços contratuais e das tabelas no carrinho.
  • Indexação de preços, auditoria das alterações e ferramenta Explain Price para identificar a origem do preço selecionado.
  • Importação e exportação CSV das linhas das tabelas e acesso aos preços através da API.

As sugestões de preço RFQ consideram a loja, o cliente, a quantidade, a moeda e os impostos; quando é utilizado o preço do catálogo, incluem também as promoções Magento aplicáveis.

Catálogo específico para cada empresa

Controle a visibilidade dos produtos através de regras para uma empresa ou para todo um website.

  • Regras para produtos selecionados, categorias ou todo o catálogo.
  • Ações de permissão e negação; a negação tem prioridade.
  • Índice de visibilidade e filtragem das listagens de produtos na loja.
  • Verificação do acesso a SKU ocultos e nova validação nas listas de compras, RFQ e finalização da compra.
  • Consulta da visibilidade dos produtos para uma empresa e reconstrução do índice através da API.

A ausência de uma regra correspondente não oculta, por si só, um produto. A oferta continua a basear-se no catálogo nativo Magento.

Encomendas rápidas e listas de compras

Os clientes criam listas de compras com nome e adicionam vários artigos por SKU, sem procurar cada produto individualmente.

  • Colagem de até 100 linhas de cada vez: SKU, quantidade e nota opcional, por exemplo SKU-001;10;Entregar no armazém.
  • Listas com indicação de lista predefinida, artigos, último preço B2B e moeda.
  • Validação do SKU, estado do produto, associação ao website, visibilidade para a empresa, quantidade positiva e preço B2B.
  • Adição de uma lista ao carrinho após nova validação.
  • Os administradores podem consultar listas, remover artigos e exportar as linhas para CSV.
  • Debug SKU e ecrãs de registos de importação e erros por linha dos processos que fornecem estes dados.

RFQ: pedidos a partir da conta do cliente

Um comprador autorizado pode enviar um pedido de cotação com título, nota e entre 1 e 200 artigos.

  • Pesquisa por SKU, nome do produto e atributos existentes EAN, EAN13, GTIN ou código de barras.
  • Sugestões limitadas a produtos simples e virtuais ativos e visíveis.
  • Quantidade, preço unitário líquido pretendido opcional e comentário por artigo.
  • Pré-visualização dos preços sem e com impostos; as alterações de quantidade atualizam as sugestões e preservam os preços introduzidos manualmente.
  • Preços tratados na moeda da loja e de acordo com a sua configuração fiscal.
  • Validação do pedido completo: um artigo inválido anula a gravação e o formulário mantém os dados para correção.

RFQ: preparação e negociação de propostas

Os comerciais também podem criar RFQ na administração Magento, selecionando website, Store View, empresa, cliente, moeda e produtos.

  • Gravação de um rascunho ou de um pedido submetido; pesquisa de produtos com sugestões de preços sem e com impostos.
  • Preços solicitados e propostos, total negociado, data de validade, comentários e notas comerciais.
  • Estados do processo, histórico de decisões e proteção contra a aceitação de propostas expiradas.
  • Envio da proposta preparada por e-mail com ligações aos detalhes e ao PDF que exigem autenticação.
  • Aceitação ou rejeição pelo cliente, motivo de rejeição opcional e decisões do administrador.
  • PDF distintos para cliente e administrador; as notas internas e o histórico administrativo permanecem na versão de administração.

Da proposta aceite à encomenda

Transfira os artigos e preços acordados de uma proposta aceite para o processo de compra Magento.

  • Convert to Cart cria um carrinho de cliente com os artigos e preços da proposta.
  • Um cliente com permissão para encomendar prossegue para a finalização de compra padrão, escolhendo morada, entrega e pagamento.
  • Create Order na administração cria automaticamente uma encomenda quando estão disponíveis as moradas necessárias e métodos de pagamento e entrega sem ambiguidades.
  • Se ainda for necessário selecionar condições, a proposta é carregada no formulário nativo de criação de encomendas da administração Magento.
  • Preservação do contexto Store View da proposta e da ligação ao carrinho ou à encomenda preparados.

Finalização da compra, pagamentos, entregas e números PO

Adicione regras B2B ao processo de encomenda padrão Magento.

  • Verificação da empresa ativa, associação ao website e permissão do utilizador para efetuar encomendas.
  • Validação do catálogo e da disponibilidade dos preços B2B ao efetuar a encomenda.
  • Regras para métodos de pagamento e entrega permitidos por empresa e website.
  • Moradas de faturação e entrega da empresa com predefinições específicas por canal.
  • Número da ordem de compra do cliente (PO) e comentário da encomenda.
  • Registo da empresa, comprador e estados de crédito, aprovação e exportação no contexto B2B da encomenda.

Limites de crédito comercial e prazos de pagamento

Acompanhe o limite de crédito, a utilização e o montante disponível separadamente para cada empresa, website e moeda.

  • Prazos de pagamento, ativação ou bloqueio do limite e opção de permitir a sua ultrapassagem.
  • Seleção dos métodos de pagamento que utilizam o crédito da empresa; os restantes funcionam sem um limite configurado.
  • Reserva atómica antes de efetuar a encomenda, associada à encomenda gravada.
  • Libertação da reserva após falha sem criação de encomenda, pagamento integral, cancelamento ou encerramento.
  • Ajustes manuais da utilização, detalhes da exposição e histórico de eventos.
  • Reconciliação por cron após interrupção do processo ou erro temporário.

Um pagamento parcial mantém a totalidade da reserva até à liquidação integral ou ao cancelamento.

Aprovação de encomendas e controlo do processamento

Defina regras de aprovação por empresa, website, moeda e limiar de valor da encomenda. A prioridade e o limiar determinam a regra aplicável quando várias correspondem.

  • Atribuição de utilizadores ativos da empresa como aprovadores.
  • Criação automática de um pedido pendente para uma encomenda que corresponda a uma regra.
  • Aprovação, rejeição ou cancelamento com comentário e registo de auditoria.
  • Marcação da exportação como bloqueada e suspensão da encomenda quando o seu estado o permite.
  • A aprovação atualiza o estado B2B e levanta a suspensão; a rejeição ou o cancelamento mantém a exportação bloqueada.

O processo incluído encerra um pedido pendente com uma única decisão. A aprovação em várias etapas exige uma extensão adicional e a integração deve respeitar o estado de bloqueio da exportação.

Documentos comerciais no portal do cliente

Disponibilize faturas, notas de crédito, guias de remessa e confirmações de encomenda à empresa correta.

  • Criação automática de documentos a partir de encomendas, faturas, expedições e notas de crédito Magento Sales.
  • Configuração da origem dos documentos, do estado inicial e da geração de cada tipo de documento; suporte de um modelo híbrido Magento + API.
  • Carregamento manual de PDF na administração, metadados, datas, montantes, moedas e ligações a entidades Magento.
  • Partilha dos ficheiros originais de um sistema externo sem alterar o conteúdo.
  • Transferências verificadas de acordo com a empresa, website, permissões e estado do documento.
  • Pré-visualização do acesso do cliente, ficheiros e registos de sincronização na administração.

PDF editáveis e versões linguísticas

Um gerador PDF comum suporta documentos de venda e propostas RFQ.

  • Edição de modelos HTML/CSS na administração e pré-visualização com dados de exemplo.
  • Modelos separados por tipo de documento, website e destinatário; um modelo local tem prioridade sobre um global.
  • Títulos personalizados para confirmações, faturas, notas de crédito, guias de remessa e propostas comerciais.
  • Logótipo, dados do vendedor e comprador, identificações fiscais, moradas, artigos, totais, informações e instruções de pagamento e entrega nos documentos Sales.
  • Versão RFQ para o cliente separada dos dados internos do administrador.
  • Etiquetas traduzidas de acordo com a língua da loja; os dicionários incluem polaco e muitas outras línguas europeias.

As alterações aos modelos aplicam-se aos novos PDF gerados. Os ficheiros anteriormente gravados têm de ser gerados novamente.

Conta da empresa e adaptador Hyvä Themes

O portal da empresa reúne dados da empresa, moradas, contactos, utilizadores, documentos, crédito, listas de compras e RFQ.

  • Moradas da empresa e as cinco encomendas mais recentes no painel nativo da conta.
  • Consulta de encomendas pessoais ou de toda a empresa conforme as permissões, ligações PDF protegidas e repetição da encomenda pelo comprador original autorizado.
  • Seis definições de visibilidade para ligações nativas: moradas, encomendas, transferências, pagamentos guardados, avaliações e newsletter.
  • Adaptador Hyvä Themes opcional incluído, com tabelas, formulários e navegação da conta adaptáveis ao ecrã.
  • Ativação por Store View; desativado por predefinição e ativo apenas com Hyvä e B2B.

O adaptador abrange a conta do cliente. Hyvä Checkout, carrinho e minicarrinho exigem um âmbito de integração separado. As definições do menu controlam a visibilidade das ligações; as permissões são verificadas de forma independente.

Importação e exportação CSV de dados B2B

Transfira e atualize dados através de perfis associados a um website específico.

  • Empresas, atribuições de utilizadores e funções com permissões.
  • Definições das tabelas de preços, preços contratuais e regras de visibilidade do catálogo.
  • Metadados de documentos, ligações a ficheiros de documentos existentes e limites de crédito comercial.
  • Carregamento de CSV, validação e modo dry-run para verificar a importação antes de gravar.
  • Histórico de tarefas, registos de erros por linha e transferência de relatórios de erros e ficheiros exportados.
  • Importação e exportação separadas das linhas das tabelas de preços em Pricing.

A importação de atribuições de utilizadores usa contas Magento existentes; a importação de ficheiros de documentos faz referência a ficheiros já disponíveis numa localização permitida.

API REST e GraphQL

Disponibilize os processos B2B a integrações ou interfaces personalizadas através da API.

  • REST: configuração de websites, empresas e utilizadores, produtos, disponibilidade MSI, preços, catálogo, listas de compras, RFQ, documentos, limites, aprovações, contexto de encomenda, importação/exportação e integrações.
  • Operações em lote para empresas e chave de idempotência na criação de empresas.
  • Relatórios de produtos, incluindo traduções em falta e dados de inventário.
  • Consultas GraphQL para dados da empresa, preços, listas, propostas, documentos, crédito, aprovações e tarefas de integração.
  • Mutações GraphQL para listas de compras, processos RFQ e publicação, processamento e repetição de tarefas de integração.

O acesso depende das permissões e do contexto da operação. REST e GraphQL disponibilizam contratos definidos; os respetivos conjuntos de operações não são idênticos.

Integrações ERP, PIM, WMS e CRM

O pacote fornece a infraestrutura para ligar Magento aos sistemas da sua empresa.

  • Perfis por website, tipo de sistema, direção da troca de dados e adaptador.
  • Mapeamentos entre identificadores locais e externos.
  • Criação de tarefas de sincronização com hora agendada, dados de entrada e chave de idempotência.
  • Estados de processamento, resultados, número de tentativas, registos e erros.
  • Repetição manual da mesma tarefa e consulta das tarefas que exigem intervenção na Dead Letter Queue.

Ligar um sistema ERP, PIM, WMS, CRM, EDI ou de aprovisionamento específico exige um adaptador e um processo de tratamento em funcionamento. A implementação define as origens de empresas, preços, existências, encomendas e documentos.

Painel, relatórios e diagnóstico

O painel B2B apresenta o número e os estados das empresas, utilizadores ativos, tabelas de preços, regras de catálogo, erros e alterações recentes.

  • Relatórios sobre empresas sem website ativo, utilizadores ou tabela de preços e sobre clientes sem empresa.
  • Relatórios de preços indexados, dados de origens MSI e traduções de nomes de produtos em falta.
  • Documentos sem ficheiros, erros de importação e integração e encomendas a aguardar aprovação ou bloqueadas para exportação.
  • Filtragem de relatórios por website, pré-visualização dos registos e exportação CSV.
  • Estado do sistema, auditorias de empresas e decisões, registos de crédito e sincronização, ferramentas Explain Price e Debug SKU.
  • Configuração do diagnóstico B2B e da retenção de registos.

Um pacote, arquitetura modular

O pacote kowal/metapackage-b2b-suite contém 17 módulos Magento e o tema base frontend/Kowal/b2b. Inclui Base, Access Control, Company, Admin UI, Pricing, Catalog Permissions, Quick Order, Quote, Checkout, Credit Limit, Approval, Document, Import/Export, Integration, REST API, GraphQL e o adaptador Hyvä opcional.

A instalação é feita através de um único pacote Composer. Após a concessão de acesso ao repositório, a implementação inclui ativar os módulos necessários, atualizar a base de dados Magento, configurar websites e empresas, compilar, publicar recursos e limpar as caches de acordo com o modo de implementação da loja.

Requisitos e âmbito da implementação

O projeto destina-se ao Magento Open Source 2.4.9 e o pacote requer PHP ^8.3. Utiliza o catálogo, carrinho, finalização da compra e MSI nativos do Magento, além do gerador mPDF.

Estão disponíveis a loja Magento clássica e um adaptador opcional para a conta Hyvä Themes. O tema B2B base é um ponto de partida para personalizar a aparência do portal.

O âmbito depende da versão da loja, tema, pagamentos, entregas e sistemas externos. A compatibilidade e o percurso de compra completo devem ser verificados na instalação de destino.

Planeie uma implementação B2B à medida da sua empresa

Pretende adaptar o módulo à sua loja? Peça informações sobre a implementação do Kowal B2B Suite e discuta a configuração ou extensões adicionais.

Antes de planear a implementação, leia como reduzir as operações manuais de venda B2B em Magento 2 e quanto custa realmente processar manualmente uma encomenda B2B (artigos em polaco).

Mais informação

Hyva Theme Hyva Theme Redy
Compatibilidade com o modelo Hyvä, Luma / Blank, KOWAL

Configuração da integração

Kowal B2B API — documentação REST completa

Versão do contrato: V1 · Fonte da verdade: Kowal_B2BApi/etc/webapi.xml · Destinatários: administradores de lojas, parceiros de implementação e equipas que integram ERP, PIM, WMS ou sistema de compras.

1. Finalidade e limites da API

A Kowal B2B API disponibiliza dados e processos B2B em funcionamento no Magento 2: empresas, catálogo e preços individuais, compras rápidas, documentos, limite de crédito comercial, aprovações, RFQ e filas de integração. É uma REST API para integrações de sistemas; não substitui os endpoints padrão do Magento para catálogo, carrinho, checkout e conta de cliente.

O documento descreve exclusivamente os endpoints atualmente expostos pelo módulo. Não inclui promessa de operações que o contrato V1 não disponibiliza, por exemplo, criação de encomenda por REST, CRUD de listas de preços ou edição da configuração de website.

2. Obtenção de acesso e regras de colaboração

2.1. Processo de lançamento da integração

  1. O integrador comunica ao administrador da loja o objetivo da integração, ambiente (teste/produção), sistema de origem, âmbito dos dados e lista das áreas API necessárias.
  2. O administrador cria ou configura a integração Magento, atribui-lhe permissões ACL mínimas e transmite por canal seguro: baseUrl, token, websiteId, companyId (quando aplicável), moeda e dados de teste.
  3. O integrador executa o teste GET /V1/kowal-b2b/websites/:websiteId/config e, em seguida, testes funcionais no ambiente de teste.
  4. Antes da produção, ambas as partes acordam o calendário de sincronização, tamanho máximo dos dados, retry, proprietário dos dados e forma de reportar erros.
  5. Os tokens são armazenados exclusivamente num cofre de segredos; o administrador roda-os ou revoga-os quando há alteração de fornecedor, utilizador ou âmbito da integração.

2.2. Responsabilidades

ParteResponsabilidade
Administrador da lojaConfiguração do B2B website, empresa e relação da empresa com o website, token e ACL; fornecimento de dados de teste; decisão sobre o acesso aos dados.
IntegradorArmazenamento seguro do token, uso correto do contexto websiteId/companyId, validação de dados, tratamento de erros e repetições, não divulgação de dados de outras empresas.
Proprietário do processo de negócioDefinição da fonte da verdade para preços, documentos, RFQ, limites e estados de sincronização.

Não se deve usar o token de administrador numa aplicação cliente nem partilhar um token único por sistemas independentes. Cada integração deve ter o seu próprio token e apenas as ACL necessárias.

2.3. Permissões

O Magento verifica o token Bearer e as ACL atribuídas ao utilizador administrativo ou à integração. Os endpoints B2B exigem um dos seguintes grupos de permissões:

ACLÂmbito
configWebsites e feature flags
companies, company_save, company_users, batchEmpresas, os seus utilizadores e importação em lote de empresas
products, prices, catalog_permissionsCatálogo, disponibilidade, preços e visibilidade
import_export, quick_order, documentsPerfis de importação/exportação, listas de compras e documentos
credit_limits, approvals, orders, quotesLimite, workflow de aprovação, contexto de encomendas e RFQ
system_integrationsPerfis, mapeamentos e jobs de integração

O âmbito deve resultar da finalidade da integração. Exemplo: um sistema de compras precisa normalmente de products, prices, catalog_permissions, quick_order e quotes; um ERP que trate documentos — documents e, se for proprietário da sincronização, system_integrations.

3. Convenções técnicas

Endereço, cabeçalhos e parâmetros

O endereço base tem a forma https://b2b.example.com/rest/V1. Todos os caminhos seguintes neste documento são indicados a partir de /V1; o endereço completo do endpoint é BASE_URL + caminho.

Authorization: Bearer Accept: application/jsonContent-Type: application/json

A API usa JSON. Os nomes no URL estão em camelCase (websiteId, companyId) e os campos JSON correspondem aos nomes dos parâmetros dos contratos Magento. :companyId, :quoteId, :sku etc. são parâmetros de caminho. Nos exemplos, ? indica um parâmetro opcional.

websiteId é obrigatório em operações dependentes do canal de venda. Deve apontar para um website existente com B2B ativado. companyId indica a empresa que deve ter uma relação ativa com esse website quando a operação funciona no seu contexto. A API não seleciona website nem empresa predefinidos.

Request body e idempotência

O Magento serializa o objeto DTO sob o nome do parâmetro do método: a maioria das gravações aceita {'request': {...}}; a criação de empresa usa {'company': {...}}; o batch de empresas — {'companies': [...]}. Endpoints com argumentos simples aceitam campos sem wrapper, por exemplo, {'websiteId': 1, 'currency': 'PLN', 'items': [...]}.

O cabeçalho Idempotency-Key (máx. 128 caracteres) é atualmente suportado por POST /companies: repetir com a mesma chave devolverá a empresa criada anteriormente. Para o job de integração, use o campo request.idempotencyKey. Não assuma idempotência automática de outros endpoints de escrita; repita-os apenas depois de determinar o status da operação.

Respostas e erros

As respostas de sucesso são objetos ou arrays de contratos Magento. Os campos devolvidos pelos objetos podem ser expandidos de forma compatível; a integração deve ignorar campos desconhecidos. Um erro de negócio pode conter:

{ 'code': 'b2b.company.not_assigned_to_website', 'message': 'B2B company is not assigned to website.', 'website_id': 1, 'trace_id': 'request-correlation-id', 'details': {'company_id': 10}, 'field_errors': []}
HTTPSignificadoReação do integrador
400 / 422Dados incorretos ou validação de domínioCorrija os dados; não repita sem alterar o payload.
401 / 403Token/ACL inexistente ou insuficienteNão repita; reporte ao administrador o âmbito do token.
404O recurso ou a relação não existe no contexto indicadoVerifique os identificadores e o contexto website.
409Conflito de status ou duplicadoLeia o estado atual antes de decidir repetir.
5xx / timeoutErro técnicoAplique retry limitado com backoff e conserve o trace_id.

Não registe tokens, dados pessoais completos nem segredos de configuração. O reporte à equipa da loja deve conter hora, método, caminho sem segredos, status HTTP, trace_id e payload anonimizado.

4. Esquemas de dados de entrada

Os esquemas abaixo são comuns aos endpoints de referência. Um campo sem ? é exigido pelo contrato; ? indica valor opcional. Os campos metadata, config, configuration e payload são objetos JSON.

DTO / wrapperCampos
companywebsiteId, name, taxId, externalId?, status?, salesRepresentativeId?, customerGroupId?, websiteActive?
companyUserwebsiteId, roleId, active
request — RFQwebsiteId, companyId, customerId?, externalId?, title, currency, validUntil?, customerNote?, salesNote?, metadata?
request — item RFQquoteId, sku, productId?, name?, qty, requestedPrice?, offeredPrice?, comment?, metadata?
request — decisão RFQcustomerId?, adminUserId?, message?
request — comentário RFQquoteId, customerId?, adminUserId?, authorType, message, visibleForCustomer
request — documentowebsiteId, companyId, orderId?, orderIncrementId?, invoiceId?, invoiceIncrementId?, creditmemoId?, creditmemoIncrementId?, externalId?, documentNumber, documentType, status, issueDate?, dueDate?, grandTotal?, currency?, metadata?
request — ficheiro de documentodocumentId, fileName, filePath, mimeType, fileSize, checksum?, primary
request — limitewebsiteId, companyId, termsId?, creditLimit, currency, active, status, metadata?
request — exposição do limitewebsiteId, companyId, sourceType, sourceId, sourceIncrementId?, amount, currency, dueDate?, metadata?
request — condições de pagamentowebsiteId, code, name, daysDue, active, description?
request — regra de aprovaçãowebsiteId, companyId, name, thresholdAmount, currency?, priority, active, metadata?
request — aprovadorruleId, customerId, sortOrder, active
request — decisão de aprovaçãoapproverCustomerId?, comment?
request — pedido de aprovaçãowebsiteId, companyId, orderId?, orderIncrementId?, requesterCustomerId?, grandTotal, currency, comment?, metadata?
request — perfil import/exportwebsiteId, code, name, direction, entityType, format, behavior, active, configuration?
request — perfil de integraçãowebsiteId, code, name, systemType, adapterCode, direction, active, maxAttempts, config?
request — mapeamentowebsiteId, systemType, entityType, localId, externalId, metadata?
request — job de integraçãoprofileId, direction?, entityType, operation, idempotencyKey?, maxAttempts?, payload?, scheduledAt?

5. Referência de endpoints

Nas tabelas, ACL significa o recurso mínimo de permissão Magento. Resultado define o tipo de resposta de sucesso.

5.1. Websites e configuração

Método e endpointACLEntradaResultado e utilização
GET /V1/kowal-b2b/websitesconfig—Array de website (websiteId, código, nome, flag B2B). Obtenha antes da configuração da integração.
GET /V1/kowal-b2b/websites/:websiteId/configconfigpath: websiteIdConfiguração B2B do website (incl. enabled/debug/retenção de logs). Execute como teste de acesso.
GET /V1/kowal-b2b/websites/:websiteId/featuresconfigpath: websiteIdFeature flags ativas para o website; use para ativação condicional de funcionalidades do cliente.

5.2. Empresas e utilizadores de empresa

Método e endpointACLEntradaResultado e utilização
GET /companies?websiteId=companiesquery: websiteIdArray de empresas atribuídas ao website.
POST /companiescompany_savebody: companyCria uma empresa e a relação com o website; use Idempotency-Key em repetições. Devolve a empresa.
POST /companies/batchbatchbody: companies — array companyCria várias empresas e devolve o resultado por elemento, incluindo erros.
GET /companies/:companyId?websiteId=companiespath: companyId; query: websiteIdEmpresa verificada no contexto do website.
PUT /companies/:companyIdcompany_savepath: companyId; body: companyAtualiza os dados e a relação da empresa para company.websiteId.
POST /companies/:companyId/activate?websiteId=company_savepath: companyId; query: websiteIdAtiva a empresa no website indicado e devolve a empresa.
POST /companies/:companyId/block?websiteId=company_savepath: companyId; query: websiteIdBloqueia a empresa no website indicado e devolve a empresa.
GET /companies/:companyId/users?websiteId=company_userspath: companyId; query: websiteIdArray de atribuições de clientes à empresa.
PUT /companies/:companyId/users/:customerIdcompany_userspath: companyId, customerId; body: companyUserAtribui/atualiza a função e atividade do cliente na empresa; devolve a atribuição.

5.3. Produtos, preço e visibilidade do catálogo

Método e endpointACLEntradaResultado e utilização
GET /products?websiteId=productsquery: websiteIdArray de produtos Magento básicos para o website.
GET /products/:sku?websiteId=productspath: sku codificado; query: websiteIdProduto (id, sku, nome, tipo, status, websites).
GET /products/:sku/availability?websiteId=productspath: sku; query: websiteIdDisponibilidade e quantidade vendável MSI para o SKU.
GET /products/:sku/b2b-status?websiteId=productspath: sku; query: websiteIdStatus B2B: atribuição ao website, traduções e dados stock.
GET /reports/products/missing-translations?websiteId=productsquery: websiteIdRelatório de SKU sem traduções necessárias, com reason/details.
GET /reports/products/missing-stock?websiteId=productsquery: websiteIdRelatório de SKU sem dados stock necessários.
GET /companies/:companyId/products/:sku/price?websiteId=&currency=&qty=pricespath: companyId, sku; query: websiteId, currency, opc. qty (predefinido 1)Explicação do preço adequado para a empresa, moeda e quantidade; leia antes da compra.
GET /companies/:companyId/products/:sku/visibility?websiteId=catalog_permissionspath: companyId, sku; query: websiteIdResultado da visibilidade/compra do SKU para a empresa.
GET /companies/:companyId/catalog-visibility?websiteId=catalog_permissionspath: companyId; query: websiteIdArray de itens do índice do catálogo visível da empresa.
POST /companies/:companyId/catalog-visibility/reindex?websiteId=catalog_permissionspath: companyId; query: websiteIdReconstrói o índice e devolve o número de itens indexados. Operação administrativa.

5.4. Importação e exportação por ficheiro

Método e endpointACLEntradaResultado e utilização
GET /import-export/profiles?websiteId=import_exportquery: websiteIdArray de perfis de importação/exportação do website.
POST /import-export/profilesimport_exportbody: request — perfil import/exportGuarda o perfil e devolve os seus dados.
POST /import-export/import/:profileId?sourceFile=&dryRun=import_exportpath: profileId; query: sourceFile, opc. dryRun=falseInicia a importação do ficheiro indicado no ambiente Magento; devolve o job. Não envia multipart.
POST /import-export/export/:profileId?resultFile=import_exportpath: profileId; query opc.: resultFileCria um job de exportação, opcionalmente com caminho de ficheiro de destino.
GET /import-export/jobs?websiteId=import_exportquery: websiteIdArray de jobs import/export para o website.
GET /import-export/jobs/:jobIdimport_exportpath: jobIdEstado, resultado e dados de um único job.
GET /import-export/jobs/:jobId/logsimport_exportpath: jobIdLogs de diagnóstico do job.

5.5. Encomenda rápida e listas de compras

Método e endpointACLEntradaResultado e utilização
POST /companies/:companyId/quick-order/validatequick_orderpath: companyId; body: websiteId, currency, items (sku, qty)Valida vários SKU no contexto da empresa: disponibilidade, visibilidade e preço; devolve resultado agregado.
GET /companies/:companyId/shopping-lists?websiteId=quick_orderpath: companyId; query: websiteIdArray de listas de compras da empresa.
POST /companies/:companyId/shopping-listsquick_orderpath: companyId; body: websiteId, name, opc. customerId, isDefault=falseCria uma lista de compras e devolve-a.
GET /shopping-lists/:listId/itemsquick_orderpath: listIdArray de itens da lista indicada.
POST /shopping-lists/:listId/itemsquick_orderpath: listId; body: currency, items (sku, qty)Adiciona itens à lista e devolve os itens guardados.

5.6. Documentos e ficheiros

Método e endpointACLEntradaResultado e utilização
GET /companies/:companyId/documents?websiteId=&documentType=documentspath: companyId; query: websiteId, opc. documentTypeDocumentos da empresa, opcionalmente filtrados por tipo.
GET /documents/:documentId?companyId=&websiteId=documentspath: documentId; query: companyId, websiteIdDetalhes do documento após verificar a pertença da empresa.
POST /documentsdocumentsbody: request — documentoCria ou guarda metadados do documento e devolve o documento.
POST /documents/filesdocumentsbody: request — ficheiro de documentoRegista um ficheiro existente no storage Magento (nome, caminho, MIME, tamanho), não envia binários.
GET /documents/:documentId/files?companyId=&websiteId=documentspath: documentId; query: companyId, websiteIdArray de metadados dos ficheiros do documento.
GET /documents/:documentId/sync-logsdocumentspath: documentIdLogs de sincronização do documento; destinados à integração administrativa.

5.7. Limite de crédito comercial e condições de pagamento

Método e endpointACLEntradaResultado e utilização
GET /companies/:companyId/credit/status?websiteId=&currency=credit_limitspath: companyId; query: websiteId, currencyStatus do limite, utilização e montante disponível da empresa.
POST /credit-limitscredit_limitsbody: request — limiteCria/atualiza o limite da empresa e devolve o limite.
POST /credit/exposurescredit_limitsbody: request — exposiçãoReserva a exposição do limite para a origem (por exemplo, encomenda) e devolve-a.
POST /credit/exposures/:exposureId/releasecredit_limitspath: exposureId; body opc.: messageLiberta a exposição; devolve o seu estado.
GET /payment-terms?websiteId=credit_limitsquery: websiteIdArray de condições de pagamento ativas/conhecidas do website.
POST /payment-termscredit_limitsbody: request — condições de pagamentoGuarda as condições de pagamento e devolve-as.

5.8. Workflow de aprovação

Método e endpointACLEntradaResultado e utilização
GET /companies/:companyId/approval/rules?websiteId=&currency=approvalspath: companyId; query: websiteId, opc. currencyRegras de aprovação da empresa para canal/moeda.
POST /approval/rulesapprovalsbody: request — regraCria/atualiza uma regra de limiar e devolve-a.
GET /approval/rules/:ruleId/approversapprovalspath: ruleIdArray de aprovadores atribuídos, por ordem sortOrder.
POST /approval/approversapprovalsbody: request — aprovadorGuarda a atribuição do cliente como aprovador.
GET /companies/:companyId/approval/required?websiteId=&grandTotal=&currency=approvalspath: companyId; query: websiteId, grandTotal, currencyBoolean: se o montante exige aprovação.
POST /approval/requestsapprovalsbody: request — pedido de aprovaçãoCria um request para a encomenda e devolve-o.
GET /companies/:companyId/approval/requests?websiteId=&status=approvalspath: companyId; query: websiteId, opc. statusArray de requests de aprovação da empresa.
POST /approval/requests/:requestId/approveapprovalspath: requestId; body: request — decisãoAprova o request; devolve o seu estado atual.
POST /approval/requests/:requestId/rejectapprovalspath: requestId; body: request — decisãoRejeita o request; devolve o seu estado atual.
POST /approval/requests/:requestId/cancelapprovalspath: requestId; body: request — decisãoCancela o request; devolve o seu estado atual.
GET /approval/requests/:requestId/decisionsapprovalspath: requestIdHistórico de decisões do request.

5.9. Contexto B2B de encomendas

Método e endpointACLEntradaResultado e utilização
GET /orders/:orderId/b2b-contextorderspath: orderIdContexto B2B de uma encomenda Magento nativa individual (por exemplo, empresa, status de aprovação, limite, exportação).
GET /companies/:companyId/orders/b2b-context?websiteId=&approvalStatus=orderspath: companyId; query: websiteId, opc. approvalStatusArray de contextos de encomendas da empresa, opcionalmente filtrado por status de aprovação.

5.10. RFQ e ofertas comerciais

Método e endpointACLEntradaResultado e utilização
GET /companies/:companyId/quotes?websiteId=&status=quotespath: companyId; query: websiteId, opc. statusRFQ e ofertas da empresa, opcionalmente por status.
POST /quotesquotesbody: request — RFQCria um RFQ em rascunho e devolve-o. Adicione itens através de endpoint separado.
GET /quotes/:quoteIdquotespath: quoteIdDetalhes do RFQ/oferta.
GET /quotes/:quoteId/itemsquotespath: quoteIdArray de itens RFQ.
POST /quotes/itemsquotesbody: request — item RFQAdiciona SKU e quantidade, preço solicitado/oferecido opcional e comentário.
GET /quotes/:quoteId/commentsquotespath: quoteIdComentários RFQ. O cliente vê apenas comentários marcados como visíveis.
POST /quotes/commentsquotesbody: request — comentário RFQAdiciona mensagem; authorType e visibleForCustomer definem autor e visibilidade.
GET /quotes/:quoteId/historyquotespath: quoteIdHistórico de alterações de status e eventos RFQ.
POST /quotes/:quoteId/submitquotespath: quoteId; body: request — decisão RFQSubmete o RFQ em rascunho para cotação.
POST /quotes/:quoteId/make-offerquotespath: quoteId; body: request — decisão RFQO comercial cria/submete a oferta; antes da chamada, defina os preços dos itens.
POST /quotes/:quoteId/acceptquotespath: quoteId; body: request — decisão RFQAceita a oferta atual. Neste contrato, não cria uma encomenda REST.
POST /quotes/:quoteId/rejectquotespath: quoteId; body: request — decisão RFQRejeita a oferta/RFQ.
POST /quotes/:quoteId/cancelquotespath: quoteId; body: request — decisão RFQCancela o RFQ, se o status atual o permitir.

5.11. Perfis e jobs de integração

Método e endpointACLEntradaResultado e utilização
GET /integrations/profiles?websiteId=&systemType=system_integrationsquery: websiteId, opc. systemTypePerfis de integração para o website.
POST /integrations/profilessystem_integrationsbody: request — perfil de integraçãoGuarda o perfil ERP/PIM/WMS etc. e devolve-o.
POST /integrations/mappingssystem_integrationsbody: request — mapeamentoGuarda o par ID local ↔ ID externo.
GET /integrations/mappings/local?websiteId=&systemType=&entityType=&localId=system_integrationsquery: todos os parâmetros obrigatóriosLocaliza o mapeamento pelo identificador Magento.
GET /integrations/mappings/external?websiteId=&systemType=&entityType=&externalId=system_integrationsquery: todos os parâmetros obrigatóriosLocaliza o mapeamento pelo identificador do sistema externo.
POST /integrations/jobssystem_integrationsbody: request — jobPublica o job para execução; idempotencyKey identifica a operação de negócio.
GET /integrations/jobs?websiteId=&status=system_integrationsquery: websiteId, opc. statusArray de jobs de integração.
GET /integrations/jobs/:jobIdsystem_integrationspath: jobIdEstado e detalhes de um único job.
POST /integrations/jobs/:jobId/processsystem_integrationspath: jobIdProcessa o job e devolve o seu estado atual.
POST /integrations/jobs/:jobId/retrysystem_integrationspath: jobIdRepete o job após erro, de acordo com o seu limite de tentativas.
GET /integrations/jobs/:jobId/logssystem_integrationspath: jobIdLogs de execução do job.
GET /integrations/jobs/:jobId/errorssystem_integrationspath: jobIdErros de domínio/técnicos do job.

6. Exemplos de chamadas

export BASE_URL='https://b2b.example.com/rest/V1'export TOKEN='token-przekazany-przez-administratora'export WEBSITE_ID=1 COMPANY_ID=10 SKU='B2B-SKU-001' CURRENCY='PLN'# Test dostępu i konfiguracji kanałucurl -sS '$BASE_URL/kowal-b2b/websites/$WEBSITE_ID/config'  -H 'Authorization: Bearer $TOKEN' -H 'Accept: application/json'# Cena kontraktowa firmy dla konkretnej ilościcurl -sS '$BASE_URL/kowal-b2b/companies/$COMPANY_ID/products/$SKU/price?websiteId=$WEBSITE_ID&currency=$CURRENCY&qty=5'  -H 'Authorization: Bearer $TOKEN' -H 'Accept: application/json'# Walidacja koszyka po SKUcurl -sS -X POST '$BASE_URL/kowal-b2b/companies/$COMPANY_ID/quick-order/validate'  -H 'Authorization: Bearer $TOKEN' -H 'Content-Type: application/json'  --data '{'websiteId':1,'currency':'PLN','items':[{'sku':'B2B-SKU-001','qty':5}]}'# Utworzenie RFQcurl -sS -X POST '$BASE_URL/kowal-b2b/quotes'  -H 'Authorization: Bearer $TOKEN' -H 'Content-Type: application/json'  --data '{'request':{'websiteId':1,'companyId':10,'customerId':25,'title':'Dostawa kwartalna','currency':'PLN','externalId':'ERP-RFQ-2026-001'}}'

7. Cenários de integração recomendados

Compra por SKU

  1. Leia a configuração do website e guarde o websiteId, companyId e moeda fornecidos.
  2. Use quick order para validação agregada de SKU, quantidade, visibilidade e disponibilidade.
  3. Para os itens aceites, obtenha o preço de price com o qty correto.
  4. Crie RFQ, adicione itens e envie-os por submit, se a compra exigir oferta.
  5. Acompanhe o status e o histórico do RFQ; após a aceitação, siga o processo de encomenda Magento acordado, porque V1 não expõe endpoint de criação de order.

Documentos e faturação

  1. Obtenha a lista de documentos da empresa, opcionalmente filtrando por documentType.
  2. Para o documento selecionado, obtenha metadados e lista de ficheiros; o caminho do ficheiro não é automaticamente um URL público — acorde com o administrador da loja a forma de descarregar o binário.
  3. Leia o status do limite antes do processo de compra; apenas a integração com ACL credit_limits pode geri-lo.

Operações assíncronas

  1. Guarde o perfil de integração e os mapeamentos de identificadores.
  2. Publique o job com idempotencyKey de negócio e conserve o jobId.
  3. Leia o job e os logs/erros; chame retry apenas depois de analisar o erro e remover a sua causa.

8. Lista de aceitação antes da produção

  • O token tem apenas as ACL necessárias e não é um token de administrador usado pela UI.
  • O integrador trata corretamente 401, 403, 404, validação 422, conflito 409 e timeouts.
  • Cada request no contexto B2B transmite o websiteId correto e os dados da empresa usam o companyId correto.
  • Preços, visibilidade e disponibilidade são verificados antes de criar o processo de compra.
  • A criação de empresa usa Idempotency-Key; os jobs de integração têm idempotencyKey estável no body.
  • Os logs não contêm tokens nem dados sensíveis, e o procedimento de suporte transmite trace_id.
  • Os testes foram realizados no ambiente de teste numa empresa que tem relação ativa com o B2B website.

9. Compatibilidade

O contrato é versionado por /V1. A extensão da resposta com novos campos é compatível; o integrador deve tolerar campos desconhecidos. Uma alteração que remova um campo, o significado de um campo ou um endpoint exige uma nova versão da API. Em caso de divergência entre o documento e a instalação em funcionamento, prevalece o contrato ativo webapi.xml da versão do módulo em causa.

Manual de instalação do módulo

Instalação e configuração do Kowal B2B Suite

Este manual destina-se à pessoa que comprou o Kowal B2B Suite e que tem de o colocar em funcionamento numa instalação existente do Magento Open Source. Orienta através de duas etapas:

  1. instalação técnica — realizada por um programador ou administrador do servidor;
  2. configuração de negócio — realizada no painel Magento pelo administrador da loja.

Antes de começar, faça uma cópia da base de dados e dos ficheiros Magento. Recomendamos que a primeira execução seja realizada num ambiente de teste e só depois implementada em produção.

1. O que recebe e do que precisa

O Kowal B2B Suite é fornecido como pacote Composer kowal/metapackage-b2b-suite. Inclui módulos B2B e o theme frontend/Kowal/b2b.

Requisitos

ElementoRequisito
MagentoMagento Open Source 2.4.9
PHP8.3
ComposerComposer 2
Acesso ao servidorSSH e possibilidade de executar bin/magento
Magentocatálogo, clientes, checkout, Sales, MSI e cron em funcionamento
PDFpossibilidade de escrita em var/ pelo processo PHP

Da Kowal receberá:

  • endereço do repositório Composer privado — doravante REPOSITORY_URL;
  • nome de utilizador ou identificador de acesso — USERNAME;
  • token de acesso — ACCESS_TOKEN;
  • intervalo de versões permitido do pacote.

Não guarde o token no repositório Git, em tickets nem no histórico da shell partilhada com outras pessoas.

2. Instalação técnica

Execute todos os comandos no diretório raiz da instalação Magento existente, como utilizador com acesso aos ficheiros e ao comando bin/magento.

2.1. Preparação

  1. Certifique-se de que o Magento funciona corretamente antes da alteração.
  2. Registe o estado da implementação e faça backup da base de dados e dos diretórios app/etc, pub/media e var.
  3. Em produção, ative o modo maintenance durante a atualização:
bin/magento maintenance:enable

2.2. Adicionar o repositório privado

Adicione o repositório Composer da Kowal e configure os dados de acesso recebidos.

Receberá por e-mail, após a compra, os dados de acesso ao repositório Composer, ou seja, o endereço de e-mail do cliente e o token de licença. Também estão disponíveis no painel do cliente após iniciar sessão em kowal.store. Substitua TWOJ_EMAIL_KLIENTA pelo endereço de e-mail da sua conta e TWOJ_TOKEN pelo token recebido. Execute os comandos no diretório raiz do Magento.

composer config repositories.kowal composer https://repo.kowal.storecomposer config http-basic.repo.kowal.store 'TWOJ_EMAIL_KLIENTA' 'TWOJ_TOKEN'

Normalmente, o Composer guarda as credenciais no auth.json local; não adicione este ficheiro ao Git.

2.3. Instalação do pacote

Instale a versão fornecida com a licença. Para a linha atual do pacote, um comando de exemplo tem a seguinte forma:

composer require kowal/metapackage-b2b-suite:^0.2 --with-all-dependencies

Depois de descarregar as dependências, atualize o esquema e a configuração do Magento:

bin/magento setup:upgradebin/magento cache:clean

No modo de produção, execute adicionalmente:

bin/magento setup:di:compilebin/magento setup:static-content:deploy -f pl_PL en_USbin/magento cache:flush

Utilize apenas os locale que estão ativos na loja. Se a instalação usar outro processo de deployment, inclua os comandos acima no respetivo procedimento padrão.

2.4. Verificação da instalação

bin/magento module:status | grep Kowalbin/magento indexer:status

No painel administrativo deverá aparecer o menu B2B e o separador Stores > Configuration > Kowal > B2B. Se não aparecerem, verifique o resultado de setup:upgrade, a cache e as funções ACL do utilizador administrador.

2.5. Permissões dos ficheiros PDF

Os PDF gerados pelo B2B utilizam mPDF e diretórios em var/, incluindo var/tmp/kowal_b2b_mpdf e var/kowal_b2b_documents. O processo PHP tem de poder criá-los e escrever neles. A falta destas permissões manifesta-se por erro na geração do documento ou do PDF.

Após concluir a implementação em produção, desative o maintenance:

bin/magento maintenance:disable

3. Configuração da estrutura da loja B2B

3.1. Website e store view

O Suite funciona ao nível de website, e não globalmente. Pode gerir B2C e B2B na mesma instalação Magento, mas o B2B deve funcionar num website separado ou num website de venda empresarial escolhido de forma consciente.

  1. Em Stores > Settings > All Stores, crie ou selecione o website B2B, o respetivo store e store view.
  2. Guarde o website_id — é usado por empresas, preços, documentos, API e integrações.
  3. Em Content > Design > Configuration, atribua o theme frontend/Kowal/b2b apenas ao B2B store view.
  4. Verifique se as moedas ativas, impostos, métodos de entrega e métodos de pagamento estão configurados para o mesmo scope.

Não atribua o theme B2B ao store view B2C se não quiser alterar a sua camada de apresentação. A instalação dos módulos por si só não ativa a lógica B2B para todos os website.

3.2. Ativação do B2B

  1. Abra Stores > Configuration > Kowal > B2B.
  2. No seletor de scope, escolha o Website correto.
  3. Na secção General, defina Enable B2B como Yes.
  4. Durante a implementação, pode ativar Debug Mode; desative-o após os testes.
  5. No scope Default Config, defina o período de retenção dos logs.
  6. Guarde a configuração e limpe a cache.

Após a ativação, todos os store view pertencentes a esse website são tratados como B2B. Uma empresa sem relação ativa com esse website não terá acesso a ele.

3.3. Dados do vendedor

Preencha os dados da empresa vendedora em Stores > Configuration > General > Store Information: nome, morada, telefone e NIF. São usados em documentos e PDF RFQ. Preencha também o endereço de e-mail geral do remetente na configuração Sales Emails e o logótipo de e-mail, se tiver de aparecer no PDF.

4. Configuração do primeiro cliente B2B

Use a sequência abaixo para cada empresa. Permite evitar uma situação em que o cliente tem conta, mas não vê a oferta ou não consegue passar pelo checkout.

4.1. Empresa, pessoas e endereços

  1. Abra B2B > Companies e crie a empresa.
  2. Indique o nome, NIF, identificador externo, se a empresa for sincronizada com ERP, status Active e atribuição ao B2B website.
  3. Adicione um utilizador da empresa ou atribua um cliente Magento existente. Atribua-lhe a função correta e ative a atribuição.
  4. Em B2B > Company Addresses, adicione os endereços da empresa; marque o endereço de faturação e de envio predefinido para o website B2B.
  5. Em B2B > Company Contacts, adicione um contacto principal ativo com e-mail e telefone.

O endereço de faturação e o contacto principal também são usados no PDF RFQ. A falta de dados não bloqueia o PDF, mas o documento ficará menos completo.

4.2. Funções da empresa

Atribua aos utilizadores apenas as permissões necessárias. Uma divisão típica é:

FunçãoExemplos de tarefas
Administrador da empresautilizadores, funções, endereços, documentos e histórico da empresa
Compradorcatálogo, encomenda rápida, carrinho, RFQ e encomendas
Aprovadordecisões no workflow de aprovação
Contabilidadedocumentos e informações de faturação

Teste a conta de cada tipo, especialmente a permissão para efetuar encomendas e aprovações. Não utilize uma conta comum para toda a empresa.

5. Oferta, preços e checkout

5.1. Catálogo e preços

  1. Certifique-se de que os produtos Magento estão atribuídos ao B2B website, ativos e com dados MSI corretos.
  2. Configure listas de preços ou preços contratuais para a empresa na área B2B > Pricing (Price Lists, Price List Assignments ou Contract Prices).
  3. Configure regras de visibilidade do catálogo para a empresa de acordo com o modelo de permissões implementado e, em seguida, verifique a visibilidade na conta do cliente.
  4. Teste na conta da empresa: pesquisa de SKU, visibilidade do produto e preço para a quantidade 1 e para o escalão de quantidade.

O preço B2B depende da empresa, website, moeda e quantidade. Um produto visível em B2C não tem de estar disponível para o cliente B2B.

5.2. Entrega e pagamento

  1. Ative os métodos de entrega e pagamento necessários na configuração padrão do Magento para o B2B store view.
  2. Em B2B > Checkout, adicione regras de métodos disponíveis para empresa/website, se quiser limitar a escolha.
  3. Realize um teste do carrinho com os endereços predefinidos da empresa.

Se a criação de encomenda a partir de RFQ tiver de funcionar automaticamente do lado do administrador, a empresa deve ter endereços predefinidos inequívocos, método de pagamento e entrega ativos. Caso contrário, o Suite carregará os dados para o Backend Order Create nativo, onde o administrador preenche os elementos em falta.

5.3. Limites e aprovações

Estas funcionalidades são opcionais, mas devem ser configuradas antes de serem disponibilizadas aos clientes.

  1. Em B2B > Credit > Payment Terms, adicione prazos de pagamento.
  2. Em B2B > Credit > Credit Limits, atribua à empresa limite, moeda, status e prazo de pagamento.
  3. Em B2B > Approvals > Rules, crie uma regra de limiar de valor para a empresa e website.
  4. Em B2B > Approvals > Approvers, atribua as pessoas aprovadoras.
  5. Teste o carrinho abaixo e acima do limiar e verifique se a decisão do aprovador altera o processo seguinte.

6. Documentos, PDF e RFQ

6.1. Documentos Magento

Em Stores > Configuration > Kowal > B2B > Documents, escolha a origem dos documentos e decida quais devem ser gerados automaticamente: confirmações de encomenda, faturas, guias de remessa e notas de crédito. Defina também o status de destino do documento.

Em B2B > Documents > PDF Templates:

  1. verifique o template ativo para cada tipo e website;
  2. faça a pré-visualização;
  3. ajuste HTML/CSS apenas se tiver uma pessoa que conheça templates Magento e CSS mPDF;
  4. gere uma fatura ou confirmação de teste e verifique o download a partir da conta da empresa.

6.2. RFQ e oferta PDF

  1. Em B2B > Quotes > RFQ, crie um RFQ de teste para uma empresa e utilizador ativos.
  2. Adicione SKU visível para a empresa, quantidade e preço da oferta.
  3. Defina a data de validade, envie a oferta ao cliente e gere o PDF.
  4. Verifique a variante do cliente: dados do vendedor/comprador, itens, preço, total e data de validade.
  5. Verifique a variante do administrador: adicionalmente, notas comerciais, comentários, histórico e informações internas sobre os itens.

O PDF do cliente não pode conter notas do comercial nem histórico interno de status.

7. Encomendas rápidas, importações e integrações

Encomendas rápidas

Em B2B > Quick Order > Debug SKU, verifique a lista SKU,qty para empresa, website e moeda. Em seguida, crie uma lista de compras e teste a sua utilização pelo cliente no storefront.

Importação e exportação

Em B2B > Import/Export, defina o perfil apenas depois de determinar a origem dos dados. A configuração do perfil é um objeto JSON e deve conter caminhos de ficheiros acessíveis no servidor Magento. Primeiro execute a importação em modo de teste e analise o job e os logs.

Integrações API

Antes de criar o token de integração, defina o âmbito dos dados e o proprietário da sincronização. Use uma integração Magento separada para cada ERP, PIM, WMS ou middleware e atribua-lhe apenas as ACL B2B necessárias. A lista completa de endpoints, tokens e regras de segurança encontra-se na documentação API para integradores.

8. Checklist de aceitação

Antes do lançamento em produção, confirme:

  • Os módulos Kowal estão ativos, o cron funciona e a cache e os índices estão corretos.
  • O B2B está ativado apenas para o website correto.
  • O theme B2B está atribuído apenas ao B2B store view.
  • A empresa de teste tem status Active, utilizador, função, contacto e endereços predefinidos.
  • O produto de teste está ativo, atribuído ao website, visível para a empresa e tem preço B2B correto.
  • O cliente consegue iniciar sessão, pesquisar SKU, usar quick order e adicionar o produto ao carrinho.
  • O checkout mostra apenas os métodos de entrega e pagamento permitidos.
  • O limite e a regra de aprovação funcionam de acordo com a política da empresa, se estas funcionalidades forem usadas.
  • O documento e o PDF RFQ são gerados e estão disponíveis apenas para a empresa correta.
  • O RFQ pode ser enviado, aceite e encaminhado para o processo de criação de encomenda.
  • As integrações têm tokens separados e ACL limitadas, se forem usadas.

9. Problemas mais frequentes

SintomaO que verificar
Não há menu B2Bsetup:upgrade, status dos módulos, cache e ACL do administrador.
A empresa ou o cliente não vê o B2BSe o B2B está ativo para o website correto e se a empresa tem uma relação ativa com esse website.
O produto não está visível ou não tem preçoAtribuição do produto ao website, atividade do SKU, dados MSI, regras de catálogo, preço da empresa, moeda e quantidade.
Falta método de entrega ou pagamentoConfiguração padrão do Magento, scope B2B store view e regras B2B Checkout.
O PDF não é geradoTemplate PDF ativo, pacote mPDF, permissões para var/, dados do vendedor e logs Magento.
O RFQ não cria encomenda automaticamenteEndereços predefinidos da empresa, pagamento e entrega inequívocos; nos restantes casos, use Backend Order Create.
A API devolve 403O token de integração não tem a ACL necessária; não use o token de administrador numa aplicação externa.

Ao contactar o suporte, indique a versão do Magento, a versão do pacote, os passos de reprodução, a hora do evento, logs anonimizados de forma segura e eventual trace_id. Não envie tokens nem palavras-passe.

10. Atualização do pacote

  1. Consulte a informação de versão fornecida pela Kowal.
  2. Execute primeiro a atualização no ambiente de teste.
  3. Faça backup, composer update kowal/metapackage-b2b-suite --with-all-dependencies, bin/magento setup:upgrade e, em produção, também a compilação DI e o deployment dos recursos estáticos.
  4. Repita a checklist de aceitação, com especial atenção a preços, checkout, documentos e integrações.

Não atualize o pacote copiando ficheiros manualmente para app/code; isso causa problemas com o Composer e dificulta o suporte posterior.

Pressione para saltar o carrossel

Encontrámos outros produtos que podem ser do seu interesse!

Magento 2 BaseLinker Stock Export - synchronizacja stanów magazynowych z ERP i Magento do BaseLinker
30,75 €
Kowal Analytics para Magento 2
30,75 €
Escreva a sua própria avaliação
Está a avaliar: Sistema B2B profissional para Magento 2 Open Source
A sua classificação:
Preço
Qualidade
Suporte
loader
Carregando...

Classificação enviada para aprovação.

Perguntas e respostas

Question
O Kowal B2B Suite funciona com Magento 2 Open Source?
Answer
Sim. Acrescenta funcionalidades de venda B2B ao Magento 2 Open Source, permitindo muitos processos grossistas e contratuais sem migrar para Adobe Commerce.
Question
Czy każdy klient B2B może mieć własne ceny i katalog produktów?
Answer
Tak. System pozwala odwzorować indywidualne warunki handlowe kontrahentów, w tym ceny, katalogi, progi ilościowe i zasady zakupowe. Zakres konfiguracji jest dopasowywany do modelu sprzedaży firmy.
Question
Czy jedna firma może mieć wielu użytkowników z różnymi uprawnieniami?
Answer
Tak. W ramach jednego kontrahenta można obsługiwać wielu użytkowników i różne role zakupowe. Pozwala to rozdzielić między innymi składanie zamówień, ich akceptację oraz dostęp do danych i dokumentów.
Question
Czy system B2B można zintegrować z ERP, PIM, WMS lub CRM?
Answer
Tak. Kowal B2B Suite może wymieniać dane z zewnętrznymi systemami, między innymi ERP, PIM, WMS i CRM. Integracja może obejmować produkty, ceny, klientów, zamówienia, dokumenty, statusy oraz inne dane wymagane przez konkretny proces biznesowy.
Question
Czy wdrożenie platformy B2B można realizować etapami?
Answer
Tak. Wdrożenie może rozpocząć się od podstawowych funkcji, takich jak firmy, użytkownicy, ceny i katalogi, a następnie zostać rozszerzone o szybkie zamówienia, RFQ, limity kupieckie, akceptacje, dokumenty oraz integracje.
Alterar preferências de cookies