Integração da API Hepsiburada com Odoo: guia completo

O cenário do comércio eletrônico da Turquia apresenta duas plataformas dominantes, e a Hepsiburada é aquela que todo vendedor sério deve dominar. Fundada em 2000, a Hepsiburada é o mercado online mais antigo e um dos mais confiáveis da Turquia, com mais de 100 milhões de visitas mensais, mais de 65.000 vendedores e um catálogo de produtos que abrange todas as categorias de consumo, desde eletrônicos e moda até peças automotivas e suprimentos industriais. Para os vendedores que executam as suas operações no Odoo ERP, a integração com a Hepsiburada através da sua API robusta é o caminho para vendas eficientes e escaláveis no mercado turco.

A integração do Hepsiburada com o Odoo por meio de sua API permite que os vendedores automatizem o gerenciamento de listas de produtos, processamento de pedidos, sincronização de estoque em tempo real, integração de carga e reconciliação de liquidação financeira. Isto elimina processos manuais que retardam o cumprimento, causam erros e limitam a capacidade do vendedor de escalar na plataforma de comércio eletrônico mais estabelecida da Turquia.

Principais conclusões

Hepsiburada recebe mais de 100 milhões de visitas mensais e é o mercado mais visitado da Turquia

A plataforma hospeda mais de 65.000 vendedores com mais de 50 milhões de listagens de produtos

Hepsiburada abriu o capital na NASDAQ em 2021, demonstrando infraestrutura de mercado de nível institucional

A API HepsiBurada (HBAPI) fornece pontos de extremidade de integração abrangentes para produtos, pedidos, estoque e reclamações

O conector do ECOSIRE lida com localização turca, conformidade fiscal KDV e integração multi-carga

Vendedores integrados à API alcançam processamento de pedidos 40% mais rápido e 90% menos erros de estoque

Por que a Hepsiburada é importante

Enquanto a Trendyol lidera em moda e volume de pedidos diários, a Hepsiburada possui vantagens distintas nas categorias de eletrônicos, eletrodomésticos, automotivo e industrial. A reputação da plataforma em termos de confiança do consumidor – construída ao longo de 25 anos de operação – proporciona-lhe uma base de clientes fiéis que se sobrepõe, mas difere do público da Trendyol. Os vendedores de comércio eletrônico turcos mais bem-sucedidos operam em ambas as plataformas, tornando a integração do Hepsiburada com o Trendyol um requisito padrão.

Estatísticas da Hepsiburada (2025-2026)

Métrica	Valor
Visitas mensais	Mais de 100 milhões
Vendedores ativos	65.000+
Listagens de produtos	Mais de 50 milhões
GMV anual	~US$ 5 bilhões
Categorias principais	Eletrônicos, eletrodomésticos, moda, automotivo, cosméticos, casa
Taxas de comissão	6-18% (dependendo da categoria)
Ciclo de pagamento	Liquidações quinzenais
Modelo de atendimento	FBM (navios do vendedor) + HepsiJet + transportadoras aprovadas
Participação no mercado na Turquia	~25%
Usuários de aplicativos móveis	30 milhões+
Fundado	2000 (mais de 25 anos de operação)

Posição Competitiva da Hepsiburada

Hepsiburada se diferencia por:

Confiança: 25 anos de operação construíram uma profunda confiança do consumidor, especialmente para compras de alto valor
Força da eletrônica: participação de mercado líder em eletrônicos de consumo, computação e dispositivos móveis
Logística HepsiJet: Rede logística interna com entrega no mesmo dia nas principais cidades
HepsiPay: sistema de pagamento integrado com opções de parcelamento (crítico no mercado de parcelamento da Turquia)
Vendas corporativas: segmento de mercado B2B para compras empresariais
Hepsiglobal: Programa de vendas internacionais atingindo mercados internacionais

Aprofundamento da API Hepsiburada (HBAPI)

