تخطّي إلى المحتوى
أنت تستعرض النسخة الجديدة من Puzzel.org العودة إلى الموقع الحالي
واجهة برمجة التطبيقات للمطورين

أنشئ الأنشطة من نظامك الخاص

طلب POST واحد لكل نوع نشاط. أرسل محتواك بصيغة JSON، واحصل في المقابل على نشاط في حسابك على Puzzel.org ورابط يمكنك تسليمه للاعبين أو وضعه داخل iframe.

الرابط الأساسي
https://puzzel.org/api/public/v1
المصادقة
المفتاح والبريد الإلكتروني داخل المحتوى
نقاط النهاية
20 أنواع أنشطة
الحصة
10 أنشطة يوميًا

طلبك الأول

لا شيء لتثبيته ولا مصافحة أولية: أرسل محتوى JSON يتضمّن مفتاحك وبريدك الإلكتروني ومحتواك. يحمل الرد مفتاح النشاط الجديد والرابط الذي يُلعب عليه.

POST crossword 
curl -X POST https://puzzel.org/api/public/v1/crossword \
  -H "Content-Type: application/json" \
  -d '{
  "account_api_key": "YOUR_API_KEY",
  "email": "you@example.com",
  "title": "Crossword",
  "language": "ar",
  "items": [
    {
      "answer": "BANANA",
      "description": "A long yellow fruit",
      "type": "text"
    },
    {
      "answer": "CHERRY",
      "description": "A small red stone fruit",
      "type": "text"
    },
    {
      "answer": "MELON",
      "description": "Big, green outside, sweet inside",
      "type": "text"
    }
  ]
}'
نجاح 
{
  "success": true,
  "id": "-Nq8sample_activity_key",
  "url": "https://puzzel.org/en/crossword/embed?p=-Nq8sample_activity_key",
  "message": "Crossword created successfully"
}

كل مثال في هذه الصفحة هو طلب كامل وقابل للتشغيل. استبدل المفتاح والمحتوى بما يخصّك وسيعمل كما هو.

المصادقة

لا رؤوس (headers) ولا رمز حامل (bearer token). ينتقل بيانا الاعتماد كلاهما داخل محتوى JSON لكل طلب، ولا يُقبل المفتاح إلا للحساب الذي يخصّه ذلك البريد الإلكتروني.

الحقلالنوعما يفعله
account_api_key
مطلوب
string
stringمفتاح API الخاص بحسابك. يُوضع في المحتوى، لا في رأس الطلب.
email
مطلوب
string
stringالعنوان الذي يسجّل به حسابك على Puzzel.org الدخول. لا يكون المفتاح صالحًا إلا معه.

يوجد مفتاحك في قسم الحساب من لوحة التحكم، خلف زر "إظهار".

تسجيل الدخول

تُمنح مفاتيح API عند بدء الاشتراك، لذا لا يملك الحساب المجاني مفتاحًا بعد.

عرض الخطط

تعامل مع المفتاح معاملة كلمة المرور. فهو ينشئ الأنشطة ويستبدلها في حسابك، لذا احتفظ به على الخادم بعيدًا عن أي شيء يمكن للمتصفح قراءته.

محتوى الطلب

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

الحقلالنوعما يفعله
account_api_key
مطلوب
string
stringمفتاح API الخاص بحسابك. يُوضع في المحتوى، لا في رأس الطلب.
email
مطلوب
string
stringالعنوان الذي يسجّل به حسابك على Puzzel.org الدخول. لا يكون المفتاح صالحًا إلا معه.
title
اختياري
string
stringالاسم الذي يحمله النشاط في لوحة التحكم. اتركه فارغًا لتستخدم نقطة النهاية اسمها الاحتياطي الخاص.
language
اختياري
string
stringيحدّد فقط اللغة في الرابط الذي تحصل عليه — ولا يترجم أي شيء ترسله. تقرؤه الكلمات المخفية أيضًا لتبديل حروف الحشو إلى العربية عندما تكون قيمته "ar".
الافتراضي: "en"
activity_key
اختياري
string
stringاتركه فارغًا لإنشاء نشاط جديد. مرّر مفتاح نشاط تملكه بالفعل ليُعاد بناء ذلك النشاط بدلًا من ذلك.

settings كائن يحوي خيارات خاصة بكل نقطة نهاية. الخيارات التي تقرأها كل نقطة نهاية مذكورة معها أدناه؛ وأي شيء آخر تضعه فيها يُتجاهَل.

ما الذي يعود إليك

يردّ الطلب الناجح بالرمز 200 مع مفتاح النشاط الجديد والرابط الذي يُلعب عليه. وأي حالة أخرى تردّ بقيمة success مضبوطة على false ونص خطأ واحد.

نجاح 
{
  "success": true,
  "id": "-Nq8sample_activity_key",
  "url": "https://puzzel.org/en/crossword/embed?p=-Nq8sample_activity_key",
  "message": "Crossword created successfully"
}
فشل 
{
  "success": false,
  "error": "Invalid Email or API Key"
}

الرابط url الذي تحصل عليه هو عرض التضمين. استبدل embed بـ play لفتحه في صفحة كاملة، أو بـ build لفتحه في المحرِّر — يبقى المفتاح بعد p= كما هو.

الإنشاء مقابل التحديث

أرسل activity_key ليُعاد بناء النشاط الذي يمثّله في مكانه: يُستبدَل محتواه، ويُحدَّث اسمه وختم نسخته، ويبقى المفتاح نفسه كما هو — فتظل الروابط وأدوات التضمين التي شاركتها من قبل تعمل. أما النتائج ومكان المجلد وكل إعداد لا تكتبه نقطة النهاية بنفسها فتبقى كما كانت.

