POST/v1/cards

رفع ملف بوصفه بطاقة

upload_card

أرسل المستند في الحقل file من استمارة multipart/form-data. قبل الحفظ، يتحقق Sursa من توافق امتداد اسم الملف، وContent-Type المعلن للجزء، وتوقيع المحتوى:
- ملفات PDF؛
- ملفات DOCX وXLSX وXLSM وPPTX: ملف ZIP بنوع المستند الرئيسي المعلن؛
- ملفات ODS: ملف ZIP فيه الإدخال mimetype؛
- ملفات XLS: مستند OLE2 فيه تدفق مصنف (workbook)؛
- ملفات TXT وMD وCSV وTSV وHTML وAsciiDoc وEML: نص دون بايتات فارغة بترميز UTF-8 أو بترميز أحادي البايت، وللبريد الإلكتروني ترويسات في البداية؛
- صور PNG وJPEG وTIFF وWebP وBMP: حسب التوقيع.

عدم التوافق يعيد 415 files.type_mismatch؛ والامتداد الذي ليس في قائمة الصيغ يعيد 415 cards.unsupported_format. الملف الأكبر من حد الرفع في التثبيت أو من إجمالي التخزين المتاح للمؤسسة وفق خطتها يعيد 413 files.too_large. عند تفعيل الفحص بمضاد الفيروسات، يعيد الملف المصاب 422 files.infected، وإذا كان الماسح غير متاح مع سياسة «الرفض»، يعيد الطلب 503 files.scan_unavailable. يُسجَّل كل رفض في سجل التدقيق بوصفه file.rejected.

بدلًا من الاستمارة، يمكنك إرسال نص طلب بصيغة application/json (CardUploadFromUpload، منذ الإصدار 1.62.0): الملف هو عملية رفع متعدد الأجزاء جاهزة upload_id (POST /v1/uploads بالغرض card_file)، والحقول هي نفسها كما في الاستمارة، والحقل tags قائمة سلاسل نصية. ملف عملية الرفع فُحص بالفعل عند complete (الصيغة، ومضاد الفيروسات)، وحد الحجم هو حد الرفع متعدد الأجزاء بدلًا من حد الرفع في طلب واحد. تُستخدم عملية الرفع مرة واحدة، في المعاملة نفسها التي تنشئ البطاقة: عملية الرفع المستخدمة سابقًا تعيد 409 uploads.already_used، وغير الجاهزة بعد تعيد 409 uploads.not_ready، والمرفوضة تعيد 422 uploads.rejected، وذات الغرض الآخر تعيد 422 uploads.purpose_mismatch، والمنتهية الصلاحية تعيد 410 uploads.expired، وعملية الرفع الخاصة بجهة مستدعية أخرى أو غير المعروفة تعيد 404 uploads.not_found. إذا فشلت فحوص البطاقة (المجموعة، الفئة، الحدود)، لا تُستهلك عملية الرفع.

المصادقة

أرسل مفتاح 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.

نص الطلب

multipart/form-data

الكائن: CardUploadForm

filestring (application/octet-stream)مطلوب
collectionstring
القيمة الافتراضية: "default"
tagsstring
القيمة الافتراضية: ""
forceboolean
القيمة الافتراضية: false
owner_idinteger | null
verify_interval_daysinteger | null
categorystring | null
sensitiveboolean | null
asyncboolean
القيمة الافتراضية: false
reviewboolean
القيمة الافتراضية: false
folder_idstring | null
مجلد في المجموعة collection توضع فيه البطاقة الجديدة. المجلد من مجموعة أخرى يعيد 400 folders.card_collection_mismatch، والمجلد غير الموجود يعيد 404 folders.not_found، وغياب الصلاحية COLLECTION_EDIT_CARDS على المجلد يعيد 403 authz.forbidden. يجري الفحص قبل حفظ الملف. النسخة المكررة من ملف مرفوع بالفعل (skipped) لا تُنقل إلى المجلد.
length ≤ 64
collection_idinteger | null
المجموعة حسب المعرّف. إذا مُرِّر collection أيضًا، فالأولوية للحقل collection_id. المجموعة غير الموجودة في المؤسسة أو غير المرئية تعيد 404 collections.not_found.
external_idstring | null
قيمة external_id للبطاقة الجديدة. معها تُنشأ البطاقة حتى إن كان الملف نفسه موجودًا في المجموعة. إذا كانت بطاقة أخرى في المؤسسة تستخدم هذه القيمة، يعيد الطلب 409 cards.external_id_taken. لإنشاء بطاقة أو استبدالها حسب external_id، استخدم PUT /v1/cards-by-external-id/{external_id}.
length ≤ 512
metadatastring | null
قيمة metadata للبطاقة الجديدة: كائن JSON بوصفه قيمة حقل النموذج. القواعد هي قواعد MetadataPatch.

