وب‌سرویس کوتاه کردن لینک

وب‌سرویس پیوند چه کاری می‌کند؟

وب‌سرویس پیوند به برنامه شما یاد می‌دهد لینک کوتاه بسازد. یک نشانی بلند می‌فرستید و نشانی کوتاه آن را در پاسخ می‌گیرید. اگر کد QR هم بخواهید، همین‌جا ساخته می‌شود. پاسخ‌ها به قالب JSON هستند و هر زبان برنامه‌نویسی می‌تواند آن‌ها را بخواند.

برای استفاده از وب‌سرویس حساب و کلید API لازم است. حساب را با یک کد پیامکی می‌سازید و کلید را از پنل می‌گیرید. پیوندها در حساب شما می‌مانند و سقف درخواست ۶۰ در دقیقه است. وب‌سرویس به‌کار فروشگاه‌های اینترنتی، بات‌های تلگرام، ابزارهای بازاریابی و هر برنامه‌ای می‌آید که لینک می‌سازد.

ساختن پیوند کوتاه

برای به‌کار بردن وب‌سرویس پیوند کافی است با روش POST در پروتکل HTTP به نشانی زیر درخواست دهید. نشانی‌ای که می‌خواهید کوتاه کنید را با کلید link در بدنه درخواست بفرستید.

https://pvnd.io/api/v1/links

یا اگر احتیاج به cURL دارید، مقدار زیر را کپی کنید و در ترمینال وارد کنید.

curl --location 'https://pvnd.io/api/v1/links' \
    --header 'Accept: application/json' \
    --header 'Authorization: Bearer YOUR_API_KEY' \
    --form 'link="https://google.com"'

ساختن کد QR

اگر کد QR می‌خواهید، به‌جای مسیر بالا به این مسیر با روش POST درخواست دهید. مسیر پیوند کد QR نمی‌سازد و این مسیر هم پیوند و هم کد را می‌سازد. نشانی را با کلید link بفرستید.

https://pvnd.io/api/v1/qr-codes

curl --location 'https://pvnd.io/api/v1/qr-codes' \
    --header 'Accept: application/json' \
    --header 'Authorization: Bearer YOUR_API_KEY' \
    --form 'link="https://google.com"'

بررسی‌های ایمنی نشانی مثل مسیر پیوند است: نشانی بدافزار و سایت‌های نامناسب با 422 رد می‌شود. کلید API و سقف درخواست هم همان است، اما شمارنده درخواست این مسیر جداست. هر کد از سهم ماهانه پیوند و از سهم ماهانه کد QR طرح شما کم می‌شود.

{
    "status": "success",
    "message": "پیوند کوتاه و کد QR شما با موفقیت ساخته شد.",
    "data": {
        "link": "https://pvnd.io/aaaaa",
        "qr_svg": "https://pvnd.io/qr/aaaaa",
        "qr_png": "https://pvnd.io/qr/aaaaa.png"
    },
    "errors": []
}

دو نشانی qr_svg و qr_png کد QR همین پیوند را می‌دهند. SVG برای چاپ است و PNG برای صفحه.

کلید API

هر درخواست به وب‌سرویس کلید می‌خواهد. پیوندهای ساخته‌شده در حساب شما ذخیره می‌شوند و در بخش پیوندهای پنل دیده می‌شوند. برای ساخت کلید وارد پنل شوید و به صفحه کلیدهای API بروید. کلید تنها یک بار، هنگام ساخت، نمایش داده می‌شود و بعد از آن دیگر دیده نمی‌شود. اگر گمش کردید، آن را لغو کنید و کلید تازه‌ای بسازید.

کلید را در هدر Authorization و به‌صورت Bearer بفرستید.

curl --location 'https://pvnd.io/api/v1/links' \
    --header 'Accept: application/json' \
    --header 'Authorization: Bearer YOUR_API_KEY' \
    --form 'link="https://google.com"'

هر کلیدی که از پنل می‌سازید فعلاً تنها اجازه ساخت پیوند دارد. پیوندی که با کلید ساخته می‌شود از سهم ماهانه طرح شما کم می‌شود. پاسخ‌های 401 و 403 در جدول خطاها توضیح داده شده‌اند.

پاسخ

سرور پیوند کوتاه شما را با کد 201 در قالب زیر برمی‌گرداند.

{
    "status": "success",
    "message": "پیوند کوتاه شما با موفقیت ساخته شد.",
    "data": {
        "link": "https://pvnd.io/aaaaa"
    },
    "errors": []
}

این مسیر کد QR نمی‌سازد. برای کد QR از مسیر ساختن کد QR بهره بگیرید.

خطاها

هر پاسخ ناموفق همان قالب پاسخ موفق را دارد، با status برابر error. برنامه شما باید روی کد وضعیت HTTP و، اگر هست، روی errors.code تصمیم بگیرد، نه روی متن پیام، چون متن پیام تغییر می‌کند.

پیوند کوتاه شما دوباره کوتاه نمی‌شود. نمونه پاسخ 422 برای آن:

{
    "status": "error",
    "message": "این پیوند از پیش کوتاه شده است!",
    "data": [],
    "errors": {
        "link": [
            "این پیوند از پیش کوتاه شده است!"
        ]
    }
}

سقف درخواست

برای اینکه سرویس برای همه پایدار بماند، شمار درخواست‌ها سقف دارد: ۱۰ درخواست در دقیقه برای هر نشانی اینترنتی، و ۶۰ درخواست در دقیقه اگر کلید API خود را بفرستید. با گذر از این سقف، پاسخ 429 دریافت می‌کنید.

سهم ماهانه

اگر کلید API خود را بفرستید، سهم ماهانه طرح شما روی وب‌سرویس هم حساب می‌شود. پیوندی که از این سهم بگذرد با پاسخ 402 رد می‌شود، نه 422: نشانی‌ای که فرستاده‌اید درست است و آنچه به پایان رسیده سهم ماه است. کلید errors.code همیشه link_quota_reached است و بر خلاف متن پیام تغییر نمی‌کند، پس برنامه شما روی همین کلید تصمیم بگیرد. شمارش از اول ماه شمسی بعد از نو آغاز می‌شود.

{
    "status": "error",
    "message": "سهم ماهانه طرح پایه پر شده است؛ این طرح ماهی 10 پیوند می‌سازد. شمارش از اول ماه بعد از نو آغاز می‌شود.",
    "data": [],
    "errors": {
        "code": "link_quota_reached",
        "quota": 10,
        "used": 10
    }
}

مسیر کد QR یک پاسخ 402 دیگر هم دارد: وقتی سهم کد QR این ماه پر شده باشد، errors.code برابر qr_quota_reached است.

از اینکه پیوند را در محصول خودتان به‌کار می‌برید سپاسگزاریم. اگر پرسشی دارید، از صفحه تماس بپرسید.