API · Dleex

اطلب الخدمات من موقعك الإلكتروني أو متجرك أو برنامجك النصي: اعرض الخدمات وأسعارها، وقدّم الطلبات مع وصف المهمة، وتابعها، واستلم النتائج. إنها الخدمة نفسها الموجودة على الموقع، لذا تظهر الطلبات المقدَّمة عبر API في حسابك أيضًا.

البدء

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

أرسل المفتاح مع كل طلب HTTP:

Authorization: Bearer dlx_your_key

عنوان API: https://dleex.com/api/v1. طلبات HTTP والاستجابات بصيغة JSON. الأسعار والمبالغ أعداد صحيحة بالسنت الأمريكي: 1500 تعني 15.00 دولارًا.

الخدمات

يعرض GET /services ما يمكن طلبه.

curl https://dleex.com/api/v1/services -H "Authorization: Bearer dlx_your_key"

[
  {
    "service": "seo-article",
    "category": "seo",
    "title": { "en": "SEO article", "ru": "SEO-статья" },
    "linkRequired": false,
    "files": null,
    "script": null,
    "briefQuestions": [
      { "q": { "en": "What is the article about?", "ru": "О чём статья?" }, "hint": { "en": "The topic, or a link to the page.", "ru": "..." } },
      { "q": { "en": "Who will read it?", "ru": "..." } }
    ],
    "packages": [
      { "tier": "basic", "title": { "en": "...", "ru": "..." }, "priceUsdCents": 1500, "days": 2, "revisions": 1 },
      { "tier": "standard", "...": "..." },
      { "tier": "premium", "...": "..." }
    ],
    "addons": [
      {
        "id": 7,
        "title": { "en": "Express delivery", "ru": "Срочное выполнение" },
        "description": null,
        "priceUsdCents": 1000,
        "extraDays": -1,
        "tiers": ["standard", "premium"]
      }
    ]
  }
]

يحدد days المدة التي يستغرقها العمل، وrevisions عدد المرات التي يمكنك فيها طلب تعديل. أما addons فهي إضافات يمكنك طلبها مع الباقات المذكورة في tiers: يُضاف سعر الإضافة إلى سعر الباقة، ويُضاف extraDays إلى مدة تنفيذها (القيمة السالبة تعني تنفيذًا أسرع، ولا تقل المدة أبدًا عن يوم واحد). وتمثل briefQuestions ما تسأل عنه الخدمة بخصوص المهمة، وبعض الأسئلة مصحوب بـ hint؛ أجب عنها في answers عند تقديم الطلب. وتكون القائمة فارغة إذا لم تطرح الخدمة أي أسئلة. وتكون قيمة linkRequired هي true للخدمة التي تُنفَّذ اعتمادًا على ما يفتحه رابط، مثل ملف شخصي أو منشور، أو تسجيل لإضافة ترجمة نصية إليه: يحتاج طلب هذه الخدمة إلى link.

تكون قيمة files هي null للخدمة التي لا تقبل ملفات مع متطلبات الطلب. وفي غير ذلك تبيّن الملفات التي تقبلها الخدمة، مثلًا {"accept": ["image"], "maxFiles": 3, "maxMb": 5, "required": true, "insteadOfLink": false}: الأنواع (image وaudio وvideo)، وعدد الملفات المسموح به مع متطلبات طلب واحدة أو طلب تعديل واحد، والحجم الأقصى لكل ملف بالميغابايت، وما إذا كانت متطلبات الطلب تحتاج إلى ملف واحد على الأقل، وما إذا كان يمكن للملف أن يحل محل link (وتبقى linkRequired حينها true للطلبات المرسلة بدون ملفات). راجع قسم الملفات.

