NAV
json

斑马服务器(server)

地址

  1. 正式环境:https://zpert.com
  2. 外网可访问的测试环境:https://b.zpert.com,此环境已和数字项目集成管理平台打通,如需从数字项目集成管理平台同步数据到斑马,请使用此环境
  3. 内网测试环境:https://dev.zpert.com

斑马进度资源授权(authorization-resource)

单点登录(sso)

斑马进度提供第三方应用基于广联达用户中心单点登录斑马进度的机制,第三方应用可直访问斑马进度网站页面地址,对于最终能否正确访问到预期页面,斑马进度还会判断登录用户在斑马中是否有访问资源的权限。如权限正确则会展现预期页面,如权限不正确则会有对应错误提示。

单点登录访问斑马进度页面

第三方应用授权(app-auth)

首先,在斑马进度网站创建第三方应用获取应用的client_idclient_secret;使用access token访问/open资源下的页面;使用接口参数签名的方式访问斑马进度API。如果仅仅过网关访问斑马进度API,则可忽略本章文档。 详细信息如下:

创建第三方应用

  1. 在斑马进度的网站中添加第三方应用(企业--设置--第三方应用),点击新建应用按钮,输入应用名称完成第三方应用创建。完成应用创建后就可以拿到client_idclient_secret,选中应用授权中组织的根节点添加管理员权限。
  2. 新建第三方应用示例图
  3. 添加管理员示例图
  4. 第三方应用可创建多了,可只用其中的一个或多个。

获取access token

获取access token

使用access token访问斑马进度页面

签名算法

签名算法(signature)

签名算法(signature)

获取access_token接口签名

生成获取access_token接口专用签名方式

签名参数列表

签名参数 是否必须 描述
grant_type 值固定为:client_credentials
client_id 应用的 uid
timestamp 当前时间的 unix 值, 600 秒之内发送的请求视为有效的
nonce 随机生成的字符串
client_secret 应用的 client_secret

获取client_id&client_secret

签名算法

  1. grant_type, client_id, timestamp, nonce按名称升序排列
  2. 将每个参数与参数对应的值组成的字符串(例如 'grant_type=xxxxx'), 用'&'连接成一个字符串str
  3. 在str的前后加入client_secret,组成一个新的字符串
  4. 对新字符串做32位md5处理, 取32位小写的结果作为 signature

Ruby实现

  #源码
  require "rest-client"
  require "json"
  require "pry"
  require "uuid"

  client_id = '3245d490f4160138fc74245e60d8aead'
  client_secret = '46fba050f4160138fc74245e60d8aead'

  uuid = UUID.new
  uuid_str = uuid.generate
  timestamp = Time.now.to_i
  params = {
    grant_type: "client_credentials",
    client_id: client_id,
    timestamp: timestamp,
    nonce: uuid_str
  }

  puts params

  str = params.keys.sort.map{|k| "#{k}=#{params[k]}"}.join('&')
  str = "#{client_secret}#{str}#{client_secret}"
  puts str
  signature = Digest::MD5.hexdigest(str)
  puts signature

  # 示例
  签名参数:
  grant_type = "client_credentials"
  client_id = "3245d490f4160138fc74245e60d8aead"
  client_secret = "46fba050f4160138fc74245e60d8aead"
  timestamp = "1603099304"
  nonce = "6dc78060-f41a-0138-fc77-245e60d8aead"

  待签字符串:
  46fba050f4160138fc74245e60d8aeadclient_id=3245d490f4160138fc74245e60d8aead&grant_type=client_credentials&nonce=6dc78060-f41a-0138-fc77-245e60d8aead&timestamp=160309930446fba050f4160138fc74245e60d8aead

  签名结果:
  dd39886dc8b83dac1b5331f818877180

其他接口签名(other)

除获取access_token接口之外的其他接口生成签名的算法

签名参数列表

签名参数 是否必须 描述
client_id 应用的 uid
timestamp 当前时间的 unix 值, 600 秒之内发送的请求视为有效的
nonce 随机生成的字符串
client_secret 应用的 client_secret

获取client_id&client_secret

签名算法

  1. client_id, timestamp, nonce按名称升序排列
  2. 将每个参数与参数对应的值组成的字符串(例如 'client_id=xxxxx'), 用'&'连接成一个字符串str
  3. 在str的前后加入client_secret,组成一个新的字符串
  4. 对新字符串做32位md5处理, 取32位小写的结果作为 signature

Ruby实现

  # 源码
  require "rest-client"
  require "json"
  require "pry"
  require "uuid"

  client_id = '3245d490f4160138fc74245e60d8aead'
  client_secret = '46fba050f4160138fc74245e60d8aead'

  uuid = UUID.new
  uuid_str = uuid.generate
  timestamp = Time.now.to_i
  params = {
    client_id: client_id,
    timestamp: timestamp,
    nonce: uuid_str
  }

  str = params.keys.sort.map{|k| "#{k}=#{params[k]}"}.join('&')
  str = "#{client_secret}#{str}#{client_secret}"
  puts str
  signature = Digest::MD5.hexdigest(str)
  puts signature

  # 示例
  client_id = "3245d490f4160138fc74245e60d8aead"
  client_secret = "46fba050f4160138fc74245e60d8aead"
  timestamp = "1603097721"
  nonce = "be2ed1d0-f416-0138-fc76-245e60d8aead"

  待签字符串:

  46fba050f4160138fc74245e60d8aeadclient_id=3245d490f4160138fc74245e60d8aead&nonce=be2ed1d0-f416-0138-fc76-245e60d8aead&timestamp=160309772146fba050f4160138fc74245e60d8aead

  签名结果:
  f49b8ac3d9651fc2dd8cdd09dea3f75f

Access token

获取access token

access token用于访问斑马内嵌页面等资源。

HTTP Request

POST /api/v2/oauth/token

Query参数

参数名称 是否必选 描述
grant_type 值固定为:client_credentials
client_id 应用的 uid
p_id 斑马计划的id要
timestamp 当前时间的 unix 值, 600 秒之内发送的请求视为有效的
nonce 随机生成的字符串,例如 uuid
signature 签名

成功返回结果:

  {
    "code":0,
    "access_token":"f6c87fb84bc872f92f519a41204180d15658bcdee014e3387a1ad9abfbd70d43",
    "token_type":"Bearer",
    "expires_in":7200,
    "created_at":1543372633
  }

失败返回结果:

  // 请求不在60秒有效期之内
  {"code":1, "message":"请求过时"}

  // nonce重复
  {"code":2, "message":"执行过的请求"}

  // 包含非法字段,例如client_secret
  {"code":3, "message":"包含非法字段"}

  // 生成的signature错误
  {"code":4, "message":"signature错误"}

  // client_id错误
  {"code":5, "message":"由于未知、不支持或没有客户端,认证失败"}

  // 其他一些错误,例如grant_type错误等
  {"code":6,"message":"服务器不支持此类型的授权方式"}

API V2

企业(Company)接口

获取企业信息

HTTP Request

GET /api/v2/companies/info

Query参数

参数名称 是否必选 描述
client_id 应用的 uid
timestamp 当前时间的 unix 值, 600 秒之内发送的请求视为有效的
nonce 随机生成的字符串,例如 uuid
signature 签名

成功返回结果:

{
  "code":0,
  "data":
    {
      "company":
        {
          "id": 3,        // 企业id
          "name": "xxxx"  // 企业名称
        }
    }
}

失败返回结果:

  // 请求不在600秒有效期之内
  {"code":1, "message":"请求过时"}

  // nonce重复
  {"code":2, "message":"执行过的请求"}

  // 包含非法字段,例如client_secret
  {"code":3, "message":"包含非法字段"}

  // 生成的signature错误
  {"code":4, "message":"signature错误"}

  // client_id错误
  {"code":5, "message":"由于未知、不支持或没有客户端,认证失败"}

计划(Project)接口

获取企业下所有计划

HTTP Request

GET /api/v2/company_projects

Query参数

参数名称 是否必选 描述
client_id 应用的 uid
timestamp 当前时间的 unix 值, 600 秒之内发送的请求视为有效的
nonce 随机生成的字符串,例如 uuid
signature 签名

成功返回结果:

{
  "code":0,
  "data":
    {
      "company_projects":
        [
          {
            "id":61, // 计划id
            "name":"6666", // 计划名称
            "company_catalog": // 计划归属的目录或项目
              {
                "id":215, // 目录或项目的id
                "name":"项目b", // 目录或项目的名称
                "folder":false // true代表是目录, false代表是项目
                "cloudt_project_id": "336969852666368" //数字项目集成管理平台项目id
              }
          }
        ]
    }
}

失败返回结果:

  // 请求不在600秒有效期之内
  {"code":1, "message":"请求过时"}

  // nonce重复
  {"code":2, "message":"执行过的请求"}

  // 包含非法字段,例如client_secret
  {"code":3, "message":"包含非法字段"}

  // 生成的signature错误
  {"code":4, "message":"signature错误"}

  // client_id错误
  {"code":5, "message":"由于未知、不支持或没有客户端,认证失败"}

获取计划详情

HTTP Request

GET /api/v2/company_projects/:id

Path 参数

参数名称 是否必选 描述
id 斑马计划id

Query 参数

