Importação de pedidos do Shopify para Odoo: guia completo

Para uma loja que processa 200 pedidos por dia, a importação manual de pedidos consome cerca de 3 a 4 horas diárias do tempo da equipe e introduz uma taxa de erro de 2 a 5% que se espalha pelo estoque, envio e contabilidade.

Automatizar o pipeline de pedidos do Shopify para Odoo elimina totalmente esse gargalo. Os pedidos chegam ao Odoo segundos após a colocação, os registros dos clientes são mesclados automaticamente, os status dos pagamentos são sincronizados em tempo real, as atualizações de atendimento são enviadas para o Shopify com números de rastreamento e as condições de erro são detectadas e enfileiradas para resolução, em vez de descartadas silenciosamente.

Este guia cobre a automação completa da importação de pedidos - desde o webhook do Shopify que inicia o processo até o write-back de atendimento que fecha o ciclo. Cada etapa inclui mapeamentos de dados específicos, casos extremos e modos de falha que você precisa lidar para uma implementação de nível de produção.

Principais conclusões

Os webhooks do Shopify fornecem eventos de pedidos em tempo real — pedidos/criação, pedidos/atualizados, pedidos/cancelados — que acionam o pipeline de importação

A sincronização de clientes usa e-mail como chave de correspondência primária, com criação automatizada para novos clientes e fusão de campos para os existentes

O mapeamento de status de pagamento traduz os estados de pagamento do Shopify (autorizado, pago, parcialmente pago, reembolsado) em registros de pagamento Odoo

A correspondência de produtos conecta itens de linha do Shopify a produtos Odoo usando SKU como identificador principal – a correspondência em nível de variante é essencial

O write-back de atendimento envia a confirmação de entrega do Odoo de volta ao Shopify com números de rastreamento, informações da transportadora e dados de atendimento por item de linha

O atendimento parcial (remessas divididas de vários armazéns) exige rastreamento de atendimento no nível do item de linha, não no nível do pedido

O tratamento de erros deve incluir filas de novas tentativas, processamento de mensagens mortas e alertas — falhas silenciosas são as falhas mais perigosas

Chaves de idempotência (ID de pedido do Shopify) evitam pedidos duplicados de novas tentativas de webhook

Arquitetura: o pipeline de importação de pedidos

O pipeline completo de importação de pedidos tem seis estágios, cada um com transformações de dados e modos de falha específicos:

Stage 1: Webhook Reception
  Shopify → orders/create webhook → Integration endpoint

Stage 2: Customer Resolution
  Find or create Odoo customer from Shopify customer data

Stage 3: Product Matching
  Map Shopify line items to Odoo products by SKU/variant

Stage 4: Order Creation
  Create Odoo sale order with lines, taxes, shipping, discounts

Stage 5: Payment Recording
  Record payment status based on Shopify financial_status

Stage 6: Fulfillment Writeback
  Odoo delivery → Shopify fulfillment with tracking

Cada estágio é uma operação distinta que pode falhar de forma independente. Uma implementação robusta os processa como um pipeline com pontos de verificação – se o Estágio 4 falhar, os estágios 1–3 não serão executados novamente na nova tentativa.

Etapa 1: recebimento de webhooks de pedidos do Shopify

Os webhooks do Shopify são a base da importação de pedidos em tempo real. Quando ocorre um evento de pedido, o Shopify envia uma solicitação HTTP POST para seu endpoint registrado com a carga completa do pedido.

Assinaturas de Webhook obrigatórias

Tópico do webhook	Finalidade	Quando dispara
encomendar/criar	Novo pedido realizado	O cliente conclui a compra
pedidos/atualizado	Encomenda modificada	Pagamento capturado, cumprimento adicionado, edições feitas
pedidos/cancelados	Pedido cancelado	Comerciante ou cliente cancela
reembolsos/criar	Reembolso emitido	Reembolso total ou parcial processado

Verificação de webhook

Cada webhook recebido deve ser verificado usando a assinatura HMAC-SHA256 da Shopify. A carga útil do webhook é assinada com o segredo compartilhado do seu aplicativo – verifique a assinatura antes do processamento. Webhooks não verificados devem ser rejeitados com uma resposta 401.

Lidando com garantias de entrega de webhook

