openData StudioEnglish
UKG Pro 图标

UKG Pro 打卡与令牌数据 API

UKG, Inc. · 企业办公

在 Google Play 中打开

UKG Pro 是 UKG, Inc.（Ultimate Kronos Group）推出的员工自助应用。UKG 总部位于马萨诸塞州洛厄尔，由 Ultimate Software 与 Kronos 合并而成。员工添加雇主租户后，通过 UKG AuthN 或公司单点登录进入原生外壳：一侧是 Pro 薪资与人力资源界面——工资单、薪资摘要、我的休假、我的排班、团队工时表、组织架构、统一收件箱审批与 UKG Talk；另一侧是 Kronos Dimensions 考勤——上下班打卡、无网时离线保存打卡并稍后上传，以及在地理围栏地图上标出进/出/转移打卡。应用面向在美国运行 UKG Pro（原 UltiPro）和 UKG Dimensions / Workforce Central 的雇主，服务需要在手机而非考勤机上查看薪资、休假、排班与打卡的时薪/月薪员工、主管与考勤员，对位 ADP Mobile Solutions、Workday 与 Paylocity 的员工端。

导入的打卡事件带有 punchTime 与 punchValid 标记；在已知地点内打卡时还可附 punchGeoLocation、geofenceMethod 与 jobName。离线上传前会先读取 serverTime、员工的 gmtOffset / zoneId 以及 EMPLOYEE_OFFLINE_MOBILE_PUNCH 等 FACP 开关，以便按 DST transitions 校正时间戳再提交。

会话上的身份信封包含 personId、personBadgeNumber 与租户 vanityUrl；AuthN 返回 accessToken、refreshToken 以及 WFM/Talk 作用域（access:wfm、read:talk、write:talk）。Pro 网关配置再补上 componentCompanyId 与 companyAccessCode。Talk 再用 externalUID、mobileNumber、tenantDomain 与 spotId 映射同一员工。薪资对账、出勤审计、目录关联与 IT 开通机器人消费这些字段；openData Studio 把它们变成可调用的开放数据。

应用截图

  • UKG Pro 应用截图 1
  • UKG Pro 应用截图 2
  • UKG Pro 应用截图 3
  • UKG Pro 应用截图 4
  • UKG Pro 应用截图 5
  • UKG Pro 应用截图 6
  • UKG Pro 应用截图 7
  • UKG Pro 应用截图 8

API 端点一览

以下端点与请求/响应示例均依据应用界面推导重构，为示意说明，并非实际抓包。

  • 导入离线考勤打卡

    POST /v1/clock/{tenantId}/punches/batch opendata

    把设备在离线时保存的上班、下班与岗位转移打卡上传到 Workforce Central / Dimensions，写入员工工时卡。

    认证方式： 会话 Cookie 加 AuthN Bearer accessToken。写操作附带 GET /v1/clock/{tenantId}/feature-flags 取得的 csrf。

    • personId
    • personNum
    • personBadgeNumber
    • punchTime
    • punchValid
    • punchXferJson
    • punchGeoLocation
    • geofenceMethod
    • jobName
    • deviceTimeAtPunchSec
    • serverTimeAtPunchSec
    POST /v1/clock/ACME_PROD/punches/batch HTTP/1.1
Authorization: Bearer <access_token>
Content-Type: application/json

{
  "punches": [
    {
      "personId": "10432",
      "personNum": "E-10432",
      "personBadgeNumber": "88421",
      "punchTime": 1759687200,
      "punchValid": "yes",
      "punchXferJson": "{}",
      "punchGeoLocation": {"latitude": 42.6334, "longitude": -71.3162, "geofenceMethod": "gps"},
      "jobName": "Warehouse-A",
      "deviceTimeAtPunchSec": 1759687200,
      "serverTimeAtPunchSec": 1759687201
    }
  ]
}
    {
  "imported": 1,
  "failed": 0,
  "punches": [
    {
      "personId": "10432",
      "punchTime": 1759687200,
      "punchValid": "yes",
      "verified": true
    }
  ]
}

  • 离线打卡信息与 FACP 开关

    GET /v1/clock/{tenantId}/offline-policy opendata

    读取租户服务器时钟、员工时区/币种偏好与夏令时转换表，以及决定是否允许离线打卡、取消餐扣和记录位置的 FACP 功能开关，供上传前校验。

    认证方式： AuthN 的 Bearer accessToken 加租户会话 Cookie。查询参数携带 tenantId 与 facpNames。

    • serverTime
    • userDetails
    • gmtOffset
    • zoneId
    • currencyPreference
    • userPreferences
    • rules
    • transitions
    • dateTimeBefore
    • offsetBefore
    • dateTimeAfter
    • offsetAfter
    • tenantId
    • facpNames
    GET /v1/clock/ACME_PROD/offline-policy?facpNames=EMPLOYEE_OFFLINE_MOBILE_PUNCH,TS_CANCEL_MEAL_DEDUCTS,EMPLOYEE_LOCATION_RECORD_DATA HTTP/1.1
