Integrar o SAP Business One com o Magento é ligar o ERP, que emite os documentos fiscais, à loja que cobra e envia, e o difícil não é mover encomendas, é fazer coincidir três mapeamentos: produtos, impostos e pagamentos. Se qualquer um estiver errado, a encomenda chega ao SAP com o valor, o IVA ou o estado de pagamento incorretos.
Para a empresa, isso significa faturas que não batem com o que o cliente pagou, conciliações bancárias manuais e equipas a corrigir documentos. Tratamos esta ligação na nossa área de integração de SAP com ecommerce, e este guia foca-se nos três mapeamentos que mais falham.
Vê aqui como funciona a ligação, como mapear impostos, como alinhar estados de encomenda e pagamentos, que dados vão em cada sentido e uma lista de verificação antes de arrancar.
Como se liga o SAP Business One ao Magento?
A ligação usa o Service Layer do SAP Business One e a API REST do Magento, quase sempre com uma camada intermédia entre os dois. Segundo a formação oficial da SAP, o Service Layer segue o mesmo modelo em todos os objetos de negócio: POST cria, GET lê, PATCH atualiza e DELETE apaga.
Segundo a documentação da Adobe, a API REST do Adobe Commerce e do Magento Open Source usa OAuth 1.0a para aplicações de terceiros, o caso típico de uma integração. A mesma documentação descreve endpoints em massa, que agrupam várias chamadas do mesmo tipo num único pedido e as colocam numa fila de mensagens. Isto é útil para atualizar muitos preços ou stocks, mas exige que a fila esteja corretamente configurada.
A camada intermédia é onde se guarda o estado de cada mensagem, se repete o que falhou e se avisa quando algo precisa de atenção. É também onde ficam as regras de conversão que descrevemos a seguir.
Como mapear produtos e atributos?
O mapeamento de produtos começa pela referência: cada artigo do SAP tem de corresponder a um SKU do Magento, sem exceções. Quando o Magento tem produtos configuráveis, com variantes de cor ou tamanho, cada variante precisa de um artigo próprio no ERP, ou então de uma regra clara de composição.
Escreva uma tabela de correspondência de campos antes de começar. O que é um campo livre no Magento pode ser um campo definido pelo utilizador no SAP, e o que é um atributo da loja pode nem existir no ERP. Os textos comerciais, as imagens e as categorias normalmente ficam no Magento; a referência, o preço de base e o stock ficam no SAP.
Um bom teste é escolher dez artigos reais, incluindo um configurável, um com promoção e um com unidade especial, e percorrer o fluxo completo antes de ligar o catálogo inteiro.
Como mapear impostos entre o SAP e o Magento?
O IVA tem de ter uma única origem de cálculo, e essa origem é, na prática, o documento que o SAP emite. Se a loja calcular um valor e o SAP outro, a diferença aparece na fatura. Por isso é preciso compreender como o Magento calcula impostos antes de o comparar com o SAP.
Segundo a documentação da Adobe, uma regra de imposto combina três elementos: uma taxa, uma classe fiscal do cliente e uma classe fiscal do produto. O Commerce aplica a regra cruzando a classe do cliente, a classe do produto e a região, que pode basear-se na morada de envio, na de faturação ou na origem do envio. Se houver vários impostos, a prioridade determina se se somam ou se se compõem.
A configuração de vendas e impostos tem ainda duas opções que mudam o resultado: se os preços do catálogo incluem ou excluem imposto, e se o cálculo se baseia no preço unitário, no total da linha ou no total da encomenda. Estas opções têm de coincidir com a forma como o SAP guarda e arredonda os valores.
| Ponto a decidir | Magento | SAP Business One | Ação |
|---|---|---|---|
| Preço no catálogo | Com ou sem IVA | Definido pela lista de preços | Alinhar e testar |
| Base de cálculo | Unidade, linha ou total | Confirmar no ERP | Escolher o mesmo |
| Classe fiscal | Cliente e produto | Código de imposto | Tabela de equivalências |
| Morada de referência | Envio ou faturação | Cliente e morada | Definir a regra |
Confirme com o seu contabilista as regras de faturação aplicáveis, incluindo clientes empresariais e vendas para fora de Portugal, antes de fixar as equivalências.
Como alinhar estados de encomenda e pagamentos?
O estado de pagamento da loja decide quando a encomenda deve ir para o SAP e com que informação. Segundo a documentação da Adobe, o Magento distingue os estados da encomenda (states), usados internamente pelo sistema, dos estados visíveis (statuses), que comunicam o progresso ao cliente e à administração sem alterar o fluxo.
Entre os estados visíveis predefinidos, a Adobe documenta o pagamento pendente (pending_payment), quando o cliente foi enviado ao gateway e ainda não há retorno, o em processamento (processing), o completo (complete), o fechado (closed), quando existe nota de crédito e reembolso, o cancelado (canceled) e o em espera (holded). Segundo a mesma documentação, só os estados predefinidos entram no fluxo da encomenda; os restantes servem para comentários.
Na prática, recomendamos uma regra simples: a encomenda só segue para o SAP quando o pagamento está confirmado, ou quando o método de pagamento é, por natureza, diferido, como a transferência com prazo. Cada estado do Magento deve ter uma ação no SAP escrita:
- Pagamento pendente: não enviar, ou enviar como reserva, conforme a regra de stock.
- Em processamento: criar o documento de venda no SAP.
- Completo: confirmar expedição e, se aplicável, fatura.
- Fechado: criar a nota de crédito correspondente.
- Cancelado: libertar o stock reservado.
Que dados vão em cada sentido?
Cada dado tem um sistema mestre, e o outro apenas o recebe. Resumimos a distribuição que usamos nestes projetos:
| Dado | Sistema mestre | Sentido | Nota |
|---|---|---|---|
| Artigos e SKU | SAP | SAP para loja | Um SKU por artigo |
| Stock e preços | SAP | SAP para loja | Atualização em lote |
| Encomendas pagas | Magento | Loja para SAP | Um documento por encomenda |
| Pagamentos | Magento | Loja para SAP | Referência do gateway |
| Faturas e notas | SAP | SAP para loja | A loja apenas mostra |
| Clientes | Definir | Ambos | Chave por NIF |
Para os pagamentos, guarde sempre a referência do gateway no documento do SAP. Sem ela, a conciliação entre o extrato bancário, o gateway e o ERP faz-se à mão.
Erros que vemos com mais frequência
- IVA calculado em dois sítios. A loja e o SAP chegam a valores diferentes por arredondamento.
- Estados sem ação. Um estado novo do Magento não tem equivalente no SAP e a encomenda fica parada.
- Encomendas enviadas antes do pagamento. O ERP regista vendas que depois são canceladas.
- Duplicados por reenvio. Sem controlo, o mesmo pedido cria dois documentos.
- Sem registo de erros. Só se percebe quando o cliente reclama.
Lista de verificação antes de arrancar
Se faltar uma resposta nesta lista, resolva-a primeiro:
- Cada dado tem um sistema mestre escrito e aprovado.
- Cada SKU do Magento corresponde a um artigo do SAP.
- A configuração de impostos da loja foi comparada com a do SAP.
- Cada estado de encomenda tem uma ação definida no SAP.
- A referência do gateway de pagamento fica no documento do SAP.
- Existe ambiente de ensaio do SAP e do Magento.
- Há registo de erros e uma pessoa que o recebe e resolve.
- Está escrito o que acontece quando o SAP ou a loja ficam indisponíveis.
Como trabalhamos na Avafa
Começamos por mapear produtos, impostos e pagamentos, e só depois escolhemos a forma de ligação. Revemos as equivalências fiscais e os estados de encomenda antes de qualquer desenvolvimento, porque é aí que os erros custam mais. Se quiser ver como abordamos estes projetos, comece pela página de integração SAP com ecommerce.
Guias relacionados do mesmo cluster
Estes guias comparam a mesma ligação com outras plataformas e outros ERP:
- SAP S/4HANA e Magento: pedidos, stock e preços
- SAP Business One com Adobe Commerce Cloud
- SAP Business One com PrestaShop
- SAP Business One com WooCommerce
- Odoo e Magento: gestão do negócio
Perguntas frequentes
O Magento tem ligação nativa ao SAP Business One?
A documentação da Adobe descreve a API REST como forma de integrar com sistemas ERP, e a da SAP descreve o Service Layer. Não descrevem um conector pronto entre ambos; a ligação faz-se por desenvolvimento ou com uma plataforma de integração.
Quem deve calcular o IVA, o Magento ou o SAP?
A loja calcula o IVA para mostrar ao cliente, e o SAP emite o documento fiscal. Os dois têm de chegar ao mesmo valor, por isso as classes fiscais, a base de cálculo e o arredondamento devem ser comparados antes de arrancar.
Quando deve uma encomenda seguir para o SAP?
Recomendamos que siga quando o pagamento está confirmado, ou quando o método é diferido por natureza. Enviar antes do pagamento obriga a anular documentos quando o cliente desiste.
Posso atualizar muitos preços de uma vez?
Sim. A documentação da Adobe descreve endpoints em massa que agrupam várias chamadas numa única, processadas através de uma fila de mensagens. A fila tem de estar configurada e a resposta indica apenas que o pedido foi aceite, não que foi processado.
O que fazer com os reembolsos?
Um reembolso no Magento deve gerar uma nota de crédito no SAP, ligada ao documento original. Defina a regra antes de arrancar, porque os reembolsos parciais costumam ser o caso mais complexo.