Sistema B2B profissional para Magento 2 Open Source
- Compatibilidade
- 2.4.9, 2.4.8, 2.4.7
- Hyva Theme
- Hyva Theme Redy
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
- 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.
- 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. - O integrador executa o teste
GET /V1/kowal-b2b/websites/:websiteId/confige, em seguida, testes funcionais no ambiente de teste. - 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.
- 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
| Parte | Responsabilidade |
|---|---|
| Administrador da loja | Configuraçã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. |
| Integrador | Armazenamento 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ócio | Definiçã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 |
|---|---|
config | Websites e feature flags |
companies, company_save, company_users, batch | Empresas, os seus utilizadores e importação em lote de empresas |
products, prices, catalog_permissions | Catálogo, disponibilidade, preços e visibilidade |
import_export, quick_order, documents | Perfis de importação/exportação, listas de compras e documentos |
credit_limits, approvals, orders, quotes | Limite, workflow de aprovação, contexto de encomendas e RFQ |
system_integrations | Perfis, 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': []}| HTTP | Significado | Reação do integrador |
|---|---|---|
400 / 422 | Dados incorretos ou validação de domínio | Corrija os dados; não repita sem alterar o payload. |
401 / 403 | Token/ACL inexistente ou insuficiente | Não repita; reporte ao administrador o âmbito do token. |
404 | O recurso ou a relação não existe no contexto indicado | Verifique os identificadores e o contexto website. |
409 | Conflito de status ou duplicado | Leia o estado atual antes de decidir repetir. |
5xx / timeout | Erro técnico | Aplique 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 / wrapper | Campos |
|---|---|
company | websiteId, name, taxId, externalId?, status?, salesRepresentativeId?, customerGroupId?, websiteActive? |
companyUser | websiteId, roleId, active |
request — RFQ | websiteId, companyId, customerId?, externalId?, title, currency, validUntil?, customerNote?, salesNote?, metadata? |
request — item RFQ | quoteId, sku, productId?, name?, qty, requestedPrice?, offeredPrice?, comment?, metadata? |
request — decisão RFQ | customerId?, adminUserId?, message? |
request — comentário RFQ | quoteId, customerId?, adminUserId?, authorType, message, visibleForCustomer |
request — documento | websiteId, companyId, orderId?, orderIncrementId?, invoiceId?, invoiceIncrementId?, creditmemoId?, creditmemoIncrementId?, externalId?, documentNumber, documentType, status, issueDate?, dueDate?, grandTotal?, currency?, metadata? |
request — ficheiro de documento | documentId, fileName, filePath, mimeType, fileSize, checksum?, primary |
request — limite | websiteId, companyId, termsId?, creditLimit, currency, active, status, metadata? |
request — exposição do limite | websiteId, companyId, sourceType, sourceId, sourceIncrementId?, amount, currency, dueDate?, metadata? |
request — condições de pagamento | websiteId, code, name, daysDue, active, description? |
request — regra de aprovação | websiteId, companyId, name, thresholdAmount, currency?, priority, active, metadata? |
request — aprovador | ruleId, customerId, sortOrder, active |
request — decisão de aprovação | approverCustomerId?, comment? |
request — pedido de aprovação | websiteId, companyId, orderId?, orderIncrementId?, requesterCustomerId?, grandTotal, currency, comment?, metadata? |
request — perfil import/export | websiteId, code, name, direction, entityType, format, behavior, active, configuration? |
request — perfil de integração | websiteId, code, name, systemType, adapterCode, direction, active, maxAttempts, config? |
request — mapeamento | websiteId, systemType, entityType, localId, externalId, metadata? |
request — job de integração | profileId, 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 endpoint | ACL | Entrada | Resultado e utilização |
|---|---|---|---|
GET /V1/kowal-b2b/websites | config | — | Array de website (websiteId, código, nome, flag B2B). Obtenha antes da configuração da integração. |
GET /V1/kowal-b2b/websites/:websiteId/config | config | path: websiteId | Configuração B2B do website (incl. enabled/debug/retenção de logs). Execute como teste de acesso. |
GET /V1/kowal-b2b/websites/:websiteId/features | config | path: websiteId | Feature flags ativas para o website; use para ativação condicional de funcionalidades do cliente. |
5.2. Empresas e utilizadores de empresa
| Método e endpoint | ACL | Entrada | Resultado e utilização |
|---|---|---|---|
GET /companies?websiteId= | companies | query: websiteId | Array de empresas atribuídas ao website. |
POST /companies | company_save | body: company | Cria uma empresa e a relação com o website; use Idempotency-Key em repetições. Devolve a empresa. |
POST /companies/batch | batch | body: companies — array company | Cria várias empresas e devolve o resultado por elemento, incluindo erros. |
GET /companies/:companyId?websiteId= | companies | path: companyId; query: websiteId | Empresa verificada no contexto do website. |
PUT /companies/:companyId | company_save | path: companyId; body: company | Atualiza os dados e a relação da empresa para company.websiteId. |
POST /companies/:companyId/activate?websiteId= | company_save | path: companyId; query: websiteId | Ativa a empresa no website indicado e devolve a empresa. |
POST /companies/:companyId/block?websiteId= | company_save | path: companyId; query: websiteId | Bloqueia a empresa no website indicado e devolve a empresa. |
GET /companies/:companyId/users?websiteId= | company_users | path: companyId; query: websiteId | Array de atribuições de clientes à empresa. |
PUT /companies/:companyId/users/:customerId | company_users | path: companyId, customerId; body: companyUser | Atribui/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 endpoint | ACL | Entrada | Resultado e utilização |
|---|---|---|---|
GET /products?websiteId= | products | query: websiteId | Array de produtos Magento básicos para o website. |
GET /products/:sku?websiteId= | products | path: sku codificado; query: websiteId | Produto (id, sku, nome, tipo, status, websites). |
GET /products/:sku/availability?websiteId= | products | path: sku; query: websiteId | Disponibilidade e quantidade vendável MSI para o SKU. |
GET /products/:sku/b2b-status?websiteId= | products | path: sku; query: websiteId | Status B2B: atribuição ao website, traduções e dados stock. |
GET /reports/products/missing-translations?websiteId= | products | query: websiteId | Relatório de SKU sem traduções necessárias, com reason/details. |
GET /reports/products/missing-stock?websiteId= | products | query: websiteId | Relatório de SKU sem dados stock necessários. |
GET /companies/:companyId/products/:sku/price?websiteId=¤cy=&qty= | prices | path: 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_permissions | path: companyId, sku; query: websiteId | Resultado da visibilidade/compra do SKU para a empresa. |
GET /companies/:companyId/catalog-visibility?websiteId= | catalog_permissions | path: companyId; query: websiteId | Array de itens do índice do catálogo visível da empresa. |
POST /companies/:companyId/catalog-visibility/reindex?websiteId= | catalog_permissions | path: companyId; query: websiteId | Reconstró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 endpoint | ACL | Entrada | Resultado e utilização |
|---|---|---|---|
GET /import-export/profiles?websiteId= | import_export | query: websiteId | Array de perfis de importação/exportação do website. |
POST /import-export/profiles | import_export | body: request — perfil import/export | Guarda o perfil e devolve os seus dados. |
POST /import-export/import/:profileId?sourceFile=&dryRun= | import_export | path: profileId; query: sourceFile, opc. dryRun=false | Inicia a importação do ficheiro indicado no ambiente Magento; devolve o job. Não envia multipart. |
POST /import-export/export/:profileId?resultFile= | import_export | path: profileId; query opc.: resultFile | Cria um job de exportação, opcionalmente com caminho de ficheiro de destino. |
GET /import-export/jobs?websiteId= | import_export | query: websiteId | Array de jobs import/export para o website. |
GET /import-export/jobs/:jobId | import_export | path: jobId | Estado, resultado e dados de um único job. |
GET /import-export/jobs/:jobId/logs | import_export | path: jobId | Logs de diagnóstico do job. |
5.5. Encomenda rápida e listas de compras
| Método e endpoint | ACL | Entrada | Resultado e utilização |
|---|---|---|---|
POST /companies/:companyId/quick-order/validate | quick_order | path: 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_order | path: companyId; query: websiteId | Array de listas de compras da empresa. |
POST /companies/:companyId/shopping-lists | quick_order | path: companyId; body: websiteId, name, opc. customerId, isDefault=false | Cria uma lista de compras e devolve-a. |
GET /shopping-lists/:listId/items | quick_order | path: listId | Array de itens da lista indicada. |
POST /shopping-lists/:listId/items | quick_order | path: listId; body: currency, items (sku, qty) | Adiciona itens à lista e devolve os itens guardados. |
5.6. Documentos e ficheiros
| Método e endpoint | ACL | Entrada | Resultado e utilização |
|---|---|---|---|
GET /companies/:companyId/documents?websiteId=&documentType= | documents | path: companyId; query: websiteId, opc. documentType | Documentos da empresa, opcionalmente filtrados por tipo. |
GET /documents/:documentId?companyId=&websiteId= | documents | path: documentId; query: companyId, websiteId | Detalhes do documento após verificar a pertença da empresa. |
POST /documents | documents | body: request — documento | Cria ou guarda metadados do documento e devolve o documento. |
POST /documents/files | documents | body: request — ficheiro de documento | Regista um ficheiro existente no storage Magento (nome, caminho, MIME, tamanho), não envia binários. |
GET /documents/:documentId/files?companyId=&websiteId= | documents | path: documentId; query: companyId, websiteId | Array de metadados dos ficheiros do documento. |
GET /documents/:documentId/sync-logs | documents | path: documentId | Logs de sincronização do documento; destinados à integração administrativa. |
5.7. Limite de crédito comercial e condições de pagamento
| Método e endpoint | ACL | Entrada | Resultado e utilização |
|---|---|---|---|
GET /companies/:companyId/credit/status?websiteId=¤cy= | credit_limits | path: companyId; query: websiteId, currency | Status do limite, utilização e montante disponível da empresa. |
POST /credit-limits | credit_limits | body: request — limite | Cria/atualiza o limite da empresa e devolve o limite. |
POST /credit/exposures | credit_limits | body: request — exposição | Reserva a exposição do limite para a origem (por exemplo, encomenda) e devolve-a. |
POST /credit/exposures/:exposureId/release | credit_limits | path: exposureId; body opc.: message | Liberta a exposição; devolve o seu estado. |
GET /payment-terms?websiteId= | credit_limits | query: websiteId | Array de condições de pagamento ativas/conhecidas do website. |
POST /payment-terms | credit_limits | body: request — condições de pagamento | Guarda as condições de pagamento e devolve-as. |
5.8. Workflow de aprovação
| Método e endpoint | ACL | Entrada | Resultado e utilização |
|---|---|---|---|
GET /companies/:companyId/approval/rules?websiteId=¤cy= | approvals | path: companyId; query: websiteId, opc. currency | Regras de aprovação da empresa para canal/moeda. |
POST /approval/rules | approvals | body: request — regra | Cria/atualiza uma regra de limiar e devolve-a. |
GET /approval/rules/:ruleId/approvers | approvals | path: ruleId | Array de aprovadores atribuídos, por ordem sortOrder. |
POST /approval/approvers | approvals | body: request — aprovador | Guarda a atribuição do cliente como aprovador. |
GET /companies/:companyId/approval/required?websiteId=&grandTotal=¤cy= | approvals | path: companyId; query: websiteId, grandTotal, currency | Boolean: se o montante exige aprovação. |
POST /approval/requests | approvals | body: request — pedido de aprovação | Cria um request para a encomenda e devolve-o. |
GET /companies/:companyId/approval/requests?websiteId=&status= | approvals | path: companyId; query: websiteId, opc. status | Array de requests de aprovação da empresa. |
POST /approval/requests/:requestId/approve | approvals | path: requestId; body: request — decisão | Aprova o request; devolve o seu estado atual. |
POST /approval/requests/:requestId/reject | approvals | path: requestId; body: request — decisão | Rejeita o request; devolve o seu estado atual. |
POST /approval/requests/:requestId/cancel | approvals | path: requestId; body: request — decisão | Cancela o request; devolve o seu estado atual. |
GET /approval/requests/:requestId/decisions | approvals | path: requestId | Histórico de decisões do request. |
5.9. Contexto B2B de encomendas
| Método e endpoint | ACL | Entrada | Resultado e utilização |
|---|---|---|---|
GET /orders/:orderId/b2b-context | orders | path: orderId | Contexto 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= | orders | path: companyId; query: websiteId, opc. approvalStatus | Array de contextos de encomendas da empresa, opcionalmente filtrado por status de aprovação. |
5.10. RFQ e ofertas comerciais
| Método e endpoint | ACL | Entrada | Resultado e utilização |
|---|---|---|---|
GET /companies/:companyId/quotes?websiteId=&status= | quotes | path: companyId; query: websiteId, opc. status | RFQ e ofertas da empresa, opcionalmente por status. |
POST /quotes | quotes | body: request — RFQ | Cria um RFQ em rascunho e devolve-o. Adicione itens através de endpoint separado. |
GET /quotes/:quoteId | quotes | path: quoteId | Detalhes do RFQ/oferta. |
GET /quotes/:quoteId/items | quotes | path: quoteId | Array de itens RFQ. |
POST /quotes/items | quotes | body: request — item RFQ | Adiciona SKU e quantidade, preço solicitado/oferecido opcional e comentário. |
GET /quotes/:quoteId/comments | quotes | path: quoteId | Comentários RFQ. O cliente vê apenas comentários marcados como visíveis. |
POST /quotes/comments | quotes | body: request — comentário RFQ | Adiciona mensagem; authorType e visibleForCustomer definem autor e visibilidade. |
GET /quotes/:quoteId/history | quotes | path: quoteId | Histórico de alterações de status e eventos RFQ. |
POST /quotes/:quoteId/submit | quotes | path: quoteId; body: request — decisão RFQ | Submete o RFQ em rascunho para cotação. |
POST /quotes/:quoteId/make-offer | quotes | path: quoteId; body: request — decisão RFQ | O comercial cria/submete a oferta; antes da chamada, defina os preços dos itens. |
POST /quotes/:quoteId/accept | quotes | path: quoteId; body: request — decisão RFQ | Aceita a oferta atual. Neste contrato, não cria uma encomenda REST. |
POST /quotes/:quoteId/reject | quotes | path: quoteId; body: request — decisão RFQ | Rejeita a oferta/RFQ. |
POST /quotes/:quoteId/cancel | quotes | path: quoteId; body: request — decisão RFQ | Cancela o RFQ, se o status atual o permitir. |
5.11. Perfis e jobs de integração
| Método e endpoint | ACL | Entrada | Resultado e utilização |
|---|---|---|---|
GET /integrations/profiles?websiteId=&systemType= | system_integrations | query: websiteId, opc. systemType | Perfis de integração para o website. |
POST /integrations/profiles | system_integrations | body: request — perfil de integração | Guarda o perfil ERP/PIM/WMS etc. e devolve-o. |
POST /integrations/mappings | system_integrations | body: request — mapeamento | Guarda o par ID local ↔ ID externo. |
GET /integrations/mappings/local?websiteId=&systemType=&entityType=&localId= | system_integrations | query: todos os parâmetros obrigatórios | Localiza o mapeamento pelo identificador Magento. |
GET /integrations/mappings/external?websiteId=&systemType=&entityType=&externalId= | system_integrations | query: todos os parâmetros obrigatórios | Localiza o mapeamento pelo identificador do sistema externo. |
POST /integrations/jobs | system_integrations | body: request — job | Publica o job para execução; idempotencyKey identifica a operação de negócio. |
GET /integrations/jobs?websiteId=&status= | system_integrations | query: websiteId, opc. status | Array de jobs de integração. |
GET /integrations/jobs/:jobId | system_integrations | path: jobId | Estado e detalhes de um único job. |
POST /integrations/jobs/:jobId/process | system_integrations | path: jobId | Processa o job e devolve o seu estado atual. |
POST /integrations/jobs/:jobId/retry | system_integrations | path: jobId | Repete o job após erro, de acordo com o seu limite de tentativas. |
GET /integrations/jobs/:jobId/logs | system_integrations | path: jobId | Logs de execução do job. |
GET /integrations/jobs/:jobId/errors | system_integrations | path: jobId | Erros 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¤cy=$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
- Leia a configuração do website e guarde o
websiteId,companyIde moeda fornecidos. - Use quick order para validação agregada de SKU, quantidade, visibilidade e disponibilidade.
- Para os itens aceites, obtenha o preço de
pricecom oqtycorreto. - Crie RFQ, adicione itens e envie-os por
submit, se a compra exigir oferta. - Acompanhe o status e o histórico do RFQ; após a aceitação, siga o processo de encomenda Magento acordado, porque
V1não expõe endpoint de criação de order.
Documentos e faturação
- Obtenha a lista de documentos da empresa, opcionalmente filtrando por
documentType. - 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.
- Leia o status do limite antes do processo de compra; apenas a integração com ACL
credit_limitspode geri-lo.
Operações assíncronas
- Guarde o perfil de integração e os mapeamentos de identificadores.
- Publique o job com
idempotencyKeyde negócio e conserve ojobId. - Leia o job e os logs/erros; chame
retryapenas 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ção422, conflito409e timeouts. - Cada request no contexto B2B transmite o
websiteIdcorreto e os dados da empresa usam ocompanyIdcorreto. - 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êmidempotencyKeyestá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:
- instalação técnica — realizada por um programador ou administrador do servidor;
- 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
| Elemento | Requisito |
|---|---|
| Magento | Magento Open Source 2.4.9 |
| PHP | 8.3 |
| Composer | Composer 2 |
| Acesso ao servidor | SSH e possibilidade de executar bin/magento |
| Magento | catálogo, clientes, checkout, Sales, MSI e cron em funcionamento |
possibilidade 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
- Certifique-se de que o Magento funciona corretamente antes da alteração.
- Registe o estado da implementação e faça backup da base de dados e dos diretórios
app/etc,pub/mediaevar. - Em produção, ative o modo maintenance durante a atualização:
bin/magento maintenance:enable2.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-dependenciesDepois de descarregar as dependências, atualize o esquema e a configuração do Magento:
bin/magento setup:upgradebin/magento cache:cleanNo modo de produção, execute adicionalmente:
bin/magento setup:di:compilebin/magento setup:static-content:deploy -f pl_PL en_USbin/magento cache:flushUtilize 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:statusNo 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:disable3. 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.
- Em Stores > Settings > All Stores, crie ou selecione o website B2B, o respetivo store e store view.
- Guarde o
website_id— é usado por empresas, preços, documentos, API e integrações. - Em Content > Design > Configuration, atribua o theme
frontend/Kowal/b2bapenas ao B2B store view. - 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
- Abra Stores > Configuration > Kowal > B2B.
- No seletor de scope, escolha o Website correto.
- Na secção General, defina Enable B2B como
Yes. - Durante a implementação, pode ativar Debug Mode; desative-o após os testes.
- No scope Default Config, defina o período de retenção dos logs.
- 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
- Abra B2B > Companies e crie a empresa.
- Indique o nome, NIF, identificador externo, se a empresa for sincronizada com ERP, status
Activee atribuição ao B2B website. - Adicione um utilizador da empresa ou atribua um cliente Magento existente. Atribua-lhe a função correta e ative a atribuição.
- 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.
- 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ção | Exemplos de tarefas |
|---|---|
| Administrador da empresa | utilizadores, funções, endereços, documentos e histórico da empresa |
| Comprador | catálogo, encomenda rápida, carrinho, RFQ e encomendas |
| Aprovador | decisões no workflow de aprovação |
| Contabilidade | documentos 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
- Certifique-se de que os produtos Magento estão atribuídos ao B2B website, ativos e com dados MSI corretos.
- Configure listas de preços ou preços contratuais para a empresa na área B2B > Pricing (Price Lists, Price List Assignments ou Contract Prices).
- 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.
- Teste na conta da empresa: pesquisa de SKU, visibilidade do produto e preço para a quantidade
1e 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
- Ative os métodos de entrega e pagamento necessários na configuração padrão do Magento para o B2B store view.
- Em B2B > Checkout, adicione regras de métodos disponíveis para empresa/website, se quiser limitar a escolha.
- 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.
- Em B2B > Credit > Payment Terms, adicione prazos de pagamento.
- Em B2B > Credit > Credit Limits, atribua à empresa limite, moeda, status e prazo de pagamento.
- Em B2B > Approvals > Rules, crie uma regra de limiar de valor para a empresa e website.
- Em B2B > Approvals > Approvers, atribua as pessoas aprovadoras.
- 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:
- verifique o template ativo para cada tipo e website;
- faça a pré-visualização;
- ajuste HTML/CSS apenas se tiver uma pessoa que conheça templates Magento e CSS mPDF;
- gere uma fatura ou confirmação de teste e verifique o download a partir da conta da empresa.
6.2. RFQ e oferta PDF
- Em B2B > Quotes > RFQ, crie um RFQ de teste para uma empresa e utilizador ativos.
- Adicione SKU visível para a empresa, quantidade e preço da oferta.
- Defina a data de validade, envie a oferta ao cliente e gere o PDF.
- Verifique a variante do cliente: dados do vendedor/comprador, itens, preço, total e data de validade.
- 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
| Sintoma | O que verificar |
|---|---|
| Não há menu B2B | setup:upgrade, status dos módulos, cache e ACL do administrador. |
| A empresa ou o cliente não vê o B2B | Se 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ço | Atribuiçã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 pagamento | Configuração padrão do Magento, scope B2B store view e regras B2B Checkout. |
| O PDF não é gerado | Template PDF ativo, pacote mPDF, permissões para var/, dados do vendedor e logs Magento. |
| O RFQ não cria encomenda automaticamente | Endereços predefinidos da empresa, pagamento e entrega inequívocos; nos restantes casos, use Backend Order Create. |
A API devolve 403 | O 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
- Consulte a informação de versão fornecida pela Kowal.
- Execute primeiro a atualização no ambiente de teste.
- Faça backup,
composer update kowal/metapackage-b2b-suite --with-all-dependencies,bin/magento setup:upgradee, em produção, também a compilação DI e o deployment dos recursos estáticos. - 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.