Authorization: Bearer <access_token>
    {
  "serverTime": 1759687300,
  "userDetails": {
    "timeZone": {"gmtOffset": -14400, "zoneId": "America/New_York"},
    "currencyPreference": "USD",
    "userPreferences": {"locale": "en_US"}
  },
  "rules": {
    "EMPLOYEE_OFFLINE_MOBILE_PUNCH": true,
    "TS_CANCEL_MEAL_DEDUCTS": false,
    "EMPLOYEE_LOCATION_RECORD_DATA": true
  },
  "transitions": [
    {
      "dateTimeBefore": "2026-03-08T02:00:00",
      "offsetBefore": -18000,
      "dateTimeAfter": "2026-03-08T03:00:00",
      "offsetAfter": -14400
    }
  ]
}

  • 最近一次打卡与常用转移

    GET /v1/clock/{tenantId}/latest-and-favorites opendata

    返回员工最近一次打卡以及最近使用的岗位/劳务账户转移，供打卡按钮预填下一次进/出或转移。

    认证方式： Bearer accessToken 加租户会话 Cookie。

    • lastPunch
    • punchTime
    • punchValid
    • jobName
    • geofenceMethod
    • punchGeoLocation
    • mru
    • punchXferJson
    GET /v1/clock/ACME_PROD/latest-and-favorites HTTP/1.1
Authorization: Bearer <access_token>
    {
  "lastPunch": {
    "punchTime": 1759680000,
    "punchValid": "yes",
    "jobName": "Warehouse-A",
    "geofenceMethod": "wifi",
    "punchGeoLocation": {"latitude": 42.6334, "longitude": -71.3162}
  },
  "mru": [
    {"jobName": "Warehouse-A", "punchXferJson": "{\"laborAccount\":\"LA-12\"}"},
    {"jobName": "Shipping-Dock", "punchXferJson": "{\"laborAccount\":\"LA-18\"}"}
  ]
}

  • 移动能力与 CSRF 令牌

    GET /v1/clock/{tenantId}/feature-flags opendata

    签发外壳在打卡导入及其他写操作上携带的 CSRF 令牌，并声明租户已启用的 Dimensions 移动能力。

    认证方式： SSO 之后的租户会话 Cookie。用于换取后续写调用的 CSRF。

    • csrf
    • offlinePunch
    • locationRecordData
    • cancelMealDeducts
    GET /v1/clock/ACME_PROD/feature-flags HTTP/1.1
Cookie: TENANT_SSO=...
    {
  "csrf": "c9f1e2a0-4b7d-4c21-9e01-8f2d6a41b0c7",
  "offlinePunch": true,
  "locationRecordData": true,
  "cancelMealDeducts": false
}

  • 移动会话上下文

    GET /v1/people/{tenantId}/me osint

    返回已登录员工的身份信封——人员、工牌、租户与 vanity URL——后续打卡、排班与收件箱调用都绑定在该信封上。

    认证方式： Bearer accessToken 加租户会话 Cookie。

    • personId
    • personNum
    • personName
    • userName
    • personBadgeNumber
    • tenantId
    • vanityUrl
    • offlineUser
    GET /v1/people/ACME_PROD/me HTTP/1.1
Authorization: Bearer <access_token>
    {
  "personId": "10432",
  "personNum": "E-10432",
  "personName": "Jane Doe",
  "userName": "jdoe",
  "personBadgeNumber": "88421",
  "tenantId": "ACME_PROD",
  "vanityUrl": "https://acme.example.invalid",
  "offlineUser": false
}

  • 移动客户端启动

    GET /v1/shell/{tenantId}/boot opendata

    告知混合外壳当前租户属于哪个父产品（Dimensions 或 Pro），以及登录后打开哪个首页模块。

    认证方式： Bearer accessToken 加租户会话 Cookie。

    • parentProduct
    • mobileHome
    • tenantId
    • modules
    GET /v1/shell/ACME_PROD/boot HTTP/1.1