参数名称 是否必选 描述
client_id 应用的 uid
timestamp 当前时间的 unix 值, 600 秒之内发送的请求视为有效的
nonce 随机生成的字符串,例如 uuid
mt_size 里程碑数量,不需要参加 signature 的计算,当 mt_size = -1 时,会返回所有进行中的里程碑数据,当 mt_size = 0 或者不存在时,不返回里程碑数据,当 mt_size > 0 时,返回小于等于指定数量的里程碑数据
signature 签名

成功返回结果:

{
  "code":0,
  "data":
    {
      "id":73, // 计划id
      "user_name":"xx", // 负责人名称
      "name":"住一黑庄户", // 计划名称
      "uploaded_at":1500974424, // 计划建立时间
      "last_uploaded_at":1533629696, // 计划上次更新时间
      "ask_start_time":1486915200, // 计划要求开始时间
      "ask_stop_time":1534348800, // 计划要求结束时间
      "ask_duration":549, // 计划要求工期天数
      "real_start_time":1533484800, // 计划实际开始时间, 可能不存在
      "real_stop_time":null, // 计划实际结束时间, 可能不存在
      "real_duration":null, //计划实际工期, 可能不存在
      "plan_start_time":1486915200, // 计划预计开始时间
      "plan_stop_time":1534348800, // 计划预计结束时间
      "plan_duration": 12.0, // 计划工期
      "estimate_start_time":1486915200, // 计划估计开始时间
      "estimate_stop_time":1534348800, // 计划估计结束时间
      "forward_line_unix": 1534348800, // 最新的里程碑时间
      "offset": 12.0, // 计划预测偏差天数,小于零超期,大于零提前,等于零按时完成
      "milestones":[ // 里程碑数据
        {
          "id": 1,  // 里程碑id
          "name": "xxx",  // 里程碑名称
          "rank": 1,      // 里程碑等级
          "ask_stop_time": 1499235885, // 要求结束时间
          "plan_start_time": 1499235885, // 预计开始
          "plan_stop_time": 1499235885, // 预计结束
          "estimate_start_time": 1499235885, // 估计开始
          "estimate_stop_time": 1499235885, // 估计结束
          "real_start_time": 1499235885, // 实际开始
          "real_stop_time": 1499235885 // 实际结束
          "offset": 12.0 // 计划预测偏差天数,小于零超期,大于零提前,等于零按时完成
        }
      ]
    }
}

失败返回结果:

  // 请求不在600秒有效期之内
  {"code":1, "message":"请求过时"}

  // nonce重复
  {"code":2, "message":"执行过的请求"}

  // 包含非法字段,例如client_secret
  {"code":3, "message":"包含非法字段"}

  // 生成的signature错误
  {"code":4, "message":"signature错误"}

  // client_id错误
  {"code":5, "message":"由于未知、不支持或没有客户端,认证失败"}

项目(Catalog)接口

获取企业组织结构

HTTP Request

GET /api/v2/company_catalogs

Query 参数

参数名称 是否必选 描述
client_id 应用的 uid
timestamp 当前时间的 unix 值, 600 秒之内发送的请求视为有效的
nonce 随机生成的字符串,例如 uuid
signature 签名

成功返回结果:

{
  "code":0,
  "data":
    {
      "company_catalog":
        {
          "id": 3,            // 目录id
          "parent_id": null,  // 目录的父id,根节点的父id为空
          "name": "xx集团",    // 目录名称
          "status": "",       // 项目状态
          "default_company_project_id": null, // 项目的主控计划id
          "desc": null,       // 描述
          "folder": true,     // 是否是目录,目录:true,项目:false
          "tags": "",         // 标签
          "catalog_no": "E1BFBF2998A7561F07F6F28E", // 编号
          "establish_time": null,// 立项时间,unix时间戳
          "children": [
            {
              "id": 3519,
              "parent_id": 3,
              "name": "模板库",
              "status": "未开始",
              "default_company_project_id": null,
              "desc": null,
              "folder": false,
              "tags": "",
              "catalog_no": "__TEMPLATE_ITEM__",
              "establish_time": 1554816484
            },
            {
              "id": 3387,
              "parent_id": 3,
              "name": "已完成项目",
              "status": "",
              "default_company_project_id": null,
              "desc": null,
              "folder": true,
              "tags": "",
              "catalog_no": "__DONE_FOLDER__",
              "establish_time": null,
              "children": []
            }
          ]
        }
    }
}

失败返回结果:

  // 请求不在600秒有效期之内
  {"code":1, "message":"请求过时"}

  // nonce重复
  {"code":2, "message":"执行过的请求"}

  // 包含非法字段,例如client_secret
  {"code":3, "message":"包含非法字段"}

  // 生成的signature错误
  {"code":4, "message":"signature错误"}

  // client_id错误
  {"code":5, "message":"由于未知、不支持或没有客户端,认证失败"}

获取项目列表

HTTP Request

GET /api/v2/company_catalogs/company_items

Query 参数

参数名称 是否必选 描述
client_id 应用的 uid
timestamp 当前时间的 unix 值, 600 秒之内发送的请求视为有效的
nonce 随机生成的字符串,例如 uuid
signature 签名
catalog_name 组织名称
catalog_code 项目编码
min_duration_offset 最小偏差天数
max_duration_offset 最大偏差天数

成功返回结果:

{
  "code":0,
  "data":
    {
      "company_catalogs":
        [
          {
            "id": 124,              // 项目id
            "cloudt_project_id": "336969852666368", //数字项目集成管理平台项目id
            "parent_id": 86,        // 父目录id
            "name": "轨道北京地铁7号线东延工程土建施工02合同段",
            "status": "进行中",      // 状态
            "default_company_project_id": null, // 主控计划id,当不存在时,默认取了项目下第一个计划
            "desc": "",
            "folder": false,
            "tags": "地铁",
            "catalog_no": "D29C406EA630378F6D00DFE3",
            "establish_time": 1514525385, // 立项时间,unix时间戳
            "manage_status": 1,  // 0 未及时上传,1 暂未上传,2 前锋线未及时更新 上周一之前,3 前锋线已及时更新 上周一之后
            "emphasis": false,  // 是否重点项目
            "plan_info": {                // 主控计划信息
              "root": {                   // 整个计划的信息
                "name": "项目结束",        // root的name都是'项目结束'
                "ask": 1569686400,        // 要求完成时间,unix时间戳
                "estimate": null,         // 预测完成时间,unix时间戳
                "status": null            // 自然日数,小于零时是超期,大于零时是提前,等于零是按时完成
              },
              "milestone0": null,         // 近期里程碑1
              "milestone1": null,         // 近期里程碑2
              "milestone2": null          // 近期里程碑3
            }
          }
        ],
        "statistics_catalogs": [1, 2, 3] // 统计项目id数组
    }
}

失败返回结果:

  // 请求不在600秒有效期之内
  {"code":1, "message":"请求过时"}

  // nonce重复
  {"code":2, "message":"执行过的请求"}

  // 包含非法字段,例如client_secret
  {"code":3, "message":"包含非法字段"}

  // 生成的signature错误
  {"code":4, "message":"signature错误"}

  // client_id错误
  {"code":5, "message":"由于未知、不支持或没有客户端,认证失败"}

获取项目信息

HTTP Request

GET /api/v2/company_catalogs/:id/company_item

Query 参数

参数名称 是否必选 描述
client_id 应用的 uid
timestamp 当前时间的 unix 值, 600 秒之内发送的请求视为有效的
nonce 随机生成的字符串,例如 uuid
signature 签名

成功返回结果:

{
  "code":0,
  "data":
    {
      "company_projects":     // 项目下的计划
        [
            {
              "id": 3801,     // 计划id
              "name": "黑庄户住一项目部1#3#5#8#23#32#2018年12月份进度计划",  // 计划名称
              "plan_info":
                {
                  "forward_line_unix": 315504000  // 前锋线时间,unix时间戳
                }
            },
        ]
    }
}

失败返回结果:

  // 请求不在600秒有效期之内
  {"code":1, "message":"请求过时"}

  // nonce重复
  {"code":2, "message":"执行过的请求"}

  // 包含非法字段,例如client_secret
  {"code":3, "message":"包含非法字段"}

  // 生成的signature错误
  {"code":4, "message":"signature错误"}

  // client_id错误
  {"code":5, "message":"由于未知、不支持或没有客户端,认证失败"}

API V3

V3接口返回的时间皆为UTC时间

获取计划标准(standard)格式

HTTP Request

GET /api/v3/company_projects/:id/standard_data

Query 参数

参数名称 是否必填 描述
client_id 应用的 uid
timestamp 当前时间的 unix 值, 600 秒之内发送的请求视为有效的
nonce 随机生成的字符串,例如 uuid
signature 签名

成功返回结果:

