Integração da API Hepsiburada com Odoo: Guia completo de configuração

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.

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)

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:

1. Separação: Confirme o recebimento do pedido e inicie o processamento do armazém
2. Faturado: Gerar e registrar fatura (obrigatório antes da embalagem)
3. Embalado: Crie um pacote com dimensões, peso e empresa de carga atribuída
4. 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

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

Etapa 2: Configuração do Odoo

1. Localização para a Turquia: Instale módulos de contabilidade, impostos e documentos específicos da Turquia
2. Moeda: Configure TRY com atualizações automatizadas da taxa de câmbio
3. Configuração KDV (IVA): Configure taxas de imposto (1%, 10%, 20%) por categoria de produto
4. Canal de vendas: Crie uma equipe de vendas "Hepsiburada"
5. Cliente: Crie um registro de cliente "Hepsiburada Marketplace"
6. Transportadoras: Configure a HepsiJet e empresas de carga aprovadas no módulo de entrega Odoo
7. 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:

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

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

6. Mapeie categorias de produtos para a taxonomia de Hepsiburada

Etapa 4: configuração da lista de produtos

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

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

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

Etapa 6: Configuração Financeira

1. Mapeie as taxas de comissão por categoria de produto
2. Configurar cronograma de importação de liquidação
3. Configure contas de despesas específicas para taxas
4. 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

---

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:

1. Inventário unificado: pool de estoque único alocado em ambas as plataformas com buffers de segurança
2. Preços específicos da plataforma: Diferentes taxas de comissão e dinâmica competitiva por plataforma
3. Acompanhamento de desempenho separado: cada plataforma tem seu próprio algoritmo de pontuação do vendedor
4. 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

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.