activity_key 
{
  "account_api_key": "YOUR_API_KEY",
  "email": "you@example.com",
  "activity_key": "-Nq8sample_activity_key",
  "title": "Fruit crossword, week 2",
  "items": [
    {
      "answer": "BANANA",
      "description": "A long yellow fruit",
      "type": "text"
    },
    {
      "answer": "CHERRY",
      "description": "A small red stone fruit",
      "type": "text"
    },
    {
      "answer": "MELON",
      "description": "Big, green outside, sweet inside",
      "type": "text"
    }
  ]
}
  • يُطبَّق title في كل تحديث، بما في ذلك قيمته الافتراضية — اتركه فارغًا ليُعاد تسمية النشاط باسم نقطة النهاية الاحتياطي.
  • تُعاد كتابة كتل الإعدادات التي تكتبها نقطة النهاية بنفسها من الصفر، لذا يعيد التحديث أيضًا ضبطها على القيم التي ترسلها، أو على القيم الافتراضية لنقطة النهاية.
  • لا يمكنك تحديث إلا الأنشطة التي يملكها حسابك. مفتاح حساب آخر يردّ بالرمز 403.
  • يكلّف التحديث مثل الإنشاء تمامًا: طلبًا واحدًا يُخصَم من حصة اليوم.

حد معدل الطلبات

10
10 أنشطة لكل حساب يوميًا

يُحتسَب كل طلب ناجح، سواء كان إنشاءً أو تحديثًا. وإذا تجاوزت الحد، يردّ الطلب التالي بالرمز 429 حتى تُصفَّر العدّادات.

تُصفَّر العدّادات مرة واحدة يوميًا بمهمة مجدولة، لا وفق نافذة متحركة مدتها 24 ساعة.

الأخطاء

تصل الأخطاء دائمًا بصيغة JSON بالحقلين نفسهما، ولا تصل أبدًا كصفحة HTML. نص الخطأ مكتوب ليقرأه إنسان — فهو يسمّي الحقل أو الحد الذي فشل.

الحالةما يعنيه
400
Bad Request
شيء ما في المحتوى مفقود أو غير صحيح الصياغة أو خارج النطاق المسموح. تسمّي الرسالة الحقل المعني.
401
Unauthorized
البريد الإلكتروني غير معروف، أو المفتاح لا يخصّ ذلك الحساب.
403
Forbidden
activity_key الذي أرسلته يخصّ حسابًا آخر.
429
Too Many Requests
استُنفدت حصة اليوم. تُصفَّر مرة واحدة يوميًا.
500
Server Error
لم يتمكّن المولّد من بناء لغز مما أرسلته — غالبًا بسبب قلة الكلمات، أو كلمات يتعذّر ترتيبها معًا.

نقاط النهاية

مسار واحد لكل نوع نشاط، جميعها POST، وجميعها تحت الرابط الأساسي نفسه. تسرد كل واحدة المحتوى الذي تحتاجه، والإعدادات التي تقرؤها، وطلبًا يمكنك تشغيله.

الكلمات والحروف

الكلمات المتقاطعة

يشابك إجاباتك في شبكة ويرقّم التعريفات نيابة عنك.

#
POST /api/public/v1/crossword على الأقل 2 عناصر في items
المحتوى

مصفوفة من الكلمات. يقرن كل عنصر الإجابة بالتعريف الذي يشير إليها.

تعود إلى الاسم الاحتياطي "Crossword API"

جدير بالمعرفة
  • تُستبعَد الإجابات الأقصر من حرفين قبل بناء الشبكة، ويجب أن يتبقى منها اثنتان على الأقل.
  • تُكتب الإجابات بأحرف كبيرة ويحصل المولّد على عشرين محاولة لترتيبها. وإن تعذّر عليه وضع كلمة واحدة يردّ الطلب بالرمز 500.
طلب مثال
POST crossword 
curl -X POST https://puzzel.org/api/public/v1/crossword \
  -H "Content-Type: application/json" \
  -d '{
  "account_api_key": "YOUR_API_KEY",
  "email": "you@example.com",
  "title": "Crossword",
  "language": "ar",
  "items": [
    {
      "answer": "BANANA",
      "description": "A long yellow fruit",
      "type": "text"
    },
    {
      "answer": "CHERRY",
      "description": "A small red stone fruit",
      "type": "text"
    },
    {
      "answer": "MELON",
      "description": "Big, green outside, sweet inside",
      "type": "text"
    }
  ]
}'
نجاح 
{
  "success": true,
  "id": "-Nq8sample_activity_key",
  "url": "https://puzzel.org/en/crossword/embed?p=-Nq8sample_activity_key",
  "message": "Crossword created successfully"
}
افتح المحرِّر العودة إلى الأعلى

الكلمات المخفية

يخفي كلماتك في شبكة حروف، بالاتجاهات والشكل اللذين تختارهما.

#
POST /api/public/v1/wordseeker على الأقل 2 عناصر في items
المحتوى

مصفوفة من الكلمات. يصبح نص التعريف قائمة الكلمات التي يعمل عليها اللاعبون.

تعود إلى الاسم الاحتياطي "Wordseeker API"

جدير بالمعرفة
  • تُستبعَد الإجابات الأقل من حرفين، وتُكتب كل إجابة بأحرف كبيرة قبل إدراجها في الشبكة.
  • تُحشى الشبكة بحروف لاتينية ما لم تكن قيمة language هي "ar"، التي تبدّل الحشو إلى العربية.
