Integração Shopify + Odoo ERP: o guia completo

À medida que as lojas do Shopify aumentam, a lacuna entre o que o Shopify lida nativamente e o que a empresa realmente precisa para obter excelência operacional torna-se uma restrição significativa. Gerenciamento de estoque em vários armazéns, contabilidade em várias moedas, pedidos de fabricação acionados por vendas do Shopify, CRM sofisticado com histórico completo do cliente e reposição automatizada de fornecedores – tudo isso exige um ERP, e o Odoo é cada vez mais o sistema preferido para empresas de comércio eletrônico de médio porte.

Shopify + Odoo não é uma integração plug-and-play. Requer decisões arquitetônicas cuidadosas sobre qual sistema possui quais dados, o que sincroniza em qual direção e como lidar com casos extremos, como remessas parciais, processamento de devoluções e mapeamento de variantes. Este guia cobre tudo, desde arquitetura de integração até padrões de implementação específicos.

Principais conclusões

• Odoo é a fonte da verdade para estoque, clientes e contabilidade; Shopify é a fonte da verdade para transações de comércio eletrônico
• A sincronização bidirecional de estoque (Shopify → Odoo para pedidos, Odoo → Shopify para níveis de estoque) é o principal requisito de integração
• O gerenciamento do catálogo de produtos deve estar no Odoo e sincronizar com o Shopify - e não o contrário
• Os registros do cliente são mesclados entre sistemas usando e-mail como identificador exclusivo
• Ciclo de vida do pedido: Shopify cria pedido → Odoo recebe pedido → Odoo cria entrega → atualizações de atendimento Shopify
• O processamento de devolução requer coordenação: Shopify inicia devolução → Odoo processa recebimento → atualização de ambos os sistemas
• A API Webhook do Shopify fornece eventos de pedidos em tempo real; Odoo os recebe por meio de middleware de conector
• Existem conectores diretos Odoo-Shopify (Syncee, OdooConnector), mas integrações personalizadas via REST API oferecem mais controle

---

Compreendendo a arquitetura de integração

Antes de implementar, defina o sistema autoritativo para cada domínio de dados:

Por que Odoo possui estoque:

O rastreamento de estoque do Shopify é funcional, mas limitado para operações multiarmazém e multicanal. O módulo de estoque do Odoo lida com: rastreamento de lote e número de série, gerenciamento de armazém em vários locais, regras de reabastecimento automatizadas, integração de fabricação (produtos acabados diminuem o estoque de componentes) e operações de atendimento baseadas em código de barras. O Shopify deve refletir a realidade do estoque do Odoo, e não o contrário.

Por que o Shopify é a camada de comércio:

A finalização da compra, o processamento de pagamentos, o cálculo da taxa de envio, a cobrança de impostos e a experiência de atendimento ao cliente do Shopify são os melhores da categoria. O comércio eletrônico B2C da Odoo (site Odoo) é funcional, mas não no nível do Shopify para comércio DTC. A arquitetura ideal mantém o Shopify como interface comercial e o Odoo como espinha dorsal operacional.

---

Métodos de integração: aplicativos conectores versus API personalizada

Opção 1: aplicativos de conector pré-criados

Vários aplicativos de mercado Shopify e Odoo fornecem integração pré-construída:

Conectores pré-construídos funcionam bem para: catálogo de produtos padrão e sincronização de pedidos para modelos de negócios simples, sem estruturas de variantes complexas, vários armazéns ou dependências de fabricação.

Opção 2: integração personalizada via APIs

Para requisitos de negócios complexos, uma integração personalizada usando a API REST/GraphQL da Shopify e a API JSON-RPC/REST da Odoo oferece maior controle e confiabilidade.

Arquitetura de integração personalizada:

Shopify (Commerce Layer)
│
│ Webhooks (orders/create, orders/updated, refunds/create, inventory_levels/update)
│
▼
Integration Service (Node.js / Python middleware)
│
│ Event processing, transformation, error handling, retry logic
│
▼
Odoo (ERP Layer)
│
│ Odoo JSON-RPC API (sales orders, inventory, customers, accounting)
│
└── Inventory updates → Shopify Admin API

