商户开放API

商户需要先登录到控制台->开发者, 获取商户开发者Secret才能调用本系列API。

介绍

请求方式

HOST: https://open.idatariver.com
Headers: Authorization: Bear Your_Developer_Secret

多语言支持

平台支持自动将商户的项目/商品信息翻译为多国语言, 如果需要获取指定语言版本, 只需要在Headers里传递X-Idr-Locale字段。

接口会将自动翻译的结果存放在nameI18n与descI18n字段里。

目前自动翻译包括项目/商品的name和desc字段。

X-Idr-Locale	语言
en	🇬🇧 English
fa	🇮🇷 فارسی
zh-cn	🇨🇳 简体中文
ja	🇯🇵 日本語
ru	🇷🇺 Русский
zh-hk	🇭🇰 繁体中文
de	🇩🇪 Deutsche
ar	🇦🇪 العربية
es	🇪🇸 Español
fr	🇫🇷 Français
ko	🇰🇷 한국어
tr	🇹🇷 Türkçe
uk	🇺🇦 Українська
uz	🇺🇿 O'zbekcha
kk	🇰🇿 Қазақша
pl	🇵🇱 Polski
pt	🇵🇹 Português
pa	🇮🇳 ਪੰਜਾਬੀ

请求示例

GET请求POST请求

shell

curl https://open.idatariver.com/mapi?key=value \
  -H "Authorization: Bearer $iDataRiver_Merchant_Secret" \
  -H "X-Idr-Locale: zh-cn" \

shell

curl https://open.idatariver.com/mapi \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $iDataRiver_Merchant_Secret" \
  -H "X-Idr-Locale: zh-cn" \
  -d '{
    "key": "value"
  }'

返回格式

为了更好的统一管理维护API，API均按照以下字段格式返回

字段名称	描述
code	(必填)返回码，整数类型，根据此字段判断返回业务状态，详细含义见下方表格
result	(可选)完整的原始返回结果，其字段结构与解释应由供应商提供
msg	(可选)请求失败原因

返回码解释

code字段的含义与解释

code	描述
0	请求成功
1000	内部错误
1001	参数错误
1002	请求资源不存在
1003	内部处理较忙，请稍后重试
1004	权限不足

接口文档

使用场景

开放API分为公开API与私密API，区别如下:

公开API一般是由用户触发调用的，比如下单，查看商家主页的商品信息等，适合放在独立站前端使用。

私密API只应该由商家自己使用，用于访问或管理商户核心数据，适合后端处理商户数据管理。

即便是公开API也不应该 直接 在前端暴露调用方式，以免泄漏商户密钥。

商户店铺基础信息公开

返回商户基础信息。

GET /mapi/merchant/basicInfo

返回核心字段说明

字段	类型	描述
name	string	商家名称
desc	string	商家简介
contacts	object	商家联系方式
website	object	独立站配置

商户主页信息公开

返回商户项目列表，以及项目下的所有商品信息。

GET /mapi/merchant/info

返回核心字段说明

示例

字段	类型	描述
name	string	商家名称
desc	string	商家简介
contacts	object	商家联系方式
guarantee	number	商家保证金
projects	array	已上架的项目列表, 内部字段可参考项目详情接口
website	object	独立站配置

获取订单详情公开

根据订单id获取订单详细信息。

GET /mapi/order/info

字段	类型	是否必填	描述
id	string	是	订单id

返回核心字段说明

示例

