小红书开放平台MAPI 新手指南（品牌方/代理商/服务商）

感谢您选择小红书 Marketing API，小红书商业开放平台集成了聚光平台、蒲公英平台、私信三方工具、千帆推广平台的API能力，您可通过入驻及使用开放平台，启动您的智能营销之旅。

【MAPI 文档一览】： https://doc.weixin.qq.com/doc/w3_AZIArgYvAGoCNC0ftR5agTLmc0VW3?scode=ANAAyQcbAAgtjLpZWmAZIArgYvAGo

一、文档使用说明

1. 本接入SOP适用于：品牌+代理/服务商身份用户首次接入MAPI

2. 聚光API接入门槛：针对品牌+代理/服务商身份，聚光API不设置接入的日耗门槛，但在接入前仍需用户确认已满足以下条件：

a. 请检查是否已认证聚光平台投放资质，需认证并通过聚光推广资质后，再申请成为开放平台开发者

b. 开放平台注册开发者时需要在聚光平台是可投状态，即完成了资质认证和首次充值

3. 商业开放平台仅提供登录能力，不提供账号注册、专业号认证等能力，需使用已在其他平台（专业号/Partner）完成认证的品牌/代理账号进行登录。

4. 对于接入流程中不理解的名词，可参考文档第四部分的概念解析，接入流程中的一些高频问题可查看文档第五部分的FAQ。

二、 API接入流程概览

三、商业开放平台支持的登录方式

身份类型	可登录账号
品牌	● 品牌主账号 ● 专业号管理员账号
代理商（服务商相同）	● 竞价端口主账号 ● 竞价端口管理员员工账号 ● 蒲公英端口主账号（for 蒲公英API） ● 蒲公英端口管理员员工账号（for 蒲公英API）
技术服务商	● 提交申请的小红书非商业化账号

四、 MAPI接入步骤

操作步骤	步骤说明	示例
账号登录	品牌方/代理商/服务商在其他平台上完成资料填写和资质认证后，在商业开放平台使用主账号进行登录。
注册为开发者	登录后，点击右上角的“注册为开发者”，进入注册界面，确认相关信息后点击“下一步”和“提交审核”，即可完成注册流程。相关信息不不支持在商业开放平台修改，如需修改，品牌主客户请移步专业号平台，代理商请移步Partner平台进行修改
应用创建	注册为开发者后，进入应用中心，点击右上角“添加应用”按钮。
应用创建	进入添加应用窗口，选择服务场景、填写相关信息以及回调地址后，点击“确认添加”创建应用。
应用授权	在应用中心点击“编辑”，进入“编辑应用”窗口，拿到该应用的secret和授权url
	在浏览器打开该应用的授权url，进入授权界面，确认当前账号为品牌/代理主账号后，勾选确认要授予目标应用哪些权限，点击确认授权。
	点击确认授权后，可通过在创建应用时设置的回调地址，得到授权码auth_code（有效期为10min）
获取token	使用appid、secret、auth_code，即可调用【获取Token】接口，获取access_token 、refresh_token 以及其他重要参数。	调用【获取token】接口示例
刷新token	access_token有效期为24h，在refresh_token未过期的情况下，可通过调用【刷新token】接口，获取新的token，从而实现授权循环。如果刷新token也过期，则必须重新进行以上授权流程获取auth_code。	调用【刷新token】接口示例
开始调用接口	至此，开发者已获取了该应用的access_token，可以通过该应用调用聚光API的各类接口，如拉取数据、创编操作等。	调用【创意层级离线报表】示例 – curl部分调用【创意层级离线报表】示例 – json部分

附：商业开放平台不同身份之间的授权关系如下表所示：

操作方向	身份	可授权/被授权身份
被授权	品牌开发者	只能被品牌身份授权
	代理商开发者	只能被代理商授权
	服务商开发者	可被代理商和服务商授权
	技术服务商开发者	只能被品牌身份授权
授权	品牌身份	可授权给品牌开发者、技术服务商开发者
	代理商身份	可授权给代理商开发者、服务商开发者
	服务商身份	可授权给服务商开发者

附：商业开放平台授权时，默认授权的账号和权功能范围包括：

