Rapid Translate واجهة برمجة التطبيقات (API)

مقدمة

ال Rapid Translate تتيح واجهة برمجة التطبيقات (API) لتطبيقك إرسال المستندات للترجمة المعتمدة، واسترجاع أحدث المعلومات حول حالة الطلب والأسعار، واستلام الملفات النهائية - دون الحاجة إلى تدخل فريقك في عملية الدفع. وهي مصممة خصيصًا للشركات التي تقدم طلبات الترجمة نيابةً عن عملائها.

جميع الطلبات موجهة إلى https://www.rapidtranslate.org/api/v1 عبر بروتوكول HTTPS. الطلبات والاستجابات بتنسيق JSON، باستثناء عملية إنشاء الطلب، التي يتم فيها تحميل الملفات بتنسيق JSON. multipart/form-dataتُعاد جميع المبالغ على النحو التالي: سنتات عددية صحيحة بالدولار الأمريكي، وجميع الطوابع الزمنية بتوقيت UTC ISO-8601.

مجموعة ساعي البريد

هل تفضل تصفح واجهة برمجة التطبيقات قبل كتابة أي كود؟ تحتوي مجموعة Postman الخاصة بنا على جميع نقاط النهاية مهيأة مسبقًا - بما في ذلك المصادقة، ونصوص الأمثلة، ومعلمات الاستعلام.

قم بتنزيل مجموعة بوستمان

1. في برنامج Postman، اختر ملف ← استيراد وحدد الملف الذي تم تنزيله.
2. افتح المجموعة المتغيرات وضبط مفتاح API إلى مفتاح من إعدادات الأعمال ← مفاتيح واجهة برمجة التطبيقات.
3. (اختياري) مجموعة baseUrl بالنسبة لبيئتك — يتم ضبطها افتراضياً على بيئة الإنتاج.
4. أرسل أي طلب. استخدم مفتاح Sandbox للاختبار دون تقديم طلبات مدفوعة.

المصادقة

قم بمصادقة كل طلب باستخدام مفتاح API السري الخاص بك كرمز مميز، واطلب استجابة بتنسيق JSON. كلا العنوانين مطلوبان:

المصادقة: حامل مفتاح API الخاص بك، القبول: تطبيق/json

يمكنك إنشاء المفاتيح وتدويرها في لوحة التحكم ضمن إعدادات الأعمال ← مفاتيح واجهة برمجة التطبيقات . تُعرض المفاتيح مرة واحدة عند إنشائها وتُخزن مشفرةً - إذا فقدت مفتاحًا، فقم بتدويره. ينتمي كل مفتاح إلى وضع واحد (الوضع الفعلي أو وضع الاختبار) ويحمل مجموعة ثابتة من النطاقات.

النطاقات

تتطلب كل نقطة نهاية قدرة محددة على المفتاح. المفتاح الذي يفتقر إلى النطاق المطلوب يُرجع قيمة خاطئة. 403 نطاق محظور.

وضع الاختبار والوضع التجريبي

وضع الاختبار هو خاصية للمفتاح ، وليس لحسابك. يعمل مفتاح Sandbox في بيئة محاكاة كاملة، بينما يقوم مفتاح Live بوضع طلبات حقيقية قابلة للفوترة. يمكنك استخدام كليهما في الوقت نفسه.

تستخدم طلبات بيئة الاختبار نفس عمليات التحقق من الصحة، وتعيين الحقول، والتسعير الحقيقي، ولكنها تتجاوز تخزين الملفات، والتعرف الضوئي على الأحرف، والتنفيذ. عند الإنشاء، يمر طلب بيئة الاختبار تلقائيًا بدورة حياته (عملية → مكتملة)، وإطلاق نفس روابط الويب مثل الطلب المباشر، وأخيراً تسليم مستند نموذجي ثابت.

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

• الوضع المباشر: صحيح — طلب حقيقي قابل للفوترة
• الوضع المباشر: خطأ — صندوق الاختبار / طلب تجريبي

حدود المعدل

يتم تحديد عدد الطلبات المسموح بها لكل مؤسسة. الحد الافتراضي هو 120 طلبًا في الدقيقةتجاوز هذا الحد يؤدي إلى إرجاع 429 معدل محدودأعد المحاولة بعد فترة توقف قصيرة. إذا كانت عملية التكامل لديك تتطلب حدًا أعلى، فاتصل بنا. support@rapidtranslate.org.

الردود

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

مورد واحد

