مستندات API
سوالی دارید؟ با ما تماس بگیرید.
همه درخواست‌های API باید از طریق HTTPS انجام شوند و از HTTP Basic Auth با استفاده از موارد زیر استفاده کنند:
Username: API KEY
Password: Not needed
مثال
curl https://api.printfriendly.com/v1/pdfs/create /
-u your_api_key: /
-d page_url=https://en.wikipedia.org/wiki/Eclipse
پرچم | توضیحات |
|---|---|
-u | اعتبارنامه احراز هویت اولیه را وارد کنید، یک علامت دو نقطه بعد از کلید API از درخواست رمز عبور توسط cURL جلوگیری می‌کند. |
-د | ارسال داده در درخواست POST |
در صورت موفقیت، شما یک پاسخ http با وضعیت 302 (تغییر مسیر) دریافت خواهید کرد و اطلاعات JSON در بدنه پاسخ قرار خواهد گرفت.
# HTTP RESPONSE
# HEADERS (some of headers are ommited)
Content-Type: application/json; charset=utf-8
Status: 302 Found
Location: https://v.printfriendly.com/system/pdfs/pdf_1480936999_755625A4.pdf
# BODY
{"success":"Redirect to https://v.printfriendly.com/system/pdfs/pdf_1480947535_6e7ecaA4.pdf"}
نسخه API
نسخه فعلی API 1.0 است.
نسخه اصلی API باید به صورت 'v' و عدد، به عنوان مثال v1، v2، v3 در URL ارائه شود.
مثال
https://api.printfriendly.com/v2/pdf/create
https://api.printfriendly.com/v2/html/create
روش‌های API
روش | ورودی | خروجی |
|---|---|---|
پی‌دی‌اف / ایجاد کنید | لینک / HTML | HTML |
html / ایجاد | لینک / HTML | پی‌دی‌اف |
پارامترها
شما باید پارامتر page_url یا html را فراهم کنید. تمامی پارامترهای دیگر اختیاری هستند.
پارامترها | ارزش |
|---|---|
آدرس صفحه | آدرس صفحه هدف |
HTML | محتوای HTML صفحه هدف |
css_url | آدرس برای فایل CSS سفارشی |
header_image_url | آدرس اینترنتی برای تصویر سربرگ سفارشی |
متن سرصفحه | متن رشته |
تمام مثال‌های زیر برای روش "pdf/create" ارائه شده‌اند و برای روش "html/create" نیز کار می‌کنند.
مثال با پارامتر page_url
curl https://api.printfriendly.com/v1/pdfs/create /
-u your_api_key: /
-d page_url=https://test.test /
-d css_url=https://my-site.com/pdf_style.css /
-d header_text='My Custom Header'
در صورت موفقیت، شما یک پاسخ http با وضعیت 302 (تغییر مسیر) دریافت خواهید کرد و اطلاعات JSON در بدنه پاسخ قرار خواهد گرفت.
نمونه‌ای با پارامترهای html
curl https://api.printfriendly.com/v1/pdfs/create /
-u your_api_key: /
-d html='<html><body><h1>Title</h1><p>Text text text text text text text text text</p></body></html>'
در صورت موفقیت، شما پاسخ http با وضعیت ۲۰۰ و محتوای PDF/HTML را در بدن پاسخ دریافت خواهید کرد.
خطاها
PrintFriendly از کدهای وضعیت متعارف و پاسخ JSON برای ارائه جزئیات خطا استفاده می‌کند.
کدهای وضعیت
وضعیت | توضیحات |
|---|---|
۲۰۰ موفقیت‌آمیز | همه چیز خوب کار می‌کند. |
۴۰۰ درخواست نامعتبر | خطایی رخ داده است. جزئیات را در JSON ببینید. |
۴۰۱ غیرمجاز | ۴۰۱ غیرمجاز |
۴۰۴ پیدا نشد | ۴۰۴ پیدا نشد |
۴۲۹ درخواست‌های بیش از حد | ۴۲۹ درخواست‌های بیش از حد |
تمام پاسخ‌های نه موفقیت‌آمیز (نه وضعیت 302 OK) دارای بدنه JSON با جزئیات خطا هستند، که شامل نوع خطا و پیام خواهد بود.
انواع خطا
نوع | توضیحات |
|---|---|
اعتبارسنجی پارامترها | اعتبارسنجی پارامترها ناموفق بود. |
دامنه ممنوع | این دامنه به طور موقت ممنوع شده است. |
خطا در تجزیه | نمی‌توان صفحه را تحلیل کرد. نمی‌توانیم محتوای این صفحه را تعیین کنیم. |
خطای واکشی | صفحه قابل دریافت نیست. بررسی کنید که URL قابل دسترسی باشد و دوباره تلاش کنید. |
بارگذاری سنگین | اعتبارسنجی پارامترها شکست خورد. |
پسوند فایل نامعتبر | فقط صفحات وب پشتیبانی می‌شوند. این یک فایل PDF/TXT یا تصویر (JPG، PNG، GIF) است. |
صفحه بزرگ | صفحه هدف بیش از 2 مگابایت است. صفحات بزرگ پشتیبانی نمی‌شوند. |
پلتفرم امنیتی | پلتفرم امنیتی از بارگذاری این صفحه جلوگیری می‌کند. |
زمان پایان | زمان مجاز به پایان رسید. موتور نمی‌تواند صفحه را در مدت 30 ثانیه پردازش کند. لطفاً بعداً دوباره تلاش کنید. |
همه‌گیر | خطای غیرمنتظره. لطفاً بعداً دوباره امتحان کنید. |
مثال
curl https://api.printfriendly.com/v1/pdfs/create /
-u your_api_key: /
-d page_url=https://test.test
HTML input
# HTTP RESPONSE
# HEADERS (some of headers were ommited)
Content-Type: application/json; charset=utf-8/
Status: 400 Bad Request
# BODY (JSON)
{"status":"failed","message":"Print technology unable to download or parse content"}
محدودیت نرخ درخواست‌ها
رابط کاربری محدودیت 60 درخواست در دقیقه دارد. اگر از این محدودیت تجاوز کنید، پاسخی با وضعیت: 429 درخواست‌های زیاد دریافت خواهید کرد.
سرصفحه | توضیحات |
|---|---|
محدودیت نرخ-X | محدودیت کل درخواست‌ها برای دوره فعلی. |
محدودیت-باقی‌مانده-X | درخواست باقی‌مانده برای دوره جاری. |
بازنشانی محدودیت نرخ-X | مدت زمان به ثانیه تا پایان دوره جاری. |
نمونه با پارامتر page_url
# HEADERS (some of headers were ommited)
Status: 429 Too Many Requests
X-RateLimit-Limit: 60
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 20
# BODY (JSON)Empty