الإعدادات التي تقرؤها
الحقلالنوعما يفعله
hidden_solution
اختياري في settings
string
stringتتهجّى الحروف المتبقية هذه القيمة. كما يخبر ضبطها المولّد بترتيب الحل أولًا بدلًا من حشو أكبر عدد ممكن من الكلمات.
directions
اختياري في settings
string[]
string[]الاتجاهات التي يمكن أن تسير فيها الكلمة. اتركها فارغة لتسير الكلمات شرقًا وجنوبًا شرقيًا وجنوبًا فقط.
واحد من westeastnorthsouthnorthwestnortheastsouthwestsoutheast
الافتراضي: ["east", "southeast", "south"]
template
اختياري في settings
string
stringيقصّ الشبكة على شكل معيّن بدلًا من تركها مربّعة.
واحد من squarecirclecrossdiamondpyramidsmileystarcross_plus
طلب مثال
POST wordseeker 
curl -X POST https://puzzel.org/api/public/v1/wordseeker \
  -H "Content-Type: application/json" \
  -d '{
  "account_api_key": "YOUR_API_KEY",
  "email": "you@example.com",
  "title": "Wordseeker",
  "language": "ar",
  "items": [
    {
      "answer": "BANANA",
      "description": "A long yellow fruit",
      "type": "text"
    },
    {
      "answer": "CHERRY",
      "description": "A small red stone fruit",
      "type": "text"
    },
    {
      "answer": "MELON",
      "description": "Big, green outside, sweet inside",
      "type": "text"
    }
  ],
  "settings": {
    "hidden_solution": "FRUIT",
    "directions": [
      "east",
      "south",
      "southeast"
    ],
    "template": "square"
  }
}'
نجاح 
{
  "success": true,
  "id": "-Nq8sample_activity_key",
  "url": "https://puzzel.org/en/wordseeker/embed?p=-Nq8sample_activity_key",
  "message": "Wordseeker created successfully"
}
افتح المحرِّر العودة إلى الأعلى

الأكروستيك

يرصّ إجاباتك بحيث يتهجّى عمود واحد كلمة مخفية.

#
POST /api/public/v1/acrostic على الأقل 1 عناصر في items
المحتوى

مصفوفة من الكلمات. يجب أن توفّر مجتمعةً كل حرف من الكلمة المخفية.

تعود إلى الاسم الاحتياطي "Acrostic API"

جدير بالمعرفة
  • إذا تعذّر على الإجابات توفير الحروف التي يحتاجها الحل، يردّ الطلب بالرمز 500 بدلًا من حفظ شبكة غير مكتملة.
  • يعيد المولّد ترتيب إجاباتك ليعمل العمود، لذا فالترتيب الذي ترسله ليس الترتيب الذي يراه اللاعبون.
الإعدادات التي تقرؤها
الحقلالنوعما يفعله
hidden_solution
مطلوب في settings
string
stringالكلمة التي يتهجّاها العمود المميَّز. لن تعمل نقطة النهاية هذه من دونها.
طلب مثال
POST acrostic 
curl -X POST https://puzzel.org/api/public/v1/acrostic \
  -H "Content-Type: application/json" \
  -d '{
  "account_api_key": "YOUR_API_KEY",
  "email": "you@example.com",
  "title": "Acrostic",
  "language": "ar",
  "items": [
    {
      "answer": "PEACH",
      "description": "Fuzzy skin, sweet flesh",
      "type": "text"
    },
    {
      "answer": "BANANA",
      "description": "A long yellow fruit",
      "type": "text"
    },
    {
      "answer": "CHERRY",
      "description": "A small red stone fruit",
      "type": "text"
    },
    {
      "answer": "MELON",
      "description": "Big, green outside, sweet inside",
      "type": "text"
    }
  ],
  "settings": {
    "hidden_solution": "PLUM"
  }
}'
نجاح 
{
  "success": true,
  "id": "-Nq8sample_activity_key",
  "url": "https://puzzel.org/en/acrostic/embed?p=-Nq8sample_activity_key",
  "message": "Acrostic created successfully"
}
افتح المحرِّر العودة إلى الأعلى

الكلمات المبعثرة

api_e_word_scramble

#
POST /api/public/v1/word-scramble على الأقل 1 عناصر في items
المحتوى

api_c_word_scramble

تعود إلى الاسم الاحتياطي "Word Scramble API"

جدير بالمعرفة
  • الأنشطة المُنشأة عبر API يكون فيها إعداد خلط الترتيب مفعّلًا دائمًا، لذا فالترتيب الذي ترسله ليس الترتيب الذي يحصل عليه اللاعبون.
الإعدادات التي تقرؤها
الحقلالنوعما يفعله
hidden_solution
اختياري في settings
string
stringكلمة إضافية اختيارية يُدخلها اللاعبون بعد حل البقية.
طلب مثال
POST word-scramble 
curl -X POST https://puzzel.org/api/public/v1/word-scramble \
  -H "Content-Type: application/json" \
  -d '{
  "account_api_key": "YOUR_API_KEY",
  "email": "you@example.com",
  "title": "Word Scramble",
  "language": "ar",
  "items": [
    {
      "answer": "BANANA",
      "description": "A long yellow fruit",
      "type": "text"
    },
    {
      "answer": "CHERRY",
      "description": "A small red stone fruit",
      "type": "text"
    },
    {
      "answer": "MELON",
      "description": "Big, green outside, sweet inside",
      "type": "text"
    }
  ],
  "settings": {
    "hidden_solution": "FRUIT"
  }
}'
نجاح 
{
  "success": true,
  "id": "-Nq8sample_activity_key",
  "url": "https://puzzel.org/en/word-scramble/embed?p=-Nq8sample_activity_key",
  "message": "Word Scramble created successfully"
}
افتح المحرِّر العودة إلى الأعلى

