Chuyển tới nội dung
Sursa Developers

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ộc

    external_id củ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 string

    Cá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-expandable củ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ằng data. 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ượng expanded củ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ành null. Đườ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-Asstring

    Chỉ 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_asstring

    Cookie của chế độ “View as” cho một phiên. POST /auth/view-as đặt cookie này, còn DELETE /auth/view-as xóa nó.

Phản hồi

200Phản hồi thành công

Header phản hồi

  • RateLimit-Policy

    Cá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>. key là 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, day và month là hạn mức của tổ chức cho phút, ngày và tháng theo lịch, tính theo UTC.

  • RateLimit

    Phầ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-Limit

    Giớ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-Remaining

    Số yêu cầu còn lại theo giới hạn chặt nhất.

  • X-RateLimit-Reset

    Số giây cho đến khi giới hạn chặt nhất được đặt lại.

application/json

Đối tượng: Card

  • expandedCardExpanded
  • accessstring

    Giá trị cho phép: wholepartial

  • access_contactstring

    Người cần liên hệ để xin quyền truy cập (chỉ khi access=partial).

  • aclobject
    Trường
    • verifybooleanbắt buộc
    • writebooleanbắt buộc
  • categorystringbắt buộc
  • category_confidencenumber | nullbắt buộc
  • category_lockedbooleanbắt buộc
  • category_reviewbooleanbắt buộc
  • category_sourceCategorySource | nullbắt buộc
  • collectionstringbắt buộc
  • collection_idintegerbắt buộc
  • collection_titlestring
  • commentsarray of CardComment
  • content_jsonContentJSON | null

    Nộ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/drafts với card_id).

  • editing_lockEditingLock | null

    Khó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.locked của POST /v1/cards/{card_id}/lock.

  • created_atstring (date-time)bắt buộc
  • days_since_verifiedintegerbắt buộc
  • errorstring | nullbắt buộc
  • eventsarray of CardEvent
  • feedback_negintegerbắt buộc
  • feedback_posintegerbắt buộc
  • foldersarray of CardFolderRef

    Chỉ 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_tablesboolean

    Chỉ trong danh sách thẻ.

  • hidden_partsboolean
  • idstringbắt buộc
  • jobJob | null
  • kindCardKindbắt buộc
  • org_idintegerbắt buộc
  • owner_activeboolean | null
  • owner_idinteger | nullbắt buộc
  • owner_namestring | nullbắt buộc
  • pagesinteger | nullbắt buộc
  • parserstring | nullbắt buộc

    Trì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.

  • partsarray of CardPartbắt buộc
  • sensitivebooleanbắt buộc
  • sha256string | nullbắt buộc
  • sizeintegerbắt buộc
  • snoozed_atstring (date-time) | null
  • snoozed_byinteger | null
  • snoozed_untilstring | null
  • source_changedbooleanbắt buộc
  • source_pathstring | nullbắt buộc
  • source_urlstring | nullbắt buộc
  • statusstringbắt buộc

    Giá trị cho phép: processingreadyerrorarchived

  • tablesarray of CardTable
  • tagsarray of stringbắt buộc
  • titlestringbắt buộc
  • trustnumberbắt buộc
  • trust_if_verifiednumber
  • trust_partsTrustPartsbắt buộc
  • updated_atstring (date-time)bắt buộc
  • verificationVerificationbắt buộc
  • verified_atstring (date-time) | nullbắt buộc
  • verified_byinteger | nullbắt buộc
  • verified_by_namestring | null
  • verifier_idsarray of integerbắt buộc
  • verifiersarray of object
    Trường
    • activebooleanbắt buộc
    • idintegerbắt buộc
    • namestringbắt buộc
  • verify_interval_daysintegerbắt buộc
  • versionintegerbắt buộc
  • versionsarray of CardVersion
  • source_archiveArchiveSource
  • created_byinteger | null
  • manual_optionsobject

    Cài đặt đọc tài liệu thủ công (xem trước).

  • doc_kindDocKind | null

    Loại tài liệu. null nế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: rulesmanualnull

  • invoiceDocInvoiceExtraction | null

    Cá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). null nế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 ReviewWarning

    Cảnh báo khi đọc tài liệu (ReviewWarning; chỉ trong thẻ, không có trong danh sách).

  • enrichmentCardEnrichmentStatus | null

    Trạ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. null nghĩ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 | null

    ID 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; null nghĩ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-Policy

    Cá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>. key là 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, day và month là hạn mức của tổ chức cho phút, ngày và tháng theo lịch, tính theo UTC.

  • RateLimit

    Phầ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-Limit

    Giớ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-Remaining

    Số yêu cầu còn lại theo giới hạn chặt nhất.

  • X-RateLimit-Reset

    Số giây cho đến khi giới hạn chặt nhất được đặt lại.

application/json

Đối tượng: Error

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-Policy

    Cá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>. key là 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, day và month là hạn mức của tổ chức cho phút, ngày và tháng theo lịch, tính theo UTC.

  • RateLimit

    Phầ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-Limit

    Giớ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-Remaining

    Số yêu cầu còn lại theo giới hạn chặt nhất.

  • X-RateLimit-Reset

    Số giây cho đến khi giới hạn chặt nhất được đặt lại.

application/json

Đối tượng: Error

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-Policy

    Cá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>. key là 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, day và month là hạn mức của tổ chức cho phút, ngày và tháng theo lịch, tính theo UTC.

  • RateLimit

    Phầ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-Limit

    Giớ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-Remaining

    Số yêu cầu còn lại theo giới hạn chặt nhất.

  • X-RateLimit-Reset

    Số giây cho đến khi giới hạn chặt nhất được đặt lại.

application/json

Đối tượng: Error

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-Policy

    Cá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>. key là 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, day và month là hạn mức của tổ chức cho phút, ngày và tháng theo lịch, tính theo UTC.

  • RateLimit

    Phầ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-Limit

    Giớ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-Remaining

    Số yêu cầu còn lại theo giới hạn chặt nhất.

  • X-RateLimit-Reset

    Số giây cho đến khi giới hạn chặt nhất được đặt lại.

application/json

Đối tượng: Error

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-Policy

    Cá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>. key là 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, day và month là hạn mức của tổ chức cho phút, ngày và tháng theo lịch, tính theo UTC.

  • RateLimit

    Phầ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-Limit

    Giớ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-Remaining

    Số yêu cầu còn lại theo giới hạn chặt nhất.

  • X-RateLimit-Reset

    Số giây cho đến khi giới hạn chặt nhất được đặt lại.

application/json

Đối tượng: Error

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-After

    Số giây cần chờ trước khi thử lại yêu cầu.

  • RateLimit-Policy

    Cá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>. key là 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, day và month là hạn mức của tổ chức cho phút, ngày và tháng theo lịch, tính theo UTC.

  • RateLimit

    Phầ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-Limit

    Giớ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-Remaining

    Số yêu cầu còn lại theo giới hạn chặt nhất.

  • X-RateLimit-Reset

    Số giây cho đến khi giới hạn chặt nhất được đặt lại.

application/json

Đối tượng: Error

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.

← cards · Tài liệu tham chiếu API