字段	类型	描述
id	string	订单id
skuName	string	商家名称
status	string	订单状态, 可取值为: `NEW`(新订单), `DONE`(已支付), `EXPIRED`(过期未支付), `REFUND`(已退款)
quantity	number	下单数量
projectName	string	项目名称
projectType	string	项目类型
merchant	string	商家id
oriPrice	number	订单原价
price	number	订单实际支付价格(会扣除代金券优惠)
affCode	string	订单推广id, 需开通代理商功能后使用
anonymous	bool	是否是匿名下单
consumer	string	消费者在iDataRiver的用户id, 匿名下单时为空
contactInfo	string	消费者匿名支付时留下的查询信息, 任何人可用此字段查询订单
coupon	string	优惠券码
paymentFeeCovered	bool	是否由商家承担此订单的支付通道费用
dt	string	订单创建日期
createdAt	string	订单创建时间(UTC+0时区)
createdTS	string	订单创建时间戳
digitalItemsStr	string	当订单支付完成后, 返回用户购买的数字内容
expiredInterval	number	订单支付有效期
mContacts	object	商家联系方式
mPayments	array	订单支付方式(仅显示当前可用的支付通道)
mPayments[*].enabled	bool	当前支付通道是否开启
mPayments[*].isPlatform	bool	是否是平台内置支付
mPayments[*].name	string	支付通道名称
mPayments[*].desc	string	支付通道描述信息
mPayments[*].method	string	支付通道id, 平台内置支付通道可取值为: `credits`(平台余额支付), `crypto`(加密货币), `alipay`(支付宝), `wxpay`(微信支付), `onramp`(Visa/Mastercard), `onramp-google`(Google Pay), `onramp-apple`(Apple Pay), `onramp-revolut`(Revolut), `onramp-venmo`(Venmo), `gcash` (GCash)
mPayments[*].ratioRange	string	支付通道收取百分比费率
mPayments[*].fixedFeeRange	string	支付通道收取固定费用(USD)
project	object	项目信息, 内部字段解释请参考项目详情接口
sku	object	商品信息, 内部字段解释请参考商品详情接口

创建商品订单公开

商品下单。

POST /mapi/order/add

字段	类型	是否必填	描述
projectId	string	是	项目id, 你可以在`获取全部项目`接口里获取项目的id字段
skuId	string	是	商品id
orderInfo	object	是	商品下单明细, 示例: `{"quantity": 1,"coupon": "","contactInfo": "","affCode":""}`, 其中`quantity`为下单数量, `coupon`为优惠券(没有请传空字符串), `contactInfo`为联系方式(必填), 用户可通过此值找回订单, 字符长度为`5-100`, `affCode`是代理商推广码(选填)。

针对BUYMEABTC项目, 不需要传skuId字段, orderInfo字段格式如下:

{"amount":5, "private": false, "name": "", "message": ""}

amount赞助金额, 单位usd
private是否公开赞助信息
name昵称，可为空
message留言消息，可为空

返回核心字段说明

字段	类型	描述
orderId	string	订单id

支付商品订单公开

获取订单支付跳转链接。

如果订单价格为0，将直接购买成功并且不返回支付链接。

对于使用支付宝/微信支付场景, 应该添加以下提示语: 【如果无法打开支付页面, 请关闭VPN或切换网络。】

POST /mapi/order/pay

字段	类型	是否必填	描述
id	string	是	订单id
method	string	是	支付method, 来自于订单详情接口字段`mPayments`里的的`method`值
redirectUrl	string	否	支付成功后的重定向链接, 应该指向订单页面, 需要包含完整域名
callbackUrl	string	否	订单支付成功或退款时触发的后端回调通知, 会将订单数据以post请求(json格式)发送给此链接, 请在5秒内处理完毕并返回200/201状态码, 否则会认为回调失败, 回调失败时会进行重试(最多5次)。此url必须使用域名https，不能通过ip访问

回调检查

callbackUrl回调的订单数据字段请参考订单详情api。

你可以通过回调订单的status字段判断当前订单是已支付还是已退款。

在使用回调功能接受到订单通知时, 请主动请求一次订单信息对订单真实状态进行确认。

这样可以避免商家的callbackUrl被漏泄时, 来自第三方的恶意回调。

需要注意: 此处回调优先级高于商家设置的事件钩子。

返回核心字段说明

字段	类型	描述
payUrl	string	支付链接
payCurrency	string	支付货币
amount	number	支付金额

查询商品订单列表公开

根据创建订单时留下的联系方式或订单id，查询订单列表。

GET /mapi/order/search

字段	类型	是否必填	描述
query	string	是	下单留的联系方式或者订单号

返回核心字段说明

字段	类型	描述
items	array	订单列表
items[*].id	string	订单id
items[*].price	string	订单价格
items[*].quantity	string	下单数量
items[*].skuName	string	商品名称
items[*].status	string	订单状态
items[*].date	string	订单创建日期(UTC+0时区)

获取商家订单列表私密

按时间倒序获取商家的订单列表。

GET /mapi/order/list

