饿了么开放平台商品集成方案

文档说明

本文档面向对象为期望对饿了么店铺（仅单店，API不支持连锁店菜单管理）上的商品进行管理的第三方开发者或者自研商家，阅读此文档默认您已经完成开发者资质认证、应用创建和具备接口调用能力，如果还未完成，可以先阅读 新手指南。

背景介绍

商户的线下店铺或者ERP系统中的商品，想要与饿了么店铺上的商品进行同步管理，实现商品数据的双向打通，则需要理解饿了么上商品的模型定义，了解如何与线下店铺或者ERP系统中的商品进行关联管理，并且可以顺畅的将饿了么的商品模型映射到开发者的系统，商家就可以直接在ERP系统中完成商品的新增、删除、修改、查询等一系列操作，并会同步更新展示在消费者使用的饿了么客户端上，降低了商家维护多套系统商品的成本。

准备工作

先阅读 商品能力 说明文档，大致了解商品接口提供的能力。

对接场景

创建商品

每个商品都必须存在于某一分类下。新建商品可分为以下两种场景:

在已有分类下新建商品，涉及接口：查询店铺商品分类、添加商品、批量添加商品；

在新的分类下新建商品，涉及接口：添加商品分类。

删除商品

删除商品支持对商品分类和商品本身的删除，删除商品分类时分类下的所有商品均会被删除，请谨慎操作。

只删除商品，涉及接口：删除商品、批量删除商品

通过删除分类删除分类下的所有商品，涉及接口：删除商品分类

修改商品

修改商品信息需要注意的是：

如果是在更新商品时删除了商品规格会导致对应规格的销量一起删除，通过接口更新商品时请注意把商品规格ID填写完整。

调用更新商品接口更新商品时若规格ID不传则对应的商品规格销量会清零，不输入规格ID默认为删除老规格更新为新的规格，更新商品时请注意把商品信息填写完整。

涉及接口：更新商品、批量修改商品价格

查询商品

查询商品支持查询门店中的所有商品信息，并提供了不同纬度的查询，以快速获取所需要的信息。

查询商品，涉及接口：查询商品详情、批量查询商品详情、分页获取店铺下的商品

不同纬度查询商品，涉及接口：获取一个分类下的所有商品、根据商品条形码获取商品、根据商品扩展码获取商品、查询店铺活动商品

商品上下架

商品上下架支持批量操作，单次操作不得超过 50 条商品 ID 或是调用「eleme.product.item.updateItem」更新商品接口 onShelf = 1 代表上架，onShelf = 0代表下架 ，推荐使用批量上/下架接口

上架商品，涉及接口：批量上架商品

下架商品，涉及接口：删除下架商品

商品库存管理

商家在店铺实际经营的过程中根据自己的原材料配置情况做菜品库存的实时管理，可单个和批量更新商品库存，也可以根据需要直接快捷沽清或置满库存。

更新商品库存，涉及接口：批量更新商品库存，更新商品（调用此接口注意把接口内容商品信息其他相关字段值也上传完整，若不传对应的字段信息会被清空）

沽清库存，涉及接口：批量沽清商品

置满库存，涉及接口：批量置满库存

上传商品图片

添加商品接口需要通过 imageHash 字段上传商品图片，获取图片的hash值有两种方式：

通过 uploadImage 接口传入图片文件的base64编码值，返回图片的hash值；

通过 uploadImageWithRemoteUrl 接口传入远程图片的url地址，返回图片的hash值。接口调用流程如下：

上传图片，获取 imageHash 字段，涉及接口：上传图片，返回图片的hash值、通过远程URL上传图片，返回图片的hash值、获取上传图片的url地址

添加商品，涉及接口：添加商品、批量添加商品；

为商品添加原材料信息

添加商品时，原材料materials是一个必填字段，该字段下id 和 name的值必须通过接口“eleme.product.item.getItemMaterialTree 获取商品原材料数据”获取，一般情况下所有门店获取到的原材料一致，materials上传后会在用户端展示。接口调用流程如下：

获取商品原材料数据，涉及接口：获取商品原材料数据

添加商品，涉及接口：添加商品、批量添加商品；