{
  "code": 0,
  "data": {
    ......
    "tasks": [                 // 计划工作项数组
      {
        "id": 0,
        "name": "test1",
        "rank": 1,
        "type": 0,
        "layer": 0,
        "level": 0,
        "depends": "",
        "end_dot": 7,
        "duration": 8092800,
        "begin_dot": 0,
        "draw_type": 2,
        "is_parent": true,
        "department": {},
        "is_keywork": true,
        "attachments": [],
        "depend_type": "FS",
        "forign_name": "The Pert Chart of Zebra Project",
        "source_count": {
          "plan": 1.0,
          "unit": "",
          "price": 0.0,
          "real_price": 0.0,
          "current_plan": 0.0,
          "contract_price": 0.0
        },
        "ask_stop_time": 1585872000,
        "auto_duration": true,
        "schedule_type": 0,
        "ask_start_time": 1585785600,
        "plan_stop_time": 1593878400,
        "work_style_idx": 1,
        "plan_start_time": 1585785600,
        "estimate_stop_time": 1593878400,
        "estimate_start_time": 1585785600,
        "is_typical_deviation": true
      }
    ],
    "groups": [],
    "legend": {
      "sDate": "2020-04-02",
      "width": 320,
      "height": 160,
      "visible": true,
      "position": 0,
      "script10": "\n  备注:",
      "script21": "项目负责人",
      "script22": "",
      "script31": "绘图人",
      "script32": "",
      "script41": "审核人",
      "script42": "",
      "script51": "校对人",
      "script52": "",
      "script61": "起始时间",
      "script62": "",
      "script71": "结束时间",
      "script72": "",
      "script81": "文件名",
      "script82": "",
      "script91": "总工期",
      "script92": "",
      "developer": "斑马·梦龙网络计划制作",
      "script11_1": "总工期(工日)",
      "show_symbol_list": [
        1
      ],
      "show_symbol_mode": 0,
      "is_show_script_10": true,
      "is_show_script_11": true,
      "is_show_catalog_name": true
    },
    "next_id": 15,
    "version": 2,
    "calendars": [
      {
        "id": 0,
        "name": "自然日",
        "work_periods": [
          [
            0,
            86400
          ]
        ]
      },
      {
        "id": 6,
        "name": "标准",
        "work_periods": [
          [
            0,
            86400
          ]
        ]
      }
    ],
    "count_time": 1585756800,
    "plan_state": 1,
    "progresses": [
      {
        "time": 1585785600,
        "notes": "",
        "is_display": true
      }
    ],
    "store_type": "zpert",
    "default_calendar_id": 6
    ......
  }
}

失败返回结果:

  // 请求不在600秒有效期之内
  {"code":1, "message":"请求过时"}

  // nonce重复
  {"code":2, "message":"执行过的请求"}

  // 包含非法字段,例如client_secret
  {"code":3, "message":"包含非法字段"}

  // 生成的signature错误
  {"code":4, "message":"signature错误"}

  // client_id错误
  {"code":5, "message":"由于未知、不支持或没有客户端,认证失败"}

获取计划计算(calculation)数据

HTTP Request

GET /api/v3/company_projects/:id/calculation_data

Query 参数

参数名称 是否必填 描述
client_id 应用的 uid
timestamp 当前时间的 unix 值, 600 秒之内发送的请求视为有效的
nonce 随机生成的字符串,例如 uuid
signature 签名

成功返回结果:

{
  "code": 0,
  "data": {
    "tasks":
      [
        {
          "id": 0,                                  //工作id
          "plan_duration_days": 41.0,               //计划工期天数(浮点)
          "front_works": "",                        //前置工作(字符串)
          "front_works_number": 0,                  //前置工作数(整数)
          "behind_works_number": 0,                 //后置工作数(整数)
          "free_time_difference": 0.0,              //自由时差(浮点)
          "total_time_difference": 0.0,             //总时差(浮点)
          "earlist_start_time": "2022-02-17",       //最早开始
          "earlist_stop_time": "2022-04-05",        //最早完成
          "latest_start_time": "2022-02-17",        //最晚开始
          "latest_stop_time": "2022-04-05",         //最晚完成
          "start_time_difference": 0.0,             //开始时间差异(浮点)
          "stop_time_difference": 8.0,              //完成时间差异(浮点)
          "relative_start_time": 0.0,               //相对开始(浮点)
          "relative_stop_time": 48.0,               //相对完成(浮点)
          "estimate_delay_time": 55.0,              //预测超期(浮点)
          "plan_delay_time": 47.0,                  //计划超期(浮点)
          "duration_difference": 8.0,               //工期差异(浮点)
          "effect_on_key_path": 8.0,                //影响关键线路(浮点)
          "last_plan_duration": 0.0,                //原计划工期(工日)(浮点)
          "start_time_change": 0.0,                 //开始时间变动(浮点)
          "stop_time_change": 0.0,                  //完成时间变动(浮点)
          "duration_change": 0.0,                   //工期变动(浮点)
          "plan_elapsed_time": 39.0,                //计划进行时间(浮点)
          "plan_remaining_time": 17.0,              //计划剩余时间(浮点)
          "plan_total_cost": 0.0,                   //计划总费用(浮点)
          "real_total_cost": 0.0,                   //实际总费用(浮点)
          "production_value": 0.0,                  //产值(浮点)
          "plan_labour": 0.0,                       //计划总人数
          "real_labour": 0.0,                       //实际总人数
          "cumulative_completion": 0.6,             //累计完成量(浮点)
          "current_plan_quantities": 0.0,           //当期计划量(浮点)
          "predict_stop_time": "2022-04-13",        //预计完成
          "period_start_time": "",                  //本期开始
          "period_stop_time": "",                   //本期完成
          "vacation": "",                           //假期
          "duration_include_vacation": 48.0         //工期(含假期)(浮点)
          //总计划
          "ask_duration_days": 1.0,                 //要求工期(不包括假期)(浮点)
          "ask_duration_days_include_vacation": 1.0,//要求工期(包括假期)(浮点)
          //计划变动分析计算结果(原工期差异 = 原计划工期天数 - 计划工期天数)
          "last_plan_start_diff_days": 0.0,         //原计划开始偏差天数(浮点)
          "last_plan_stop_diff_days": 0.0,          //原计划结束偏差天数(浮点)
          "last_plan_duration_days": 0.0,           //原计划工期天数(浮点)
          "change_details": "",                     //执行情况(计划变动)(字符串)
          "change_resolution": ""                   //解决措施(计划变动)(字符串)
          //进度对比分析计算结果(实际工期/剩余差异 = 实际工期/预计剩余天数 - 计划工期天数)
          "real_duration_days": 41.0,               //实际工期天数(浮点)
          "real_start_diff_days": 1.0,              //实际开始偏差天数(浮点)(由状态判断是否可能滞后)
          "real_stop_diff_days": 1.0,               //实际结束偏差天数(浮点)
          "plan_left_days": 40.0,                   //计划剩余天数(浮点)
          "predict_left_days" :  0.0                //预计剩余天数(浮点)
          "progress_details": "",                   //执行情况(进度对比)(字符串)
          "progress_resolution": "",                //解决措施(进度对比)(字符串)
        }
      ]
  }
}

失败返回结果:

  // 请求不在600秒有效期之内
  {"code":1, "message":"请求过时"}

  // nonce重复
  {"code":2, "message":"执行过的请求"}

  // 包含非法字段,例如client_secret
  {"code":3, "message":"包含非法字段"}

  // 生成的signature错误
  {"code":4, "message":"signature错误"}

  // client_id错误
  {"code":5, "message":"由于未知、不支持或没有客户端,认证失败"}

获取计划里程碑(milestone)数据

HTTP Request

GET /api/v3/company_projects/:id/milestones

Query 参数

参数名称 是否必填 描述
client_id 应用的 uid
timestamp 当前时间的 unix 值, 600 秒之内发送的请求视为有效的
nonce 随机生成的字符串,例如 uuid
signature 签名

成功返回结果:

{
  "code": 0,
  "data": {
    "tasks": [
        {
          "id": 0,                           //工作id
          "name": "0708",                    //工作名称
          "rank": 1,                         //里程碑等级
          "plan_delay_days": -33.0,          //提前或滞后天数(要求-计划)
          "estimate_delay_days": -33.0,      //提前或滞后天数(要求-预测)
          "stop_time_difference": 8.0,       //完成时间差异(浮点)
          "plan_stop_time": 1589130000,      //计划完成时间
          "estimate_stop_time": 1589130000,  //预测完成时间
          "real_stop_time": 0,               //实际完成时间
          "ask_stop_time": 1586304000,       //要求完成时间
          "plan_duration_days": 34.0         //计划工期天数(浮点)(只有总任务存)
        }
      ]
    }
}

失败返回结果:

  // 请求不在600秒有效期之内
  {"code":1, "message":"请求过时"}

  // nonce重复
  {"code":2, "message":"执行过的请求"}

  // 包含非法字段,例如client_secret
  {"code":3, "message":"包含非法字段"}

  // 生成的signature错误
  {"code":4, "message":"signature错误"}

  // client_id错误
  {"code":5, "message":"由于未知、不支持或没有客户端,认证失败"}

批量更新计划工作项(update_tasks)状态

HTTP Request

POST /api/v3/company_projects/:id/update_tasks

Path 参数

参数名称 类型 是否必填 描述
id Int 斑马进度计划id

Query 参数

参数名称 类型 是否必填 描述
client_id String 应用的 uid
timestamp String 当前时间的 unix 值, 600 秒之内发送的请求视为有效的
nonce String 随机生成的字符串,例如 uuid
signature String 签名

请求体数据结构

参数名称 类型 是否必填 描述
forward_line_time Int 前锋线时间,使用该字段的值设置计划前锋线时间,单位:秒
feedbacks Array 计划工作项状态反馈列表

反馈项数据结构