Shopify garante entrega pelo menos uma vez, o que significa que o mesmo webhook pode ser enviado várias vezes – após o tempo limite da rede, durante o ciclo de novas tentativas do Shopify ou durante a recuperação de incidentes. Seu endpoint deve ser idempotente: receber os mesmos pedidos/criar webhook duas vezes não deve criar dois pedidos Odoo.

Padrão de implementação: use o ID do pedido da Shopify como chave de idempotência. Antes de criar um pedido Odoo, verifique se já existe um pedido com essa referência Shopify. Se isso acontecer, pule a criação e retorne uma resposta 200 para que o Shopify pare de tentar novamente.

Requisitos de tempo de resposta

Shopify espera uma resposta 200 em 5 segundos. Se o seu endpoint demorar mais, o Shopify marca a entrega como com falha e tenta novamente. Por esse motivo, o endpoint do webhook deve aceitar a carga útil, validar a assinatura HMAC, enfileirar o pedido para processamento assíncrono e retornar 200 imediatamente. A criação real do pedido acontece em um trabalhador em segundo plano.

Etapa 2: Resolução do cliente

Cada pedido do Shopify inclui dados do cliente – e-mail, nome, telefone, endereço de entrega e endereço de cobrança. A integração deve resolver isso no banco de dados de contatos do Odoo.

Algoritmo de correspondência de clientes

A lógica de correspondência recomendada segue esta sequência de prioridade:

Correspondência exata de e-mail: pesquise nos contatos do Odoo o endereço de e-mail do pedido do Shopify. O email é o identificador exclusivo mais confiável.
Correspondência por telefone (se não houver correspondência por e-mail): alguns pedidos B2B ou pedidos POS podem não ter e-mail. Volte para a correspondência de número de telefone com normalização (tirar espaços, traços, normalização de código de país).
Criar novo contato: Se nenhuma correspondência for encontrada, crie um novo contato Odoo com todos os dados disponíveis do pedido do Shopify.

Mesclagem de campos para clientes existentes

Quando um cliente Odoo existente é correspondido, a integração deve atualizar (não substituir) os campos ausentes:

If Odoo contact has no phone but Shopify order does → add phone
If Odoo contact has phone and Shopify order has different phone → keep Odoo (source of truth)
If Shopify order has new shipping address → add as child contact (delivery address)

Tratamento de endereço

Os pedidos do Shopify incluem um endereço de cobrança e um endereço de entrega. No Odoo, eles são mapeados para diferentes tipos de contato. O endereço de cobrança deve estar associado ao registro do parceiro principal (ou a um contato filho do tipo “endereço de fatura”). O endereço de entrega deve ser um contato filho do tipo “endereço de entrega”. Se o cliente tiver usado vários endereços de entrega em pedidos diferentes, cada endereço exclusivo deverá ser um contato filho separado, permitindo a seleção de endereço para pedidos manuais futuros.

Atendimento ao cliente B2B

Para pedidos B2B (recursos B2B do Shopify Plus), a integração deve mapear a empresa Shopify para um contato do tipo empresa Odoo, com o comprador individual como contato filho. Isso preserva o relacionamento entre empresa e indivíduo que as operações B2B exigem para condições de crédito, preços por volume e gerenciamento de contas.

Etapa 3: correspondência de produto

Cada item de linha em um pedido do Shopify deve corresponder a um produto no Odoo. Essa correspondência é onde muitas integrações falham, porque Shopify e Odoo representam produtos de forma diferente.

Correspondência baseada em SKU

SKU é a chave de correspondência primária recomendada. Ao gerenciar produtos no Odoo e sincronizá-los com o Shopify, a referência interna (SKU) do Odoo deve ser definida na variante do produto Odoo e na variante do Shopify. A integração corresponde ao SKU do item de linha do Shopify com a referência interna da variante do produto Odoo.

Complexidade de correspondência de variantes

As variantes do Shopify (tamanho: grande, cor: azul) devem corresponder às variantes do produto Odoo com valores de atributos equivalentes. Isso é simples quando os SKUs são consistentes, mas falha quando os SKUs diferem entre os sistemas, quando o Shopify tem variantes que não existem no Odoo (por exemplo, uma nova variante adicionada no Shopify, mas ainda não sincronizada com o Odoo) ou quando os produtos Odoo usam atributos configuráveis enquanto o Shopify usa variantes predefinidas.

