Integração do Magento 2 com ERP e NF-e: guia técnico completo

As três APIs do Magento 2: REST, GraphQL e SOAP

O Adobe Commerce / Magento 2 expõe três tipos de web API: GraphQL, REST (Representational State Transfer) e SOAP (Simple Object Access Protocol). O framework REST/SOAP é o mesmo por baixo: ambos seguem o modelo CRUD (create, read, update, delete) mais search, e os endpoints são declarados no webapi.xml de cada módulo. Na prática, escolher a API certa para cada caminho de integração evita boa parte das dores futuras.

Quando usar cada uma

• GraphQL: é a recomendação oficial para o storefront/frontend — headless, PWA e apps mobile ("next-generation commerce experiences, including headless storefronts and sophisticated mobile applications"). Usa um endpoint único /graphql com queries e mutations, e o cliente pede exatamente os campos que precisa, eliminando over/under-fetching. Esse controle fino sobre o payload tem impacto direto nos tempos de resposta do front e, por tabela, na Performance e Core Web Vitals da loja.
• REST: a escolha natural para integrações back-end — ERP, painel administrativo e operações em lote. É onde vivem as integrações com SAP, TOTVS, Bling, Tiny e Omie.
• SOAP: compartilha o mesmo framework do REST; útil quando um sistema legado exige WSDL. Para projetos novos eu prefiro REST pela simplicidade.

Os endpoints GraphQL diferem entre as modalidades de hospedagem: em PaaS (on-prem/Cloud), https://<server>/graphql; em SaaS (Adobe Commerce as a Cloud Service), https://<region>-<env>.api.commerce.adobe.com/<tenantId>/graphql.

Segundo a documentação para desenvolvedores da Adobe Commerce, o framework de web API é baseado no modelo CRUD (create, read, update, delete) e search — a página afirma textualmente em inglês: "The framework is based on the CRUD (create, read, update, delete) & search model." A indicação de usar GraphQL para o storefront de próxima geração é um resumo meu da orientação geral da Adobe, e não uma frase única dessa página.

Fonte: Adobe Commerce Developer

Regra de bolso que uso em todo projeto: GraphQL para o que o cliente vê, REST para o que o ERP escreve. Não tente alimentar o ERP via GraphQL nem montar a vitrine puxando REST campo a campo — cada API foi otimizada para o seu lado.

Autenticação: tokens de integração, OAuth 1.0a e ACL

Antes de qualquer chamada, o ERP precisa se autenticar. O Magento 2 oferece três tipos de token, todos enviados no header Authorization: Bearer <token>, com comportamentos de expiração bem diferentes — e errar isso é a causa nº 1 de integrações que "param de funcionar do nada".

Para integração com ERP eu sempre uso o Integration token: ele não expira, evitando a complexidade de renovação automática. A criação de uma Integration gera quatro credenciais — consumer key, consumer secret, access token e access token secret. A expiração de admin e customer tokens é configurável em Stores > Settings > Configuration > Services > OAuth > Access Token Expiration (campos Admin Token Lifetime e Customer Token Lifetime, em horas). Um cron job que roda de hora em hora remove tokens admin e customer expirados.

Conforme a documentação para desenvolvedores da Adobe Commerce, o integration token tem validade indefinida — "It lasts until it is manually revoked" — enquanto, por padrão, "an admin token is valid for 4 hours, while a customer token is valid for 1 hour". Os trechos entre aspas são literais da página; o restante é resumo meu.

Fonte: Adobe Commerce Developer

OAuth 1.0a para integrações de terceiros

Em PaaS/on-prem, integrações de terceiros podem autenticar via OAuth 1.0a. O fluxo: o lojista cria a Integration (o Commerce gera consumer key/secret), ativa a integração — quando o Commerce faz um HTTPS POST de consumer key/secret, verifier e store URL para o Callback Link — e então um request token de vida curta é trocado por um access token de vida longa (não expira até revogação). A chave de assinatura concatena consumer secret + token secret separados por &. Em SaaS (Adobe Commerce as a Cloud Service), os métodos tradicionais de admin/integration token não são suportados — usa-se Adobe IMS com OAuth 2.0 server-to-server.

