پرش به مطلب اصلی

درخواست‌های API مدیریت

این سند نقاط پایانی API موجود برای برنامه‌های مدیریتی جهت مدیریت پست‌ها در ماژول CMS را توضیح می‌دهد.

لیست پست‌ها​

بازیابی لیست تمام پست‌ها با جزئیات مدیریتی.

درخواست​

GET /api/admin/v3/cms/post?includes=category,tags,author&field_sets=%7B%22cms_posts%22%3A%22id%2Ctitle%2Cslug%2Cexcerpt%2Ccontent%2Cfeatured_image%2Cstatus%2Ccreated_at%2Cupdated_at%2Cpublished_at%2Ccategory%2Ctags%2Cauthor%2Cview_count%2Ccomment_count%2Cis_featured%2Cseo%22%7D&search=status%3Apublished&searchFields=status&per_page=20&page=1 HTTP/1.1
Api-Key: {{api-key}}

پارامترهای پرس‌وجو​

پارامترنوعتوضیحات
includesstringموجودیت‌های مرتبط برای گنجاندن در پاسخ (مثلاً category,tags,author)
field_setsobjectشیء JSON که مشخص می‌کند کدام فیلدها برای هر نوع موجودیت گنجانده شوند
searchstringعبارات جستجو با قالب field:value
searchFieldsstringفیلدهایی که در آنها جستجو شود
searchJoinstringنحوه پیوند عبارات جستجوی چندگانه (and یا or)
per_pageintegerتعداد آیتم‌ها در هر صفحه
pageintegerشماره صفحه برای صفحه‌بندی
sortstringفیلد برای مرتب‌سازی (گزینه‌ها: id، created_at، updated_at، title، status)
orderstringترتیب مرتب‌سازی (گزینه‌ها: asc، desc)

پاسخ​

{
  "status": true,
  "result": [
    {
      "id": 1,
      "title": "نمونه عنوان مقاله",
      "slug": "sample-post-title",
      "excerpt": "این یک نمونه خلاصه مقاله است...",
      "content": "این محتوای کامل مقاله نمونه است...",
      "featured_image": "https://example.com/images/sample-post.jpg",
      "status": "published",
      "created_at": "2025-03-15T10:30:00.000000Z",
      "updated_at": "2025-03-15T14:45:00.000000Z",
      "published_at": "2025-03-15T15:00:00.000000Z",
      "category": {
        "id": 3,
        "name": "تکنولوژی",
        "slug": "technology"
      },
      "tags": [
        {
          "id": 7,
          "name": "API",
          "slug": "api"
        },
        {
          "id": 12,
          "name": "مستندات",
          "slug": "documentation"
        }
      ],
      "author": {
        "id": 5,
        "name": "جان دو",
        "email": "john.doe@example.com",
        "avatar_url": "https://www.gravatar.com/avatar/abc123.jpg?s=80&d=mp&r=g"
      },
      "view_count": 1250,
      "comment_count": 18,
      "is_featured": true,
      "seo": {
        "meta_title": "عنوان سئو سفارشی",
        "meta_description": "توضیحات سئو سفارشی برای موتورهای جستجو",
        "og_image": "https://example.com/images/og-sample-post.jpg"
      }
    }
  ],
  "meta": {
    "pagination": {
      "total": 98,
      "count": 20,
      "per_page": 20,
      "current_page": 1,
      "total_pages": 5,
      "links": {
        "next": "http://localhost:8080/api/admin/v3/cms/post?includes=category,tags,author&field_sets=%7B%22cms_posts%22%3A%22id%2Ctitle%2Cslug%2Cexcerpt%2Ccontent%2Cfeatured_image%2Cstatus%2Ccreated_at%2Cupdated_at%2Cpublished_at%2Ccategory%2Ctags%2Cauthor%2Cview_count%2Ccomment_count%2Cis_featured%2Cseo%22%7D&search=status%3Apublished&searchFields=status&per_page=20&page=2"
      }
    }
  }
}

ایجاد پست​

ایجاد یک پست جدید در CMS.

درخواست​

POST /api/admin/v3/cms/post HTTP/1.1
Api-Key: {{api-key}}
Content-Type: application/json

بدنه درخواست​