参数名称 类型 是否必填 描述
id Int 工作项id,唯一标识一个工作项
status Int 工作项状态,0表示未开始,1表示进行中,2表示已完成
real_start_time Int 工作项实际开始时间,进行中和已完成状态的工作,该字段必填,单位:秒
real_stop_time Int 工作项实际完成时间,已完成状态的工作,该字段必填,单位:秒
predict_stop_time Int 工作项预计完成时间,进行中状态的工作,该字段必填,单位:秒
completion_ratio Double 完成占比
details String 偏差原因
resolution String 解决措施

请求体示例:

{
  "forward_line_time": 1589130000,            //前锋线时间
  "feedbacks": [
    {
      "id": 0,                           //id
      "status": 1,                       //状态
      "real_start_time": 1589130000,     //时间开始时间
      "real_stop_time": 0,               //实际完成时间
      "predict_stop_time": 1589130000,   //预计完成时间
      "completion_ratio": 0.3,           //完成占比
      "details": "",                     //偏差原因
      "resolution": ""                   //解决措施
    }
  ]
}

成功返回结果:

  {
    "code":0,
    "message": "更新成功"
  }

失败返回结果:

  // 请求不在600秒有效期之内
  {"code":1, "message":"请求过时"}

  // nonce重复
  {"code":2, "message":"执行过的请求"}

  // 包含非法字段,例如client_secret
  {"code":3, "message":"包含非法字段"}

  // 生成的signature错误
  {"code":4, "message":"signature错误"}

  // client_id错误
  {"code":5, "message":"由于未知、不支持或没有客户端,认证失败"}

内嵌斑马进度页面(embed-page)

单点登录的方式(sso)

计划详情页面

数字项目集成管理平台上注册产品

测试环境地址:https://xmgl-test.glodon.com/zpet/gateway

正式环境地址:https://xmgl.glodon.com/zpet/gateway

Http Method:GET

请求参数:

参数名称 是否必须 说明
access_path 值固定为:SNAP_COMPANY_PROJECT
cloudt_tenant_id 数字项目集成管理平台租户id
zpet_project_id 斑马计划id
hack_style 自定义样式(css)文件地址

示例:

测试环境地址:https://xmgl-test.glodon.com/zpet/gateway?access_path=SNAP_COMPANY_PROJECT&cloudt_tenant_id=123&zpet_project_id=789&hack_style=https://demo.com/a.css

正式环境地址:https://xmgl.glodon.com/zpet/gateway?access_path=SNAP_COMPANY_PROJECT&cloudt_tenant_id=123&zpet_project_id=789&hack_style=https://demo.com/a.css

单独产品

测试环境地址:https://b.zpert.com/company_projects/:id/snap

正式环境地址:https://zpert.com/company_projects/:id/snap

Http Method:GET

请求参数:

参数名称 是否必须 说明
com_id 斑马企业id
id 斑马计划id
hack_style 自定义样式(css)文件地址

示例:

测试环境地址:https://b.zpert.com/company_projects/12/snap?com_id=1&hack_style=https://demo.com/a.css

正式环境地址:https://zpert.com/company_projects/12/snap?com_id=1&hack_style=https://demo.com/a.css

项目详情页面

数字项目集成管理平台上注册产品

测试环境地址:https://xmgl-test.glodon.com/zpet/gateway

正式环境地址:https://xmgl.glodon.com/zpet/gateway

Http Method:GET

请求参数:

参数名称 是否必须 说明
access_path 值固定为:COMPANY_ITEM_COMPANY_CATALOG
cloudt_tenant_id 数字项目集成管理平台租户id
cloudt_item_id 数字项目集成管理平台项目id
hack_style 自定义样式(css)文件地址

示例:

测试环境地址:https://xmgl-test.glodon.com/zpet/gateway?access_path=COMPANY_ITEM_COMPANY_CATALOG&cloudt_tenant_id=123&cloudt_item_id=456&hack_style=https://demo.com/a.css

正式环境地址:https://xmgl.glodon.com/zpet/gateway?access_path=COMPANY_ITEM_COMPANY_CATALOG&cloudt_tenant_id=123&cloudt_item_id=456&hack_style=https://demo.com/a.css

单独产品

测试环境地址:https://b.zpert.com/company_catalogs/:id/company_item

正式环境地址:https://zpert.com/company_catalogs/:id/company_item

Http Method:GET

请求参数:

参数名称 是否必须 说明
com_id 斑马企业id
id 斑马项目id
hack_style 自定义样式(css)文件地址

示例:

测试环境地址:https://b.zpert.com/company_catalogs/12/company_item?com_id=1&hack_style=https://demo.com/a.css

正式环境地址:https://zpert.com/company_catalogs/12/company_item?com_id=1&hack_style=https://demo.com/a.css

备注

  1. 第三方应用没有使用广联云作为用户中心,则不能使用此方案。
  2. 斑马提供统一的页面样式,如果第三方应用需要个性化显示斑马提供的内嵌页面,斑马提供通过参数hack_style满足第三方应用自定义页面样式的需求,hack_style的值是第三方应用提供的个性化样式(css)文件地址。

使用access token

计划详情页面

测试环境地址:https://b.zpert.com/frontend/open/company_projects/:id

正式环境地址:https://zpert.com/frontend/open/company_projects/:id

请求参数:

参数名称 是否必须 说明
id 斑马计划id
access_token 斑马资源访问票据
hack_style 自定义样式(css)文件地址

示例:

测试环境地址:https://b.zpert.com/frontend/open/company_projects/12?access_token=xxxxxx&hack_style=https://demo.com/a.css

正式环境地址:https://zpert.com/frontend/open/company_projects/12?access_token=xxxxxx&hack_style=https://demo.com/a.css

斑马计划内容字段说明(zpet)

内容示例(必填字段)

