接入前准备

通用能力

餐饮

大交通

酒旅

酒店行业新预售券解决方案

酒店行业日历房解决方案

度假行业解决方案

景区行业解决方案

景区创建订单

景区订单状态查询

景区回调审核退款

景区履约验券

景区确认订单

景区取消订单通知

景区退款结果通知

景区退款审核

景区支付通知

景区预订信息校验

日历票价格库存属性发布

日历票商品查询

三方码发布

发券回调接口

发放凭证（SPI）

日历票商品发布

团购核销

门店管理

景区日历票商品类目

通用错误码

综合

历史版本文档（不推荐）

发放凭证（SPI）

我的收藏

接口说明

三方码发券SPI,抖音通知三方发码，如果为同步发码则返回三方码，异步发码则根据发码通知的凭证单的映射关系异步发放三方码

•

对接方需保证，当凭证回调给抖音成功后才可用。用户才能入园

•

抖音侧服务商接单成功后后向服务商发起发放凭证申请。

•

同步发码在10min请求不到服务商的码则会自动退货并发起退款流程

◦

如果同步无法完成发码，可接入异步链路

基本信息

研发同学填写

HTTP URL	地址由服务商提供
HTTP Method	抖音侧向开发者侧发起POST类型的请求，请求超时时间 8s
权限要求	需要申请权限，路径：抖音开放平台-服务商平台>控制台>应用详情>解决方案需要url配置，路径：联系抖音对接技术人员，做配置需要商家授权，路径：抖音来客>店铺管理>第三方应用授权

请求头

•

Content-Type：application/json

•

X-Bytedance-Logid: 请求logid，用于问题排查用

•

x-life-clientkey: 服务商应用的client_key

•

X-life-sign: 请求签名，签名规则

请求体

参数名称	参数类型	参数描述	必需	是否加密
order_id	string	抖音侧的订单号	是
count	int	每份出行人数，商品多个适用人群的crowd_num总和，比如家庭票一份包含了多个人，非家庭票只有一个出行人	是
start_time	int	预约开始时间，时间戳，秒	是
expire_time	int	预约截至时间，时间戳，秒	是
sku	object	商品信息	是
.sku_name	string	抖音商品名	是
.sku_id	string	抖音的商品ID	是
.third_sku_id	string	三方服务商侧的商品ID	是
amount	struct	金额信息	否
.original_amount	int	原始金额,单位分	否
.pay_amount	int	用户实付金额,单位分	否
.ticket_amount	int	平台营销金额,单位分	否
.merchant_ticket_amount	int	商家营销金额,单位分	否
.fee_amount	int	支付手续费，单位分	否
.commission_amount	int	达人分佣金额，单位分	否
.payment_discount_amount	in	支付优惠金额，单位分，平台补贴的一种	否
.coupon_pay_amount	int	券实付金额（=用户实付金额+支付优惠金额），单位分	否
tourists	list(object)	出行人信息	否
.name	string	姓名	否
.phone	string	联系电话	否
.id_card	string	身份证号码	否
.credential_type	int	证件类型 1 // 身份证 2 // 港澳通行证 3 //台湾通行证 4 //回乡证 5 //台胞证 6 //护照 7 外籍护照 8 外国人永久居留证
copies	int	购买份数，一单买3份，传的就是3，与回传的vouchers集合size对应	否

金额说明：

（1）商家实收（抽佣前）=原始金额-商家营销金额；

（2）商家实收（抽佣后）此接口不提供；

（3）平台营销金额：平台补贴的金额；

（4）支付优惠金额：使用平台支付优惠的平台补贴金额。

请求示例

•

全部游玩人，商品属性 reserved_type = 3（tourists 个数等于 copies x count）

{    
    "order_id":"12345678",
    "count":1,
    "sku_id":"23456",
    "third_sku_id":"345678",
    "sku": {
        "sku_id": "23456",
        "sku_name": "虹口漂流多人票",
        "third_sku_id": "23785"
    },
    "amount":{
        "original_amount":10000,
        "pay_amount":8000,
        "ticket_amount":1000,
        "merchant_ticket_amount":1000,
        "payment_discount_amount":1000,
        "coupon_pay_amount":1000
    },
    "tourists":[
        {
            "name":"张三",
            "phone":"13800000000",
            "id_card":"310115199807013370"
        },
        {
            "name":"李四",
            "phone":"13900000000",
            "id_card":"310115199912130020"
        }
    ],
    "start_time":1664553600,
    "expire_time":1665158399,
    "copies":2
}

•

一单一人（tourists 个数等于1）

{    
    "order_id":"12345678",
    "count":2,
    "sku_id":"23456",
    "third_sku_id":"345678",
    "amount":{
        "original_amount":10000,
        "pay_amount":8000,
        "ticket_amount":1000,
        "merchant_ticket_amount":1000,
        "payment_discount_amount":1000,
        "coupon_pay_amount":1000
    },
    "tourists":[
        {
            "name":"张三",
            "phone":"13800000000",
            "id_card":"310115199807013370"
        }
    ],
    "start_time":1664553600,
    "expire_time":1665158399,
    "copies":3
}

