Hepsiburada API 与 Odoo 集成：完整设置指南

土耳其的电子商务格局有两个占主导地位的平台，Hepsiburada 是每个认真的卖家都必须掌握的平台。 Hepsiburada 成立于 2000 年，是土耳其历史最悠久、最值得信赖的在线市场之一，每月访问量超过 1 亿次，卖家超过 65,000 名，产品目录涵盖从电子和时尚到汽车零部件和工业用品的各个消费类别。对于在 Odoo ERP 上运营的卖家来说，通过其强大的 API 与 Hepsiburada 集成是在土耳其市场实现高效、可扩展销售的途径。

要点

• Hepsiburada 每月访问量超过 1 亿次，是土耳其访问量最大的市场
• 该平台拥有 65,000 多名卖家，拥有 50 多万种产品列表
• Hepsiburada 于 2021 年在纳斯达克上市，展示机构级市场基础设施
• HepsiBurada API (HBAPI) 为产品、订单、库存和索赔提供全面的集成端点
• ECOSIRE 的连接器可处理土耳其本地化、KDV 税务合规性和多货物集成
• API 集成卖家的订单处理速度提高了 40%，库存错误减少了 90%

---

为什么 Hepsiburada 很重要

Trendyol 在时尚和日常订单量方面处于领先地位，而 Hepsiburada 在电子、家电、汽车和工业品类方面拥有明显优势。该平台在超过 25 年的运营中建立起来的消费者信任声誉为其拥有了与 Trendyol 受众重叠但又不同的忠实客户群。大多数成功的土耳其电子商务卖家都在这两个平台上运营，这使得 Hepsiburada 与 Trendyol 的集成成为标准要求。

Hepsiburada 统计（2025-2026）

Hepsiburada 的竞争地位

Hepsiburada 的与众不同之处在于：

• 信任：25 年的运营已经建立了深厚的消费者信任，特别是对于高价值购买
• 电子实力：消费电子、计算和移动设备市场份额领先
• HepsiJet 物流：内部物流网络，在主要城市提供当日送达服务
• HepsiPay：具有分期付款选项的集成支付系统（在土耳其分期付款驱动的市场中至关重要）
• 企业销售：用于企业采购的 B2B 市场部分
• Hepsiglobal：进入国际市场的跨境销售计划

---

Hepsiburada API (HBAPI) 深入探究

Hepsiburada 提供结构良好的 REST API，可实现全面的卖家集成。 API 文档以英语提供（与某些土耳其平台 API 不同），可供国际开发团队使用。

API架构

HBAPI 被组织成服务域：

挂牌服务

• 创建具有完整属性集的产品列表
• 管理变体（颜色、尺寸、型号、容量）
• 处理图像上传和排序
• 映射到 Hepsiburada 的类别分类
• 管理列表状态（主动、被动、锁定）
• 处理条形码 (GTIN/EAN) 要求

订单服务

• 检索新订单（可打包订单）
• 访问订单详细信息（行项目、数量、地址）
• 更新订单行状态（提货、开具发票、发货）
• 创建包裹并指定货运公司
• 处理部分履行（首先运送可用物品）

库存服务

• 更新每个仓库每个列表的库存数量
• 设置可用性状态
• 处理多仓库库存分配

理赔服务

• 处理买家索赔（商品错误、损坏、丢失）
• 提交带有证据的索赔回复
• 跟踪索赔结果和财务影响

金融服务

• 访问结算报告
• 查看佣金明细
• 跟踪罚款和调整扣除
• 下载发票和财务文件

身份验证

HBAPI 使用 HTTP 基本身份验证，并通过 Hepsiburada 商户面板提供商户 ID、用户名和密码。为了安全起见，某些端点需要额外的 IP 白名单。

速率限制和最佳实践

• 标准速率限制：每个端点每分钟 100 个请求
• 库存更新：建议批量操作（每个请求最多 100 个 SKU）
• 订单轮询：建议每 10 分钟一次
• 产品创建：高峰期每小时仅限 500 个新列表