Hepsiburada fornece uma API REST bem estruturada que permite integração abrangente do vendedor. A documentação da API está disponível em inglês (ao contrário de algumas APIs da plataforma turca), tornando-a acessível às equipes de desenvolvimento internacionais.

Arquitetura de API

A HBAPI está organizada em domínios de serviço:

Serviço de listagem

Crie listas de produtos com conjuntos completos de atributos
Gerenciar variantes (cor, tamanho, modelo, capacidade)
Lidar com upload e pedido de imagens
Mapa para a taxonomia da categoria de Hepsiburada
Gerenciar o status da listagem (ativo, passivo, bloqueado)
Lidar com requisitos de código de barras (GTIN/EAN)

Serviço de pedido

Recuperar novos pedidos (pedidos embaláveis)
Acesse detalhes do pedido (itens de linha, quantidades, endereços)
Atualizar o status da linha do pedido (coleta, faturado, enviado)
Criar pacotes e atribuir empresas de carga
Lidar com o cumprimento parcial (envio dos itens disponíveis primeiro)

Serviço de inventário

Atualizar quantidades de estoque por listagem por armazém
Definir status de disponibilidade
Lidar com a alocação de estoque em vários armazéns

Serviço de Sinistros

Processar reclamações do comprador (item errado, danificado, faltando)
Enviar respostas de reivindicação com evidências
Acompanhe os resultados das reivindicações e o impacto financeiro

Serviço Financeiro

Acesse relatórios de liquidação
Ver detalhamentos de comissões
Acompanhe penalidades e deduções de ajuste
Baixe faturas e documentos financeiros

Autenticação

HBAPI usa autenticação básica HTTP com ID de comerciante, nome de usuário e senha fornecidos através do Painel de Comerciantes Hepsiburada. Alguns endpoints exigem listas brancas de IP adicionais para segurança.

Limites de taxas e práticas recomendadas

Limites de taxa padrão: 100 solicitações por minuto por endpoint
Atualizações de inventário: operações em lote recomendadas (até 100 SKUs por solicitação)
Pesquisa de pedidos: recomendado a cada 10 minutos
Criação de produtos: limitada a 500 novas listagens por hora durante períodos de pico

Arquitetura de Integração

Pipeline de processamento de pedidos

O ciclo de vida dos pedidos da Hepsiburada difere ligeiramente de outros mercados. Os pedidos passam por uma máquina de estados específica:

New → Picking → Invoiced → Packaged → Shipped → Delivered
  ↓        ↓         ↓          ↓
Cancel  Re-stock  [Skip if    Tracking
                   digital]    Push

A integração deve respeitar esta máquina de estados – pular estados ou atualizar fora da sequência causa erros de API e possíveis falhas no processamento de pedidos.

Componente 1: Integração da lista de produtos

Criar e gerenciar listagens no Hepsiburada requer atenção aos requisitos específicos da plataforma:

Atributos da categoria: Cada categoria possui atributos obrigatórios e opcionais. Os eletrônicos exigem marca, modelo, especificações técnicas e período de garantia. A moda exige tabela de tamanhos, materiais e instruções de cuidados
Requisito de código de barras: Todos os produtos físicos devem ter códigos de barras GTIN/EAN válidos. A integração deve validar o formato do código de barras antes do envio
Requisitos de imagem: mínimo de 500x500 pixels, fundo branco para imagem principal, até 8 imagens por listagem
Verificação da marca: As marcas devem ser aprovadas na Hepsiburada antes que os produtos possam ser listados. A integração deve verificar o status de aprovação da marca antes de tentar criar a listagem
Idioma do conteúdo: todo o conteúdo da listagem deve estar em turco para o mercado nacional

O conector mapeia os dados do produto Odoo para o formato de listagem da Hepsiburada, valida atributos obrigatórios e lida com a conversão do formato de imagem.

Componente 2: Importação de pedidos e gerenciamento de estado

