PUT/v1/cards-by-external-id/{external_id}

إنشاء بطاقة أو استبدالها بالمعرّف الخارجي

upsert_card_by_external_id

ينشئ بطاقة أو يستبدلها حسب المعرّف external_id الذي يحدده صاحب التكامل. أرسل النص بصيغة application/json (CardTextUpsert) أو الملف بصيغة multipart/form-data (CardFileUpsertForm، مع فحوص الملف نفسها كما في POST /v1/cards). إذا لم يكن في المؤسسة بطاقة بهذا المعرّف external_id، تُنشأ البطاقة في المجموعة والمجلد المحددين في نص الطلب (201). وإلا يُستبدل المحتوى بإصدار جديد ويُفهرَس من جديد بالطريقة نفسها التي يُفهرَس بها إصدار جديد من ملف، وتأخذ تفاصيل البطاقة (العنوان، والوسوم، والمسؤول، والفئة، وmetadata) القيم الممرَّرة (200). المحتوى غير المتغير لا ينشئ إصدارًا جديدًا (status: skipped، reason: unchanged)، لذا فتكرار الطلب آمن حتى دون الترويسة Idempotency-Key. عند تمرير الحقل metadata، يستبدل الكائن كله. يُفحص الوصول كما في الرفع عند إنشاء البطاقة، وكما في تعديل البطاقة عند استبدالها. لا يُستبدل محتوى البطاقة المرئية جزئيًا فقط للجهة المستدعية (403 cards.content_whole_access). بطاقات المصادر لا تُستبدل بهذه الطريقة: إذا كان المعرّف external_id يخص مستندًا من مصدر مخصص، أو كانت البطاقة التي عُثر عليها يديرها مصدر، يعيد الطلب 409 cards.managed_by_source. تغيير المحتوى يزيل توثيق البطاقة، كما يفعل أي إصدار جديد (السبب update).

المصادقة

أرسل مفتاح API في الترويسة Authorization: Authorization: Bearer <key>.

معاملات المسار

external_idstringمطلوب
المعرّف external_id للبطاقة: سلسلة من 1 إلى 512 حرفًا، فريدة داخل المؤسسة.
length ≥ 1, length ≤ 512

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

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

الكائن: CardTextUpsert

titlestring
length ≥ 1, length ≤ 200
bodystringمطلوب
نص البطاقة بالصيغة المحددة في content_type.
length ≥ 1, length ≤ 500000
content_typeCardTextContentType
collectionstring
المجموعة حسب الاسم، عند إنشاء البطاقة. افتراضيًا، المجموعة الافتراضية في التثبيت.
collection_idinteger | null
المجموعة حسب المعرّف، عند إنشاء البطاقة. إذا مُرِّر collection أيضًا، فالأولوية للحقل collection_id.
folder_idstring | null
مجلد في المجموعة للبطاقة الجديدة، مع الفحوص نفسها التي يخضع لها folder_id عند رفع ملف.
length ≤ 64
tagsarray of string | null
items ≤ 30
categorystring | null
length ≤ 60
sensitiveboolean | null
owner_idinteger | null
verify_interval_daysinteger | null
≥ 1, ≤ 3650
metadataMetadataPatch
asyncboolean
القيمة true تعيد الاستجابة فورًا وتفهرس البطاقة في قائمة الانتظار؛ والقيمة false تعيدها بعد الفهرسة.
القيمة الافتراضية: false

multipart/form-data

الكائن: CardFileUpsertForm

filestring (application/octet-stream)مطلوب
titlestring | null
عنوان البطاقة. إن لم يُمرَّر، تأخذ البطاقة الجديدة اسم الملف، وتحتفظ البطاقة الموجودة بعنوانها.
length ≤ 200
collectionstring
collection_idinteger | null
folder_idstring | null
length ≤ 64
tagsstring
وسوم مفصولة بفواصل.
owner_idinteger | null
verify_interval_daysinteger | null
categorystring | null
sensitiveboolean | null
metadatastring | null
الحقل metadata: كائن JSON بوصفه قيمة حقل النموذج. القواعد هي قواعد MetadataPatch.
asyncboolean
القيمة الافتراضية: false

الاستجابات

200البطاقة كانت موجودة. استُبدل محتواها (`queued`، `ready`، `error`) أو لم يتغير (`skipped`).

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

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

الكائن: 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

201أُنشئت البطاقة (`queued` للطلب غير المتزامن، و`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
عدد الثواني حتى إعادة ضبط الحد الأشد صرامة.

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

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، إضافةً إلى الرموز العامة لكل طلب.

حدود المعدل

تحمل الاستجابات الترويستين RateLimit وRateLimit-Policy، والترويسات الأقدم X-RateLimit-Limit وX-RateLimit-Remaining وX-RateLimit-Reset. وفي الاستجابة 429 الترويسة Retry-After بالثواني: انتظر ثم أعد المحاولة.

← cards · مرجع API

curl -X PUT 'https://api.sursa.com/v1/cards-by-external-id/EXTERNAL_ID' \
  -H "Content-Type: application/json" \
  -d '{"title":"Refund policy","body":"# Refund policy\n\nRefunds are processed within 14 days.","collection":"support"}' \
  -H "Authorization: Bearer $SURSA_API_KEY"

جرّب

مفتاح API

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

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

X-View-As header

external_id path *

نص الطلب (JSON)