لعبة المشنقة

يحوّل كلماتك أو عباراتك إلى جولات لتخمين الحروف.

#
POST /api/public/v1/hangman على الأقل 1 عناصر في items
المحتوى

مصفوفة من الكلمات أو العبارات القصيرة. التعريف هو التلميح الذي يراه اللاعبون.

تعود إلى الاسم الاحتياطي "Hangman API"

طلب مثال
POST hangman 
curl -X POST https://puzzel.org/api/public/v1/hangman \
  -H "Content-Type: application/json" \
  -d '{
  "account_api_key": "YOUR_API_KEY",
  "email": "you@example.com",
  "title": "Hangman",
  "language": "ar",
  "items": [
    {
      "answer": "BANANA",
      "description": "A long yellow fruit",
      "type": "text"
    }
  ]
}'
نجاح 
{
  "success": true,
  "id": "-Nq8sample_activity_key",
  "url": "https://puzzel.org/en/hangman/embed?p=-Nq8sample_activity_key",
  "message": "Hangman created successfully"
}
افتح المحرِّر العودة إلى الأعلى

Wordle

يصنع لعبة تخمين الكلمة من كل كلمة ترسلها.

#
POST /api/public/v1/wordle على الأقل 1 عناصر في items
المحتوى

مصفوفة من الكلمات. يحصل اللاعبون على جولة واحدة لكل كلمة.

تعود إلى الاسم الاحتياطي "Wordle API"

جدير بالمعرفة
  • يُنشأ وإعداد التحقق من أن التخمينات كلمات حقيقية مفعّل. أوقفه في المحرِّر إذا كانت كلماتك أسماء أو مبتكَرة.
طلب مثال
POST wordle 
curl -X POST https://puzzel.org/api/public/v1/wordle \
  -H "Content-Type: application/json" \
  -d '{
  "account_api_key": "YOUR_API_KEY",
  "email": "you@example.com",
  "title": "Wordle",
  "language": "ar",
  "items": [
    {
      "answer": "MELON",
      "description": "Sweet and green",
      "type": "text"
    },
    {
      "answer": "PEACH",
      "description": "Fuzzy and orange",
      "type": "text"
    }
  ]
}'
نجاح 
{
  "success": true,
  "id": "-Nq8sample_activity_key",
  "url": "https://puzzel.org/en/wordle/embed?p=-Nq8sample_activity_key",
  "message": "Wordle created successfully"
}
افتح المحرِّر العودة إلى الأعلى

تمرين الطباعة

api_e_typing_practice

#
POST /api/public/v1/typing-practice على الأقل 1 عناصر في items
المحتوى

api_c_typing_practice

تعود إلى الاسم الاحتياطي "Typing Practice API"

طلب مثال
POST typing-practice 
curl -X POST https://puzzel.org/api/public/v1/typing-practice \
  -H "Content-Type: application/json" \
  -d '{
  "account_api_key": "YOUR_API_KEY",
  "email": "you@example.com",
  "title": "Typing Practice",
  "language": "ar",
  "items": [
    {
      "answer": "The quick brown fox jumps over the lazy dog",
      "description": "Every letter of the alphabet",
      "type": "text"
    },
    {
      "answer": "Pack my box with five dozen liquor jugs",
      "description": "Another pangram",
      "type": "text"
    }
  ]
}'
نجاح 
{
  "success": true,
  "id": "-Nq8sample_activity_key",
  "url": "https://puzzel.org/en/typing-practice/embed?p=-Nq8sample_activity_key",
  "message": "Typing Practice created successfully"
}
افتح المحرِّر العودة إلى الأعلى

عجلة الحظ

api_e_wheel_of_fortune

#
POST /api/public/v1/wheel-of-fortune على الأقل 1 عناصر في items
المحتوى

api_c_wheel_of_fortune

تعود إلى الاسم الاحتياطي "Wheel of Fortune API"

جدير بالمعرفة
  • يُنشأ بإعداد "إظهار النتيجة في العجلة فقط"، لذا تُقرأ النتيجة من العجلة بدلًا من إعلانها بجانبها.
طلب مثال
POST wheel-of-fortune 
curl -X POST https://puzzel.org/api/public/v1/wheel-of-fortune \
  -H "Content-Type: application/json" \
  -d '{
  "account_api_key": "YOUR_API_KEY",
  "email": "you@example.com",
  "title": "Wheel of Fortune",
  "language": "ar",
  "items": [
    {
      "answer": "Read a page aloud",
      "description": "Segment 1",
      "type": "text"
    },
    {
      "answer": "Name three fruits",
      "description": "Segment 2",
      "type": "text"
    },
    {
      "answer": "Spell it backwards",
      "description": "Segment 3",
      "type": "text"
    }
  ]
}'
نجاح 
{
  "success": true,
  "id": "-Nq8sample_activity_key",
  "url": "https://puzzel.org/en/wheel-of-fortune/embed?p=-Nq8sample_activity_key",
  "message": "Wheel of Fortune created successfully"
}
افتح المحرِّر العودة إلى الأعلى
البطاقات والأزواج

لعبة الذاكرة

بطاقات مقلوبة يقلبها اللاعبون ويطابقونها في أزواج.

#
POST /api/public/v1/memory على الأقل 2 عناصر في items
المحتوى

مصفوفة من الأزواج. يحمل كل زوج البطاقتين اللتين تنتميان معًا.

