انتقل إلى المحتوى
Sursa Developers

PATCH/v1/cards/{card_id}

تعديل بطاقة

update_card

المصادقة

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

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

  • card_idstringمطلوب

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

  • 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

الكائن: CardUpdate

  • external_idstring | null

    يضبط قيمة external_id للبطاقة أو يغيّرها؛ والقيمة "" أو null تزيلها. إذا كانت بطاقة أخرى في المؤسسة تستخدم هذه القيمة، يعيد الطلب 409 cards.external_id_taken. لا تتغير قيمة external_id لبطاقة من مصدر (409 cards.managed_by_source).

    length ≤ 512

  • metadataMetadataPatch
  • titlestring | null
  • owner_idinteger | null
  • verifier_idsarray of integer | null
  • verify_interval_daysinteger | null

    ≥ 1, ≤ 3650

  • tagsarray of string | null
  • statusstring | null
  • source_urlstring | null
  • categorystring | null
  • sensitiveboolean | null
  • table_categoriesmap of object | null

الاستجابات

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

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

    معرّف البطاقة في نظام جهة التكامل. وهو فريد في المؤسسة بين البطاقات التي لا تأتي من مصادر؛ والقيمة 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 (الحصة هي هامش الذروة، والنافذة الزمنية هي مدة إعادة ملئه بالكامل؛ وللجلسة يكون 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