---

集成架构

订单处理管道

Hepsiburada 的订单生命周期与其他市场略有不同。订单通过特定的状态机：

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

集成必须遵守此状态机 - 跳过状态或不按顺序更新会导致 API 错误和潜在的订单处理失败。

组件 1：产品列表集成

在 Hepsiburada 上创建和管理列表需要注意平台特定的要求：

• 类别属性：每个类别都有强制属性和可选属性。电子产品需要品牌、型号、技术规格和保修期。时尚需要尺码表、材质和保养说明
• 条形码要求：所有实体产品必须具有有效的 GTIN/EAN 条形码。集成必须在提交之前验证条形码格式
• 图片要求：最小 500x500 像素，主图片白色背景，每个列表最多 8 张图片
• 品牌验证：品牌必须在 Hepsiburada 上获得批准，然后产品才能上市。集成应在尝试创建列表之前检查品牌批准状态
• 内容语言：国内市场的所有列表内容都必须使用土耳其语

该连接器将 Odoo 产品数据映射到 Hepsiburada 的列表格式、验证强制属性并处理图像格式转换。

组件 2：订单导入和状态管理

连接器轮询 HBAPI 以获取新的可打包订单，并使用以下命令创建 Odoo 销售订单：

• 完整的产品和变体映射
• 客户送货地址
• 用于状态更新跟踪的订单级和行级 ID
• 付款方式信息
• 交付SLA要求

状态更新遵循 Hepsiburada 所需的顺序：

1. 拣货：确认订单接收并开始仓库处理 2.开票：生成并登记发票（打包前需要）
2. 包装：创建包含尺寸、重量和指定货运公司的包裹
3. 已发货：推送货物追踪号码

每个状态转换都会使用适当的数据调用 HBAPI，并且连接器会处理瞬时故障的重试。

第 3 部分：库存管理

库存可用性通过批量 API 调用从 Odoo 推送到 Hepsiburada：

• 每个 SKU 的库存数量每 15-30 分钟更新一次
• 适用于多渠道卖家的安全缓冲
• Hepsiburada 上的零库存商品自动停用
• 库存恢复触发自动重新激活

协调 Hepsiburada 库存与其他销售渠道需要采用我们的实时库存同步指南 中描述的集中方法。

第 4 部分：货物和物流

Hepsiburada 支持多种货物选项：

• HepsiJet：Hepsiburada自有物流网络（主要城市当日送达）
• Yurtic Kargo：土耳其最大的货运公司
• Aras Kargo：覆盖全国，价格具有竞争力
• MNG Kargo：在企业和大件物品运输方面实力雄厚
• 苏拉特货运：标准交付的预算友好型选择
• UPS 土耳其：适用于国际和优质递送

该连接器与 Odoo 的运输模块集成，根据可配置的规则（产品类别、目的地、重量、紧急程度）分配适当的承运人，并将跟踪信息推送到 Hepsiburada。

第 5 部分：索赔和售后

Hepsiburada 的索赔系统处理买家纠纷：

• 错误的商品：买家收到的产品与订购的产品不同
• 损坏：产品到达时已损坏
• 缺少物品：订单交付不完整
• 质量：产品与列表描述不符

该连接器将索赔导入 Odoo 的帮助台模块，使您的客户服务团队能够审查证据、提交响应并跟踪结果 - 所有这些都在 Odoo 内进行。索赔解决质量会影响卖家评分，因此高效处理至关重要。

第 6 部分：财务结算

每两周一次的结算包括：

• 每个订单行的总销售收入
• 特定类别佣金 (6-18%)
• HepsiJet物流费
• 服务费（挂牌、交易）
• 罚金扣除（延迟发货、取消、索赔损失）
• 促销贡献

该连接器为每个结算组件创建详细的日记帐分录，从而在 Odoo 中实现准确的每个产品和每个类别的盈利能力分析。