تعود إلى الاسم الاحتياطي "Memory Game API"

جدير بالمعرفة
  • البطاقة كائن له type وvalue. استخدم "text" للكلمات، أو "image" أو "audio" أو "youtube" أو "link" مع رابط في value، وأضف alt لوصف.
طلب مثال
POST memory 
curl -X POST https://puzzel.org/api/public/v1/memory \
  -H "Content-Type: application/json" \
  -d '{
  "account_api_key": "YOUR_API_KEY",
  "email": "you@example.com",
  "title": "Memory Game",
  "language": "ar",
  "items": [
    {
      "cards": [
        {
          "type": "text",
          "value": "Apple"
        },
        {
          "type": "text",
          "value": "A red fruit"
        }
      ]
    },
    {
      "cards": [
        {
          "type": "text",
          "value": "Banana"
        },
        {
          "type": "text",
          "value": "A yellow fruit"
        }
      ]
    }
  ]
}'
نجاح 
{
  "success": true,
  "id": "-Nq8sample_activity_key",
  "url": "https://puzzel.org/en/memory/embed?p=-Nq8sample_activity_key",
  "message": "Memory game created successfully"
}
افتح المحرِّر العودة إلى الأعلى

لعبة المطابقة

api_e_matching_pairs

#
POST /api/public/v1/matching-pairs على الأقل 2 عناصر في items
المحتوى

api_c_matching_pairs

تعود إلى الاسم الاحتياطي "Matching Game API"

جدير بالمعرفة
  • البطاقة كائن له type وvalue. استخدم "text" للكلمات، أو "image" أو "audio" أو "youtube" أو "link" مع رابط في value، وأضف alt لوصف.
طلب مثال
POST matching-pairs 
curl -X POST https://puzzel.org/api/public/v1/matching-pairs \
  -H "Content-Type: application/json" \
  -d '{
  "account_api_key": "YOUR_API_KEY",
  "email": "you@example.com",
  "title": "Matching Game",
  "language": "ar",
  "items": [
    {
      "cards": [
        {
          "type": "text",
          "value": "Apple"
        },
        {
          "type": "text",
          "value": "A red fruit"
        }
      ]
    },
    {
      "cards": [
        {
          "type": "text",
          "value": "Banana"
        },
        {
          "type": "text",
          "value": "A yellow fruit"
        }
      ]
    }
  ]
}'
نجاح 
{
  "success": true,
  "id": "-Nq8sample_activity_key",
  "url": "https://puzzel.org/en/matching-pairs/embed?p=-Nq8sample_activity_key",
  "message": "Matching pairs game created successfully"
}
افتح المحرِّر العودة إلى الأعلى

بطاقات المراجعة

api_e_flash_cards

#
POST /api/public/v1/flash-cards على الأقل 1 عناصر في items
المحتوى

api_c_flash_cards

تعود إلى الاسم الاحتياطي "Flash Cards API"

جدير بالمعرفة
  • تخزّن نقطة النهاية عدد البطاقات نفسه الذي ترسله، لذا أرسل بطاقتين بالضبط لكل عنصر — الوجه الأمامي ثم الخلفي.
  • البطاقة كائن له type وvalue. استخدم "text" للكلمات، أو "image" أو "audio" أو "youtube" أو "link" مع رابط في value، وأضف alt لوصف.
طلب مثال
POST flash-cards 
curl -X POST https://puzzel.org/api/public/v1/flash-cards \
  -H "Content-Type: application/json" \
  -d '{
  "account_api_key": "YOUR_API_KEY",
  "email": "you@example.com",
  "title": "Flash Cards",
  "language": "ar",
  "items": [
    {
      "cards": [
        {
          "type": "text",
          "value": "Apple"
        },
        {
          "type": "text",
          "value": "A red fruit"
        }
      ]
    },
    {
      "cards": [
        {
          "type": "text",
          "value": "Banana"
        },
        {
          "type": "text",
          "value": "A yellow fruit"
        }
      ]
    }
  ]
}'
نجاح 
{
  "success": true,
  "id": "-Nq8sample_activity_key",
  "url": "https://puzzel.org/en/flash-cards/embed?p=-Nq8sample_activity_key",
  "message": "Flash Cards created successfully"
}
افتح المحرِّر العودة إلى الأعلى

لعبة التصنيف

بطاقات تُصنَّف في الفئة التي تنتمي إليها.

#
POST /api/public/v1/categorize على الأقل 2 عناصر في items
المحتوى

مصفوفة من الفئات، لكل منها اسم والبطاقات التي تنتمي إليها.

تعود إلى الاسم الاحتياطي "Categorize Game API"

جدير بالمعرفة
  • تُحفَظ الفئة المُرسَلة بلا اسم باسم "فئة بلا عنوان"، لذا أرسل اسمًا دائمًا.
  • البطاقة كائن له type وvalue. استخدم "text" للكلمات، أو "image" أو "audio" أو "youtube" أو "link" مع رابط في value، وأضف alt لوصف.
طلب مثال
POST categorize 
curl -X POST https://puzzel.org/api/public/v1/categorize \
  -H "Content-Type: application/json" \
  -d '{
  "account_api_key": "YOUR_API_KEY",
  "email": "you@example.com",
  "title": "Categorize Game",
  "language": "ar",
  "items": [
    {
      "name": "Red fruits",
      "cards": [
        {
          "type": "text",
          "value": "Strawberry"
        },
        {
          "type": "text",
          "value": "Cherry"
        }
      ]
    },
    {
      "name": "Yellow fruits",
      "cards": [
        {
          "type": "text",
          "value": "Banana"
        },
        {
          "type": "text",
          "value": "Lemon"
        }
      ]
    }
  ]
}'
نجاح 
{
  "success": true,
  "id": "-Nq8sample_activity_key",
  "url": "https://puzzel.org/en/categorize/embed?p=-Nq8sample_activity_key",
  "message": "Categorize game created successfully"
}
افتح المحرِّر العودة إلى الأعلى

