clinicpro/docs/api/tag.md

Tag API

Prefix: /api/v1/tags, /api/v1/admin/tag

Tags are used for categorizing blog posts.

---

GET /api/v1/tags

List all active tags.

Permission: PUBLIC

Response 200

{
  "success": true,
  "data": [
    { "id": 1, "name": "دیابت", "slug": "diabat", "status": "active" },
    { "id": 2, "name": "قلب", "slug": "ghalb", "status": "active" }
  ]
}

---

GET /api/v1/admin/tags

List all tags with pagination (admin view — includes inactive).

Permission: ROLE_ADMIN

Query Parameters

Param	Type	Required	Description
page	integer	❌	Default: 1
limit	integer	❌	Default: 20
search	string	❌	Matches name or slug (case-insensitive LIKE). Tags have no parent.

Response 200

{
  "success": true,
  "data": [ ... ],
  "meta": { "totalRecords": 10, "totalPages": 1, "currentPage": 1 }
}

Errors

Code	HTTP	Description
ERR_AUTH_001	401	Missing token
ERR_AUTH_006	403	Not admin

---

POST /api/v1/admin/tag

Create a new tag.

Permission: ROLE_ADMIN

Request Body (application/json)

{
  "name": "دیابت",
  "slug": "diabat",
  "status": "active"
}

Field	Type	Required	Description
name	string	✅	Tag name
slug	string	❌	Auto-generated from name if omitted
status	string	❌	"active" (default) or "inactive"

Response 201

Tag object.

Errors

Code	HTTP	Description
ERR_AUTH_001	401	Missing token
ERR_AUTH_006	403	Not admin
ERR_VALIDATION_002	422	Missing name

---

PATCH /api/v1/admin/tag/{id}

Update a tag.

Permission: ROLE_ADMIN

Path Parameters

Param	Type	Description
id	integer	Tag ID

All fields optional.

Response 200

Updated tag object.

Errors

Code	HTTP	Description
ERR_AUTH_001	401	Missing token
ERR_AUTH_006	403	Not admin
ERR_NOT_FOUND_001	404	Tag not found

---

DELETE /api/v1/admin/tag/{id}

Delete a tag.

Permission: ROLE_ADMIN

Response 200

{ "success": true, "data": { "message": "تگ حذف شد" } }

Errors

Code	HTTP	Description
ERR_AUTH_001	401	Missing token
ERR_AUTH_006	403	Not admin
ERR_NOT_FOUND_001	404	Tag not found

---

Bulk import / export

Full-table JSON export and strict wipe+replace import for this category live under /api/v1/admin/categories/{bundle}/{export|import} — see category-import.md.

Sorting by id

The admin list endpoint accepts sort=id&order=asc|desc to order by id (used by the admin «دسته‌بندی‌ها» page when clicking the «شناسه» column). Without sort, the default ordering (weight/name) is unchanged.

---

برچسب‌های Tenant (doctor/clinic)

برچسب‌های اختصاصیِ هر tenant با رنگ نمایش — جدا از taxonomy سراسری بالا. همه به entity کاربر (doctor/clinic) scope می‌شوند؛ هر tenant فقط برچسب‌های خودش را می‌بیند/تغییر می‌دهد.

Permission: IS_AUTHENTICATED_FULLY (doctor/clinic/secretary)

GET /api/v1/tenant-tags

لیست برچسب‌های tenant جاری. Response: { success, data: [{ uuid, name, color, active }] }

POST /api/v1/tenant-tag

{ "name": "فوری", "color": "#FF0000", "active": true }

Field	Type	Required	Validation
name	string	✅	غیرخالی، حداکثر ۶۰
color	string	❌	هگز #RRGGBB یا #RRGGBBAA (پیش‌فرض #5559CE)
active	bool	❌	وضعیت اولیه (پیش‌فرض true)

Response 201: TenantTag object.

PATCH /api/v1/tenant-tag/{uuid}

فیلدهای اختیاری name / color / active. فقط مالک؛ در غیر این صورت 404.

DELETE /api/v1/tenant-tag/{uuid}

حذف برچسب. فقط مالک؛ در غیر این صورت 404.

Errors

HTTP	Code	field	Description
422	ERR_VALIDATION_001	name	نام خالی
422	ERR_VALIDATION_001	color	رنگ نامعتبر
404	ERR_NOT_FOUND_001	—	برچسب یافت نشد یا متعلق به tenant دیگر
403	ERR_FORBIDDEN_001	—	پروفایل tenant یافت نشد