响应参数

字段名称	字段类型	字段描述
data	object
.error_code	int64	接口错误码	是
.description	string	接口错误描述	是
.result	int	发码结果. 0:发码中 1:成功 2:失败	是
.fail_reason	string	失败原因	否
.vouchers	list	凭证列表	否
..entrance	struct	景区的入园项目（若入园凭证是单独的凭证，则使用此字段用来传入园凭证。若不是单独的凭证，可使用自定义项目的字段传入）	否
...project_id	string	入园项目的唯一标识，同一个订单下不能重复（核销时需要）	是
~~...id_cards~~	~~list<string>~~	~~身份证号码，最多限100个~~	否
...qrcodes	list<string>	二维码凭证内容，会生成二维码展示，每个字符串长度不能超过512。	否
...certificate_nos	list<string>	券号凭证，最多限100个	否
...gmcode_imgs	list<string>	GM码数据流base64字符串列表。单个图片大小限制1M以内。（若使用图片数据流，则不支持使用qrcodes传二维码凭证内容，长度不超过512）	否
...urls	list<string>	链接凭证，在C端直接展示此链接，最多XX个	否
...credentials	list<object>	证件列表	否
....credential_type	int	凭证类型 1:身份证 2:港澳通行证 3:台湾通行证 4:回乡证 5:台胞证 6:护照 7 外籍护照 8 外国人永久居留证	否
....credential_no	string	凭证号	否
..projects	list<object>	可自定义的项目（例：景区项目索道A、索道B等）	否
...project_id	string	园内项目的唯一标识，同一个订单下不能重复（核销时需要）	是
...name	string	自定义的项目名称（例：景区XXXX索道）	是
~~...id_cards~~	~~list<string>~~	~~身份证号码，最多限100个~~	否
...qrcodes	list<string>	二维码凭证，展示为二维码，每个URL长度不能超过512。	否
...certificate_nos	list<string>	券号凭证，在C端展示为数字串，最多限100个	否
...gmcode_imgs	list<string>	GM码数据流base64字符串列表。单个图片大小限制1M以内。（若使用图片数据流，则不支持使用qrcodes传二维码凭证内容）	否
...urls	list<string>	链接凭证，在C端直接展示此链接，最多XX个	否
...credentials	list<object>	证件列表	否
....credential_type	int	凭证类型 1:身份证 2:港澳通行证 3:台湾通行证 4:回乡证 5:台胞证 6:护照 7 外籍护照 8 外国人永久居留证	否
....credential_no	string	凭证号	否

发码结果

发码中，则必须十分钟内通过凭证回调接口回调抖音侧告知结果，否则会自动取消预约

发码成功，则必须在响应中直接返回正确的凭证 (后面不需要回调)

发码失败，

接口请求成功时务必确保 error_code=0, 发放券码的结果通过 data.result 字段返回。

ii.

若 error_code 不为 0，不处理 data 中的数据，抖音会十分钟内多次重试发券请求。

凭证

entrance和projects不能同时都为空

id_cards、qrcodes、certificate_nos不能同时都为空，与商品的code_sending_info属性对应

code_sending_info必须要配置才能回传，凭证方式可以全部配置，无需回传所有凭证，至少回传任一凭证即可，但是不允许出现如未配置身份证，但是回传了身份证这种case

id_cards、qrcodes、certificate_nos返回的各自集合长度不能超过请求的count

如果请求带了tourists，则返回的id_cards集合身份证信息必须包含在tourists中

vouchers的size需要与发码请求的copies大小一致，copies代表一单买了几份

注意copies和count是2个不同的概念

订单维度project_id需要唯一，不能重复

gmcode_imgs 仅需要数据部分，如：“iVBORw...Jggg==”，无需前置格式信息（如：“data:image/jpeg;base64,”）。

id_cards 字段已废弃，使用credential_type、credentials传输证件类型和证件号

回传失败排查：日历票服务商对接凭证问题排查

响应示例

可在后续验收时进行补充，验收文档示例（复制后使用）

正常示例

•

发码中

{
  "data": {
    "error_code": 0,
    "description": "success",
    "result": 0
  }
}

•

发码成功

◦

1单1份（每份1个出行人，只包含门票，凭证类型为身份证）

{
  "data": {
    "error_code": 0,
    "description": "success",
    "result": 1,
    "vouchers": [
      {
        "entrance": {
          "project_id": "1",
          "credentials": [
          {
              "credential_type": 1,
              "credential_no":"310115199807013370"
          }
          ]
        }
      }
    ]
  }
}

◦

1单1份（每份1个出行人，只包含门票，凭证类型为身份证+券码）

