البناء باستخدام Wordly API.

بداية سريعة

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

1. 1
   إنشاء حساب

   سجل باستخدام عنوان البريد الإلكتروني وكلمة المرور فقط.

2. 2
   تحقق من بريدك الإلكتروني

   أدخل الرمز الذي أرسلته [email protected]. التحقق يمنح 50 ساعة معتمدة مجانية.

3. 3
   قم بتخزين مفتاح API الخاص بك

   انسخ ما تم إنشاؤه wly_live_... المفتاح والاحتفاظ به في متغير البيئة من جانب الخادم.

4. 4
   تقديم طلب اختبار

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

curl "https://api.wordlyenglish.com/v1/account" \
  -H "Authorization: Bearer $WORDLY_API_KEY" \
  -H "Accept: application/json"

{
  "data": {
    "message": "Authenticated",
    "credits_remaining": 50
  },
  "meta": { "lang": "en" }
}

عنوان URL الأساسي والإصدار

يتم تقديم جميع نقاط نهاية الإنتاج من عنوان URL الأساسي ذي الإصدار التالي:

ستستخدم الاستجابة المعطلة أو تغييرات السلوك إصدار مسار جديد. يمكن إدخال الحقول المضافة داخل v1لذا يجب على العملاء تجاهل خصائص الاستجابة التي لا يتعرفون عليها.

المصادقة

تتطلب نقاط النهاية التي تمت مصادقتها مفتاح API في HTTP Authorization رأس باستخدام مخطط Bearer.

Authorization: Bearer wly_live_your_api_key

رسائل API المترجمة

اضبط لغة الرد باستخدام ?lang=tr أو المعيار Accept-Language header. معلمات الاستعلام لها الأسبقية. تعلن كل استجابة JSON عن اللغة المحددة فيها Content-Language و meta.lang. تظل رموز الأخطاء مستقرة في اللغة الإنجليزية للتعامل مع البرامج؛ يتم ترجمة الرسالة التي يمكن قراءتها بواسطة الإنسان فقط.

curl "https://api.wordlyenglish.com/v1/account?lang=tr" \
  -H "Authorization: Bearer $WORDLY_API_KEY" \
  -H "Accept-Language: tr-TR"

رموز اللغة المدعومة: en, tr, de, fr, es, it, pt, nl, pl, ru, uk, ar, fa, he, hi, bn, ur, zh, ja, ko, id, ms, vi, th, sv, no, da, fi, cs, ro.

الاعتمادات والفواتير

Each successful metered request consumes the documented number of credits. Email-verified accounts receive 50 free credits once. Credits are deducted atomically, so concurrent requests cannot spend the same balance twice. Balance lookup through GET /v1/account is free.

Use GET /v1/account when you need the current balance. Other endpoint responses include the operation charge but omit the remaining balance. When the balance is insufficient, the API returns HTTP 402 ولا معالجة العملية.

{
  "error": {
    "code": "credits_exhausted",
    "message": "Your credit balance is exhausted. Add a package or enable pay-as-you-go to continue.",
    "upgrade_url": "/app.php?page=billing"
  }
}

دورة حياة مفتاح API

قم بإنشاء مفاتيح منفصلة للتطوير والتدريج والإنتاج. يقوم Wordly بتخزين تجزئة تشفير لكل مفتاح فقط؛ يتم عرض القيمة الكاملة مرة واحدة عند الإنشاء.

• مفاتيح الاسم حسب البيئة أو الخدمة.
• استخدم متغيرات البيئة أو مخزنًا سريًا مُدارًا.
• قم بإلغاء المفتاح على الفور إذا كان من الممكن أن يكون قد تم كشفه.
• قم بتدوير المفاتيح دون إعادة استخدام القيم القديمة.
• لا ترسل المفاتيح في سلاسل الاستعلام.

تنسيق الاستجابة

تستخدم الاستجابات الناجحة المستوى الأعلى data كائن وقد يشمل أ meta كائن. تستخدم الأخطاء دائمًا المستوى الأعلى error كائن ذو كائن مستقر يمكن قراءته آليًا code وقابلة للقراءة من قبل الإنسان message.

{
  "data": { ... },
  "meta": {
    "credits_used": 1,
    "request_id": "..."
  }
}

{
  "error": {
    "code": "invalid_api_key",
    "message": "..."
  }
}

احتفظ بال request_id عند الاتصال بالدعم بخصوص طلب تمت فوترته بنجاح. JSON مشفر بـ UTF-8 ويجب على العملاء إرساله Accept: application/json.

نقاط نهاية الإنتاج

نقاط نهاية المفردات

GET /v1/words/{word}

إرجاع مطابقة تامة للكلمة. استخدم languages=tr,de,fr لإرجاع الترجمات المطلوبة فقط. تكلفة الكتالوج أو السجلات المترجمة هي رصيد واحد؛ تكلف الملفات الشخصية المخصبة بالكامل 5 ساعات معتمدة.