Escopos e ACL

Crie a integração em System > Extensions > Integrations > Add New Integration. Em Basic Settings > API, defina o Resource Access (All ou recursos específicos). Esses recursos vêm do acl.xml de cada módulo, consolidados numa árvore de ACL e referenciados pelo webapi.xml. Recomendo nunca conceder "All" ao ERP: libere só os recursos de catálogo, estoque e pedidos que ele realmente usa. O princípio do menor privilégio também vale para integração — e é um dos pilares do guia de Segurança e Hardening do Magento 2, que recomendo seguir em paralelo (token rotativo, IP allowlist e WAF na frente da API).

Async APIs e Bulk APIs: alto volume com filas de mensagens

Chamadas REST síncronas funcionam para baixo volume, mas quebram quando o ERP precisa empurrar milhares de SKUs ou pedidos de uma vez — timeouts, locks de banco e travamento da loja. A resposta do Magento são as Async APIs e Bulk APIs, que gravam o trabalho em fila e respondem na hora.

Async APIs

Basta adicionar o prefixo /async ao endpoint síncrono. Em PaaS: PUT https://<host>/rest/<store-view-code>/async/V1/products/:sku. Em SaaS: PUT https://<server>.api.commerce.adobe.com/<tenant-id>/V1/async/products/:sku. Suporta POST, PUT, DELETE e PATCH (GET não é suportado). A resposta retorna imediatamente um bulk_uuid, um array request_items e o campo errors — a operação é processada depois, fora do ciclo da requisição.

Bulk APIs

As Bulk APIs combinam múltiplas chamadas do mesmo tipo num único array. O handler divide o array em entidades individuais e grava cada uma como mensagem separada na fila. Em PaaS: POST https://<host>/rest/<store-view-code>/async/bulk/V1/products. Em SaaS: POST https://<server>.api.commerce.adobe.com/<tenant-id>/V1/async/bulk/products. Parâmetros de rota como :sku viram bySku (substitui : por by e capitaliza).

Para processar a fila, mantenha o consumer ativo: php bin/magento queue:consumers:start async.operations.all. Em produção, dimensione o paralelismo com --max-messages e suba mais de um processo do consumer quando o backlog crescer — um único consumer raramente dá conta de uma carga de catálogo de Black Friday.

Acompanhamento de status

O acompanhamento de cada lote é o que dá visibilidade operacional:

• Sumário: GET /V1/bulk/:bulkUuid/status
• Contagem por status: GET /V1/bulk/:bulkUuid/operation-status/:status
• Detalhado: GET /V1/bulk/:bulkUuid/detailed-status (inclui topic_name e serialized_data)

De acordo com a documentação para desenvolvedores da Adobe Commerce, os códigos de status de operação bulk distinguem uma falha retentável (código 2, retriably failed) de uma falha que não deve ser repetida sem correção (código 3, not retriable). Esta é uma paráfrase da tabela oficial de status, não uma citação literal.

Fonte: Adobe Commerce Developer

Na minha experiência, toda carga de catálogo do ERP para o Magento deve usar Bulk + monitoramento de bulk_uuid. É a diferença entre uma importação que derruba a loja e uma que escoa em segundo plano.

Message Queue Framework: RabbitMQ vs MySQL queue

Por trás das Async/Bulk APIs está o Message Queue Framework (MQF). Publishers publicam via PublisherInterface::publish($topic, $message) e consumers processam por tópico — por exemplo inventory.update ou product_action_attribute.update. A configuração mora em quatro arquivos: communication.xml, queue_topology.xml, queue_publisher.xml e queue_consumer.xml.

