جلب استخراج

GET /v1/extractions/{id}

استرجاع سجل استخراج واحد بواسطة المعرّف. تُستخدم نقطة النهاية هذه بشكل أساسي للاستعلام عن نتيجة استخراج غير متزامن.

جرّبه

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

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

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

الطلب

الترويسات

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

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

المعامل	النوع	مطلوب	الوصف
id	string	نعم	معرّف الاستخراج المُرجع من نقطة النهاية تشغيل استخراج.

أمثلة الكود

curl

curl https://api.docmap.io/v1/extractions/extract_9k2m4n6p8q0r1s3t \
  -H "Authorization: Bearer dm_live_abc123def456ghi789jkl012mno345"

TypeScript

const apiKey = process.env.DOCMAP_API_KEY

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

const { data } = await response.json()
console.log(data.status, data.extractedData)

Python

import requests

api_key = "dm_live_abc123def456ghi789jkl012mno345"

response = requests.get(
    "https://api.docmap.io/v1/extractions/extract_9k2m4n6p8q0r1s3t",
    headers={"Authorization": f"Bearer {api_key}"},
)

data = response.json()["data"]
print(data["status"], data["extractedData"])

الاستجابة

الحالة: 200 OK

جسم الاستجابة مغلف في كائن data يحتوي على سجل استخراج واحد.

الحقول

كل حقل مطابق لاستجابة تشغيل استخراج.

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

مثال (مكتمل)

{
  "data": {
    "id": "extract_9k2m4n6p8q0r1s3t",
    "userId": "uid_a1b2c3d4e5f6",
    "templateId": "tmpl_8f3a2b1c4d5e6f7g",
    "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": "2024-11-20T14:30:00.000Z"
  }
}

مثال (قيد المعالجة)

{
  "data": {
    "id": "extract_9k2m4n6p8q0r1s3t",
    "userId": "uid_a1b2c3d4e5f6",
    "templateId": "tmpl_8f3a2b1c4d5e6f7g",
    "templateName": "Invoice Template",
    "fileName": "invoice-2024-001.pdf",
    "status": "processing",
    "extractedData": null,
    "error": null,
    "variables": [
      {
        "name": "vendor_name",
        "type": "string",
        "description": "Name of the vendor or supplier"
      }
    ],
    "source": "api",
    "runId": null,
    "processingTimeMs": null,
    "createdAt": "2024-11-20T14:30:00.000Z"
  }
}

نمط الاستعلام المتكرر

عند استخدام عمليات الاستخراج غير المتزامنة، قم بالاستعلام عن نقطة النهاية هذه حتى لا تكون الحالة "processing":

TypeScript

async function pollExtraction(extractionId: string, apiKey: string) {
  const maxAttempts = 30
  const intervalMs = 2000

  for (let i = 0; i < maxAttempts; i++) {
    const response = await fetch(
      `https://api.docmap.io/v1/extractions/${extractionId}`,
      { headers: { 'Authorization': `Bearer ${apiKey}` } },
    )

    const { data } = await response.json()

    if (data.status !== 'processing') {
      return data
    }

    await new Promise((resolve) => setTimeout(resolve, intervalMs))
  }

  throw new Error('Extraction timed out')
}

Python

import time
import requests

def poll_extraction(extraction_id: str, api_key: str):
    max_attempts = 30
    interval_s = 2

    for _ in range(max_attempts):
        response = requests.get(
            f"https://api.docmap.io/v1/extractions/{extraction_id}",
            headers={"Authorization": f"Bearer {api_key}"},
        )

        data = response.json()["data"]

        if data["status"] != "processing":
            return data

        time.sleep(interval_s)

    raise TimeoutError("Extraction timed out")

TIP

يُوصى بفاصل استعلام قدره ثانيتان. تكتمل معظم عمليات الاستخراج في غضون 5--30 ثانية.

الأخطاء

الحالة	الرمز	الوصف
401	UNAUTHORIZED	مفتاح API / رمز مفقود أو غير صالح أو منتهي الصلاحية.
403	FORBIDDEN	الاستخراج ينتمي إلى مستخدم آخر.
404	NOT_FOUND	لا يوجد استخراج بالمعرّف المحدد.