{
  "store_type": "zpert",
  "calendars": [
    {
      "id": 7,
      "name": "标准",
      "work_periods": [
        [
 28800,
 43200
        ],
        [
 46800,
 61200
        ]
      ]
    }
  ],
  "default_calendar_id": 7,
  "work_styles": [
    {
      "name_style": 2,
      "name_align": 1,
      "pen": {
        "lopnColor": 0,
        "lopnStyle": 0,
        "lopnWidth_x": 1
      },
      "font": {
        "lfHeight": -12,
        "lfWidth": 0,
        "lfWeight": 400,
        "lfItalic": 0,
        "lfUnderline": 0,
        "lfStrikeOut": 0,
        "lfCharSet": 134,
        "color": 16711680,
        "lfFaceName": "宋体"
      },
      "show_content": 0,
      "note_show_flags": 0,
      "flags": {
        "is_key": false,
        "is_parent": false,
        "type": 0,
        "draw_type": 0
      },
      "gantt_style": {
        "bar_brush": {
 "lbStyle": 0,
 "lbColor": 16758609,
 "lbHatch": 3
        },
        "font": {
 "lfHeight": -15,
 "lfWidth": 0,
 "lfWeight": 400,
 "lfItalic": 0,
 "lfUnderline": 0,
 "lfStrikeOut": 0,
 "lfCharSet": 134,
 "color": 0,
 "lfFaceName": "宋体"
        },
        "grid_row_color": 16777215,
        "left_show_content": 0,
        "right_show_content": 0,
        "top_show_content": 0,
        "bottom_show_content": 0,
        "grid_row_height": 21,
        "is_auto_adjust_row_height": true
      }
    },
    {
      "name_style": 2,
      "name_align": 1,
      "pen": {
        "lopnColor": 255,
        "lopnStyle": 0,
        "lopnWidth_x": 3
      },
      "font": {
        "lfHeight": -16,
        "lfWidth": 0,
        "lfWeight": 400,
        "lfItalic": 0,
        "lfUnderline": 0,
        "lfStrikeOut": 0,
        "lfCharSet": 134,
        "color": 8421376,
        "lfFaceName": "宋体"
      },
      "show_content": 0,
      "note_show_flags": 0,
      "flags": {
        "is_key": true,
        "is_parent": true,
        "type": 0,
        "draw_type": 2
      },
      "gantt_style": {
        "bar_brush": {
 "lbStyle": 0,
 "lbColor": 10388851,
 "lbHatch": 3
        },
        "font": {
 "lfHeight": -15,
 "lfWidth": 0,
 "lfWeight": 700,
 "lfItalic": 0,
 "lfUnderline": 0,
 "lfStrikeOut": 0,
 "lfCharSet": 134,
 "color": 0,
 "lfFaceName": "宋体"
        },
        "grid_row_color": 16777215,
        "left_show_content": 0,
        "right_show_content": 0,
        "top_show_content": 0,
        "bottom_show_content": 0,
        "grid_row_height": 21,
        "is_auto_adjust_row_height": false
      }
    }
  ],
  "dots_size": 4,
  "prop": {
    "part": {
      "same_height": true,
      "width": 60,
      "show": 1,
      "horz_align": 0,
      "vert_align": 1,
      "line_width": 1,
      "line_color": 12615808
    },
    "font_set": {
      "work_logfont": {
        "lfHeight": -12,
        "lfWidth": 0,
        "lfWeight": 400,
        "lfItalic": 0,
        "lfUnderline": 0,
        "lfStrikeOut": 0,
        "lfCharSet": 134,
        "color": 16711680,
        "lfFaceName": "宋体"
      },
      "num_logfont": {
        "lfHeight": -9,
        "lfWidth": 0,
        "lfWeight": 400,
        "lfItalic": 0,
        "lfUnderline": 0,
        "lfStrikeOut": 0,
        "lfCharSet": 134,
        "color": 32768,
        "lfFaceName": "宋体"
      },
      "milestone_logfont": {
        "lfHeight": -12,
        "lfWidth": 0,
        "lfWeight": 400,
        "lfItalic": 0,
        "lfUnderline": 0,
        "lfStrikeOut": 0,
        "lfCharSet": 134,
        "color": 16711680,
        "lfFaceName": "宋体"
      },
      "title_logfont": {
        "lfHeight": -48,
        "lfWidth": 0,
        "lfWeight": 400,
        "lfItalic": 0,
        "lfUnderline": 0,
        "lfStrikeOut": 0,
        "lfCharSet": 134,
        "color": 255,
        "lfFaceName": "宋体"
      },
      "script_logfont": {
        "lfHeight": -12,
        "lfWidth": 0,
        "lfWeight": 400,
        "lfItalic": 0,
        "lfUnderline": 0,
        "lfStrikeOut": 0,
        "lfCharSet": 134,
        "color": 0,
        "lfFaceName": "宋体"
      },
      "script1_logfont": {
        "lfHeight": -12,
        "lfWidth": 0,
        "lfWeight": 400,
        "lfItalic": 0,
        "lfUnderline": 0,
        "lfStrikeOut": 0,
        "lfCharSet": 134,
        "color": 0,
        "lfFaceName": "宋体"
      },
      "jobtype_logfont": {
        "lfHeight": -16,
        "lfWidth": 0,
        "lfWeight": 400,
        "lfItalic": 0,
        "lfUnderline": 0,
        "lfStrikeOut": 0,
        "lfCharSet": 134,
        "color": 8421376,
        "lfFaceName": "宋体"
      },
      "src_logfont": {
        "lfHeight": -12,
        "lfWidth": 0,
        "lfWeight": 400,
        "lfItalic": 0,
        "lfUnderline": 0,
        "lfStrikeOut": 0,
        "lfCharSet": 134,
        "color": 0,
        "lfFaceName": "宋体"
      },
      "src_label_logfont": {
        "lfHeight": -12,
        "lfWidth": 0,
        "lfWeight": 400,
        "lfItalic": 0,
        "lfUnderline": 0,
        "lfStrikeOut": 0,
        "lfCharSet": 134,
        "color": 16711680,
        "lfFaceName": "宋体"
      },
      "annotation_logfont": {
        "lfHeight": -12,
        "lfWidth": 0,
        "lfWeight": 400,
        "lfItalic": 0,
        "lfUnderline": 0,
        "lfStrikeOut": 0,
        "lfCharSet": 134,
        "color": 16711680,
        "lfFaceName": "宋体"
      }
    },
    "print": {
      "left_margin": 20.0,
      "top_margin": 20.0,
      "right_margin": 20.0,
      "bottom_margin": 20.0,
      "paper_size": -1,
      "orientation": 2,
      "print_preview_horizon_page_num": 1,
      "print_preview_vertical_page_num": 1
    },
    "gantt_set": {
      "name": "斑马进度计划1",
      "f_name": "The Gantt Chart of Zebra Project",
      "work_height": 21,
      "bar_height": 12,
      "is_show_separator": true,
      "is_show_links": true,
      "left_show_content": 0,
      "right_show_content": 0,
      "top_show_content": 0,
      "bottom_show_content": 0,
      "brush": {
        "lbStyle": 0,
        "lbColor": 0,
        "lbHatch": 3
      },
      "left_margin": 100.0,
      "fonts": {
        "ordinary": {
 "lfHeight": -15,
 "lfWidth": 0,
 "lfWeight": 400,
 "lfItalic": 0,
 "lfUnderline": 0,
 "lfStrikeOut": 0,
 "lfCharSet": 134,
 "color": 0,
 "lfFaceName": "宋体"
        },
        "parent": {
 "lfHeight": -15,
 "lfWidth": 0,
 "lfWeight": 700,
 "lfItalic": 0,
 "lfUnderline": 0,
 "lfStrikeOut": 0,
 "lfCharSet": 134,
 "color": 0,
 "lfFaceName": "宋体"
        },
        "key": {
 "lfHeight": -15,
 "lfWidth": 0,
 "lfWeight": 400,
 "lfItalic": 0,
 "lfUnderline": 0,
 "lfStrikeOut": 0,
 "lfCharSet": 134,
 "color": 255,
 "lfFaceName": "宋体"
        },
        "milestone": {
 "lfHeight": -15,
 "lfWidth": 0,
 "lfWeight": 400,
 "lfItalic": 0,
 "lfUnderline": 0,
 "lfStrikeOut": 0,
 "lfCharSet": 134,
 "color": 0,
 "lfFaceName": "宋体"
        }
      },
      "is_bold_out_frame": true,
      "gantt_pen_set": {
        "ordinary": {
 "lopnColor": 16758609,
 "lopnStyle": 0,
 "lopnWidth_x": 1
        },
        "key": {
 "lopnColor": 8750591,
 "lopnStyle": 0,
 "lopnWidth_x": 3
        },
        "link": {
 "lopnColor": 11568456,
 "lopnStyle": 0,
 "lopnWidth_x": 0
        },
        "free_time": {
 "lopnColor": 65280,
 "lopnStyle": 0,
 "lopnWidth_x": 1
        },
        "milestone": {
 "lopnColor": 5221112,
 "lopnStyle": 0,
 "lopnWidth_x": 1
        },
        "progress": {
 "lopnColor": 255,
 "lopnStyle": 0,
 "lopnWidth_x": 3
        },
        "frozen": {
 "lopnColor": 255,
 "lopnStyle": 0,
 "lopnWidth_x": 3
        },
        "frame": {
 "lopnColor": 0,
 "lopnStyle": 0,
 "lopnWidth_x": 4
        },
        "note_border": {
 "lopnColor": 0,
 "lopnStyle": 0,
 "lopnWidth_x": 1
        },
        "parent": {
 "lopnColor": 10388851,
 "lopnStyle": 0,
 "lopnWidth_x": 1
        }
      },
      "parent_work_style": 0
    },
    "language": 0,
    "is_adddlg": false,
    "layer_height1": 40,
    "layer_height2": 100,
    "pert_mode": 1,
    "is_show_grid_editor": true,
    "is_show_pert": true,
    "is_show_src": 1,
    "is_stagger": true,
    "is_hide_unimportant_link": false,
    "pen_set": {
      "ordinary": {
        "lopnColor": 0,
        "lopnStyle": 0,
        "lopnWidth_x": 1
      },
      "key": {
        "lopnColor": 255,
        "lopnStyle": 0,
        "lopnWidth_x": 3
      },
      "link": {
        "lopnColor": 6513507,
        "lopnStyle": 0,
        "lopnWidth_x": 0
      },
      "free_time": {
        "lopnColor": 65280,
        "lopnStyle": 0,
        "lopnWidth_x": 1
      },
      "milestone": {
        "lopnColor": 0,
        "lopnStyle": 0,
        "lopnWidth_x": 1
      },
      "progress": {
        "lopnColor": 255,
        "lopnStyle": 0,
        "lopnWidth_x": 3
      },
      "frozen": {
        "lopnColor": 255,
        "lopnStyle": 0,
        "lopnWidth_x": 3
      },
      "frame": {
        "lopnColor": 0,
        "lopnStyle": 0,
        "lopnWidth_x": 4
      },
      "note_border": {
        "lopnColor": 0,
        "lopnStyle": 0,
        "lopnWidth_x": 1
      },
      "parent": {
        "lopnColor": 0,
        "lopnStyle": 0,
        "lopnWidth_x": 1
      }
    },
    "dot_style": 0,
    "arrow_style": 0,
    "name_pos": 1,
    "time_unit": 0,
    "is_show_script": 1,
    "head_height": 58,
    "cr": 9,
    "crl": 4,
    "cr_x": 9,
    "cr_y": 9,
    "crl_x": 4,
    "crl_y": 4,
    "is_rect_name": false,
    "is_line_title": true,
    "title_blank": 0,
    "is_flag_show": true,
    "is_bold_out_frame": true,
    "src_height": 120,
    "fee_unit": 0,
    "is_time_save": true,
    "time_save": 180000,
    "show_diff": true,
    "is_show_splitline": false,
    "frozen_timeruler_and_partition": false,
    "color_set": {
      "srcsumcolor": 16711680,
      "srcdistcolor": 32768,
      "srcsscolor": 255
    },
    "show_content": 0,
    "name_style": 2,
    "password": "",
    "logic_cname": "",
    "logic_fname": "",
    "is_solid_milestone": false,
    "is_freetime_same_color": false,
    "is_show_freetime": false,
    "is_link_show_freetime": false,
    "is_link_same_style": false,
    "is_parent_show_single_line": false,
    "is_show_duration_in_sections": false,
    "tags": "",
    "desc": "网络图说明",
    "progress_statistics_type": 0,
    "valuation_mode": 0,
    "is_show_finish_ratio": true,
    "is_show_estimate_plan": false,
    "font_size_style": 1,
    "gantt_print": {
      "title": 1,
      "legend": 1,
      "scale": 0,
      "print_page_number": true,
      "gantt_adjust": true
    },
    "is_ai_recommend_name": true,
    "is_ai_recommend_work": true
  },
  "legend": {
    "visible": true,
    "width": 320,
    "height": 160,
    "left_margin": 20,
    "right_margin": 20,
    "warning_num": 0,
    "position": 1,
    "picture_bar": false,
    "script21": "项目负责人",
    "script22": "",
    "script31": "绘图人",
    "script32": "",
    "script41": "审核人",
    "script42": "",
    "script51": "校对人",
    "script52": "",
    "script61": "起始时间",
    "script62": "",
    "script62_1": "",
    "script71": "完成时间",
    "script72": "",
    "script72_1": "",
    "script81": "文件名",
    "script82": "",
    "script91": "总工期(含假期)",
    "script92": "",
    "script92_1": "",
    "script10": "\n  备注:",
    "script11_1": "总工期(工日)",
    "script11_2": "",
    "is_show_catalog_name": true,
    "is_show_script_2": true,
    "is_show_script_3": true,
    "is_show_script_4": true,
    "is_show_script_5": true,
    "is_show_script_6": true,
    "is_show_script_7": true,
    "is_show_script_8": true,
    "is_show_script_9": true,
    "is_show_script_10": true,
    "is_show_script_11": true,
    "is_show_brand": true,
    "developer": "斑马进度计划制作",
    "sDate": "2021-12-07",
    "is_show_symbol": false,
    "show_symbol_mode": 0,
    "show_symbol_list": [
      1,
      1,
      1,
      1,
      1,
      1,
      1,
      1
    ]
  },
  "tasks": [
    {
      "type": 0,
      "id": 0,
      "name": "斑马进度计划1",
      "forign_name": "The Pert Chart of Zebra Project",
      "duration": 576000,
      "plan_start_time": 1638864000,
      "plan_stop_time": 1640538000,
      "work_style_idx": 1,
      "layer": 0,
      "ask_start_time": 1638835200,
      "level": 0,
      "auto_duration": true,
      "draw_type": 2,
      "height": 3,
      "ask_stop_time": 1638921600,
      "is_keywork": true,
      "is_parent": true,
      "last_is_key_work": false
    }
  ]
}