O conector pesquisa o HBAPI em busca de novos pedidos embaláveis e cria pedidos de venda Odoo com:

Mapeamento completo de produtos e variantes
Endereço de entrega do cliente
IDs de nível de pedido e de linha para rastreamento de atualização de estado
Informações sobre a forma de pagamento
Requisitos de SLA de entrega

As atualizações de estado seguem a sequência exigida pela Hepsiburada:

Separação: Confirme o recebimento do pedido e inicie o processamento do armazém
Faturado: Gerar e registrar fatura (obrigatório antes da embalagem)
Embalado: Crie um pacote com dimensões, peso e empresa de carga atribuída
Enviado: Empurre o número de rastreamento da carga

Cada transição de estado chama a HBAPI com dados apropriados e o conector trata de novas tentativas para falhas transitórias.

Componente 3: Gerenciamento de estoque

A disponibilidade de estoque é enviada do Odoo para o Hepsiburada por meio de chamadas de API em lote:

Quantidades de estoque por SKU atualizadas a cada 15-30 minutos
Buffers de segurança aplicados para vendedores multicanais
Itens com estoque zero desativados automaticamente no Hepsiburada
A restauração de estoque aciona a reativação automática

A coordenação do inventário da Hepsiburada com outros canais de vendas requer a abordagem centralizada descrita em nosso guia de sincronização de inventário em tempo real.

Componente 4: Carga e Logística

Hepsiburada suporta múltiplas opções de carga:

HepsiJet: rede logística própria da Hepsiburada (entrega no mesmo dia nas principais cidades)
Yurtic Kargo: o maior transportador de carga da Turquia
Aras Kargo: Cobertura nacional com preços competitivos
MNG Kargo: forte na entrega de itens corporativos e volumosos
Surat Kargo: opção econômica para entregas padrão
UPS Turquia: Para entregas internacionais e premium

O conector se integra ao módulo de remessa do Odoo para atribuir a transportadora apropriada com base em regras configuráveis (categoria do produto, destino, peso, urgência) e envia informações de rastreamento para a Hepsiburada.

Componente 5: Reclamações e Pós-Venda

O sistema de reclamações da Hepsiburada lida com disputas de compradores:

Item errado: O comprador recebeu um produto diferente do pedido
Danificado: Produto chegou danificado
Itens faltantes: entrega do pedido incompleta
Qualidade: Produto não corresponde à descrição do anúncio

O conector importa declarações para o módulo de suporte técnico do Odoo, permitindo que sua equipe de atendimento ao cliente analise evidências, envie respostas e rastreie resultados — tudo dentro do Odoo. A qualidade da resolução de sinistros afeta a pontuação do vendedor, tornando crítico o tratamento eficiente.

Componente 6: Liquidação Financeira

As liquidações quinzenais incluem:

Receita bruta de vendas por linha de pedido
Comissões específicas da categoria (6-18%)
Taxas de logística da HepsiJet
Taxas de serviço (listagem, transação)
Deduções de multas (envio tardio, cancelamento, perdas com reclamações)
Contribuições promocionais

O conector cria lançamentos contábeis manuais detalhados para cada componente de liquidação, permitindo análises precisas de lucratividade por produto e por categoria no Odoo.

Guia de configuração

Etapa 1: Conta de comerciante Hepsiburada

Cadastre-se no Painel Comercial Hepsiburada
Verificação completa de identidade e impostos
Solicite acesso à API e receba credenciais (ID do comerciante, nome de usuário, senha)
Envie a lista de permissões de IP para acesso à API
Solicite aprovações de marca para suas marcas de produtos

Etapa 2: Configuração do Odoo

