POST/v1/users/import

从 CSV 导入用户

users_import

在 csv 字段中发送 CSV 文件。第一行是表头。分隔符为 , 或 ;，根据表头自动识别。编码为 UTF-8（允许 BOM），最多 1000 个数据行。
列：email（必填；别名 e-mail、mail、почта）、name（display_name、имя）、role（admin、editor、verifier、viewer；别名 роль）、groups（группы；多个用户组之间用 | 或 ; 分隔，按普通用户组的键或名称指定）、profile（data_profile、профиль；数据权限档案的键）。未知的列会被跳过，并列在 ignored_columns 中。

使用 dry_run: true（默认）时，返回不做更改的预览：每一行的操作和错误。否则执行没有错误的行：
- invite：按文件中的角色、档案和姓名发送邀请。配置了邮件时会发送电子邮件，链接在响应中返回。
- exists：使用此电子邮件地址的用户已存在。该用户会被加入文件中的用户组；角色和档案不变。
- pending：发往此地址的邀请正在等待接受。文件中的用户组会添加到该邀请中。

有错误的行会被跳过。受邀用户在接受邀请时加入其用户组。create_groups 会创建缺失的普通用户组；不使用它时，未知的用户组视为该行的错误。套餐的用户限额和订阅席位会针对所有新邀请一次性检查：不够时什么都不执行（402）。手动邀请的限制（50 个待接受）不适用于导入。需要权限 ORG_MANAGE_USERS。会将 users.import 事件写入审计日志，并为每个邀请写入 invitation.create。

身份验证

在 Authorization 请求头中传入 API 密钥：Authorization: Bearer <密钥>。

请求头参数

Idempotency-Keystring
写操作安全重试所用的键：1 到 255 个可打印 ASCII 字符；建议每个逻辑操作使用一个 UUID v4。24 小时内使用同一个键重试不会再次执行操作，而是返回已保存的响应（状态、响应头和正文），并附带 Idempotency-Replayed: true 头。同一个键配合不同的方法、路径、Content-Type 或正文时返回 409 api.idempotency_mismatch；第一个请求仍在执行时返回 409 api.idempotency_in_progress，并附带 Retry-After: 1。收到 5xx 或 429 响应后，该键被释放，重试会再次执行操作。键的作用范围是组织和调用方（API 密钥、用户或自定义数据源密钥）。
length ≥ 1, length ≤ 255

请求体

application/json

对象：UsersImportRequest

csvstring必填
UTF-8 编码的 CSV 文件内容。
length ≥ 1, length ≤ 2000000
dry_runboolean
仅预览（默认）。false 执行没有错误的行。
默认值：true
default_rolestring
没有 role 列或该单元格为空的行所使用的角色。
默认值："viewer"
default_profilestring | null
没有档案的行所使用的数据权限档案。为空时使用组织的默认档案（管理员获得完全访问权限）。
create_groupsboolean
创建缺失的普通用户组。不设置此标志时，未知用户组视为该行出错。
默认值：false
ttl_daysinteger
邀请的有效天数。
默认值：7≥ 1, ≤ 30

响应

200导入的预览或结果，按行列出

响应头

RateLimit-Policy
当前生效的限制，格式遵循 IETF 草案 draft-ietf-httpapi-ratelimit-headers：以逗号分隔的项 "<name>";q=<quota>;w=<window in seconds>。key 是 API 密钥的请求速率（配额即突发量，时间窗口是配额完全恢复所需的时间；会话为 user，无凭据时为 ip）；minute、day 和 month 是组织按 UTC 计算的自然分钟、自然日和自然月的配额。
RateLimit
RateLimit-Policy 中每项限制的剩余量："<name>";r=<remaining>;t=<seconds until reset>。
X-RateLimit-Limit
RateLimit-Policy 中最严格一项（剩余请求数最少的一项）的限额。
X-RateLimit-Remaining
最严格限制下的剩余请求数。
X-RateLimit-Reset
距最严格限制重置的秒数。
Idempotency-Replayed
为 true 时表示该响应是按此 Idempotency-Key 从已保存的响应重放的：操作没有再次执行。

application/json

对象：UsersImportResult