{
  "title": "عنوان مقاله جدید",
  "slug": "new-post-title",
  "excerpt": "این خلاصه برای مقاله جدید است...",
  "content": "این محتوای کامل مقاله جدید است...",
  "featured_image": "https://example.com/images/new-post.jpg",
  "status": "draft",
  "category_id": 3,
  "tag_ids": [7, 12],
  "author_id": 5,
  "is_featured": false,
  "published_at": "2025-04-10T12:00:00Z",
  "seo": {
    "meta_title": "عنوان سئو سفارشی",
    "meta_description": "توضیحات سئو سفارشی برای موتورهای جستجو",
    "og_image": "https://example.com/images/og-new-post.jpg"
  }
}

پاسخ​

{
  "status": true,
  "result": {
    "id": 99,
    "title": "عنوان مقاله جدید",
    "slug": "new-post-title",
    "excerpt": "این خلاصه برای مقاله جدید است...",
    "content": "این محتوای کامل مقاله جدید است...",
    "featured_image": "https://example.com/images/new-post.jpg",
    "status": "draft",
    "created_at": "2025-04-05T19:30:00.000000Z",
    "updated_at": "2025-04-05T19:30:00.000000Z",
    "published_at": "2025-04-10T12:00:00.000000Z",
    "category": {
      "id": 3,
      "name": "تکنولوژی",
      "slug": "technology"
    },
    "tags": [
      {
        "id": 7,
        "name": "API",
        "slug": "api"
      },
      {
        "id": 12,
        "name": "مستندات",
        "slug": "documentation"
      }
    ],
    "author": {
      "id": 5,
      "name": "جان دو",
      "email": "john.doe@example.com",
      "avatar_url": "https://www.gravatar.com/avatar/abc123.jpg?s=80&d=mp&r=g"
    },
    "view_count": 0,
    "comment_count": 0,
    "is_featured": false,
    "seo": {
      "meta_title": "عنوان سئو سفارشی",
      "meta_description": "توضیحات سئو سفارشی برای موتورهای جستجو",
      "og_image": "https://example.com/images/og-new-post.jpg"
    }
  }
}

به‌روزرسانی پست​

به‌روزرسانی یک پست موجود.

درخواست​

PUT /api/admin/v3/cms/post/{post_id} HTTP/1.1
Api-Key: {{api-key}}
Content-Type: application/json

پارامترهای مسیر​

پارامترنوعتوضیحات
post_idintegerشناسه پست

بدنه درخواست​

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

پاسخ​

{
  "status": true,
  "result": {
    "id": 1,
    "title": "عنوان مقاله به‌روزرسانی شده",
    "slug": "updated-post-title",
    "excerpt": "این خلاصه به‌روزرسانی شده مقاله است...",
    "content": "این محتوای کامل به‌روزرسانی شده مقاله است...",
    "featured_image": "https://example.com/images/updated-post.jpg",
    "status": "published",
    "created_at": "2025-03-15T10:30:00.000000Z",
    "updated_at": "2025-04-05T20:15:00.000000Z",
    "published_at": "2025-04-05T20:15:00.000000Z",
    "category": {
      "id": 5,
      "name": "آموزش",
      "slug": "education"
    },
    "tags": [
      {
        "id": 7,
        "name": "API",
        "slug": "api"
      },
      {
        "id": 15,
        "name": "برنامه‌نویسی",
        "slug": "programming"
      }
    ],
    "author": {
      "id": 5,
      "name": "جان دو",
      "email": "john.doe@example.com",
      "avatar_url": "https://www.gravatar.com/avatar/abc123.jpg?s=80&d=mp&r=g"
    },
    "view_count": 1250,
    "comment_count": 18,
    "is_featured": true,
    "seo": {
      "meta_title": "عنوان سئو به‌روزرسانی شده",
      "meta_description": "توضیحات سئو به‌روزرسانی شده برای موتورهای جستجو",
      "og_image": "https://example.com/images/og-updated-post.jpg"
    }
  }
}

دریافت پست​

بازیابی یک پست خاص با شناسه.

درخواست​

GET /api/admin/v3/cms/post/{post_id}?includes=category,tags,author HTTP/1.1
Api-Key: {{api-key}}

پارامترهای مسیر​

پارامترنوعتوضیحات
post_idintegerشناسه پست

پارامترهای پرس‌وجو​

پارامترنوعتوضیحات
includesstringموجودیت‌های مرتبط برای گنجاندن در پاسخ (مثلاً category,tags,author)

پاسخ​

مشابه پاسخ برای به‌روزرسانی پست است.

حذف پست (انتقال به سطل زباله)​

