المخططات

توثق هذه الصفحة نماذج البيانات التي يُرجعها DocMap API. جميع الاستجابات تستخدم JSON.

ExtractionRecord

يمثل سجل الاستخراج عملية استخراج مستند واحدة -- نتيجة معالجة ملف PDF مقابل قالب.

interface ExtractionRecord {
  id: string              // Unique extraction ID
  userId: string          // Owner user ID
  templateId: string      // Template used for extraction
  templateName: string    // Human-readable template name
  fileName: string        // Original uploaded file name
  status: 'processing' | 'completed' | 'failed'
  extractedData: Record<string, unknown> | null  // Structured data or null if failed
  error: string | null    // Error message if failed, null if successful
  variables: Variable[]   // Template variable definitions used
  source: 'dashboard' | 'api'  // How the extraction was initiated
  runId: string | null    // Batch run ID, null if not part of a batch
  processingTimeMs: number | null  // Processing duration in milliseconds
  createdAt: string       // ISO 8601 timestamp
}

وصف الحقول

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

مثال

{
  "id": "ext_kp92mf7x",
  "userId": "u_abc123",
  "templateId": "tpl_inv001",
  "templateName": "Standard Invoice",
  "fileName": "acme-invoice-2024-003.pdf",
  "status": "completed",
  "extractedData": {
    "vendor_name": "Acme Corp",
    "invoice_number": "INV-2024-003",
    "invoice_date": "2024-11-15",
    "due_date": "2024-12-15",
    "total_amount": 4750.00,
    "currency": "USD",
    "line_items": [
      {
        "description": "Cloud Hosting - Pro Plan",
        "quantity": 1,
        "unit_price": 2500.00
      },
      {
        "description": "SSL Certificate (Wildcard)",
        "quantity": 3,
        "unit_price": 750.00
      }
    ]
  },
  "error": null,
  "variables": [
    { "key": "vendor_name", "type": "string", "context": "Name of the vendor or supplier", "required": true },
    { "key": "invoice_number", "type": "string", "context": "Invoice or reference number" },
    { "key": "invoice_date", "type": "date", "context": "Date the invoice was issued" },
    { "key": "due_date", "type": "date", "context": "Payment due date" },
    { "key": "total_amount", "type": "number", "context": "Total amount due" },
    { "key": "currency", "type": "string", "context": "Currency code (e.g. USD, EUR)" },
    {
      "key": "line_items",
      "type": "array",
      "context": "Individual line items on the invoice",
      "arrayType": "object",
      "fields": [
        { "key": "description", "type": "string", "context": "Item description" },
        { "key": "quantity", "type": "number", "context": "Quantity ordered" },
        { "key": "unit_price", "type": "number", "context": "Price per unit" }
      ]
    }
  ],
  "source": "api",
  "runId": null,
  "processingTimeMs": 3842,
  "createdAt": "2024-11-20T14:30:00.000Z"
}

ApiKeyPublic

الإسقاط العام لمفتاح API. قيمة المفتاح الفعلية وتجزئته لا تُرجعان أبداً بعد الإنشاء.

interface ApiKeyPublic {
  id: string              // Key ID
  userId: string          // Owner user ID
  name: string            // Label for the key
  prefix: string          // First 16 characters of the key (e.g., "dm_live_a1b2c3d4")
  expiresAt: string | null  // ISO 8601 expiration, null if never expires
  lastUsedAt: string | null // ISO 8601 last usage, null if never used
  createdAt: string       // ISO 8601 timestamp
  revoked: boolean        // Whether the key has been revoked
}

وصف الحقول

الحقل	النوع	الوصف
id	string	معرّف فريد لمفتاح API.
userId	string	معرّف المستخدم الذي يملك هذا المفتاح.
name	string	تسمية قابلة للقراءة البشرية للمفتاح (مثال: "Production Server").
prefix	string	أول 16 حرفاً من المفتاح، مفيدة لتحديد أي مفتاح قيد الاستخدام دون كشف القيمة الكاملة.
expiresAt	string | null	طابع زمني ISO 8601 لوقت انتهاء صلاحية المفتاح. null إذا أُنشئ المفتاح بدون انتهاء صلاحية.
lastUsedAt	string | null	طابع زمني ISO 8601 لآخر مرة استُخدم فيها المفتاح لمصادقة طلب. null إذا لم يُستخدم أبداً.
createdAt	string	طابع زمني ISO 8601 لوقت إنشاء المفتاح.
revoked	boolean	ما إذا كان المفتاح قد تم إلغاؤه. في استجابات القائمة، تُصفّى المفاتيح الملغاة، لذا عادةً ما تكون false.