تكون قيمة script هي null للخدمة التي لا تقرأ نصًا بصوت مسموع. أما خدمة التعليق الصوتي فتحدد أطول نص تقرؤه كل باقة، بعدد الأحرف، مثلًا {"maxChars": {"basic": 1000, "standard": 3000, "premium": 9000}}: تحتاج طلباتها إلى script، أي النص المطلوب قراءته حرفيًا. يُقرأ التسجيل بصوت مُركَّب: أينما نشرته، أخبر مستمعيك بأن الصوت مُركَّب (راجع الشروط).

الرصيد

GET /balance

{ "balanceUsdCents": 10000, "currency": "USD" }

تقديم طلب

POST /orders. يُخصم السعر (الباقة والإضافات، مطروحًا منه أي خصم) من الرصيد ويبدأ العمل فورًا.

الحقل
`service`	إلزامي	خدمة من `/services`
`tier`	إلزامي	`basic` أو `standard` أو `premium`
`text`	إلزامي في غياب `answers` و`script` و`awaitBrief`	المهمة: ما المطلوب تنفيذه، حتى 10,000 حرف. مع `script`: طريقة القراءة (النبرة والسرعة وطريقة نطق الأسماء)
`link`	اختياري	رابط إلى الصفحة أو الملف الشخصي أو المنشور، أو إلى تسجيل: رابط مباشر إلى الملف، أو رابط Dropbox أو Yandex Disk. إلزامي حيث تكون `linkRequired` هي `true`
`answers`	اختياري	إجابات عن `briefQuestions` الخاصة بالخدمة: `[{"q": "question", "a": "answer"}]`، حتى 8 إجابات، وكل إجابة حتى 5,000 حرف
`script`	إلزامي حيث لا تكون قيمة `script` في `/services` هي `null`، ومرفوض في غير ذلك	النص المطلوب قراءته بصوت مسموع حرفيًا، حتى `maxChars` الخاص بالباقة (20,000 حرف كحد أقصى، ويُحتسب فاصل السطر حرفًا واحدًا). اترك سطرًا فارغًا بين الفقرات
`locale`	اختياري	لغة النتيجة، `en` أو `ru`. لغة حسابك افتراضيًا
`addons`	اختياري	معرّفات الإضافات من `/services` المتاحة لهذه الباقة، مثلًا `[7]`
`promoCode`	اختياري	رمز ترويجي؛ إذا لم يكن قابلًا للتطبيق، فلن يُقدَّم الطلب (راجع الأخطاء)
`awaitBrief`	اختياري	`true` لإرسال متطلبات الطلب لاحقًا، بعد رفع الملفات: يُدفع ثمن الطلب وينتظر بالحالة `awaiting_brief`. لا ترسل حينها `text` و`link` و`answers` و`script`. راجع الملفات

curl https://dleex.com/api/v1/orders -H "Authorization: Bearer dlx_your_key" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: <your-order-id>" \
  -d '{"service":"seo-article","tier":"basic","text":"An article about trail running shoes, 5 keywords: ..."}'

الترويسة Idempotency-Key اختيارية وتتيح لك تكرار طلب HTTP بأمان؛ ويحتاج كل طلب جديد إلى مفتاح جديد. راجع قسم التكرار الآمن أدناه.

قدّم إما text أو إجابة واحدة على الأقل، أو كليهما؛ وفي التعليق الصوتي يكفي script. اكتب كل سؤال في q كما هو في briefQuestions، بلغة الطلب، وتجاوز الأسئلة التي لا تملك إجابة عنها:

{
  "service": "seo-article",
  "tier": "basic",
  "answers": [
    { "q": "What is the article about?", "a": "Choosing trail running shoes" },
    { "q": "Who will read it?", "a": "Runners moving from road to trail" }
  ]
}

الاستجابة هي الطلب (الحالة 201):

{
  "id": 1042,
  "status": "in_progress",
  "service": "seo-article",
  "tier": "basic",
  "priceUsdCents": 1500,
  "addons": [],
  "discountUsdCents": 0,
  "promoCode": null,
  "locale": "en",
  "text": "An article about trail running shoes...",
  "link": null,
  "answers": [],
  "script": null,
  "fileIds": [],
  "files": [],
  "revisionsLeft": 1,
  "createdAt": "2026-10-16T11:00:00.000Z",
  "dueAt": "2026-10-18T11:00:00.000Z",
  "deliveredAt": null,
  "autoAcceptAt": null,
  "completedAt": null,
  "results": []
}

