API و وب‌هوک‌ها
بگذارید برنامه‌های دیگر محتوا، فرم‌های فرستاده‌شده و مشترکان سایتتان را بخوانند، و همان لحظه که چیزی رخ می‌دهد باخبرشان کنید.
اگر طرح شما آن را دارد، توسعه‌دهندگان وب‌سایتتان را به ابزارهای دیگر وصل می‌کند — یک سرویس خودکارسازی، یک اپ، یا کد خودتان. دو بخش دارد: کلیدهای API برای برنامه‌ای که می‌خواهد از سایت بخواند، و وب‌هوک‌ها برای برنامه‌ای که می‌خواهد وقتی چیزی رخ داد باخبر شود. تنها مدیران و مالک آن را می‌بینند.
کلیدهای API
کلید API تازه را بزنید، آن را به نام چیزی که از آن استفاده می‌کند بنامید و تنها آنچه را که لازم دارد بخواند تیک بزنید. کلید یک بار نمایش داده می‌شود — همان موقع کپی‌اش کنید. اگر گم شد، آن را باطل کنید و کلید دیگری بسازید؛ کلید باطل‌شده بی‌درنگ از کار می‌افتد.
| می‌تواند بخواند | یعنی |
|---|---|
| نوشته‌ها، صفحه‌ها، پارتیتورها و آثار منتشرشده | آنچه سایت عمومی نشان می‌دهد. متن‌ها و فایل‌های ویژهٔ اعضا کنار گذاشته می‌شوند. |
| فرم‌های فرستاده‌شده | آنچه بازدیدکنندگان فرستاده‌اند — نام، ایمیل، پاسخ‌ها. |
| مشترکان خبرنامه | نشانی ایمیل و نام مشترکان. |
فراخوانی API
کلید را در سرآیند Authorization: Bearer vp_… بفرستید. بخش توسعه‌دهندگان نشانی API سایت شما و همهٔ نقطه‌های پایانی را آمادهٔ کپی نشان می‌دهد:
| نقطهٔ پایانی | برمی‌گرداند |
|---|---|
/posts | نوشته‌های منتشرشده، تازه‌ترین‌ها اول، بدون متنشان. |
/posts/{slug} | یک نوشته با متنش. |
/pages | صفحه‌های منتشرشده با متنشان. |
/scores | پارتیتورهای منتشرشده به ترتیب سایت، با مشخصات اثر. |
/scores/{slug} | یک پارتیتور با موومان‌ها، نخستین اجرا و فایل‌ها. |
/releases | آثار منتشرشده با جلدهایشان. |
/releases/{slug} | یک اثر با قطعه‌ها و پیوندهای سرویس‌ها. |
/forms/{formId}/submissions | فرستاده‌های یک فرم، تازه‌ترین‌ها اول. |
/subscribers | مشترکان تأییدشدهٔ خبرنامه. |
- فهرست‌ها صفحه به صفحه می‌آیند:
?page=2برای صفحهٔ بعد، و?per_page=برای حداکثر ۱۰۰ مورد در هر بار. هر پاسخ شمار کل را هم می‌گوید. - در سایت چندزبانه،
?locale=fa(یا زبان دیگری) محتوای همان زبان را می‌دهد. - شناسهٔ هر فرم بخش پایانی نشانی است، وقتی آن را در فرم‌ها باز می‌کنید.
- مبلغ‌ها به کوچک‌ترین واحد ارز هستند:
1250یعنی 12.50.
وب‌هوک‌ها
وب‌هوک تازه را بزنید، یک نشانی https که درخواست POST می‌پذیرد وارد کنید و رویدادهایی را که باید فرستاده شوند برگزینید. وقتی یکی رخ دهد، VPress آن را به‌صورت JSON به آنجا می‌فرستد.
| رویداد | فرستاده می‌شود وقتی |
|---|---|
post.published | نوشته‌ای منتشر شود — با ذخیرهٔ منتشرشده یا طبق زمان‌بندی. |
form.submitted | بازدیدکننده‌ای یکی از فرم‌های سایت را بفرستد. |
newsletter.subscribed | کسی اشتراک خبرنامه‌اش را تأیید کند. |
order.paid | سفارشی از فروشگاه پرداخت شود. |
score.published | پارتیتوری در /scores فهرست می‌شود. |
release.published | اثری در /music فهرست می‌شود. |
ارسال آزمایشی بی‌درنگ یک پیام آزمایشی می‌فرستد تا ببینید نقطهٔ پایانی‌تان پاسخ می‌دهد، و ارسال‌های اخیر زیر هر وب‌هوک نشان می‌دهد چه فرستاده شد و چه برگشت. ارسالی که پاسخ 2xx نگیرد در طول روز بعد دوباره فرستاده می‌شود. پس از ۲۰ شکست پشت سر هم، وب‌هوک خودش خاموش می‌شود؛ نقطهٔ پایانی را درست کنید و وب‌هوک را ذخیره کنید تا دوباره روشن شود.
اطمینان از اصل بودن یک ارسال
وقتی وب‌هوکی می‌سازید، کلید امضای آن یک بار به شما نشان داده می‌شود. هر ارسال سرآیند X-VPress-Signature به شکل t=…,v1=… دارد: t زمان ارسال است و v1 یک HMAC-SHA256 از زمان، یک نقطه و بدنهٔ خام، با همان کلید. آن را خودتان حساب کنید و مقایسه کنید، و ارسال‌های قدیمی‌تر از پنج دقیقه را نپذیرید. این همان روش Stripe است، پس بیشتر کتابخانه‌های وب‌هوک می‌توانند آن را بررسی کنند.
هنوز کمک لازم دارید؟
اگر مقاله‌ها پاسخ پرسش شما را ندارند، تیکت باز کنید تا تیم VPress پاسخ دهد.