---

设置指南

第 1 步：Hepsiburada 商户账户

1. 在 Hepsiburada 商户面板注册
2. 完成身份和税务验证
3. 请求 API 访问并接收凭据（商户 ID、用户名、密码） 4.提交API访问IP白名单
4. 为您的产品品牌申请品牌批准

步骤 2：Odoo 配置

1. 土耳其本地化：安装土耳其特定的会计、税务和文档模块
2. 货币：使用自动汇率更新配置 TRY
3. KDV (VAT) 设置：配置每个产品类别的税率（1%、10%、20%）
4. 销售渠道：创建“Hepsiburada”销售团队
5. 客户：创建“Hepsiburada Marketplace”客户记录
6. 承运商：在 Odoo 交付模块中配置 HepsiJet 和认可的货运公司
7. 账户：创建佣金、物流费和罚款的费用账户

步骤 3：安装 ECOSIRE 连接器

部署 ECOSIRE Hepsiburada 连接器：

1.通过Odoo Apps安装 2. 导航至设置 > Hepsiburada 集成 3. 输入商户ID、API用户名和密码 4. 根据需要配置IP白名单 5. 设置同步间隔：

• 订单：每 10 分钟一班
• 库存：每 15 分钟一次
• 产品：每 4 小时或手动

6. 将产品类别映射到 Hepsiburada 的分类法

步骤 4：产品列表配置

1. 将 Odoo 产品映射到具有强制属性的 Hepsiburada 类别
2. 验证所有产品的 GTIN/EAN 条形码
3. 准备土耳其语产品内容 4.上传合规的产品图片
4. 设置 TRY 定价并考虑佣金利润
5. 同步初始目录并监控列表批准

第 5 步：订单工作流程设置

1.配置订单导入和状态管理 2. 设置Hepsiburada订单的仓库分配规则 3. 配置发票生成（在 Hepsiburada 流程中打包之前需要） 4. 设置货物分配规则 5. 测试端到端订单处理

第 6 步：财务设置

1. 绘制每个产品类别的佣金率
2. 配置结算导入时间表
3. 设立特定费用费用账户
4. 定义微小差异的调节容差

---

Hepsiburada 特定的挑战

挑战 1：包装前发票要求

Hepsiburada 要求卖家在创建运输包裹之前生成发票，这一顺序与大多数市场中发票在运输之后或同时发生的顺序不同。

解决方案：连接器自动执行 Odoo 中的发票生成步骤，在确认提货后立即创建并注册发票。这可确保始终遵循正确的状态顺序（提货 > 已开票 > 已包装 > 已发货）。

挑战2：分期付款文化

土耳其有着浓厚的分期付款文化——消费者经常分 3、6、9 或 12 个月分期付款。虽然 Hepsiburada 和 HepsiPay 管理消费者分期付款关系，但卖家根据正常结算条款收到全额付款（减去​​佣金）。

解决方案：无论消费者的分期计划如何，连接器都会在 Odoo 中正确记录全额付款金额。记录分期付款结构仅供参考，但不会影响卖方的会计处理。

挑战3：Hepsiglobal跨境复杂性

Hepsiburada 的 Hepsiglobal 计划支持跨境销售，引入多货币定价、国际运输物流和海关文件要求。

解决方案：该连接器支持 Hepsiglobal，为每个目标市场提供单独的定价配置、国际运营商集成以及通过 Odoo 生成海关文档。

挑战 4：电子行业的激烈竞争

电子产品是 Hepsiburada 最强的类别，但也是最具竞争力的类别。价格敏感度极高，Buy Box 竞争需要实时的定价响应能力。

解决方案：连接器支持根据竞争地位和利润下限进行调整的定价规则。对于竞争激烈的类别，可以更频繁地触发定价更新，同时保持盈利能力。

挑战 5：季节性需求激增

土耳其电子商务的需求在 11.11（双十一）、黑色星期五和斋月前购物期间出现大幅增长。在这些活动期间，订单量可能会增加 3-5 倍。

