با Wordly API بسازید.

شروع سریع

یک حساب کاربری رایگان ایجاد کنید، ایمیل خود را با استفاده از کد شش رقمی تأیید کنید و کلید 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 هدر با استفاده از طرح حامل.

Authorization: Bearer wly_live_your_api_key

پیام های API محلی شده

زبان پاسخ را با ?lang=tr یا استاندارد Accept-Language هدر پارامترهای پرس و جو اولویت دارند. هر پاسخ 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 برای برگرداندن فقط ترجمه های درخواستی هزینه کاتالوگ یا سوابق ترجمه شده 1 اعتبار. پروفایل های کاملا غنی شده 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

همه 30 رابط پشتیبانی شده و محلی پیام 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 از طریق یک Backend قابل اعتماد درخواست می کند.
• زمان‌بندی اتصال و پاسخ را تنظیم کنید.
• دسته 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.