Pilha de tecnologia para integração personalizada:

• Middleware: Node.js (para alinhamento do ecossistema Shopify) ou Python (para alinhamento do ecossistema Odoo)
• Fila: Redis ou RabbitMQ para processamento confiável de eventos
• Banco de dados: PostgreSQL para estado de integração, chaves de idempotência, logs de erros
• Hospedagem: AWS Lambda ou similar para manipuladores de webhook (escala automaticamente com picos de tráfego do Shopify)

---

Sincronização de pedidos: Shopify → Odoo

A sincronização de pedidos é o caminho de integração mais crítico. Cada pedido do Shopify deve criar um pedido de venda Odoo correspondente que acione o atendimento e atualize os registros financeiros.

Configuração do webhook do Shopify para eventos de pedido:

// Register webhooks via Shopify API
const webhooks = [
  {
    topic: 'orders/create',
    address: 'https://your-integration.com/webhooks/shopify/orders',
    format: 'json'
  },
  {
    topic: 'orders/updated',
    address: 'https://your-integration.com/webhooks/shopify/orders/updated',
    format: 'json'
  },
  {
    topic: 'orders/fulfilled',
    address: 'https://your-integration.com/webhooks/shopify/orders/fulfilled',
    format: 'json'
  },
  {
    topic: 'refunds/create',
    address: 'https://your-integration.com/webhooks/shopify/refunds',
    format: 'json'
  }
];

Transformando um pedido do Shopify em um pedido de venda Odoo:

def shopify_order_to_odoo_sale_order(shopify_order: dict) -> dict:
    """Transform Shopify order payload to Odoo sale.order format"""

    # Find or create Odoo partner (customer)
    partner_id = find_or_create_odoo_partner(
        email=shopify_order['email'],
        name=shopify_order['customer']['first_name'] + ' ' + shopify_order['customer']['last_name'],
        phone=shopify_order['customer'].get('phone'),
        shipping_address=shopify_order['shipping_address']
    )

    # Map line items
    order_lines = []
    for item in shopify_order['line_items']:
        odoo_product_id = get_odoo_product_from_shopify_variant(
            item['variant_id']
        )
        order_lines.append({
            'product_id': odoo_product_id,
            'product_uom_qty': item['quantity'],
            'price_unit': float(item['price']),
            'name': item['name'],
            'shopify_line_id': item['id'],  # Custom field for traceability
        })

    # Add shipping as a service product line
    if float(shopify_order.get('shipping_lines', [{}])[0].get('price', 0)) > 0:
        order_lines.append({
            'product_id': SHIPPING_PRODUCT_ID,  # Configured in settings
            'product_uom_qty': 1,
            'price_unit': float(shopify_order['shipping_lines'][0]['price']),
            'name': shopify_order['shipping_lines'][0]['title'],
        })

    return {
        'partner_id': partner_id,
        'order_line': [(0, 0, line) for line in order_lines],
        'shopify_order_id': shopify_order['id'],  # Custom field
        'shopify_order_name': shopify_order['name'],  # e.g., #1001
        'note': shopify_order.get('note', ''),
        'state': 'sale',  # Confirm order automatically
    }

Tratamento de idempotência:

A Shopify pode entregar o mesmo evento de webhook diversas vezes (novas tentativas de rede). Sua integração deve lidar com eventos duplicados normalmente:

def process_shopify_order_webhook(payload: dict):
    shopify_order_id = str(payload['id'])

    # Check if already processed
    if OrderSyncLog.objects.filter(
        shopify_order_id=shopify_order_id,
        status='completed'
    ).exists():
        logger.info(f"Order {shopify_order_id} already processed, skipping")
        return

    # Process and log
    try:
        odoo_order_id = create_odoo_sale_order(payload)
        OrderSyncLog.objects.create(
            shopify_order_id=shopify_order_id,
            odoo_order_id=odoo_order_id,
            status='completed'
        )
    except Exception as e:
        OrderSyncLog.objects.create(
            shopify_order_id=shopify_order_id,
            status='failed',
            error=str(e)
        )
        raise

