wx/hl-api-changelog
1
0
派生 0
代码 工单 合并请求 Actions 软件包 项目 版本发布 百科 动态
hl-api-changelog/2026-03/17_0928/hl-contract-service.md
API Changelog Bot a9bac94ee1 docs: 2026-03/17_0928 sync 13 services (0 breaking)
2026-03-17 09:28:57 +08:00

33 KiB
原始文件 Blame 文件历史

合同服务 API 文档

服务: hl-contract-service 接口总数: 18

目录

  • 合同管理 (12 个接口)
  • 补充约定模板管理 (6 个接口)

合同管理

GET /admin/contract/active-by-order/{orderId}

获取订单有效合同

返回订单当前有效的合同（非作废状态的最新合同），用于检查订单是否已有签署中或已签署的合同。

权限：需管理员登录。

关联字典：

  • contract_status：合同状态（显示）

路径参数

参数 类型 必填 说明
orderId integer 订单ID

响应 统一响应结果«合同信息»

字段 类型 必填 说明
code int 状态码
data 合同信息 响应数据
  agencyCode string 旅行社编号
  contactName string 联系人姓名
  contactPhone string 联系人电话
  contractId long 合同ID
  contractNumber string 合同编号
  contractType string 合同类型: TOUR-旅游合同, INSURANCE-保险单
  createTime string 创建时间
  departureDate string 出发日期
  destination string 目的地
  fileUrl string 合同文件URL
  mode string 签约模式: STANDARD/SYNC
  orderId long 订单ID
  platform string 签约平台
  qrCodeUrl string 二维码URL
  returnDate string 返回日期
  signUrl string 签署URL
  status string 合同状态
  statusLabel string 合同状态标签
  templateCode string 模板编码
  templateName string 模板名称
  totalAmount number 合同总金额
  touristCount int 出行人数
  travelAgencyName string 旅行社名称
message string 响应消息

GET /admin/contract/agencies

可用旅行社列表

返回系统配置的旅行社列表，创建合同时选择签约旅行社

响应 统一响应结果«List«旅行社信息»»

字段 类型 必填 说明
code int 状态码
data 旅行社信息[] 响应数据
  agencyAddress string 旅行社地址
  agencyName string 旅行社名称
  businessLicenseNumber string 营业执照号
  businessScope string 经营范围
  code string 旅行社编码
  licenseNumber string 旅行社许可证号
  regionId string 地区ID
  transactorName string 经办人姓名
  transactorPhone string 经办人电话
  zjParentId int 属地管理机构ID
message string 响应消息

GET /admin/contract/by-order/{orderId}

按订单查询合同

查询指定订单下的所有合同记录（含已作废），按创建时间倒序排列。用于订单详情页展示合同历史。

权限：需管理员登录。

关联字典：

  • contract_status：合同状态（列表显示）

路径参数

参数 类型 必填 说明
orderId integer 订单ID

响应 统一响应结果«List«合同信息»»

字段 类型 必填 说明
code int 状态码
data 合同信息[] 响应数据
  agencyCode string 旅行社编号
  contactName string 联系人姓名
  contactPhone string 联系人电话
  contractId long 合同ID
  contractNumber string 合同编号
  contractType string 合同类型: TOUR-旅游合同, INSURANCE-保险单
  createTime string 创建时间
  departureDate string 出发日期
  destination string 目的地
  fileUrl string 合同文件URL
  mode string 签约模式: STANDARD/SYNC
  orderId long 订单ID
  platform string 签约平台
  qrCodeUrl string 二维码URL
  returnDate string 返回日期
  signUrl string 签署URL
  status string 合同状态
  statusLabel string 合同状态标签
  templateCode string 模板编码
  templateName string 模板名称
  totalAmount number 合同总金额
  touristCount int 出行人数
  travelAgencyName string 旅行社名称
message string 响应消息

POST /admin/contract/create

创建合同(标准模式)

标准电子签约流程：创建合同 → 平台生成合同PDF → 发送签署短信给出行人 → 出行人在线签署 → 回调更新状态。状态流转：CREATED → SIGNING → SIGNED

请求体 创建合同请求