Tratamento de produtos incomparáveis: quando um item de linha do Shopify não pode ser correspondido a um produto Odoo, a integração não deve ignorá-lo silenciosamente. Em vez disso, ele deve criar o pedido com uma linha de produtos de espaço reservado (por exemplo, um item abrangente "Produto Shopify incomparável" com o título da variante Shopify na descrição), sinalizar o pedido para revisão e alertar a equipe de operações.

Pacote e Kit de Produtos

Se você vende pacotes no Shopify (por exemplo, um "Starter Kit" enviado como três produtos separados), a integração precisa saber se deve criar uma única linha de pedido Odoo (para o produto em pacote) ou várias linhas (para os produtos componentes). Isso depende da configuração do seu inventário Odoo – se você rastreia produtos em pacote como um único item ou como componentes individuais.

Etapa 4: Criação de pedidos no Odoo

Com o cliente resolvido e os produtos correspondidos, a integração cria o pedido de venda Odoo. Esta é a fase com maior utilização de dados, exigindo um mapeamento de campo cuidadoso.

Mapeamento de campo: pedido de venda do Shopify para Odoo

Campo Shopify	Campo Odoo	Notas
pedido.id	x_shopify_order_id	Campo personalizado para referência
nome do pedido	cliente_pedido_ref	por exemplo, "#1042"
pedido.criado_at	data_pedido	Data do pedido
pedido.cliente.e-mail	id_do_parceiro	Resolvido na Etapa 2
order.shipping_address	parceiro_shipping_id	Endereço de entrega contato
pedido.endereço_de_faturamento	parceiro_fatura_id	Endereço de faturação contato
ordem.moeda	moeda_id	Mapa para moeda Odoo
pedido.nota	nota	Notas do cliente
ordem.tags	tags_ids	Sincronização de tags opcional

Mapeamento de item de linha

Campo Shopify	Campo de linha de pedido de venda Odoo	Notas
line_item.variant_id	id_do_produto	Resolvido na Etapa 3
item_linha.quantidade	produto_uom_qty	Quantidade do pedido
item_linha.preço	unidade_preço	Preço unitário
line_item.total_discount	desconto	Converter para porcentagem
line_item.tax_lines	id_imposto	Mapa para a posição fiscal do Odoo

Tratamento de descontos

Shopify representa descontos de forma diferente do Odoo. Shopify fornece um valor de desconto por item de linha e um código de desconto geral no nível do pedido. Odoo espera um percentual de desconto por linha.

Conversão: discount_percentage = (shopify_discount_amount / (quantity * unit_price)) * 100

Para descontos no nível do pedido (por exemplo, "10% de desconto no pedido inteiro"), o desconto deve ser distribuído proporcionalmente entre os itens de linha. Algumas implementações adicionam um item de linha de valor negativo separado para descontos no nível do pedido em vez de distribuição – ambas as abordagens são válidas, mas a distribuição proporcional produz uma análise de margem por item de linha mais limpa.

Linha de Envio

As despesas de envio do Shopify devem ser mapeadas para um produto Odoo dedicado (por exemplo, "Envio do Shopify") em uma linha de pedido separada. Isso mantém a receita de remessa distinta da receita do produto nos relatórios.

Campo Shopify	Linha Odoo	Notas
linhas_de_transporte[0].título	product_id → "Envio do Shopify"	Descrição do Shopify
linhas_de_transporte[0].preço	unidade_preço	Valor do frete
linhas_de_transporte[0].tax_lines	id_imposto	Taxa de envio, se aplicável

Confirmação do pedido

Depois de criar a ordem de venda no estado de rascunho, a integração deve confirmá-la automaticamente (action_confirm) para acionar fluxos de trabalho posteriores — criação de ordem de entrega, ordens de fabricação (para produtos MTO) e ordens de compra (para produtos dropship). Confirme automaticamente apenas se o status do pagamento for "pago" ou "autorizado" — retenha rascunhos de pedidos para estados de pagamento "pendentes".

Etapa 5: Registro de pagamento

O campo financial_status do Shopify indica o estado do pagamento do pedido. A integração deve traduzir isso em registros de pagamento Odoo.

Mapeamento de status de pagamento

