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

node --env-file=.env translate-text.mjs input.txt Spanish translated.txt
node --env-file=.env translate-text.mjs input.txt Spanish translated.txt --start

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

{
  "version": "document-ir/8",
  "format": "txt",
  "fingerprint": "f8c3bf62a9aa3e6fc1619c250e48abe7519373d3edf41be62eb5dc45199af2ef",
  "sourceLanguage": "auto",
  "targetLanguage": "Spanish",
  "segments": [
    {
      "id": "s0",
      "text": "Hello, world."
    }
  ]
}

POST /api/v1/quotes?output=best-effort-v1

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

{
  "quoteId": "<quote id>",
  "idempotencyKey": "my-document-0001",
  "payload": {
    "version": "document-ir/8",
    "format": "txt",
    "fingerprint": "f8c3bf62a9aa3e6fc1619c250e48abe7519373d3edf41be62eb5dc45199af2ef",
    "sourceLanguage": "auto",
    "targetLanguage": "Spanish",
    "segments": [
      {
        "id": "s0",
        "text": "Hello, world."
      }
    ]
  }
}

GET /api/v1/translations/JOB_ID/result
Authorization: Bearer doctr_...

{
  "version": "document-ir/8",
  "jobId": "<job id>",
  "fingerprint": "f8c3bf62a9aa3e6fc1619c250e48abe7519373d3edf41be62eb5dc45199af2ef",
  "targetLanguage": "Spanish",
  "segments": [
    {
      "id": "s0",
      "text": "Hola, mundo."
    }
  ],
  "mock": false
}

اقتباس واحد باستخدام cURL

احفظ JSON الخاص بعرض السعر أعلاه باسم payload.json، واضبط DOCUMENT_TRANSLATOR_API_KEY في الصَدَفة. يطلب هذا الأمر عرض سعر فقط. لبدء الترجمة، أرسل JSON الخاص بالبدء مع معرّف عرض السعر المُعاد والبيانات المطابقة تمامًا إلى نقطة نهاية translations.

curl https://document-translator.com/api/v1/quotes \
  -H "Authorization: Bearer $DOCUMENT_TRANSLATOR_API_KEY" \
  -H "Content-Type: application/json" \
  --data-binary @payload.json

في PowerShell، استخدم curl.exe و$env:DOCUMENT_TRANSLATOR_API_KEY؛ واكتب الأمر في سطر واحد بدلًا من استخدام علامة الشرطة المائلة العكسية لمتابعة الأمر الظاهرة أعلاه.

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

يحجز كل مستند عبر API رصيدًا واحدًا من الحساب ضمن الحدود المقررة. لا تُحصّل رسوم المهام الصارمة إلا بعد التحقق من جاهزيتها؛ وتُحرَّر الحجوزات للمهام الفاشلة أو الملغاة غير المكتملة. مع مخرجات أفضل جهد، قد تُستخدم الأرصدة المتفق عليها لمعالجة فجوات بسيطة، بينما تُحرَّر الأرصدة عند وجود فجوات كبيرة أو أخطاء حرجة. راجع outcome.creditOutcome وoutcome.completion بدلًا من افتراض أن كل نتيجة جاهزة قد احتُسبت رسومها.

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

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

GET /api/v1/translations?requestKey=IDEMPOTENCY_KEY&quoteId=QUOTE_ID
DELETE /api/v1/translations?requestKey=IDEMPOTENCY_KEY&quoteId=QUOTE_ID

أعِد استخدام معرّف عرض السعر والبيانات ومفتاح منع التكرار نفسها بعد بدء غير مؤكد. تُعيد المحاولات المتطابقة المهمة الحالية دون رسوم إضافية. وتُعيد البيانات المعدّلة أو إعادة استخدام المفتاح لعرض سعر آخر الخطأ 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

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

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

queued → processing → ready
                   ↘ failed / cancelled / expired

{"jobs":[{"id":"<job id>","state":"processing","completedChunks":1,"totalChunks":2}]}

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

PUT /api/v1/translations/{id}/files/docx
X-Download-Kind: reading-copy
Content-Type: application/vnd.openxmlformats-officedocument.wordprocessingml.document
Content-Length: {bytes}

{binary DOCX body}

GET /api/v1/translations/{id}

{"savedFormats":["docx"],"savedDownloads":[{"format":"docx","kind":"reading-copy"}]}

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

PUT /api/v1/translations/{id}/manifest
Content-Type: application/json
Content-Length: {bytes, maximum 2 MiB}

{"version":1,"parserVersion":"document-ir/8","fingerprint":"{original SHA-256}","ocr":[]}

PUT /api/v1/translations/{id}/source
Content-Type: application/octet-stream
Content-Length: {bytes, maximum 25 MiB}
X-Parser-Version: document-ir/8
X-Source-SHA256: {original SHA-256}

{unchanged original bytes}

GET /api/v1/translations/{id}
// sourceBackup is available only after both saves
GET /api/v1/translations/{id}/manifest
GET /api/v1/translations/{id}/source

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

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

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

n8n وMake وZapier

استخدم خطوة طلب HTTP مع بيانات اعتماد Bearer سرية. استخرج النص أولًا، ثم أرسل حمولة JSON إلى نقطة نهاية عرض السعر باستخدام POST، وبعدها أرسل معرّف عرض السعر والحمولة ومفتاح idempotency ثابتًا بطول 16–80 حرفًا إلى نقطة نهاية translations باستخدام POST. أضف فترة انتظار، ثم أرسل طلب GET إلى الحالة حتى تصبح جاهزة، واجلب النتيجة وأعِد بناء النص المترجم أو احفظه. احتفظ بمعرّف عرض السعر ومفتاح إعادة المحاولة في سجل سير العمل. لا حاجة إلى موصّل مخصص أو تحميل متعدد الأجزاء.

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

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

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

نحتفظ بنسخة خاصة من مستندك الأصلي حتى 24 ساعة بعد اكتمال الترجمة لتتمكن من استعادة التنزيلات. يمكنك حذفها قبل ذلك بحذف الترجمة. لا يُرسل إلى مزود الترجمة سوى النص المستخرج. تفاصيل الخصوصية