Escolha do broker

O Magento suporta três backends de fila, e a escolha tem impacto direto em confiabilidade:

• RabbitMQ (AMQP 0.9.1): o broker primário, com armazenamento de mensagens não entregues (dead-letter). É o que recomendo para produção.
• ActiveMQ Artemis (STOMP): alternativa suportada.
• Adapter MySQL: usa as tabelas queue, queue_message e queue_message_status. É básico e não recomendado para produção.

Use an external message broker like RabbitMQ or ActiveMQ Artemis for production environments whenever possible.

Fonte: Adobe Commerce Developer

Configurando o RabbitMQ

Via CLI, a configuração é direta (porta AMQP padrão 5672):

php bin/magento setup:config:set \
  --amqp-host="rabbitmq.local" \
  --amqp-port="5672" \
  --amqp-user="magento" \
  --amqp-password="***" \
  --amqp-virtualhost="/"

Versões: atenção à divergência entre páginas oficiais

Há uma divergência real entre páginas oficiais da Adobe: a página de message-broker ainda cita RabbitMQ 3.8.x para o Magento 2.3/2.4, valor desatualizado, enquanto a página de System Requirements lista RabbitMQ 4.1 para o Adobe Commerce 2.4.8. Sempre confirme contra a versão exata que você opera. Para a 2.4.8, os requisitos atuais são PHP 8.4/8.3, MariaDB 11.4 ou MySQL 8.4, OpenSearch 2.19 e RabbitMQ 4.1. No quesito cache/sessão, a documentação lista Redis 7.2; e, especificamente para o Adobe Commerce on Cloud, já há suporte a Valkey 8 — o fork open source do Redis adotado pela comunidade desde a mudança de licenciamento do Redis em 2024, e que tende a substituir o Redis nas pilhas mais recentes. Se você gerencia infraestrutura, vale planejar a transição de Redis para Valkey junto com o upgrade.

Em produção eu trato o consumer como serviço gerenciado (supervisord ou cron com lock) para garantir que async.operations.all e os consumers de estoque estejam sempre vivos. Fila parada = pedido sem baixa de estoque.

Webhooks e extensibilidade out-of-process (App Builder / Adobe I/O)

Até aqui falamos de o ERP chamar o Magento. Mas muitas integrações precisam do contrário: o Magento avisar sistemas externos quando algo acontece. Para isso o Adobe Commerce oferece dois mecanismos out-of-process, com semânticas opostas.

Webhooks (síncronos)

Os Webhooks do Adobe Commerce permitem configurar lógica síncrona: quando um evento dispara, o Commerce faz "a real-time call from Commerce to a URL endpoint" e aguarda a resposta do sistema externo — completando a ação ou lançando uma exceção. São ideais quando você precisa de validação em tempo real antes de o pedido seguir (checagem de crédito no ERP, validação fiscal, regra de preço). Instalação via Composer:

composer require magento/commerce-webhooks=^1.0 --no-update

Conforme a documentação de extensibilidade da Adobe Commerce, um webhook dispara uma chamada em tempo real do Commerce para um endpoint de URL — no texto original, "a real-time call from Commerce to a URL endpoint". O sistema externo então responde, e a própria documentação descreve que, se a resposta indicar indisponibilidade, "the flow is interrupted and an exception is thrown". Os trechos entre aspas são literais; o restante é resumo meu.

Fonte: Adobe Commerce Developer

Adobe I/O Events (assíncronos)

Quando comunicação assíncrona basta, use Adobe I/O Events: o Commerce envia eventos ao Adobe I/O, que os roteia para apps do Adobe App Builder, eliminando API polling. Os eventos são registrados via io_events.xml — por exemplo plugin.magento.sales.api.order_management.place para captura de novos pedidos. O journaling persiste eventos por até 7 dias, permitindo consumo assíncrono mesmo se o consumidor ficar offline.

App Builder