{
  "data": {
    "error_code": 0,
    "description": "success",
    "result": 1,
    "vouchers": [
      {
        "entrance": {
          "project_id": "1",
          "credentials": [
          {
              "credential_type": 1,
              "credential_no":"310115199807013370"
          }
          ],
          "qrcodes": [
            "qr_code1_096700560961"
          ]
        }
      }
    ]
  }
}

◦

1单1份（每份1个出行人，只包含门票）

{
  "data": {
    "error_code": 0,
    "description": "success",
    "result": 1,
    "vouchers": [
      {
        "entrance": {
          "project_id": "1",
          "credentials": [
          {
              "credential_type": 1,
              "credential_no":"310115199807013370"
          }
          ],
          "qrcodes": [
            "qr_code1_096700560961"
          ],
          "certificate_nos": [
            "a_096700560961"
          ]
        }
      }
    ]
  }
}

◦

1单1份（每份1个出行人，包含门票+园内项目）

{
  "data": {
    "error_code": 0,
    "description": "success",
    "result": 1,
    "vouchers": [
      {
        "entrance": {
          "project_id": "1",
          "credentials": [
          {
              "credential_type": 1,
              "credential_no":"310115199807013370"
          }
          ],
          "qrcodes": [
            "qr_code1_096700560961"
          ],
          "certificate_nos": [
            "a_096700560961"
          ]
        },
        "projects": [
          {
            "name": "园内项目A",
            "project_id": "2",
          "credentials": [
          {
              "credential_type": 1,
              "credential_no":"310115199807013370"
          }
          ],
            "qrcodes": [
              "qr_code2_806011925184"
            ],
            "certificate_nos": [
              "b_806011925184"
            ]
          }
        ]
      }
    ]
  }
}

◦

1单2份（每份1个出行人，包含门票+园内项目）

{
  "data": {
    "error_code": 0,
    "description": "success",
    "result": 1,
    "vouchers": [
      {
        "entrance": {
          "project_id": "1",
          "credentials": [
          {
              "credential_type": 1,
              "credential_no":"310115199807013370"
          }
          ],
          "qrcodes": [
            "qr_code1_096700560961"
          ],
          "certificate_nos": [
            "a_096700560961"
          ]
        },
        "projects": [
          {
            "name": "园内项目A",
            "project_id": "2",
          "credentials": [
          {
              "credential_type": 1,
              "credential_no":"310115199807013370"
          }
          ],
            "qrcodes": [
              "qr_code2_806011925184"
            ],
            "certificate_nos": [
              "b_806011925184"
            ]
          }
        ]
      },
      {
        "entrance": {
          "project_id": "3",
          "credentials": [
          {
              "credential_type": 1,
              "credential_no":"310115199807013371"
          }
          ],
          "qrcodes": [
            "qr_code1_096700560962"
          ],
          "certificate_nos": [
            "a_096700560962"
          ]
        },
        "projects": [
          {
            "name": "园内项目A",
            "project_id": "4",
          "credentials": [
          {
              "credential_type": 1,
              "credential_no":"310115199807013372"
          }
          ],
            "qrcodes": [
              "qr_code2_806011925182"
            ],
            "certificate_nos": [
              "b_806011925182"
            ]
          }
        ]
      }
    ]
  }
}

◦

1单1份（每份3个出行人，包含门票+园内项目）

{
  "data": {
    "error_code": 0,
    "description": "success",
    "result": 1,
    "vouchers": [
      {
        "entrance": {
          "project_id": "1",
          "credentials": [
            {
              "credential_type": 1,
              "credential_no": "310115199807013370"
            },
            {
              "credential_type": 1,
              "credential_no": "310115199807013371"
            },
            {
              "credential_type": 1,
              "credential_no": "310115199807013372"
            }
          ],
          "qrcodes": [
            "qr_code1_096700560961",
            "qr_code1_096700560962",
            "qr_code1_096700560963"
          ],
          "certificate_nos": [
            "a_096700560961",
            "a_096700560962",
            "a_096700560963"
          ]
        },
        "projects": [
          {
            "name": "xx景区A项目",
            "project_id": "2",
            "credentials": [
              {
                "credential_type": 1,
                "credential_no": "310115199807013370"
              },
              {
                "credential_type": 1,
                "credential_no": "310115199807013371"
              },
              {
                "credential_type": 1,
                "credential_no": "310115199807013372"
              }
            ],
            "qrcodes": [
              "qr_code2_806011925184",
              "qr_code2_806011925133",
              "qr_code2_806011925136"
            ],
            "certificate_nos": [
              "b_806011925184",
              "b_806011925123",
              "b_806011925125"
            ]
          }
        ]
      }
    ]
  }
}

◦

部分退商品&留资有身份证（身份证必传）

{
  "data": {
    "error_code": 0,
    "description": "success",
    "result": 1,
    "vouchers": [
      {
        "entrance": {
          "project_id": "1",
          "credentials": [
          {
              "credential_type": 1,
              "credential_no":"310115199807013370"
          }
          ]
        }
      }
    ]
  }
}