Authorization: Bearer <access_token>
    {
  "parentProduct": "dimensions",
  "mobileHome": "punch",
  "tenantId": "ACME_PROD",
  "modules": ["timekeeping", "scheduling", "inbox"]
}

  • 登录完成握手

    GET /v1/session/{tenantId}/ready opendata

    确认移动客户端的 SSO 已完成，外壳随后可调用功能开关、身份信封与打卡接口。

    认证方式： GET /v1/session/{tenantId}/sso-start 建立的 SSO 会话 Cookie。在功能开关与身份信封之前完成移动登录握手。

    • status
    • personId
    • tenantId
    GET /v1/session/ACME_PROD/ready HTTP/1.1
Cookie: TENANT_SSO=...
    {
  "status": "ok",
  "personId": "10432",
  "tenantId": "ACME_PROD"
}

  • 签发 OAuth 访问令牌

    GET /v1/session/{tenantId}/bearer opendata

    签发外壳保存、并在 Dimensions REST 调用上以 Bearer 携带的 accessToken。

    认证方式： GET /v1/session/{tenantId}/sso-start 之后的 SSO 会话。返回后续 Bearer 调用使用的 OAuth 令牌字段。

    • accessToken
    • expiresInSeconds
    • refreshToken
    • oidcFlag
    • expirationDateInSeconds
    • clientId
    • appKey
    GET /v1/session/ACME_PROD/bearer HTTP/1.1
Cookie: TENANT_SSO=...
    {
  "accessToken": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "expiresInSeconds": 3600,
  "refreshToken": "rt-c91e2b77",
  "oidcFlag": true,
  "expirationDateInSeconds": 1759690900,
  "clientId": "ukgpromobileapp",
  "appKey": "ukg-oneapp-android"
}

  • AuthN 连接（OIDC 探测）

    GET /v1/identity/oidc/handshake opendata

    用深链 OIDC 令牌探测 AuthN，返回本会话使用的信封（access / id / refresh 令牌及 WFM/Talk 作用域）。

    认证方式： 查询/正文携带深链 OIDC 交接的 oidcServerUrl 与 oidcToken。无需事先 Bearer。

    • oidcServerUrl
    • oidcToken
    • accessToken
    • idToken
    • refreshToken
    • scope
    • clientId
    • authNInstance
    GET /v1/identity/oidc/handshake HTTP/1.1
Content-Type: application/json

{
  "oidcServerUrl": "https://acme.okta.com/oauth2/default",
  "oidcToken": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9..."
}
    {
  "accessToken": {
    "value": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
    "scope": "read:userinfo hrms_data access:wfm read:talk write:talk offline_access openid profile email"
  },
  "idToken": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "refreshToken": "rt-c91e2b77",
  "clientId": "ukgpromobileapp",
  "authNInstance": "prod-us"
}

  • 移动应用配置（Pro 网关）

    GET /v1/pro/{companyId}/modules opendata

    加载员工所属公司的 Pro 移动网关配置——模块列表（工资单、休假、排班、组织架构、收件箱）与 TMS 租户 id。

    认证方式： Pro 公司会话。可选查询参数 componentCompanyId 来自已登录 Pro 档案。

    • componentCompanyId
    • companyAccessCode
    • parentProduct
    • modules
    • tmsTenant
    GET /v1/pro/C0012/modules?componentCompanyId=C0012 HTTP/1.1