解决方案：该连接器支持峰值模式配置，具有更高的同步频率、更大的安全缓冲区和自动容量警报。活动前检查表可确保在需求激增之前准备好库存、定价和履行能力。

---

手动与 ECOSIRE 连接器

---

双平台策略：Hepsiburada + Trendyol

大多数成功的土耳其电子商务卖家同时在 Hepsiburada 和 Trendyol 上运营。这两个平台有不同的优势：

• Hepsiburada：在电子、电器、B2B 领域更强。年龄较大、收入较高的人群
• Trendyol：在时尚、美容、杂货方面更强。年轻、移动优先的人群

从 Odoo 运行两者都需要：

1. 统一库存：跨两个平台分配单一库存池，并具有安全缓冲区
2. 特定平台定价：每个平台不同的佣金率和竞争动态
3. 单独的绩效跟踪：每个平台都有自己的卖家评分算法
4. 综合报告：跨平台收入、利润率和业绩比较

ECOSIRE连接器支持多平台Odoo配置，我们的多市场管理指南详细介绍了运营策略。

---

ECOSIRE 集成服务

ECOSIRE 的 Odoo 集成服务 为 Hepsiburada 卖家提供全面支持：

• 端到端连接器部署和配置
• 土耳其语本地化（KDV、会计、电子发票）
• 定制履行工作流程设计
• 货运公司整合与优化
• 双平台设置（来自一个 Odoo 的 Hepsiburada + Trendyol）
• 员工培训和持续支持

浏览 ECOSIRE 的市场连接器目录 了解所有可用的集成。

---

常见问题

连接器是否支持 HepsiJet 和其他土耳其货运公司？

是的。该连接器与 HepsiJet、Yurtic Kargo、Aras Kargo、MNG Kargo、Surat Kargo 和 UPS Turkey 集成。承运商分配是基于规则的（您可以配置产品类别、重量、目的地和紧急程度的规则），并且跟踪号码会自动从 Odoo 的交付模块推送到 Hepsiburada。

土耳其税（KDV）如何处理？

连接器将 Hepsiburada 产品类别映射到正确的 KDV 率（1%、10% 或 20%）。 Odoo 中生成的发票包含适当的税务计算，结算对账根据 Hepsiburada 的记录验证税额。支持土耳其电子发票 (e-Fatura) 格式以符合法规要求。

如果订单状态更新期间API调用失败会发生什么？

连接器针对暂时性 API 故障实施具有指数退避功能的重试逻辑。如果重试后状态更新失败，订单会在 Odoo 中标记为需要手动关注，并向配置的操作联系人发送警报。系统跟踪 API 可靠性指标以识别系统问题。

支持哪些 Odoo 版本？

ECOSIRE Hepsiburada 连接器支持 Odoo 17、18 和 19（社区版和企业版）。土耳其语本地化功能与该模块捆绑在一起。

---

结论

Hepsiburada 拥有庞大的流量、超过 25 年建立的消费者信任以及在高价值类别中的强大定位，使其成为任何瞄准土耳其市场的卖家的重要销售渠道。该平台的结构化 API 为自动化提供了坚实的基础，但集成必须尊重 Hepsiburada 的特定要求 - 订单状态机、包装前发票工作流程、货物集成和索赔处理都具有特定于平台的细微差别。

投资适当的 Hepsiburada-Odoo 集成的卖家可以获得复合优势：更快的订单处理可以提高卖家分数，从而提高可见性，从而推动更多订单——这是一个由运营效率驱动的良性循环。那些依赖手动流程的人发现了相反的情况：处理缓慢会导致分数下降、可见性降低和销售额下降。

前进的道路是明确的。无论您是要建立第一个 Hepsiburada 业务还是扩大现有运营规模，通过 ECOSIRE 的专用连接器 将平台连接到您的 Odoo ERP 都可以消除限制增长和侵蚀利润的运营摩擦。