O Adobe Developer App Builder é uma plataforma serverless de extensibilidade out-of-process: você estende o Commerce sem modificar o core, o que reduz o TCO ao simplificar upgrades. O tutorial oficial demonstra uma action que valida o nome de um produto e rejeita termos como "test" ou "example" antes de salvar. Para integrações com ERP, esse padrão é poderoso: a lógica de de-para e validação vive fora do Magento, e a loja continua atualizável.

Sincronização de estoque, preço, catálogo e pedidos com MSI

A sincronização que mais gera problema é a de estoque — porque vender o que não existe destrói a confiança do cliente. O Magento 2.3 introduziu o Inventory Management (antes chamado MSI — Multi Source Inventory), desenvolvido pelo programa Community Engineering e disponível em Open Source, Commerce e Commerce Cloud. Entender seus quatro conceitos é pré-requisito para integrar estoque corretamente.

• Sources: locais físicos — armazéns, lojas, centros de distribuição, drop shippers.
• Stocks: mapeiam o canal de venda/website para uma ou mais sources.
• Salable Quantity: a quantidade vendável virtual, agregada das sources — na documentação, "the total virtual inventory that can be sold through a sales channel". Deve ser obtida por service call dedicado, nunca lida como valor estático gravado no produto.
• Reservations: deduções append-only da salable quantity, criadas no checkout e liberadas no shipment.

When an event such as an order placement, cancellation, refund, or shipment occurs, the Append Reservation Service creates a reservation for each SKU, indicating how many items to add to the salable quantity total. Reservations are append-only entities.

Fonte: Adobe Commerce Developer

O erro mais comum na integração de estoque

Vejo ERPs sobrescrevendo a quantidade do produto diretamente e "comendo" as reservations em andamento, o que provoca overselling. A regra de ouro: ao desenvolver, use a interface de alto nível PlaceReservationsForSalesEventInterface e nunca AppendReservationsInterface diretamente na lógica de negócio. O ERP deve atualizar a quantidade da source via API de inventory (/V1/inventory/source-items); o Magento calcula a salable quantity considerando as reservations abertas. Em catálogos grandes, prefira a versão bulk dessa atualização para não gerar uma chamada por SKU.

O que sincronizar e em que direção

Defina sempre um dono único por entidade. Estoque e preço pertencem ao ERP; pedidos nascem no Magento. Sincronização sem dono definido vira guerra de sobrescrita.

ERPs brasileiros: SAP, TOTVS, Bling, Tiny e Omie

O fluxo típico de integração no Brasil é sempre o mesmo, independente do ERP: o ERP gerencia produtos, estoque, preços e financeiro; o e-commerce envia o pedido; o ERP dá baixa de estoque, emite a NF-e via SEFAZ e devolve número, chave e status da nota para o Magento atualizar o status do pedido. O que muda é a maturidade e o estilo de API de cada plataforma.

ERPs cloud (APIs REST/JSON)

• Bling (API v3): REST com OAuth 2.0 (Authorization: Bearer [access_token]), métodos GET/POST/PUT/PATCH/DELETE e scopes definidos pelo usuário. Expõe GET /produtos e gestão de pedidos de venda (inserção, edição e situações). Há migração v2→v3 documentada.
• Omie: consumida em JSON (e SOAP legado). Cada requisição manda Content-Type: application/json com app_key, app_secret, call e um objeto param. As credenciais saem do resumo da aplicação (somente admin), em "Chave de Integração API". O portal developer.omie.com.br permite testar, e há exemplos em github.com/omiexperience/api-examples. A Omie está desenvolvendo suporte REST com Swagger.
• Tiny: ERP cloud brasileiro com API REST/JSON, padrão semelhante para produtos, pedidos e NF-e.

Segundo a documentação oficial do Bling, a API v3 é "estruturada no padrão REST", usa os métodos GET/POST/PUT/PATCH/DELETE e autentica "por meio de autenticação OAuth 2.0", com o header Authorization: Bearer [access_token]. Os trechos entre aspas reproduzem o texto da página; o restante é resumo meu.