Authorization: Bearer <access_token>
    {
  "componentCompanyId": "C0012",
  "companyAccessCode": "ACME1",
  "parentProduct": "pro",
  "modules": ["pro.pay-statements", "pro.my-time-off", "pro.my-schedule", "pro.org-chart", "pro.inbox.todo.approve"],
  "tmsTenant": {"id": "tms-77", "instances": ["prod-atl"]}
}

  • 认证 access_token（表单提交）

    POST /v1/identity/oauth/exchange opendata

    用授权码换取 OAuth access_token / refresh_token / id_token 三件套，供租户主机签发路径不可用时使用。

    认证方式： OAuth2 表单 POST，携带 grant_type 以及凭证 Bean 中的 clientId/clientSecret。租户主机 GET /v1/session/{tenantId}/bearer 的替代路径。

    • grant_type
    • access_token
    • token_type
    • expires_in
    • refresh_token
    • id_token
    • scope
    POST /v1/identity/oauth/exchange HTTP/1.1
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code&client_id=ukgpromobileapp&client_secret=******&code=spl-8f21
    {
  "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_token": "rt-c91e2b77",
  "id_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "scope": "read:userinfo hrms_data access:wfm offline_access openid profile email"
}

  • SSO 门户引导

    GET /v1/session/{tenantId}/sso-start opendata

    打开租户 SSO 门户以启动移动登录，并签发后续调用携带的 Cookie。

    认证方式： 未认证入口。公司 vanity URL 加可选 companyAccessCode；设置供 GET /v1/session/{tenantId}/ready 与 GET /v1/session/{tenantId}/bearer 使用的 SSO Cookie。

    • loginUrl
    • vanityUrl
    • companyAccessCode
    GET /v1/session/ACME_PROD/sso-start HTTP/1.1
    {
  "loginUrl": "/v1/session/ACME_PROD/sso-start",
  "vanityUrl": "https://acme.example.invalid",
  "companyAccessCode": "ACME1"
}

  • 移动登录设置

    GET /v1/session/{tenantId}/brand opendata

    返回租户 vanity URL 与品牌信息，供登录前屏幕在 SSO 之前绘制雇主配色。

    认证方式： 未认证。在 SSO 门户之前解析租户 vanity URL 与品牌。

    • vanityUrl
    • brandingVersion
    • brandingColor
    • companyAccessCode
    GET /v1/session/ACME_PROD/brand HTTP/1.1
    {
  "vanityUrl": "https://acme.example.invalid",
  "brandingVersion": "2026.4",
  "brandingColor": "#0057B8",
  "companyAccessCode": "ACME1"
}

  • OIDC 会话（用户管理）

    GET /v1/people/{tenantId}/oidc-record osint

    读取已登录员工的 OIDC 会话记录，供外壳把 personId 与 userName 绑定到后续 WFM 调用。

    认证方式： SSO Cookie。

    • oidcSession
    • personId
    • userName
    • personName
    • email
    GET /v1/people/ACME_PROD/oidc-record HTTP/1.1
Cookie: TENANT_SSO=...
    {
  "oidcSession": "sess-10432",
  "personId": "10432",
  "userName": "jdoe",
  "personName": "Jane Doe",
  "email": "[email protected]"
}

  • Talk 自定义登录

    POST /v1/talk/session/from-bearer opendata

    用 AuthN 的 accessToken 换取 Talk 会话，让内嵌的职场频道模块加载员工频道。

    认证方式： JSON 正文把 AuthN 的 accessToken 作为 access_token 提交。

    • access_token
    • token
    • tenantDomain
    • parentProduct
    • spotId
    POST /v1/talk/session/from-bearer HTTP/1.1
Content-Type: application/json

{
  "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9..."
}
    {
  "token": "talk-sess-c91e",
  "tenantDomain": "acme.talk.example.invalid",
  "parentProduct": "pro",
  "spotId": "spot-acme-prod"
}

  • 按令牌查询 Talk 用户

    POST /v1/talk/people/lookup osint

    解析已登录员工的 Talk 档案——姓名、邮箱、mobileNumber，以及映射回 personId 的 HRIS externalUID。

    认证方式： 自定义登录之后的 Talk 会话。正文携带 token 与 user_agent。

    • id
    • firstName
    • lastName
    • name
    • email
    • mobileNumber
    • externalUID
    • status
    • online
    • customFieldData
    POST /v1/talk/people/lookup HTTP/1.1
Content-Type: application/json

{
  "token": "talk-sess-c91e",
  "user_agent": "UkgOneApp ukgpromobileapp Android"
}
    {
  "id": "u-10432",
  "firstName": "Jane",
  "lastName": "Doe",
  "name": "Jane Doe",
  "email": "[email protected]",
  "mobileNumber": "+1-978-555-0142",
  "externalUID": "10432",
  "status": "active",
  "online": {"state": "online"},
  "customFieldData": []
}

  • Talk 频道（spot）详情

    GET /v1/talk/workplace/{spotId} opendata

    加载员工的 Talk 工作频道（spot）——tenantDomain、parentProduct 与管理幅度开关，决定 Talk 首页展示哪些群组与提醒。

    认证方式： 人员查询之后的 Talk 会话。

    • spotId
    • name
    • tenantDomain
    • parentProduct
    • userEmail
    • userMobile
    • isSpanOfControlEnabled
    • unreadAlertsCount
    GET /v1/talk/workplace/spot-acme-prod HTTP/1.1
