个人中心 API 文档 - 1.0.0

个人中心平台介绍

0. 说明

请求说明

  • client_id 为授权客户端Id。
  • 接口参数说明中： 使用大括号 {} 表示这是变量，例如 {client_id} 表示 client_id 这个变量的值， 而不是 “client_id” 字符串。

回调说明

回调接口地址在“个人中心>API管理”中配置，要求回调接口必须为 POST 类型。

对于部分数据变化，系统会向回调接口发送一条回调请求。 请求 Body 如下：

字段名 类型 说明
Action string 所有回调的地址相同，通过Action来区分具体的回调动作
StringData string 回调参数， 如果是对象或数组，将会转成 JSON 字符串形式。 在下面的字段说明中依旧会按对象字段说明

目前支持回调的场景有：账单发生变化， 发票发生变化。 具体在下面对应功能的文档中说明。

1.获取授权码

接口功能

access_token 为控制器的全局唯一接口调用凭据，SCRM 调用各接口时都需使用 access_token；access_token 的有效期目前为 24 个小时，过期后需刷新重新获取。

请求URL

https://personalcenter.unirpa.com/api/connect/token

请求方式

POST

请求头

参数名 必选 类型 说明
Content-Type true string 参数值：application/x-www-form-urlencoded

参数

参数名 必选 类型 说明
client_id true string 授权客户端Id
client_secret true string 授权客户端密钥
grant_type true string client_credentials

响应

返回字段 字段类型 说明
access_token string 授权码
expires_in int 过期时间
token_type string 授权码类型
scope string 访问范围作用域

响应示例

1
2
3
4
5
6
{
  "access_token": "eyJhbGciOiJSUzI1NiIsImtpZCI6IkJENTVCQ0RGRDdEQzQzQTZCQUNENDI2RTZFQzFFMThBRUMzQ0UzNzVSUzI1NiIsInR5cCI6ImF0K2p3dCIsIng1dCI6InZWVzgzOWZjUTZhNnpVSnVic0hoaXV3ODQzVSJ9.eyJuYmYiOjE2MzM2ODI2MDksImV4cCI6MTYzMzc2OTAwOSwiaXNzIjoiaHR0cDovL2xvY2FsaG9zdDoxMjAwMSIsImNsaWVudF9pZCI6InRhb2NsaWVudCIsImp0aSI6IjJBMjlCNzkwQUU3QTNCNjdDNTczMjE5QTQ0MDUxRjI4IiwiaWF0IjoxNjMzNjgyNjA5LCJzY29wZSI6WyJhcHBtYXJrZXRzZXJ2aWNlIiwiY29tbXVuaXR5c2VydmljZSIsIklkZW50aXR5U2VydmVyQXBpIl19.h8CYhv_q8T_tJG0cwe36JWf4ExL7CKBmx5uSb0mOKtYM0ay8nd3c9Xd0q6WM2Quvt8bLkIWJi7CDR4iA3RDH-4OVzY7je4w4cb44dRh-VmEHPZ6kO8dUZYvlXtMZMgTApOaVoIkqKJIiPRK_bQxeuu9Cv3co1AnSGR7HBsCdjqpFSwhGCLLJqE5C82UEVch5m7jS3_upwAOujLZ2ppUFl3xQnV8mGfUFzn99xE0pZTHUcKnrCuI_suv1CatknVBS7R_qf8xHxMww4NGdcpazG_8v-Jk2p7zPRw_fuYHZMAj_yoGpcge27iJQO6cWkxDOQemeBEyz3rjIo7z9F1Mjgw",
  "expires_in": 86400,
  "token_type": "Bearer",
  "scope": "integrationapp"
}

2. 账单

2.1. 获取账单详情

接口功能

通过账单号获取账单详情信息

请求URL

https://personalcenter.unirpa.com/openapi/v1/Bill/GetBill/{BillNo}

请求方式

GET

请求头

参数名 必选 类型 说明
Authorization true string Bearer {access_token}

参数

参数名 必选 类型 说明
BillNo true string 账单编号

响应字段

返回字段 字段类型 说明
code string 响应码
message string 响应消息
data Json 返回数据包含订单详细信息

data 字段说明

返回字段 字段类型 说明
billNo string 订单编号
description string 产品描述
totalAmount decimal 订单总价格
paymentAmount decimal 订单应付金额
discountAmount decimal 优惠金额
paymentTime datetime 付款时间
priceCalculationMethod int 计费模式。 见 PriceCalculationMethodType
quantity int 商品总数
unit int 计费单位。见 BillUnitType
billType int 订单类型。 见 BillType
price decimal 价格
productType int 产品类型。见 ProductType
paymentStatus int 支付状态。见 PaymentStatus
createdTime datetime 创建时间
creatorId string 用户Id
appName string 产品名称