Status_financeiro do Shopify	Ação Odoo	Notas
pago	Cadastrar pagamento (integral)	Criar fatura de conciliação de pagamento
autorizado	Nenhum pagamento ainda	Pagamento capturado posteriormente
parcialmente_pago	Cadastrar pagamento parcial	Valor recorde pago até agora
pendente	Manter em rascunho	Aguardar confirmação de pagamento
reembolsado	Cadastrar pagamento + nota de crédito	Cenário de reembolso total
parcialmente_reembolsado	Cadastrar pagamento + crédito parcial	Cenário de reembolso parcial
anulado	Cancelar pedido	Autorização de pagamento anulada

Criação automática de faturas

Para pedidos “pagos”, a integração deve criar e validar a fatura Odoo automaticamente e, em seguida, registrar o pagamento nela. Isso mantém as contas a receber limpas – os pedidos totalmente pagos do Shopify devem ter saldo AR zero no Odoo.

Para pedidos “autorizados” (comuns no Shopify Payments quando a captura manual está habilitada), a integração deve criar o pedido de venda, mas não a fatura. Quando o pagamento é capturado posteriormente (acionando um webhook de pedidos/atualizado com status_financeiro mudando para "pago"), a integração cria a fatura e registra o pagamento.

Configuração da forma de pagamento

Crie um diário de pagamentos Odoo dedicado para pagamentos do Shopify (por exemplo, diário "Shopify Payments" do tipo "Banco"). Todos os registros de pagamentos automatizados devem usar este diário. Isso mantém os registros de pagamento do Shopify separados de outros métodos de pagamento e simplifica a reconciliação bancária.

Etapa 6: Writeback de cumprimento

A etapa final fecha o ciclo – quando um pedido é atendido no Odoo (pedido de entrega validado), a integração envia os dados de atendimento de volta ao Shopify, atualizando o status do pedido e fornecendo ao cliente informações de rastreamento.

Acionando o Writeback

No Odoo, o evento de atendimento é a validação de um pedido de entrega (stock.picking). A integração deve escutar eventos de confirmação de pedido de entrega e acionar uma chamada de API de atendimento do Shopify.

Mapeamento de dados de atendimento

Campo de entrega Odoo	Campo de atendimento do Shopify	Notas
transportadora_tracking_ref	número_de_rastreamento	Número de rastreamento da transportadora
ID_da_operadora.nome	empresa_de_rastreamento	por exemplo, "UPS", "FedEx"
move_line_ids	itens_de_linha	Mapear produtos Odoo de volta aos IDs de item de linha do Shopify
data_concluído	—	Carimbos de data e hora do Shopify automaticamente

Tratamento de atendimento parcial

O atendimento parcial ocorre quando um pedido é enviado em vários pacotes, de vários armazéns ou quando alguns itens estão em espera. Shopify oferece suporte nativo ao atendimento parcial – você pode atender itens de linha específicos e deixar outros não atendidos. A integração deve rastrear quais itens de linha do Shopify correspondem a quais linhas de pedido de entrega do Odoo e enviar apenas os itens atendidos em cada chamada da API de atendimento. Enviar um atendimento para itens que já foram atendidos causa um erro de API.

Tratamento de remessas divididas

Quando o Odoo divide um pedido de entrega em várias remessas (cenário de pedido em espera), cada remessa gera um pedido de entrega separado. A integração deve:

Detectar que o novo pedido de entrega é um pedido em espera (relacionado ao mesmo pedido de venda)
Identifique quais itens de linha estão nesta remessa
Crie um atendimento parcial no Shopify apenas para esses itens
Inclua o número de rastreamento correto para esta remessa específica

Writeback de atendimento para pedidos de dropship

Para atendimentos de dropship (onde o fornecedor envia diretamente ao cliente), as informações de rastreamento vêm do recebimento do pedido de compra, e não de um pedido de entrega no armazém. A integração deve monitorar as confirmações de recebimento de compra para pedidos de dropship e usar o número de rastreamento do fornecedor para o atendimento do Shopify.

Tratamento e recuperação de erros

Os erros no pipeline de importação de pedidos se enquadram em três categorias, cada uma exigindo uma estratégia de recuperação diferente.

Erros transitórios (tentar novamente automaticamente)