الملفات

تعمل بعض الخدمات اعتمادًا على ملفات العميل، مثل صور صفحات لكتابتها نصيًا أو تسجيل لإضافة ترجمة نصية إليه: قيمة files الخاصة بها في /services ليست null. تُرفع الملفات إلى طلب ينتظر متطلباته:

قدّم الطلب مع "awaitBrief": true وبدون text وlink وanswers وscript. يُدفع ثمنه فورًا وتكون حالته awaiting_brief؛ وتبدأ مدة التنفيذ مع إرسال متطلبات الطلب.
لكل ملف، أرسل POST /orders/{id}/files مع {"name": "page-1.png", "size": 482113, "mime": "image/png"}: حيث size هو الحجم الدقيق بالبايت، وmime اختياري. الاستجابة (201) هي الملف ومكان رفعه:

{
  "file": { "id": 77, "name": "page-1.png", "mime": "application/octet-stream", "size": 482113, "status": "pending", "used": false, "uploadExpiresAt": "2026-10-16T12:00:00.000Z", "createdAt": "2026-10-16T11:00:00.000Z" },
  "upload": { "url": "https://...", "headers": { "content-type": "application/octet-stream" }, "expiresAt": "2026-10-16T12:00:00.000Z" }
}

أرسل بايتات الملف عبر PUT إلى upload.url مع headers المحددة تمامًا ودون مفتاح API، قبل upload.expiresAt (خلال ساعة):

curl -X PUT "$url" -H "content-type: application/octet-stream" --data-binary @page-1.png

POST /orders/{id}/files/{fileId}/complete. يُرفض مع 422 ويُحذف كل ملف يختلف حجمه عن size أو لا تنتمي بايتاته إلى نوع مذكور في accept: لا عبرة بالاسم ولا بقيمة mime. وفي غير ذلك تكون الاستجابة هي الملف، وحالته الآن checking. بعد بضع ثوانٍ، أو بضع دقائق للتسجيل الطويل، تصبح حالته ready، أو rejected مع السبب في reason، مثلًا recording_no_sound أو file_unreadable. ويبيّن حقل files في الطلب حالة الملفات.
POST /orders/{id}/brief مع text وlink وanswers وscript كما في POST /orders. تُرسل معه الملفات الجاهزة التي لم تُرسل بعد، أو اذكر الملفات المراد إرسالها في fileIds. وما دام أحدها لا يزال checking، تُرفض متطلبات الطلب مع 409 files_not_ready: أرسلها مجددًا بعد قليل. الاستجابة (200) هي الطلب، وحالته الآن in_progress.

يسحب DELETE /orders/{id}/files/{fileId} ملفًا لم يُرسل بعد. يقبل الطلب 5 ملفات كحد أقصى و4 GB إجمالًا؛ ويُحتسب الملف الذي بدأ رفعه إلى أن يكتمل أو يُسحب، كما تُحتسب الملفات المسحوبة أو المرفوضة، لمدة يوم من بدء رفعها، ضمن حد 12 GB مع ملفات الطلب: وبعد تجاوزه يُرفض الرفع مع 409 upload_quota وretryAt، وهو الوقت الذي يُقبل فيه الرفع من جديد. ويقبل الطلب المُسلَّم ملفات لطلب التعديل أيضًا: ارفعها بالطريقة نفسها، ثم أرسل fileIds مع طلب التعديل.

بدون awaitBrief، يُرفض طلب الخدمة التي ملفاتها required مع 400 files_required، ويُرفض مع 400 link_required الطلب المرسل بدون رابط لخدمة يمكن فيها للملف أن يحل محل الرابط.