مثال

{
  "id": "key_m3x9kq72",
  "userId": "u_abc123",
  "name": "Production Server",
  "prefix": "dm_live_a1b2c3d4",
  "expiresAt": "2025-03-15T00:00:00.000Z",
  "lastUsedAt": "2025-01-10T09:22:14.000Z",
  "createdAt": "2024-12-15T10:00:00.000Z",
  "revoked": false
}

WebhookPublic

الإسقاط العام لخطاف الويب. سر التوقيع لا يُرجع أبداً بعد الإنشاء.

interface WebhookPublic {
  id: string              // Webhook ID
  userId: string          // Owner user ID
  url: string             // Registered endpoint URL
  events: WebhookEvent[]  // Subscribed events
  active: boolean         // Whether the webhook is active
  createdAt: string       // ISO 8601 timestamp
}

type WebhookEvent = 'extraction.completed' | 'extraction.failed'

وصف الحقول

الحقل	النوع	الوصف
id	string	معرّف فريد لخطاف الويب.
userId	string	معرّف المستخدم الذي يملك هذا خطاف الويب.
url	string	نقطة نهاية HTTPS التي تتلقى طلبات POST لخطاف الويب.
events	string[]	الأحداث التي اشترك فيها هذا خطاف الويب. القيم: "extraction.completed" و"extraction.failed".
active	boolean	ما إذا كان خطاف الويب نشطاً. في استجابات القائمة، تُرجع فقط خطافات الويب النشطة، لذا دائماً true.
createdAt	string	طابع زمني ISO 8601 لوقت إنشاء خطاف الويب.

مثال

{
  "id": "webhook-abc123def456",
  "userId": "uid_a1b2c3d4e5f6",
  "url": "https://your-app.com/webhooks/docmap",
  "events": ["extraction.completed", "extraction.failed"],
  "active": true,
  "createdAt": "2025-01-15T10:00:00.000Z"
}

Variable

يحدد المتغير حقلاً واحداً في قالب الاستخراج. تخبر المتغيرات الذكاء الاصطناعي بالبيانات التي يجب البحث عنها ونوع البيانات المطلوب إرجاعها.

interface Variable {
  key: string              // Field name in extracted data
  type: 'string' | 'number' | 'date' | 'boolean' | 'object' | 'array'
  context: string          // Description/hint for the AI extractor
  required?: boolean       // Whether the field is required
  fields?: Variable[]      // Nested fields (for type: 'object')
  arrayType?: 'string' | 'number' | 'object'  // Item type (for type: 'array')
}

وصف الحقول

الحقل	النوع	الوصف
key	string	اسم الحقل الذي سيظهر كمفتاح في البيانات المستخرجة. يجب أن يكون حرفاً واحداً على الأقل.
type	string	نوع البيانات المتوقع. واحد من: string أو number أو date أو boolean أو object أو array.
context	string	وصف بلغة طبيعية يساعد الذكاء الاصطناعي على فهم ما يجب استخراجه لهذا الحقل. السياق الأكثر تحديداً ينتج نتائج أفضل.
required	boolean	(اختياري) إذا كان true، سيحاول الذكاء الاصطناعي دائماً إرجاع قيمة لهذا الحقل.
fields	Variable[]	(اختياري) لـ type: "object"، يحدد الحقول المتداخلة داخل الكائن. هذا تكراري -- يمكن للكائنات المتداخلة أن تحتوي على fields خاصة بها.
arrayType	string	(اختياري) لـ type: "array"، يحدد نوع العناصر في المصفوفة. واحد من: string أو number أو object. عندما يكون arrayType هو "object"، استخدم fields لتحديد شكل كل عنصر.

