البدء

يرشدك هذا الدليل خلال إعداد بيئتك وإجراء أول طلب استخراج باستخدام DocMap API.

المتطلبات الأساسية

قبل أن تبدأ، تأكد من أن لديك:

1. حساب DocMap -- سجّل في docmap.io إذا لم تكن قد فعلت ذلك بعد.
2. قالب استخراج واحد على الأقل -- أنشئ قالباً في لوحة التحكم يحدد الحقول التي تريد استخراجها من مستنداتك.

TIP

تحدد القوالب بنية البيانات التي تريد استخراجها. على سبيل المثال، قد يتضمن قالب الفاتورة حقولاً مثل vendor_name وinvoice_number وtotal_amount ومصفوفة line_items. يمكنك إنشاء القوالب وإدارتها من لوحة التحكم قبل إجراء أي استدعاءات API.

عنوان URL الأساسي

تُرسل جميع طلبات API إلى:

https://api.docmap.io

جميع نقاط النهاية مسبوقة بـ /v1/. على سبيل المثال، نقطة نهاية الاستخراج هي:

https://api.docmap.io/v1/extractions/run

إنشاء مفتاح API

1. انتقل إلى لوحة التحكم > الإعدادات > مفاتيح API.
2. انقر على إنشاء مفتاح API.
3. أعطِ مفتاحك اسماً وصفياً (مثل "خادم الإنتاج" أو "التطوير المحلي").
4. اختر فترة انتهاء الصلاحية.
5. انسخ المفتاح فوراً -- يُعرض مرة واحدة فقط ولا يمكن استرجاعه لاحقاً.

WARNING

خزّن مفتاح API الخاص بك بشكل آمن. سيُعرض مرة واحدة فقط عند الإنشاء. إذا فقدته، ستحتاج إلى إنشاء مفتاح جديد.

سيكون مفتاح API الخاص بك بتنسيق dm_live_... ويُستخدم في ترويسة Authorization لكل طلب.

طلبك الأول

تحقق من إعدادك عن طريق فحص نقطة نهاية صحة API:

curl

curl https://api.docmap.io/health

TypeScript

const res = await fetch('https://api.docmap.io/health')
const data = await res.json()
console.log(data) // { status: "ok" }

Python

import requests
res = requests.get('https://api.docmap.io/health')
print(res.json())  # {"status": "ok"}

إذا كان كل شيء يعمل، ستتلقى:

{ "status": "ok" }

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

مع مفتاح API الخاص بك وقالب جاهز، يمكنك استخراج البيانات المنظمة من ملف PDF. قم بتشفير ملف PDF الخاص بك كسلسلة base64 وأرسله إلى نقطة النهاية /v1/extractions/run.

curl

curl -X POST https://api.docmap.io/v1/extractions/run \
  -H "Authorization: Bearer dm_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "templateId": "your-template-id",
    "fileName": "invoice.pdf",
    "pdfBase64": "JVBERi0xLjQ...",
    "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: 'your-template-id',
    fileName: 'invoice.pdf',
    pdfBase64: 'JVBERi0xLjQ...', // base64-encoded PDF
    mimeType: 'application/pdf',
  }),
})

const data = await response.json()
console.log(data)

Python

import requests
import base64

api_key = "dm_live_your_api_key"

# Read and encode the PDF
with open("invoice.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": "your-template-id",
        "fileName": "invoice.pdf",
        "pdfBase64": pdf_base64,
        "mimeType": "application/pdf",
    },
)

print(response.json())

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

يُرجع الاستخراج الناجح البيانات المستخرجة المطابقة لحقول القالب الخاص بك:

{
  "id": "ext_abc123",
  "templateId": "your-template-id",
  "fileName": "invoice.pdf",
  "status": "completed",
  "data": {
    "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
      }
    ]
  },
  "createdAt": "2024-11-20T14:30:00.000Z"
}

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

راقب استخدام API الخاص بك للبقاء ضمن حدود خطتك:

curl

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

TypeScript

const res = await fetch('https://api.docmap.io/v1/usage', {
  headers: { 'Authorization': `Bearer ${apiKey}` },
})
const usage = await res.json()
console.log(usage)

Python

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

الخطوات التالية

الآن بعد أن أجريت أول استخراج لك، استكشف بقية الوثائق:

• المصادقة -- تعرف على مفاتيح API وأفضل ممارسات الأمان.
• مرجع API -- المرجع الكامل لجميع نقاط النهاية المتاحة.