---

Sincronização de estoque: Odoo → Shopify

Os níveis de estoque devem refletir a realidade do Odoo no Shopify em tempo real (ou quase em tempo real) para evitar vendas excessivas.

Sincronização de inventário baseada em gatilhos:

A abordagem mais confiável é a sincronização orientada por eventos: quando o estoque muda no Odoo (venda, recebimento de compra, conclusão da fabricação, ajuste de estoque), o Odoo envia a quantidade atualizada para o Shopify.

# In Odoo (using automated actions or override)
def _post_write_sync_to_shopify(self):
    """Called after inventory level changes in Odoo"""
    for move_line in self:
        product = move_line.product_id
        location = move_line.location_id

        if location.is_shopify_sync_location:
            shopify_variant_id = product.shopify_variant_id
            if shopify_variant_id:
                new_quantity = product.with_context(
                    location=location.id
                ).qty_available

                sync_inventory_to_shopify(
                    shopify_variant_id=shopify_variant_id,
                    quantity=int(new_quantity)
                )

def sync_inventory_to_shopify(shopify_variant_id: str, quantity: int):
    """Push inventory update to Shopify via Admin API"""
    inventory_item_id = get_inventory_item_id(shopify_variant_id)
    location_id = get_shopify_location_id()  # Primary Shopify location

    shopify.InventoryLevel.set(
        inventory_item_id=inventory_item_id,
        location_id=location_id,
        available=quantity
    )

Conciliação de inventário agendada:

Mesmo com a sincronização orientada por eventos, agende uma reconciliação diária de inventário completo:

1. Exporte todas as quantidades de produtos Odoo do local designado para sincronização do Shopify
2. Compare com os níveis de estoque atuais do Shopify
3. Atualize quaisquer discrepâncias (podem ocorrer devido a eventos de sincronização com falha, ajustes manuais)
4. Registrar resultados de reconciliação para fins de auditoria

Essa reconciliação evita desvios de inventário devido a pequenas falhas de sincronização acumuladas.

---

Sincronização do catálogo de produtos: Odoo → Shopify

Para empresas que gerenciam catálogos de produtos no Odoo (com preços em várias moedas, especificações detalhadas e matrizes de variantes complexas), a sincronização do catálogo com o Shopify elimina a entrada dupla manual.

Arquitetura de mapeamento de produto:

Odoo Product (product.template)
├── Shopify Product (via shopify_product_id field on Odoo template)
│
└── Odoo Product Variants (product.product)
    └── Shopify Variants (via shopify_variant_id field on Odoo product.product)

O que sincronizar do Odoo para o Shopify:

• Nome do produto (descrição de vendas do Odoo)
• Descrição do produto (descrição HTML longa)
• Imagens (imagens product.template)
• Preço (usando a lista de preços configurada do Shopify)
• SKU (referência interna do Odoo)
• Código de barras (EAN/UPC da Odoo)
• Peso (para cálculo de frete)
• Status ativo/arquivado (cancelar publicação no Shopify quando o produto Odoo for arquivado)
• Inventário (do local de sincronização designado)

O que NÃO sincronizar do Odoo para o Shopify:

• Metadados de SEO específicos do Shopify (tags de título, meta descrições – gerencie no Shopify)
• Etiquetas de produtos do Shopify (gerenciar no Shopify)
• Coleções/categorias do Shopify (gerenciar no Shopify)
• Conteúdo específico do Shopify (seções do construtor de páginas, descrições detalhadas formatadas para o Shopify)

---

Gerenciamento de dados do cliente

Os clientes que existem no Shopify (a partir de sua conta na loja) e no Odoo (como contatos/parceiros) precisam de uma fusão cuidadosa para criar um único perfil unificado.

Estratégia de desduplicação usando e-mail:

def find_or_create_odoo_partner(email: str, name: str, **kwargs) -> int:
    """Find existing Odoo partner by email or create new one"""
    existing = Partner.search([
        ('email', '=', email)
    ], limit=1)

    if existing:
        # Update with latest data from Shopify
        existing.write({
            'phone': kwargs.get('phone', existing.phone),
        })
        return existing.id
    else:
        # Create new partner
        partner = Partner.create({
            'name': name,
            'email': email,
            'phone': kwargs.get('phone'),
            'type': 'contact',
            'customer_rank': 1,
            'shopify_customer_id': kwargs.get('shopify_customer_id'),
        })
        return partner.id

IDs de cliente do Shopify armazenados no Odoo:

Adicione um campo personalizado shopify_customer_id ao modelo res.partner do Odoo. Isso permite a pesquisa bidirecional: encontre o parceiro Odoo no ID do Shopify, encontre o cliente do Shopify no parceiro Odoo.

---

Ciclo de atendimento: Odoo → Shopify

Quando Odoo processa uma entrega (coleta + validação), o pedido é atendido. Shopify deve ser notificado para:

• Marcar o pedido como atendido
• Enviar o e-mail de confirmação de envio ao cliente
• Registre o número de rastreamento

def sync_fulfillment_to_shopify(odoo_picking: StockPicking):
    """Called after Odoo delivery is validated"""
    shopify_order_name = odoo_picking.sale_id.shopify_order_name
    tracking_number = odoo_picking.carrier_tracking_ref

    # Find Shopify order
    shopify_orders = shopify.Order.find(name=shopify_order_name)
    if not shopify_orders:
        return

    shopify_order = shopify_orders[0]

    # Create fulfillment in Shopify
    fulfillment = shopify.Fulfillment.create({
        'order_id': shopify_order.id,
        'tracking_number': tracking_number,
        'tracking_company': odoo_picking.carrier_id.name,
        'notify_customer': True,  # Sends Shopify's shipping email
        'line_items': [
            {'id': line.shopify_line_id}
            for line in odoo_picking.sale_id.order_line
            if line.shopify_line_id
        ]
    })

---

Integração contábil: Shopify Sales → Odoo Financials

Cada venda do Shopify deve eventualmente aparecer no módulo de contabilidade do Odoo como uma entrada de venda publicada.

Abordagem de integração para contabilidade:

Opção 1 – Contabilidade em nível de pedido: cada pedido do Shopify cria uma fatura Odoo (ou o pedido de venda Odoo gera uma fatura quando atendido). Os pagamentos registrados no Shopify acionam o registro de pagamento no Odoo.

Opção 2 – Contabilidade em nível de liquidação: As liquidações do Shopify Payments (depósitos bancários diários ou semanais) são registradas no Odoo como lançamentos contábeis manuais que são reconciliados com as transações bancárias. Isso é mais simples de manter, mas fornece uma contabilidade menos granular.

Para a maioria dos comerciantes de médio porte, a contabilidade no nível da liquidação (Opção 2) é suficiente e significativamente menos complexa de implementar e manter.

Dados de pagamento do Shopify → lançamento no diário Odoo:

def process_shopify_payout(payout_data: dict):
    """Create Odoo journal entry for Shopify Payments payout"""
    journal = ShopifyJournal.get_or_create()  # Shopify clearing account

    entry = AccountMove.create({
        'journal_id': journal.id,
        'date': payout_data['date'],
        'ref': f"Shopify Payout {payout_data['id']}",
        'line_ids': [
            (0, 0, {
                'account_id': SHOPIFY_CLEARING_ACCOUNT_ID,
                'credit': payout_data['amount'],
                'name': f"Shopify sales - {payout_data['period']}",
            }),
            (0, 0, {
                'account_id': SHOPIFY_FEES_ACCOUNT_ID,
                'debit': payout_data['fees'],
                'name': 'Shopify Payments fees',
            }),
            (0, 0, {
                'account_id': BANK_ACCOUNT_ID,
                'debit': payout_data['amount'] - payout_data['fees'],
                'name': f"Bank deposit - Shopify payout {payout_data['id']}",
            }),
        ]
    })
    entry.action_post()

