---
title: "员工文件"
description: "把电子表格用作你的员工来源：下载示例文件，填写各列，上传它，再次上传以更新。这是不用 HRIS 运行 Pyn 的方式。"
sidebar:
  label: 概览
  order: 0
area: integrations
feature: employee-file
appPath: /settings/integrations/available
lastVerified: 2026-11-09
version: "2026-11-09"
audience: admin
related:
  - integrations
  - directory/employees
  - integrations/sync-and-matching
  - integrations/sample-data
intercom:
  - id: "16755797"
    title: How to Upload Employee Data Manually (Pyn 2)
    url: https://intercom.help/pyn/en/articles/16755797-how-to-upload-employee-data-manually-pyn-2
    note: replaces
  - id: "16755703"
    title: Connect  to your HRIS (Pyn 2)
    url: https://intercom.help/pyn/en/articles/16755703-connect-to-your-hris-pyn-2
    note: draws on
  - id: "6024080"
    title: How to upload employee data manually (Pyn 1)
    url: https://intercom.help/pyn/en/articles/6024080-how-to-upload-employee-data-manually-pyn-1
    note: "Pyn 1 article, kept for reference"
translation:
  source: integrations/employee-file/index.mdx
  sourceSha: 5e56e7dc24fde63c7998601735bb3a5093248c35
---

Employee File 把一份电子表格变成你的员工目录。每一行是一名员工，每一列是一个 Pyn 属性，每次上传都是你的完整名册：行按 `employeeId` 添加或更新，文件中缺少的人会被标记为从这个来源移除。Pyn 在保存任何内容之前先验证文件，并告诉你哪些行和列无法读取。

## 开始之前

- 你是管理员或所有者。
- 准备一份 CSV、XLS 或 XLSX，列标题是下面的属性名称。**Download Sample File** 提供一份包含每一列和五个示例行的 CSV。
- 每一行都需要 `employeeId` 和 `primaryEmail`。对于身处有多个时区的国家的员工，给出 `timeZone`；对美国、加拿大和澳大利亚，`postalCode` 加 `country` 就够了。否则该行会被拒绝。

![Installed 下的 Employee File 集成，上传面板已打开。](https://support.pyn.ai/media/integrations/employee-file/integrations-employee-file-tile.png)

## 连接

1. 在 Pyn 中，打开左侧导航中的 **Settings**，然后打开 **Integrations** 下的 **Available**。

2. 选择 **Employee File** 磁贴；它的封面上显示 **File Upload**。Pyn 创建该集成并打开它的面板："Upload a spreadsheet of your employees to get started. Use the sample file to see the expected columns." 如果无法创建该集成，标题为 **Add Employee File** 的对话框会显示 "We could not create the Employee File integration. Please try again or contact support."

3. 选择 **Download Sample File**，在它的基础上构建你的文件，保留标题行。

4. 选择 **Upload** 并选择你的文件。验证和保存期间，面板显示 **Uploading...**。

5. 成功后它显示 "Success! Uploaded n records. Head over to the Directory to see employees after processing completes. This can take a minute or two."

如果有行失败，面板会在 "There were n errors found in the uploaded file:" 下列出前五个，带有行号和问题，以及其余的数量，例如 `Unknown country: "Engalnd"`、`Could not determine timezone from country "United States". Add a postal code or choose a time zone.` 或 `Invalid birthday format. Expected MM-dd, dd/MM, yyyy-MM-dd or ISO8601 datetime.`。只要有任何一行失败，就什么都不会保存。修正列出的行，然后再次上传整个文件。

## 同步的内容

| 列 | 必填 | 说明 |
| --- | --- | --- |
| `employeeId` | 是 | 你为此人设定的稳定 id；上传按它匹配 |
| `primaryEmail` | 是 | 工作邮箱，也用于匹配 Slack 和 Google 账户 |
| `displayName`、`legalName`、`preferredName`、`jobTitle` | | |
| `personalEmail`、`secondaryEmail`、`avatarUri` | | 个人邮箱用于入职前沟通 |
| `status` | | `active`、`inactive` 或 `leave`；留空表示 `active` |
| `startDate`、`terminationDate`、`tenureDate` | | `yyyy-MM-dd` 或 `yyyy/MM/dd`，或 `.xls` 或 `.xlsx` 文件中的日期单元格；不存在的日期会被拒绝 |
| `birthday` | | `MM-dd`、`dd/MM`、`yyyy-MM-dd` 或 ISO 日期时间 |
| `country`、`postalCode`、`timeZone` | | 国家为名称或 ISO 代码；时区为 IANA 名称，例如 `Europe/London`。`.xls` 或 `.xlsx` 文件中的数字单元格按表格显示的样子读取，所以 `00000` 格式的邮政编码会保留前导零 |
| `businessUnit`、`department`、`division`、`location`、`team` | | 成为人口统计属性和群组 |
| `managerId`、`buddyId`、`hrbpId`、`mentorId` | | 相关人员的 `employeeId` |

没有计划刷新；文件在你上传时被读取。**Advanced** 标签页列出 **Fields in Employee File**，每列带有计数。你也可以用[员工](https://support.pyn.ai/zh-cn/directory/employees/)中的 **Add employee** 一次添加一个人，它会询问 **Full name\***、**Preferred name**、**Work email**、**Personal email**、**Start date\***、**Country\***、**Time zone\*** 和 **Manager**，并把此人添加为即将入职的员工。

## 测试

上传后一两分钟打开[员工](https://support.pyn.ai/zh-cn/directory/employees/)。在职的行出现在 **Active** 下，未来的入职日期在 **Upcoming** 下，`status` 为 `inactive` 的在 **Inactive** 下。打开一个人检查他们的经理关联。

## 重新连接或断开连接

没有凭据。要更改数据就上传一份新文件，并且始终上传所有人：之后的文件中缺少的行会被标记为从这个来源移除，此人显示为非在职；在之后的文件中再次列出他们，会按那一行的 `status` 把他们恢复。**Deactivate** 保留数据但忽略上传；**Activate** 重新启用上传。

## 故障排除

| 你看到的 | 含义 |
| --- | --- |
| "The uploaded file was empty" | 标题下方没有数据行，或者缺少标题行。 |
| 提到 `country` 或 `postalCode` 的行错误 | 国家名称无法识别，或者邮政编码无法解析为时区。添加 `timeZone`。 |
| 经理没有关联 | `managerId` 与任何一行的 `employeeId` 都不匹配。 |
| 某人出现两次 | 他们的 `employeeId` 和邮箱在两次上传之间全都变了，所以与之前的记录没有任何匹配。保持 id 和邮箱稳定。 |

## 相关

- [集成](https://support.pyn.ai/zh-cn/integrations/)，了解可以改用的 HRIS 集成。
- [员工](https://support.pyn.ai/zh-cn/directory/employees/)，检查上传的记录并添加单个人员。
- [同步频率与匹配](https://support.pyn.ai/zh-cn/integrations/sync-and-matching/)，了解 id 和邮箱如何匹配。
- [Sample Data](https://support.pyn.ai/zh-cn/integrations/sample-data/)，改用虚构名册试用 Pyn。
