北极星接口迁到美团技术服务合作中心：接口、授权、门店ID对照

你的系统几年前接的是北极星开放平台：代码里调的是 tuangou.receipt.prepare 这样的 method，库里存着每家门店的 session 和 open_shop_uuid。现在北极星的技术及运营服务已由美团技术服务合作中心承接，要继续核销，这三样都得换成合作中心的写法。

自己迁移、换门店系统还是改接第三方接口，这件事要先定下来。本文只讲决定自己迁移之后的技术对照：名词怎么换，接口路径怎么对，授权和门店ID怎么转，存量 session 怎么搬过去。

一句话回答： 团购模块的11个北极星 method 在合作中心都有对应路径，例如 tuangou.receipt.prepare 对应 /ddzh/tuangou/receipt/prepare，业务id都是58。授权从 session 换成标准 OAuth 2.0 的 access_token（appAuthToken），门店授权用 businessId 58。北极星存的 openShopUuid 和合作中心的 opBizCode、opPoiId 一一对应但值不同，要用官方转换接口换。存量授权用迁移接口把 session 搬过去；只接了 API、没接消息的，不需要调灰度接口。

• 接口一一对应。 团购模块 method 与新路径逐条对照，接口权限按对照表申请；
• 授权换成 OAuth 2.0。 每个 businessId 单独授权，token 不能跨业务用，再次授权时 scope 要传全量；
• 门店ID要转换。 openShopUuid 是混淆后的点评门店ID，合作中心要的是混淆后的美团门店ID，用“混淆后门店id转换”接口取得；
• 存量迁移分两块。 授权数据用迁移接口搬，消息流量用两个灰度接口切；所有 session 迁移成功、流量正常后不再支持回滚；
• 切流前留着北极星。 迁移 session 不影响北极星调用，流量切完之前北极星侧要保持可用，作为降级通道。

一、先核对官方口径：下线时间和适用范围

北极星什么时候停，两处官方页面的写法不同。我们在2026年10月15日查阅，原文要点并列如下：

两种说法本文不做调和。对开发者来说，做法是同一个：新的对接都在技术合作中心完成，北极星侧只作为切流前的过渡。你的账号处在哪个阶段，以平台运营的通知和控制台状态为准；原站通知写明，平台运营会依次联系已合作开发者。

动手之前，再确认四件事：

• 适用对象。 《北极星迁移指引》注明“仅适用于原北极星开放平台的开发者”，《接口明细对照表》也只面向存量用户；没接过北极星的，直接按新平台文档对接；
• 要重新入驻。 北极星的“我是开发者-工具型应用/信息型应用”对应三方服务商，“我是商家-自用型应用”对应自研品牌商；原合作开发者、合作商家都要在技术合作中心重新入驻；
• 入驻条件按新平台。 三方服务商要提供 Web 应用防火墙、等保证明或网络信息安全保险、保证金等企业信息安全保障，服务零售业务开通时保证金账户余额需达到10万元；平台暂不提供个人开发者的对接服务（2026年10月15日查阅，以官方后台为准）；
• 整体顺序。 官方给的新平台对接流程是：明确合作身份 → 完成入驻 → 接口权限和消息回调 → 获得门店授权 → 调试业务接口。

二、名词对照：北极星的叫法在合作中心对应什么

新文档的名词整套换了。先把词对齐，再看接口，读文档会顺很多。

三、团购接口对照：11个 method 换成路径

《接口明细对照表》里，团购模块的11个接口都是“请求”类，业务id都是58：

评价模块同样在业务id 58 下：ugc.queryShopReview 对应 /ddzh/ugc/queryshopreview（单一门店查询评论数据），ugc.querystar 对应 /ddzh/ugc/querystar（查询门店星级和单项分）。预订、经营数据等模块另有对照，预订消息改用数字 msgtype，例如预订结果同步是 5810003。

申请接口权限时，官方给的提交格式和示例是这样的：

改造时注意三点：