Authorization: Bearer talk-sess-c91e
    {
  "spotId": "spot-acme-prod",
  "name": "Acme Workplace",
  "tenantDomain": "acme.talk.example.invalid",
  "parentProduct": "pro",
  "userEmail": "[email protected]",
  "userMobile": "+1-978-555-0142",
  "isSpanOfControlEnabled": true,
  "unreadAlertsCount": 3
}

数据类别

  • 考勤打卡
  • 最近打卡状态
  • 定位打卡
  • OAuth 令牌
  • OIDC 会话
  • 员工身份
  • 租户配置
  • CSRF 会话
  • FACP 功能开关
  • Talk 职场身份

数据使用场景与案例

  • 劳动力打卡对账

    考勤数据流按 personId、punchTime 与 punchValid 拉取已导入打卡，并与最近打卡快照核对，避免发薪关账时漏掉离线打卡。

  • 地理围栏出勤审计

    合规任务读取每笔导入的 punchGeoLocation、geofenceMethod 与 jobName，标出已知地点半径之外或缺少 GPS/Wi-Fi 证明的打卡。

  • 按租户的 SSO 开通

    IT 自动化消费 componentCompanyId、companyAccessCode、vanityUrl 以及 AuthN 的 accessToken/refreshToken 信封，无需服务台逐步指导即可为新员工开通移动租户。

  • 主管收件箱路由

    当移动应用配置列出 pro.inbox.todo.approve 与团队工时表模块后，机器人可用 mobile context 中的 personId 把待审批派给对应经理。

  • Talk 与 HRIS 身份关联

    目录任务把 Talk UserProfileModel 的 externalUID 接到 Dimensions 的 personId，再用 tenantDomain 与 spotId 把同一员工开通进职场频道，无需二次邀请。

常见问题

UKG Pro 的移动调用如何鉴权？

员工输入公司 vanity URL 或 companyAccessCode，在租户门户完成 SSO 后，外壳保存 AuthN 的 accessToken（以及 refreshToken / idToken）。后续考勤调用以 Bearer 加会话 Cookie 发送该令牌；打卡导入等写操作还会附带 GET /v1/clock/{tenantId}/feature-flags 返回的 csrf。

考勤集成能读到哪些打卡字段？

POST /v1/clock/{tenantId}/punches/batch 接受 personId、personNum、personBadgeNumber、punchTime、punchValid、punchXferJson、punchGeoLocation 与 jobName。GET /v1/clock/{tenantId}/latest-and-favorites 返回最近一次打卡与常用转移；GET /v1/clock/{tenantId}/offline-policy 在离线上传前提供 serverTime、时区偏移和 FACP 开关。

同一个客户端会同时访问 UKG Pro 薪资和 Kronos Dimensions 吗？

会。原生外壳同时承载两端。考勤 REST 在租户打卡面（/v1/clock/{tenantId}/… 与打卡批量导入）。Pro 的工资单、休假、排班、组织架构与收件箱模块由 GET /v1/pro/{companyId}/modules 配置，使用 Pro 档案中的 componentCompanyId。

离线打卡可以稍后上传吗？

可以。启用 EMPLOYEE_OFFLINE_MOBILE_PUNCH 后，应用用 deviceTimeAtPunchSec / serverTimeAtPunchSec 和 punchValid 保存打卡，AuthN 成功后提交到 POST /v1/clock/{tenantId}/punches/batch。

更多企业办公类应用

相关主题

  • UKG Pro API
  • UKG Pro 端点
  • UKG 打卡导入
  • Kronos Dimensions 最近打卡
  • UKG AuthN accessToken
  • UltiPro 移动网关
  • 员工考勤 API
  • UKG Pro 租户配置

需要集成这个 App 的数据 API？

我们可为任意指定 App 交付定制集成——源码交付 USD 500 起，或托管 API 按调用计费。告诉我们您需要的数据即可。

  • 每个项目均签 NDA 与 SOW
  • 3–7 天交付
  • 验收通过后才付款
  • 仅在授权范围内作业

获取报价