راهنمای API خط وب ابزار

احراز هویت

کلید خود را از بخش کلیدهای API بسازید و در هدر هر درخواست قرار دهید. دسترسی API نیازمند پلن دارای API است. کلید API را فقط در backend یا محیط امن پروژه خود استفاده کنید و آن را داخل کد frontend عمومی قرار ندهید.

Authorization: Bearer kt_xxxxxxxxxxxxxxxxxxxxxxxx

ساخت QR Code

POST /api/v1/qr

بدنه به‌صورت JSON است. فیلد type یکی از url، text، phone، sms، email، wifi، vcard، geo، event یا whatsapp است. فیلد data برای نوع‌های ساده string و برای نوع‌های چندفیلدی object است. فرمت پیش‌فرض SVG است و می‌تواند PNG یا WebP باشد. URL فقط encode می‌شود و API برای ساخت QR آن را fetch نمی‌کند.

curl -X POST https://YOUR_DOMAIN/api/v1/qr \
  -H "Authorization: Bearer kt_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "url",
    "data": "https://example.com/pricing",
    "format": "png",
    "options": {
      "size": 1024,
      "margin": 6,
      "errorCorrectionLevel": "H",
      "foreground": "#111827",
      "background": "#ffffff",
      "dotStyle": "rounded",
      "cornerStyle": "rounded"
    }
  }' \
  --output khateweb-qr.png

برای نوع‌های پیچیده، نمونه Wi-Fi: {"type":"wifi","data":{"ssid":"Office","password":"secret","encryption":"WPA"}}. برای vCard، event و ایمیل نیز نام فیلدها در جدول زیر مشخص شده است.

گزینه‌های طراحی شامل size بین ۱۲۸ تا ۲۰۴۸، margin بین ۴ تا ۱۶، سطوح تصحیح خطای L/M/Q/H، رنگ‌های HEX، dotStyle، cornerStyle و لوگوی data URL از نوع PNG/JPEG/WebP است. اندازه لوگو حداکثر ۲۸٪ و حجم بدنه درخواست حداکثر ۵۱۲ کیلوبایت است.

پردازش تصویر

POST /api/v1/image

بدنه به‌صورت multipart/form-data است. فیلد file (تصویر ورودی) و format الزامی‌اند؛ format یکی از webp، avif، png، jpeg، gif یا same است. مقدار same فقط حجم را کم می‌کند و فرمت را عوض نمی‌کند (JPEG/PNG/WebP/AVIF/GIF؛ انیمیشن حفظ می‌شود)؛ هدرهای X-Image-Format و X-Compression-Skipped (مقدار not-smaller یعنی فایل اصلی برگشته چون فشرده‌سازی کوچک‌ترش نکرد) برمی‌گردند و برای SVG/TIFF/BMP/HEIC خطای same_format_unsupported می‌آید (خروجی ico فقط در ابزار تصویر سایت موجود است، نه در این endpoint). سقف حجم فایل ورودی ثابت نیست و بر اساس max_file_size پلن فعلی شما تعیین می‌شود؛ مصرف فعلی و سقف پلن را در داشبورد ببینید. پاسخ موفق، مستقیماً بایت‌های تصویر پردازش‌شده با Content-Type متناظر فرمت خروجی است.

curl -X POST https://YOUR_DOMAIN/api/v1/image \
  -H "Authorization: Bearer kt_xxx" \
  -F "file=@photo.png" \
  -F "format=webp" \
  -F "quality=82" \
  -F "width=1200" \
  --output out.webp

پردازش به همین ترتیب انجام می‌شود: چرخش → قرینه‌سازی عمودی/افقی → تغییر اندازه → سیاه‌وسفید → بلور → شارپ‌کردن → خروجی نهایی. اعمال هر مرحله به فرستادن فیلد متناظر بستگی دارد.

فیلدهای بولی (keepAspectRatio، flipV، flipH، grayscale، sharpen، stripMetadata) فقط با مقدار متنی "1" فعال می‌شوند؛ هر مقدار دیگری (از جمله عدم ارسال فیلد، به‌جز keepAspectRatio و stripMetadata که پیش‌فرضشان فعال است) غیرفعال در نظر گرفته می‌شود. نوع فایل ورودی باید یکی از png، jpeg، gif، tiff، bmp، webp، avif یا svg باشد.

واکاوی سایت

POST /api/v1/analyze

بدنه به‌صورت JSON با url (عمومی) و strategy اختیاری (mobile یا desktop). پاسخ، گزارش کامل Lighthouse است. اجرای هر تحلیل ممکن است تا حدود ۹۰ ثانیه طول بکشد.

curl -X POST https://YOUR_DOMAIN/api/v1/analyze \
  -H "Authorization: Bearer kt_xxx" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://example.com","strategy":"mobile"}'

بررسی لینک‌های خراب

POST /api/v1/links