Tempos limite de rede, limites de taxa de API, indisponibilidade temporária de serviço – tudo isso se resolve sozinho. A integração deve implementar novas tentativas de espera exponencial: primeira tentativa após 30 segundos, segunda após 2 minutos, terceira após 10 minutos, até uma contagem máxima de novas tentativas configurável (normalmente de 5 a 10).

Erros de dados (Quarentena para revisão)

Produtos incomparáveis, endereços inválidos, campos obrigatórios ausentes — exigem intervenção humana. A integração deve colocar o pedido em quarentena em uma fila de revisão com uma descrição clara do que falhou, criar uma atividade ou notificação Odoo para a equipe de operações e fornecer um mecanismo de nova tentativa com um clique após a correção do problema de dados.

Erros Sistêmicos (Alerta Imediatamente)

Falhas de autenticação, alterações de permissão de API, erros de configuração do conector — afetam todos os pedidos, não apenas um. A integração deve detectar padrões (por exemplo, 5 falhas consecutivas) e escalar imediatamente por e-mail e alerta no painel.

A fila de cartas mortas

Os pedidos que falham em todas as novas tentativas são transferidos para uma fila de mensagens mortas – um registro persistente de pedidos não processáveis. Essa fila deve ser monitorada diariamente. Motivos comuns de mensagens mortas incluem produtos que existem no Shopify, mas nunca foram sincronizados com o Odoo, dados de clientes com caracteres inválidos que o Odoo rejeita, pedidos com itens de preço zero que falham na validação do Odoo e incompatibilidades de moeda quando uma nova moeda do Shopify não é configurada no Odoo.

Testando o pipeline de importação de pedidos

Antes de entrar no ar, teste todos os caminhos do pipeline:

Cenários de testes funcionais

Cenário	Resultado Esperado
Pedido pago padrão	Odoo SO criado, confirmado, faturado, pagamento registrado
Encomende com código de desconto	Desconto distribuído corretamente pelas linhas
Encomende com múltiplas variantes	Cada variante é mapeada para corrigir o produto Odoo
Pedido para novo cliente	Novo contato Odoo criado com todos os endereços
Pedido para cliente existente	Contato existente encontrado, campos mesclados
Pedido em várias moedas	Registrado em moeda de apresentação, convertido em funcional
Cumprimento parcial	Shopify mostra parcialmente atendido com itens de linha corretos
Cumprimento total	Shopify mostra preenchido com número de rastreamento
Cancelamento de pedido	Odoo SO cancelado, inventário restaurado
Reembolso (integral)	Nota de crédito criada, pagamento estornado
Reembolso (parcial)	Nota de crédito parcial para rubricas específicas
Webhook duplicado	Segundo webhook não cria pedido duplicado
Produto não está em Odoo	Pedido em quarentena com alerta
Limite de taxa de API atingido	Pedido repetido após período de espera

Teste de carga

Se sua loja processa grandes volumes (mais de 500 pedidos/dia), teste de carga o pipeline de importação com volumes de dados semelhantes aos de produção. Verifique se o pipeline lida com tráfego intenso (vendas instantâneas), se os bloqueios de banco de dados não criam gargalos e se os limites de taxa da API Shopify e Odoo são respeitados.

Otimização de desempenho

Processamento em lote para importações históricas

Ao configurar inicialmente a integração ou importar pedidos históricos, use a API REST da Shopify para buscar pedidos em lotes de 250 (o tamanho máximo da página) em vez de processar cada pedido individualmente. Crie registros Odoo em lotes usando o método de criação ORM com uma lista de valores.

Cache de pesquisas de produtos e clientes

A correspondência de produtos (Estágio 3) e a resolução do cliente (Estágio 2) envolvem pesquisas no banco de dados para cada pedido. Armazene em cache produtos e clientes acessados com frequência para reduzir chamadas de API Odoo. Invalide o cache quando produtos ou clientes forem atualizados.

Simultaneidade de processamento de webhook

Para armazenamentos de alto volume, processe webhooks simultaneamente – vários trabalhadores extraindo da fila de mensagens simultaneamente. Garanta a segurança da simultaneidade usando o bloqueio no nível do banco de dados na verificação da chave de idempotência para evitar que dois trabalhadores criem o mesmo pedido simultaneamente.

Perguntas frequentes

Com que rapidez os pedidos do Shopify aparecem no Odoo com automação baseada em webhook?