• 按表登记，不按规则拼。 团购模块的新路径刚好是把 method 的点换成斜杠、加上 /ddzh/ 前缀，但别写成自动拼接：评价的 ugc.queryShopReview 对应的是全小写的 /ddzh/ugc/queryshopreview。用到哪个 method，就在映射表里登记哪一条；
• 接口名按对照表写。 上面的官方示例把 prepare 写成“验券”，而对照表里 prepare 叫“输码验券校验”，consume 才叫“验券”。核销要先校验、再验券，两个接口都用，提交时两条都列上。入驻后平台运营会一对一开通权限；控制台的接口权限申请页也可以按模块或按接口自主申请，列表里没有的提交工单；
• 字段按新文档核对。 对照表只给了路径对应。公共参数、签名和业务参数要按合作中心文档逐个核对，不要照搬北极星时期的实现。技术合作中心提供了北极星接口文档查询页，可以对着旧文档逐条比。

四、授权：session 换成 OAuth 2.0 的 access_token

北极星的 session，在合作中心对应 access_token。合作中心用标准 OAuth 2.0 流程，接口和报错里把这个令牌叫 appAuthToken。一家门店的授权过程：

1. 生成授权链接。 自己拼接，或用控制台的“授权链接生成工具”生成；团购传 businessId=58；链接有效期24小时，生成后尽快让商家登录授权；
2. 商家确认授权。 商家登录美团账号，同意把业务授权给你的开发者；
3. 接收授权码。 平台把授权码 code 回调到你配置的地址，code 有效期10分钟；回调只支持 HTTPS，端口80或443；
4. 换取令牌。 用 code 换 access_token，同时拿到 opBizCode 和 opBizName：businessId 58 时分别是混淆后的美团门店ID和门店名称，建议当场保存与三方门店的映射；
5. 按需刷新。 获取令牌后3天内刷新，令牌不会变化，官方不建议频繁刷新。

和北极星时期相比，容易出错的是下面几处：

五、门店ID：openShopUuid 换成 opPoiId

北极星时期，三方系统里存的门店ID是 openShopUuid（也写作 open_shop_uuid）。到了合作中心，接口要的是混淆后的美团门店ID。三个字段的关系：

openShopUuid 与 opBizCode（58业务）、opPoiId 一一对应，对应关系唯一，但值不同。旧值不能直接当新值传。

存量门店用《存量迁移说明》里的数据互转接口处理。“混淆后门店id转换”分“原北极星转合作中心”和“合作中心转原北极星”两个方向，混淆后的用户id、客户id也各有一对双向转换接口。官方举的例子正好是这个场景：三方系统保存了三方门店ID和 open_shop_uuid 的映射，迁移后通过转换接口拿到 opPoiId 保存。

落库可以这样做：门店表新增一列存 opPoiId，逐店转换写入；open_shop_uuid 列保留到切流完成。灰度期间，北极星推来的消息带的还是北极星侧的门店，可以先用“原北极星转合作中心”接口换成合作中心门店，取到合作中心的授权数据，再调合作中心接口。

六、存量迁移：授权迁移、流量灰度和回滚边界

《存量迁移说明》把迁移分成两部分：一是授权数据，把北极星 session 迁成合作中心 token，有了授权数据才能调合作中心接口、收合作中心消息；二是流量，交互方从北极星换成合作中心。

开始前，先把北极星应用（AppKey）和合作中心开发者（developerId）绑定：在控制台【北极星存量迁移】页新增迁移应用信息，或由运营在后台绑定。打算让商家重新授权、不迁 session 的，可以不绑定。

几条要点：

• 迁移 session 不影响北极星。 调了迁移接口，授权数据就到了合作中心，但当前北极星流量和北极星接口调用照常，原 session 仍可继续使用；
• 切流前北极星要保持可用。 流量完全切到合作中心之前，北极星侧 session 过期要刷新。官方建议做降级：访问合作中心接口失败时，用原 session 访问北极星接口；
• 灰度只管消息。 两个灰度接口控制的是美团请求三方的消息流量，从北极星推送换成合作中心推送。只对接了 API、没对接消息的，不需要调灰度接口；
• 对接了消息，两个都要调。 先用“指定开发者和session”把所有 session 逐步灰度，全部完成后再调“指定开发者”。前者管需要业务授权的消息，后者管不需要业务授权的消息；
• 两侧消息都要兼容。 灰度过程中，同一种消息可能从北极星推来，也可能从合作中心推来，系统要同时能处理；
• 回滚有边界。 官方流程图注明：所有 session 迁移成功且存量商家流量正常后，将不再支持回滚。回滚预案只在这之前有效。

