UKG Pro 打卡与令牌数据 API

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 把它们变成可调用的开放数据。

应用截图

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 相似的应用

Workday — Workday 是一套云端人力资本管理平台，把人事、薪资、人才与劳动力规划放在同一系统，员工端可处理休假、工时卡与已发布排班。
ADP Mobile Solutions — ADP Mobile Solutions 是 ADP 的员工自助应用，用于查看工资单、上下班打卡、申请休假并在手机上处理人事信息。
Dayforce — Dayforce 是一套人力资本管理平台，把薪资、考勤、劳动力管理与员工自助放在同一系统，并按实时方式计算收入。
Paylocity — Paylocity 是面向中型市场的云端人力资本管理平台，覆盖薪资、人事以及员工自助门户，用于维护个人信息、福利与休假申请。
Paycom — Paycom 是运行在单一数据库上的薪资与人事系统，员工可自行录入数据，并通过 Beti 在发薪前核对工资。
SAP SuccessFactors — SAP SuccessFactors 是 SAP 的云端人力资本管理套件，把核心人事、人才管理与劳动力流程集中在一起，面向大型组织。
Oracle HCM Cloud — Oracle HCM Cloud 是甲骨文的云端人力资源平台，把企业内各个人事流程连在一起，涵盖人才管理与员工自助。
BambooHR — BambooHR 是面向中小企业的云端人力资源系统，把员工档案、休假申请、入职与薪资集中在一个平台。

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

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

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

获取报价

UKG Pro 打卡与令牌数据 API

应用截图

API 端点一览

导入离线考勤打卡

离线打卡信息与 FACP 开关

最近一次打卡与常用转移

移动能力与 CSRF 令牌

移动会话上下文

移动客户端启动

登录完成握手

签发 OAuth 访问令牌

AuthN 连接（OIDC 探测）

移动应用配置（Pro 网关）

认证 access_token（表单提交）

SSO 门户引导

移动登录设置

OIDC 会话（用户管理）

Talk 自定义登录

按令牌查询 Talk 用户

Talk 频道（spot）详情

数据类别

数据使用场景与案例

劳动力打卡对账

地理围栏出勤审计

按租户的 SSO 开通

主管收件箱路由

Talk 与 HRIS 身份关联

常见问题

与 UKG Pro 相似的应用

更多企业办公类应用

ADP Mobile Solutions

Box

CryptoRush: Crypto Simulator

Darwinbox

相关主题

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

UKG Pro 打卡与令牌数据 API

应用截图

API 端点一览

导入离线考勤打卡

离线打卡信息与 FACP 开关

最近一次打卡与常用转移

移动能力与 CSRF 令牌

移动会话上下文

移动客户端启动

登录完成握手

签发 OAuth 访问令牌

AuthN 连接（OIDC 探测）

移动应用配置（Pro 网关）

认证 access_token（表单提交）

SSO 门户引导

移动登录设置

OIDC 会话（用户管理）

Talk 自定义登录

按令牌查询 Talk 用户

Talk 频道（spot）详情

数据类别

数据使用场景与案例

劳动力打卡对账

地理围栏出勤审计

按租户的 SSO 开通

主管收件箱路由

Talk 与 HRIS 身份关联

常见问题

相关应用

与 UKG Pro 相似的应用

更多企业办公类应用

ADP Mobile Solutions

Box

CryptoRush: Crypto Simulator

Darwinbox

相关主题

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