calendar

日历

json字段 json类型 必填 默认值 意义 范围 导出
name string “” 日历名称
id int 0 唯一标识 如果不填写该字段则会自动生成
work_periods array [ [28800,43200],[46800,61200] ] 工作起止时间对数组(单位:秒数,默认值为8-12点,13-17点) 最大值为24*60*60=86400
vacation_rules array 详见vacation_rule 休息日数组

rule

json字段 json类型 必填 默认值 意义 范围 导出 导入
name string “”
type enum 0 休息日类型 0:按日期
1:按周
2:按月
3:按年
start int64_t 系统当前时间 时间段的开始时间 上述type为"0"时,值为选定时间CTime
上述type为"1"时,表示周几,0=周日,1=周一...6=周六,可循环(即开始为周六,结束为周一)
上述type为"2"时,表示每月的哪天,1=1日,2=2日,可循环
上述type为"3"时,表示每年的哪天,值为何月*100+何日,可循环
stop int64_t 系统当前时间+1天 时间段的结束时间 同start
is_vacation bool True 是否休息 bool
is_valid bool True 是否生效 bool
zoom_ratio unsigned int 100 该时间段显示的缩放比例 大于1的整数
is_show_name bool False 是否显示该时间段名称 bool
back_color unsigned int 13154803 该时间段的背景色 0-16777215

feedback

实际进度状态和时间反馈

json字段 json类型 必填 默认值 意义 范围 导出
data_source int 1 数据来源 0:来源于云端服务器
1:来源于本地客户端
2: 空类型,用于默认的过滤选项
status int 0 工作状态 0:未开始
1:进行中
2:已完成
feedback_time int64_t 0 反馈时间 int64_t
details string “” 偏差原因
resolution string “” 解决措施
real_start_time int64_t 进行中和已完成的工作必须有 0 实际开始时间 int64_t 进行中和已完成的工作必须有
real_stop_time int64_t 已完成的工作必须有 0 实际结束时间 int64_t 已完成的工作必须有
predict_stop_time int64_t 进行中的工作必须有 0 预计结束时间 int64_t 进行中的工作必须有
completion_ratio double 0.0 完成占比 0-1
channel string "PC" 渠道

object

根节点

json字段 json类型 必填 默认值 意义 范围 导出
dots_size unsigned int 2 节点数量 大于等于2的int
tasks array 详见task(常用、计算类、其他) 工作数组 详见task
tasks_calc array 详见task_calc 工作信息的计算数据数组 详见task_calc
next_id int 0 工作ID的最大值+1 int
calendars array 标准日历和24小时日历 日历数组 详见calendar
count_time int64_t 0 统计时间:前锋线基准时间,当前的检视、反馈时间 int64_t
default_calendar_id int 7 默认日历id
frozen_time int64_t 0 冻结时间:拉直前锋线的时间 int64_t
guid array 系统自动生成 GUID
links array 详见task 关系数组 详见task
progresses array 详见表progress 前锋线数组 详见表progress
res_kinds array 详见表res_kind 本计划资源集合 详见表res_kind
schema value 详见表schema 自定义字段 详见表schema
store_type string "zpert" 保存类型 "zpert"
version int 2 版本 2
groups array 详见表group 分类集合 详见表group
last_count_time int64_t 0 上一次的检视、反馈时间 int64_t
is_in_schedule_analysis_state bool false 是否进入了检视状态 bool
is_auto_compute_ask_stop_time bool false 是否自动计算计划的要求完成时间 bool
prop value 详见表prop 项目属性相关数据 详见表prop
shared_norms array 详见表res_kind 本计划定额集合 详见表res_kind
local_work_sites array 详见表worksite 本地工作部位 详见表worksite
views_list array 详见表view 本计划视图 详见表view
current_view_idx int 0 当前所用视图的索引值 int
group_by_manager value 详见表groupbymanager 分组管理器 详见表groupbymanager
grid_rows array 详见表gridrow 表格行集合 详见表gridrow
lock_manager value 详见表lockmanager 锁定管理器 详见表lockmanager
extension array 详见表extensions 扩展数据源 详见表extensions
zpert_product string "ZPERT_LIBRARY" 软件产品名称
zpert_version string "0.0.0.0" 软件版本号
version_records array(string) 软件版本号记录
show_root int 0 当前根节点的索引值 int



例子模板说明:

1.后附文件例子中,work_styles、prop和legend字段为必填的默认字段。 2.后附必填字段的文件例子为一个包含必填的基本字段的文件,即空文件。用户可在此基础上增加所用的字段。项目时间需修改tasks数组中第一组的ask_start_time、ask_stop_time和duration。

progress

前锋线(进度检视线)

json字段 json类型 必填 默认值 意义 范围 导出
time int64_t 0 前锋线时间 int64_t
is_display bool False 是否显示 bool
notes string "L" 前锋线说明

res

工作挂接的资源集合

json字段 json类型 必填 默认值 意义 取值范围 导出
res_kind_idx int 本计划资源集合(字段object->res_kinds)的索引
plan double 0.0 计划数量
real double 0.0 实际数量
count_type int 0 0:总量,1:强度
above_max double 最大限量
above_nom double 一般限量

res_kind

本计划资源

json字段 json类型 必填 默认值 意义 取值范围 导出
kind int 7 资源种类 0:人力 1:机械 2:材料 4:合同 5:图纸 6:工程量 7:统计,包括费用,人数,工日 8:特殊的统计(交接工作) 9:工作 10:图表 11:更新 12:网络库 13:自定义资源 14:用于图标 15:自定义资源图 16:自定义资源图-来自物料 17:自定义资源图-来自劳务 18:设备 19:主材费
code string 资源编码
name string 资源名称
unit string 单位
forign_name string 资源外文名称
price double 0.0 资源单价
details string 定额的工作内容
sub_ress array 详见sub_res 子资源或资源定额集合 详见sub_res

schema

自定义字段

json字段 json类型 必填 默认值 意义 取值范围 导出
next_id int 0 不重复id序号
fields array 详见fields 自定义字段集合

fields字段

自定义字段格式

json字段 json类型 必填 默认值 意义 取值范围 导出
id int 0 id
name string 名称
type int 类型 0:文本
1:数值
2:开始时间
3:枚举
4:完成时间
is_visible bool true 表格中是否显示
width int 100 表格中显示列宽度
is_read_only bool false 是否只读
default_value default_value字段的类型:当type为0、3时,default_value为字符串类型当type为1时,default_value为浮点数类型当type为2、4时,default_value为int64类型 default_value字段的默认值:当type为0、3时,“”当type为1时,0.0当type为2、4时,0 字段默认值 default_value字段的默认值:当type为0、3时,文本当type为1时,浮点数范围当type为2、4时,int64范围
is_required_column bool false 列是否必填 bool

source_count

工作资源挂接与资源统计

json字段 json类型 必填 默认值 意义 取值范围 导出
plan double 1 计划数量
current_plan double 0.0 当期计划量
price double 0.0 计划单价
real_price double 0.0 实际单价
contract_price double 0.0 合同单价
unit string “” 单位
is_plan_empty bool true unit和plan都为默认值
ress array 详见res 工作挂接的资源集合 详见res

sub_res

子资源或资源定额

json字段 json类型 必填 默认值 意义 取值范围 导出
res_kind_idx int 本计划资源集合(字段object->res_kinds)的索引
content double 0.0 资源含量

task

工作项