dry_runboolean必填
totalinteger必填
文件中的数据行数。
countsUsersImportCounts必填
delimiterstring必填
从表头识别出的分隔符。
columnsarray of string必填
已识别的列，采用规范形式（email、name、role、groups、profile）。
ignored_columnsarray of string必填
created_groupsarray of string必填
执行过程中创建的用户组。
limitUsersImportLimit必填
rowsarray of UsersImportRow必填

400请求无效：参数值或对象状态不允许执行该操作（`detail` 为消息）。

响应头

RateLimit-Policy
当前生效的限制，格式遵循 IETF 草案 draft-ietf-httpapi-ratelimit-headers：以逗号分隔的项 "<name>";q=<quota>;w=<window in seconds>。key 是 API 密钥的请求速率（配额即突发量，时间窗口是配额完全恢复所需的时间；会话为 user，无凭据时为 ip）；minute、day 和 month 是组织按 UTC 计算的自然分钟、自然日和自然月的配额。
RateLimit
RateLimit-Policy 中每项限制的剩余量："<name>";r=<remaining>;t=<seconds until reset>。
X-RateLimit-Limit
RateLimit-Policy 中最严格一项（剩余请求数最少的一项）的限额。
X-RateLimit-Remaining
最严格限制下的剩余请求数。
X-RateLimit-Reset
距最严格限制重置的秒数。

application/json

对象：Error

401未发送凭据（既没有会话 Cookie，也没有 API 密钥），或未找到该密钥。

响应头

RateLimit-Policy
当前生效的限制，格式遵循 IETF 草案 draft-ietf-httpapi-ratelimit-headers：以逗号分隔的项 "<name>";q=<quota>;w=<window in seconds>。key 是 API 密钥的请求速率（配额即突发量，时间窗口是配额完全恢复所需的时间；会话为 user，无凭据时为 ip）；minute、day 和 month 是组织按 UTC 计算的自然分钟、自然日和自然月的配额。
RateLimit
RateLimit-Policy 中每项限制的剩余量："<name>";r=<remaining>;t=<seconds until reset>。
X-RateLimit-Limit
RateLimit-Policy 中最严格一项（剩余请求数最少的一项）的限额。
X-RateLimit-Remaining
最严格限制下的剩余请求数。
X-RateLimit-Reset
距最严格限制重置的秒数。

application/json

对象：Error

402组织已达到套餐限额（卡片、存储空间或用户）。`error.details` 中包含 `kind`、`limit` 和 `used`。

响应头

RateLimit-Policy
当前生效的限制，格式遵循 IETF 草案 draft-ietf-httpapi-ratelimit-headers：以逗号分隔的项 "<name>";q=<quota>;w=<window in seconds>。key 是 API 密钥的请求速率（配额即突发量，时间窗口是配额完全恢复所需的时间；会话为 user，无凭据时为 ip）；minute、day 和 month 是组织按 UTC 计算的自然分钟、自然日和自然月的配额。
RateLimit
RateLimit-Policy 中每项限制的剩余量："<name>";r=<remaining>;t=<seconds until reset>。
X-RateLimit-Limit
RateLimit-Policy 中最严格一项（剩余请求数最少的一项）的限额。
X-RateLimit-Remaining
最严格限制下的剩余请求数。
X-RateLimit-Reset
距最严格限制重置的秒数。

application/json

对象：Error

403不允许执行该操作：角色权限不足、无权访问合集或卡片、请求在“View as”模式下执行，或组织已被暂停或删除（`detail` 为对象，包含 `code: org_suspended | org_deleted`）。

响应头

RateLimit-Policy
当前生效的限制，格式遵循 IETF 草案 draft-ietf-httpapi-ratelimit-headers：以逗号分隔的项 "<name>";q=<quota>;w=<window in seconds>。key 是 API 密钥的请求速率（配额即突发量，时间窗口是配额完全恢复所需的时间；会话为 user，无凭据时为 ip）；minute、day 和 month 是组织按 UTC 计算的自然分钟、自然日和自然月的配额。
RateLimit
RateLimit-Policy 中每项限制的剩余量："<name>";r=<remaining>;t=<seconds until reset>。
X-RateLimit-Limit
RateLimit-Policy 中最严格一项（剩余请求数最少的一项）的限额。
X-RateLimit-Remaining
最严格限制下的剩余请求数。
X-RateLimit-Reset
距最严格限制重置的秒数。