{
  "data": {
    "id": "9b1c...-uuid",
    "reference": "APO-10432",
    "status": "processing",
    "total": 11270,
    "currency": "USD"
  }
}

قائمة مرقمة إلى صفحات

{
  "data": [ ... ],
  "meta": {
    "current_page": 1,
    "per_page": 25,
    "total": 134,
    "last_page": 6
  }
}

أخطاء

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

{
  "message": "The given data was invalid.",
  "error_code": "validation_failed",
  "errors": {
    "source_language": ["The selected source language is invalid."]
  }
}

حالة الطلبات

طلب حالة تتبع دورة حياة مستقرة. هذه القيم الخمس هي أيضاً القيم المقبولة من قبل حالة تفعيل الفلتر قائمة الطلبات:

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

قيم الحقول

المجموعات الثابتة المقبولة عند إنشاء الطلب.

أنواع الترجمة

التف حوله

طرق التوصيل

روابط الويب

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

الفعاليات

ظرف

كل شحنة تأتي في نفس الظرف: حدث كتلة (بما في ذلك) الوضع المباشر) وحدث محدد بيانات حاجز.

{
  "event": {
    "type": "order_status",
    "id": "evt_9b1c...",
    "livemode": true,
    "sent_at": "2026-08-28T10:20:00+00:00"
  },
  "data": {
    "order": {
      "id": "9b1c2d3e-...-uuid",
      "reference": "APO-10432",
      "status": "completed"
    }
  }
}

ال تسليم المستندات يُضيف الحدث وثائق مصفوفة (كل منها يحتوي على) اسم, رابط التنزيل, إصدار, حالة) و أ منفذ الرابط. الـ مراجعة العميل يُضيف الحدث قائمة مفصلة التسعير كتلة و الإجراءات.الموافقة كائن يحتوي على عنوان URL المطلوب استدعاؤه.

التحقق من التوقيعات

يتم توقيع كل طلب حتى تتمكن من التأكد من أنه صادر من Rapid Translate نرسل ثلاثة رؤوس:

احسب التوقيع المتوقع كـ HMAC-SHA256 للسلسلة "{timestamp}.{raw_request_body}" باستخدام سر توقيع webhook الخاص بك، ثم قارنه بقيمة الترويسة:

// PHP
$expected = 'sha256=' . hash_hmac(
    'sha256',
    $timestamp . '.' . $rawBody,
    $webhookSecret
);
$valid = hash_equals($expected, $signatureHeader);

Node.js (Express) — قم بتثبيت المسار باستخدام محلل نص خام بحيث يتم الحفاظ على البايتات الدقيقة:

// app.use('/webhooks/rapidtranslate', express.raw({ type: 'application/json' }))
const crypto = require('crypto');

const timestamp = req.get('X-RapidTranslate-Timestamp');
const received  = req.get('X-RapidTranslate-Signature'); // "sha256=..."
const rawBody   = req.body;                               // Buffer, untouched

const expected = 'sha256=' + crypto
  .createHmac('sha256', WEBHOOK_SECRET)
  .update(`${timestamp}.${rawBody}`)
  .digest('hex');

const valid = received &&
  crypto.timingSafeEqual(Buffer.from(received), Buffer.from(expected));

ثلاثة أشياء تُوقع الناس في الخطأ:

• ال توقيع X-RapidTranslate يحمل العنوان sha256= البادئة. إما قارنها بـ 'sha256=' + yourHmac (كما سبق) أو قم بإزالة البادئة قبل المقارنة - لا تقم بمطابقة القيمة السداسية العشرية المجردة مع العنوان بأكمله.
• قم بتشفير نص الطلب الخام تمامًا كما تم استلامه. إعادة تسلسل JSON المُحلل يُغير المسافات البيضاء وترتيب المفاتيح، لذا لن تتطابق التوقيعات - اقرأ النص قبل أن يقوم أي برنامج وسيط JSON بتحليله.
• قارن في زمن ثابت (hash_equals / crypto.timingSafeEqual), أبداً مع == أو ===.

ال {الطابع الزمني} يُعد جزءًا من السلسلة الموقعة، لذا اقرأه من الترويسة وأضفه قبل التجزئة. كما يتيح لك رفض عمليات التسليم القديمة أو المعاد إرسالها، مثل أي طابع زمني أقدم من خمس دقائق.

تُعاد محاولات التسليم الفاشلة مع تراجع تدريجي (حتى 5 محاولات). رد بـ 2xx يتم إرسال إشعار استلام إلى الحالة.