Fonte: Bling (ERP)

ERPs enterprise

Para SAP e TOTVS Protheus, a integração se dá por API própria ou via iPaaS. A TOTVS oferece o TOTVS iPaaS com pacotes aceleradores, e webhooks são o gatilho comum para o Protheus receber pedidos vindos do e-commerce. Nesses ambientes, raramente o Magento fala direto com o ERP — há uma camada de middleware fazendo orquestração e transformação.

Minha recomendação prática: lojas pequenas e médias com Bling/Tiny/Omie podem partir para integração direta ou um conector de mercado; operações com SAP/TOTVS quase sempre justificam um middleware dedicado.

NF-e: emissão, SEFAZ e atualização do pedido

A NF-e modelo 55 é um documento fiscal emitido e armazenado eletronicamente, transmitido à SEFAZ autorizadora e replicado ao Ambiente Nacional (Receita Federal). A comunicação acontece via Web Services SOAP da SEFAZ, em dois ambientes: homologação (testes) e produção. A especificação técnica oficial está no Manual de Orientação do Contribuinte (MOC), atualmente na versão 7.0, que define os schemas XML, os web services e os critérios de integração; alterações pontuais entre revisões maiores são publicadas como Notas Técnicas (NT) no Portal Nacional, e é nelas que costumam aparecer mudanças de leiaute que quebram integração se ignoradas.

De acordo com o Portal Nacional da NF-e, a nota fiscal eletrônica é transmitida à SEFAZ por web services, com ambientes distintos de homologação (testes) e produção, e a especificação técnica é definida pelo Manual de Orientação do Contribuinte (MOC) e suas Notas Técnicas. Esta é uma síntese minha do conteúdo do portal, não uma citação literal.

Fonte: Portal Nacional da NF-e

Por que não emitir NF-e direto do Magento

Esta é uma decisão de arquitetura que defendo em todo projeto: não emita NF-e diretamente do Magento. Delegue ao ERP ou a um middleware/gateway fiscal certificado (os emissores integrados a Bling/Tiny/Omie ou gateways fiscais especializados). Eles é que:

• Assinam digitalmente: com certificado A1 (arquivo) ou A3 (token/cartão).
• Transmitem à SEFAZ: tratando contingência e o protocolo de autorização.
• Retornam: a chave de acesso de 44 dígitos, o número da nota, o DANFE e o XML autorizado.

Manter a emissão fiscal fora do core do Magento também reduz a sua superfície de conformidade: certificados, chaves e dados sensíveis ficam concentrados no gateway, o que conversa diretamente com as práticas do guia de Segurança e Hardening do Magento 2.

Fechando o ciclo no Magento

De posse do retorno da SEFAZ, o ERP/middleware chama de volta o Magento via REST para atualizar o status do pedido e anexar os dados fiscais (chave, número, link do DANFE/XML). É esse retorno que transforma "pedido pago" em "pedido faturado e enviável". O fluxo completo fica assim:

1. Magento captura o pedido e o envia ao ERP (evento/webhook).
2. ERP dá baixa de estoque na source e gera a NF-e.
3. Middleware fiscal assina e transmite à SEFAZ (homologação ou produção).
4. SEFAZ autoriza e devolve a chave de 44 dígitos + protocolo.
5. ERP retorna chave, número, DANFE e XML ao Magento via REST.
6. Magento atualiza o status do pedido e disponibiliza a nota ao cliente.

Um cuidado operacional: em homologação a SEFAZ exige a frase legal de teste no XML — nunca rode validação fiscal de QA contra o ambiente de produção, sob risco de gerar notas reais indevidas.

Confiabilidade: idempotência, retry, erros e logging

