ข้ามไปยังเนื้อหา
Sursa Developers

POST/v1/cards/{card_id}/verify

ยืนยันว่าการ์ดเป็นปัจจุบัน

verify_card

การยืนยันตัวตน

ส่งคีย์ API ในเฮดเดอร์ Authorization: Authorization: Bearer <คีย์>

พารามิเตอร์พาธ

  • card_idstringจำเป็น

พารามิเตอร์เฮดเดอร์

  • Idempotency-Keystring

    คีย์ป้องกันการทำซ้ำ (idempotency key) สำหรับลองคำขอเขียนข้อมูลใหม่อย่างปลอดภัย: อักขระ ASCII ที่พิมพ์ได้ 1 ถึง 255 ตัว แนะนำให้ใช้ UUID v4 หนึ่งค่าต่อการดำเนินการเชิงตรรกะหนึ่งรายการ การลองใหม่ด้วยคีย์เดิมภายใน 24 ชั่วโมงจะไม่ทำการดำเนินการซ้ำ แต่ส่งคืนการตอบกลับที่บันทึกไว้ (สถานะ เฮดเดอร์ และเนื้อหา) พร้อมเฮดเดอร์ Idempotency-Replayed: true คีย์เดิมที่ใช้กับเมธอด พาธ Content-Type หรือเนื้อหาที่ต่างออกไปจะส่งคืน 409 api.idempotency_mismatch ส่วนระหว่างที่คำขอแรกยังทำงานอยู่จะส่งคืน 409 api.idempotency_in_progress พร้อม Retry-After: 1 หลังการตอบกลับ 5xx หรือ 429 Sursa จะปล่อยคีย์ และการลองใหม่จะทำการดำเนินการอีกครั้ง คีย์มีขอบเขตตามองค์กรและผู้เรียก (คีย์ API ผู้ใช้ หรือคีย์แหล่งข้อมูล)

    length ≥ 1, length ≤ 255

  • X-View-Asstring

    สำหรับคีย์ API ที่มีบทบาท admin เท่านั้น ทำคำขอในนามโปรไฟล์ข้อมูล <profile>[:viewer|verifier|editor] เช่น employee:viewer คีย์การติดตั้งใช้เฮดเดอร์นี้ไม่ได้ (403)

พารามิเตอร์คุกกี้

  • kb_view_asstring

    คุกกี้ของโหมด “View as” สำหรับเซสชัน POST /auth/view-as ตั้งค่าคุกกี้นี้ และ DELETE /auth/view-as ล้างค่า

เนื้อหาคำขอ

application/json

ออบเจ็กต์: VerifyRequest

  • notestring | null

การตอบกลับ

200การตอบกลับเมื่อสำเร็จ

เฮดเดอร์การตอบกลับ

  • RateLimit-Policy

    ขีดจำกัดที่มีผล ในรูปแบบของร่าง IETF draft-ietf-httpapi-ratelimit-headers: รายการคั่นด้วยจุลภาค "<name>";q=<quota>;w=<window in seconds> โดย key คืออัตราคำขอของคีย์ API (โควตาคือช่วงพุ่งสูง (burst) กรอบเวลาคือเวลาที่ใช้เติมกลับจนเต็ม สำหรับเซสชันคือ 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

    จำนวนวินาทีจนกว่าขีดจำกัดที่เข้มงวดที่สุดจะรีเซ็ต

  • Idempotency-Replayed

    true หมายถึงการตอบกลับนี้เป็นการส่งคืนซ้ำจากการตอบกลับที่บันทึกไว้สำหรับ Idempotency-Key นี้: ไม่มีการทำการดำเนินการซ้ำ

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

    เนื้อหาในรูปแบบของเครื่องมือแก้ไขของเวอร์ชันที่เผยแพร่ล่าสุด ฟิลด์นี้อาจไม่มี ในกรณีนั้นให้ดึงเนื้อหาในรูปแบบของเครื่องมือแก้ไขจากฉบับร่าง (POST /v1/drafts พร้อม card_id)

  • editing_lockEditingLock | null

    การล็อกการแก้ไขที่มีผลอยู่ ฟิลด์นี้อาจไม่มี ในกรณีนั้น เครื่องมือแก้ไขจะทราบว่าใครถือการล็อกอยู่จาก 409 cards.locked ของ POST /v1/cards/{card_id}/lock

  • 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} อ่านและแทนที่การ์ดตามค่านี้

    length ≤ 512

  • metadataMetadata
400คำขอไม่ถูกต้อง: ค่าพารามิเตอร์หรือสถานะของออบเจ็กต์ไม่อนุญาตให้ดำเนินการ (`detail` เป็นข้อความ)

เฮดเดอร์การตอบกลับ

  • RateLimit-Policy

    ขีดจำกัดที่มีผล ในรูปแบบของร่าง IETF draft-ietf-httpapi-ratelimit-headers: รายการคั่นด้วยจุลภาค "<name>";q=<quota>;w=<window in seconds> โดย key คืออัตราคำขอของคีย์ API (โควตาคือช่วงพุ่งสูง (burst) กรอบเวลาคือเวลาที่ใช้เติมกลับจนเต็ม สำหรับเซสชันคือ 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ไม่ได้ส่งข้อมูลรับรอง (ไม่มีทั้งคุกกี้เซสชันและคีย์ API) หรือไม่พบคีย์

เฮดเดอร์การตอบกลับ

  • RateLimit-Policy

    ขีดจำกัดที่มีผล ในรูปแบบของร่าง IETF draft-ietf-httpapi-ratelimit-headers: รายการคั่นด้วยจุลภาค "<name>";q=<quota>;w=<window in seconds> โดย key คืออัตราคำขอของคีย์ API (โควตาคือช่วงพุ่งสูง (burst) กรอบเวลาคือเวลาที่ใช้เติมกลับจนเต็ม สำหรับเซสชันคือ 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 (โควตาคือช่วงพุ่งสูง (burst) กรอบเวลาคือเวลาที่ใช้เติมกลับจนเต็ม สำหรับเซสชันคือ 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 (โควตาคือช่วงพุ่งสูง (burst) กรอบเวลาคือเวลาที่ใช้เติมกลับจนเต็ม สำหรับเซสชันคือ 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 (โควตาคือช่วงพุ่งสูง (burst) กรอบเวลาคือเวลาที่ใช้เติมกลับจนเต็ม สำหรับเซสชันคือ 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 (โควตาคือช่วงพุ่งสูง (burst) กรอบเวลาคือเวลาที่ใช้เติมกลับจนเต็ม สำหรับเซสชันคือ 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 นอกเหนือจากรหัสทั่วไปของทุกคำขอ

การลองใหม่อย่างปลอดภัย

ส่งเฮดเดอร์ Idempotency-Key (เช่น UUID) ไปกับทุกคำขอ POST และ PATCH เมื่อลองใหม่ด้วยคีย์เดียวกันภายใน 24 ชั่วโมง Sursa จะส่งคืนการตอบกลับที่บันทึกไว้แทนการดำเนินการคำขอซ้ำ

ขีดจำกัดอัตราการเรียก

การตอบกลับมีเฮดเดอร์ RateLimit และ RateLimit-Policy รวมถึงเฮดเดอร์แบบเดิม X-RateLimit-Limit X-RateLimit-Remaining และ X-RateLimit-Reset การตอบกลับ 429 มี Retry-After เป็นวินาที ให้รอตามนั้นแล้วลองใหม่

← cards · เอกสารอ้างอิง API