POST/v1/cards/bulk

تنفيذ إجراء جماعي على البطاقات

bulk_cards

ينفّذ إجراءً جماعيًا على البطاقات المحددة. تُفحص الصلاحيات لكل بطاقة: الدور في المجموعة وملف تعريف البيانات (الإجراءات المدمِّرة تتطلب الوصول إلى كل جزء من المستند). البطاقات التي لا يمكنك تنفيذ الإجراء عليها تُتخطى مع ذكر السبب. يُسجَّل كل تغيير في سجل التدقيق للبطاقة، إضافة إلى سجل واحد cards.bulk بالنتيجة.

إجراءات المجلدات:
- الإجراء folder_move مع params.folder_id (مطلوب) يضع البطاقة في المجلد، وإذا مُرِّر params.from_folder_id، يزيلها من ذلك المجلد (نقل من المجلد المفتوح).
- الإجراء folder_remove مع params.folder_id يزيل البطاقة من المجلد؛ وتبقى البطاقة في المجموعة.

تُفحص المجلدات مرة واحدة لكل طلب: المجلد المفقود أو غير المرئي يعيد 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 <key>.

معاملات الترويسة

Idempotency-Keystring
مفتاح لإعادة محاولة عملية كتابة بأمان: من 1 إلى 255 حرفًا من أحرف ASCII القابلة للطباعة؛ يُنصح بقيمة UUID v4 لكل عملية منطقية. إعادة المحاولة بالمفتاح نفسه خلال 24 ساعة لا تنفّذ العملية مرة أخرى، بل تعيد الاستجابة المحفوظة (الحالة والترويسات والنص) مع الترويسة Idempotency-Replayed: true. المفتاح نفسه مع أسلوب أو مسار أو Content-Type أو نص مختلف يعيد 409 api.idempotency_mismatch؛ وما دام الطلب الأول قيد التنفيذ، يعيد 409 api.idempotency_in_progress مع Retry-After: 1. بعد استجابة 5xx أو 429 يُحرَّر المفتاح، وتنفّذ إعادة المحاولة العملية مرة أخرى. نطاق المفتاح هو المؤسسة والجهة المستدعية (مفتاح 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 (الحصة هي هامش الذروة، والنافذة الزمنية هي مدة إعادة ملئه بالكامل؛ وللجلسة يكون 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 (الحصة هي هامش الذروة، والنافذة الزمنية هي مدة إعادة ملئه بالكامل؛ وللجلسة يكون 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 (الحصة هي هامش الذروة، والنافذة الزمنية هي مدة إعادة ملئه بالكامل؛ وللجلسة يكون 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 (الحصة هي هامش الذروة، والنافذة الزمنية هي مدة إعادة ملئه بالكامل؛ وللجلسة يكون 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 (الحصة هي هامش الذروة، والنافذة الزمنية هي مدة إعادة ملئه بالكامل؛ وللجلسة يكون 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 (الحصة هي هامش الذروة، والنافذة الزمنية هي مدة إعادة ملئه بالكامل؛ وللجلسة يكون 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 (الحصة هي هامش الذروة، والنافذة الزمنية هي مدة إعادة ملئه بالكامل؛ وللجلسة يكون 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 ساعة تعيد الاستجابة المحفوظة بدل تنفيذ الطلب مرة أخرى.

حدود المعدل

تحمل الاستجابات الترويستين 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)