字段 类型 必填 说明
adultCost number 是 成人费用
agencyCode string 旅行社编号（可选，默认使用配置值）
childCost number 儿童费用
contactName string 是 联系人姓名
contactPhone string 是 联系人电话
contractType string 合同类型: TOUR-旅游合同(默认), INSURANCE-保险单
days int 行程天数
departureCity string 出发城市
departureDate string 是 出发日期
destination string 是 目的地
disputeResolution int 争议解决方式: 1-仲裁 2-诉讼
groupId string 团号
leastCustomerNumber int 最低成团人数
nights int 住宿晚数
orderId long 订单ID
paymentMethod int 付款方式: 1-现金 2-转账 3-在线
returnDate string 是 返回日期
routeName string 是 线路名称
signatoryIdNumber string 是 签署人证件号码
signatoryIdType int 签署人证件类型: 1-身份证
signatoryMode int 签署模式: 1-短信 2-现场 3-线下
signatoryName string 是 签署人姓名
signatoryPhone string 是 签署人电话
signingPlace string 签约地点
supplementaryClause string 补充约定内容
templateCode string 是 模板编码
totalAmount number 是 合同总金额
transactorName string 经办人姓名
transactorPhone string 经办人电话
travelers 合同出行人请求[] 是 出行人列表
  age int 年龄
  gender string 性别: male/female
  health string 健康信息
  idCardNo string 是 证件号码
  idCardType int 证件类型: 1-身份证 2-护照
  isChild boolean 是否儿童
  isSigner boolean 是否签署人
  name string 是 姓名
  phone string 手机号
vehicleModel string 车型名称(产品快照)

响应 统一响应结果«合同详情»

字段 类型 必填 说明
code int 状态码
data 合同详情 响应数据
  agencyCode string 旅行社编号
  contactName string 联系人姓名
  contactPhone string 联系人电话
  contractId long 合同ID
  contractNumber string 合同编号
  contractType string 合同类型: TOUR-旅游合同, INSURANCE-保险单
  createTime string 创建时间
  departureDate string 出发日期
  destination string 目的地
  fileUrl string 合同文件URL
  mode string 签约模式: STANDARD/SYNC
  orderId long 订单ID
  platform string 签约平台
  qrCodeUrl string 二维码URL
  returnDate string 返回日期
  signUrl string 签署URL
  status string 合同状态
  statusLabel string 合同状态标签
  statusLogs 合同状态变更日志[] 状态变更日志
    createTime string 创建时间
    logId long 日志ID
    newStatus string 新状态
    oldStatus string 旧状态
    source string 变更来源
  supplementaryClause string 补充约定内容
  templateCode string 模板编码
  templateName string 模板名称
  totalAmount number 合同总金额
  touristCount int 出行人数
  travelAgencyName string 旅行社名称
  travelers 合同出行人信息[] 出行人列表
    idCardNo string 证件号码
    idCardType string 证件类型
    isSigner boolean 是否签署人
    name string 姓名
    phone string 手机号
    travelerId long 出行人ID
message string 响应消息

GET /admin/contract/list

合同列表

分页查询合同记录，支持按订单号、合同状态、旅行社筛选

关联字典：

  • contract_status：合同状态（列表筛选+显示）

查询参数

参数 类型 必填 说明 示例
orderId integer(int64) 订单ID 1001
page integer(int32) 页码 1
pageSize integer(int32) 每页条数 20
platform string 签约平台 TOURAGE
status string 合同状态 SIGNED

响应 统一响应结果«分页结果«合同信息»»

字段 类型 必填 说明
code int 状态码
data 分页结果«合同信息» 响应数据
  page int 当前页码
  pageSize int 每页条数
  records 合同信息[] 数据列表
    agencyCode string 旅行社编号
    contactName string 联系人姓名
    contactPhone string 联系人电话
    contractId long 合同ID
    contractNumber string 合同编号
    contractType string 合同类型: TOUR-旅游合同, INSURANCE-保险单
    createTime string 创建时间
    departureDate string 出发日期
    destination string 目的地
    fileUrl string 合同文件URL
    mode string 签约模式: STANDARD/SYNC
    orderId long 订单ID
    platform string 签约平台
    qrCodeUrl string 二维码URL
    returnDate string 返回日期
    signUrl string 签署URL
    status string 合同状态
    statusLabel string 合同状态标签
    templateCode string 模板编码
    templateName string 模板名称
    totalAmount number 合同总金额
    touristCount int 出行人数
    travelAgencyName string 旅行社名称
  total int 总记录数