---

Perguntas frequentes

Quanto tempo leva para implementar uma integração Shopify-Odoo?

Uma integração básica (sincronização de pedidos, sincronização de inventário, sincronização de clientes) usando um conector pré-construído leva de 2 a 4 semanas, incluindo configuração, testes e migração de dados. Uma integração personalizada que cobre todo o ciclo de vida (pedidos, estoque, sincronização de atendimento, devoluções, contabilidade) leva de 8 a 16 semanas, dependendo da complexidade do negócio. Cenários complexos – Odoo multi-armazém, manufatura, multi-moeda, multi-empresa – adicionam de 4 a 8 semanas adicionais. Orçamento para manutenção contínua: as integrações exigem atualizações quando o Shopify ou o Odoo lançam alterações na API.

Devo gerenciar produtos no Shopify ou no Odoo?

Para catálogos de produtos simples: gerencie no Shopify e atualize manualmente o Odoo para fins de fabricação/compra. Para catálogos complexos (muitas variantes, preços em várias moedas, especificações técnicas, listas técnicas de fabricação): gerencie no Odoo e sincronize com o Shopify. O fator crítico é onde sua equipe de produto realmente trabalha. Se sua equipe de merchandising mora no Shopify, forçá-los a trabalhar no Odoo cria atrito. Se sua equipe de operações gerencia produtos no Odoo para fabricação e compras, o Shopify Sync é a abordagem certa.

O que acontece com os pedidos existentes do Shopify quando a integração entra em operação?

Os pedidos históricos não precisam migrar para o Odoo. A integração processa novos pedidos a partir da data de entrada em operação. Para dados históricos (registros de clientes, catálogo de produtos, linhas de base de estoque), execute uma migração de dados única antes da integração entrar em operação: importe dados históricos de clientes para o Odoo, importe o catálogo de produtos e defina linhas de base de estoque no Odoo para corresponder às quantidades atuais do Shopify.

Como faço para lidar com pedidos do Shopify com produtos que não existem no Odoo?

Este caso extremo quebra integrações ingênuas. Crie um substituto: quando um pedido do Shopify contém um ID de variante que não é mapeado para um produto Odoo, crie o pedido no Odoo com um espaço reservado para produto "Produto desconhecido" e alerte sua equipe de integração. Defina uma fila de erros com notificação: a equipe de operações analisa produtos não mapeados, cria o produto Odoo e reprocessa o pedido com falha. Isto é preferível à falha silenciosa ou ao bloqueio de todos os pedidos enquanto se aguarda uma correção do mapeamento.

Essa integração pode oferecer suporte a várias lojas do Shopify (por exemplo, diferentes lojas de mercado)?

Sim, mas com complexidade adicional. Cada loja Shopify é uma conexão API separada. Uma instância do Odoo pode receber pedidos de várias lojas do Shopify, com a origem da loja rastreada por meio de um campo personalizado. A alocação de estoque entre lojas requer lógica adicional: pool de estoque compartilhado (o Odoo aloca entre lojas com base na demanda do pedido) ou estoque segregado por local (cada loja tem um local Odoo designado). A integração de várias lojas duplica o escopo dos testes e a carga de manutenção contínua.

---

Próximas etapas

Uma integração Shopify-Odoo bem implementada transforma a eficiência operacional: eliminando a entrada manual de dados, evitando vendas excessivas, permitindo relatórios sofisticados e conectando vendas de comércio eletrônico a processos de fabricação, compras e financeiros.

ECOSIRE cria Shopify e integrações Odoo ERP para comerciantes de médio porte — abrangendo design de arquitetura, desenvolvimento personalizado, migração de dados, testes e suporte contínuo. Nossa equipe de integração implementou conexões Shopify-Odoo para mais de 30 comerciantes em diversas categorias de produtos.

Entre em contato com nossa equipe de integração para projetar sua arquitetura de integração Shopify-Odoo.