application/json

الكائن: CardUploadFromUpload

upload_idstringمطلوب
عملية رفع جاهزة (ready) بالغرض card_file؛ تُستخدم مرة واحدة.
collectionstring
القيمة الافتراضية: "default"
collection_idinteger | null
المجموعة حسب المعرّف. وإذا مُرِّر الحقل collection أيضًا، تكون الأولوية للحقل collection_id. والمجموعة غير الموجودة في المؤسسة، أو غير المرئية، أو الواقعة خارج مجموعات المفتاح تعيد 404 collections.not_found.
tagsarray of string
items ≤ 30
forceboolean
القيمة الافتراضية: false
owner_idinteger | null
verify_interval_daysinteger | null
categorystring | null
sensitiveboolean | null
asyncboolean
القيمة الافتراضية: false
reviewboolean
القيمة الافتراضية: false
folder_idstring | null
length ≤ 64
external_idstring | null
المعرّف external_id للبطاقة الجديدة، كما في حقل الاستمارة. معه تُنشأ البطاقة حتى لو كان في المجموعة الملف نفسه. وإذا كانت بطاقة أخرى في المؤسسة تستخدمه، يعيد الطلب 409 cards.external_id_taken.
length ≤ 512
metadataMetadataPatch

الاستجابات

200القيمة `queued` (غير متزامن)، أو `skipped` (مكرر)، أو `ready` أو `error` (متزامن).

ترويسات الاستجابة

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

الكائن: UploadResult

statusstringمطلوب
القيم المسموح بها: queuedskippedreadyerror
job_idinteger
jobJob
cardCard | null
duplicatetrue
card_idstring | null
reasonstring
القيمة unchanged أو an identical file is already indexed.
tablesinteger
timingsobject
الحقول
- total_snumber
errorstring

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

402بلغت المؤسسة حدًّا من حدود خطتها (البطاقات أو التخزين أو المستخدمون). يحتوي الحقل `error.details` على `kind` و`limit` و`used`.

ترويسات الاستجابة

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

409حالة الكائن لا تسمح بالإجراء، مثل التكرار، أو فهرسة جارية، أو مهمة معالجة عولجت بالفعل.

ترويسات الاستجابة

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

410كان الكائن موجودًا لكنه لم يعد متاحًا: استُخدم الرابط أو انتهت صلاحيته، أو حُذف الملف في نهاية مدة الاحتفاظ به.

ترويسات الاستجابة

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

413نص الطلب يتجاوز الحجم المسموح به.

ترويسات الاستجابة

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

415صيغة الملف غير مدعومة.

ترويسات الاستجابة

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

503خدمة يعتمد عليها هذا الطلب غير متاحة مؤقتًا. أعد المحاولة لاحقًا.

ترويسات الاستجابة

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' \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"upload_id":"upl_0123456789abcdef0123456789abcdef"}' \
  -H "Authorization: Bearer $SURSA_API_KEY"

جرّب

مفتاح API

يبقى المفتاح في ذاكرة هذا التبويب فقط، ولا يُرسَل إلا إلى https://api.sursa.com.

تعمل الطلبات على البيانات الحقيقية لمؤسستك.

Idempotency-Key header

X-View-As header

Idempotency-Key

إذا بقي الحقل فارغًا، يُنشأ مفتاح جديد لكل طلب.

نص الطلب (JSON)