قائمة عمليات الاستخراج

GET /v1/extractions

قائمة سجلات الاستخراج للمستخدم المصادق عليه. تُرجع النتائج بترتيب زمني عكسي (الأحدث أولاً). يدعم ترقيم الصفحات القائم على المؤشر والتصفية حسب القالب أو معرّف التشغيل الدفعي أو نطاق التاريخ.

جرّبه

اختبر هذا الـ endpoint بشكل تفاعلي في Swagger UI.

المصادقة مطلوبة

أدرج مفتاح API في ترويسة Authorization.

الطلب

الترويسات

الترويسة	القيمة	مطلوب
Authorization	Bearer <token>	نعم

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

المعامل	النوع	مطلوب	الوصف
templateId	string	لا	تصفية النتائج لعمليات الاستخراج من قالب محدد.
runId	string	لا	تصفية النتائج لعمليات الاستخراج من تشغيل دفعي محدد. يُرجع جميع النتائج المطابقة (يتجاهل limit/cursor).
limit	number	لا	الحد الأقصى لعدد النتائج المُرجعة. الافتراضي: 50، الحد الأقصى: 100.
cursor	string	لا	مؤشر ترقيم الصفحات. مرر قيمة createdAt لآخر عنصر من الصفحة السابقة لجلب الصفحة التالية.
dateFrom	string	لا	تصفية عمليات الاستخراج التي أُنشئت في هذا التاريخ أو بعده (YYYY-MM-DD).
dateTo	string	لا	تصفية عمليات الاستخراج التي أُنشئت في هذا التاريخ أو قبله (YYYY-MM-DD).

ترقيم الصفحات

تتضمن الاستجابة قيمة منطقية hasMore. عندما تكون true، مرر قيمة createdAt لآخر عنصر كمعامل cursor لجلب الصفحة التالية.

عند التصفية بـ runId، تُرجع جميع عمليات الاستخراج المطابقة في استجابة واحدة (لا حاجة لترقيم الصفحات لأن التشغيلات الدفعية عادةً صغيرة).

أمثلة الكود

curl

# List all extractions (default limit of 50)
curl https://api.docmap.io/v1/extractions \
  -H "Authorization: Bearer dm_live_a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f0"

# Filter by template and limit results
curl "https://api.docmap.io/v1/extractions?templateId=48291&limit=10" \
  -H "Authorization: Bearer dm_live_a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f0"

# Filter by batch run ID
curl "https://api.docmap.io/v1/extractions?runId=b4704c6e-8917-4671-8c92-178aec3eba92" \
  -H "Authorization: Bearer dm_live_a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f0"

# Filter by date range
curl "https://api.docmap.io/v1/extractions?dateFrom=2025-01-01&dateTo=2025-01-31" \
  -H "Authorization: Bearer dm_live_a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f0"

# Paginate through results
curl "https://api.docmap.io/v1/extractions?limit=10&cursor=2025-01-15T09:30:00.000Z" \
  -H "Authorization: Bearer dm_live_a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f0"

TypeScript

const apiKey = process.env.DOCMAP_API_KEY

// List all extractions
const response = await fetch('https://api.docmap.io/v1/extractions', {
  headers: { 'Authorization': `Bearer ${apiKey}` },
})

const { data, hasMore } = await response.json()
console.log(`Found ${data.length} extractions, hasMore: ${hasMore}`)

// Paginate through all results
let cursor: string | undefined
const allExtractions = []

do {
  const url = new URL('https://api.docmap.io/v1/extractions')
  url.searchParams.set('limit', '50')
  if (cursor) url.searchParams.set('cursor', cursor)

  const res = await fetch(url, {
    headers: { 'Authorization': `Bearer ${apiKey}` },
  })
  const page = await res.json()

  allExtractions.push(...page.data)
  cursor = page.hasMore ? page.data.at(-1)?.createdAt : undefined
} while (cursor)

console.log(`Total: ${allExtractions.length} extractions`)

// Filter by template
const filtered = await fetch(
  'https://api.docmap.io/v1/extractions?templateId=48291&limit=10',
  { headers: { 'Authorization': `Bearer ${apiKey}` } },
)

