Thiên Kim Wine API v1

REST API 19 endpoints - Backend Laravel 12 + Frontend Next.js 15

REST API Documentation

19 endpoints RESTful với JSON response, filter, sort, pagination, tracking, cache management.

Quick Start

Base URL

http://localhost:8000/api/v1

Frontend

http://localhost:3000

Auth

Hầu hết endpoints public không cần auth

Response

JSON với HATEOAS links

Tổng Quan

Thiên Kim Wine API cung cấp 19 endpoints quản lý sản phẩm, bài viết, menus, settings, tracking.

Authentication

Hầu hết endpoints public không yêu cầu xác thực.

Header (nếu cần auth):

Authorization: Bearer YOUR_TOKEN

Health & System

GET
/health

System health status

Response: { "status": "OK", "database": true, "cache": true }

Products

GET
/san-pham

Danh sách sản phẩm (filter, sort, pagination)

Parameters:

Field Kiểu Mô Tả
q string Tìm kiếm theo tên
brand int ID thương hiệu
price_min, price_max int Khoảng giá
sort string price, name, created_at (thêm - để giảm dần)
page, per_page int Pagination (mặc định 24/trang)

Ví Dụ:

GET /api/v1/san-pham?q=bordeaux&brand=5&price_max=5000000&sort=-price&page=1&per_page=24
GET
/san-pham/{slug}

Chi tiết sản phẩm

Response:

{
  "data": {
    "id": 1,
    "name": "Rượu Vang Đỏ Bordeaux",
    "slug": "ruou-vang-do-bordeaux",
    "price": 2500000,
    "vintage": 2015,
    "description": "...",
    "gallery": [...],
    "brand": { ... },
    "origin": { ... },
    "wine_type": { ... }
  },
  "_links": { "self": { "href": "..." } }
}

Articles

GET
/bai-viet

Danh sách bài viết (pagination)

Query: page, per_page (mặc định 12/trang)

GET
/bai-viet/{slug}

Chi tiết bài viết

Home

GET
/home

Homepage components (carousel, featured products, banners)

Social Links

GET
/social-links

Facebook, Instagram, YouTube, Zalo... (ở footer)

Response:

[
  {
    "id": 1,
    "platform": "facebook",
    "url": "https://facebook.com/wincellar",
    "icon_url": "/storage/icons/facebook.svg",
    "order": 1
  },
  ...
]

Tracking & Analytics

GET
/track/generate-id

Generate UUID cho anonymous tracking (call 1 lần first visit)

Response:

{
  "success": true,
  "data": {
    "anon_id": "550e8400-e29b-41d4-a716-446655440000"
  }
}
POST
/track/visitor

Track visitor session

Body:

Field Bắt Buộc
anon_id Required
user_agent Optional
POST
/track/event

Track events: product_view, article_view, cta_contact

Body:

{
  "anon_id": "550e8400-e29b-41d4-a716-446655440000",
  "event_type": "product_view",
  "product_id": 123,
  "metadata": {
    "referrer": "/san-pham",
    "page_url": "/san-pham/ruou-vang-do"
  }
}
Event Types: product_view, article_view, cta_contact

Settings

GET
/settings

Site info: logo, favicon, watermark sản phẩm (url + vị trí + kích thước), hotline, email, địa chỉ, meta defaults

Response:

{
  "data": {
    "id": 1,
    "site_name": "Wincellar Clone",
    "hotline": "0123 456 789",
    "address": "123 Đường ABC, Quận 1, TP.HCM",
    "hours": "8:00 - 22:00",
    "email": "contact@wincellar.com",
    "logo_url": "/storage/images/logo.png",
    "favicon_url": "/storage/images/favicon.ico",
    "product_watermark_url": "/storage/images/watermark.png",
    "product_watermark_position": "none",
    "product_watermark_size": "128x128",
    "meta_defaults": {
      "title": "Thiên Kim Wine - Cửa Hàng Rượu Vang",
      "description": "Chuyên cung cấp rượu vang nhập khẩu",
      "keywords": "rượu vang, wine"
    }
  },
  "meta": {
    "cache_version": 15
  }
}
Cache: 1 giờ | Auto-invalidate khi admin update