curl "https://api.wordlyenglish.com/v1/words/water?languages=tr,de" \
  -H "Authorization: Bearer $WORDLY_API_KEY"

GET /v1/words/search

البحث مع q واختياري level, part_of_speech, category, limit، و cursor. تتراوح الحدود من 1 إلى 50. اجتياز meta.next_cursor في الطلب التالي

curl "https://api.wordlyenglish.com/v1/words/search?q=app&level=advanced&limit=20" \
  -H "Authorization: Bearer $WORDLY_API_KEY"

GET /v1/words/random

إرجاع 1-20 كلمة عشوائية. تصفية حسب level, part_of_speechأو category. كل فتحة يتم إرجاعها تكلف رصيدًا واحدًا.

POST /v1/words/batch

يبحث عن ما بين 1 و50 كلمة فريدة في طلب واحد. تحافظ الاستجابة على ترتيب الطلب وتضع علامة على كل عنصر found.

curl -X POST "https://api.wordlyenglish.com/v1/words/batch?lang=tr" \
  -H "Authorization: Bearer $WORDLY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"words":["water","opportunity"],"languages":["tr","de"]}'

GET /v1/languages

إرجاع كافة اللغات المدعومة للواجهة والرسائل API الثلاثين. يتم إرجاع ترجمات المفردات فقط عندما تكون متاحة. نقطة النهاية هذه عامة ولا تكلف أية أرصدة.

حد المعدل

يقتصر كل مفتاح API على 120 طلبًا مقبولاً في الدقيقة الواحدة. تشمل الردود X-RateLimit-Limit و X-RateLimit-Remaining. أ 429 rate_limit_exceeded الرد يشمل Retry-After: 60.

Response field reference

Every stable response variable is described below. Additive fields may appear later, so clients should ignore fields they do not recognize.

Vocabulary object

Meta object

Error object

أخطاء

سياسة إعادة المحاولة الموصى بها

لا تقم بإعادة المحاولة 401, 402أو 404 تلقائيا. للعابرة 5xx الاستجابات، استخدم التراجع الأسي مع عدم الاستقرار والحد الأقصى الصارم لإعادة المحاولة. لا تقم مطلقًا بإنشاء حلقة إعادة محاولة غير محدودة لأن كل طلب مصادق عليه تم قبوله قد يستهلك أرصدة.

جافا سكريبت / Node.js

const response = await fetch('https://api.wordlyenglish.com/v1/account', {
  headers: {
    Authorization: `Bearer ${process.env.WORDLY_API_KEY}`,
    Accept: 'application/json'
  }
});

const body = await response.json();
if (!response.ok) {
  throw new Error(`${body.error.code}: ${body.error.message}`);
}

console.log(body.data.credits_remaining);

بايثون

import os
import requests

response = requests.get(
    'https://api.wordlyenglish.com/v1/account',
    headers={
        'Authorization': f'Bearer {os.environ["WORDLY_API_KEY"]}',
        'Accept': 'application/json',
    },
    timeout=15,
)
response.raise_for_status()
print(response.json()['data']['credits_remaining'])

PHP

$curl = curl_init('https://api.wordlyenglish.com/v1/account');
curl_setopt_array($curl, [
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_TIMEOUT => 15,
  CURLOPT_HTTPHEADER => [
    'Authorization: Bearer ' . getenv('WORDLY_API_KEY'),
    'Accept: application/json',
  ],
]);

$body = curl_exec($curl);
$status = curl_getinfo($curl, CURLINFO_RESPONSE_CODE);
curl_close($curl);

if ($status >= 400) {
  throw new RuntimeException('Wordly API request failed');
}
$data = json_decode($body, true, flags: JSON_THROW_ON_ERROR);

دارت / رفرفة

لا تقم بشحن مفتاح Wordly داخل تطبيق Flutter. ينتمي المثال إلى وظيفة الخادم أو الواجهة الخلفية لـ Dart الموثوقة.

final response = await http.get(
  Uri.parse('https://api.wordlyenglish.com/v1/account'),
  headers: {
    'Authorization': 'Bearer ${Platform.environment['WORDLY_API_KEY']}',
    'Accept': 'application/json',
  },
);

final body = jsonDecode(response.body) as Map<String, dynamic>;
if (response.statusCode >= 400) {
  throw Exception((body['error'] as Map)['code']);
}

قائمة مرجعية الإنتاج

• يطلب Proxy Wordly من خلال واجهة خلفية موثوقة.
• ضبط مهلة الاتصال والاستجابة.
• مقبض 401, 402, 404، و 5xx بشكل منفصل.
• Query GET /v1/account when your application needs the current balance.
• تسجيل نقطة النهاية والحالة ووقت الاستجابة و request_id دون تسجيل مفتاح API.
• استخدم مفاتيح منفصلة لكل بيئة وقم بتدويرها بشكل دوري.
• Cache stable vocabulary responses in your backend when appropriate.