بدنه JSON با فیلد url (صفحه عمومی). همه لینک‌ها و تصاویر صفحه (حداکثر ۱۰۰ مورد اول) بررسی می‌شود و گزارشی شامل totals و فهرست results برمی‌گردد؛ هر مورد یکی از وضعیت‌های broken، error، blocked، restricted، redirect، skipped یا ok دارد و موارد مشکل‌دار اول می‌آیند. وضعیت restricted یعنی سرور مقصد به ربات‌ها پاسخ ۴۰۱، ۴۰۳ یا ۴۲۹ داده و لینک لزوماً خراب نیست. هر فراخوانی یک درخواست از سقف ماهانه API مصرف می‌کند و فقط بعد از تکمیل بررسی ثبت می‌شود. اجرا ممکن است تا حدود یک دقیقه طول بکشد.

curl -X POST https://YOUR_DOMAIN/api/v1/links \
  -H "Authorization: Bearer kt_xxx" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://example.com/blog"}'

بررسی گواهی SSL

POST /api/v1/ssl

بدنه JSON با فیلد host (نام دامنه عمومی؛ فقط پورت ۴۴۳). پاسخ شامل مشخصات گواهی (صادرکننده، تاریخ انقضا، نام‌های پوشش‌داده‌شده، زنجیره)، نسخه TLS، هدر HSTS، ریدایرکت http به https و فهرست findings با سطح ok، warn یا error است. هر فراخوانی یک درخواست از سقف ماهانه API مصرف می‌کند و فقط بعد از تکمیل بررسی ثبت می‌شود.

curl -X POST https://YOUR_DOMAIN/api/v1/ssl \
  -H "Authorization: Bearer kt_xxx" \
  -H "Content-Type: application/json" \
  -d '{"host":"example.com"}'

بررسی سئوی فنی یک صفحه

POST /api/v1/seo-audit

بدنه JSON با فیلد url (صفحه عمومی). پاسخ شامل امتیاز score (۰ تا ۱۰۰)، فهرست checks (هر مورد با status برابر pass، warn یا fail) و meta (عنوان، توضیحات، canonical، robots، تعداد H1 و تصاویر بدون alt) است. هر فراخوانی یک درخواست از سقف ماهانه API مصرف می‌کند.

curl -X POST https://YOUR_DOMAIN/api/v1/seo-audit \
  -H "Authorization: Bearer kt_xxx" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://example.com/"}'

نقشه‌ی سایت

POST /api/v1/sitemap

بدنه JSON با mode و url. حالت validate یک sitemap موجود را دریافت و ساختارش را بررسی می‌کند. حالت generate سایت را (فقط همان دامنه، با احترام به robots.txt، حداکثر ۱۰۰ صفحه) می‌خزد و فایل xml می‌سازد. خزیدن سنگین است و سقف درخواست آن در دقیقه کمتر است. هر فراخوانی یک درخواست از سقف ماهانه API مصرف می‌کند.

curl -X POST https://YOUR_DOMAIN/api/v1/sitemap \
  -H "Authorization: Bearer kt_xxx" \
  -H "Content-Type: application/json" \
  -d '{"mode":"validate","url":"https://example.com/sitemap.xml"}'

فشرده‌سازی CSS، JS و HTML

POST /api/v1/minify

بدنه JSON با code (حداکثر ۵۰۰ کیلوبایت) و kind برابر css، js یا html. کد فقط تجزیه و دوباره چاپ می‌شود و هرگز اجرا یا ذخیره نمی‌شود. خطای نحوی با کد 422 و syntax_error و شماره خط برمی‌گردد. هر فراخوانی یک درخواست از سقف ماهانه API مصرف می‌کند.

curl -X POST https://YOUR_DOMAIN/api/v1/minify \
  -H "Authorization: Bearer kt_xxx" \
  -H "Content-Type: application/json" \
  -d '{"kind":"css","code":"a { color: red; }"}'

متن فارسی

POST /api/v1/persian-text

بدنه JSON با فیلد operation برابر normalize یا slug و فیلد text (حداکثر ۲۰۰ هزار نویسه). عملیات normalize «ي» و «ك» عربی را فارسی می‌کند و اعداد، کشیدگی، فاصله‌گذاری، علائم و نیم‌فاصله را اصلاح می‌کند؛ آدرس‌ها، ایمیل‌ها و متن داخل بک‌تیک دست‌نخورده می‌مانند. گزینه‌های اختیاری: arabicLetters، tatweel، diacritics، spacing، punctuation، zwnj (بولی) و digits (keep، persian یا english). پاسخ شامل text، تعداد اصلاحات هر مرحله در changes و جمع کل در total است. عملیات slug یک نامک فارسی با گزینه‌های separator (- یا _) و maxLength (۱۰ تا ۲۰۰) می‌سازد و شکل رمزگذاری‌شده را هم در encoded برمی‌گرداند. گزینه ناشناخته خطای invalid_options می‌دهد. هر فراخوانی یک درخواست از سقف ماهانه API مصرف می‌کند.

curl -X POST https://YOUR_DOMAIN/api/v1/persian-text \
  -H "Authorization: Bearer kt_xxx" \
  -H "Content-Type: application/json" \
  -d '{"operation":"normalize","text":"كتاب هاي من را مي خوانم","options":{"digits":"persian"}}'