身份	授权账号范围	授权功能范围
品牌方	默认授权品牌名下所有的账号和代子账号	● 聚光场景：报表服务，查询计划、单元、创意等服务、创编计划、单元、创意等服务 ● 蒲公英场景：授前博主报价数据、授后数据、订单和评论相关服务的接口 ●乘风场景：数据报表
代理商/服务商	默认授权代理名下所有代子账号	● 聚光场景：报表服务，查询计划、单元、创意等服务，创编计划、单元、创意等服务（2024.06.06更新） ● 蒲公英场景：授前博主报价数据、授后数据、订单和评论相关服务的接口 ●乘风场景：数据报表
技术服务商	需选择授权账户，支持逐一勾选账户or批量添加，允许一次性最后添加1000条数据，超过则需要第二批添加	● 聚光场景：报表服务，查询计划、单元、创意等服务 ● 私信三方场景：私信三方工具服务 ●千帆推广场景：数据报表

五、 API词汇解析

5.1 名词概念

1. 应用（appid）：开发者在商业开放平台上创建的，每个应用一般对应了用户侧程序的一类使用场景。一个应用对应唯一的appid，但开发者之间的appid可重复，即A用户可拥有一个appid=1的应用，B用户也可拥有一个appid=1的应用，这两个应用间无任何关系。

2. 回调地址：客户自定义的链接地址，开放平台会将授权相关信息（即auth_code和state）拼接至该回调地址，是由用户独立确认的网址。

3. 授权链接/授权url：由开发者创建应用后，该应用自动生成的网址，可根据需求进行自定义（主要是指scope，即申请的权限范围），并需要手动给到授权方，再由授权方操作进行应用授权，在“编辑应用”界面获取，格式为：https://ad-market.xiaohongshu.com/auth?appId=应用ID&scope=权限范围&redirectUri=回调地址&state=abcd。

4. 授权码（auth_code）：授权方点击被授权方提供的授权url后，跳转到的网址中的auth_code=xxx部分，较长。开发者拿到后，可作为入参调用【获取token】接口，获取access_token和refresh_token，每个auth_code的有效期为10分钟，在10分钟内未利用其获取token，则需要重新授权。

5. access_token：access_token是在每次调用API接口时，需要在请求代码的header中传入的参数，每个access_token的有效期为一天。

6. refresh_token：refresh_token是用来调用【刷新token】接口，允许开发者独立获取新的access_token和新的refresh_token，从而实现授权的循环，每个refresh_token的有效期为30天。

7. 接口：即要使用的具体API功能，如【创建计划】、【创意层级离线报表】等，如：/api/open/jg/campaign/create

8. 请求参数/curl信息：用户在调用API接口时输入的完整代码，一般包含了较多的参数，代表用户想要完成的各种操作细节，是处理调用报错类问题的关键，因为平台侧现在已较少出现影响恶劣的bug，因此代码报错或者返回的数据错误时，大概率是请求代码有问题，因此若想快速解决问题，一定要主动提供请求参数和curl信息！

9. 返回信息：用户在调用了某个API接口后，接口返回的信息，主要包括以下三类：拉取的数据（如数据报表）、提示操作成功与失败（如创编）、报错信息（如参数错误等）。在处理代码报错问题时，请务必附上返回信息，辅助技术老师判断问题。

5.2 动作概念

1. 入驻/注册：即在商业开放平台注册成为开发者，以进行后续的创建应用、调用API活动，品牌方/代理商/服务商身份客户可在商业开放平台官网自主完成注册流程。

2. 创建应用：注册为开发者后即可在商业开放平台“应用中心“，通过”创建应用“按钮进行，需要选择平台（聚光/乘风/蒲公英/私信三方）、填写应用名称、回调地址等信息。

3. 授权：API的授权是某一广告主针对开发者的某一具体应用（appid）而言的。创建应用后，开发者可通过”编辑应用“窗口查看应用自动生成的授权url，线下给到广告主，需要先登录上正确的账号（即，要拉数的主账号，而不是随便一个自己的账号，对品牌/代理而言与开发者账号相同），再在浏览器中打开授权url，确认要授予的权限范围后，点击确认授权。

4. 获取授权码：点击确认授权后，浏览器会将授权码auth_code回调至原先设定的回调地址网页，其中的auth_code即为要使用的授权码。

5. 获取token：开发者用获取的auth_code，调用【获取token】接口，拿到access_token和refresh_token，至此，完整的授权流程已结束。

6. 刷新token：开发者用获取到的refresh_token，调用【刷新token】接口，拿到新的access_token和新的refresh_token，实现授权循环。

7. 调用接口：通过传入curl和请求参数，进行具体API功能的使用，如创建计划、拉取数据报表等。