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

GET/v1/cards

Liệt kê thẻ

list_cards

Trả về thẻ theo bộ lọc, sắp xếp và phân trang. Với preview=1 (cho chế độ xem dạng ô), mỗi thẻ còn có preview (200 ký tự đầu tiên của văn bản) và preview_tables (các trang tính kèm số dòng), trong phạm vi hồ sơ dữ liệu của bạn.

Xác thực

Gửi khóa API trong header Authorization: Authorization: Bearer <khóa>.

Tham số truy vấn

  • collectionstring | null
  • folderstring | null

    <folder ID> trả về các thẻ của thư mục và mọi thư mục con của nó. none trả về các thẻ của bộ sưu tập không nằm trong thư mục nào và cần có collection (nếu không, trả về 400 cards.invalid_folder_filter). Nếu thư mục không tồn tại hoặc không hiển thị với bạn, yêu cầu trả về 404 folders.not_found.

    length ≤ 64

  • statusstring | null

    Giá trị cho phép: processingreadyerrorarchivedall

  • ownerstring | null

    me, none hoặc ID người dùng.

  • owner_idinteger | null
  • verificationstring | null

    Giá trị cho phép: verifiedneeds_verificationstale

  • kindCardKind
  • typestring | null

    table trả về các thẻ có bảng dữ kiện, text trả về các thẻ không có bảng dữ kiện.

    Giá trị cho phép: tabletext

  • tagsstring | null

    Các nhãn phân tách bằng dấu phẩy (thẻ phải có tất cả các nhãn đó).

  • idsstring | null

    Các ID thẻ phân tách bằng dấu phẩy.

  • searchstring | null
  • categorystring | null
  • sensitiveboolean | null
  • sortCardSort

    Mặc định: "created_at"

  • orderstring

    Giá trị cho phép: ascdesc

    Mặc định: "desc"

  • limitinteger

    Mặc định: 200

  • offsetinteger

    Mặc định: 0

  • previewboolean

    true thêm preview (200 ký tự đầu tiên) và preview_tables cho chế độ xem dạng ô.

    Mặc định: false

  • updated_sincestring (date-time)

    Chỉ các thẻ có updated_at bằng hoặc sau thời điểm này (RFC 3339 có độ lệch múi giờ), dùng để đồng bộ. Khi không chỉ định rõ sort và order, danh sách được sắp xếp theo updated_at tăng dần, sau đó theo id. Thẻ đã xóa không có trong danh sách: việc xóa được báo bằng sự kiện.

  • metadatamap of string

    Lọc theo metadata: metadata[<key>]=<value> so khớp chính xác. Tối đa 3 điều kiện, và mọi điều kiện đều phải khớp (?metadata[team]=support&metadata[crm_id]=A-1042). Quá 3 điều kiện hoặc khóa không hợp lệ trả về 400 api.metadata_invalid.

  • collection_idinteger

    Bộ sưu tập theo ID. Khi collection cũng được truyền, collection_id được ưu tiên. Bộ sưu tập không tồn tại trong tổ chức hoặc không hiển thị với bạn trả về 404 collections.not_found.

  • external_idstring

    Chỉ thẻ có external_id này.

  • cursorstring

    Con trỏ của trang tiếp theo, lấy từ X-Next-Cursor hoặc next_cursor của phản hồi trước với cùng bộ lọc; con trỏ mang theo kích thước trang. Dùng cùng với offset: 422 validation.failed; con trỏ của danh sách khác, của bộ lọc khác hoặc sai định dạng: 400 api.cursor_invalid.

    length ≤ 512

  • 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

  • Link

    Địa chỉ của trang tiếp theo, <…>; rel="next". Không có header nghĩa là đây là trang cuối.

  • X-Next-Cursor

    Con trỏ của trang tiếp theo cho tham số cursor. Không có header nghĩa là đây là trang cuố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: CardList

array of Card
  • expandedCardExpanded
  • permissionsObjectPermissionList
  • 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