Integrar o Microsoft Dynamics 365 com o Magento é ligar o ERP, que manda em clientes, preços, stock e faturação, à loja que vende. Dynamics 365 é uma família de aplicações, e neste guia usamos como caso de referência o Business Central, cuja API está documentada em pormenor. Do lado da loja, Magento é o nome histórico da plataforma que a Adobe comercializa como Adobe Commerce.
A ligação não vem feita. Constrói-se sobre a API do ERP e a API REST da loja, com uma camada que traduz os dados e controla os erros. Mais difícil do que a técnica é a governança: decidir qual sistema manda em cada dado, quem corrige um erro e o que acontece quando duas fontes discordam. Na Avafa tratamos estes projetos dentro da nossa área de integração de Microsoft Dynamics 365 com ecommerce.
Vamos ver como se liga cada lado segundo a documentação oficial, que dados devem circular e que regras de governança evitam os problemas mais comuns.
Como se liga o Dynamics 365 Business Central à loja?
O Business Central expõe uma API REST na versão 2.0, com autenticação através do Microsoft Entra ID na versão online. Segundo a documentação da Microsoft, o endereço inclui o nome do ambiente, o que permite ter produção e testes separados, e os dados a que a integração acede dependem das permissões do utilizador usado.
A API cobre entidades como clientes, artigos e encomendas de venda, e tem dois comportamentos que pesam no desenho. Primeiro, a execução de um pedido está limitada a 8 minutos no serviço online, segundo a página de limites operacionais, após os quais o serviço devolve o erro 408 de tempo esgotado; por isso convém dividir os lotes grandes. Segundo, quando os limites de pedidos são ultrapassados, a API responde com o código 429, e o cliente deve esperar e repetir com intervalos crescentes.
Na instalação em servidores próprios, o endereço e a autenticação são diferentes, por isso convém confirmar qual é a variante em uso antes de planear.
Como avisar a loja de que algo mudou no ERP?
O Business Central oferece webhooks, mas com regras que condicionam o desenho. O sistema externo regista uma subscrição, e o Business Central valida o destino devolvendo um código de validação, que tem de ser devolvido na resposta. A documentação da Microsoft indica o seguinte:
- As subscrições expiram ao fim de três dias se não forem renovadas, e a renovação também exige a validação.
- Os avisos têm um atraso: por defeito, o sistema espera 30 segundos antes de enviar.
- Se mais de 1.000 registos mudarem nessa janela, é enviado um único aviso do tipo coleção, e o destino consulta o que mudou com um filtro de data.
- Se o destino não responde, há novas tentativas durante 36 horas, mas só para certos códigos de erro. Para outras respostas, a subscrição é eliminada.
Na prática, um webhook que expira sem que ninguém o renove deixa a loja sem atualizações, e ninguém recebe erro nenhum. Por isso o desenho deve incluir uma tarefa de renovação e uma verificação periódica de que as subscrições existem. Convém ainda prever uma sincronização de segurança que compare os dados dos dois lados, para apanhar o que os avisos perderam.
Como se escreve na loja Magento sem a bloquear?
A API REST do Magento tem endpoints assíncronos e em lote, pensados para volume. Segundo a documentação da Adobe, o pedido em lote junta várias chamadas do mesmo tipo e cada entidade é colocada numa fila de mensagens. A resposta traz um identificador do lote, e o estado “aceite” significa apenas que o pedido entrou na fila, não que a operação tenha sido bem-sucedida.
Isto exige uma regra no fluxo: o resultado de cada operação deve ser verificado depois, usando o identificador do lote, em vez de se presumir que foi concluída. Há ainda uma exigência de infraestrutura. Na instalação em nuvem ou em servidores próprios, a documentação indica que é preciso instalar e configurar o RabbitMQ, o gestor de mensagens por defeito, antes de usar a API em lote.
A Adobe publica também o Commerce Integration Starter Kit, um projeto aberto para integrações de retaguarda com ERP, sistemas de encomendas e CRM. Segundo o repositório oficial, traz integrações de referência para produto, cliente, grupo de clientes, stock, encomenda e expedição, construídas sobre o Adobe Developer App Builder. É um ponto de partida a avaliar, não uma solução fechada.
Que dados devem ir em cada sentido?
Cada dado deve ter um único sistema mestre:
| Dado | Sistema mestre | Sentido |
|---|---|---|
| — | — | — |
| Preços e condições | Dynamics 365 | ERP para loja |
| Stock disponível | Dynamics 365 | ERP para loja |
| Dados base do produto | ERP ou PIM | Origem para loja |
| Textos e imagens | PIM ou Magento | Origem para loja |
| Encomendas | Magento | Loja para ERP |
| Estado de expedição e fatura | Dynamics 365 | ERP para loja |
Quando o catálogo é grande e as descrições são trabalhadas fora do ERP, o habitual é separar funções: o ERP fica com preço, stock e documentos, e um PIM ou a loja com a parte comercial do produto.
Que regras de governança de dados evitam problemas?
A governança resume-se a quatro decisões escritas antes de programar. Sem elas, cada erro vira uma discussão sobre quem tem razão.
- Um mestre por dado, registado num documento que a equipa técnica e a de negócio conhecem.
- Uma chave de correspondência estável entre sistemas, como o código do artigo ou o número do cliente, e não o nome.
- Uma regra de conflito: se o mesmo campo mudar nos dois lados, ganha o mestre.
- Um responsável por cada fila de erros, com prazo para corrigir e reenviar.
A chave de correspondência é onde mais projetos tropeçam. Se o código do artigo existe em formatos diferentes nos dois sistemas, as atualizações criam duplicados em vez de corrigir registos. Normalizar a chave antes da primeira carga poupa muita limpeza.
Que riscos tem esta integração?
| Risco | Medida preventiva |
|---|---|
| — | — |
| Webhook expira sem aviso | Renovação automática e verificação |
| Operação aceite mas falhada | Verificar o resultado do lote |
| Lote demasiado grande | Dividir em lotes menores |
| Limite de pedidos excedido | Espera crescente após o erro 429 |
| Duplicados por chave diferente | Normalizar a chave antes da carga |
Lista de verificação antes de arrancar o projeto
- Confirmar qual aplicação Dynamics 365 está em uso e se é versão online ou instalada.
- Confirmar a variante do Magento ou Adobe Commerce e se há RabbitMQ disponível.
- Definir o mestre de cada dado e a chave de correspondência.
- Escrever o mapeamento de campos, incluindo impostos, unidades e moedas.
- Planear a renovação das subscrições e a verificação de que continuam ativas.
- Definir a verificação do resultado dos lotes e o tratamento de erros.
- Preparar um ambiente de testes com dados representativos.
- Testar o ciclo completo: encomenda, alteração, cancelamento, expedição e fatura.
- Atribuir um responsável pela monitorização depois da entrada em produção.
Como trabalhamos na Avafa
Começamos por mapear dados e responsáveis, e só depois escolhemos a forma de ligação. Revemos as regras de governança e o desenho dos fluxos antes de qualquer desenvolvimento, para que o projeto não arranque com um conflito entre fontes. Para ver como abordamos este trabalho, comece pela página de integração de Microsoft Dynamics 365 com ecommerce.
Guias relacionados do mesmo cluster
Se a plataforma de destino ainda não está decidida, estes guias comparam o mesmo ERP com outras opções:
- Dynamics 365 com Adobe Commerce para empresas
- Dynamics 365 com WooCommerce
- Dynamics 365 com PrestaShop: stock e pedidos
- SAP S/4HANA e Magento: pedidos, stock e preços
- Odoo e Magento na gestão do negócio
Perguntas frequentes
O Magento tem ligação nativa ao Dynamics 365?
Não de forma que dispense trabalho. A ligação faz-se pelas APIs de cada plataforma, com uma camada intermédia. Convém confirmar na documentação de cada fornecedor o que existe à data do projeto.
Os webhooks do Business Central chegam para sincronizar a loja?
Servem de aviso, mas não garantem sozinhos a consistência. Expiram se não forem renovados e podem agrupar muitas alterações num único aviso. Convém ter uma sincronização de segurança.
Aceite na fila significa que o produto foi criado?
Não. Na API em lote do Magento, o estado aceite só indica que o pedido entrou na fila. O resultado tem de ser verificado depois com o identificador do lote.
Preciso do RabbitMQ?
Segundo a documentação da Adobe, sim, na instalação em nuvem ou em servidores próprios, para usar a API em lote. Na versão como serviço não é preciso configurar a fila.
Quanto tempo demora um projeto destes?
Depende do número de fluxos e da qualidade dos dados no ERP. Em vez de uma estimativa genérica, convém fazer primeiro o levantamento e o mapeamento de dados.