核销服务由无限聚核提供美团、抖音团购核销一站式接入。搜「美团核销 Java示例」时结果里常混着不确定的 SDK 帖、过期字段说明和「直接 msconsume」半截示例。开发真正卡的是走自研开放平台还是接第三方统一接口prepare → consume → 撤销怎么串超时与未知态怎么分支一句话回答自研走美团开放平台「验券准备 → 执行验券 → 撤销」接第三方则用同一套「预核销 → 核销 → 撤销」platform1表示美团。出站请求用Authorization: Bearer API Key成功只认顶层successtrue失败看errorCode业务侧按券码 本地订单去重聚合核销无需调方传幂等键。下文用 Java 11 JDKHttpClient Jackson 写可运行示意不是官方完整 Java SDK 类库。业态以V2 服务零售聚合为主到店餐饮请改用餐饮路由勿照搬本文路径。依据无限聚核公开 API 与接入 FAQ 口径整理查阅日期 2026-10-20字段以当前公开文档为准。先选路径。自研管商家 token聚合用具体门店shopIdplatform1出站鉴权是 Bearer。API Key 只放服务端不要臆造「官方美团核销 Java SDK」类名去 import幂等分两层。接口避免重复核成多笔业务仍要自己去重并保存首次成功响应prepare 不改券状态。真正扣券在 consumeticketInfo必须整段原文回传撤销用 consumeCredential。与消费者退款是两件事撤销无幂等。示意图字段与规则摘自无限聚核公开 API2026-10-20 查阅非平台后台截图。一、两条路先选对路径你做什么适用自研美团开放平台办服务商自研资质管商家 token对接准备验券撤销与查询要抖音再单独接一套已有多商户能力、要原生能力尽量全开第三方统一接口建门店、商家授权、业务后端调统一预核销核销撤销平台差异由服务商消化要同时核美团抖音、缩短上线两条路都不要「跳过准备直接核」。自研侧常见准备执行接口族名如receipt.prepare、对应验券到店餐饮文档里还会见到mspreparemsconsume等属另一路由聚合侧服务零售对应ddzh-tuangou-receipt-prepare→ddzh-tuangou-receipt-consume。自研时请对照美团开放平台当前文档与官方示例常见有 Go 等不要假设存在一套完整的「官方美团核销 Java SDK 类名」可直接 import多数团队用 HTTP JSON 自封装。下文示意走聚合路径platform1。二、最小闭环prepare → consume → cancel预核销输码验券校验POST …/ddzh-tuangou-receipt-prepare传shopId、platform1、code。成功后拿到套餐展示信息与不透明ticketInfo。不改变券状态不发权益。核销验券POST …/ddzh-tuangou-receipt-consume顾客确认后原样回传同一组shopId、platform、code、num、ticketInfo。成功看successtrue保存wxdgOrderNo、data[]、consumeCredential[]。撤销POST …/ddzh-tuangou-receipt-cancel传原shopId、platform与consumeCredential数组1–10 项。美团侧撤销窗口常见约 10 分钟以平台当前说明为准。撤销与消费者退款是两件事。shopId必须是聚合侧具体门店ID不是商户 ID、不是你自己系统门店主键、不是美团平台门店码。API Host 与完整 URL以当前公开 API 文档为准下文只写路径后半段。三、HTTP 封装与出站鉴权示意省略部分 importapiHost、apiKey只放服务端配置。出站统一Authorization: Bearer API Key需要接收授权结果 Webhook 时入站验签用当前 API Key 对timestamp . rawBody做 HMAC-SHA256结果为小写十六进制并加v1前缀必须用原始 Body 字节不能先解析再序列化。验签细节以公开文档「Webhook」章节为准本文重点仍是核销主链路。privatefinalObjectMapperjsonnewObjectMapper();privatefinalHttpClienthttpHttpClient.newHttpClient();privateStringapiHost;// 从服务端配置注入以当前公开文档为准privateStringapiKey;staticfinalclassApiResponse{finalinthttpStatus;finalJsonNodebody;ApiResponse(inthttpStatus,JsonNodebody){this.httpStatushttpStatus;this.bodybody;}booleanisSuccess(){returnbody.path(success).isBoolean()body.path(success).booleanValue();}StringerrorCode(){returnbody.path(errorCode).asText();}}ApiResponsepostJson(Stringpath,StringrequestJson)throwsIOException,InterruptedException{HttpRequestrequestHttpRequest.newBuilder(URI.create(apiHost/api/hexiao/v2/path)).timeout(Duration.ofSeconds(10)).header(Authorization,Bearer apiKey).header(Content-Type,application/json).POST(HttpRequest.BodyPublishers.ofString(requestJson)).build();HttpResponseStringresponsehttp.send(request,HttpResponse.BodyHandlers.ofString());JsonNodebody;try{bodyjson.readTree(response.body());}catch(JsonProcessingExceptione){bodyNullNode.getInstance();}returnnewApiResponse(response.statusCode(),bodynull?NullNode.getInstance():body);}也可用 OkHttp 等价替换关键是不要假装有官方完整 Java SDK并固定超时、日志脱敏、traceId落库。四、预核销保存 ticketInfo请求体关键字段{shopId:123,platform:1,code:顾客输入的美团券码}ObjectNodeprepare(longshopId,Stringcode,intnum)throwsException{if(num1||num10)thrownewIllegalArgumentException(num 1–10);ObjectNodereqjson.createObjectNode().put(shopId,shopId).put(platform,1).put(code,code);ApiResponsereplypostJson(ddzh-tuangou-receipt-prepare,req.toString());if(!reply.isSuccess())thrownewIllegalStateException(prepare failed: reply.errorCode());JsonNodedatareply.body.path(data);StringticketInfodata.path(ticketInfo).asText();if(ticketInfo.isEmpty())thrownewIllegalStateException(missing ticketInfo);// 美团预核销常用 ticketName dealPrice元与已配置商品预匹配无统一商品 ID// ticketInfo 当不透明串整段保存禁止解析重组ObjectNodeconsumeReqreq.deepCopy().put(num,num).put(ticketInfo,ticketInfo);// 业务侧落 pending / 确认单保存 consumeReq 原文与 prepare datareturnjson.createObjectNode().put(ticketName,data.path(ticketName).asText()).put(payAmountFen,data.path(payAmount).asLong()).set(consumeRequest,consumeReq);}注意payAmountactualPayAmount多为分dealPrice多为元响应里没有门店 ID后续始终用你保存的shopId。prepare 成功不等于已核销。五、核销原参数 errorCode 分支staticfinalSetStringRETRYABLESet.of(CONSUME_IN_PROGRESS,RESULT_UNKNOWN,SERVICE_UNAVAILABLE,PROVIDER_UNAVAILABLE);voidconsume(StringpendingConsumeRequestJson)throwsInterruptedException{// 发请求前业务侧写 pending / 加锁门店平台券码本地订单finalintmaxAttempts3;JsonNodelastNullNode.getInstance();for(inti0;imaxAttempts;i){if(i0)Thread.sleep(1000L*i);ApiResponsereply;try{replypostJson(ddzh-tuangou-receipt-consume,pendingConsumeRequestJson);}catch(IOExceptione){continue;// 超时断连原样重试}lastreply.body;if(reply.isSuccess()){// 保存首次完整响应wxdgOrderNo、data[]、consumeCredential[]return;}Stringecreply.errorCode();if(ALREADY_CONSUMED.equals(ec)){// code 常见 10500保存 wxdgOrderNo停重试转核对勿补发、勿编造凭证return;}if(!RETRYABLE.contains(ec)){// PLATFORM_REJECTED、参数授权等停展示原因return;}}// 仍未知标记 unknown查已验券信息或对账}核销请求体示例{shopId:123,platform:1,code:同一券码,num:1,ticketInfo:预核销返回的原值整段回传}幂等键怎么理解公开 FAQ 口径当前聚合核销无需调方传idempotencyKey旧客户端传入也会被忽略。接口侧保证同一业务请求不会核成多笔不保证重复调用返回同一份首次成功明细。业务系统必须按「门店 平台 券码 本地订单」去重加锁保存首次完整成功响应并按data[i]与consumeCredential[i]下标对应收到ALREADY_CONSUMED常见code10500时用wxdgOrderNo核对而不是再点一次当补偿。六、撤销voidcancel(longshopId,ListStringcredentials)throwsException{if(credentials.isEmpty()||credentials.size()10){thrownewIllegalArgumentException(consumeCredential 1–10);}ObjectNodereqjson.createObjectNode().put(shopId,shopId).put(platform,1);ArrayNodearrreq.putArray(consumeCredential);credentials.forEach(arr::add);ApiResponsereplypostJson(ddzh-tuangou-receipt-cancel,req.toString());// 整笔拒绝CREDENTIAL_INVALID / CANCEL_UNSUPPORTED 等// 到达平台后看 data[].statussucceeded / rejected / unknown// 撤销无幂等未知时先查券状态勿盲目重发}请求体示例{shopId:123,platform:1,consumeCredential:[核销成功时保存的凭证]}七、上线前验收预核销成功只进确认页未发权益核销successtrue后wxdgOrderNo、明细、凭证齐全权益只发一次超时用原请求原参数有限重试不重新预核销、不换ticketInfoPLATFORM_REJECTED停ALREADY_CONSUMED核对撤销在时限内可回退本地权益未知项先查已验券信息。八、与自研美团路径对照环节自研美团开放平台聚合platform1服务零售准备receipt.prepare 等以当期文档为准ddzh-tuangou-receipt-prepare执行对应验券接口ddzh-tuangou-receipt-consume撤销以开放平台当期字段为准consumeCredential 数组门店商家 token门店绑定具体门店 shopId成功判断以开放平台当期说明为准success 布尔值JavaHTTP自封装勿臆造 SDK 类名HttpClientJackson 示意到店餐饮是另一套接口族本文不展开餐厅请另查餐饮路由文档勿把上表服务零售路径直接套过去。常见问题美团核销的 Java 示例要自己算请求签名吗出站调用无限聚核 V2 聚合接口时请求头使用Authorization: Bearer API Key即可调用方不必再拼美团开放平台那套出站sign也不要臆造官方完整 Java SDK 类名。若配置了 Webhook入站才需要按公开文档用 API Key 做 HMAC-SHA256 验签。prepare 和 consume 可以合并成一次调用吗不可以。每次新的核销前都要先调输码验券校验确认券仍可用再把返回的ticketInfo原文交给验券接口。跳过 prepare 或篡改ticketInfo会导致核销失败或凭证非法。接口说幂等为什么业务还要按券码去重接口幂等保证同一业务请求不会核成多笔但重复请求命中已成功订单时只返回 10500 提示和wxdgOrderNo不会再次给出首次成功明细与撤销凭证。权益发放必须以本地保存的首次成功记录为准并按券码与业务订单去重。聚合核销无需调方传idempotencyKey。失败后怎样安全重试仅当errorCode属于CONSUME_IN_PROGRESS、RESULT_UNKNOWN、SERVICE_UNAVAILABLE、PROVIDER_UNAVAILABLE或请求超时未拿到响应时使用完全相同的原 JSON 有间隔、有上限地重试。PLATFORM_REJECTED与ALREADY_CONSUMED停止自动重试。本文和「小程序接入 Java 实战」怎么分工小程序全流程接入授权、商品映射、确认页、权益见开发实战里的小程序集成文本文专打检索意图「美团核销 Java示例」聚焦服务零售下鉴权、幂等与 prepare → consume → cancel。两篇互补不要互相改写成一篇。小结美团核销用 Java 写关键不是找一个「官方 SDK jar」而是把Bearer 鉴权、业务幂等、prepare → consume → cancel钉死。自研跟美团开放文档接聚合则统一三步ticketInfo整段回传成功只认success幂等靠业务去重而不是调方传幂等键。示例未对真实券编译联调上线前请对照当前公开 API 文档自行验收。