迁移 session 时常见的报错和处理：

七、三种迁移案例：停机、灰度、只接了 API

《迁移案例》分享了三种已完成迁移的做法。三种都要先通知所服务的商家；迁移失败的 session，都要让商家对相关门店或客户在合作中心重新授权。

怎么套用（本文建议，不是官方流程）：只做团购核销的，对应第三种。迁完授权以后，API 流量什么时候切、先切哪些门店，由你自己的调用层决定，可以按门店分批切。还对接了预订等有消息的模块，就在停机和灰度之间选；单量大、不能停服的，走灰度。

八、调用层改造示例和切流验收

自己迁移时，可以把改造收在调用层一处：按 method 查新路径，按门店决定走合作中心还是北极星，合作中心失败时按条件降级。下面是一段 Go 示例，路径来自官方对照表，门店数据和函数名都是虚构的：

// 示例：北极星 method → 技术合作中心路径，只登记用到的接口
var hubPath = map[string]string{
	"tuangou.receipt.prepare":        "/ddzh/tuangou/receipt/prepare",
	"tuangou.receipt.consume":        "/ddzh/tuangou/receipt/consume",
	"tuangou.receipt.reverseconsume": "/ddzh/tuangou/receipt/reverseconsume",
	"tuangou.receipt.getconsumed":    "/ddzh/tuangou/receipt/getconsumed",
	"tuangou.deal.queryshopdeal":     "/ddzh/tuangou/deal/queryshopdeal",
}

// 示例：一家门店的迁移状态，数据虚构
type Shop struct {
	AppShopID    string // 三方系统自己的门店ID，如 "S1001"
	OpenShopUUID string // 北极星时期的混淆后点评门店ID，切流完成前保留
	OpPoiID      string // 转换接口或授权换令牌拿到的混淆后美团门店ID
	HubToken     string // 技术合作中心 businessId=58 的 appAuthToken
	BjxSession   string // 北极星 session，切流完成前过期要刷新
	OnHub        bool   // 这家门店的 API 调用是否已切到技术合作中心
}

func Call(ctx context.Context, method string, s *Shop, in Input) (*Result, error) {
	path, ok := hubPath[method]
	if !ok {
		return nil, fmt.Errorf("method %s 未登记新路径", method)
	}
	if !s.OnHub || s.HubToken == "" {
		return bjx.Call(ctx, method, s.BjxSession, in) // 还没切的门店照旧走北极星
	}
	// 公共参数、签名、业务参数都按技术合作中心文档组装，不复用北极星的字段
	res, err := hub.Post(ctx, path, s.HubToken, hubParams(method, s, in))
	if err == nil {
		return res, nil
	}
	if isWrite(method) && !surelyNotSent(err) {
		// 验券、撤销验券结果不明时不降级重发，先用“查询已验券信息”核对
		return nil, ErrNeedCheck
	}
	return bjx.Call(ctx, method, s.BjxSession, in) // 切流完成前的降级通道
}

这段示例的几处考虑：

• 未登记就报错。 映射表只放用到的接口，没登记的 method 直接报错，不让拼错的路径悄悄失败；
• 按门店切 API。 OnHub 让你按门店分批把 API 调用切到合作中心，出问题改回开关即可。它和消息灰度是两件事，消息流量仍由官方灰度接口控制；
• 写操作不盲目降级。 官方建议合作中心失败时用原 session 访问北极星。验券、撤销验券是写操作，超时等结果不明时，先查询已验券信息确认，再决定是否重发，避免同一张券在两边各处理一次（本文建议）；
• 切完再拆旧通道。 全部门店切完、消息灰度到100%且运行正常后，再删除北极星分支和旧字段。