في الطلب، يسرد files ملفاتك مع status لكل منها، ويسرد fileIds الملفات التي أُرسلت مع متطلبات الطلب. للملف الجاهز url يعمل حتى expiresAt، مثل ملفات النتائج. تُحفظ الملفات لمدة 30 يومًا بعد إغلاق الطلب.

التكرار الآمن

قد تنتهي مهلة طلب HTTP بعد أن يكون الطلب قد قُدِّم بالفعل. لتكرار POST /orders دون الدفع مرتين، أرسل معه الترويسة Idempotency-Key: سلسلة من 1 إلى 255 حرفًا من حروف ASCII القابلة للطباعة تختارها مرة واحدة لكل طلب، مثل UUID أو رقم الطلب في نظامك. وأرسل المفتاح نفسه والمحتوى نفسه عند تكرار طلب HTTP.

curl -i https://dleex.com/api/v1/orders -H "Authorization: Bearer dlx_your_key" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: shop-order-981" \
  -d '{"service":"seo-article","tier":"basic","text":"An article about trail running shoes, 5 keywords: ..."}'

إذا كان قد قُدِّم طلب بهذا المفتاح من قبل، فالاستجابة هي ذلك الطلب بحالته الحالية، مع الحالة 201 وترويسة إضافية. ولا يُخصم أي مبلغ مرة أخرى:

HTTP/1.1 201 Created
Idempotent-Replayed: true

يرتبط المفتاح بطلب HTTP الذي أُرسل معه أول مرة. ويُرفض المفتاح نفسه مع محتوى مختلف، مثل إضافات أخرى أو رمز ترويجي آخر، مع 422 idempotency_key_reused، ولا يُخصم أي مبلغ.
إذا وصلت عدة طلبات HTTP بمفتاح واحد في الوقت نفسه، يُقدَّم طلب واحد وتعيده بقية الطلبات في استجابتها. أما طلب HTTP الذي يضطر إلى الانتظار طويلًا فيُجاب بـ 409 idempotency_key_in_progress ولا يُخصم شيء: كرّره بعد لحظة.
طلب HTTP الذي فشل، مثلًا مع 400 أو 402 أو 404 أو بخطأ في إضافة أو رمز ترويجي، لا يستهلك مفتاحه: صحّحه وأرسله مجددًا بالمفتاح نفسه.
يُحتفظ بالمفتاح لمدة 24 ساعة. وبعد ذلك يُقدِّم المفتاح نفسه طلبًا جديدًا.
المفاتيح منفصلة لكل حساب. وبدون الترويسة يُقدِّم كل طلب HTTP طلبًا جديدًا.

لا يحتاج القبول ومتطلبات الطلب وطلبات التعديل إلى مفتاح. تكرار القبول آمن: بعد اكتمال الطلب، يُجاب التكرار بـ 409 order_not_delivered. وكذلك متطلبات الطلب: بعد قبولها، يُجاب التكرار بـ 409 brief_not_expected وتكون حالة الطلب in_progress. أما طلب التعديل فمختلف: أثناء إعادة تنفيذ العمل يُجاب التكرار بـ 409 order_not_delivered، لكن بعد تسليم العمل المُعاد يطلب التكرار تعديلًا آخر. قبل تكرار طلب تعديل، تحقّق من الطلب باستخدام GET /orders/{id} (status و revisionsLeft).

تتبّع الطلبات

يعيد GET /orders/{id} طلبًا واحدًا، ويعيد GET /orders طلباتك، الأحدث أولًا. وتقبل القائمة status وlimit (من 1 إلى 100، و20 افتراضيًا) وbefore (معرّف طلب، للحصول على طلبات أقدم).

حالة الطلب:

الحالة	المعنى
`awaiting_brief`	قُدِّم مع `awaitBrief`: في انتظار `POST /orders/{id}/brief`
`in_progress`	العمل قيد التنفيذ
`quality_check`	اكتمل العمل ويجري فحصه قبل التسليم
`delivered`	النتيجة جاهزة، راجع `results`. اقبلها أو اطلب تعديلًا قبل `autoAcceptAt`
`revision`	يجري تنفيذ التعديلات التي طلبتها
`completed`	قبلت النتيجة، أو قُبلت تلقائيًا
`refunded`	أُعيد المبلغ إلى رصيدك

تحقّق كل بضع دقائق؛ لا حاجة إلى الاستعلام أكثر من ذلك. عندما تكون حالة الطلب delivered، يحتوي results على العمل: قيمة kind هي text (Markdown) أو report (تقرير تسليم لطلبات وسائل التواصل الاجتماعي) أو files (ملفات للتنزيل، مع ملاحظة اختيارية في body). لكل نتيجة قائمة files، وتكون فارغة للنصوص والتقارير: لكل ملف name وmime وsize بالبايت وurl يعمل حتى expiresAt، أي نحو ساعة. اقرأ الطلب مجددًا للحصول على روابط جديدة. قد يعيد الرابط التوجيه إلى مخزن الملفات، لذا اتبع عمليات إعادة التوجيه، مثلًا curl -L -o result.png "$url"، ولا ترسل مفتاح API معه: الرابط وحده يفتح الملف.

القبول والتعديلات

يقبل POST /orders/{id}/accept النتيجة ويُكمل الطلب.
يطلب POST /orders/{id}/revision مع {"text": "what to change"} تعديلًا، ما دامت قيمة revisionsLeft أكبر من صفر. إذا كانت الخدمة تقبل ملفات، يسرد fileIds الملفات المرفوعة لطلب التعديل؛ وبدونه تُرسل معه الملفات الجاهزة التي لم تُرسل بعد.

إذا لم تقبل الطلب المُسلَّم ولم تطلب تعديله، فإنه يُقبل تلقائيًا بعد 3 أيام من التسليم، في الوقت المحدد في autoAcceptAt (وقيمته null في الحالات الأخرى). ويبدأ احتساب الأيام الثلاثة من جديد مع كل تسليم جديد بعد التعديل. يمكنك أيضًا قبول العمل على الموقع. إذا كتبت في محادثة الطلب على الموقع بعد التسليم، فلن يُقبل الطلب تلقائيًا وتبقى قيمة autoAcceptAt هي null إلى أن تقبله أو نعيد تنفيذ العمل أو نسترد لك المبلغ. وبعد الرد على رسالتك، قد نبدأ احتساب الأيام الثلاثة من جديد أيضًا: وعندها تعرض autoAcceptAt الوقت الجديد.

الأخطاء

تأتي الأخطاء مع حالة HTTP ورمز:

{ "code": "insufficient_balance" }

