diff --git a/docs/行业电子凭证/app 授权说明.md b/docs/行业电子凭证/app 授权说明.md new file mode 100644 index 00000000..bc98e3c7 --- /dev/null +++ b/docs/行业电子凭证/app 授权说明.md @@ -0,0 +1,396 @@ +2.OAuth2的code授权流程及接口简介 +2.1 code授权流程 +![alt text](image.png) + + 授权流程可以简单归纳为： + 1.获取授权码code（步骤1234）； + 2.授权码code换取长时令牌refreshToken以及短时访问令牌accessToken（步骤56），使用accessToken调用电商授权API（步骤789）； + 3.若短时访问令牌accessToken过期，则使用长时令牌refreshToken刷新短时访问令牌accessToken，再使用新的accessToken进行调用。 + + 下面将详细介绍每一步的调用过程及用到的接口 + +2.2 获取授权码code +授权页面地址示例：https://open.kwaixiaodian.com/oauth/authorize?app_id=xxx&redirect_uri=xxx&scope=xxx,xxx&response_type=code&state=xxx + +使用说明： +1、若应用为”商家后台””快分销”“快赚客”自研应用，需要现在应用的测试用户或授权用户列表中添加用户后，用户打开授权页面完成授权； +2、若应用为第三方ISV应用，需要上架到服务市场，用户需在服务市场订购了服务完成授权。 + +页面参数说明: + +参数名 + +是否必须 + +描述 + +app_id + +是 + +应用的 appKey + +response_type + +是 + +授权的类型，默认为"code" + +scope + +是 + +APP已经拥有且需要获取用户授权的权限包，多个用 “,” 连接，比如merchant_item。可至“应用中心-APP详情页”查看APP已获得的权限包列表，平台所有权限包见下文 + +redirect_uri + +是 + +授权成功的回调uri，为APP在创建时填写的回调地址 + +state + +否 + +状态值，成功授权后回调时会原样带回 + + 如果授权成功，授权服务器会将用户的浏览器重定向到应用 ：http(s)://redirect_uri?code=CODE&state=STATE + +参数名 + +参数类型 + +是否必须 + +code + +string + +用来换取access_token 的授权码，有效期为 2 分钟且只能使用一次，在用户首次允许授权时返回 + +state + +string + +如果请求时传递参数，会回传该参数 + +2.3 用授权码code换取长时令牌refreshToken以及访问令牌accessToken + 请求地址: https://openapi.kwaixiaodian.com/oauth2/access_token ** 此接口为后端接口** + + 请求方法: GET + + 请求参数: + +参数名 + +是否必须 + +描述 + +app_id + +是 + +开发者appKey + +grant_type + +是 + +授权的类型，"code" + +code + +是 + +2.2中获取到的code + +app_secret + +是 + +开发者的appSecret + + 正确返回值: + +参数名 + +描述 + +result + +返回结果类型，1为正确，其他为不正确 + +access_token + +临时访问令牌，作为调用授权API时的入参，过期时间为expires_in值，授权用户、app和权限组范围唯一决定一个access_token值 + +refresh_token + +长时访问令牌，默认为180天，授权用户、app和权限组范围唯一决定一个refresh_token值 +注意：refresh_token值不需要存储固定值，因access_token48小时过期时间内需要用长时令牌refreshToken刷新访问令牌accessToken，每次刷新会换取新的refreshToken + +open_id + +用户对该开发者的唯一身份标识 + +expires_in + +access_token过期时间，单位秒，默认为172800，即48小时 + +scopes + +本次授权中，用户允许的授权权限范围，即access_token和refresh_token中包含的scopes + + 异常返回值： + +参数名 + +描述 + +result + +返回结果类型，详情查看本文错误码简介 + +error + +错误类型 + +error_msg + +错误详情，用于提示具体的错误原因 + +2.4 用长时令牌refreshToken刷新访问令牌accessToken + 当access_token 过期时，可以使用(在有效期内的) refresh_token重新获取新的access_token，不需要显式的用户授权过程，若refresh_token也过期了，则需要再次经过用户授权，因此需要关注refresh_token的时效（默认180天），需要在时效内用此接口再换取新的refresh_token才不会出现用户授权频繁失效的情况。该接口只支持authorization_code模式获取access_token 刷新，刷新得到新的access_token 和refresh_token, 旧的refresh_token 随即在5分钟内失效。 + + 使用子账号的refreshToken刷新accessToken时以下情况会报错：1、子账号被禁用、删除或状态不可用；2、子账号的主账号和APP不存在授权关系。 + + 当且仅当子账号状态可用，且子账号的主账号和APP存在授权关系时，才可正确获取到子账号的accessToken。 + + 请求地址: https://openapi.kwaixiaodian.com/oauth2/refresh_token ** 此接口为后端接口** + + 请求方法: POST + + 请求参数: + +参数名 + +是否必须 + +描述 + +grant_type + +是 + +授权的类型，必须是"refresh_token" + +refresh_token + +是 + +长时访问令牌，默认为180天，2.3接口中返回的值 + +app_id + +是 + +开发者 appId + +app_secret + +是 + +开发者的appSecret + + 正确返回值: + +参数名 + +描述 + +result + +返回结果类型，1为正确，其他为不正确 + +access_token + +临时访问令牌，作为调用授权API时的入参，过期时间为expires_in值 + +expires_in + +access_token过期时间，单位秒，默认为172800，即48小时 + +refresh_token + +长时访问令牌，默认为180天，会返回新的refresh_token，原有的refresh_token即失效 +注意：refresh_token值不需要存储固定值，因access_token48小时过期时间内需要用长时令牌refreshToken刷新访问令牌accessToken，每次刷新会换取新的refreshToken + +refresh_token_expires_in +refresh_token 的过期时间，单位秒，默认为180天 + +scopes +access_token包含的scope + + 异常返回值： + +参数名 + +描述 + +result + +返回结果类型，详情查看本文错误码简介 + +error + +错误类型 + +error_msg + +错误详情，用于提示具体的错误原因 + + + + === + 4.授权错误码简介 +result + +error + +异常描述 + +100200100 + +invalid_request + +缺少必要的请求参数 + +100200101 + +unauthorized_client + +app 非法，例如 开发者不存在，app 不存在或状态不正确等 + +100200102 + +access_denied + +请求被拒绝，授权和后续API，访问中出现任何的Token 错误都会返回这个异常，存在三种可能 +invalid refresh_token 无效token +refreshToken.discarded refreshToken已经用过，不能重复使用 +refreshToken.revokedAuthorization 用户已经撤销授权 + +100200103 + +unsupported_response_type + +responseType 错误 + +100200104 + +unsupported_grant_type + +换取accessToken 使用的grantType 错误 + +100200105 + +invalid_grant + +换取accessToken 使用的 code 错误 + +100200106 + +invalid_scope + +权限 scope 错误，或者用户取消了授权等 + +100200107 + +invalid_openid + +用户的 openid 无效 + +100200500 + +server_error + +服务器内部错误，开发者侧无法处理 + + + +5.权限组列表 + 权限组用于控制APP调用API和接受消息的权限范围，只有当APP拥有该API所属的权限组才可以调用API，只有当APP拥有该消息所属的权限组才可以消费消息，列表中说明了现有的权限组以及对应的权限组的API和消息。快手电商开放平台会根据开发者创建的应用类型授予默认的权限组，若开发者需要申请额外的权限组，请发邮件到open@kuaishou.com并说明理由。 + +Scope + +描述 + +备注 + +user_base + +授权之后的默认权限 + +所有应用默认拥有此权限组 + +user_info + +用户基本信息 + +所有应用默认拥有此权限组 + +merchant_user + +商家用户信息 + +用户API权限 + +merchant_item + +读取或更新店铺的商品数据 + +商品API和商品消息权限 + +merchant_order + +读取或更新店铺的订单信息 + +订单API和订单消息权限 + +merchant_refund + +读取或更新店铺的售后信息 + +退款单API和退款单消息权限 + +merchant_distribution + +读取或更新分销信息 + +分销API权限 + +merchant_logistics + +读取或更新物流信息 + +物流API权限 + +merchant_promotion + +读取或更新营销信息 + +营销API权限 + +merchant_cs + +读取或更新店铺的客服信息 + +客服API权限 + +merchant_comment + +读取或更新店铺的评价信息 评价API权限 +merchant_servicemarket + +获取应用在服务市场的订购信息 服务市场API权限 diff --git a/docs/行业电子凭证/image.png b/docs/行业电子凭证/image.png new file mode 100644 index 00000000..cc35e86d Binary files /dev/null and b/docs/行业电子凭证/image.png differ diff --git a/docs/行业电子凭证/解决方案/业务方案/1.方案介绍.md b/docs/行业电子凭证/解决方案/业务方案/1.方案介绍.md new file mode 100644 index 00000000..0e415d27 --- /dev/null +++ b/docs/行业电子凭证/解决方案/业务方案/1.方案介绍.md @@ -0,0 +1,309 @@ +方案介绍 +更新时间：2025-03-26 +阅读数：21079 +1.业务介绍 + 快手平台提供了凭证发送和核销能力，给有线上发码及线下消费的交易商家提供服务。码商可以通过入驻快手小店及电商开放平台，给快手商家提供电子凭证的发送以及核销的服务。目前快手整体提供了三种电子凭证的对接能力 + + 1.快手发码和核销：此种方式无需ISV对接，联系我们的快手电子平台运营同学，即可接入，这种方式属于接入最快的方式。所有券码的生命周期由快手平台负责，商家可以自定义券的应用场景，有效期等。【平台发码产品使用手册（可忽略门店管理）】 + + 2.码库发码、快手核销：商家可以通过excel导入已有的券码，核销由快手平台核销，这种方式也无需ISV对接，但是需要商家手动把外部二维码导入。【码库发码产品使用手册（可忽略门店管理）】 + + 3.商家发码和核销：这种方式下由商家系统自己负责发码，并且将码的副本信息同步给快手平台，双方共同管理券码的生命周期，本方案主要介绍这种接入方式。 + + 4. 新开发的跨门店结算/按卡券结算能力/poi接入的相关细节可以查看对接实践 + + + +名词解释 +发码方式：用户购买后商家通过某种方式把卡券发送给用户，目前快手支持3种发码方式：商家发码、码库发码、快手平台发码 + +i、商家发码：商家通过对接收单和发码2个接口，当用户购买商品后，快手会「推送订单给商家」，以及商家必须在超时时效内「回调发码的结果」给快手 + +ii、码库发码：商家需提前准备一批「未核销」的卡券，上传到快手小店的「码库」中。当用户购买商品后，快手会自动从「码库」中选择一个「未核销」的卡券发给用户。无需商家对接「发码接口」 + +iii、快手平台发码：商家无需提前准备卡券，由快手侧自动生成唯一的卡券发给用户。缺点是这批卡券是快手生成的，商家系统是不存在这些卡券的，所以不支持商家核销，只能在快手内核销 + + + +核销方式：用户收到卡券后可以通过不同方式核销掉，目前快手支持2中核销方式：商家核销、快手核销 + +i、商家核销：用户收到卡券后，拿着卡券去商家系统进行核销，核销完成后商家需回传核销状态给快手，快手驱动卡券状态到『已核销』。商家需要对接『核销回调接口』 + +ii、快手核销（非自动）：商家使用快手商家版APP或者快手小店后台「券码工具箱」，对用户卡券进行核销。核销后快手会驱动卡券状态到『已核销』。商家无需对接核销接口 + +iii、自动核销（只发不核）：用户的卡券发放成功后，快手会自动核销，适用于少数业务场景。该核销方式必须同步给快手小二并获得其同意，方可配置。商家无需对接核销接口 + + + +关单：商家在指定的发码时间内，未进行发码回调。快手先调用商家的查询接口，如果查询到券码，报警人工处理。如果查询不到券码，才会调用销毁接口通知商家进行关单。 + +i、查询接口：超过24h（不同业务，超时时间不同）商家还未发码回调，快手定时任务会触发查询发码结果的操作，商家只能返回2种错误码「4012002-订单不存在」「 4012005-卡券不存在」，详见错误码规范 + +ii、发起销毁接口：当快手「查询接口」识别到商家返回的是上面2种指定的「关单错误码」，快手侧会调用「发起销毁接口」通知商家关单。商家必须要同意销毁「result=1」，快手才会关单并退款 + + + +常用对接场景 +商家发商家核：只能商家发码且商家主动核销，商家需要对接「发码」和「核销」接口，对应下文的方案A 。 + +只发不核：发码后自动核销，无需用户主动去「商家系统」或者「快手系统」核销。只发不核模式容易产生大量客诉，需要小二谨慎评估才可以使用该功能。包括：商家发码自动核销、码库发码自动核销、快手平台发码自动核销，统称为「只发不核」 + + + +快手已支持的链路 +发码方式 \ 核销方式 商家核销 快手核销（非自动） 自动核销【只发不核】（需加白才能开通） +商家发码 支持 不支持 支持 +码库发码 支持 支持 支持 +快手平台发码 不支持 支持 支持 + + +订单和卡券状态 +动作 订单状态 卡券状态 +用户支付成功 已支付/待发货（30） 无 +商家发码成功 已发货（40） 未使用 +商家核销成功 已签收（50） 已使用 +核销成功 + N天，用户无异议推动订单完成（结算货款） 交易完成（70） 已使用 +商家超时未发码（默认24h内需发货） 交易失败（80） 无 +卡券到期未核销（过期自动退场景） 交易失败（80） 已销毁 +用户主动申请退款（支持退款场景） 交易失败（80） 已销毁 + + +2.接入评估 +2.1 目标用户 + 面向拥有自研能力可以发码的商家，可以和平台进行对接并将数据同步，双方共同管理券码的生命周期 + +2.2 接入评估 +评估点 评估等级 评估内容 默认 备注信息 +售卖类目 高 放在哪个类目下？有哪些资质 运营决策 商家和快手小二沟通清楚售卖类目 +售后规则 高 +随时退过期退：未使用状态下，支持用户主动申请。卡券未使用状态下，过期会自动退款 + +过期自动退：不支持用户主动申请退款。卡券未使用状态下，过期会自动退款 + +不可退：卡券不关心是否使用，都不支持退款 + +已商家实际业务为准，不可以随意选择 +商品发品示例如下，不支持其他售后规则，比如：不支持「7天无理由退款」。 + + + +发码方式 高 +【商家发码、码库发码、快手平台发码】 + +商家发码：商家通过对接接口进行发码 + +码库发码：商家在快手小店先导入券码，发品的时候绑定码库。如果用户购买了该商品，那么快手会从该商品绑定的码库里面选择一个「可用」券码发给用户 + +快手平台发码：商家无需做任何操作，快手会随机生成券码然后发给用户 + +已商家实际业务为准，不可以随意选择 +建议联系运营小二，做正确评估。商品发品示例： + + + +核销方式 高 +商家核销、快手核销、自动核销（只发不核） + +商家核销：用户在快手站外核销，然后商家必须通过对接接口把核销状态同步给快手 + +快手核销：商家可以在快手小店-商品-券码工具箱，操作核销 + +自动核销（只发不核）：特殊业务场景，卡券发了之后不能退还，需发码即核销。容易产生客诉，运营小二会严格审核 + +商家核销 +建议联系产品、运营同学做完整接入的评估 + + + +技术对接方案 高 参考2.4节，有5种方案可选 默认方案A（商家发码、商家核销） +核销方式在哪 中 扫码核销、网页核销、电话核销等，说清楚 扫码核销 商家描述清楚用户卡券核销全链路 +是否需要支持实体卡 低 实体卡、虚拟卡 虚拟卡，目前已不支持实体卡 仅大闸蟹业务支持实体卡 +是否会冻结资金 低 是、否 否 +一单一份发一张码还是多张码？ 低 一单一码、一单多码 一单一码 +购买时一单一件，发「一张卡券」 + +购买时一单多件，发「多张卡券」 + +快手不支持次卡（一张卡券只能核销一次） + +结算方式 低 结算时间、结算周期、起结金额等 +1. 首张核销+N天结算 +2. 全部核销+N天结算 +3. 卡券核销+N天按卡券独立结算给门店(跨门店结算) 全部核销后+7天 不支持商家定制 +退款方式 低 部分退、整单退 整单退 +发码账号类型 低 用户填写的账号类型，比如：手机号 手机号 目前只支持手机号 +卡号形式 低 卡券号、卡密，或者两者都有 仅卡券号 +- 卡密（卡号 + 卡密）只支持在「商家发码」方式下 + +- 卡号（仅卡号）3种方式都支持 + +是否需要展示二维码 低 二维码用卡券号还是卡密等 卡券号二维码 - 只发不核默认不展示二维码 +是否需要支持撤销核销（冲正） 低 是、否，一般撤销核销配合预约核销功能使用 否 +是否有独立品牌和资质 低 自有品牌，代理品牌，无品牌等 自有品牌 +基于以上评估，选择哪个对接方案 方案A、方案B、方案C、方案D、方案E 方案A + +2.3 评估模板示例 +售卖类目：游戏充值类目 +发码方式：商家发码 +核销方式：自动核销（只发不核） +核销方式在哪：游戏内部充值入口 +支持实体卡：否 +冻结资金：否 +一单一码：一单一码 +退款方式：不支持七天无理由退款、产品质量问题整单退 +是否需要展示二维码：不需要 +卡号形式：仅卡号 +是否过期退：不支持 +是否有独立品牌和资质：是，有独立品牌及资质 +选择对接方案：方案E + + + +2.4 方案对比 +接口 +方案A (推荐方案) + +(商家发码，商家核销) + +方案B + +(商家发码，快手退款) + +方案C + +(快手码库发码，商家核销) + +方案D (推荐方案) + +(快手平台全托管) + +方案E（只发不核） + +(需要和运营沟通，只支持代金卡密类目) + +优点：方案最成熟，功能最完善，接入后券码由isv生成，可以自己定制逻辑，券码生命周期保持跟快手平台同步，并且可以自动化处理退款和券码。 + +缺点：接口数量相对较多 + +接口数量：8-13个 + +优点：在接入方案A的基础之上做减法，只保留基础的发码功能 + +缺点：退款需要在卖家后台处理，主播带货场景需要大量客服小二处理退款，容易造成退款不及时 + +接口数量：6个 + +优点：接入速度最快，仅需接入2个接口，完全由快手平台负责券码的生命周期 + +缺点：不支持卡密 + +接口数量：2个 + +优点：快手平台发码/码库发码，无需开发，运营配置即可使用 + +缺点：无法定制化，完全依赖快手平台已有能力，不支持卡密 + +接口数量：0个 + +优点：只需要接入发码、查询、销毁接口 + +缺点：接入限制多，要和运营沟通确认 + +接口数量：3 + +是否需要开发 + + + +电子凭证通知发码接口 + +integration.virtual.eticket.send + +是 是 否 否 是 +电子凭证发码回调 +integration.callback.virtual.eticket.send +是 是 否 否 是 +订单新增消息 + +kwaishop_order_addOrder + +或 + +获取订单列表v2 + +open.order.cursor.list + +可选 可选 否 否 可选 +新增退款单消息 kwaishop_refund_addRefund + +或 + +售后单列表(游标方式) open.seller.order.refund.pcursor.list + +是 否 否 否 否 +商家同意/不同意退款接口 + +open.seller.order.refund.approve + +open.seller.order.refund.disagree.refund + +是 否 否 否 否 +商家超时未发码，快手发起关单接口 + +或 + +卡券过期，快手发起销毁接口 + +integration.virtual.eticket.destroy + +是 是 +否 + +否 + +是 +电子凭证销毁回调接口 + +integration.callback.virtual.eticket.destroy + +是 是 否 否 否 +电子凭证查询接口 + +integration.virtual.eticket.query + +是 是 否 否 是 +电子凭证冲正回调接口 + +integration.callback.virtual.eticket.reverse + +可选 可选 可选 否 否 +电子凭证核销回调接口 + +integration.callback.virtual.eticket.consume + +是 是 是 否 否 +电子凭证检查电子凭证是否有效 + +open.virtual.eticket.checkavailable + +可选 可选 是 否 否 +通过图商poi获取快手poi详情 + +open.shop.poi.getPoiDetailByOuterPoi + +可选 可选 可选 可选 可选 +商品新增 + +open.item.new + +可选 可选 可选 可选 可选 +商品上下架管理 + +open.item.shelf.status.update + +可选 可选 可选 可选 可选 +商品库存扣减 + +integration.item.stock.deduct + +可选 可选 可选 可选 可选 diff --git a/docs/行业电子凭证/解决方案/业务方案/2.对接流程.md b/docs/行业电子凭证/解决方案/业务方案/2.对接流程.md new file mode 100644 index 00000000..01baa9f7 --- /dev/null +++ b/docs/行业电子凭证/解决方案/业务方案/2.对接流程.md @@ -0,0 +1,46 @@ +对接流程 +更新时间：2025-03-26 +阅读数：9606 +1.对接流程 + 参考案例， + +可见：https://docs.qingque.cn/d/home/eZQBvJqHNtsz2N14vyTrUe_BH?identityId=Ci9gpanFbu#section=h.747sjcxfqui + + 自主测试平台： + +https://gw-merchant-staging.test.gifshow.com/tool/micro + +![alt text](image.png) + +2.对接准备 +商家入驻—开放平台入驻—商品发布—绑定收款账户—联调测试—账单对账，需要按步骤完成所有的对接准备工作，即可进行技术对接 + +2.1.商家入驻 +完成在快手小店的入驻，成为快手商家，详情请见商家入驻：《企业店铺入驻手册-商家侧》 +https://s.kwaixiaodian.com/ + + + +2.2 开发者入驻 +完成在快手电商开放平台的入驻，成为商家开发者，详情请见：《开放平台入驻指南》 + +成为开发者后，创建商家后台应用，详情请见：《开放平台应用开发》，应用创建完成后申请虚拟类目权限 + +https://open.kwaixiaodian.com/ + + + +2.3 发布商品 +商品发布：《虚拟商品发布手册》 + +https://s.kwaixiaodian.com/zone/goods/config/release/add + + + +2.4 绑定账户 +绑定收款账户以及短账期：商家收款账户绑定 + +需要确定俩个账户都绑定成功，才可以进行第六步 + +2.5 账单对账 +账单对账：PC账单使用说明 如需系统对账，请单独联系我们产研同学接口 \ No newline at end of file diff --git a/docs/行业电子凭证/解决方案/业务方案/image.png b/docs/行业电子凭证/解决方案/业务方案/image.png new file mode 100644 index 00000000..804c89eb Binary files /dev/null and b/docs/行业电子凭证/解决方案/业务方案/image.png differ diff --git a/docs/行业电子凭证/解决方案/技术方案/1.基础技术.md b/docs/行业电子凭证/解决方案/技术方案/1.基础技术.md new file mode 100644 index 00000000..e229065b --- /dev/null +++ b/docs/行业电子凭证/解决方案/技术方案/1.基础技术.md @@ -0,0 +1,76 @@ +基础技术 +更新时间：2025-03-26 +阅读数：5722 +本处介绍开放平台的基础协议和通用接入方式 + +1.环境说明 +两套环境相互独立，数据不可相互使用 + +环境 环境地址 说明 +线上环境 https://open.kwaixiaodian.com 线上环境可直接使用 +线下环境 https://gw-merchant-staging.test.gifshow.com 测试环境调用需要提供出口IP，并联系快手对接人添加ip白名单 +2.授权流程 +2.1 如何获取token + 首先需要拿到appkey、appsecret、signSecret信息，线下环境找快手提供，线上环境到“开放平台-控制台-应用中心-应用详情”查看，请求示例如下 +https://gw-merchant-staging.test.gifshow.com/integration/virtual/topup/mobile/order/callback?access_token=ChFvYXV0aC5hY2Nlc3NUb2tlbhJAErnBVtjx5FPdE0AITaSq4xlW6XaTOaV_McGinj-hFivkyxAw1SZ3i28bLEa6xP-C4UuKlRz6uh3lukYRLDcAdRoSeCxQKnQhAPTTL4YL0_NqmqD-IiApwDDKEL1wBW7EbWH0ZRDO3UUNSCxMwkuF7nb57Fn7AygFMAE&appkey=ks683702719562282620&method=integration.virtual.topup.mobile.order.callback¶m=%7B%22orderId%22%3A%22100%22%2C%22businessTime%22%3A%222021-06-08T14%3A16%3A01%2B0800%22%2C%22mobile%22%3A%2215990013607%22%2C%22status%22%3A%22FAILED%22%2C%22amount%22%3A%225000%22%2C%22bizType%22%3A20%7D&signMethod=MD5×tamp=1623132961782&version=1&sign=c091ca3414a9d6429a0fda47c383d202 + +注：如果回调失败需要以指数周期（1m、2m、4m、8m...）重试 + +注意： + +测试环境需要把自己的出口ip给到快手，配置白名单，否则无权限访问。配置对接人：屈国庆，王哲，杨天问 +测试环境和线上环境，是两套token，不可混用。测试token，如下方式获取。线上token通过上面sdk调用，有效期48h。 +Token授权码：参考文档（2.2节 商家开发者角色） +授权一定要用店主的主账号来授权，否则token换取到的sellerId就是子账号的id +线上token验证：https://open.kwaixiaodian.com/commonTool/tokenAuth/accessToken?cateId=0&typeIndex=1，需要快手app扫描登录 +测试环境获取token的步骤（参考文档（2.2节 商家开发者角色））： + +测试环境：优先使用集成中心自己调试 +线上环境：需要按照开放平台的授权文档，通过你的店铺由店主授权(不要用子账号授权)，然后用你的redirect_uri来接收code。 +用授权码code换取长时令牌refreshToken以及访问令牌accessToken + 示例：https://gw-merchant-staging.test.gifshow.com/oauth2/access_token?app_id=ks683702719562282620&app_secret=zSCiWmGOk_diMCU9k3zHcg&grant_type=code&code=bab4f0378269db7a1603de9d5a381615d7d2c451ffbb32f8ede78ac8f05b6171f7d4eb8c + +用长时令牌refreshToken刷新访问令牌accessToken + 示例： +https://gw-merchant-staging.test.gifshow.com/oauth2/refresh_token?app_id=ks683702719562282620&app_secret=zSCiWmGOk_diMCU9k3zHcg&grant_type=refresh_token&refresh_token=ChJvYXV0aC5yZWZyZXNoVG9rZW4SkAGpBE83BKP9TeiwbEP1-IIQL2G08s8rU-OETIzfs5wFN2HeZgUaR_mfGjKHjHzfV-sicHG4IZmxVKlxQhdAZIdf01AR51ZtPN7sHY3eeW6RMnx8LPKo92V1yk-GnkXiiPMWpn9Vmhq0dk_U_aKh5Jwg7mMySO8IEDoz-fPk9Rc2rjUK3inqxNd7rqTQ9fz316oaEsFIUEDt4EyD090nGWRnwQ5g3SIgY-ctBM_4jrFXxBA9EF1jMaP6as57lNYIyOZf9Qlqq64oBTAB + +后面就可以一直用第三步来刷新accessToken + +3.签名算法 +3.1 协议 +https协议，支持GET/POST，调用地址、appkey、signSecret由快手提供，返回结果为json字符串。 + +3.2 签名 +官方签名说明 + +快手电商开放平台的所有开放API调用都需要进行加签，服务端会根据请求参数，对签名进行验证，签名不合法的请求将会被拒绝。当前平台支持的签名算法为MD5(signMethod=MD5) + +下面将详细介绍签名流程： + +对所有API系统参数和请求参数(不包括sign参数和byte[]类型的参数），根据参数名称进行字典顺序排序； + +排序前的顺序是：appkey=ks123，version=1，method=open.xxx.xxx，signMethod=MD5，access_token=xxxx，timestamp=1583271919000，param={"title":"短袖", "relItemId":123456, "categoryId":12} + +排序后的顺序是：appkey=ks123¶m={"categoryId":12,"relItemId":123456,"title":"短袖"}&signMethod=MD5×tamp=1583271919000&version=1&signSecret=abc + + + +保留=符号，用&符号将多个参数及其值组装在一起，根据上面的示例得到的排序结果为：access_token=xxx&appkey=ks123&method=open.xxx.xxx¶m={"title":"短袖", "relItemId":123456, "categoryId":12}&signMethod=MD5×tamp=1583271919000&version=1 + +排序好参数后，在末尾加入signSecret（在应用创建审核通过后由平台分配，在“应用中心-应用列表-应用详情”中可见）进行对应算法的签名计算 + +MD5(access_token=xxx&appkey=ks123&method=open.xxx.xxx.xxx¶m={"title":"短袖", "relItemId":123456, "categoryId":12}&signMethod=MD5×tamp=1583271919000&version=1&signSecret=xxxxxx)=sign + + + +签名加好后，将sign添加到请求参数中，并对param内容进行encode（双引号"和冒号:也需要encode），这里注意请求参数里面是不包括signSecret的，signSecret只是作为加签因子用于签名sign的计算， + +所以千万不要将signSecret当作请求参数传输，请求参数内容见第3点API调用参数说明的表格内容，请求url样例： + +https://open.kwaixiaodian.com/open/xxx/xxx?access_token=xxx&appkey=ks123&method=open.xxx.xxx.xxx¶m=%7B%22title%22%3A%22%E7%9F%AD%E8%A2%96%22%2C%20%22relItemId%22%3A123456%2C%20%22categoryId%22%3A12%7D&version=1&signMethod=MD5×tamp=1583271919000&sign=af2d80958e77e17f1d973003b7b7aec2 +说明：param是json对象，需要排序 + +4.API调用 +确认完成了授权流程后进行API的调用测试，内容详情可见《API调用说明》，也可使用平台提供的API测试工具测试 + +![alt text](image.png) \ No newline at end of file diff --git a/docs/行业电子凭证/解决方案/技术方案/2.对接实战.md b/docs/行业电子凭证/解决方案/技术方案/2.对接实战.md new file mode 100644 index 00000000..06317b8e --- /dev/null +++ b/docs/行业电子凭证/解决方案/技术方案/2.对接实战.md @@ -0,0 +1,167 @@ +对接实践 +更新时间：2025-03-26 +阅读数：8756 +1.对接泳道图 +1.1 接入方案A:全流程接入(推荐方案) +![alt text](image-1.png) +1.2 接入方案B:券码接入 +![alt text](image-2.png) + +1.3 接入方案C: 核销接入 +![alt text](image-3.png) + +注意：由快手发起调用到各位isv的接口如下： +integration.virtual.eticket.send 请看接口文档，SPI 中的 KwaishopVirtualEticketSendService +integration.virtual.eticket.destroy 请看接口文档，SPI 中的 KwaishopDigitalETicketDestoryService +integration.virtual.eticket.query 请看接口文档，SPI中的 KwaishopVirtualEticketQueryService + +注意：对于选择非快手发码的业务，必须要实现ntegration.virtual.eticket.query方法 +快手会在退款操作前主动调用，确保对端没有发码，如果真的没有发码，请您阻拦发货请求，并且返回结果会成功，且返回etickets为空。 +这样快手会主动退款。否则快手会以资金安全为由阻断买家和卖家的退款行为，造成卡单，对isv您所服务的商家造成发货时效延迟，发货失效过长会导致卖家无法让主播分销。 + +1.4 接入方案D: 平台自发码 + 平台发码，无需快手对接核销系统，在商品发布时，”券码发放方式“ 选择 “快手平台发码”即可 + +![alt text](image-4.png) + + + +1.5 可选的接入方案E:商品发布接入POI(选接) + 何为POI：对于地图产品而言，某个地理位置周边的信息，位置数据，称之为 POI (point of information) + + 想接入门店poi？快手当前提供了将百度、腾讯、高德的主流Poi信息转换为快手的Poi，并且在创建商品时关联这些Poi，这样买家浏览商品时就可以看到可用门店。 + + 当需要接入门店时评估接入，可以直接通过快手后台直接完成，也可以通过本方案的接口完成接入，包含2个接口(创建需要把各个图商的Poi转换成快手的Poi)： + + 1. open.shop.poi.getPoiDetailByOuterPoi 通过图商poi获取快手poi详情 + 当前支持的图商：1-高德 2-百度 3-腾讯 + + 2. open.item.new 商品新增接口 + + 请求参数中：poiIds传入，即为带poiId的商品，仅支持快手的Poi + + 快手商品上的poi信息跟卡券核销时的门店信息并没有做关联和强校验，如果需要做可用门店的强校验，请在回传快手核销状态时，接入方自己先做好可用门店的校验。(快手后续会提供对应的功能，请期待) + +2.能力说明(接入必看) +在接入的过程当中可能还会遇到需要查询订单信息、退款信息、结算信息、支付信息等接口，这些接口可以在如下文档按需查看。 + +https://open.kwaixiaodian.com/zone/new/docs/api?apiName=open.seller.order.cps.list&version=1 + +如果需要获取订单列表和退款列表等信息，快手提供了接口查询和消息两种方式，监听快手平台消息的文档如下 +https://open.kwaixiaodian.com/zone/new/docs/msg?msgName=kwaishop_order_addOrder&version=1 + +2.1.卡券发码的有效期 +(1) 怎么计算卡券有效期？ +![alt text](image-5.png) + +途中为商品发布时的卡券有效期选择。从上往下分别为： +固定起止时间、估计结束时间、预定有效天数 + +快手平台会根据商品上的配置自动计算有效期，要求外部isv发码时的有效期保持一致，否则发码失败。isv的有效期开始时间可以比快手平台略早，结束时间比快手平台略晚。 + +建议接入方直接采用快手根据商品上的配置，计算好的券码有效期，双方保持一致，避免出现客诉 + + + +(2) 如果需要关联erp里自己的货品id，可以通过ext大字段中的skuNick字段关联，请联系卖家上架商品时填入 + + + +2.2.什么是货值 +重点知识： + +(1)什么是货值和总货值？ + +订单totalGoodsValue标识电子凭证的总的价值。 + +每张券的goodsValue代表本张券所占的权重。 + +平台会校验所有券的goodsValue之和等于totalGoodsValue，并且按照货值比计算每张券的金额 + + + +业务介绍 场景 totalGoodsValue goodsValue 金额占比 +下单购买1件商品，发出3个电子凭证A B C，消费者支付了10元。 货值相等 3 +A券 goodsValue=1 + +B券 goodsValue1 + +C券 goodsValue=1 + +A券=3.33元 + +B券=3.33元 + +C券=3.34元 + +下单购买1件商品，发出3个电子凭证A B C，消费者支付了10元。 货值相等，但是不可以除尽的情况，需要最后一张做倒减 100 +A券 goodsValue=33 + +B券 goodsValue=33 + +C券 goodsValue=34 + +A券=3.33元 + +B券=3.33元 + +C券=3.34元 + +下单购买1件商品，发出3个电子凭证A B C，消费者支付了10元。 货值不相等 100 +A券 goodsValue=10 + +B券 goodsValue=20 + +C券 goodsValue= 70 + +A券=1元 + +B券=2元 + +C券=7元 + + + +2.3.未发货自动关闭订单，货款退回给买家的情况说明 + 快手为了保护买卖家的钱款安全，在快手发现您未能及时给买家发货(默认48小时)，会主动关闭订单将钱款退回给买家 + + 在操作钱款前，快手会主动触发KwaishopVirtualEticketQueryService(电子凭证查询发码结果或券码状态)接口，如果该接口抛出异常，或者查出卡券不为空，则会中断流程，详细处理方式如下： + +接口 您的返回结果 快手的处理方式 建议服务商的处理方式 +KwaishopVirtualEticketQueryService(电子凭证查询发码结果或券码状态) success为1 ，卡券列表为空 快手认为您的确未发券，自动关闭订单。(正常处理流程) 不用处理 +KwaishopVirtualEticketQueryService(电子凭证查询发码结果或券码状态) success不为1 ，或者抛出异常 +快手认为您服务挂了，暂缓关闭订单，退钱给买家的操作。订单卡住。 + +(异常处理流程)会影响您店铺的平均发货时长，店铺指标下降。 + +返回正确的接口，参考success为1的上诉场景 + +KwaishopVirtualEticketQueryService(电子凭证查询发码结果或券码状态) success为1 ，且返回了卡券 快手认为您那边发了货，但是没回传给快手，暂时中断发货流程，等您补发卡券 +1. 通过发码回调接口，把码发送给快手。 + +2. 联系运营，关闭这一批异常订单。 + + + +2.4.过期自动退款场景，快手发起作废和退款的情况说明 + 当卡券被发放给买家后，就会开始计算有效期，当有效期时间到，快手会优先锁定快手内的卡券的状态，进入到销毁中(此处在快手内卡券不可使用)，然后通过KwaishopDigitalETicketDestoryService(电子凭证发起销毁接口)通知服务商，此时KwaishopDigitalETicketDestoryService接口中的reason字段固定为："ETICKET_EXPIRED"。此类请求的含义为：当前卡券已经过期了，请服务商也销毁您那边的卡券。 + + 主动发起退款场景，如果您48小时未处理卡券，将会自动同意退款，卡券只能一次性处理所有卡券，不能仅销毁成功其中一张。 + + + +接口 服务商的后置请求 快手的处理方式 建议服务商的处理方式 +快手了KwaishopDigitalETicketDestoryService接口以后 KwaishopDigitalETicketDestoryService接口返回受理成功，并且调用。“integration.callback.virtual.eticket.destroy”接口，reason回传给快手的也是ETICKET_EXPIRED 这种场景，快手侧的卡券和服务商的卡券均已销毁 +快手立即触发退款，将钱退给买家。(正确场景) 无需修改 +快手了KwaishopDigitalETicketDestoryService接口以后 +KwaishopDigitalETicketDestoryService接口24小时未受理成功，或者24小时内未回传快手 + +这种场景，快手侧认为是服务商超时未处理过去卡券， + +24小时候强制将钱退给买家。(有资损风险) + +改成正确的方式 + + +2.5 什么是卡券结算(可选) + 需要您在店铺开通对应的门店结算能力，既卡券核销一张既结算一张，并且钱会独立结算给核销的门店，需要您的各个门店在快手上绑定，并且有独立的结算账户。金额会按照您配置好的门店结算给独立的门店账户。 \ No newline at end of file diff --git a/docs/行业电子凭证/解决方案/技术方案/3.接口文档.md b/docs/行业电子凭证/解决方案/技术方案/3.接口文档.md new file mode 100644 index 00000000..5c45fbfa --- /dev/null +++ b/docs/行业电子凭证/解决方案/技术方案/3.接口文档.md @@ -0,0 +1,45 @@ +接口文档 +更新时间：2025-03-26 +阅读数：6374 +API +类目 名称 展示名 操作 +订单 open.order.cursor.list 获取订单列表v2 查看 +订单 open.seller.order.close 关闭订单 查看 +订单 open.seller.order.fee.detail 获取订单费用详情 查看 +订单 open.order.detail 订单详情v2 查看 +退款 open.seller.order.refund.detail 售后单详情 查看 +退款 open.seller.order.refund.fee.detail 退款单退款费用详情 查看 +退款 open.seller.order.refund.approve 商家同意退款 查看 +退款 open.seller.order.refund.pcursor.list 售后单列表(游标方式) 查看 +退款 open.seller.order.refund.disagree.refund 商家不同意退款 查看 +商品 open.item.get 获取商品详情 查看 +商品 open.item.new 商品新增（新） 查看 +商品 open.item.edit 编辑商品（新） 查看 +商品 integration.item.stock.deduct 商品库存扣减 查看 +商品 integration.item.stock.query 商品库存查询 查看 +商品 open.item.shelf.status.update 商品上下架管理 查看 +商品 open.item.list.get 查询商品列表 查看 +店铺 open.shop.poi.getPoiDetailByOuterPoi 通过图商poi获取快手poi详情 查看 +虚拟 integration.callback.virtual.eticket.send 电子凭证发货回调接口 查看 +虚拟 integration.callback.virtual.eticket.consume 电子凭证核销回调接口 查看 +虚拟 integration.callback.virtual.eticket.reverse 电子凭证冲正回调接口 查看 +虚拟 integration.callback.virtual.eticket.destroy 电子凭证销毁回调接口 查看 +虚拟 open.virtual.eticket.checkavailable 电子凭证检查电子凭证是否有效 查看 + + +消息 +类目 名称 展示名 操作 +退款 kwaishop_refund_addRefund 新增退款单消息 查看 +退款 kwaishop_refund_updateRefund 退款单更新消息 查看 +订单 kwaishop_order_addOrder 订单新增消息 查看 +订单 kwaishop_order_statusChange 订单状态变更消息 查看 +订单 kwaishop_order_totalFeeChange 订单费用变更消息 查看 +订单 kwaishop_order_addNote 订单备注消息 查看 +SPI +类目 名称 展示名 操作 +虚拟 KwaishopVirtualEticketSendService 快手电子凭证通知发货 查看 +虚拟 KwaishopVirtualEticketQueryService 电子凭证查询发码结果或券码状态 查看 +虚拟 KwaishopDigitalETicketDestoryService 电子凭证发起销毁接口 查看 + + + \ No newline at end of file diff --git a/docs/行业电子凭证/解决方案/技术方案/image-1.png b/docs/行业电子凭证/解决方案/技术方案/image-1.png new file mode 100644 index 00000000..1908b581 Binary files /dev/null and b/docs/行业电子凭证/解决方案/技术方案/image-1.png differ diff --git a/docs/行业电子凭证/解决方案/技术方案/image-2.png b/docs/行业电子凭证/解决方案/技术方案/image-2.png new file mode 100644 index 00000000..b942cf1d Binary files /dev/null and b/docs/行业电子凭证/解决方案/技术方案/image-2.png differ diff --git a/docs/行业电子凭证/解决方案/技术方案/image-3.png b/docs/行业电子凭证/解决方案/技术方案/image-3.png new file mode 100644 index 00000000..e618f61d Binary files /dev/null and b/docs/行业电子凭证/解决方案/技术方案/image-3.png differ diff --git a/docs/行业电子凭证/解决方案/技术方案/image-4.png b/docs/行业电子凭证/解决方案/技术方案/image-4.png new file mode 100644 index 00000000..b4461c64 Binary files /dev/null and b/docs/行业电子凭证/解决方案/技术方案/image-4.png differ diff --git a/docs/行业电子凭证/解决方案/技术方案/image-5.png b/docs/行业电子凭证/解决方案/技术方案/image-5.png new file mode 100644 index 00000000..a6e9296d Binary files /dev/null and b/docs/行业电子凭证/解决方案/技术方案/image-5.png differ diff --git a/docs/行业电子凭证/解决方案/技术方案/image.png b/docs/行业电子凭证/解决方案/技术方案/image.png new file mode 100644 index 00000000..1d90660c Binary files /dev/null and b/docs/行业电子凭证/解决方案/技术方案/image.png differ