واکاوی غیرهمزمان (صف)

POST /api/v1/analyze/async → GET /api/v1/jobs/{id}

برای پرهیز از تایم‌اوت در تحلیل‌های طولانی، کار را در صف ثبت کنید. پاسخ فوری شامل jobId است؛ سپس وضعیت را poll کنید تا status برابر done شود و result برگردد.

# 1) enqueue -> 202 { jobId, status, poll }
curl -X POST https://YOUR_DOMAIN/api/v1/analyze/async \
  -H "Authorization: Bearer kt_xxx" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://example.com"}'

# 2) poll -> { status: queued|running|done|failed, result }
curl https://YOUR_DOMAIN/api/v1/jobs/JOB_ID \
  -H "Authorization: Bearer kt_xxx"

پایش سرعت (فقط‌خواندنی)

GET /api/v1/performance

خلاصه‌ی صفحه‌هایی که در داشبورد برای پایش دوره‌ای سرعت اضافه کرده‌اید: برای هر مورد آخرین امتیازها و Core Web Vitals در latest، امتیاز عملکرد بررسی قبلی در previousPerformance و روند ۱۲ بررسی اخیر در trend (قدیمی به جدید) برمی‌گردد. این درخواست از سقف ماهانه API مصرف نمی‌کند، ولی برای هر کلید در دقیقه حداکثر ۶۰ بار مجاز است. افزونه وردپرس از همین نقطه برای ویجت پیشخوان استفاده می‌کند.

curl https://YOUR_DOMAIN/api/v1/performance \
  -H "Authorization: Bearer kt_xxx"

وضعیت مانیتورهای آپتایم (فقط‌خواندنی)

GET /api/v1/monitors

وضعیت مانیتورهایی که در داشبورد ساخته‌اید: status (up، down یا unknown)، زمان آخرین بررسی و پاسخ، تاریخ انقضای SSL، درصد در دسترس بودن ۲۴ ساعت و ۳۰ روز (uptime24h، uptime30d)، قطعی باز در openIncident و آدرس صفحه‌ی وضعیت عمومی در صورت فعال بودن. این درخواست از سقف ماهانه API مصرف نمی‌کند، ولی برای هر کلید در دقیقه حداکثر ۶۰ بار مجاز است.

curl https://YOUR_DOMAIN/api/v1/monitors \
  -H "Authorization: Bearer kt_xxx"

وضعیت مصرف

GET /api/v1/usage

بدون بدنه؛ فقط هدر Authorization لازم است. برخلاف سایر endpointها، این درخواست از سهمیه ماهانه شما مصرف نمی‌کند و می‌توانید هرچند بار لازم است آن را صدا بزنید. برای نمایش وضعیت اتصال در برنامه یا افزونه خودتان (مثل داشبورد وضعیت افزونه وردپرس) مناسب است.

curl https://YOUR_DOMAIN/api/v1/usage \
  -H "Authorization: Bearer kt_xxx"

{
  "plan": { "id": "pro", "label": "حرفه‌ای" },
  "api": { "usedThisMonth": 120, "limitPerMonth": 10000, "remainingThisMonth": 9880 },
  "tools": {
    "analyze": { "usedToday": 3, "limitPerDay": 200 },
    "convert": { "usedToday": 15, "limitPerDay": 9999 }
  },
  "maxFileSizeBytes": 52428800
}

کدهای خطا

افزونه وردپرس

برای سایت‌های وردپرسی، به‌جای فراخوانی مستقیم API، افزونه رسمی «خط وب ابزار» را می‌توانید دانلود و نصب کنید. این افزونه با همان کلید API شما به سرویس متصل می‌شود و از پیشخوان وردپرس این کارها را انجام می‌دهد:

• بررسی کل کتابخانه رسانه و شناسایی تصاویری که فرمت یا حجم نامناسب دارند.
• بهینه‌سازی تکی، گروهی یا خودکار (هنگام آپلود)، با به‌روزرسانی صحیح فرمت/پسوند فایل.
• واکاوی عملکرد سایت با Lighthouse، مستقیم از پیشخوان.
• داشبورد وضعیت اتصال و مصرف، مستقیماً از همان GET /api/v1/usage بالا.
• دریافت خودکار به‌روزرسانی از طریق مکانیزم استاندارد وردپرس، بدون دانلود و آپلود دستی نسخه جدید.

برای این کار، افزونه به‌صورت دوره‌ای (و با یک دکمه «بررسی به‌روزرسانی» برای بررسی فوری) اندپوینت عمومی GET /api/wordpress-plugin/version را می‌خواند؛ این اندپوینت نیازی به کلید API ندارد و فقط شماره نسخه، لینک دانلود بسته و changelog را برمی‌گرداند — همان مسیر /downloads. اگر نسخه سرویس جدیدتر از نسخه نصب‌شده باشد، در «افزونه‌ها ← Update Now» دقیقاً مثل هر افزونه رسمی دیگر قابل به‌روزرسانی است.

جزئیات نصب و معماری افزونه در مخزن پروژه، مسیر integrations/wordpress/ موجود است.