تشغيل استخراج

POST /v1/extractions/run

قم بتشغيل استخراج على مستند PDF. تتم معالجة المستند باستخدام القالب المحدد، وتُرجع البيانات المستخرجة كـ JSON منظم يطابق تعريفات حقول القالب.

جرّبه

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

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

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

الطلب

الترويسات

الترويسة	القيمة	مطلوب
Authorization	Bearer <token>	نعم
Content-Type	application/json	نعم

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

المعامل	النوع	مطلوب	الوصف
async	string	لا	اضبطه على "true" للعودة فوراً بحالة processing بدلاً من الانتظار حتى الاكتمال. السلوك الافتراضي (محذوف أو "false") هو متزامن.

الجسم

الحقل	النوع	مطلوب	الوصف
templateId	string	نعم	معرّف قالب الاستخراج المراد استخدامه.
fileName	string	نعم	اسم الملف الأصلي للمستند.
pdfBase64	string	نعم	محتوى ملف PDF مشفر بـ Base64.
mimeType	string	نعم	نوع MIME للملف. القيم المقبولة: application/pdf، application/vnd.openxmlformats-officedocument.wordprocessingml.document.
runId	string	لا	معرّف اختياري لتجميع عمليات الاستخراج المرتبطة في تشغيل دفعي.

أمثلة الكود

curl

curl -X POST https://api.docmap.io/v1/extractions/run \
  -H "Authorization: Bearer dm_live_abc123def456ghi789jkl012mno345" \
  -H "Content-Type: application/json" \
  -d '{
    "templateId": "tmpl_8f3a2b1c4d5e6f7g",
    "fileName": "invoice-2024-001.pdf",
    "pdfBase64": "JVBERi0xLjQKMSAwIG9iago8PAovVHlwZSAvQ2F0YW...",
    "mimeType": "application/pdf"
  }'

TypeScript

const apiKey = process.env.DOCMAP_API_KEY

const response = await fetch('https://api.docmap.io/v1/extractions/run', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${apiKey}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    templateId: 'tmpl_8f3a2b1c4d5e6f7g',
    fileName: 'invoice-2024-001.pdf',
    pdfBase64: pdfBuffer.toString('base64'),
    mimeType: 'application/pdf',
  }),
})

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

Python

import requests
import base64

api_key = "dm_live_abc123def456ghi789jkl012mno345"

with open("invoice-2024-001.pdf", "rb") as f:
    pdf_base64 = base64.b64encode(f.read()).decode("utf-8")

response = requests.post(
    "https://api.docmap.io/v1/extractions/run",
    headers={
        "Authorization": f"Bearer {api_key}",
        "Content-Type": "application/json",
    },
    json={
        "templateId": "tmpl_8f3a2b1c4d5e6f7g",
        "fileName": "invoice-2024-001.pdf",
        "pdfBase64": pdf_base64,
        "mimeType": "application/pdf",
    },
)

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

الاستجابة

الحالة: 200 OK

جسم الاستجابة مغلف في كائن data.

الحقول

الحقل	النوع	الوصف
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_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",
      "invoice_date": "2024-11-15",
      "total_amount": 1250.00,
      "currency": "USD",
      "line_items": [
        {
          "description": "Widget A",
          "quantity": 10,
          "unit_price": 125.00
        }
      ]
    },
    "error": null,
    "variables": [
      {
        "name": "vendor_name",
        "type": "string",
        "description": "Name of the vendor or supplier"
      },
      {
        "name": "total_amount",
        "type": "number",
        "description": "Total invoice amount"
      }
    ],
    "source": "api",
    "runId": null,
    "processingTimeMs": 3842,
    "createdAt": "2024-11-20T14:30:00.000Z"
  }
}

الوضع غير المتزامن

بشكل افتراضي، تنتظر واجهة API انتهاء الاستخراج قبل الاستجابة (متزامن). لعمليات الاستخراج الطويلة، يمكنك استخدام الوضع غير المتزامن للحصول على استجابة فورية والاستعلام عن النتيجة لاحقاً.

أضف ?async=true إلى عنوان URL لتفعيل الوضع غير المتزامن:

curl -X POST "https://api.docmap.io/v1/extractions/run?async=true" \
  -H "Authorization: Bearer dm_live_abc123def456ghi789jkl012mno345" \
  -H "Content-Type: application/json" \
  -d '{
    "templateId": "tmpl_8f3a2b1c4d5e6f7g",
    "fileName": "invoice-2024-001.pdf",
    "pdfBase64": "JVBERi0xLjQKMSAwIG9iago8PAovVHlwZSAvQ2F0YW...",
    "mimeType": "application/pdf"
  }'

الاستجابة: 202 Accepted

الاستجابة لها نفس الشكل كاستجابة متزامنة، لكن status ستكون "processing"، وextractedData ستكون null، وprocessingTimeMs ستكون null:

{
  "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": [...],
    "source": "api",
    "runId": null,
    "processingTimeMs": null,
    "createdAt": "2024-11-20T14:30:00.000Z"
  }
}

استخدم المعرّف id المُرجع للاستعلام عن نقطة النهاية جلب استخراج حتى يتغير status إلى "completed" أو "failed".

WARNING

إذا بقي الاستخراج في حالة "processing" لأكثر من دقيقتين، تعامل معه على أنه فاشل. لا يوجد مهلة تلقائية -- في حالات نادرة (مثل إعادة تشغيل الخادم)، قد يبقى السجل في حالة "processing" إلى أجل غير مسمى.

الأخطاء

الحالة	الرمز	الوصف
401	UNAUTHORIZED	مفتاح API / رمز مفقود أو غير صالح أو منتهي الصلاحية.
404	NOT_FOUND	القالب المحدد غير موجود أو لا ينتمي إلى حسابك.
429	USAGE_LIMIT_EXCEEDED	لقد وصلت إلى حد الاستخراج الشهري لخطتك.
500	INTERNAL_ERROR	حدث خطأ غير متوقع أثناء معالجة الاستخراج.