انتقال یک پست به سطل زباله (حذف نرم).

درخواست​

DELETE /api/admin/v3/cms/post/{post_id}/trash HTTP/1.1
Api-Key: {{api-key}}

پارامترهای مسیر​

پارامترنوعتوضیحات
post_idintegerشناسه پست

پاسخ​

{
  "status": true,
  "result": {
    "message": "Post moved to trash successfully"
  }
}

حذف دائمی پست​

حذف دائمی یک پست از پایگاه داده.

درخواست​

DELETE /api/admin/v3/cms/post/{post_id} HTTP/1.1
Api-Key: {{api-key}}

پارامترهای مسیر​

پارامترنوعتوضیحات
post_idintegerشناسه پست

پاسخ​

{
  "status": true,
  "result": {
    "message": "Post deleted permanently"
  }
}

بازیابی پست از سطل زباله​

بازیابی یک پست از سطل زباله.

درخواست​

POST /api/admin/v3/cms/post/{post_id}/restore HTTP/1.1
Api-Key: {{api-key}}

پارامترهای مسیر​

پارامترنوعتوضیحات
post_idintegerشناسه پست

پاسخ​

{
  "status": true,
  "result": {
    "message": "Post restored successfully"
  }
}

عملیات دسته‌ای​

انجام عملیات روی چندین پست به طور همزمان.

درخواست​

POST /api/admin/v3/cms/post/bulk HTTP/1.1
Api-Key: {{api-key}}
Content-Type: application/json

بدنه درخواست​

{
  "ids": [1, 2, 3, 4, 5],
  "action": "trash"  // گزینه‌ها: trash, restore, delete, publish, draft, archive
}

پاسخ​

{
  "status": true,
  "result": {
    "message": "Bulk action completed successfully",
    "affected": 5
  }
}

مدیریت نظرات پست​

لیست نظرات برای یک پست​

GET /api/admin/v3/cms/post/{post_id}/comments?page=1&per_page=20 HTTP/1.1
Api-Key: {{api-key}}

پاسخ​

{
  "status": true,
  "result": {
    "comments": [
      {
        "id": 101,
        "content": "این مقاله بسیار مفید بود!",
        "created_at": "2025-03-16T09:45:00.000000Z",
        "updated_at": "2025-03-16T09:45:00.000000Z",
        "status": "approved",
        "user": {
          "id": 42,
          "name": "سارا احمدی",
          "email": "sara@example.com",
          "avatar_url": "https://www.gravatar.com/avatar/abc123.jpg?s=80&d=mp&r=g"
        },
        "parent_id": null,
        "replies_count": 1
      }
    ],
    "meta": {
      "pagination": {
        "total": 18,
        "count": 1,
        "per_page": 20,
        "current_page": 1,
        "total_pages": 1
      }
    }
  }
}

تأیید نظر​

PUT /api/admin/v3/cms/comment/{comment_id}/approve HTTP/1.1
Api-Key: {{api-key}}

پاسخ​

{
  "status": true,
  "result": {
    "message": "Comment approved successfully"
  }
}

رد نظر​

PUT /api/admin/v3/cms/comment/{comment_id}/reject HTTP/1.1
Api-Key: {{api-key}}

پاسخ​

{
  "status": true,
  "result": {
    "message": "Comment rejected successfully"
  }
}

حذف نظر​

DELETE /api/admin/v3/cms/comment/{comment_id} HTTP/1.1
Api-Key: {{api-key}}

پاسخ​

{
  "status": true,
  "result": {
    "message": "Comment deleted successfully"
  }
}

پاسخ‌های خطا​

یافت نشد (404)​

{
  "status": false,
  "error": {
    "message": "Post not found",
    "code": "resource_not_found"
  }
}

خطای اعتبارسنجی (422)​

{
  "status": false,
  "error": {
    "message": "Validation failed",
    "errors": {
      "title": [
        "عنوان مقاله الزامی است."
      ],
      "content": [
        "محتوای مقاله الزامی است."
      ]
    },
    "code": "validation_failed"
  }
}

خطای احراز هویت (401)​

{
  "status": false,
  "error": {
    "message": "Unauthenticated",
    "code": "authentication_required"
  }
}

خطای مجوز (403)​

{
  "status": false,
  "error": {
    "message": "You do not have permission to perform this action",
    "code": "permission_denied"
  }
}
آخرین به روز رسانی در تاریخ توسط Behnam Moradi