الحالة	الرمز	المعنى
400	`validation`	حقل مفقود أو غير صحيح؛ ويسرد `fields` الحقول المعنية
400	`link_required`	تحتاج هذه الخدمة إلى `link`
400	`files_required`	تحتاج هذه الخدمة إلى ملف: قدّم الطلب مع `awaitBrief` وارفع الملف
400	`script_required`	تقرأ هذه الخدمة نصًا بصوت مسموع: أرسله في `script`
400	`script_too_long`	`script` أطول مما تقرؤه الباقة؛ وقيمة `maxChars` في الاستجابة هي الحد الأقصى المقبول. لم يُخصم أي مبلغ
400	`script_not_accepted`	لا تقرأ الخدمة أي نص بصوت مسموع (قيمة `script` الخاصة بها في `/services` هي `null`): لا ترسل `script`. لم يُخصم أي مبلغ
400	`files_not_accepted`، `file_too_large`	لا تقبل الخدمة ملفات، أو الملف أكبر من `maxMb` الخاص بها
400	`invalid_idempotency_key`	`Idempotency-Key` فارغ، أو أطول من 255 حرفًا، أو ليس من حروف ASCII القابلة للطباعة
401	`invalid_api_key`	لا يوجد مفتاح، أو المفتاح غير صحيح أو ملغى. تُلغى المفاتيح أيضًا عند تأكيد البريد الإلكتروني غير المؤكد للحساب عبر تسجيل الدخول بحساب Google أو بتعيين كلمة مرور جديدة
402	`insufficient_balance`	الرصيد غير كافٍ؛ لم يُخصم أي مبلغ
404	`package_not_found`، `order_not_found`، `file_not_found`	لا توجد خدمة أو باقة أو طلب أو ملف بهذا المعرّف
409	`order_not_delivered`، `no_revisions_left`	حالة الطلب لا تسمح بهذا الإجراء
409	`brief_not_expected`	الطلب لا ينتظر متطلباته: قُدِّم بدون `awaitBrief`، أو أُرسلت متطلباته من قبل
409	`uploads_closed`	لا تُقبل الملفات إلا عندما ينتظر الطلب متطلباته أو عندما يكون مُسلَّمًا
409	`files_limit`	عدد الملفات أكبر مما تقبله الخدمة مع متطلبات طلب واحدة أو طلب تعديل واحد، أو تجاوز 5 ملفات أو 4 GB للطلب
409	`upload_quota`	مع هذا الملف، يتجاوز مجموع ملفات الطلب (بما فيها المرسلة وعمليات الرفع غير المكتملة) والملفات التي بدأ رفعها خلال اليوم الأخير ثم سُحبت أو رُفضت 12 GB: أعد المحاولة بعد `retryAt`
409	`files_not_ready`، `file_rejected`	ملف مطلوب إرساله لا يزال قيد الفحص، أو رُفض
409	`upload_incomplete`	لم يُرفع أي شيء إلى الرابط بعد: أكمل `PUT`، ثم أكمل الرفع مجددًا
409	`file_in_use`، `file_busy`	أُرسل الملف مع متطلبات الطلب أو مع طلب تعديل ويبقى مع الطلب، أو يجري نقله أثناء فحصه: أعد المحاولة بعد لحظة
409	`addon_unavailable`	إضافة غير متاحة لهذه الخدمة وهذه الباقة
409	`promo_not_found`، `promo_inactive`، `promo_used_up`، `promo_already_used`، `promo_first_order_only`، `promo_min_order`	الرمز الترويجي غير موجود، أو غير نشط حاليًا، أو نفد، أو سبق أن استخدمته، أو مخصص للطلب الأول فقط، أو يتطلب طلبًا بقيمة أكبر. لم يُخصم أي مبلغ
409	`idempotency_key_in_progress`	لا يزال طلب HTTP بهذا `Idempotency-Key` قيد المعالجة؛ كرّره بعد لحظة
410	`upload_expired`، `file_removed`	انتهت صلاحية رابط الرفع قبل رفع أي شيء، أو سحبت الملف: ابدأ عملية رفع جديدة
415	`file_type_not_accepted`	قيمة `mime` المعطاة ليست من نوع تقبله الخدمة
422	`idempotency_key_reused`	سبق استخدام `Idempotency-Key` هذا مع طلب HTTP مختلف
422	`upload_size_mismatch`، `file_type_not_accepted`	حجم الملف المرفوع لا يطابق `size`، أو بايتاته ليست من نوع تقبله الخدمة؛ وقد حُذف
422	`file_unreadable`، `recording_no_sound`، `check_failed`	إكمال ملف رفضه الفحص: لا يمكن فتحه، أو التسجيل بلا صوت، أو تعذّر فحصه. ارفع الملف مجددًا أو ارفع ملفًا آخر
429	`rate_limited`	تجاوز 120 طلب HTTP في الدقيقة بمفتاح واحد؛ انتظر عدد الثواني المذكور في `Retry-After`

استرداد المبالغ

إذا استرددنا لك مبلغ طلب، يعود المبلغ إلى الرصيد وتصبح حالة الطلب refunded.