Xác thực bằng API key

9 phút đọc

Trang này hướng dẫn cách xác thực với hệ thống Ferry bằng API key, bao gồm cách truyền header, cấu trúc định dạng khoá, quy trình tạo và xoay khoá an toàn, cùng cách phân biệt các mã lỗi xác thực.

Cách gửi khoá

Mọi yêu cầu gửi tới các endpoint thuộc tầng đối tác phải đính kèm API key trong header HTTP theo định dạng chuẩn Bearer:

Authorization: Bearer <API_KEY>

Hệ thống Ferry chỉ đọc header Authorization. Các header khác không có hiệu lực xác thực.

Định dạng khoá

Một chuỗi API key hoàn chỉnh gồm 3 phần nối với nhau bằng dấu gạch dưới (_):

Tiền tố hệ thống: Chuỗi tiền tố do Ferry cấu hình theo từng môi trường kết nối. Đối tác không cần phân tích hay tách tiền tố, chỉ cần gửi nguyên văn chuỗi khoá được cấp.
Mã định danh khoá: Chuỗi hex 24 ký tự dùng để xác định bản ghi khoá trong hệ thống.
Phần bí mật: Chuỗi hex 64 ký tự được sinh ngẫu nhiên an toàn.

Tài liệu này không in chuỗi khoá mẫu. Đối tác luôn gửi nguyên văn chuỗi khoá được cấp, không cắt bớt, không tự ghép thêm tiền tố và không thay đổi bất kỳ ký tự nào. Sơ đồ dưới đây cho thấy luồng xác thực và phân quyền một yêu cầu API:

sequenceDiagram
    autonumber
    participant Partner as Hệ thống đối tác
    participant Gateway as Cổng API Ferry
    participant Auth as Lớp xác thực khoá
    participant Perm as Lớp kiểm tra quyền
    participant Core as Lớp nghiệp vụ
    Partner->>Gateway: Gửi yêu cầu kèm header Authorization
    Gateway->>Auth: Kiểm tra tính hợp lệ của khoá
    alt Thiếu header hoặc khoá không hợp lệ
        Auth-->>Partner: 401 Unauthorized (khoá không hợp lệ)
    else Khoá hợp lệ
        Auth->>Perm: Chuyển thông tin tổ chức và vai trò
        alt Thiếu quyền hoặc lớp phân quyền lỗi tạm thời
            Perm-->>Partner: 403 Forbidden (Access denied)
        else Đủ quyền
            Perm->>Core: Thực thi nghiệp vụ
            Core-->>Partner: 200 OK kèm dữ liệu phản hồi
        end
    end

Ai tạo khoá và cách tạo

Đối tác không thể tạo API key thông qua các endpoint API. Quyền tạo khoá được giới hạn cho người dùng có vai trò quản trị viên (admin) của tổ chức đại lý trên giao diện web Dashboard.

Các bước tạo khoá trên Dashboard:

Quản trị viên đăng nhập vào Dashboard đại lý, mở menu Cài Đặt và chuyển sang tab API Keys, sau đó nhấn nút Thêm mới.

Mục API Keys trong phần Cài đặt trên Dashboard với nút Thêm mới

Nhập tên gợi nhớ cho khoá (ví dụ tên dịch vụ kết nối) trong hộp thoại rồi nhấn Tạo mới.

Hộp thoại đặt tên khoá và nhấn Tạo mới API Key

Hộp thoại thông báo tạo khoá thành công xuất hiện. Nhấn biểu tượng sao chép để lưu lại chuỗi khoá vào nơi an toàn.

Hộp thoại sao chép chuỗi API Key vừa tạo kèm cảnh báo lưu trữ

Chi tiết hướng dẫn thao tác trên Dashboard xem tại Quản lý API Key trên Dashboard.

Vòng đời và đặc tính của khoá

API key của Ferry có các đặc điểm kỹ thuật sau:

Không bao giờ hết hạn: Khoá không có thời hạn hiệu lực tự động. Một khi đã tạo, khoá có giá trị vô thời hạn cho đến khi quản trị viên chủ động thu hồi.
Thu hồi có hiệu lực ngay: Khi quản trị viên nhấn xoá khoá trên Dashboard, bản ghi khoá bị xoá hoàn toàn khỏi cơ sở dữ liệu. Lệnh gọi tiếp theo sử dụng khoá này sẽ nhận mã lỗi 401 ngay lập tức.
Không có trạng thái vô hiệu hoá tạm thời: Hệ thống không hỗ trợ tạm dừng khoá rồi kích hoạt lại. Bạn chỉ có hai trạng thái: đang hoạt động hoặc đã bị xoá vĩnh viễn.

Quyền hạn của API key

Mỗi API key gắn liền với một tổ chức đại lý duy nhất và đại diện cho quyền hạn của tổ chức đó:

Nhóm nghiệp vụ	Năng lực của API key
Đặt vé và hành khách	Tạo booking giữ chỗ, xác nhận xuất vé điện tử, tra cứu và cập nhật đơn
Lịch chạy và chuyến	Tra cứu lịch chạy, xem sơ đồ ghế và kiểm tra số chỗ còn trống
Dòng tiền và công nợ	Xem lịch sử giao dịch, tra cứu bút toán công nợ và số dư khả dụng
Giá vé và ưu đãi	Xem quy tắc phụ thu, kiểm tra điều kiện áp dụng voucher giảm giá
Khách hàng và đại lý con	Quản lý thông tin khách hàng, công ty và quản lý các tổ chức đại lý cấp dưới
Huỷ vé	Gửi yêu cầu huỷ vé tới hãng tàu

Các giới hạn và rủi ro phân quyền quan trọng:

Không có phạm vi quyền riêng lẻ (scope): Không có khoá dành riêng cho việc “chỉ đọc” hoặc khoá bị giới hạn trong một module. Khoá mang đầy đủ quyền thao tác nghiệp vụ của đại lý.
Rủi ro xoá tổ chức con: Quyền của khoá bao gồm cả việc tạo, sửa và xoá các tổ chức con thuộc chuỗi đại lý. Một khoá bị rò rỉ có thể bị kẻ xấu lợi dụng để xoá tổ chức con nếu gọi lệnh xoá tổ chức.
Không truy cập được vùng nội bộ: API key không thể thực hiện các thao tác quản trị hệ thống của Ferry hoặc các tính năng yêu cầu phiên người dùng JWT trên Dashboard.
Hiện tượng thiếu trường dữ liệu trong phản hồi: API key được hệ thống xếp vào nhóm vai trò api-key. Dữ liệu trả về chỉ hiển thị những trường được khai báo cho nhóm này. Nếu bạn thấy trên Dashboard hiển thị một trường dữ liệu (ví dụ giá chi tiết hay chiết khấu) nhưng phản hồi API lại không có (dù trả về HTTP 200), nguyên nhân là trường đó chưa được khai báo cho nhóm api-key. Đây không phải lỗi thiếu quyền (không trả về 403); bạn không thể khắc phục bằng tham số truy vấn mà cần liên hệ Ferry để bổ sung khai báo.

Quy trình xoay khoá an toàn

Do thao tác thu hồi khoá có hiệu lực ngay lập tức, việc đổi khoá đang sử dụng trên hệ thống phải tuân thủ nghiêm ngặt quy trình 4 bước sau để không làm gián đoạn dịch vụ:

Tạo khoá mới: Quản trị viên đại lý tạo một API key mới trên Dashboard. Trong lúc này, khoá cũ vẫn tiếp tục phục vụ các yêu cầu bình thường.
Cập nhật máy chủ: Nạp chuỗi khoá mới vào cấu hình biến môi trường trên toàn bộ các cụm máy chủ backend của đối tác và tiến hành triển khai lại.
Xác nhận lưu lượng: Theo dõi hệ thống để đảm bảo 100% các tiến trình và tác vụ nền đã chuyển sang gửi yêu cầu bằng khoá mới thành công.
Thu hồi khoá cũ: Quản trị viên đại lý đăng nhập Dashboard và xoá khoá cũ để hoàn tất chu kỳ xoay khoá.

Trong trường hợp khoá bị lộ nghi ngờ có sự xâm nhập, bạn cần chấp nhận gián đoạn ngắn: thực hiện xoá khoá cũ ngay lập tức, sau đó mới tạo khoá mới và triển khai lên hệ thống.

Ý nghĩa các mã lỗi xác thực

