Author: Admin Me

Khi xây dựng một ứng dụng khám phá và xem phim, phần khó không chỉ là gọi API. Dữ liệu catalog, trang chi tiết, ảnh và danh sách tập có thể có cấu trúc khác nhau; trong khi giao diện web và mobile lại cần dùng chung một mô hình ổn định.

Trong CineFlow, package @cineflow/movies gom client gọi KKPhim, kiểu dữ liệu và bước chuẩn hóa response. Bài viết này ghi lại các endpoint và quy ước mà implementation hiện tại đang dùng. Đây là tài liệu dựa trên code CineFlow, không phải cam kết rằng mọi tham số hay response đều là đặc tả chính thức, bất biến của KKPhim.

Base URL và cấu hình

Base URL mặc định là https://phimapi.com. CineFlow cho phép thay bằng biến môi trường theo nền tảng:

NEXT_PUBLIC_KKPHIM_API_URL=https://phimapi.com
EXPO_PUBLIC_KKPHIM_API_URL=https://phimapi.com

Ảnh được ghép từ base CDN trong response nếu có; fallback hiện dùng https://phimimg.com. Nếu giá trị ảnh đã là URL đầy đủ, client giữ nguyên URL đó.

Endpoint catalog

Các endpoint danh sách dùng tiền tố /v1/api:

Nhu cầu	Endpoint
Danh sách mới / trang chủ	GET /v1/api/danh-sach
Danh sách theo loại	GET /v1/api/danh-sach/{slug}
Theo thể loại	GET /v1/api/the-loai/{slug}
Theo quốc gia	GET /v1/api/quoc-gia/{slug}
Theo năm	GET /v1/api/nam/{year}
Tìm kiếm	GET /v1/api/tim-kiem

Client luôn đưa page lên URL và bảo đảm giá trị tối thiểu là 1. Các tham số tùy chọn được hỗ trợ trong request builder gồm:

Tham số	Ý nghĩa trong CineFlow
page	Trang cần lấy, mặc định 1
limit	Số mục yêu cầu trên một trang
keyword	Từ khóa tìm kiếm
type	Lọc loại nội dung trên các request không phải search
category, country, year	Điều kiện lọc catalog
sort_field	Trường sắp xếp: modified.time, _id hoặc year
sort_type	asc hoặc desc
sort_lang	Ngôn ngữ: vietsub, thuyet-minh hoặc long-tieng

Ví dụ theo đúng cách ghép URL của client:

GET https://phimapi.com/v1/api/danh-sach/phim-bo?page=1&limit=24&sort_field=modified.time&sort_type=desc
GET https://phimapi.com/v1/api/the-loai/hanh-dong?page=2
GET https://phimapi.com/v1/api/tim-kiem?page=1&keyword=mat

Tìm kiếm không gửi type lên API. Nếu ứng dụng cần lọc kết quả tìm kiếm theo loại, CineFlow lọc sau khi chuẩn hóa response. Các loại giao diện như phim-le, phim-bo, hoat-hinh được ánh xạ sang giá trị type dữ liệu tương ứng; phim chiếu rạp được lọc theo cờ chieurap.

Lấy chi tiết phim và taxonomy

Chi tiết phim lấy theo slug:

GET /phim/{slug}

Các danh mục hỗ trợ bộ lọc được lấy từ:

GET /the-loai
GET /quoc-gia
GET /nam-phat-hanh

CineFlow gọi ba taxonomy song song. Nếu một request lỗi, danh sách tương ứng được trả về rỗng; riêng danh sách năm dùng dải năm fallback khi API không trả dữ liệu dùng được.

Những trường dữ liệu CineFlow đọc

Response catalog thường được đọc từ data.items (có fallback sang items ở cấp ngoài). Pagination được tìm trong data.params.pagination, data.pagination hoặc pagination. Từ các trường pagination hiện có, client tạo một cấu trúc thống nhất gồm currentPage, pageSize, totalItems và totalPages.