message string 响应消息

POST /admin/contract/report

报备合同(同步模式)

线下签约模式：创建合同记录 → 管理员上传已签署的PDF → 同步到12301报备平台。状态流转：CREATED → UPLOADED → REPORTED

请求体 报备合同请求（同步模式）

字段 类型 必填 说明
adultCost number 是 成人费用
agencyCode string 旅行社编号
childCost number 儿童费用
contactName string 是 联系人姓名
contactPhone string 是 联系人电话
contractType string 合同类型: TOUR-旅游合同(默认), INSURANCE-保险单
days int 行程天数
departureCity string 出发城市
departureDate string 是 出发日期
destination string 是 目的地
disputeResolution int 争议解决方式: 1-仲裁 2-诉讼
groupId string 团号
leastCustomerNumber int 最低成团人数
nights int 住宿晚数
orderId long 订单ID
paymentMethod int 付款方式: 1-现金 2-转账 3-在线
returnDate string 是 返回日期
routeName string 是 线路名称
signatoryIdNumber string 是 签署人证件号码
signatoryIdType int 签署人证件类型: 1-身份证
signatoryMode int 签署模式（同步模式默认2-现场）
signatoryName string 是 签署人姓名
signatoryPhone string 是 签署人电话
signingPlace string 签约地点
supplementaryClause string 补充约定内容
templateCode string 是 模板编码
totalAmount number 是 合同总金额
transactorName string 经办人姓名
transactorPhone string 经办人电话
travelers 合同出行人请求[] 是 出行人列表
  age int 年龄
  gender string 性别: male/female
  health string 健康信息
  idCardNo string 是 证件号码
  idCardType int 证件类型: 1-身份证 2-护照
  isChild boolean 是否儿童
  isSigner boolean 是否签署人
  name string 是 姓名
  phone string 手机号

响应 统一响应结果«合同详情»

字段 类型 必填 说明
code int 状态码
data 合同详情 响应数据
  agencyCode string 旅行社编号
  contactName string 联系人姓名
  contactPhone string 联系人电话
  contractId long 合同ID
  contractNumber string 合同编号
  contractType string 合同类型: TOUR-旅游合同, INSURANCE-保险单
  createTime string 创建时间
  departureDate string 出发日期
  destination string 目的地
  fileUrl string 合同文件URL
  mode string 签约模式: STANDARD/SYNC
  orderId long 订单ID
  platform string 签约平台
  qrCodeUrl string 二维码URL
  returnDate string 返回日期
  signUrl string 签署URL
  status string 合同状态
  statusLabel string 合同状态标签
  statusLogs 合同状态变更日志[] 状态变更日志
    createTime string 创建时间
    logId long 日志ID
    newStatus string 新状态
    oldStatus string 旧状态
    source string 变更来源
  supplementaryClause string 补充约定内容
  templateCode string 模板编码
  templateName string 模板名称
  totalAmount number 合同总金额
  touristCount int 出行人数
  travelAgencyName string 旅行社名称
  travelers 合同出行人信息[] 出行人列表
    idCardNo string 证件号码
    idCardType string 证件类型
    isSigner boolean 是否签署人
    name string 姓名
    phone string 手机号
    travelerId long 出行人ID
message string 响应消息

GET /admin/contract/templates

合同模板列表

返回合同平台可用的合同模板列表，创建合同时选择模板

响应 统一响应结果«List«合同模板信息»»

字段 类型 必填 说明
code int 状态码
data 合同模板信息[] 响应数据
  createTime string 创建时间
  description string 模板描述
  mode string 签约模式: STANDARD/SYNC
  platform string 签约平台
  status string 模板状态
  templateCode string 模板编码
  templateId long 模板ID
  templateName string 模板名称
message string 响应消息

GET /admin/contract/{id}

合同详情

关联字典：

  • contract_status：合同状态（显示）

路径参数

参数 类型 必填 说明
id integer 合同ID

响应 统一响应结果«合同详情»

