واجهة API لترجمة المستندات

POST /api/v1/quotes
Authorization: Bearer doctr_...
Content-Type: application/json

{
  "version": "document-ir/1",
  "format": "txt",
  "fingerprint": "<64-character SHA-256 of the source file>",
  "sourceLanguage": "auto",
  "targetLanguage": "Spanish",
  "segments": [
    {
      "id": "s0",
      "text": "Hello, world."
    }
  ]
}

POST /api/v1/translations
Authorization: Bearer doctr_...
Content-Type: application/json

{
  "quoteId": "<quote id>",
  "idempotencyKey": "<stable key, 16–80 letters, digits, underscores or hyphens>",
  "payload": {
    "version": "document-ir/1",
    "format": "txt",
    "fingerprint": "<the same source fingerprint>",
    "sourceLanguage": "auto",
    "targetLanguage": "Spanish",
    "segments": [
      {
        "id": "s0",
        "text": "Hello, world."
      }
    ]
  }
}

// Run this on your server. Keep your API key private.
const response = await fetch(
  'https://document-translator.com/api/v1/quotes',
  {
    method: 'POST',
    headers: {
      Authorization: 'Bearer ' + apiKey,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify(payload)
  }
);
if (!response.ok) throw new Error('Quote request failed');
const quote = await response.json();
// Show the price before starting with the same payload.

أرصدة الترجمة ومفاتيح API

يستهلك كل مستند عبر API رصيدًا واحدًا من حسابك ضمن حدود الرفع. يُحجز الرصيد عند بدء المعالجة ويُخصم عند توفر ترجمة مكتملة والتحقق من صحتها. تعمل أرصدة المكافآت عند التسجيل عبر API؛ أما الحصة المجانية اليومية فمتاحة على الموقع فقط.

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

إعادة المحاولة والطلبات المنقطعة

أعِد استخدام معرّف عرض السعر والبيانات ومفتاح منع التكرار نفسها بعد بدء غير مؤكد. تُعيد المحاولات المتطابقة المهمة الحالية دون رسوم إضافية. وتُعيد البيانات المعدّلة أو إعادة استخدام المفتاح لعرض سعر آخر الخطأ 409. ويُحتفظ ببيانات المهمة ومنع التكرار لمدة سبعة أيام بعد إنهائها.

يمكن إعادة محاولة المهمة الفاشلة القابلة للاستئناف ما دام نصها المصدر متاحًا. تحتفظ إعادة المحاولة بمعرّف المهمة وتعيد استخدام الأجزاء المكتملة. يُسمح بثلاث محاولات معالجة كحد أقصى لكل مهمة. ويمكن إعادة محاولة تنزيل النتيجة عبر نقطة النهاية الخاصة بها من دون بدء ترجمة أخرى.

الاستعلام والتنزيلات

GET /api/v1/translations/JOB_ID
GET /api/v1/translations?ids=JOB_ID_1,JOB_ID_2
GET /api/v1/translations/JOB_ID/result
PUT /api/v1/translations/JOB_ID/files/txt
GET /api/v1/translations/JOB_ID/files/txt
POST /api/v1/translations/JOB_ID/retry
DELETE /api/v1/translations/JOB_ID

تقبل حالة الدفعة عشرة معرّفات كحد أقصى، وتُرجع { jobs: [...] } التي تحتوي فقط على المهام المصرّح بها وغير المحذوفة. تحقّق من الحالة كل خمس ثوانٍ تقريبًا أثناء المعالجة، وكل خمس عشرة ثانية أثناء الانتظار في قائمة الانتظار. بدّل الدفعات بالتناوب عند استعادة أكثر من عشر مهام. أوقف الاستعلام في علامات التبويب المخفية، وتوقف عند الحالات النهائية أو أخطاء التفويض الدائمة.

عندما تصبح الحالة جاهزة، استرجع النتيجة باستخدام تفويض الحساب نفسه. تتضمن النتيجة تعيين المقاطع المترجمة لإعادة إنشاء الملف محليًا. تظل النتائج متاحة لمدة 24 ساعة بعد اكتمالها؛ وتنتهي صلاحية المدخلات غير الناجحة بعد ساعة من إنشائها. تُرجع النتائج منتهية الصلاحية الرمز 410. وتُرجع المهام المحذوفة أو التي يتعذر الوصول إليها الرمز 404.

احفظ ملفًا مكتملًا باستخدام PUT، مع محتواه الثنائي وContent-Length وContent-Type المطابق. الامتدادات المدعومة هي docx وpdf وtxt وmd، ويمكن حفظ ملف واحد لكل تنسيق، بحد أقصى لحجم الملف الناتج يبلغ 50 MB. يؤدي تكرار عملية حفظ ناجحة إلى الإبقاء على الملف الحالي. ينزّل GET الملف المحفوظ؛ وتعرض savedFormats في حالة المهمة التنسيقات المتاحة. يخضع الحفظ والتنزيل لفحوصات ملكية المهمة نفسها، ولا يستهلكان أرصدة إضافية ولا يمدّدان مهلة 24 ساعة.

يلغي DELETE العمل غير المكتمل أو يزيل النصوص والملفات المحفوظة المتاحة. لا يؤدي حذف نتيجة مكتملة إلى استرداد الرصيد أو تمديد فترة تنزيلها. لا تتوفر إشعارات إكمال عبر webhooks في هذا الإصدار.

رصيد الحساب وسجله

GET /api/v1/translations?before=NEXT_CURSOR&limit=5
GET /api/v1/translations?active=1&before=NEXT_CURSOR
GET /api/account/balance

يقتصر سجل العمليات على المالك الحالي ويستخدم مؤشر ترقيم الصفحات المُعاد. تستخدم نقطة نهاية الرصيد جلسة الحساب في المتصفح، وتُعيد الحد الأدنى من معلومات تسجيل الدخول والرصيد. أثناء انتظار Checkout، استعلم عنها كل خمس ثوانٍ لعشر محاولات كحد أقصى، وأوقف الاستعلام عند إخفاء الصفحة، وتوقف عند وصول الرصيد أو تسجيل الخروج من الحساب.

الحدود والأخطاء

• ما يصل إلى 50,000 كلمة مصدر و400,000 حرف مستخرج و12,000 مقطع نصي لكل مستند. كما يحدّ المتصفح حجم الملفات الأصلية إلى 25 MB وملفات PDF إلى 100 صفحة.
• يُسمح بحد أقصى 100 مستند في قائمة الانتظار أو قيد المعالجة لكل حساب. تخضع عمليات البدء وإعادة المحاولة لحدود المعدل نفسها. التزم بوقت Retry-After في استجابات 429 واستخدم تراجعًا تدريجيًا محدودًا عند حدوث إخفاقات مؤقتة.
• تؤدي المقاطع المترجمة المفقودة أو المكررة أو ذات التنسيق غير الصحيح إلى فشل التحقق قبل النشر واحتساب الرسوم. وتُحرر الأرصدة المحجوزة للمهام الفاشلة أو الملغاة غير المكتملة.

تتضمن الأخطاء رسالة ورمزًا للخطأ. يشير 400 إلى إدخال غير صالح، و401 إلى تفويض غير صالح، و402 إلى عدم كفاية الأرصدة، و404 إلى مهمة غير متاحة، و409 إلى تعارض في عرض السعر أو الحالة، و410 إلى انتهاء الصلاحية، و429 إلى تجاوز حد المعدل أو السعة، و503 إلى عدم توفر الخدمة.

تبقى المستندات الأصلية في جهازك. يعالج مزوّد الترجمة النص المستخرج، وتُخزّن الملفات المترجمة المحفوظة بشكل خاص لتنزيلها. تُنظّف وحدة التخزين المؤقتة وفق جدول زمني؛ وتسري أيضًا سياسات الاحتفاظ لدى المزوّد. تفاصيل الخصوصية