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

GET/v1/cards

عرض قائمة البطاقات

list_cards

يعيد البطاقات مع عوامل التصفية والفرز وترقيم الصفحات. مع preview=1 (للعرض الشبكي)، تحتوي كل بطاقة أيضًا على preview (أول 200 حرف من النص) وpreview_tables (أوراق الجداول مع عدد صفوفها)، ضمن ملف تعريف البيانات الخاص بك.

المصادقة

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

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

  • collectionstring | null
  • folderstring | null

    القيمة <folder ID> تعيد بطاقات المجلد وكل مجلداته الفرعية. والقيمة none تعيد بطاقات المجموعة التي ليست في أي مجلد، وتتطلب المعامل collection (وإلا 400 cards.invalid_folder_filter). إذا لم يكن المجلد موجودًا أو لم يكن مرئيًا لك، يعيد الطلب 404 folders.not_found.

    length ≤ 64

  • statusstring | null

    القيم المسموح بها: processingreadyerrorarchivedall

  • ownerstring | null

    القيمة me أو none أو معرّف مستخدم.

  • owner_idinteger | null
  • verificationstring | null

    القيم المسموح بها: verifiedneeds_verificationstale

  • kindCardKind
  • typestring | null

    القيمة table تعيد البطاقات التي فيها جداول حقائق، والقيمة text تعيد البطاقات التي ليس فيها جداول.

    القيم المسموح بها: tabletext

  • tagsstring | null

    وسوم مفصولة بفواصل (يجب أن تحمل البطاقة كل الوسوم).

  • idsstring | null

    معرّفات بطاقات مفصولة بفواصل.

  • searchstring | null
  • categorystring | null
  • sensitiveboolean | null
  • sortCardSort

    القيمة الافتراضية: "created_at"

  • orderstring

    القيم المسموح بها: ascdesc

    القيمة الافتراضية: "desc"

  • limitinteger

    القيمة الافتراضية: 200

  • offsetinteger

    القيمة الافتراضية: 0

  • previewboolean

    القيمة true تضيف preview (أول 200 حرف) وpreview_tables للعرض الشبكي.

    القيمة الافتراضية: false

  • updated_sincestring (date-time)

    البطاقات التي تساوي فيها قيمة updated_at هذه اللحظة أو تأتي بعدها فقط (RFC 3339 مع إزاحة التوقيت)، للمزامنة. دون sort وorder صريحين، تُرتَّب القائمة حسب updated_at تصاعديًا، ثم حسب id. البطاقات المحذوفة لا تظهر في القائمة: الحذف يصل على شكل أحداث.

  • metadatamap of string

    التصفية حسب metadata: الشرط metadata[<key>]=<value> يطابق القيمة تمامًا. حتى 3 شروط، ويجب أن تتحقق كلها (?metadata[team]=support&metadata[crm_id]=A-1042). أكثر من 3 شروط أو مفتاح غير صالح يعيد 400 api.metadata_invalid.

  • collection_idinteger

    المجموعة حسب المعرّف. إذا مُرِّر المعامل collection أيضًا، تكون الأولوية للمعامل collection_id. المجموعة غير الموجودة في المؤسسة أو غير المرئية تعيد 404 collections.not_found.

  • external_idstring

    البطاقة التي لها قيمة external_id هذه فقط.

  • cursorstring

    مؤشر الصفحة التالية من الترويسة X-Next-Cursor أو من الحقل next_cursor في الاستجابة السابقة بعوامل التصفية نفسها؛ ويحمل حجم الصفحة. مع المعامل offset معًا: 422 validation.failed؛ ومؤشر قائمة أخرى أو عوامل تصفية أخرى أو مؤشر تالف: 400 api.cursor_invalid.

    length ≤ 512

  • expand[]array of string

    الكائنات المرتبطة التي تُضمَّن في الاستجابة (منذ الإصدار 1.62.0): مسار من القائمة x-expandable للعملية. كرّر المعامل حتى 10 مرات. للمسار جزءان على الأكثر تفصل بينهما نقطة (collection.default_owner). في القائمة يبدأ المسار بالبادئة data. ويُطبَّق على كل عنصر في الصفحة (expand[]=data.owner). يوضع الكائن الموسَّع في الكائن expanded للعنصر، ويبقى حقل المعرّف. والكائن الذي لا يحق للجهة المستدعية رؤيته وفق فحوص عملية القراءة الخاصة به يُوسَّع إلى null. ويعيد المسار غير المعروف، أو أكثر من 10 مسارات، أو المسار الأعمق من جزأين 400 api.expand_invalid.

    items ≤ 10

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

  • 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.

الاستجابات

200استجابة ناجحة

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

  • Link

    عنوان الصفحة التالية، <…>; rel="next". غياب الترويسة يعني أن هذه الصفحة الأخيرة.

  • X-Next-Cursor

    مؤشر الصفحة التالية للمعامل cursor. غياب الترويسة يعني أن هذه الصفحة الأخيرة.

  • 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

الكائن: CardList

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

حدود المعدل

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

← cards · مرجع API