حدود الاستخدام والمعدل

حدود الاستخراج الشهرية

تتضمن كل خطة عدداً ثابتاً من عمليات الاستخراج لكل شهر تقويمي. يُعاد تعيين الاستخدام في اليوم الأول من كل شهر (UTC).

الخطة	عمليات الاستخراج الشهرية	السعر
Free	25	$0
Starter	350	-
Core	2,500	-
Pro	10,000	-

TIP

راجع docmap.io/#pricing لأسعار الخطط الحالية ومقارنة الميزات.

التحقق من استخدامك

استعلم عن نقطة النهاية /v1/usage لرؤية خطتك الحالية وعدد الاستخدام والحد لفترة الفوترة النشطة:

curl

curl https://api.docmap.io/v1/usage \
  -H "Authorization: Bearer dm_live_your_api_key"

TypeScript

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

const { data } = await response.json();

console.log(`Plan: ${data.plan}`);
console.log(`Usage: ${data.usage} / ${data.limit}`);
console.log(`Period: ${data.periodKey}`);

Python

import requests

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

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

print(f"Plan: {data['plan']}")
print(f"Usage: {data['usage']} / {data['limit']}")
print(f"Period: {data['periodKey']}")

مثال على الاستجابة:

{
  "data": {
    "plan": "core",
    "usage": 1847,
    "limit": 2500,
    "periodKey": "2025-07"
  }
}

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

معالجة تجاوز الحد

عند الوصول إلى حدك الشهري، يُرجع أي استدعاء لـ POST /v1/extractions/run حالة 429 مع رمز الخطأ USAGE_LIMIT_EXCEEDED:

{
  "error": {
    "code": "USAGE_LIMIT_EXCEEDED",
    "message": "Monthly extraction limit reached (25/25). Upgrade your plan for more extractions."
  }
}

لديك خياران:

1. قم بترقية خطتك. انتقل إلى الإعدادات > الفوترة في لوحة تحكم DocMap. يسري حدك الجديد فوراً.
2. انتظر فترة الفوترة التالية. يُعاد تعيين الاستخدام تلقائياً في أول كل شهر (UTC).

WARNING

لا تعد محاولة أخطاء 429 USAGE_LIMIT_EXCEEDED. على عكس أخطاء الخادم، لن تُحل من تلقاء نفسها. تحقق من نقطة النهاية /v1/usage لرؤية عددك وحدك الحاليين قبل إجراء طلبات دفعية.

إليك كيفية معالجة هذا بأناقة في الكود الخاص بك:

async function runExtraction(templateId: string, fileName: string, pdfBase64: string) {
  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, fileName, pdfBase64, mimeType: "application/pdf" }),
  });

  if (response.status === 429) {
    const { error } = await response.json();
    if (error.code === "USAGE_LIMIT_EXCEEDED") {
      console.error("Monthly extraction limit reached. Upgrade your plan or wait until next month.");
      // Optionally check current usage
      const usageResponse = await fetch("https://api.docmap.io/v1/usage", {
        headers: { Authorization: `Bearer ${apiKey}` },
      });
      const { data: usage } = await usageResponse.json();
      console.log(`Current usage: ${usage.usage}/${usage.limit} (${usage.plan} plan)`);
      return null;
    }
  }

  const { data } = await response.json();
  return data;
}

تنبيهات الاستخدام

يرسل DocMap تلقائياً إشعار بريد إلكتروني عندما يصل استخدامك إلى 80% من حدك الشهري. هذا يمنحك وقتاً لترقية خطتك قبل إيقاف عمليات الاستخراج.

• يُرسل التنبيه مرة واحدة لكل فترة فوترة -- لن تتلقى رسائل بريد إلكتروني متكررة
• يتضمن البريد الإلكتروني عدد استخدامك الحالي والحد ورابطاً مباشراً للترقية
• يتلقى مالك الحساب فقط رسائل تنبيه الاستخدام

TIP

راقب استخدامك برمجياً بالاستدعاء GET /v1/usage قبل بدء عمليات دفعية كبيرة. هذا يتيح لك التحقق مما إذا كان لديك سعة متبقية كافية.

حدود معدل الطلبات

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

• أضف تأخيرات بين الطلبات الدفعية. عند معالجة العديد من الملفات، أضف تأخيراً صغيراً (مثال: 200--500 مللي ثانية) بين استدعاءات API المتتالية بدلاً من إطلاقها جميعاً في وقت واحد.
• استخدم حدود التزامن. إذا كنت تعالج الملفات بالتوازي، حدد التزامن بـ 5--10 طلبات متزامنة.
• راقب أوقات الاستجابة. إذا زادت أوقات الاستجابة بشكل ملحوظ، قلّل معدل طلباتك.

// Process files with controlled concurrency
async function processFilesWithLimit(files: string[], concurrency = 5) {
  const results = [];

  for (let i = 0; i < files.length; i += concurrency) {
    const batch = files.slice(i, i + concurrency);

    const batchResults = await Promise.all(
      batch.map((file) => runExtraction("tmpl_abc123", file, encode(file)))
    );

    results.push(...batchResults);

    // Brief pause between batches
    if (i + concurrency < files.length) {
      await new Promise((resolve) => setTimeout(resolve, 500));
    }
  }

  return results;
}