إعادة الترتيب

تسلسل يجب على اللاعبين إعادة ترتيبه.

#
POST /api/public/v1/reorder على الأقل 1 عناصر في items
المحتوى

مصفوفة من التسلسلات. يحمل كل منها بطاقاته بالترتيب الصحيح.

تعود إلى الاسم الاحتياطي "Reorder Game API"

جدير بالمعرفة
  • يُخزَّن الترتيب الذي ترسله بوصفه الترتيب الصحيح — رقم واحد أولًا.
  • البطاقة كائن له type وvalue. استخدم "text" للكلمات، أو "image" أو "audio" أو "youtube" أو "link" مع رابط في value، وأضف alt لوصف.
طلب مثال
POST reorder 
curl -X POST https://puzzel.org/api/public/v1/reorder \
  -H "Content-Type: application/json" \
  -d '{
  "account_api_key": "YOUR_API_KEY",
  "email": "you@example.com",
  "title": "Reorder Game",
  "language": "ar",
  "items": [
    {
      "name": "From seed to fruit",
      "cards": [
        {
          "type": "text",
          "value": "Plant the seed"
        },
        {
          "type": "text",
          "value": "Water it"
        },
        {
          "type": "text",
          "value": "Watch it grow"
        },
        {
          "type": "text",
          "value": "Pick the fruit"
        }
      ]
    }
  ]
}'
نجاح 
{
  "success": true,
  "id": "-Nq8sample_activity_key",
  "url": "https://puzzel.org/en/reorder/embed?p=-Nq8sample_activity_key",
  "message": "Reorder game created successfully"
}
افتح المحرِّر العودة إلى الأعلى
الأسئلة والإجابات

الاختبار

أسئلة اختيار من متعدد وأسئلة مفتوحة، تُحتسَب نقاطها أثناء تقدّم اللاعبين.

#
POST /api/public/v1/quiz على الأقل 1 عناصر في items
المحتوى

مصفوفة من الأسئلة. تحمل أسئلة الاختيار من متعدد إجاباتها؛ وتحمل الأسئلة المفتوحة الإجابة التي تقبلها.

تعود إلى الاسم الاحتياطي "Quiz API"

جدير بالمعرفة
  • قيمة question_type إما "multiple_choice"، حيث يحمل الخيار الصحيح isCorrect بقيمة true، أو "open_answer"، التي تستخدم correct_answer بدلًا من ذلك. إن تُركت فارغة، تُعامَل كاختيار من متعدد.
  • تمرّر نقطة نهاية الاختبار settings مباشرة كما هي كتل إعدادات النشاط، لذا فهي ليست مكانًا لخيارات متفرقة — عدّل الاختبار في المحرِّر بعد ذلك.
طلب مثال
POST quiz 
curl -X POST https://puzzel.org/api/public/v1/quiz \
  -H "Content-Type: application/json" \
  -d '{
  "account_api_key": "YOUR_API_KEY",
  "email": "you@example.com",
  "title": "Quiz",
  "language": "ar",
  "items": [
    {
      "question_type": "multiple_choice",
      "description": "Which fruit is yellow?",
      "answers": [
        {
          "type": "text",
          "description": "Banana",
          "isCorrect": true
        },
        {
          "type": "text",
          "description": "Cherry",
          "isCorrect": false
        }
      ]
    },
    {
      "question_type": "open_answer",
      "description": "What colour is a lemon?",
      "correct_answer": "Yellow",
      "explanation": "Lemons ripen from green to yellow."
    }
  ]
}'
نجاح 
{
  "success": true,
  "id": "-Nq8sample_activity_key",
  "url": "https://puzzel.org/en/quiz/embed?p=-Nq8sample_activity_key",
  "message": "Quiz created successfully"
}
افتح المحرِّر العودة إلى الأعلى

اللعبة اللوحية

api_e_board_game

#
POST /api/public/v1/board-game على الأقل 1 عناصر في items
المحتوى

api_c_board_game

تعود إلى الاسم الاحتياطي "Board Game API"

جدير بالمعرفة
  • قيمة question_type إما "multiple_choice"، حيث يحمل الخيار الصحيح isCorrect بقيمة true، أو "open_answer"، التي تستخدم correct_answer بدلًا من ذلك. إن تُركت فارغة، تُعامَل كاختيار من متعدد.
الإعدادات التي تقرؤها
الحقلالنوعما يفعله
number_of_tiles
اختياري في settings
number
numberعدد مربّعات اللوح. بين 10 و75.
الافتراضي: 30
game_mode
اختياري في settings
string
stringما إذا كان اللاعبون يتسابقون إلى خط النهاية أم يجمعون عناصر في الطريق.
واحد من race_to_finishcollect_items
الافتراضي: "race_to_finish"
طلب مثال
POST board-game 
curl -X POST https://puzzel.org/api/public/v1/board-game \
  -H "Content-Type: application/json" \
  -d '{
  "account_api_key": "YOUR_API_KEY",
  "email": "you@example.com",
  "title": "Board Game",
  "language": "ar",
  "items": [
    {
      "question_type": "multiple_choice",
      "description": "Which fruit is yellow?",
      "answers": [
        {
          "type": "text",
          "description": "Banana",
          "isCorrect": true
        },
        {
          "type": "text",
          "description": "Cherry",
          "isCorrect": false
        }
      ]
    },
    {
      "question_type": "open_answer",
      "description": "What colour is a lemon?",
      "correct_answer": "Yellow",
      "explanation": "Lemons ripen from green to yellow."
    }
  ],
  "settings": {
    "number_of_tiles": 30,
    "game_mode": "race_to_finish"
  }
}'
نجاح 
{
  "success": true,
  "id": "-Nq8sample_activity_key",
  "url": "https://puzzel.org/en/board-game/embed?p=-Nq8sample_activity_key",
  "message": "Board Game created successfully"
}
افتح المحرِّر العودة إلى الأعلى
الجمل والأرقام

