POST/v1/cards/bulk

ดำเนินการแบบกลุ่มกับการ์ด

bulk_cards

ดำเนินการแบบกลุ่มกับการ์ดที่เลือก Sursa ตรวจสิทธิ์ของการ์ดแต่ละใบ: บทบาทในคอลเลกชันและโปรไฟล์ข้อมูล (การดำเนินการที่ลบหรือทำลายข้อมูลต้องเข้าถึงได้ทุกส่วนของเอกสาร) การ์ดที่คุณดำเนินการไม่ได้จะถูกข้ามพร้อมเหตุผล การเปลี่ยนแปลงแต่ละครั้งบันทึกลงในล็อกการตรวจสอบของการ์ด และมีรายการ cards.bulk อีกหนึ่งรายการที่เก็บผลลัพธ์

การดำเนินการกับโฟลเดอร์:
- folder_move พร้อม params.folder_id (จำเป็น) ใส่การ์ดลงในโฟลเดอร์ และถ้าส่ง params.from_folder_id มาด้วย จะนำการ์ดออกจากโฟลเดอร์นั้น (การย้ายออกจากโฟลเดอร์ที่เปิดอยู่)
- folder_remove พร้อม params.folder_id นำการ์ดออกจากโฟลเดอร์ โดยการ์ดยังอยู่ในคอลเลกชัน

Sursa ตรวจโฟลเดอร์หนึ่งครั้งต่อคำขอ: โฟลเดอร์ที่ไม่มีอยู่หรือมองไม่เห็นจะส่งคืน 404 folders.not_found การไม่มีสิทธิ์ COLLECTION_EDIT_CARDS บนโฟลเดอร์จะส่งคืน 403 authz.forbidden และการไม่ระบุ folder_id หรือ from_folder_id จากคอลเลกชันอื่นจะส่งคืน 400 cards.bulk_invalid สำหรับการ์ดแต่ละใบ: ถ้าไม่มี CARD_EDIT การ์ดจะถูกข้ามเป็น no_write การ์ดจากคอลเลกชันอื่นที่ไม่ใช่คอลเลกชันของโฟลเดอร์จะถูกข้ามเป็น collection_mismatch และการ์ดที่อยู่ในตำแหน่งนั้นอยู่แล้วจะรายงานเป็น unchanged

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

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

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

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

ออบเจ็กต์: BulkRequest

idsarray of stringจำเป็น
items ≥ 1, items ≤ 500
actionBulkActionจำเป็น
paramsobject

การตอบกลับ

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

ออบเจ็กต์: BulkResult

countsobjectจำเป็น
ฟิลด์
- doneintegerจำเป็น
- reasonsobjectจำเป็น
  ฟิลด์
  - admin_onlynumber
  - collection_mismatchinteger
  - connectornumber
  - failedinteger
  - needs_usernumber
  - no_verifynumber
  - no_writenumber
  - not_foundnumber
  - partial_accessnumber
  - processinginteger
  - same_collectionnumber
  - sensitive_lowernumber
  - target_needs_reindexnumber
  - unchangedinteger
- skippedintegerจำเป็น
donearray of stringจำเป็น
fileAttachment
jobsarray of integer
skippedarray of BulkSkippedจำเป็น

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

curl -X POST 'https://api.sursa.com/v1/cards/bulk' \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"ids":["string"],"action":"verify"}' \
  -H "Authorization: Bearer $SURSA_API_KEY"

ลองใช้

คีย์ API

คีย์อยู่ในหน่วยความจำของแท็บนี้ และส่งไปยัง https://api.sursa.com เท่านั้น

คำขอมีผลกับข้อมูลจริงขององค์กรของคุณ

Idempotency-Key header

X-View-As header

Idempotency-Key

ถ้าเว้นว่างไว้ ระบบจะสร้างคีย์ใหม่ให้แต่ละคำขอ

เนื้อหาคำขอ (JSON)