const { data: filteredData } = await filtered.json()

Python

import requests

api_key = "dm_live_a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f0"
headers = {"Authorization": f"Bearer {api_key}"}

# List all extractions
response = requests.get(
    "https://api.docmap.io/v1/extractions",
    headers=headers,
)
result = response.json()
print(f"Found {len(result['data'])} extractions, hasMore: {result['hasMore']}")

# Paginate through all results
all_extractions = []
cursor = None

while True:
    params = {"limit": 50}
    if cursor:
        params["cursor"] = cursor

    response = requests.get(
        "https://api.docmap.io/v1/extractions",
        headers=headers,
        params=params,
    )
    page = response.json()

    all_extractions.extend(page["data"])

    if not page["hasMore"]:
        break
    cursor = page["data"][-1]["createdAt"]

print(f"Total: {len(all_extractions)} extractions")

# Filter by date range
response = requests.get(
    "https://api.docmap.io/v1/extractions",
    headers=headers,
    params={"dateFrom": "2025-01-01", "dateTo": "2025-01-31"},
)

الاستجابة

الحالة: 200 OK

يحتوي جسم الاستجابة على مصفوفة data من سجلات الاستخراج وقيمة منطقية hasMore تشير إلى وجود صفحات إضافية.

حقول المستوى الأعلى

الحقل	النوع	الوصف
data	ExtractionRecord[]	مصفوفة سجلات الاستخراج.
hasMore	boolean	true إذا كانت هناك نتائج إضافية بعد الصفحة الحالية. false عند التصفية بـ runId (تُرجع جميع النتائج).

حقول سجل الاستخراج

يحتوي كل سجل استخراج في المصفوفة على نفس حقول استجابة تشغيل استخراج:

الحقل	النوع	الوصف
id	string	معرّف الاستخراج الفريد (مسبوق بـ extract-).
userId	string	معرّف المستخدم الذي يملك هذا الاستخراج.
templateId	string	معرّف القالب المستخدم للاستخراج.
templateName	string	اسم العرض للقالب المستخدم.
fileName	string	اسم الملف الأصلي للمستند المرفوع.
status	"processing" | "completed" | "failed"	حالة الاستخراج الحالية. "processing" إذا كان لا يزال قيد المعالجة، "completed" عند النجاح، "failed" عند الخطأ.
extractedData	object | null	البيانات المستخرجة المطابقة لحقول القالب. null إذا فشل الاستخراج.
error	string | null	رسالة خطأ تصف الفشل. null إذا نجح الاستخراج.
variables	Variable[]	مصفوفة تعريفات متغيرات القالب المستخدمة أثناء الاستخراج.
source	"dashboard" | "api"	كيف تم تشغيل الاستخراج.
runId	string | null	معرّف التشغيل الدفعي، إذا تم توفيره.
processingTimeMs	number | null	إجمالي مدة المعالجة بالمللي ثانية.
createdAt	string	طابع زمني ISO 8601 لوقت إنشاء الاستخراج.

مثال

{
  "data": [
    {
      "id": "extract-KmL9nOpQrStUvWxYz",
      "userId": "L5kM9nRpQ7vX3yZ1wD4eF6gHjA2",
      "templateId": "48291",
      "templateName": "Invoice Template",
      "fileName": "invoice-2024-001.pdf",
      "status": "completed",
      "extractedData": {
        "vendor_name": "Acme Corp",
        "invoice_number": "INV-2024-001",
        "total_amount": 1250.00
      },
      "error": null,
      "variables": [
        {
          "name": "vendor_name",
          "type": "string",
          "description": "Name of the vendor or supplier"
        }
      ],
      "source": "api",
      "runId": null,
      "processingTimeMs": 3842,
      "createdAt": "2025-01-20T14:30:00.000Z"
    }
  ],
  "hasMore": true
}

الأخطاء

الحالة	الرمز	الوصف
401	UNAUTHORIZED	مفتاح API / رمز مفقود أو غير صالح أو منتهي الصلاحية.