لغز الشيفرة

يحوّل جملة إلى شيفرة يجب فكّها، حرفًا واحدًا في كل مرة.

#
POST /api/public/v1/cryptogram لا تأخذ أي items
المحتوى

جملة واحدة، في حقل sentence. لا تأخذ نقطة النهاية هذه أي items.

تعود إلى الاسم الاحتياطي "Cryptogram API"

جدير بالمعرفة
  • يُتجاهَل أي شيء ترسله في items — يُبنى اللغز من الجملة وحدها.
الإعدادات التي تقرؤها
الحقلالنوعما يفعله
sentence
مطلوب
string
stringالجملة المراد تشفيرها. يفكّها اللاعبون حرفًا حرفًا.
helpers
اختياري في settings
string
stringالحروف التي تُمنح مجانًا كمدخل للحل: لا شيء، أو الأكثر شيوعًا، أو أحرف العلة، أو تلك التي تسردها بنفسك.
واحد من nonemost_commonvowelscustom
الافتراضي: "none"
character_list
اختياري في settings
string
stringالأبجدية التي يُبنى منها الشيفرة. إن تُركت فارغة، يختار التشفير أبجديته الخاصة.
extra_letters
اختياري في settings
string
stringالحروف التي تُمنح عندما تكون قيمة helpers هي "custom". تُتجاهَل في أوضاع المساعدة الأخرى.
hide_unused_characters
اختياري في settings
boolean
booleanيستبعد من المفتاح الحروف التي لا تستخدمها الجملة على الإطلاق.
الافتراضي: false
طلب مثال
POST cryptogram 
curl -X POST https://puzzel.org/api/public/v1/cryptogram \
  -H "Content-Type: application/json" \
  -d '{
  "account_api_key": "YOUR_API_KEY",
  "email": "you@example.com",
  "title": "Cryptogram",
  "language": "ar",
  "sentence": "An apple a day keeps the doctor away",
  "settings": {
    "helpers": "vowels",
    "hide_unused_characters": false
  }
}'
نجاح 
{
  "success": true,
  "id": "-Nq8sample_activity_key",
  "url": "https://puzzel.org/en/cryptogram/embed?p=-Nq8sample_activity_key",
  "message": "Cryptogram created successfully"
}
افتح المحرِّر العودة إلى الأعلى

تمرين الحساب

يخفي جملة خلف عمليات حسابية — حلّ العملية، تكشف الحرف.

#
POST /api/public/v1/calculation لا تأخذ أي items
المحتوى

جملة واحدة، في حقل sentence. لا تأخذ نقطة النهاية هذه أي items.

تعود إلى الاسم الاحتياطي "Calculation Game API"

جدير بالمعرفة
  • إذا كانت القيود ضيقة جدًا بحيث يتعذّر ترميز الجملة، يردّ الطلب بالرمز 400 طالبًا منك تخفيفها بدلًا من حفظ لغز غير مكتمل.
الإعدادات التي تقرؤها
الحقلالنوعما يفعله
sentence
مطلوب
string
stringالجملة التي يكشفها اللاعبون بحل العمليات الحسابية.
difficulty_level
اختياري في settings
number
numberأعلى ناتج يُسمح لعملية حسابية أن تصل إليه.
واحد من 20501001000
الافتراضي: "100"
operators
اختياري في settings
string[]
string[]العمليات التي يمكن أن تظهر. x تعني الضرب، و: تعني القسمة.
واحد من +-x:
الافتراضي: ["+", "-", "x", ":"]
max_operations
اختياري في settings
number
numberعدد العمليات التي يمكن أن تسلسلها عملية حسابية واحدة.
واحد من 123
الافتراضي: 1
number_difficulty
اختياري في settings
number
numberيحدّ الأرقام المفردة داخل العملية الحسابية. من 5 إلى 1000.
الافتراضي: 100
طلب مثال
POST calculation 
curl -X POST https://puzzel.org/api/public/v1/calculation \
  -H "Content-Type: application/json" \
  -d '{
  "account_api_key": "YOUR_API_KEY",
  "email": "you@example.com",
  "title": "Calculation Game",
  "language": "ar",
  "sentence": "Fruit salad for everyone",
  "settings": {
    "difficulty_level": "100",
    "operators": [
      "+",
      "-",
      "x",
      ":"
    ],
    "max_operations": 1,
    "number_difficulty": 100
  }
}'
نجاح 
{
  "success": true,
  "id": "-Nq8sample_activity_key",
  "url": "https://puzzel.org/en/calculation/embed?p=-Nq8sample_activity_key",
  "message": "Calculation game created successfully"
}
افتح المحرِّر العودة إلى الأعلى

السودوكو

يولّد شبكة محلولة، ثم يزيل منها بعض الأرقام.

#
POST /api/public/v1/sudoku لا تأخذ أي items
المحتوى