字段 类型 必填 说明
code int 状态码
data 合同详情 响应数据
  agencyCode string 旅行社编号
  contactName string 联系人姓名
  contactPhone string 联系人电话
  contractId long 合同ID
  contractNumber string 合同编号
  contractType string 合同类型: TOUR-旅游合同, INSURANCE-保险单
  createTime string 创建时间
  departureDate string 出发日期
  destination string 目的地
  fileUrl string 合同文件URL
  mode string 签约模式: STANDARD/SYNC
  orderId long 订单ID
  platform string 签约平台
  qrCodeUrl string 二维码URL
  returnDate string 返回日期
  signUrl string 签署URL
  status string 合同状态
  statusLabel string 合同状态标签
  statusLogs 合同状态变更日志[] 状态变更日志
    createTime string 创建时间
    logId long 日志ID
    newStatus string 新状态
    oldStatus string 旧状态
    source string 变更来源
  supplementaryClause string 补充约定内容
  templateCode string 模板编码
  templateName string 模板名称
  totalAmount number 合同总金额
  touristCount int 出行人数
  travelAgencyName string 旅行社名称
  travelers 合同出行人信息[] 出行人列表
    idCardNo string 证件号码
    idCardType string 证件类型
    isSigner boolean 是否签署人
    name string 姓名
    phone string 手机号
    travelerId long 出行人ID
message string 响应消息

POST /admin/contract/{id}/invalidate

作废合同

将合同标记为作废状态（不可恢复）。作废后该合同不再有效，可重新为订单创建新合同

路径参数

参数 类型 必填 说明
id integer 合同ID

响应 统一响应结果«合同信息»

字段 类型 必填 说明
code int 状态码
data 合同信息 响应数据
  agencyCode string 旅行社编号
  contactName string 联系人姓名
  contactPhone string 联系人电话
  contractId long 合同ID
  contractNumber string 合同编号
  contractType string 合同类型: TOUR-旅游合同, INSURANCE-保险单
  createTime string 创建时间
  departureDate string 出发日期
  destination string 目的地
  fileUrl string 合同文件URL
  mode string 签约模式: STANDARD/SYNC
  orderId long 订单ID
  platform string 签约平台
  qrCodeUrl string 二维码URL
  returnDate string 返回日期
  signUrl string 签署URL
  status string 合同状态
  statusLabel string 合同状态标签
  templateCode string 模板编码
  templateName string 模板名称
  totalAmount number 合同总金额
  touristCount int 出行人数
  travelAgencyName string 旅行社名称
message string 响应消息

POST /admin/contract/{id}/resend-sms

重发签署短信

重新发送签署短信给出行人，用于签署短信过期或未收到的场景。仅SIGNING状态的合同可操作

路径参数

参数 类型 必填 说明
id integer 合同ID

响应 统一响应结果«boolean»

字段 类型 必填 说明
code int 状态码
data boolean 响应数据
message string 响应消息

GET /admin/contract/{id}/status

刷新合同状态(从平台同步)

主动查询合同平台的最新签署状态并同步到本地，适用于回调未到达的场景

路径参数

参数 类型 必填 说明
id integer 合同ID

响应 统一响应结果«合同信息»

字段 类型 必填 说明
code int 状态码
data 合同信息 响应数据
  agencyCode string 旅行社编号
  contactName string 联系人姓名
  contactPhone string 联系人电话
  contractId long 合同ID
  contractNumber string 合同编号
  contractType string 合同类型: TOUR-旅游合同, INSURANCE-保险单
  createTime string 创建时间
  departureDate string 出发日期
  destination string 目的地
  fileUrl string 合同文件URL
  mode string 签约模式: STANDARD/SYNC
  orderId long 订单ID
  platform string 签约平台
  qrCodeUrl string 二维码URL
  returnDate string 返回日期
  signUrl string 签署URL
  status string 合同状态
  statusLabel string 合同状态标签
  templateCode string 模板编码
  templateName string 模板名称
  totalAmount number 合同总金额
  touristCount int 出行人数
  travelAgencyName string 旅行社名称
message string 响应消息

POST /admin/contract/{id}/upload-pdf

上传已签署PDF(同步模式)

同步模式专用：上传线下签署完成的合同PDF文件，上传后合同状态变为UPLOADED，可进一步报备

路径参数

参数 类型 必填 说明
id integer 合同ID

响应 统一响应结果«合同信息»

