وثائق 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 في URL كـ 'v' ورقم، مثلاً v1، v2، v3.
مثال
https://api.printfriendly.com/v2/pdf/create
https://api.printfriendly.com/v2/html/create
أساليب API
طريقة | مدخل | الناتج |
|---|---|---|
ملف PDF / إنشاء | رابط / HTML | HTML |
html / إنشاء | رابط / HTML | بي دي إف |
المعلمات
يجب تقديم page_url أو html كمُدخَل. جميع المدخلات الأخرى اختيارية.
المعلمات | القيمة |
|---|---|
عنوان الصفحة | عنوان URL للصفحة المستهدفة |
HTML | محتوى HTML الخاص بالصفحة المستهدفة |
css_url | رابط URL لملف CSS المخصص |
header_image_url | عنوان 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 مع الحالة 200 ومحتوى PDF/HTML في جسم الاستجابة.
الأخطاء
تستخدم PrintFriendly رموز الحالة التقليدية واستجابة JSON لتوفير تفاصيل الخطأ.
رموز الحالة
الحالة | الوصف |
|---|---|
٢٠٠ موافق | كل شيء يعمل بشكل جيد. |
٤٠٠ طلب خاطئ | حدث خطأ. راجع التفاصيل في JSON. |
401 غير مصرح | 401 غير مصرح |
404 لم يتم العثور على | 404 لم يتم العثور على |
429 عدد كبير جدًا من الطلبات | 429 عدد كبير جدًا من الطلبات |
جميع ردود غير الناجحة (ليس حالة 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-RateLimit | عدد الثواني حتى نهاية الفترة الحالية. |
مثال مع معلمة 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