Com uma integração baseada em webhook configurada corretamente, os pedidos do Shopify aparecem no Odoo dentro de 2 a 10 segundos após a colocação do pedido. Isso inclui entrega de webhook, verificação HMAC, resolução do cliente, correspondência de produtos e criação de pedidos de venda. As alternativas baseadas em cron adicionam de 5 a 60 minutos de atraso, dependendo do intervalo de pesquisa.

O que acontece se o Odoo estiver fora do ar quando um pedido do Shopify chegar?

A fila de mensagens da integração retém a carga útil do webhook do pedido até que o Odoo esteja disponível. Quando o Odoo volta a ficar online, a fila processa todos os pedidos pendentes em sequência. Shopify também tenta novamente entregas de webhook com falha por até 48 horas, fornecendo uma rede de segurança secundária. Os pedidos nunca serão perdidos se a integração usar uma fila de mensagens persistente.

Posso importar pedidos de várias lojas do Shopify para uma instância do Odoo?

Sim. Cada loja Shopify se conecta por meio de seu próprio conjunto de credenciais de API e assinaturas de webhook. A integração marca cada pedido com a loja de origem (usando um campo personalizado ou equipe de vendas Odoo) para que você possa gerar relatórios por loja. Os produtos podem ser compartilhados entre lojas ou em lojas específicas, dependendo da sua estratégia de catálogo.

Como a integração lida com rascunhos de pedidos do Shopify?

Os rascunhos de pedidos (criados por comerciantes para pedidos por telefone ou cotações B2B) devem ser importados quando forem concluídos (pagos), e não quando forem criados como rascunhos. Assine o webhook de pedidos/criação, que é acionado quando um rascunho de pedido é convertido em um pedido real. Como alternativa, assine draft_orders/update e importe somente quando o status mudar para "concluído".

E os pedidos do Shopify PDV – eles seguem o mesmo pipeline?

Os pedidos do Shopify POS acionam os mesmos pedidos/criação de webhook que os pedidos online. A integração pode processá-los de forma idêntica, embora você possa querer marcar pedidos de PDV com uma equipe de vendas Odoo diferente ou fonte de relatórios. Os pedidos de PDV também podem incluir dinheiro ou métodos de pagamento em terminal externo, que exigem diferentes configurações de diário de pagamento Odoo.

Como lidar com as edições de pedidos após a importação (por exemplo, o comerciante edita um pedido no Shopify)?

Shopify dispara um webhook de pedidos/atualizado quando um pedido é editado. A integração deve comparar o pedido atualizado com o pedido de venda Odoo existente e aplicar as diferenças – itens de linha adicionados, itens removidos, alterações de quantidade ou ajustes de preço. Esta é uma das partes mais complexas da integração, e algumas implementações lidam com isso cancelando o Odoo SO e recriando-o, o que é mais simples, mas cria mais lançamentos contábeis.

A automação pode lidar com pedidos de assinatura de aplicativos Shopify Subscriptions?

Pedidos de assinatura (de Recharge, Bold Subscriptions ou assinaturas nativas do Shopify) acionam pedidos padrão/criam webhooks para cada cobrança recorrente. A integração os importa como qualquer outro pedido. Para vincular pedidos recorrentes a um registro de assinatura do Odoo, use o ID da assinatura do metacampo do aplicativo como referência e associe todos os pedidos de venda do Odoo relacionados a uma única assinatura do Odoo.

Implementação com ECOSIRE

Construir um pipeline de importação de pedidos Shopify para Odoo de nível de produção requer o tratamento de dezenas de casos extremos que não são óbvios até que você os encontre na produção – pagamentos parciais, pedidos com itens digitais e físicos, jurisdições fiscais complexas, roteamento de vários armazéns e atendimentos de dropship de fornecedores.

Nossos serviços de integração do Shopify incluem automação completa de pedidos com o pipeline completo descrito neste guia, tratamento pré-construído para todos os casos extremos comuns, monitoramento e alertas em tempo real e manutenção contínua à medida que as APIs evoluem.

Para empresas que também desejam automatizar o lado financeiro, consulte nosso guia para Shopify + Odoo Accounting Integration ou compare suas opções com nossa comparação do conector Shopify-Odoo.

Agende uma consulta para discutir seus requisitos de automação de pedidos do Shopify com nossa equipe de integração.