Localização para a Turquia: Instale módulos de contabilidade, impostos e documentos específicos da Turquia
Moeda: Configure TRY com atualizações automatizadas da taxa de câmbio
Configuração KDV (IVA): Configure taxas de imposto (1%, 10%, 20%) por categoria de produto
Canal de vendas: Crie uma equipe de vendas "Hepsiburada"
Cliente: Crie um registro de cliente "Hepsiburada Marketplace"
Transportadoras: Configure a HepsiJet e empresas de carga aprovadas no módulo de entrega Odoo
Contas: Crie contas de despesas para comissões, taxas de logística e multas

Etapa 3: Instale o conector ECOSIRE

Implante o conector ECOSIRE Hepsiburada:

Instale através de aplicativos Odoo
Navegue até Configurações > Integração Hepsiburada
Insira o ID do comerciante, nome de usuário da API e senha
Configure a lista de permissões de IP, se necessário
Defina intervalos de sincronização:

Pedidos: a cada 10 minutos
Inventário: a cada 15 minutos
Produtos: a cada 4 horas ou manual

Mapeie categorias de produtos para a taxonomia de Hepsiburada

Etapa 4: configuração da lista de produtos

Mapeie produtos Odoo para categorias Hepsiburada com atributos obrigatórios
Verifique os códigos de barras GTIN/EAN para todos os produtos
Prepare o conteúdo do produto em turco
Faça upload de imagens de produtos compatíveis
Defina preços TRY com margens baseadas em comissões
Sincronize o catálogo inicial e monitore a aprovação da listagem

Etapa 5: Configuração do fluxo de trabalho do pedido

Configure a importação de pedidos e o gerenciamento de estado
Defina regras de atribuição de armazém para pedidos Hepsiburada
Configure a geração de faturas (necessário antes do empacotamento no fluxo Hepsiburada)
Configure regras de atribuição de carga
Teste o processamento de pedidos de ponta a ponta

Etapa 6: Configuração Financeira

Mapeie as taxas de comissão por categoria de produto
Configurar cronograma de importação de liquidação
Configure contas de despesas específicas para taxas
Defina a tolerância de reconciliação para pequenas variações

Desafios Específicos da Hepsiburada

Desafio 1: Requisito de fatura antes do pacote

A Hepsiburada exige que os vendedores gerem uma fatura antes de criar um pacote de envio – uma sequência que difere da maioria dos mercados onde o faturamento ocorre após ou simultaneamente ao envio.

Solução: O conector automatiza a etapa de geração da fatura no Odoo, criando e registrando a fatura assim que a retirada for confirmada. Isso garante que a sequência de estados correta (Retirada > Faturado > Embalado > Enviado) seja sempre seguida.

Desafio 2: Cultura de parcelamento

A Turquia tem uma forte cultura de pagamento parcelado – os consumidores frequentemente pagam as compras em 3, 6, 9 ou 12 parcelas mensais. Embora Hepsiburada e HepsiPay gerenciem o relacionamento de parcelamento do consumidor, os vendedores recebem o pagamento integral (menos comissões) de acordo com os termos normais de liquidação.

Solução: O conector registra corretamente o valor integral do pagamento no Odoo independente do parcelamento do consumidor. A estrutura de parcelamento é registrada para fins informativos, mas não afeta o tratamento contábil do vendedor.

Desafio 3: Complexidade Hepsiglobal Transfronteiriça

O programa Hepsiglobal da Hepsiburada permite vendas internacionais, introduzindo preços em várias moedas, logística de remessa internacional e requisitos de documentação alfandegária.

Solução: O conector oferece suporte à Hepsiglobal com configurações de preços separadas por mercado-alvo, integração de transportadora internacional e geração de documentação alfandegária por meio do Odoo.

Desafio 4: Alta Competição em Eletrônica

A eletrônica é a categoria mais forte da Hepsiburada, mas também a mais competitiva. A sensibilidade ao preço é extrema e a concorrência da Buy Box exige capacidade de resposta de preços em tempo real.