json字段 json类型 必填 默认值 意义 取值范围 导出
id int 1 工作ID 唯一标识,不重复,短id
name string “” 中文名
forign_name string "" 外文名称
duration int 288000 工期(单位秒数),计算公式为:工期 * 每日工作时长(标准日历为8小时) 例如:1工日*8小时*60分*60秒=288000秒
layer int 1 工作所在层(layer*图幅每层高度=该工作的y值,零点在左上角) int
level int 1 父子层级(子比父多1) int
auto_duration bool False 自动计算工期 bool
ask_start_time int64_t 0 要求开始 int64_t
ask_stop_time int64_t 0 要求完成 int64_t
depends string 前置工作(工作序号+关系类型+延迟天数,工作序号指表格中第几项工作) 例如1FS+5
feedbacks array 详见表feedback 实际进度状态和时间反馈 详见表feedback
real_start_time int64_t 0 实际开始时间 int64_t
real_stop_time int64_t 0 实际完成时间 int64_t
type int 类型 0:工作
1:关系
3:里程碑
work_code string “” 编码
plan_start_time int64_t 0 计划开始时间 int64_t
plan_stop_time int64_t 0 计划完成时间 int64_t
estimate_start_time int64_t 0 预测开始时间 int64_t
estimate_stop_time int64_t 0 预测完成时间 int64_t
attachments array 详见表attachment 工作附件(地址链接) 详见表attachment
calendar_id int 7 该工作使用的日历id int
collapsed bool False 是否折叠 bool
custom_values array 自定义字段值(字段内容参见schema)
department value 详见表department 部门及部门负责人 详见表department
depend_type string fs 前置工作关系类型 FF、SS、SF和FS(包括小写)
draw_type unsigned int 0 显示类型 0:线形
1:保留值
2:分区
duration_unit int 0 时间单位 0:天
1:小时
2:分钟
begin_dot_id int 开始节点id int
end_dot_id int 结束节点id int
begin_dot int 开始节点索引序号 int
end_dot int 结束节点索引序号 int
frozen_status_revise int 0 冻结状态,上次调整计划时的工作状态 0:未开始
1:已完成
2:进行中
height int 1 占多少层(包含子工作的层)
is_ask_time_only_waring bool false 要求时间是否仅用来预警 bool
is_typical_deviation bool 是否采用典型偏差计算工作完成占比 bool
last_is_key_work bool false 上次是否是关键工作 bool
last_plan_start_time int64_t 0 上次计划开始时间 int64_t
last_plan_stop_time int64_t 0 上次计划完成时间 int64_t
leader string “” 负责人
leader_id int 1 负责人ID int
notes string “” 备注
project_values object 详见project_values 工作中的计划信息,主要用于网页端
schedule_type unsigned int 2 排网方式 0:越早越好
1:越晚越好
2:系统默认排网方式
source_count array 详见表source_count 工作资源挂接与资源统计
start_percent int 0 本期计划开始(%) 0-100
stop_percent int 100 本期计划完成(%) 0-100
rank int -1 级别 -1,1,2,3,4,5
is_keywork bool false 是否为关键工作 bool
is_parent bool false 是否为父工作 bool
parent_id int 父工作的id(仅有云端接口获取数据含此项) int
completion_ratio double 完成占比(仅有云端接口获取数据含此项) 0-1
work_sites array 详见表worksite 工作部位 详见表worksite

group

分类

json字段 json类型 必填 默认值 意义 范围 导出
name string 分类名称
works array 分类包含的工作集合 集合中存储的是工作在tasks中的索引号
frame_width int 1 边框粗细 正数
frame_color unsigned int 8421504 边框颜色(默认灰色) 正数
fill_color unsigned int 32768 填充颜色(默认绿色) 正数
fill_alpha int 50 填充透明度
is_show_works_line bool true 是否显示工作箭线
is_show_works_name bool true 是否显示工作名称和工期
id int 1 id标识 唯一标识,不重复,与工作id、日历id共用,如果不填则会自动生成
work_style value 不添加该字段,系统默认样式 工作样式
is_show_in_legend bool true 网络图中显示为图例

project_values

自定义字段值

json字段 json类型 必填 默认值 意义 取值范围 导出
zerenren object 由id和name两个键值对组成 责任人
zerendanwei array 同上 责任单位
member array 同上 参与人
gongzuobuwei array 同上 工作部位

vacation_rule

休息日(假期)

json字段 json类型 必填 默认值 意义 范围 导出 导入
name string “” 休息日名称
type enum 0 休息日类型 0:按日期
1:按周
2:按月
3:按年
start int64_t 系统当前时间 时间段的开始时间 上述type为"0"时,值为选定时间CTime
上述type为"1"时,表示周几,0=周日,1=周一...6=周六,可循环(即开始为周六,结束为周一)
上述type为"2"时,表示每月的哪天,1=1日,2=2日,可循环
上述type为"3"时,表示每年的哪天,值为何月*100+何日,可循环
stop int64_t 系统当前时间+1天 时间段的结束时间 同start
is_vacation bool True 是否休息 bool
is_valid bool True 是否生效 bool
zoom_ratio unsigned int 100 该时间段显示的缩放比例 大于1的整数
is_show_name bool False 是否显示该时间段名称 bool
back_color unsigned int 13154803 该时间段的背景色 0-16777215

task_calc

task计算类

json字段 json类型 必填 默认值 意义 取值范围 导出
plan_duration_days double 0 计划工期天数 double
front_works_number int 0 前置工作数 int
behind_works_number int 0 后置工作数 int
free_time_difference double 0 自由时差 double
total_time_difference double 0 总时差 double
earlist_start_time int64_t 0 最早开始 int64_t
earlist_stop_time int64_t 0 最早完成 int64_t
latest_start_time int64_t 0 最晚开始 int64_t
latest_stop_time int64_t 0 最晚完成 int64_t
start_time_difference double 0 开始时间差异 double
stop_time_difference double 0 完成时间差异 double
relative_start_time double 0 相对开始 double
relative_stop_time double 0 相对完成 double
estimate_delay_time double 0 预测超期 double
plan_delay_time double 0 计划超期 double
duration_difference double 0 工期差异 double
effect_on_key_path double 0 影响关键线路 double
last_plan_duration double 0 原计划工期(工日) double
start_time_change double 0 开始时间变动 double
stop_time_change double 0 完成时间变动 double
duration_change double 0 工期变动 double
plan_elapsed_time double 0 计划进行时间 double
plan_remaining_time double 0 计划剩余时间 double
plan_total_cost double 0 计划总费用 double
real_total_cost double 0 实际总费用 double
production_value double 0 产值 double
plan_labour double 0 计划总人数 double
real_labour double 0 实际总人数 double
cumulative_completion double 0 累计完成量 double
current_plan_quantities double 0 当期计划量 double
predict_stop_time int64_t 0 预计完成 int64_t
period_start_time int64_t 0 本期开始 int64_t
period_stop_time int64_t 0 本期完成 int64_t
vacation string 0 假期 double
duration_include_vacation double 0 工期(含假期) double
ask_duration_days double 0 要求工期(不包括假期) double
ask_duration_days_include_vacation double 0 要求工期(包括假期) double
last_plan_start_diff_days double 0 原计划开始偏差天数 double
last_plan_stop_diff_days double 0 原计划结束偏差天数 double
last_plan_duration_days double 0 原计划工期天数 double
change_details string 执行情况(计划变动)
change_resolution string 解决措施(计划变动)
real_duration_days double 0 实际工期天数 double
real_start_diff_days double 0 实际开始偏差天数 double
real_stop_diff_days double 0 实际结束偏差天数 double
plan_left_days double 0 计划剩余天数 double
predict_left_days double 0 预计剩余天数 double
progress_details string 执行情况(进度对比)
progress_resolution string 解决措施(进度对比)
plan_delay_days double 0 提前或滞后天数(要求-计划) double
estimate_delay_days double 0 提前或滞后天数(要求-预测) double
completion_ratio double 完成占比(其他类里面也有这个数据) 0-1
stop_delay_days double 进度滞后 double
behind_works string 后置工作
resource_name string 资源名称
resource_unit string 资源单位
resource_price string 资源单价
norm_name string 定额
resource_plan_quantity string 资源计划总量
resource_plan_intensity string 资源计划强度
resource_real_quantity string 资源实际总量
resource_real_intensity string 资源实际强度
count_status int 工作状态; 0:未开始;1:进行中;2:已完成
count_details string 偏差原因
count_resolution string 解决措施
group_name string 工作分类

attachment

附件

json字段 json类型 必填 默认值 意义 取值范围 导出
name string "" 名称
url string "" 链接地址
file_name string "" 文件名

prop

属性

json字段 json类型 必填 默认值 意义 取值范围 导出
cloud value 详见表prop.cloud 云计划信息 详见表prop.cloud
fee_unit int 0 费用产值单位 0代表元、1代表万元、2代表亿元
password string "" 密码
logic_cname string "" 计划中文名
logic_fname string "" 计划外文名
tags string "" 计划标签
desc string "" 计划简介
is_show_estimate_plan bool false 是否预测实际进度 bool
is_show_estimate_plan_in_schedule_analysis_state bool false 在检视状态是否预测实际进度 bool
useable_view_type int 0 可用视图类型 0:全部可用;1:仅可用本计划视图

prop.cloud

云计划信息

