GET/v1/cards-by-external-id/{external_id}

按外部 ID 获取卡片

get_card_by_external_id

按集成方的 external_id 定位卡片，返回的卡片和访问检查与 GET /v1/cards/{card_id} 相同。组织中没有此 external_id 的卡片，或调用方看不到该卡片时，请求返回 404 cards.not_found。

身份验证

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

路径参数

external_idstring必填
卡片的 external_id：长度为 1–512 个字符的字符串，在组织内唯一。
length ≥ 1, length ≤ 512

查询参数

expand[]array of string
要在响应中包含的关联对象（自 1.62.0 起）：操作的 x-expandable 列表中的路径。该参数最多可重复 10 次。路径最多有 2 段，用点分隔（collection.default_owner）。在列表中，路径以 data. 开头，作用于页面中的每一项（expand[]=data.owner）。展开的对象放入该项的 expanded 对象中，ID 字段保持不变。按其自身读取操作的检查，调用方无权查看的对象展开为 null。路径未知、超过 10 个路径或路径超过 2 段时，返回 400 api.expand_invalid。
items ≤ 10

请求头参数

X-View-Asstring
仅适用于具有 admin 角色的 API 密钥。以数据权限档案 <profile>[:viewer|verifier|editor] 的身份发出请求，例如 employee:viewer。部署密钥不能使用此头（403）。

Cookie 参数

kb_view_asstring
会话的“View as”模式 Cookie。POST /auth/view-as 设置该 Cookie，DELETE /auth/view-as 将其清除。

响应

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
距最严格限制重置的秒数。

application/json

对象：Card

expandedCardExpanded
permissionsObjectPermissionList
accessstring
可选值: wholepartial
access_contactstring
申请访问权限时的联系人（仅当 access=partial 时）。
aclobject
字段
- verifyboolean必填
- writeboolean必填
categorystring必填
category_confidencenumber | null必填
category_lockedboolean必填
category_reviewboolean必填
category_sourceCategorySource | null必填
collectionstring必填
collection_idinteger必填
collection_titlestring
commentsarray of CardComment
content_jsonContentJSON | null
最新发布版本的编辑器内容。该字段可能不存在；此时请从草稿获取编辑器内容（带 card_id 调用 POST /v1/drafts）。
editing_lockEditingLock | null
当前的编辑锁。该字段可能不存在；此时编辑器可从 POST /v1/cards/{card_id}/lock 返回的 409 cards.locked 得知谁持有锁。
created_atstring (date-time)必填
days_since_verifiedinteger必填
errorstring | null必填
eventsarray of CardEvent
feedback_neginteger必填
feedback_posinteger必填
foldersarray of CardFolderRef
仅在卡片列表中返回：包含该卡片的文件夹（用户可见的那些），以及它们从合集根目录起的路径。空列表表示卡片不在任何文件夹中。
has_tablesboolean
仅在卡片列表中返回。
hidden_partsboolean
idstring必填
jobJob | null
kindCardKind必填
org_idinteger必填
owner_activeboolean | null
owner_idinteger | null必填
owner_namestring | null必填
pagesinteger | null必填
parserstring | null必填
以中性代码表示的文档解析器：document（完整结构：页面、标题、表格、扫描页）、pdf（PDF 文本层）、docx、xlsx、csv、markdown、html、text。该列表可能扩充。
partsarray of CardPart必填
sensitiveboolean必填
sha256string | null必填
sizeinteger必填
snoozed_atstring (date-time) | null
snoozed_byinteger | null
snoozed_untilstring | null
source_changedboolean必填
source_pathstring | null必填
source_urlstring | null必填
statusstring必填
可选值: processingreadyerrorarchived
tablesarray of CardTable
tagsarray of string必填
titlestring必填
trustnumber必填
trust_if_verifiednumber
trust_partsTrustParts必填
updated_atstring (date-time)必填
verificationVerification必填
verified_atstring (date-time) | null必填
verified_byinteger | null必填
verified_by_namestring | null
verifier_idsarray of integer必填
verifiersarray of object
字段
- activeboolean必填
- idinteger必填
- namestring必填
verify_interval_daysinteger必填
versioninteger必填
versionsarray of CardVersion
source_archiveArchiveSource
created_byinteger | null
manual_optionsobject
手动解析设置（预览）。
doc_kindDocKind | null
文档类型。无法确定类型时为 null（例如，在引入文档类型之前索引的卡片）。
doc_kind_confidencenumber | null
对文档类型的置信度，取值 0 到 1。
doc_kind_sourcestring | null
确定类型的方式：规则（rules）、用户（manual）或自动分类。该列表可能扩充：将未知值视为自动分类。
可选值: rulesmanualnull
invoiceDocInvoiceExtraction | null
发票、贷项通知单或收据的字段（仅限这些类型，且只在卡片中返回，不在列表中返回）。如果您无权访问整个文档，则为 null，因为这些字段是从整个文档中提取的。
warningsarray of ReviewWarning
文档解析警告（ReviewWarning；只在卡片中返回，不在列表中返回）。
enrichmentCardEnrichmentStatus | null
信息补全状态（只在卡片中返回，不在列表中返回）。文档类型、发票字段和财务记录在索引后于后台添加，之后可能重新计算；准备就绪后显示在卡片中。null 表示没有可用的状态（卡片在索引时未进行后台信息补全）。
external_idstring | null
卡片在集成方系统中的 ID。在组织内不来自数据源的卡片之间唯一；null 表示未设置。/v1/cards-by-external-id/{external_id} 按该 ID 读取和替换卡片。
length ≤ 512
metadataMetadata

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

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

404对象不存在或您无权访问。对于访问受限的对象，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

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 中返回以下错误码。

速率限制

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

← cards · API 参考

curl 'https://api.sursa.com/v1/cards-by-external-id/EXTERNAL_ID' \
  -H "Authorization: Bearer $SURSA_API_KEY"

在线调试

API 密钥

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

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

X-View-As header

external_id path *

expand[] query