响应示例

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
{
  "code": 200,
  "message": "操作成功",
  "data": {
    "billNo": "B2022062300001",
    "description": "EricTestRobot_Eric的流程",
    "totalAmount": 0.0,
    "paymentAmount": 0.0,
    "discountAmount": 0.0,
    "paymentTime": "0001-01-01 00:00:00",
    "priceCalculationMethod": 2,
    "quantity": 0.0167,
    "unit": 2,
    "billType": 2,
    "price": 0.0,
    "productType": 6,
    "paymentStatus": 3,
    "createdTime": "2022-06-23 16:17:01",
    "creatorId": "97c46e87-8984-47cd-82fe-0c0e3b0f5aa0",
    "appName": "EricTestRobot"
  }

2.2. 取消账单

接口功能

对于未支付的账单，调用此接口来取消支付， 取消后账单作废。 同时会往回调接口回调账单状态变化消息。

请求URL

https://personalcenter.unirpa.com/openapi/v1/Bill/CancelBill/{BillNo}

请求方式

POST

请求头

参数名 必选 类型 说明
Authorization true string Bearer {access_token}

参数

参数名 必选 类型 说明
BillNo true string 账单编号

响应字段

返回字段 字段类型 说明
code string 响应码
message string 响应消息

响应示例

1
2
3
4
{
  "code": 200,
  "message": "操作成功"
}

2.3 账单回调

2.3.1 创建账单回调

回调时机：订单被创建完成后发生

请求参数
1
2
3
4
{
  "Action": "BillCreated",
  "StringData": "{\"BillNo\":\"B2022062300001\"}"
}
StringData 字段说明
字段名 类型 说明
BillNo string 订单号

2.3.2 账单状态变化回调

回调时机：所有订单状态发生改变时发生

请求参数
1
2
3
4
{
  "Action": "BillStatusChanged",
  "StringData": "{\"BillNo\":\"B2022062300001\",\"OldStatus\":1,\"NewStatus\":3}"
}
StringData 字段说明
字段名 类型 说明
BillNo string 订单号
OldStatus int 变化前订单的支付状态。 见PaymentStatusType
NewStatus int 变化后的订单支付状态。见 PaymentStatusType

2.3.3 账单被删除回调

回调时机： 账单被删除后发生

请求参数
1
2
3
4
{
  "Action": "BillDeleted",
  "StringData": "{\"BillNo\":\"B2022062300001\"}"
}
StringData 字段说明
字段名 类型 说明
BillNo string 订单号

3 发票

3.1 发票回调

3.1.1 创建发票回调

回调时机： 发票创建完成后发生

请求参数
1
2
3
4
{
  "Action": "InvoiceCreated",
  "StringData": "{\"InvoiceId\":\"e324d10e-7443-4f47-9eed-71bf0cc234fd\"}"
}
StringData 字段说明
字段名 类型 说明
InvoiceId string 发票 Id

3.1.2 发票状态变化回调

回调时机： 所有发票状态变化时发生

请求参数
1
2
3
4
{
  "Action": "InvoiceStatusChanged",
  "StringData": "{\"InvoiceId\":\"e324d10e-7443-4f47-9eed-71bf0cc234fd\",\"OldStatus\":1,\"NewStatus\":3}"
}
StringData 字段说明
字段名 类型 说明
InvoiceId string 发票 Id
OldStatus int 变化前发票的状态。 见InvoiceStatusType
NewStatus int 变化后发票的状态。 见InvoiceStatusType

3.1.3 发票被删除回调

回调时机： 发票被删除后发生

请求参数
1
2
3
4
{
  "Action": "InvoiceDeleted",
  "StringData": "{\"InvoiceId\":\"e324d10e-7443-4f47-9eed-71bf0cc234fd\"}"
}
StringData 字段说明
字段名 类型 说明
InvoiceId string 发票Id

4. 流程

4.1 运行流程

接口功能

调用 API 手动启动流程

请求URL

https://personalcenter.unirpa.com/openapi/v1/Process/RunProcess

请求方式

POST

请求头
参数名 必选 类型 说明
Authorization true string Bearer {access_token}
Content-Type true string multipart/form-data
参数
参数名 必选 类型 说明
ProcessId true string 流程 Id
ProcessParameters false string 流程参数，格式根据流程请确定
RunningIdentifier false string 运行标识符，用于熔断的幂等判定
响应字段
返回字段 字段类型 说明
code string 响应码
message string 响应消息
data json 如运行成功，返回TaskId
data 字段说明
返回字段 字段类型 说明
taskId string 任务Id
响应示例
1
2
3
4
5
6
7
{
  "code": 200,
  "message": "操作成功",
  "data": {
    "taskId": "df6d2af7-9d7b-4cf6-be41-fbeb2c1ceed5"
  }
}

5. 任务

5.1 获取任务状态

接口功能

运行流程后接口返回 TaskId， 可通过本接口获取任务运行的状态。

请求URL

https://personalcenter.unirpa.com/openapi/v1/Task/GetTaskStatus/{taskId}

请求方式

GET

请求头
参数名 必选 类型 说明
Authorization true string Bearer {access_token}
参数
参数名 必选 类型 说明
taskId true string 任务Id
响应字段
返回字段 字段类型 说明
code string 响应码
message string 响应消息
data json 任务状态信息
data 字段说明
返回字段 字段类型 说明
taskStatus int 任务状态. 见 TaskStatusType
remark string 描述 状态Fault，Stopped，Failed的错误原因
响应示例
1
2
3
4
5
6
7
8
{
  "code": 200,
  "message": "操作成功",
  "data": {
    "taskStatus": 3,
    "remark": null
  }
}

5.2 获取任务输出数据

接口功能

如果与机器人约定任务输出数据通过暂存-拉取方式获取，则在机器人将数据暂存到云平台后， 可通过本接口获取数据。

请求URL

https://personalcenter.unirpa.com/openapi/v1/Task/GetTaskOutputData/{taskId}

请求方式

GET

请求头
参数名 必选 类型 说明
Authorization true string Bearer {access_token}
参数
参数名 必选 类型 说明
taskId true string 任务Id
响应字段
返回字段 字段类型 说明
code string 响应码
message string 响应消息
data json 任务数据信息
data字段说明
返回字段 字段类型 说明
processId string 流程Id
taskId string 任务Id
taskStatus int 任务状态，见 TaskStatusType
data string 任务输出数据，为 json 字符串。具体格式与机器人约定。
message string 附加信息，具体内容与机器人约定。
响应示例
1
2
3
4
5
6
7
8
9
10
11
{
  "code": 200,
  "message": "操作成功",
  "data": {
    "processId": "cfe19a25-f70b-44cd-86a3-ff4335b46870",
    "taskId": "9cdf5f05-8865-49ee-be01-dbcf045803af",
    "taskStatus": 3 ,
    "data": "SomeJson",
    "message": null
  }
}

5.3 停止任务

接口功能

停止正在运行的任务

请求URL

https://personalcenter.unirpa.com/openapi/v1/Task/StopTask/{taskId}

请求方式

POST

请求头
参数名 必选 类型 说明
Authorization true string Bearer {access_token}
参数
参数名 必选 类型 说明
taskId true string 任务 Id
响应字段
返回字段 字段类型 说明
code string 响应码
message string 响应消息
响应示例
1
2
3
4
{
  "code": 200,
  "message": "操作成功"
}

5.4 任务回调

5.4.0 任务回调地址说明

任务的回调是通过流程卡片的回调地址(如图），而不是用户中心下的回调地址进行回调。 根据业务需求可在不同卡片配置不同的回调地址，也可以全部配置成一样的地址。

image-callback

5.4.1 任务输出数据回调。

回调时机： 任务产生数据云平台后， 且约定数据获取方式为回调图送时。

说明：除了通过暂存-拉取的方式通过[获取数据接口](#5.2 获取任务输出数据)主动获取任务数据， 还可以通过回调的方式获取数据。需要与机器人约定数据获取方式为回调推送，且配置好流程卡片的回调地址。

回调参数
1
2
3
4
{
  "Action": "TaskResultData",
  "StringData": "{\"ProcessId\":\"cfe19a25-f70b-44cd-86a3-ff4335b46870\",\"TaskId\":\"9cdf5f05-8865-49ee-be01-dbcf045803af\",\"TaskStatus\":3,\"Data\":\"SomeJson\",\"Message\":null}"
}
StringData 字段说明

与获取接口的data字段一致

字段名 字段类型 说明
ProcessId string 流程Id
TaskId string 任务Id
TaskStatus int 任务状态，见 TaskStatusType
Data string 任务输出数据，为 json 字符串。具体格式与机器人约定。
Message string 附加信息，具体内容与机器人约定。

附录：枚举类型说明

PriceCalculationMethodTyp

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
enum PriceCalculationMethodType
{
    // <summary>
    /// 未指定
    /// </summary>
    Unspecified = 0,
    
    /// <summary>
    /// 运行费（条目）
    /// </summary>
    PayForItems = 1,
    
    /// <summary>
    /// 运行费（时长）
    /// </summary>
    PayForDuration = 2,
    
    /// <summary>
    /// 运行费（成功条目）
    /// </summary>
    PayForItemsSucessed = 3,
    
    /// <summary>
    /// 云应用授权
    /// </summary>
    OnlineAppLicense = 4,
    
    /// <summary>
    /// 控制器授权
    /// </summary>
    ControlCenterLicense = 5,
    
    /// <summary>
    /// 定制应用授权
    /// </summary>
    AppCustomizationLicense = 6,
    
    /// <summary>
    /// 买断
    /// </summary>
    Buyout = 7,
    
    /// <summary>
    /// 套餐
    /// </summary>
    Suite = 8
}

BillUnitType

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
enum BillUnitType
{
    /// <summary>
    /// 未指定
    /// </summary>
    Unspecified = 0,
    
    /// <summary>
    /// 条目---条
    /// </summary>
    Item = 1,
    
    /// <summary>
    /// 时长--小时
    /// </summary>
    Hour = 2,
    
    /// <summary>
    /// 授权--年 
    /// </summary>
    Year = 3,
    
    /// <summary>
    /// 授权--月
    
    /// </summary>
    Month = 4,
    
    /// <summary>
    /// 买断--个 
    /// </summary>
    Quantity = 5
}

BillType

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
enum BillType
{
    /// <summary>
    /// 未指定
    /// </summary>
    Unspecified = 0,
    
    /// <summary>
    /// 控制器订阅
    /// </summary>
    ControlCenter = 1,
    
    /// <summary>
    /// 云应用
    /// </summary>
    OnlineApp = 2,
    
    /// <summary>
    /// 本地应用
    /// </summary>
    NativeApp = 3
}

ProductType

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
enum ProductType
{
    // <summary>
    /// 未指定
    /// </summary>
    Unspecified = -1,
    
    /// <summary>
    /// 应用源文件产品
    /// </summary>
    Application_ResourceFile = 0,
    
    /// <summary>
    /// 应用源代码产品
    /// </summary>
    Application_ResourceCode = 1,
    
    /// <summary>
    /// 控制器产品
    /// </summary>
    ControlCenter = 2,
    
    /// <summary>
    ///  控制器续订
    /// </summary>
    ControlCenterRenew = 3,
    
    /// <summary>
    ///  控制器升级
    /// </summary>
    ControlCenterUpgrade = 4,
    
    /// <summary>
    /// 定制
    /// </summary>
    Application_Custom = 5,
    
    /// <summary>
    /// 非定制应用
    /// </summary>
    Application_Online = 6 
}

PaymentStatusType

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
enum PaymentStatusType
{
    /// <summary>
    /// 未指定
    /// </summary>
    Unspecified = 0,
    
    /// <summary>
    /// 未结算：订单创建完成，但并未完成支付，资源不会执行生产
    /// </summary>
    Pending = 1, 
    
    /// <summary>
    ///已结算：订单创建并支付完成，订单状态完结，后续会执行生产动作(若有)
    /// </summary>
    Checkouted = 2,
    
    /// 已作废：订单由于支付超时或主动关闭，变更为已作废  
    Canceled = 3
}

InvoiceStatusType

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
InvoiceStatusType
{
  /// <summary>
  /// 未指定
  /// </summary>
  Unspecified = 0,

  /// <summary>
  /// 待审核
  /// </summary>
  Unapproved = 1,

  /// <summary>
  /// 已审核
  /// </summary>
  Approved = 2,

  /// <summary>
  /// 已完成
  /// </summary>
  Completed = 3,

  /// <summary>
  /// 失败
  /// </summary>
  Failed = 4,

  /// <summary>
  /// 退票
  /// </summary>
  Refund = 5,

  /// <summary>
  /// 退票成功
  /// </summary>
  Refunded = 6,

  /// <summary>
  /// 已取消
  /// </summary>
  Canceled = 7,
}

TaskStatusType

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
/// <summary>
/// 任务状态
/// </summary>
public enum TaskStatusType
{
    /// <summary>
    /// 未指定
    /// </summary>
    Unspecified = -1,
    
    /// <summary>
    /// 等待中
    /// </summary>
    Pending = 0,
    
    /// <summary>
    /// 运行中
    /// </summary>
    Running = 1,
    
    /// <summary>
    /// 运行故障
    /// </summary>
    Fault = 2,
    
    /// <summary>
    /// 运行完成
    /// </summary>
    Finished = 3,
    
    /// <summary>
    /// 运行停止
    /// </summary>
    Stopped = 4,
    
    /// <summary>
    /// 运行失败
    /// </summary>
    Failed = 5,
    
    /// <summary>
    /// 取消运行
    /// </summary>
    Canceled = 6,
    
    /// <summary>
    /// 停止中
    /// </summary>
    Stopping = 7
}