切流前验收清单

• 用到的每个 method 都在映射表里有新路径，对应接口权限已开通；
• 开发者ID和 SignKey 已配置，公共参数和签名按合作中心文档实现；
• 每家门店都有 opPoiId（或58业务授权返回的 opBizCode），并和 openShopUuid、三方门店ID对得上；
• token 按 businessId 分开保存，团购接口用58业务的 token；
• 再次授权时 scope 传全量；
• 迁移失败的 session 已列成清单，相关商家已在合作中心重新授权；
• 测试门店跑通输码验券校验、验券、查询已验券信息、撤销验券四个接口；
• 对接了消息的：两个灰度接口按顺序调到100%，系统能同时处理两侧推来的消息；
• 切流完成前，北极星 session 保持可用，降级通道能用；
• 团队清楚回滚窗口：所有 session 迁移成功、存量流量正常之后，不能再回滚。

九、常见问题

北极星开放平台到底是哪天下线的？

两处官方说法不同（2026年10月15日查阅）。北极星原站《迁移通知》写的是：已合作企业2025年7月2日起可登录技术合作中心，逐步完成接口改造升级和授权能力升级，原文档中心及控制台“逐步进行下线处理”；技术合作中心《北极星迁移指引》写的是“原北极星已于2025年6月25日正式下线”。两处指向同一个做法：新的对接在美团技术服务合作中心完成，你的账号状态以平台运营通知为准。

迁移 session 之后，北极星的 session 还能用吗？

能。官方说明调用迁移接口不影响当前北极星流量和北极星接口调用，原 session 可以继续使用。流量完全切到合作中心之前，北极星侧要保持可用，session 过期要刷新，并把它作为合作中心接口失败时的降级通道。

只接了团购核销接口，需要调灰度接口吗？

不需要。灰度接口控制的是美团请求三方的消息流量；官方迁移案例写明，团购核销模块只有 API、没有消息。只对接了 API 的，迁移授权数据即可，API 什么时候切由你的调用层决定。

openShopUuid 能直接当 opPoiId 用吗？

不能。openShopUuid 是北极星时期混淆后的点评门店ID，opPoiId 是混淆后的美团门店ID，两者一一对应但值不同。存量门店用“混淆后门店id转换(原北极星转合作中心)”接口换出 opPoiId 保存；新授权的门店，58业务授权返回的 opBizCode 就是混淆后的美团门店ID。

提示“appAuthToken 不属于当前业务 鉴权失败”怎么办？

这表示你用业务A下拿到的 appAuthToken 访问了业务B的接口。团购、评价、预订属于 businessId 58，商品管理、订单管理属于59，要用接口所属业务下获得的 token。每个业务的授权相互独立，用到几个业务，就分别授权、分别保存。

迁移 session 提示“迁移资源冲突”，只能让商家重新授权吗？

是。这个提示和“门店维度模块冲突”一样，表示该门店或客户在北极星授权给了多个不同应用。官方的处理方式是与商家确认后，对冲突门店在合作中心重新授权；需要重新授权的门店多，可以用平台提供的批量授权接口。

不想自己迁移，改接无限聚核要做什么？

不需要自己入驻技术合作中心，不收接口接入费，也不用自己交保证金。门店要重新授权：在无限聚核为每家实际门店创建门店、拿到 shopId，调获取授权链接接口 get/auth/url（platform 传1），让商家在美团页面确认授权，拿到链接不等于授权完成。调用层把核销改成输码验券校验 ddzh-tuangou-receipt-prepare 和验券 ddzh-tuangou-receipt-consume，撤销时用核销返回的 consumeCredential 调撤销核销 ddzh-tuangou-receipt-cancel；预核销和撤销不计费，核销成功计费。接口字段以无限聚核当前公开 API 文档为准。

文中平台规则摘自美团技术服务合作中心《北极星迁移指引》《接口明细对照表》《存量迁移说明》《迁移常见问题》《迁移案例》《授权常见问题》和北极星原站《迁移通知》（2026年10月15日查阅），以官方后台为准。