json字段 json类型 必填 默认值 意义 取值范围 导出
catalog_name string "" 云关联计划所属的信息的项目名
project_name string 计划所属的广联云项目的信息的项目名
cloud_plan_id string 云关联计划所属的信息的计划id
bim5d_plan_id string 新生产云关联计划id
cloud_catalog_id string 云关联计划所属的信息的项目id
cloud_company_id string 云关联计划所属的信息的租户id
bim5d_org_id string 云关联计划所属的信息的bim5d新接口组织id
bim5d_org_type int 1 云关联计划所属的信息的bim6d新接口组织类型 1表示普通项目节点,2表示模板库项目节点,3表示经典案例项目节点。
plan_id string 计划所属的广联云项目的信息的计划id
cloudt_project_id string 计划所属的广联云项目的信息的项目id
tenant_id string 计划所属的广联云项目的信息的租户id
org_id string 计划所属的广联云项目的信息的bim5d新接口组织id
org_type int 1 计划所属的广联云项目的信息的bim5d新接口组织类型 1表示普通项目节点,2表示模板库项目节点,3表示经典案例项目节点。
is_cloud bool false 是否为云计划的标识 bool

worksite

工作部位

json字段 json类型 必填 默认值 意义 取值范围 导出
local_idx string 本地索引
id string id 本地短id,企业长id
name string 名称 企业的直接取fullName
type int 类型 本地为0,其余表示企业的,1单体2楼层3施工段4自定义

groupbymanager

分组管理器

json字段 json类型 必填 默认值 意义 取值范围 导出
is_grouping bool false 当前是否在分组状态 bool
display_mode int 1 分组父结构在表格中的显示模式 0:不显示;1:树形显示;2:合并行显示
group_settings array 详见表groupbysetting 自定义分组的配置 详见表groupbysetting
curr_setting value 详见表groupbysetting 当前所用分组的配置 详见表groupbysetting

groupbysetting

分组配置

json字段 json类型 必填 默认值 意义 取值范围 导出
id int -1 分组的id -1表示不分组;0表示内置;>0表示自定义
column_id int -1 列id 列id的取值范围
name string "" 列名称
column_name string "" 自定义分组名称
suffix string "" 数据值的附加后缀,例如工期的单位、百分号等
interval_type int 0 间隔类型 0:每个值;1:固定间隔;2:自定义间隔
interval_start value 固定间隔起始值
interval_step value 固定间隔步长
time_unit int 0 时长单位 0:天;1:小时;2:分钟;3:自然天(已废弃)
interval_values array(value) 自定义间隔值

gridrow

表格行

json字段 json类型 必填 默认值 意义 取值范围 导出
type int 表格行类型 0:工作;1:分组行;2:分组依据行;3:分组父;4:空行
work_id int 工作行、分组父行类型必填 工作行的工作的id int
collapsed bool 非工作行和空白行必填 false 折叠状态 bool
row_height int 非工作行和空白行必填 0 行高 int
level int 分组依据行必填 层级 int
name string 分组依据行必填 "" 名称

view

视图

json字段 json类型 必填 默认值 意义 取值范围 导出
id string id string
name string "" 名称
view_mode int 0 视图模式 0:系统视图;1:计划视图;2:企业云视图
view_source int 0 视图来源 0:内置视图;1:自定义视图;2:云视图;3:可配置视图(2PZ组用)
is_show_grid_editor bool true 是否显示表格 bool
is_show_pert_editor bool true 是否显示网络图 bool
pert_mode int 1 网络图模式 1:时标网络图;2:逻辑网络图;4:单代号网络图;6:横道图
display_mode int 0 分组父结构在表格中的显示模式 0:不显示;1:树形显示;2:合并行显示
groupby_setting value 详见表groupbysetting 当前分组配置 详见表groupbysetting
view_columns_info array 详见表view-columninfo 列信息 详见表view-columninfo
lock_col int 0 冻结列数 int
index_column_width int 40 表格索引列的宽度 int
column_filters array 详见表columnfilters 列过滤器信息 详见表columnfilters

view-columninfo

列信息

json字段 json类型 必填 默认值 意义 取值范围 导出
id int -1 列id int
is_visible bool false 列可见性 bool
name string "" 列名称
alias string "" 列别名
width int 0 列宽度 int
data_type int 0 数据类型 int
is_readonly bool false 列是否只读 bool
is_required_column bool false 列是否必填 bool

columnfilters

列筛选器

json字段 json类型 必填 默认值 意义 取值范围 导出
column_id int 列id int
filter_info string "" 列筛选器的json信息

extensions

扩展数据

json字段 json类型 必填 默认值 意义 取值范围 导出
name stirng "" 名称
value stirng ""

lockmanager

锁定管理器

json字段 json类型 必填 默认值 意义 取值范围 导出
is_locking bool false 当前是否为锁定状态 bool
lock_settings array 详见表locksetting 锁定配置 详见表locksetting

locksetting

锁定配置

json字段 json类型 必填 默认值 意义 取值范围 导出
lock_attributes_flag uint64_t 0 锁定属性的标志位 uint64_t
is_delete_locked bool false 是否将删除锁定 bool
is_add_locked bool false 是否将增加锁定 bool
filter_manager value 锁定的工作条件,能通过过滤器的工作就会被锁定 详见表filtermanager

filtermanager

筛选器控制器

json字段 json类型 必填 默认值 意义 取值范围 导出
is_valid bool false 是否开启筛选器 bool
filters array 详见表filters 筛选器列表 详见表filters

filters

筛选器

json字段 json类型 必填 默认值 意义 取值范围 导出
checked_item int 日期类型筛选器必填 0 文本类型过滤器的文本匹配类型; 日期类型过滤器的日期匹配类型;数字类型过滤器的数字匹配类型; 枚举或整型 文本类型可选值:kTextNo = 0, 默认值不可用 kTextEqual =1,等于某个字符串;kTextNoEqual=2, 不等于某个字符串;kTextInclude=3,包含某个字符串;kTextNoInclude=4,不包含某个字符串;日期类型过滤器可选值:某个时间之前:7; 某个时间之后:8; 介于某两个时间之间:9;数字类型过滤器的可选值:kNumbericalNo = 0, 默认值不可用 kNumbericalEqual=1,等于kNumbericalLessThan=2,小于kNumbericalMoreThan=3,大于 kNumbericalBetween=4,介于
filter_only_child bool true 是否仅筛选子工作 bool
filter_type string "" 过滤器类型
filter_label int 0 过滤器标志位 0:列上的筛选器;1:期间计划筛选器;2:进度分析;3锁定管理
attribute_to_match string "" 需要与过滤器匹配的属性值
search_str string 文本类型筛选器必填 "" 用于和文本类型过滤器匹配的字符串
start_date int64_t 日期类型筛选器必填 0 日期类型过滤器的日期范围起始时间 int64_t
end_date int64_t 日期类型筛选器必填 0 日期类型过滤器的日期范围结束时间 int64_t
select_values array(string) 枚举类型过滤器的筛选字符
lower_bound double 数字类型筛选器必填 -2147483647 - 1 数字过滤器的数字范围最小值 double
upper_bound double 数字类型筛选器必填 2147483647 数字过滤器的数字范围最大值 double
is_total_include bool 快速日期筛选必填 false 是否全部包含 bool

department

部门

json字段 json类型 必填 默认值 意义 取值范围 导出
first_sector_id string "" 一级部门id
first_sector string "" 一级部门名称
second_sector_id string "" 二级部门id
second_sector string "" 二级部门名称
third_sector_id string "" 三级部门id
third_sector string "" 三级部门名称
first_leader_id string "" 一级负责人id
first_leader string "" 一级负责人名称
second_leader_id string "" 二级负责人id
second_leader string "" 二级负责人名称
third_leader_id string "" 三级负责人id
third_leader string "" 三级负责人名称

计划更新通知消息(mq)

斑马客户端上传计划(新建、更新)、删除计划斑马服务端向消息队列中发送通知消息;消息队列由项目管理平台部提供,消息队列相关内容请联系:刘延成或王耀廷

消息队列(config)

测试环境Topic:VPC_TEST_GLODON_ZPET_PROJECT_SYNC

正式环境Topic:VPC_PRODUCT_GLODON_ZPET_PROJECT_SYNC

消息体格式(body)

{
  tenant_id: '123qwesdrf', 
  cloudt_project_id: 'qqazwsxedc',
  zpert_company_id: '12',
  zpert_item_id: '12',
  zpert_plan_id: '12',
  user: {
    id: '12',
    phone: '18112345678',
    email: 'test@glodon.com',
    global_id: 'qwertyhgbn'
  },
  type: 'CREATE',
  updated_at: '2020-08-19 12:12:00'
}
  1. tenant_id: 数字项目集成管理平台租户ID
  2. cloudt_project_id: 数字项目集成管理平台项目ID
  3. zpert_company_id: 斑马进度企业ID,对应数字项目集成管理平台租户ID
  4. zpert_item_id: 斑马进度项目ID,对应数字项目集成管理平台项目ID
  5. zpert_plan_id: 斑马进度计划ID
  6. user:计划上传人信息,id为斑马进度用户ID,phone为用户手机号,email为用户邮箱,global_id为广联达用户中心的global_id
  7. type: 操作类型,取值:CREATE、UPDATE、DELETE,分别表示计划创建、更新和删除操作
  8. updated_at: 操作时间

计划组件(zpert wasm)

计划组件官方文档

计划组件官方文档地址(address)

  1. 内网测试环境:https://geip-pre.glodon.com/zpert/wasm-component/docs/
  2. 外网可访问的测试环境
  3. 正式环境