Solução: o conector oferece suporte a regras de precificação que se ajustam com base na posição competitiva e nos limites mínimos de margem. As atualizações de preços podem ser acionadas com mais frequência para categorias de alta concorrência, mantendo ao mesmo tempo as proteções de lucratividade.

Desafio 5: Picos de demanda sazonal

O comércio eletrônico turco registra grandes picos de demanda durante o dia 11/11 (Dia dos Solteiros), Black Friday e períodos de compras antes do Ramadã. Os volumes de pedidos podem aumentar de 3 a 5 vezes durante esses eventos.

Solução: O conector suporta configurações de modo de pico com maior frequência de sincronização, buffers de segurança maiores e alertas de capacidade automatizados. As listas de verificação pré-evento garantem que o estoque, os preços e a capacidade de atendimento sejam preparados antes dos picos de demanda.

Manual vs Conector ECOSIRE

Operação	Processo Manual	Conector ECOSIRE
Importação de pedidos	Verifique o painel do comerciante de hora em hora	Automático a cada 10 minutos
Atualizações de estado	Atualizar status manualmente por pedido	Progressão automatizada da máquina de estado
Geração de faturas	Criar no portal por pedido	Gerado automaticamente na confirmação de retirada
Atribuição de carga	Selecione a operadora no portal	Atribuição automática baseada em regras do Odoo
Empurrão de rastreamento	Insira o rastreamento manualmente	Push automático da entrega Odoo
Atualização de estoque	Atualização manual por SKU	Envio em lote a cada 15 minutos
Tratamento de reclamações	Monitore o portal, responda separadamente	Integrado ao helpdesk Odoo
Reconciliação de liquidação	Correspondência de planilha	Automatizado com sinalização de variação
Tempo por dia (150 pedidos)	4-6 horas	30-40 minutos
Taxa de envio dentro do prazo	80-85%	96%+

Estratégia de plataforma dupla: Hepsiburada + Trendyol

Os vendedores de comércio eletrônico turcos mais bem-sucedidos operam no Hepsiburada e no Trendyol simultaneamente. As duas plataformas têm pontos fortes diferentes:

Hepsiburada: Mais forte em eletrônicos, eletrodomésticos, B2B. Grupo demográfico mais velho e de maior renda
Trendyol: Mais forte em moda, beleza, mercearia. Grupo demográfico mais jovem e que prioriza os dispositivos móveis

Executar ambos no Odoo requer:

Inventário unificado: pool de estoque único alocado em ambas as plataformas com buffers de segurança
Preços específicos da plataforma: Diferentes taxas de comissão e dinâmica competitiva por plataforma
Acompanhamento de desempenho separado: cada plataforma tem seu próprio algoritmo de pontuação do vendedor
Relatórios consolidados: receita, margem e comparação de desempenho entre plataformas

O conector ECOSIRE suporta configuração Odoo multiplataforma e nosso guia de gerenciamento multimercado cobre a estratégia operacional em detalhes.

Serviços de Integração ECOSIRE

Serviços de integração Odoo da ECOSIRE fornecem suporte completo para vendedores Hepsiburada:

Implantação e configuração de conector ponta a ponta
Localização turca (KDV, contabilidade, fatura eletrônica)
Design de fluxo de trabalho de atendimento personalizado
Integração e otimização de transportadores de carga
Configuração de plataforma dupla (Hepsiburada + Trendyol de um Odoo)
Treinamento de pessoal e suporte contínuo

Navegue no catálogo de conectores de mercado da ECOSIRE para todas as integrações disponíveis.

Perguntas frequentes

Como a máquina de estado de pedido Hepsiburada funciona com o Odoo?

A Hepsiburada exige que os pedidos progridam através de estados específicos em sequência: Retirada, Faturado, Embalado, Enviado. O conector ECOSIRE automatiza esta máquina de estado dentro do fluxo de trabalho de processamento de pedidos do Odoo. Quando a equipe do armazém confirma a coleta, o conector gera automaticamente a fatura e, quando a entrega é criada com um número de rastreamento, o conector passa pelos estados Embalado e Enviado no Hepsiburada.