字段 类型 必填 说明
code int 状态码
data 合同信息 响应数据
  agencyCode string 旅行社编号
  contactName string 联系人姓名
  contactPhone string 联系人电话
  contractId long 合同ID
  contractNumber string 合同编号
  contractType string 合同类型: TOUR-旅游合同, INSURANCE-保险单
  createTime string 创建时间
  departureDate string 出发日期
  destination string 目的地
  fileUrl string 合同文件URL
  mode string 签约模式: STANDARD/SYNC
  orderId long 订单ID
  platform string 签约平台
  qrCodeUrl string 二维码URL
  returnDate string 返回日期
  signUrl string 签署URL
  status string 合同状态
  statusLabel string 合同状态标签
  templateCode string 模板编码
  templateName string 模板名称
  totalAmount number 合同总金额
  touristCount int 出行人数
  travelAgencyName string 旅行社名称
message string 响应消息

补充约定模板管理

POST /admin/contract/clause-template

创建补充约定模板

创建合同补充约定的模板，支持变量占位符。创建后默认启用

请求体 补充约定模板请求

字段 类型 必填 说明
content string 是 模板内容
name string 是 模板名称
sortOrder int 排序（升序）

响应 统一响应结果«补充约定模板»

字段 类型 必填 说明
code int 状态码
data 补充约定模板 响应数据
  content string 模板内容
  createTime string 创建时间
  name string 模板名称
  sortOrder int 排序
  status string 状态: ACTIVE/INACTIVE
  templateId long 模板ID
message string 响应消息

GET /admin/contract/clause-template/list

获取启用的补充约定模板列表（创建合同用）

返回所有启用状态的补充约定模板，创建合同时选择需要附加的补充约定条款。

权限：需管理员登录。

响应 统一响应结果«List«补充约定模板»»

字段 类型 必填 说明
code int 状态码
data 补充约定模板[] 响应数据
  content string 模板内容
  createTime string 创建时间
  name string 模板名称
  sortOrder int 排序
  status string 状态: ACTIVE/INACTIVE
  templateId long 模板ID
message string 响应消息

GET /admin/contract/clause-template/list-all

获取全部补充约定模板（管理页用）

关联字典：

  • common_status：通用状态（列表显示，ACTIVE=启用/INACTIVE=停用）

响应 统一响应结果«List«补充约定模板»»

字段 类型 必填 说明
code int 状态码
data 补充约定模板[] 响应数据
  content string 模板内容
  createTime string 创建时间
  name string 模板名称
  sortOrder int 排序
  status string 状态: ACTIVE/INACTIVE
  templateId long 模板ID
message string 响应消息

PUT /admin/contract/clause-template/{id}

更新补充约定模板

更新模板的标题和内容。已被合同引用的模板更新不影响已创建的合同（合同记录的是快照内容）。

权限：需管理员登录。

路径参数

参数 类型 必填 说明
id integer 模板ID

请求体 补充约定模板请求

字段 类型 必填 说明
content string 是 模板内容
name string 是 模板名称
sortOrder int 排序（升序）

响应 统一响应结果«补充约定模板»

字段 类型 必填 说明
code int 状态码
data 补充约定模板 响应数据
  content string 模板内容
  createTime string 创建时间
  name string 模板名称
  sortOrder int 排序
  status string 状态: ACTIVE/INACTIVE
  templateId long 模板ID
message string 响应消息

DELETE /admin/contract/clause-template/{id}

删除补充约定模板

软删除模板。已被合同引用的模板仍可删除，不影响已创建的合同

路径参数

参数 类型 必填 说明
id integer 模板ID

响应 统一响应结果«Void»

PUT /admin/contract/clause-template/{id}/toggle-status

切换模板启用/停用状态

关联字典：

  • common_status：通用状态（状态切换，ACTIVE=启用/INACTIVE=停用）

路径参数

参数 类型 必填 说明
id integer 模板ID

响应 统一响应结果«补充约定模板»

字段 类型 必填 说明
code int 状态码
data 补充约定模板 响应数据
  content string 模板内容
  createTime string 创建时间
  name string 模板名称
  sortOrder int 排序
  status string 状态: ACTIVE/INACTIVE
  templateId long 模板ID
message string 响应消息