GET/v1/cards-by-external-id/{external_id}
Lấy thẻ theo ID bên ngoài
get_card_by_external_id
Trả về cùng thẻ đó với cùng các bước kiểm tra quyền truy cập như GET /v1/cards/{card_id}, nhưng được xác định bằng external_id của bên tích hợp. Nếu tổ chức không có thẻ với external_id này, hoặc bên gọi không nhìn thấy thẻ, yêu cầu trả về 404 cards.not_found.
Xác thực
Gửi khóa API trong header Authorization: Authorization: Bearer <khóa>.
Tham số đường dẫn
external_idstringbắt buộcexternal_idcủa thẻ: chuỗi 1–512 ký tự, duy nhất trong tổ chức.length ≥ 1, length ≤ 512
Tham số truy vấn
expand[]array of stringCác đối tượng liên quan cần đưa vào phản hồi (từ 1.62.0): một đường dẫn trong danh sách
x-expandablecủa thao tác. Lặp lại tham số tối đa 10 lần. Một đường dẫn gồm tối đa 2 thành phần, phân tách bằng dấu chấm (collection.default_owner). Trong danh sách, đường dẫn bắt đầu bằngdata.và áp dụng cho mọi phần tử của trang (expand[]=data.owner). Đối tượng được mở rộng nằm trong đối tượngexpandedcủa phần tử, và trường ID vẫn giữ nguyên. Đối tượng mà bên gọi không được xem theo các bước kiểm tra của thao tác đọc riêng của nó được mở rộng thànhnull. Đường dẫn không xác định, hơn 10 đường dẫn hoặc đường dẫn gồm hơn 2 thành phần trả về400 api.expand_invalid.items ≤ 10
Tham số header
X-View-AsstringChỉ dành cho khóa API có vai trò
admin. Thực hiện yêu cầu với tư cách hồ sơ dữ liệu<profile>[:viewer|verifier|editor], ví dụemployee:viewer. Khóa cài đặt không thể dùng header này (403).
Tham số cookie
kb_view_asstringCookie của chế độ “View as” cho một phiên.
POST /auth/view-asđặt cookie này, cònDELETE /auth/view-asxóa nó.
Phản hồi
200Phản hồi thành công
Header phản hồi
RateLimit-PolicyCác giới hạn đang áp dụng, theo định dạng của bản dự thảo IETF
draft-ietf-httpapi-ratelimit-headers: các mục phân tách bằng dấu phẩy"<name>";q=<quota>;w=<window in seconds>.keylà tốc độ yêu cầu của khóa API (hạn mức là đợt tăng đột biến, khung thời gian là thời gian để hạn mức hồi lại hoàn toàn; với phiên làuser, khi không có thông tin xác thực làip);minute,dayvàmonthlà hạn mức của tổ chức cho phút, ngày và tháng theo lịch, tính theo UTC.RateLimitPhần còn lại của mỗi giới hạn trong
RateLimit-Policy:"<name>";r=<remaining>;t=<seconds until reset>.X-RateLimit-LimitGiới hạn của mục chặt nhất trong
RateLimit-Policy(mục còn ít yêu cầu nhất).X-RateLimit-RemainingSố yêu cầu còn lại theo giới hạn chặt nhất.
X-RateLimit-ResetSố giây cho đến khi giới hạn chặt nhất được đặt lại.
application/json
expandedCardExpandedpermissionsObjectPermissionListaccessstringGiá trị cho phép:
wholepartialaccess_contactstringNgười cần liên hệ để xin quyền truy cập (chỉ khi
access=partial).aclobjectTrường
verifybooleanbắt buộcwritebooleanbắt buộc
categorystringbắt buộccategory_confidencenumber | nullbắt buộccategory_lockedbooleanbắt buộccategory_reviewbooleanbắt buộccollectionstringbắt buộccollection_idintegerbắt buộccollection_titlestringcommentsarray of CardCommentcontent_jsonContentJSON | nullNội dung trình soạn thảo của phiên bản đã xuất bản mới nhất. Trường có thể vắng mặt; khi đó, hãy lấy nội dung trình soạn thảo từ bản nháp (
POST /v1/draftsvớicard_id).editing_lockEditingLock | nullKhóa chỉnh sửa đang hiệu lực. Trường có thể vắng mặt; khi đó, trình soạn thảo biết ai đang giữ khóa chỉnh sửa từ
409 cards.lockedcủaPOST /v1/cards/{card_id}/lock.created_atstring (date-time)bắt buộcdays_since_verifiedintegerbắt buộcerrorstring | nullbắt buộceventsarray of CardEventfeedback_negintegerbắt buộcfeedback_posintegerbắt buộcfoldersarray of CardFolderRefChỉ trong danh sách thẻ: các thư mục chứa thẻ (những thư mục người dùng nhìn thấy), kèm đường dẫn từ thư mục gốc của bộ sưu tập. Danh sách trống nghĩa là thẻ không nằm trong thư mục nào.
has_tablesbooleanChỉ trong danh sách thẻ.
hidden_partsbooleanidstringbắt buộcjobJob | nullorg_idintegerbắt buộcowner_activeboolean | nullowner_idinteger | nullbắt buộcowner_namestring | nullbắt buộcpagesinteger | nullbắt buộcparserstring | nullbắt buộcTrình đọc tài liệu dưới dạng mã trung tính:
document(cấu trúc đầy đủ: trang, tiêu đề, bảng, trang được quét),pdf(lớp văn bản của PDF),docx,xlsx,csv,markdown,html,text. Danh sách có thể mở rộng.sensitivebooleanbắt buộcsha256string | nullbắt buộcsizeintegerbắt buộcsnoozed_atstring (date-time) | nullsnoozed_byinteger | nullsnoozed_untilstring | nullsource_changedbooleanbắt buộcsource_pathstring | nullbắt buộcsource_urlstring | nullbắt buộcstatusstringbắt buộcGiá trị cho phép:
processingreadyerrorarchivedtablesarray of CardTabletagsarray of stringbắt buộctitlestringbắt buộctrustnumberbắt buộctrust_if_verifiednumberupdated_atstring (date-time)bắt buộcverified_atstring (date-time) | nullbắt buộcverified_byinteger | nullbắt buộcverified_by_namestring | nullverifier_idsarray of integerbắt buộcverifiersarray of objectTrường
activebooleanbắt buộcidintegerbắt buộcnamestringbắt buộc
verify_interval_daysintegerbắt buộcversionintegerbắt buộcversionsarray of CardVersionsource_archiveArchiveSourcecreated_byinteger | nullmanual_optionsobjectCài đặt đọc tài liệu thủ công (xem trước).
doc_kindDocKind | nullLoại tài liệu.
nullnếu chưa xác định được loại (ví dụ, với thẻ được lập chỉ mục trước khi có loại tài liệu).doc_kind_confidencenumber | nullĐộ tin cậy của loại tài liệu, từ 0 đến 1.
doc_kind_sourcestring | nullĐiều gì đã xác định loại: quy tắc (
rules), người dùng (manual) hoặc phân loại tự động. Danh sách có thể mở rộng: hãy coi giá trị không xác định là phân loại tự động.Giá trị cho phép:
rulesmanualnullinvoiceDocInvoiceExtraction | nullCác trường của hóa đơn, giấy báo có hoặc biên lai (chỉ với các loại này, và chỉ trong thẻ, không có trong danh sách).
nullnếu bạn không có quyền truy cập toàn bộ tài liệu, vì các trường được trích xuất từ toàn bộ tài liệu.warningsarray of ReviewWarningCảnh báo khi đọc tài liệu (
ReviewWarning; chỉ trong thẻ, không có trong danh sách).enrichmentCardEnrichmentStatus | nullTrạng thái làm giàu dữ liệu (chỉ trong thẻ, không có trong danh sách). Loại tài liệu, các trường hóa đơn và bản ghi tài chính được bổ sung ở chế độ nền sau khi lập chỉ mục và có thể được tính lại sau; chúng xuất hiện trong thẻ khi đã sẵn sàng.
nullnghĩa là không có trạng thái (thẻ được lập chỉ mục mà không làm giàu dữ liệu ở chế độ nền).external_idstring | nullID của thẻ trong hệ thống của bên tích hợp. Giá trị là duy nhất trong tổ chức giữa các thẻ không đến từ nguồn;
nullnghĩa là chưa được đặt./v1/cards-by-external-id/{external_id}đọc và thay thế thẻ theo giá trị này.length ≤ 512
metadataMetadata
400Yêu cầu không hợp lệ: giá trị tham số hoặc trạng thái của đối tượng không cho phép thực hiện hành động (`detail` là thông báo).
Header phản hồi
RateLimit-PolicyCác giới hạn đang áp dụng, theo định dạng của bản dự thảo IETF
draft-ietf-httpapi-ratelimit-headers: các mục phân tách bằng dấu phẩy"<name>";q=<quota>;w=<window in seconds>.keylà tốc độ yêu cầu của khóa API (hạn mức là đợt tăng đột biến, khung thời gian là thời gian để hạn mức hồi lại hoàn toàn; với phiên làuser, khi không có thông tin xác thực làip);minute,dayvàmonthlà hạn mức của tổ chức cho phút, ngày và tháng theo lịch, tính theo UTC.RateLimitPhần còn lại của mỗi giới hạn trong
RateLimit-Policy:"<name>";r=<remaining>;t=<seconds until reset>.X-RateLimit-LimitGiới hạn của mục chặt nhất trong
RateLimit-Policy(mục còn ít yêu cầu nhất).X-RateLimit-RemainingSố yêu cầu còn lại theo giới hạn chặt nhất.
X-RateLimit-ResetSố giây cho đến khi giới hạn chặt nhất được đặt lại.
application/json
401Không có thông tin xác thực nào được gửi (không có cookie phiên lẫn khóa API), hoặc không tìm thấy khóa.
Header phản hồi
RateLimit-PolicyCác giới hạn đang áp dụng, theo định dạng của bản dự thảo IETF
draft-ietf-httpapi-ratelimit-headers: các mục phân tách bằng dấu phẩy"<name>";q=<quota>;w=<window in seconds>.keylà tốc độ yêu cầu của khóa API (hạn mức là đợt tăng đột biến, khung thời gian là thời gian để hạn mức hồi lại hoàn toàn; với phiên làuser, khi không có thông tin xác thực làip);minute,dayvàmonthlà hạn mức của tổ chức cho phút, ngày và tháng theo lịch, tính theo UTC.RateLimitPhần còn lại của mỗi giới hạn trong
RateLimit-Policy:"<name>";r=<remaining>;t=<seconds until reset>.X-RateLimit-LimitGiới hạn của mục chặt nhất trong
RateLimit-Policy(mục còn ít yêu cầu nhất).X-RateLimit-RemainingSố yêu cầu còn lại theo giới hạn chặt nhất.
X-RateLimit-ResetSố giây cho đến khi giới hạn chặt nhất được đặt lại.
application/json
403Hành động không được phép: vai trò không đủ quyền, không có quyền truy cập vào bộ sưu tập hoặc thẻ, yêu cầu chạy ở chế độ “View as”, hoặc tổ chức bị tạm ngưng hay đã bị xóa (`detail` là đối tượng có `code: org_suspended | org_deleted`).
Header phản hồi
RateLimit-PolicyCác giới hạn đang áp dụng, theo định dạng của bản dự thảo IETF
draft-ietf-httpapi-ratelimit-headers: các mục phân tách bằng dấu phẩy"<name>";q=<quota>;w=<window in seconds>.keylà tốc độ yêu cầu của khóa API (hạn mức là đợt tăng đột biến, khung thời gian là thời gian để hạn mức hồi lại hoàn toàn; với phiên làuser, khi không có thông tin xác thực làip);minute,dayvàmonthlà hạn mức của tổ chức cho phút, ngày và tháng theo lịch, tính theo UTC.RateLimitPhần còn lại của mỗi giới hạn trong
RateLimit-Policy:"<name>";r=<remaining>;t=<seconds until reset>.X-RateLimit-LimitGiới hạn của mục chặt nhất trong
RateLimit-Policy(mục còn ít yêu cầu nhất).X-RateLimit-RemainingSố yêu cầu còn lại theo giới hạn chặt nhất.
X-RateLimit-ResetSố giây cho đến khi giới hạn chặt nhất được đặt lại.
application/json
404Đối tượng không tồn tại hoặc bạn không có quyền truy cập. API không xác nhận sự tồn tại của đối tượng bị hạn chế quyền truy cập.
Header phản hồi
RateLimit-PolicyCác giới hạn đang áp dụng, theo định dạng của bản dự thảo IETF
draft-ietf-httpapi-ratelimit-headers: các mục phân tách bằng dấu phẩy"<name>";q=<quota>;w=<window in seconds>.keylà tốc độ yêu cầu của khóa API (hạn mức là đợt tăng đột biến, khung thời gian là thời gian để hạn mức hồi lại hoàn toàn; với phiên làuser, khi không có thông tin xác thực làip);minute,dayvàmonthlà hạn mức của tổ chức cho phút, ngày và tháng theo lịch, tính theo UTC.RateLimitPhần còn lại của mỗi giới hạn trong
RateLimit-Policy:"<name>";r=<remaining>;t=<seconds until reset>.X-RateLimit-LimitGiới hạn của mục chặt nhất trong
RateLimit-Policy(mục còn ít yêu cầu nhất).X-RateLimit-RemainingSố yêu cầu còn lại theo giới hạn chặt nhất.
X-RateLimit-ResetSố giây cho đến khi giới hạn chặt nhất được đặt lại.
application/json
422Lỗi dữ liệu không hợp lệ: phần thân hoặc tham số không khớp với lược đồ (`detail` là danh sách lỗi dữ liệu không hợp lệ), hoặc giá trị tham số nằm ngoài phạm vi cho phép (`detail` là thông báo).
Header phản hồi
RateLimit-PolicyCác giới hạn đang áp dụng, theo định dạng của bản dự thảo IETF
draft-ietf-httpapi-ratelimit-headers: các mục phân tách bằng dấu phẩy"<name>";q=<quota>;w=<window in seconds>.keylà tốc độ yêu cầu của khóa API (hạn mức là đợt tăng đột biến, khung thời gian là thời gian để hạn mức hồi lại hoàn toàn; với phiên làuser, khi không có thông tin xác thực làip);minute,dayvàmonthlà hạn mức của tổ chức cho phút, ngày và tháng theo lịch, tính theo UTC.RateLimitPhần còn lại của mỗi giới hạn trong
RateLimit-Policy:"<name>";r=<remaining>;t=<seconds until reset>.X-RateLimit-LimitGiới hạn của mục chặt nhất trong
RateLimit-Policy(mục còn ít yêu cầu nhất).X-RateLimit-RemainingSố yêu cầu còn lại theo giới hạn chặt nhất.
X-RateLimit-ResetSố giây cho đến khi giới hạn chặt nhất được đặt lại.
application/json
429Quá nhiều yêu cầu (`api.rate_limited`), hạn mức của tổ chức theo phút, ngày hoặc tháng đã dùng hết (`api.quota_exceeded`; `error.details` chứa `quota`, `limit` và `reset_at`), tổ chức đã đạt giới hạn, hoặc dịch vụ trả lời đang bận (`answers.engine_busy`). Hãy chờ khoảng thời gian ghi trong header `Retry-After`.
Header phản hồi
Retry-AfterSố giây cần chờ trước khi thử lại yêu cầu.
RateLimit-PolicyCác giới hạn đang áp dụng, theo định dạng của bản dự thảo IETF
draft-ietf-httpapi-ratelimit-headers: các mục phân tách bằng dấu phẩy"<name>";q=<quota>;w=<window in seconds>.keylà tốc độ yêu cầu của khóa API (hạn mức là đợt tăng đột biến, khung thời gian là thời gian để hạn mức hồi lại hoàn toàn; với phiên làuser, khi không có thông tin xác thực làip);minute,dayvàmonthlà hạn mức của tổ chức cho phút, ngày và tháng theo lịch, tính theo UTC.RateLimitPhần còn lại của mỗi giới hạn trong
RateLimit-Policy:"<name>";r=<remaining>;t=<seconds until reset>.X-RateLimit-LimitGiới hạn của mục chặt nhất trong
RateLimit-Policy(mục còn ít yêu cầu nhất).X-RateLimit-RemainingSố yêu cầu còn lại theo giới hạn chặt nhất.
X-RateLimit-ResetSố giây cho đến khi giới hạn chặt nhất được đặt lại.
application/json
Mã lỗi
Các mã endpoint này có thể trả về trong error.code, ngoài các mã chung của mọi yêu cầu.
Giới hạn tốc độ
Phản hồi có các header RateLimit và RateLimit-Policy cùng các header cũ hơn X-RateLimit-Limit, X-RateLimit-Remaining và X-RateLimit-Reset. Phản hồi 429 có Retry-After tính bằng giây: hãy chờ rồi thử lại.