Integração de e-commerce com ERP é, na essência, um problema de sistemas distribuídos: redes falham, serviços reiniciam, mensagens chegam duas vezes. O que separa uma integração de produção de um protótipo é como ela lida com isso. Quatro pilares sustentam confiabilidade.

1. Desacoplamento por filas

Use Bulk/Async APIs com RabbitMQ para desacoplar produtor e consumidor e absorver picos (Black Friday, carga de catálogo). O RabbitMQ guarda mensagens não entregues (dead-letter), então nada se perde se o consumidor cair momentaneamente.

2. Idempotência

Esta é a salvaguarda que o integrador precisa garantir — o Magento não faz isso sozinho. Use uma chave de idempotência estável: SKU para produtos, increment_id para pedidos, ou uma chave externa do ERP. Assim, se a mesma mensagem for reprocessada, ela não cria pedido nem baixa estoque em duplicidade. Sem isso, todo retry vira risco de duplicação.

3. Retry seguro

Os códigos de status bulk são a base do reprocessamento inteligente: o código 2 (Retriably failed) indica falha temporária — reprocesse com backoff exponencial (por exemplo 1s, 2s, 4s, 8s, com teto e jitter); o código 3 (Not retriable) indica que o dado precisa ser corrigido antes — reprocessar sem corrigir só repete o erro. Trate-os de forma diferente; não faça retry cego.

4. Logging e auditoria

Registre o bulk_uuid de cada lote e consulte GET /V1/bulk/:bulkUuid/detailed-status (com topic_name e serialized_data) para auditar operação a operação. Quando um cliente reclama "meu pedido não foi pro ERP", o bulk_uuid permite rastrear exatamente onde a mensagem parou. Logging não é luxo — é a ferramenta de diagnóstico que economiza horas de investigação.

Arquitetura: integração direta vs middleware/iPaaS e de-para

A última decisão — e talvez a mais estratégica — é onde mora a lógica de integração. Há dois caminhos, e a escolha errada cobra caro na manutenção.

Integração direta (ponto-a-ponto)

O Magento fala diretamente com o ERP via REST/GraphQL. É mais simples e barato de começar, ideal para um único ERP cloud (Bling, Tiny, Omie) e baixa complexidade de regras. O custo: acopla os sistemas — qualquer mudança no ERP ou no Magento pode quebrar o outro lado, e adicionar um terceiro sistema multiplica conexões.

Middleware / iPaaS

Uma camada intermediária (TOTVS iPaaS, n8n e similares) centraliza orquestração, mapeamento de dados (de-para) e resiliência. O n8n suporta qualquer sistema com API REST, webhooks ou SQL e traz mais de 400 integrações nativas; no Brasil é usado para orquestrar Bling/Tiny/Omie com o e-commerce e disparar a emissão de NF-e. A Adobe descreve essas opções na Enterprise reference architecture.

O mapeamento de-para

Independente do caminho, o de-para é onde os projetos mais erram. Documente em tabela cada campo: SKU do Magento ↔ código do ERP, status do pedido ↔ situação do ERP, atributo de produto ↔ campo fiscal. Sem esse mapeamento explícito, a integração vira caixa-preta. Vale tratar o de-para com o mesmo rigor que se trata a definição de URLs e atributos no guia de SEO Técnico para Magento 2: dado bem modelado na origem evita retrabalho em toda a cadeia.

Nota sobre legado

Se você ainda opera Magento 1, atenção: a plataforma atingiu End of Life em 30/06/2020 (todas as versões, Enterprise e Community/Open Source), sem novos patches de segurança ou suporte oficial. O anúncio do fim de suporte foi feito pela Adobe com bastante antecedência (amplamente reportado como setembro de 2018). Qualquer projeto de integração novo deve nascer no Magento 2 / Adobe Commerce — investir em integração sobre o M1 é construir sobre fundação sem manutenção. O caminho recomendado está detalhado no guia de Migração de Magento 1 para Magento 2.