字段	类型	是否必填	描述
status	string	否	订单状态, 默认为空表示不筛选状态, 可取值: `DONE`(已完成), `NEW`(新订单), `EXPIRED`(已过期), `REFUND`(已退款)
page	string	否	翻页参数, 默认为1, 每次翻页+1

返回核心字段说明

字段	类型	描述
hasMore	bool	是否需要翻页
items	array	订单列表
items[*].id	string	订单id
items[*].price	string	订单价格
items[*].quantity	string	下单数量
items[*].skuName	string	商品名称
items[*].status	string	订单状态
items[*].payMethod	string	已完成订单的付款方式
items[*].payTo	string	可取值为 `platform`由平台代收, `merchant`直接支付给商家自定义收款
items[*].platformFee	number	平台服务费
items[*].paymentFee	number	支付通道费
items[*].paymentFeeCovered	bool	支付通道费是否由商家承担
items[*].profit	number	由平台代收时, 扣除所有手续费后的商家净收益
items[*].date	string	订单创建日期(UTC+0时区)

获取全部项目私密

返回商家创建的所有项目，包括未上线状态项目。

GET /mapi/project/list

返回核心字段说明

示例

字段	类型	描述
projects	array	项目列表
projects[*].id	string	项目id
projects[*].type	string	项目类型
projects[*].status	string	项目状态
projects[*].cover	string	封面图, 返回图片链接或base64图片数据
projects[*].name	string	项目名称
projects[*].nameI18n	object	项目名称(多语言)
projects[*].desc	string	项目描述
projects[*].descI18n	object	项目描述(多语言)
projects[*].i18nType	number	`0`开启自动翻译、`1`不翻译
projects[*].owner	string	商户id
projects[*].seoPath	string	项目链接路径
projects[*].slug	string	项目短id
projects[*].createdTS	string	项目创建时间戳
projects[*].createdAt	string	项目创建时间
projects[*].updatedAt	string	项目更新时间

获取指定项目私密

获取项目包含的所有数据，包括商品列表，定价列表，优惠券列表。

并且数字商品会返回所有库存数据。

GET /mapi/project/detail

字段	类型	是否必填	描述
id	string	是	项目id

返回核心字段说明

示例

字段	类型	描述
id	string	项目id
type	string	项目类型
status	string	项目状态
cover	string	封面图, 返回图片链接或base64图片数据
name	string	项目名称
nameI18n	object	项目名称(多语言)
desc	string	项目描述
descI18n	object	项目描述(多语言)
i18nType	number	0开启自动翻译、1不翻译
owner	string	商户id
seoPath	string	项目链接路径
slug	string	项目短id
createdTS	string	项目创建时间戳
createdAt	string	项目创建时间
updatedAt	string	项目更新时间
affiliates	array	代理商列表
affiliates[*].id	string	id
affiliates[*].userId	string	带货商家在平台的商家id
affiliates[*].code	string	代理商推广码
affiliates[*].name	string	代理商名称
affiliates[*].ratio	number	分成比例
affiliates[*].totalAmount	number	总带货金额
affiliates[*].settledAmount	number	已结算金额
affiliates[*].settledProfit	number	已结算利润
affiliates[*].lastSettleAt	string	最近一次结算日期
affiliates[*].lastSettleTS	string	最近一次结算时间戳
coupons	array	优惠券列表
coupons[*].id	string	id
coupons[*].status	string	优惠券状态
coupons[*].code	string	优惠码
coupons[*].scope	string	优惠范围, 可取值为: `globle`(所有商品生效), `specific`(指定商品生效)
coupons[*].policy	string	优惠策略, 可取值为: `reduction`(降价), `fixed`(一口价), `discount`(打折券)
coupons[*].fixed	number	一口价优惠的金额, 仅`policy`=`fixed`有意义
coupons[*].discount	number	打折券的折扣比例, 仅`policy`=`discount`有意义
coupons[*].capped	number	降价金额, 仅`policy`=`reduction`有意义
coupons[*].usedNum	number	已使用次数
coupons[*].scopeItems	array	`scope`=`specific`时, 指定生效的商品id列表
pricings	array	定价计划列表
pricings[*].id	string	id
pricings[*].status	string	优惠券状态
pricings[*].scope	string	优惠范围, 可取值为: `globle`(所有商品生效), `specific`(指定商品生效)
pricings[*].policy	string	优惠策略, 可取值为: `fixed`(固定价), `stage_quantity`(按购买数量阶梯优惠), `stage_rpd`(API业务使用, 按接口每日调用次数阶梯优惠), `dynamic`(API业务使用, 每次调用都动态计价)
pricings[*].price	number	`policy`=`fixed`时的定价金额
pricings[*].stages	array	阶梯定价规则
pricings[*].dynamicCapped	number	`policy`=`dynamic`时允许的最大金额, 默认不超过0.2usd
pricings[*].scopeItems	array	`scope`=`scopeItems`时, 指定生效的商品id列表
skus	array	商品/SKU列表
skus[*].id	string	商品id
skus[*].status	string	商品上架状态
skus[*].priority	number	商品展示优先级, 值越小优先级越高
skus[*].sold	number	销量
skus[*].pricingScope	string	可取值`global`或`specific`, 表示价格是全局定价还是指定定价
skus[*].docLink	string	商品外部描述文档链接
skus[*].stock	number	库存
skus[*].name	string	商品名称
skus[*].nameI18n	object	商品名称(多语言)
skus[*].desc	string	商品描述
skus[*].descI18n	object	商品描述(多语言)
skus[*].hiddenStock	bool	是否隐藏库存
skus[*].itemType	string	当`type`=`DIGITAL`时, 可取值为`reuse`(重复销售), `consumable`(售后删档)
skus[*].items	array	当`type`=`DIGITAL`时, 所有数据项
skus[*].itemsNum	string	当`type`=`DIGITAL`时, 数据项数量