لا شيء. يصدر اللغز بأكمله من إعداديه الاثنين.

تعود إلى الاسم الاحتياطي "Sudoku API"

جدير بالمعرفة
  • لا ترسل items ولا sentence — الحجم والصعوبة هما المُدخل بأكمله.
  • لا يوفّر المحرِّر إعداد الصعوبة إلا للأحجام 2x3 و3x3 و3x4. أما API فيطبّقه على كل الأحجام، بما فيها 2x2 و4x4.
الإعدادات التي تقرؤها
الحقلالنوعما يفعله
size
اختياري في settings
string
stringحجم الكتلة الواحدة، مكتوبًا كصفوف × أعمدة — يعطي 3x3 الشبكة الكلاسيكية 9x9. لا تتحقق نقطة النهاية إلا من إمكانية تفسيره كرقمين، لذا التزم بالأحجام التي يوفّرها المحرِّر.
واحد من 2x22x33x33x44x4
الافتراضي: "3x3"
difficulty_level
اختياري في settings
string
stringعدد الأرقام المتروكة على اللوح للبدء منها.
واحد من easynormalhard
الافتراضي: "normal"
طلب مثال
POST sudoku 
curl -X POST https://puzzel.org/api/public/v1/sudoku \
  -H "Content-Type: application/json" \
  -d '{
  "account_api_key": "YOUR_API_KEY",
  "email": "you@example.com",
  "title": "Sudoku",
  "language": "ar",
  "settings": {
    "size": "3x3",
    "difficulty_level": "normal"
  }
}'
نجاح 
{
  "success": true,
  "id": "-Nq8sample_activity_key",
  "url": "https://puzzel.org/en/sudoku/embed?p=-Nq8sample_activity_key",
  "message": "Sudoku created successfully"
}
افتح المحرِّر العودة إلى الأعلى
الصور

الصورة المقطّعة

يقطّع صورة إلى قطع تُسحب لإعادة تجميعها.

#
POST /api/public/v1/jigsaw لا تأخذ أي items
المحتوى

رابط صورة واحد، في حقل image. لا تأخذ نقطة النهاية هذه أي items.

تعود إلى الاسم الاحتياطي "Jigsaw Game API"

جدير بالمعرفة
  • ينشئ API دائمًا صورة مقطّعة بحجم 4×4. عدد القطع والقطع غير المنتظمة والحواف المستقيمة إعدادات خاصة بالمحرِّر — إرسال rows أو columns هنا لا يفعل شيئًا.
  • يُخزَّن الرابط كما أرسلته ولا يُنسخ الملف أبدًا، لذا يجب أن يبقى قابلًا للوصول العام طالما ظل النشاط يُلعب.
الإعدادات التي تقرؤها
الحقلالنوعما يفعله
image
مطلوب
string
stringالرابط المطلق للصورة المراد تقطيعها. يُرسَل في المستوى الأعلى، لا داخل settings.
طلب مثال
POST jigsaw 
curl -X POST https://puzzel.org/api/public/v1/jigsaw \
  -H "Content-Type: application/json" \
  -d '{
  "account_api_key": "YOUR_API_KEY",
  "email": "you@example.com",
  "title": "Jigsaw Game",
  "language": "ar",
  "image": "https://example.com/orchard.jpg"
}'
نجاح 
{
  "success": true,
  "id": "-Nq8sample_activity_key",
  "url": "https://puzzel.org/en/jigsaw/embed?p=-Nq8sample_activity_key",
  "message": "Jigsaw game created successfully"
}
افتح المحرِّر العودة إلى الأعلى

اللغز المنزلق

يقسّم صورة إلى مربّعات تنزلق إلى مكانها.

#
POST /api/public/v1/slidingpuzzle لا تأخذ أي items
المحتوى

رابط صورة واحد، داخل settings. لا تأخذ نقطة النهاية هذه أي items.

تعود إلى الاسم الاحتياطي "Sliding Puzzle API"

جدير بالمعرفة
  • خلافًا للصورة المقطّعة، تقرأ نقطة النهاية هذه صورتها من settings.image. يُتجاهَل حقل image في المستوى الأعلى ويردّ الطلب بالرمز 400.
  • يُخزَّن الرابط كما أرسلته ولا يُنسخ الملف أبدًا، لذا يجب أن يبقى قابلًا للوصول العام طالما ظل النشاط يُلعب.
الإعدادات التي تقرؤها
الحقلالنوعما يفعله
image
مطلوب في settings
string
stringالرابط المطلق للصورة المراد تشويشها. خلافًا للصورة المقطّعة، يوجد هذا الحقل داخل settings.
طلب مثال
POST slidingpuzzle 
curl -X POST https://puzzel.org/api/public/v1/slidingpuzzle \
  -H "Content-Type: application/json" \
  -d '{
  "account_api_key": "YOUR_API_KEY",
  "email": "you@example.com",
  "title": "Sliding Puzzle",
  "language": "ar",
  "settings": {
    "image": "https://example.com/orchard.jpg"
  }
}'
نجاح 
{
  "success": true,
  "id": "-Nq8sample_activity_key",
  "url": "https://puzzel.org/en/slidingpuzzle/embed?p=-Nq8sample_activity_key",
  "message": "Sliding puzzle created successfully"
}
افتح المحرِّر العودة إلى الأعلى

هل هناك خلل ما؟

أرسل الطلب الذي جرّبته والخطأ الذي حصلت عليه، وستحصل على إجابة حقيقية من الشخص الذي كتب نقطة النهاية.

راسل الدعم عبر البريد الإلكتروني