Một mục phim được chuẩn hóa thành các trường ứng dụng như:

• Định danh và tên: _id/id, name, origin_name, slug, type.
• Hình ảnh và thông tin phát hành: poster_url, thumb_url, year, time.
• Trạng thái tập: episode_current, episode_total, cùng season nếu có.
• Phân loại: category, country, quality, lang.
• Điểm đánh giá: tmdb, imdb; client đọc cả dạng snake_case và camelCase cho điểm/số lượt bình chọn.
• Cờ hiển thị: chieurap, sub_docquyen; thời gian cập nhật từ modified.time hoặc modified_at.

Client chấp nhận một số giá trị số được gửi dưới dạng chuỗi và chuyển chúng về number khi hợp lệ. Trường tùy chọn thiếu hoặc sai kiểu không làm hỏng toàn bộ catalog; các helper trả về giá trị an toàn hoặc null.

Chi tiết phim bổ sung content, status, trailer_url, actor, director, notify, showtimes, view và is_copyright. Phần giới thiệu (content) có thể chứa HTML; khi hiển thị dạng văn bản, CineFlow có helper loại thẻ và giải mã một số HTML entity phổ biến.

Cấu trúc server và tập phim

Response chi tiết chứa danh sách server ở episodes (hoặc trường tương ứng trong metadata phim). Mỗi server được đọc từ server_name và server_data; client cũng hỗ trợ các tên thay thế name và episodes.

Mỗi tập có các trường chính:

Trường nguồn	Trường đã chuẩn hóa
name	name
slug	slug
filename	filename
link_embed	embedUrl
link_m3u8	m3u8Url

Client bỏ qua tập không có cả link embed lẫn link M3U8. Player HLS dùng m3u8Url; URL trả về là nguồn do API cung cấp, và khả năng phát còn phụ thuộc trạng thái của nguồn/CDN cùng khả năng tương thích thiết bị.

Luồng gọi và chuẩn hóa

Luồng dữ liệu có thể tóm tắt như sau:

1. Tạo URL từ loại trang, slug và các tham số lọc.
2. Gọi fetch với AbortSignal nếu caller truyền vào.
3. Nếu HTTP response không thành công, ném lỗi có status để lớp gọi quyết định cách hiển thị.
4. Đọc JSON dưới dạng dữ liệu chưa tin cậy, kiểm tra object/array và chuẩn hóa vào các type dùng chung.
5. UI web và mobile tiêu thụ cùng domain model thay vì tự đọc các biến thể response thô.

Trong package API client, request không thêm custom header. Các tính năng ứng dụng riêng—như xác thực, entitlement hoặc lưu tiến độ xem—nằm ở lớp CineFlow và không nên nhầm với endpoint catalog của KKPhim.

Những điểm cần kiểm tra khi cập nhật tích hợp

• Xác nhận endpoint và slug còn hoạt động trước khi thêm loại danh sách mới.
• Kiểm tra response thực tế khi API đổi cách bọc data, pagination hoặc trường ảnh.
• Không giả định mọi phim đều có TMDB/IMDB, năm, poster hay link phát.
• Giữ bước normalize ở một nơi để web và mobile không lệch cách hiểu dữ liệu.
• Xử lý riêng lỗi mạng, HTTP error và link tập bị thiếu; đừng coi response JSON hợp lệ đồng nghĩa nội dung luôn phát được.
• Trước khi phát hành sản phẩm công khai hoặc thương mại, tự xác minh quyền sử dụng dữ liệu, hình ảnh, video và điều khoản của nhà cung cấp.

Tài liệu này phản ánh cách CineFlow đang sử dụng KKPhim: endpoint catalog và chi tiết được gom trong client dùng chung, response được chuẩn hóa thành model nội bộ, còn giao diện chỉ làm việc với các trường đã ổn định hơn. Khi API thay đổi, nên cập nhật phần mapping và ví dụ dựa trên response quan sát được thay vì dựa vào giả định.