抖音开放平台Logo
开发者文档
“/”唤起搜索
控制台
  • 生活服务商家应用 OpenAPI SDK 总览
  • 能力
  • 基础能力
  • 历史版本文档(不推荐使用)
  • 酒店日历房能力
  • 度假预售券能力
  • 景区日历票能力
  • 酒店预售券能力
  • 预置码
  • OpenAPI
  • 历史版本文档(不推荐)
  • 能力背景

    过抖音已有的底层交互的接口体系构建,在此基础上对外开放住宿类预售券的 openAPI,使更多的 SaaS 服务商、渠道商家能够自行接入,将商户预售商品资源快速接入到抖音。

    功能流程简介

    模式概述

    无券能力的Saas服务商
    能力的Saas服务商
    概述
    酒店对接多个售卖渠道,通过switch服务商实现数据往返。
    云PMS/Saas居多。
    特点/差异点
    是否有券能力
    无券能力:
    此类商户(或对接方)使用的Saas中,仅可将日历房类的产品直连至抖音。
    因此商户如果需要上线券类产品,需要通过商家端自行上单,在上单同时选择券类产品的可用范围(可用产品来自于直连链路)。
    有券能力:
    此类为商户提供的Saas中,可以管理券+房。
    因此在对接时,对方可将Saas系统内已经定义好的券+日历房产品直连至抖音。
    上单差异
      1.商户上单为认领模式。
      2.在商家端配置预售券、预定商品信息从服务商获取。
      1.商户上单需为认领模式。
      2.券商品信息可直接通过服务商同步至抖音 预定商品信息从服务商获取。
    结算差异
    结算款直接结算给商户(酒店)。
    结算款直接结算给商户(酒店)。

    底层系统交互流程

    1、无券能力的 Saas 服务商:
    2、有券能力的 Saas 服务商:

    概念说明:
    房型级房量:该房型的物理房量,在没有产品级别房量的情况下该房量映射到所有关联产品。
    产品级房量:只适用于指定房型+房价的房量,该房量与对应房型的其他关联产品无关。
    RP: RP = ratePlan, 即售卖计划,包含:支付方式、早餐、内外宾、退订规则等。
    SPU(物理房型):SPU = Standard Product Unit (标准产品单位),SPU 是商品信息聚合的最小单位;酒旅行业就是物理房型。 房型包含 面积、可入住人数、窗型、有无 wifi、床型等。
    Product:SPU + RP。
    SKU:SKU=stock keeping unit ( 库存量单位 ),SKU 即库存进出计量的单位。 Product + 价量态日历。
    静态信息:
      酒店,酒店相关整体介绍的信息。包括了酒店地址,公共设施,评级等介绍。
      SPU。
      RP。
    动态信息:日历化产品的价格,房态及产品级别房量,房型级别房量。
    预定商品:
      对酒旅,是指我们从技术服务商获取得房型信息(房间面积、有无 wifi 、房间照片等)+ rp 。
      对 KTV,是指商家在抖音来客系统设置完包房&时间段 的关联产品;
    预售商品:抖音来客商品列表(审核通过)的数据。与 C 端货架展示的数据一致。泛指预售券。

    接入前期准备

    step.0 整体流程

    该部分步骤,详细可以参考技术服务商接入指南:https://partner.open-douyin.com/docs/resource/zh-CN/local-life/guide/guide

    step.1 入驻服务商平台

    未入驻或已入驻但无生活服务应用

    未入驻抖音服务商平台的服务商或已入驻抖音服务商平台但无正式应用的技术服务商,按以下流程直接入驻服务商平台并开展业务。
    第一步:登录抖音服务商平台
    第二步:通过邮箱或手机号注册账号,注册成功后进入控制台。
    第三步:完成入驻流程,并开通「第三方应用代开发」。
    第四步:填写基础信息。
    第五步:填写经营信息。
    注意:依据认证不同的服务能力,要求的填写字段存在差异,支持多选,认证「第三方应用代开发」能力,需上传应用工具相关介绍。
    第六步:等待平台审核反馈通知。
    平台一般在 10 个工作日内完成审核。
    第七步:平台审核通过后,进行对公认证。
    平台为开发者提供了五种对公验证的方式,可依据自身情况选择验证形式。

    step.2 获取 ClientKey&ClientSecret

    创建第三方生活服务商家应用

    填写相关信息,创建应用。
    应用创建成功后,可进入应用详情页查看 ClientKey&ClientSecret:
    等待应用审核完成。审核时效 3 个工作日。

    step.3 生成 access_token

    通过请求参数 ClientKey&ClientSecret 调用 /oauth/client_token/ 生成的 token,此 token 不需要用户授权。示例: clt.943da17996fb5cebfbc70c044c3fc25a57T54D。
    注意:需每 2 小时更新。

    step.4 开通应用的解决方案

    在应用详情中,点击解决方案,选择对应的解决方案申请开通。审核时效 3 个工作日。
    需要申请的能力包括:
    门店管理 / 订单查询 / SPU 信息发布 / 商品查询 / 商品发布 / 日历属性发布 / 预订信息查询 /交易闭环预约:

    step.5 服务商/商家回调地址配置

    回调接口类型
    回调接口文档
    接口地址
    配置方式
    对接说明
    SPI接口
    接口地址由服务商/商家提供
    开放平台-服务商平台/开发者平台-控制台-应用详情页-开发设置-SPI 回调
    Webhook通知
    技术服务商/自研商家需通过表格提交给抖音侧完成配置

    step.6 抖音来客测试账号申请

    需要提前向抖音侧申请提供,根据测试账号获得测试 token。

    step.7 商家入驻抖音来客

    首先确保商家已经入驻抖音来客,并完成 POI 的认领:https://life.douyin.com/

    step.8 商家在抖音来客做授权

    授权行业:酒店解决方案。
    授权权限:门店管理 / 订单查询 / SPU 信息发布 / 商品查询 / 商品发布 / 日历属性发布 / 预订信息查询。

    接口开发

    创建预售券&创建预约单元

    1、业务流程

    2、对接接口

    接口
    接口路径
    调用方
    注意事项
    保存SPU(物理房型)接口
    商家/服务商
      创建或更新SPU
      product_type商品类型:13,预订
      对于同一服务商,相同的out_spu_id会被认为是同一SPU,重复创建会被覆盖
      SPU属性,需要通过模板获取
    查询商品模板
    商家/服务商
      查询商品模板,创建商品时的属性列表需与该接口保持一致,否则无法识别
      类目需要与抖音侧对接人确认。
      attr_key_value_map的格式,见下文专门介绍部分
    创建/更新商品接口(预订商品和预售商品)
    商家/服务商
      创建或更新商品
      对于同一服务商,相同的out_id会被认为是同一商品,重复创建会被覆盖
      商品和SKU属性,需要通过模板获取
      顺序:先上预订商品,再上预售商品,上预售商品时通过bind_skus字段关联
      spu_id,关联的SPU ID,由创建接口返回,product_type=13时必填
      团购类型: 12: 新预售 13: 预定
      actual_amount、stock,创建预售商品为必传,创建预定商品时非必传
      bind_skus,新预售商品对应的预定商品SKU ID列表,product_type=12时必填,其他类型不可填,必须是有效的预定商品SKU ID
      注意:如果预售券为多预订商品多门店的通兑券,则需要在bind_skus中绑定多门店的预订商品,且在「pois」(适用门店)字段中传入对应预订商品所属的POI_IDs。
    查询商品数据(含基础信息)
    商家/服务商
      使用商品ID或外部商品ID查询商品草稿
      处于新建审核中、修改审核中、或审核成功、失败的数据可以通过该接口查询到
      一次最多查询10个草稿数据
    保存日历属性
    商家/服务商
      创建或更新商品日历
      需要在创建了酒旅预定商品后调用
      Calendar属性,需要通过模板获取
    保存日历库存(房态房量)
    商家/服务商
      创建或更新商品日历库存
      需要在创建了酒旅预定商品后调用
      stock_qty,总库存可以为0
    保存日历价格接口(房价)
    商家/服务商
      创建或更新商品日历价格
      需要在创建了酒旅预定商品后调用
    商品审核结果通知
    抖音

    3、attr_key_value_map 的格式

    attr_key_value_map:
    {
    [必填] breakfast_num int // 表示早餐数量, 枚举值为:-1:按人头含早,0:无早、1:单早、2:双早
    [必填] guest_type list // 接待客人类型 枚举值为:[1] 内宾,[2]外宾, [1,2] 内宾+外滨
    [必填] pre_order_rule: { // 预定规则
    [必填] time_type int // 1:绝对时间 2:提前时间
    soonest_order_time int // 最早预约时间
    soonest_order_sec_offset int // 最早预约提前时间(秒)
    latest_order_time int // 最晚预约时间
    latest_order_sec_offset int // 最晚预约提前时间(单位:秒)
    start_time string // 开始销售时间 e.g.: 08:00:00
    end_time string // 结束销售时间 e.g.: 19:00:00
    }
    }
    其中:
    time_type 传了 1 的话,则必须传 soonest_order_time 或 latest_order_time
    time_type 传了 2 的话,则必须传 soonest_order_sec_offset 或 latest_order_sec_offset
    备注 PreOrderRuleStruct 结构体:
    struct PreOrderRuleStruct { 1: required i64 time_type // 1-绝对时间 2-提前时间 2: optional i64 soonest_order_time // 最早预约时间 3: optional i64 soonest_order_sec_offset // 最早预约提前时间(单位:秒) 4: optional i64 latest_order_time // 最晚预约时间 5: optional i64 latest_order_sec_offset // 最晚预约提前时间(单位:秒) 6: optional string start_time // 开始销售时间 e.g.: 08:00:00 7: optional string end_time // 结束销售时间 e.g.: 19:00:00 }
    根据「查询商品模板」查出的模板,可以看到该行业该类型下的商品对应的可传的相关属性,技术需要关心的字段主要是以下几个:
      key - 属性主键,attr_key_value_map的key是什么
      is_required - 是否必传
      is_multi - 是否列表,需要和value_type组合起来看。例如:value_type=STRING(表示字符串,具体参见下文),is_multi=true,则表示value是一个字符串列表(也就是list)类型;value_type=IMAGE(表示图片控件,具体参见下文),is_multi=true,则表示value是一个图片控件结构体列表(也就是list)类型;
      value_type - attr_key_value_map的value类型,枚举可参见后文的表格。
    attr_key_value_map 的类型是 map<string,string>,如果 value_type 为其他值类型需转换为 string:
      value_type为整数/浮点数:转为十进制格式的string
      value_type为布尔值:转为"true"或"false"
      value_type为结构体或结构体列表:需要使用json序列化

    交易流程

    1、业务流程

    2、对接接口

    接口
    接口路径
    调用方
    注意事项
    下单接口(预售券)
    抖音
      抖音侧调用第三方服务商接口推送用户下单消息,返回结果
    支付结果通知(预售券)
    抖音
      抖音侧调用第三方服务商接口触达第三方服务商推送支付成功消息通知,返回结果
    预约单试单
    抖音
      status,支付状态,枚举:SUCCESS-成功,CANCEL-取消(取消通知售后触发)
    创建预约单
    抖音
      抖音侧调用第三方服务商接口创建抖音住宿的预约单
    取消预约单
    抖音
      抖音侧调用第三方服务商接口触达第三方服务商推送订单取消通知,返回结果
    退款成功状态通知(预售券)
    抖音
      抖音侧异步发起退款状态通知,实现为调用 Saas 开放平台接口通知 Saas 服务商退款完成信息。
    查询预约单
    商家/服务商
      对于第三方服务商需要查询抖音住宿的预约单信息

    FAQ

    1、准备阶段常见问题

    问题
    解答
    是否可提供抖音来客测试账号?
    可以提供测试账号,需提供对应公司: 企业名称、手机号/邮箱,
    测试账号如需延期,应该如何操作?
    可联系抖音侧提出相应申请
    如何配置回调地址
    暂时需商家手工填写,提交抖音侧配置。
    如在调用接口中返回测试账号token失效,怎么办?
    如遇到此类问题,可以在对接群里反馈给对应抖音同学,进行相关处理

    2、创建预售券&创建预约单元模块常见问题

    问题
    解答
    stock库存相关设置说明
    库存信息在创建预售商品时为必传,创建预定商品时非必传; 库存上限类型limit_typelimit_type,1-有限库存 2-无限库存,值为2时,总库存stock_qty字段 和 可用库存avail_qty 字段无意义
    origin_amount原价字段定义说明
    字段定义为原价,但在预售券商品创建时,由commodity属性中的价格自动计算原价,也就是会根据商品搭配进行对应计算,故此字段可填写0
    我们这边有些产品没有设置原价,只有售卖价格,我看文档要求origin_amount(原价)必传,这种情况我就传和实际价格一致,可以吗?
    可以,如此设置,线上展示则不会有划线价
    创建预售商品如遇返回“当前门店非正常营业”怎么办?
    这种情况可以在对接群中反馈给抖音同学,由抖音技术同学统一操作处理(poi上线)
    创建预售\预订商品失败可能是什么原因?
    可以优先检查下有没有给三方的商品id,即out_id字段为必填
    apply_room_mum与apply_night目前商品模板返回说明都是“包含间数”,二者有什么区别?
    apply_room_mum为 包含间数
    apply_night为 包含间夜
    系统返回的正确修正会在10月内完成调整
    商品属性KV中,返回的房型面积,是否可以支持区间?
    暂时不支持区间,只能是单一数值
    商品属性KV中,返回的床型,是否可以支持多选?
    床型类型不支持多种,仅支持一种床型
    商品接口中,预订商品推送日历类产品,product_type选什么?
    此产品与日历房没有直接关系,预订商品product_type均为13。
    商品接口中的product,与SKU以及商家的Rate_Plan是什么关系?
    product 和sku是1:1的关系,spu+rp=product
    日历保存价量态的接口,是否有频控?
    暂时没有频控,同一商品同时只能有一个请求在处理
    推送房价接口,价格单位是元还是分?
    单位:分
    下架rp后,抖音后台仍能够关联到对应产品,怎么办?
    这个问题已经定位,在尚未优化完成前,商家请不勾选已下架产品即可。
    另外下架rp抖音这边目前没有限制,所以需要谨慎操作,如果遇到该产品仍在使用期,且已经售卖,但商家在直客通操作下架,会造成已购买的用户无法预约,形成客诉,损失订单。
    创建预售券商品时,关联预订商品,但对应房型图片不展示
    目前关联预订商品模块中的图片暂时无法支持展示,这个需求会在后续迭代中优化解决。

    3、交易模块常见问题

    问题
    解答
    预约下单失败的重试,抖音会重试多少次?
    抖音侧目前的接口下单等待时间是3s,但是会在30分钟内,重试多次;
    如果服务商有明确的错误返回,抖音侧则不会重试。
    订单取消接口的调用规则是什么?
    目前抖音在商品预约成功后,只支持客服取消,客服取消时会调你们接口,不过抖音客服逻辑是强制取消,无论你们那边返回成功与否,抖音侧都会变成取消。不过客服会保证线下和商家沟通确认后再进行取消操作。
    取消规则具体值有哪些?
    "struct CustomPolicyStruct {
    1: required i64 policy_rule_type // 规则类型
    2: optional string policy_value // 规则值
    3: optional NoteStruct note //规则描述
    }"
    现在只支持 "预定后不可取消" 这一种。 对应传值为 policy_rule_type=2,policy_value不用传
    预约试单和取消预约单接口,成功响应码我们填什么?
    成功code=0
    创建预约单,我们是否可以以预约单作为幂等条件?
    可以

    4、线上验证常见问题

    问题
    解答
    测试账号创建的预售券商品如何审核?
    预售券商品审核,可以提交对应商品id给抖音同学进行内部操作 需注意:预订商品无审核流程,预售券商品才需要审核。
    正式接入商家的商品,可否协助审核?
    正式商家的线上商品审核需要走统一队列,无特殊审核渠道
    已完成预售商品创建及审核,如何在抖音前台找到对应商品进行下单?
    审核通过的商品,在【抖音来客】后台,商品管理模块可查看到。可点击对应操作模块中-更多,生成二维码,用抖音app进行扫码,便可进入对应商品页。
    如在预售券购买过程中提示系统开小差,怎么办?
    此问题涉及的可能性较多,需服务商提供对应预售券商品id给到抖音侧,进行相关协查。
    常见可能性:
      1.poi未线上化,无法下单
      2.ppe环境poi和线上存在不一致
      3.如果只是个别商品购买报错,可能是测试商品创建在效率平台审核时,poi是ppe可见状态 可以找@尹嘉辉 修复
    如在预约过程中,遇到日历均不可预约怎么办?
    遇到此类问题的原因大多是库存传输问题导致,可优先检查库存数量以及预售券售卖规则(如连住几晚)是否互相满足。如还有问题,可提供对应product_id给到抖音对接同学协助排查。
    如在预约过程中,遇到提示“房型信息发生变更”提示,怎么办?
    此问题可能性较多,目前只要抖音后端处理报错,用户都看到的是这个错误。服务商可提供对应订单号或商品id给抖音侧进行排查
    线上商家如何进行链路测试?
    目前抖音侧线上商家测试均需要在线上完成,对应商品创建、预约完成后,取消订单也需要走一下客服流程处理退款。