Khi gửi yêu cầu với API key, bạn có thể nhận được hai mã trạng thái HTTP liên quan đến xác thực và phân quyền:

Mã HTTP	Ý nghĩa kỹ thuật	Nguyên nhân thường gặp	Hướng xử lý
401 Unauthorized	Khoá không hợp lệ	Thiếu header `Authorization`, sai tiền tố `Bearer`, sai chuỗi khoá, hoặc khoá đã bị thu hồi	Kiểm tra lại cú pháp header; dán lại chuỗi khoá nguyên văn; xin cấp khoá mới nếu khoá cũ đã bị xoá
403 Forbidden	Từ chối truy cập (`Access denied`)	(1) Khoá không đủ quyền trên endpoint (endpoint nội bộ hoặc ngoài danh mục mở cho đối tác); (2) Lớp phân quyền của Ferry đang gặp sự cố kết nối tạm thời	Nếu gọi endpoint mới: đối chiếu xem có thuộc 86 route của tầng partner không. Nếu lỗi xuất hiện bất thường trên endpoint vốn đang chạy: thử lại có giới hạn; nếu không hết, liên hệ Ferry

Lưu ý quan trọng:

Phản hồi 401 trả về cùng một thông điệp và không chỉ rõ chi tiết lỗi (sai định dạng, sai phần bí mật hay khoá không tồn tại) nhằm đảm bảo an ninh.
Phản hồi 403 trả về cùng một thông điệp Access denied cho cả hai trường hợp: khoá thực sự thiếu quyền, hoặc lớp phân quyền của hệ thống đang gặp lỗi tạm thời. Mã chẩn đoán chi tiết chỉ ghi vào log nội bộ của Ferry. Do đó, nếu 403 xuất hiện đột ngột trên các lệnh gọi vốn đang hoạt động bình thường, hãy thực hiện thử lại có giãn cách ngắn (exponential backoff) trước khi kết luận là quyền bị thay đổi.

Sai lầm thường gặp

Hiểu nhầm	Thực tế	Cách xử lý đúng
Gửi khoá qua header khác	Ferry chỉ đọc duy nhất header `Authorization`	Luôn cấu hình header `Authorization: Bearer <key>`
Nhúng khoá vào ứng dụng di động hoặc web	Khoá có toàn quyền quản lý dữ liệu đại lý	Lưu khoá an toàn trên máy chủ backend
Xoá khoá cũ trước khi cấu hình khoá mới	Thao tác xoá có hiệu lực tức thì, gây đứt gãy dịch vụ	Tạo khoá mới, triển khai xong xuôi mới xoá khoá cũ
Cho rằng khoá sẽ tự hết hạn	Khoá không có hạn sử dụng	Tự xây dựng chính sách xoay khoá định kỳ nội bộ
Nghĩ rằng 403 luôn là do khoá bị thu hồi quyền	403 cũng là mã trả về khi lớp phân quyền của Ferry gặp sự cố tạm thời	Thử lại có giới hạn; nếu lỗi kéo dài thì liên hệ vận hành Ferry
Nghĩ rằng thiếu trường dữ liệu trong phản hồi là do thiếu quyền	Nhiều trường chưa được bật hiển thị cho nhóm vai trò `api-key`	Báo Ferry bổ sung khai báo trường cho vai trò API key

Tra ở đâu trên Scalar

Trang này tương ứng với nút Authorize ở góc trên cùng của cổng tài liệu Scalar UI — Ferry VN API.

Để thử nghiệm các endpoint trên giao diện Scalar:

Nhấn nút Authorize.
Dán chuỗi API key của bạn vào ô xác thực Bearer token.
Thử nghiệm với các endpoint đọc đơn giản như nhóm Voyages hoặc Bookings để xác nhận khoá hoạt động.

Đọc tiếp

Trang	Nội dung nên đọc tiếp
Tổng quan bề mặt tích hợp	Xem ranh giới quyền hạn và danh sách nhóm nghiệp vụ mở cho đối tác
Môi trường	Quản lý khoá API giữa môi trường UAT và Production
Quy ước chung	Quy chuẩn phân trang, định dạng ngày giờ và xử lý lỗi
Quản lý API Key trên Dashboard	Hướng dẫn thao tác giao diện Dashboard dành cho quản trị viên đại lý