בנה עם Wordly API.

התחלה מהירה

צור חשבון בחינם, אמת את הדוא"ל שלך באמצעות הקוד בן שש הספרות, והעתק את מפתח ה-API המוצג פעם אחת בלוח המחוונים למפתחים שלך.

1. 1
   צור חשבון

   הרשמה רק עם כתובת אימייל וסיסמה.

2. 2
   אמת את האימייל שלך

   הזן את הקוד שנשלח על ידי [email protected]. Verification grants 50 free credits.

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, so clients should ignore response properties they do not recognize.

אימות

נקודות קצה מאומתות דורשות מפתח API ב-HTTP Authorization כותרת באמצעות ערכת ה-Bearer.

Authorization: Bearer wly_live_your_api_key

הודעות API מקומיות

הגדר את שפת התגובה עם ?lang=tr או התקן Accept-Language כותרת. פרמטרי שאילתה מקבלים עדיפות. כל תגובת JSON מצהירה על המקום שנבחר בו Content-Language ו meta.lang. Error codes remain stable in English for programmatic handling; only the human-readable message is localized.

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 key lifecycle

צור מפתחות נפרדים לפיתוח, הבמה והפקה. 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, and cursor. Limits range from 1 to 50. Pass 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, or category. Each returned slot costs one credit.

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. A 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, or 404 באופן אוטומטי. לחולפים 5xx תגובות, השתמש ב-backoff אקספוננציאלי עם ריצוד ומכסה קפדנית של ניסיון חוזר. לעולם אל תיצור לולאת ניסיון חוזר ללא גבולות מכיוון שכל בקשה מאומתת מקובלת עשויה לצרוך קרדיטים.

JavaScript / 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 backend או שרת מהימן.

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']);
}

רשימת תיוג ייצור

• בקשות פרוקסי של Wordly דרך קצה אחורי מהימן.
• הגדר תפוגה של חיבור ותגובה.
• ידית 401, 402, 404, and 5xx בנפרד.
• Query GET /v1/account when your application needs the current balance.
• יומן נקודת קצה, סטטוס, זמן אחזור ו request_id מבלי לרשום את מפתח ה-API.
• השתמש במפתחות נפרדים לכל סביבה וסובב אותם מעת לעת.
• Cache stable vocabulary responses in your backend when appropriate.