application/json

对象：Error

413请求体超过允许的大小。

响应头

RateLimit-Policy
当前生效的限制，格式遵循 IETF 草案 draft-ietf-httpapi-ratelimit-headers：以逗号分隔的项 "<name>";q=<quota>;w=<window in seconds>。key 是 API 密钥的请求速率（配额即突发量，时间窗口是配额完全恢复所需的时间；会话为 user，无凭据时为 ip）；minute、day 和 month 是组织按 UTC 计算的自然分钟、自然日和自然月的配额。
RateLimit
RateLimit-Policy 中每项限制的剩余量："<name>";r=<remaining>;t=<seconds until reset>。
X-RateLimit-Limit
RateLimit-Policy 中最严格一项（剩余请求数最少的一项）的限额。
X-RateLimit-Remaining
最严格限制下的剩余请求数。
X-RateLimit-Reset
距最严格限制重置的秒数。

application/json

对象：Error

422校验错误：请求体或参数不符合定义的结构（`detail` 为校验错误列表），或参数值超出范围（`detail` 为消息）。

响应头

RateLimit-Policy
当前生效的限制，格式遵循 IETF 草案 draft-ietf-httpapi-ratelimit-headers：以逗号分隔的项 "<name>";q=<quota>;w=<window in seconds>。key 是 API 密钥的请求速率（配额即突发量，时间窗口是配额完全恢复所需的时间；会话为 user，无凭据时为 ip）；minute、day 和 month 是组织按 UTC 计算的自然分钟、自然日和自然月的配额。
RateLimit
RateLimit-Policy 中每项限制的剩余量："<name>";r=<remaining>;t=<seconds until reset>。
X-RateLimit-Limit
RateLimit-Policy 中最严格一项（剩余请求数最少的一项）的限额。
X-RateLimit-Remaining
最严格限制下的剩余请求数。
X-RateLimit-Reset
距最严格限制重置的秒数。

application/json

对象：Error

429请求过多（`api.rate_limited`）、组织每分钟、每天或每月的配额已用完（`api.quota_exceeded`；`error.details` 中包含 `quota`、`limit` 和 `reset_at`）、已达到组织的限额，或回答服务繁忙（`answers.engine_busy`）。请等待 `Retry-After` 头中给出的时间。

响应头

Retry-After
重试请求前需要等待的秒数。
RateLimit-Policy
当前生效的限制，格式遵循 IETF 草案 draft-ietf-httpapi-ratelimit-headers：以逗号分隔的项 "<name>";q=<quota>;w=<window in seconds>。key 是 API 密钥的请求速率（配额即突发量，时间窗口是配额完全恢复所需的时间；会话为 user，无凭据时为 ip）；minute、day 和 month 是组织按 UTC 计算的自然分钟、自然日和自然月的配额。
RateLimit
RateLimit-Policy 中每项限制的剩余量："<name>";r=<remaining>;t=<seconds until reset>。
X-RateLimit-Limit
RateLimit-Policy 中最严格一项（剩余请求数最少的一项）的限额。
X-RateLimit-Remaining
最严格限制下的剩余请求数。
X-RateLimit-Reset
距最严格限制重置的秒数。

application/json

对象：Error

错误码

除所有请求通用的错误码外，此接口还可能在 error.code 中返回以下错误码。

安全重试

每个 POST 和 PATCH 请求都传入 Idempotency-Key 头（例如一个 UUID）。24 小时内用同一个键重试时，返回已保存的响应，不会再次执行请求。

速率限制

响应带有 RateLimit 和 RateLimit-Policy 头，以及旧版的 X-RateLimit-Limit、X-RateLimit-Remaining 和 X-RateLimit-Reset 头。429 响应带有以秒为单位的 Retry-After：等待后重试。

← users · API 参考

curl -X POST 'https://api.sursa.com/v1/users/import' \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"csv":"string"}' \
  -H "Authorization: Bearer $SURSA_API_KEY"

在线调试

API 密钥

密钥只保存在此标签页的内存中，只会发送到 https://api.sursa.com。

请求会作用于您组织的真实数据。

Idempotency-Key header

Idempotency-Key

留空时，每个请求都会生成一个新键。

请求体（JSON）