新建项目私密

创建一个新项目。

POST /mapi/project/add

字段	类型	是否必填	描述
name	string	是	项目名称
type	string	是	项目类型, 目前支持数字商品:DIGITAL

返回核心字段说明

字段	类型	描述
id	string	项目id

修改项目信息私密

修改项目基础信息。

POST /mapi/project/update

字段	类型	是否必填	描述
id	string	是	项目id, 可从项目列表接口获取
name	string	是	项目名称, 字数不超过50
status	string	是	项目状态, 可选值: `ONLINE`, `OFFLINE`
i18nType	string	否	自动翻译状态, 可选值: 开启-`0`, 关闭-`1`, 默认为`1`
desc	string	否	项目描述, 字数不超过500
cover	string	否	图片base64编码, 不得超过`2Mb`, 仅支持`PNG`、`JPG`、`JPEG`格式, 样例:`data:image/jpeg;base64,/9j/4AAQSkZJRgABAQAAkACQAAD...`

删除项目(不可撤销) 私密

删除项目。

POST /mapi/project/remove

字段	类型	是否必填	描述
project	string	是	项目id

获取单个商品/SKU详情私密

获取项目下指定商品的详细信息，数字商品将返回数据项。

GET /mapi/project/sku/detail

字段	类型	是否必填	描述
id	string	是	商品/SKU id

返回核心字段说明

示例

字段	类型	描述
id	string	商品id
status	string	项目状态
name	string	项目名称
nameI18n	object	项目名称(多语言)
desc	string	项目描述
descI18n	object	项目描述(多语言)
owner	string	商户id
project	string	项目id
priority	number	商品展示优先级, 值越小优先级越高
sold	number	销量
docLink	string	商品外部描述文档链接
stock	number	库存
hiddenStock	bool	是否隐藏库存
itemType	string	当`type`=`DIGITAL`时, 可取值为`reuse`(重复销售), `consumable`(售后删档)
items	array	当`type`=`DIGITAL`时, 所有数据项
itemsNum	string	当`type`=`DIGITAL`时, 数据项数量
order	object	下单相关字段
createdTS	string	项目创建时间戳
createdAt	string	项目创建时间
updatedAt	string	项目更新时间

新增项目商品/SKU 私密

在指定项目下增加一个商品。

POST /mapi/project/sku/add

字段	类型	是否必填	描述
projectId	string	是	项目id

返回核心字段说明

字段	类型	描述
id	string	商品id

更新商品/SKU 私密

更新商品信息。

修改数字商品库存数据时，会使用新的数据直接覆盖原来的库存数据项。

因此如果要更改数字商品的库存数据项，请先将商品下架，以防止导致与正在购买的订单产生冲突。