Posso executar Hepsiburada e Trendyol na mesma instância do Odoo?

Sim. O conector ECOSIRE suporta operação em vários mercados a partir de uma única instância Odoo. O inventário é gerenciado centralmente com regras de alocação por plataforma. Os pedidos de ambas as plataformas fluem para o fluxo de trabalho unificado de processamento de pedidos do Odoo, e a reconciliação financeira mantém as comissões e taxas de cada plataforma separadas para uma análise precisa da lucratividade.

Como a integração lida com o sistema de reclamações e disputas da Hepsiburada?

As reclamações do comprador da Hepsiburada são importadas para o módulo de helpdesk do Odoo com todos os detalhes relevantes (informações do pedido, tipo de reclamação, evidências do comprador). Sua equipe pode analisar reivindicações, enviar respostas com evidências e acompanhar os resultados da resolução — tudo dentro do Odoo. As métricas de reivindicação são alimentadas em seu painel de desempenho do vendedor para identificar e resolver problemas recorrentes.

O conector suporta a HepsiJet e outras empresas de carga turcas?

Sim. O conector se integra com HepsiJet, Yurtic Kargo, Aras Kargo, MNG Kargo, Surat Kargo e UPS Turkey. A atribuição da transportadora é baseada em regras (você configura regras para categoria de produto, peso, destino e urgência) e os números de rastreamento são enviados para Hepsiburada automaticamente a partir do módulo de entrega do Odoo.

Como são tratados os impostos turcos (KDV)?

O conector mapeia as categorias de produtos Hepsiburada para a taxa KDV correta (1%, 10% ou 20%). As faturas geradas no Odoo trazem os cálculos de impostos apropriados e a reconciliação de liquidação valida os valores dos impostos em relação aos registros da Hepsiburada. O formato de fatura eletrónica turca (e-Fatura) é suportado para conformidade regulamentar.

O que acontece se a chamada da API falhar durante a atualização do estado do pedido?

O conector implementa lógica de repetição com espera exponencial para falhas transitórias de API. Se uma atualização de estado falhar após novas tentativas, o pedido será sinalizado no Odoo para atenção manual e um alerta será enviado ao contato de operações configurado. O sistema rastreia métricas de confiabilidade da API para identificar problemas sistêmicos.

Quais versões do Odoo são suportadas?

O conector ECOSIRE Hepsiburada suporta Odoo 17, 18 e 19 (edições Community e Enterprise). Os recursos de localização em turco estão incluídos no módulo.

Conclusão

A combinação de tráfego massivo, confiança do consumidor construída ao longo de 25 anos e forte posicionamento da Hepsiburada em categorias de alto valor torna-a um canal de vendas essencial para qualquer vendedor que vise o mercado turco. A API estruturada da plataforma fornece uma base sólida para automação, mas a integração deve respeitar os requisitos específicos da Hepsiburada – a máquina de estado do pedido, o fluxo de trabalho da fatura antes do pacote, a integração da carga e o tratamento de reclamações, todos têm nuances específicas da plataforma.

Os vendedores que investem na integração Hepsiburada-Odoo adequada ganham uma vantagem acrescida: o processamento mais rápido de pedidos melhora as pontuações do vendedor, o que aumenta a visibilidade, o que gera mais pedidos – um ciclo virtuoso alimentado pela eficiência operacional. Aqueles que dependem de processos manuais descobrem o oposto: o processamento lento leva à degradação da pontuação, à redução da visibilidade e ao declínio das vendas.

O caminho a seguir é claro. Esteja você estabelecendo sua primeira presença Hepsiburada ou ampliando uma operação existente, conectar a plataforma ao seu ERP Odoo por meio do conector específico da ECOSIRE elimina o atrito operacional que limita o crescimento e corrói as margens.