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

POST/v1/cards/{card_id}/verify

Xác nhận thông tin của thẻ vẫn còn cập nhật

verify_card

Xác thực

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

Tham số đường dẫn

  • card_idstringbắt buộc

Tham số header

  • Idempotency-Keystring

    Khóa để thử lại an toàn một thao tác ghi: 1 đến 255 ký tự ASCII in được; nên dùng một UUID v4 cho mỗi thao tác logic. Lần thử lại với cùng khóa trong vòng 24 giờ không chạy lại thao tác: dịch vụ trả về phản hồi đã lưu (trạng thái, header và phần thân) kèm header Idempotency-Replayed: true. Cùng khóa nhưng khác phương thức, đường dẫn, Content-Type hoặc phần thân trả về 409 api.idempotency_mismatch; khi yêu cầu đầu tiên vẫn đang chạy, trả về 409 api.idempotency_in_progress kèm Retry-After: 1. Sau phản hồi 5xx hoặc 429, khóa được giải phóng và lần thử lại sẽ chạy lại thao tác. Khóa có phạm vi theo tổ chức và bên gọi (khóa API, người dùng hoặc khóa nguồn tùy chỉnh).

    length ≥ 1, length ≤ 255

  • 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 thân yêu cầu

application/json

Đối tượng: VerifyRequest

  • notestring | null

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.

  • Idempotency-Replayed

    true nghĩa là phản hồi được phát lại từ phản hồi đã lưu cho Idempotency-Key này: thao tác không chạy lại.

application/json

Đối tượng: 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.

Thử lại an toàn

Gửi header Idempotency-Key (ví dụ một UUID) với mỗi yêu cầu POST và PATCH. Một lần thử lại với cùng khóa trong vòng 24 giờ trả về phản hồi đã lưu thay vì thực hiện lạ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