POST /mapi/project/sku/update

字段	类型	是否必填	描述
id	string	是	商品/SKU id
name	string	否	商品名称, 字数不大于50
status	string	否	商品状态, 可选值: `ONLINE`, `OFFLINE`
priority	number	否	商品优先级, 取值范围为`1-100`
itemType	string	否	数据项类型, 可取值: 重复出售-`reuse`、售后删档-`consumable`
items	array	否	数字商品的数据项, 每一个元素均对应一个卡密, 例如:`["123", "456"]`, 必须同时传递`itemType`参数。 🔔 此值会直接覆盖原来的卡密, 请谨慎调用
docLink	string	否	外部文档链接
hiddenStock	bool	否	是否隐藏库存, 取值 `true`或`false`
desc	string	否	项目描述, 字数不大于500

更新商品时，至少保证有一个有效字段需要更新，否则会返回失败。

删除商品/SKU 私密

永久删除商品，无法撤销。

POST /mapi/project/sku/remove

字段	类型	是否必填	描述
id	string	是	商品/SKU id

新增定价计划私密

添加一个定价计划。

POST /mapi/project/pricing/add

字段	类型	是否必填	描述
projectId	string	是	项目id

返回核心字段说明

字段	类型	描述
id	string	定价计划id

更新定价计划私密

修改定价计划。

POST /mapi/project/pricing/update

字段	类型	是否必填	描述
id	string	是	定价计划id
status	string	是	商品状态, 可选值: `ONLINE`, `OFFLINE`
scope	string	是	商品状态, 可选值: 全局-`global`, 指定范围-`specific`
scopeItems	array	否	当`scope`=`specific`时, 此数组元素为需要生效的商品id, 且不能为空
policy	string	是	定价策略, 可选值: 固定价-`fixed`, 批发价-`stage_quantity`
price	string	否	固定价格, 当`policy`=`fixed`时, 需要传此参数
stages	object	否	批发价设置, 当`policy`=`stage_quantity`时, 需要传此参数, 示例: `[{ "threshold": 0, 'price': 10 },{ "threshold": 10, 'price': 8 }]`表示购买数量小于10个的单价为10usd, 大于等于10个的单价为8usd, 最多设置5个阶梯

删除定价计划私密

永久删除定价计划，无法撤销。

请保证商品至少有一个可用的定价计划。

POST /mapi/project/pricing/remove

字段	类型	是否必填	描述
id	string	是	定价计划id

新增优惠券私密

添加一个优惠券。

POST /mapi/project/coupon/add

字段	类型	是否必填	描述
projectId	string	是	项目id

返回核心字段说明

字段	类型	描述
id	string	优惠券id

更新优惠券私密

修改优惠券规则。

POST /mapi/project/coupon/update

字段	类型	是否必填	描述
id	string	是	优惠券id
status	string	是	商品状态, 可选值: `ONLINE`, `OFFLINE`
scope	string	是	商品状态, 可选值: 全局-`global`, 指定范围-`specific`
scopeItems	array	否	当`scope`=`specific`时, 此数组元素为需要生效的商品id, 且不能为空
policy	string	是	定价策略, 可选值: 减价券-`reduction`, 打折券-`discount`, 一口价券-`fixed`
reduction	number	否	减价券的金额, 当`policy`=`reduction`时, 需要传此参数
fixed	number	否	一口价券金额, 当`policy`=`fixed`时, 需要传此参数
discount	number	否	打折券比例, 取值范围`1-100`, 当`policy`=`discount`时, 需要传此参数
capped	number	否	打折券优惠上限, 当`policy`=`discount`时, 可以通过传此参数控制最多优惠的金额数量

删除优惠券私密

永久删除优惠券，无法撤销。

POST /mapi/project/coupon/remove

字段	类型	是否必填	描述
id	string	是	优惠券id

telegram机器人群发消息私密

此功能需要商家先开通了自定义telegram机器人, 商家也可以直接在商城应用Telegram群发助手使用。

添加一条telegram广播消息，使用商家自定义的telegram机器人发送。

🔔 本接口不限制群发消息次数，但是同一时间只能有一条正在群发的消息，必须等待上一条群发处理完后才能继续群发。

强烈建议合理使用此功能，每次群发会自动剔除无效用户。