البنية التكرارية

تدعم المتغيرات التداخل التعسفي عبر خاصية fields. متغير object يحتوي على متغيرات فرعية، ومتغير array مع arrayType: "object" يستخدم أيضاً fields لوصف كل عنصر في المصفوفة.

هذا يتيح لك نمذجة بنيات المستندات المعقدة مثل الفواتير ذات بنود العناصر، والعقود ذات أطراف متعددة، أو أي بيانات هرمية.

مثال: قالب فاتورة مع متغيرات متداخلة

[
  {
    "key": "vendor_name",
    "type": "string",
    "context": "Name of the vendor or supplier company",
    "required": true
  },
  {
    "key": "invoice_number",
    "type": "string",
    "context": "Invoice or reference number"
  },
  {
    "key": "invoice_date",
    "type": "date",
    "context": "Date the invoice was issued (YYYY-MM-DD)"
  },
  {
    "key": "total_amount",
    "type": "number",
    "context": "Total amount due including tax"
  },
  {
    "key": "billing_address",
    "type": "object",
    "context": "The billing address on the invoice",
    "fields": [
      { "key": "street", "type": "string", "context": "Street address" },
      { "key": "city", "type": "string", "context": "City name" },
      { "key": "state", "type": "string", "context": "State or province" },
      { "key": "zip", "type": "string", "context": "Postal or ZIP code" },
      { "key": "country", "type": "string", "context": "Country name or code" }
    ]
  },
  {
    "key": "line_items",
    "type": "array",
    "context": "Individual line items listed on the invoice",
    "arrayType": "object",
    "fields": [
      { "key": "description", "type": "string", "context": "Item description" },
      { "key": "quantity", "type": "number", "context": "Quantity ordered" },
      { "key": "unit_price", "type": "number", "context": "Price per unit" },
      { "key": "total", "type": "number", "context": "Line total (quantity x unit_price)" }
    ]
  },
  {
    "key": "tags",
    "type": "array",
    "context": "Keywords or categories that describe this invoice",
    "arrayType": "string"
  }
]

في هذا المثال:

• billing_address هو object يحتوي على خمسة حقول string متداخلة.
• line_items هو array من الكائنات، كل منها يحتوي على description وquantity وunit_price وtotal.
• tags هو array بسيط من السلاسل النصية بدون fields متداخلة.

UsageResponse

تُرجع بواسطة نقطة النهاية GET /v1/usage. تعرض الخطة الحالية للمستخدم المصادق عليه واستخدام الاستخراج لفترة الفوترة.

interface UsageResponse {
  plan: 'free' | 'starter' | 'core' | 'pro'
  usage: number            // Extractions used this period
  limit: number            // Maximum for current plan
  periodKey: string        // Current period (e.g., "2025-01")
}

وصف الحقول

الحقل	النوع	الوصف
plan	string	خطة المستخدم الحالية. واحدة من: free أو starter أو core أو pro.
usage	number	عدد عمليات الاستخراج المستهلكة في فترة الفوترة الحالية.
limit	number	الحد الأقصى لعمليات الاستخراج المسموح بها لخطة المستخدم.
periodKey	string	فترة الفوترة الحالية بتنسيق YYYY-MM (مثال: "2025-01").

مثال

{
  "data": {
    "plan": "starter",
    "usage": 142,
    "limit": 500,
    "periodKey": "2025-01"
  }
}

TIP

تُرجع نقطة نهاية الاستخدام البيانات مغلفة في كائن data، كما هو موضح أعلاه.

ErrorResponse

تتبع جميع أخطاء API بنية متسقة مع code قابل للقراءة آلياً وmessage قابل للقراءة بشرياً.

interface ErrorResponse {
  error: {
    code: string           // Machine-readable error code
    message: string        // Human-readable description
  }
}

مثال

{
  "error": {
    "code": "NOT_FOUND",
    "message": "Extraction not found"
  }
}

راجع مرجع رموز الأخطاء للحصول على القائمة الكاملة لرموز الأخطاء ورموز حالة HTTP وخطوات الحل.