POST /mapi/rainbow/broadcast/add

字段	类型	是否必填	描述
content	string	是	群发文本内容, 长度不能超过4000
test	bool	是	是否为测试模式, 传`true`表示只给商家绑定的账号发送(常用于正式群发前的效果测试), 传`false`表示群发给所有可接收消息的用户

获取telegram机器人历史群发记录私密

获取近期telemgram机器人群发的历史记录，包括返回群发用户总数、拒收用户、发送成功数量、执行总时长

GET /mapi/rainbow/broadcast/list

返回核心字段说明

示例

字段	类型	描述
items	array	群发记录列表
items[*].id	string	全局唯一id
items[*].eid	string	业务唯一id(用于除重)
items[*].status	string	执行状态
items[*].params	object	群发参数
items[*].createdTS	string	创建时间戳
items[*].createdAt	string	创建时间

查询License授权码公开

查询License详情。

GET /mapi/license/query

字段	类型	是否必填	描述
code	string	是	授权码, 支持同时传入多个(使用逗号分隔), 一次最多传100个

返回核心字段说明

字段	类型	描述
items	array	成功激活的授权码列表
items[*].license	string	授权码
items[*].status	string	授权码状态
items[*].states	string	业务参数
items[*].order	string	订单id
items[*].merchant	string	商家id
items[*].skuName	string	商品名称
items[*].createdTS	string	创建时间戳
items[*].createdAt	string	创建时间
items[*].activateTS	string	创建时间戳
items[*].activateAt	string	创建时间

激活License授权码私密

将License商品售出的授权码标记为已使用状态, 此过程不可逆。

授权码只能激活一次, 授权码在被使用后商家应该调用此接口进行激活处理, 防止被重复使用。

POST /mapi/license/activate

字段	类型	是否必填	描述
code	string	是	授权码, 支持同时传入多个(使用逗号分隔), 一次最多传100个

返回结果里会包含成功激活的授权码信息。

返回核心字段说明

字段	类型	描述
items	array	成功激活的授权码列表
items[*].license	string	授权码
items[*].status	string	授权码状态
items[*].states	string	业务参数
items[*].order	string	订单id
items[*].merchant	string	商家id
items[*].skuName	string	商品名称
items[*].createdTS	string	创建时间戳
items[*].createdAt	string	创建时间
items[*].activateTS	string	创建时间戳
items[*].activateAt	string	创建时间

商户开放API ​

介绍 ​

请求方式 ​

多语言支持 ​

请求示例 ​

返回格式 ​

返回码解释 ​

接口文档 ​

商户店铺基础信息 公开 ​

商户主页信息 公开 ​

获取订单详情 公开 ​

创建商品订单 公开 ​

支付商品订单 公开 ​

查询商品订单列表 公开 ​

获取商家订单列表 私密 ​

获取全部项目 私密 ​

获取指定项目 私密 ​

新建项目 私密 ​

修改项目信息 私密 ​

删除项目(不可撤销) 私密 ​

获取单个商品/SKU详情 私密 ​

新增项目商品/SKU 私密 ​

更新商品/SKU 私密 ​

删除商品/SKU 私密 ​

新增定价计划 私密 ​

更新定价计划 私密 ​

删除定价计划 私密 ​

新增优惠券 私密 ​

更新优惠券 私密 ​

删除优惠券 私密 ​

telegram机器人群发消息 私密 ​

获取telegram机器人历史群发记录 私密 ​

查询License授权码 公开 ​

激活License授权码 私密 ​

商户开放API

介绍

请求方式

多语言支持

请求示例

返回格式

返回码解释

接口文档

商户店铺基础信息公开

商户主页信息公开

获取订单详情公开

创建商品订单公开

支付商品订单公开

查询商品订单列表公开

获取商家订单列表私密

获取全部项目私密

获取指定项目私密

新建项目私密

修改项目信息私密

删除项目(不可撤销) 私密

获取单个商品/SKU详情私密

新增项目商品/SKU 私密

更新商品/SKU 私密

删除商品/SKU 私密

新增定价计划私密

更新定价计划私密

删除定价计划私密

新增优惠券私密

更新优惠券私密

删除优惠券私密

telegram机器人群发消息私密

获取telegram机器人历史群发记录私密

查询License授权码公开

激活License授权码私密