Quy Trình Tích Hợp API C4
# 1. Lộ trình Tổng quan
# 1.1 Giới thiệu Tổng quan Quy trình Tích hợp API C4
Quy trình Tích hợp Hệ thống API C4 được thiết kế theo lộ trình chuẩn hóa, chặt chẽ qua 5 bước chính, nhằm đảm bảo sự hợp tác hiệu quả và triển khai hệ thống một cách bảo mật, ổn định. Mục tiêu là giúp các Đại lý F1 (Đối tác) nhanh chóng kích hoạt và sử dụng các dịch vụ API của JTHT.
# 1.2 Tổng quan 5 Giai đoạn
- Kinh doanh/Hợp đồng: Thiết lập khung pháp lý, ký kết hợp đồng và xác định Tier Level (Enterprise, Premium, Standard, Basic) để định rõ phạm vi quyền truy cập API.
- Cấu hình Ban đầu: Phối hợp nhân sự IT để thu thập thông tin kỹ thuật, thiết lập Portal quản trị, cấu hình bảo mật Whitelist IP và chuẩn bị bộ API Credentials (Key, Token).
- Tích hợp & Kiểm thử (Sandbox/UAT): Đại lý nhận tài liệu và môi trường thử nghiệm (Sandbox), thực hiện tích hợp, chạy bộ Test Case chuẩn. Giai đoạn này kết thúc bằng việc ký biên bản Nghiệm thu UAT.
- Triển khai & Vận hành (Go-live): Cấp Credentials Production và chuyển sang môi trường thật. JTHT thực hiện Giám sát Đặc biệt trong 1-2 tuần đầu để đảm bảo hệ thống vận hành trơn tru.
- Bàn giao Vận hành Chính thức: Sau khi hệ thống ổn định, chính thức chuyển sang chế độ hỗ trợ và vận hành định kỳ theo hợp đồng.
Quy trình này đảm bảo mỗi Đại lý được cấp quyền truy cập phù hợp với cấp độ (Tier Level) của mình, được bảo vệ bằng các lớp bảo mật như Whitelist IP, và được hỗ trợ đầy đủ qua môi trường Sandbox trước khi Go-live.
# 1.3 Sơ đồ Quy trình kích hoạt Đại lý F1
# 1.4 Bảng mô tả Sơ đồ Quy trình Kích hoạt Đại lý F1
# Các Giai đoạn Chính
| Giai đoạn | Hoạt động | Vai trò Chính |
|---|---|---|
| Kinh doanh/Hợp đồng | Ký Hợp đồng & Xác định Tier Level (Enterprise/Premium/Standard/Basic). | Sales/Kinh doanh |
| Cấu hình Ban đầu | Phối hợp Nhân sự, Cấu hình Portal & Whitelist IP, Cấp API. | IT/Kỹ thuật |
| Tích hợp & Kiểm thử | Cấp Tài liệu & Sandbox, Đại lý Dev & Test, Nghiệm thu UAT. | Đại lý/Kỹ thuật/QA |
| Triển khai & Vận hành | Go-live, Giám sát 1-2 tuần đầu. | Vận hành (Operations) |
# 2. Quy trình Kích hoạt Đại lý F1
# Bước 1: Ký hợp đồng nguyên tắc
Đây là bước khởi đầu và bắt buộc trước khi thực hiện bất kỳ hoạt động kỹ thuật nào liên quan đến việc cấp phát API credentials. Nội dung bao gồm:
- Ký kết hợp đồng nguyên tắc giữa đại lý và JTHT.
- Hai bên thống nhất các điều khoản hợp tác, phạm vi dịch vụ và trách nhiệm pháp lý.
- Hợp đồng là cơ sở pháp lý cho việc cấp quyền truy cập hệ thống.
# Xác định Tier Level của Đại lý
Dựa trên hồ sơ, năng lực kinh doanh và gói dịch vụ mà đại lý đăng ký. Các cấp độ hiện có:
- Enterprise – Quyền truy cập toàn diện, ưu tiên cao nhất.
- Premium – Quyền truy cập nâng cao, hỗ trợ đa dịch vụ.
- Standard – Quyền truy cập cơ bản cho các dịch vụ phổ biến.
- Basic – Quyền truy cập giới hạn, phù hợp thử nghiệm hoặc đại lý nhỏ.
# Thỏa thuận phạm vi quyền truy cập API services
- Xác định rõ nhóm API mà đại lý được phép sử dụng theo tier: đặt chỗ, thanh toán, quản lý đơn hàng, báo cáo…
- Đảm bảo đại lý hiểu và tuân thủ chính sách sử dụng API (rate limit, bảo mật, quản lý dữ liệu).
- Lập phụ lục hợp đồng (nếu cần) để ghi nhận phạm vi dịch vụ và quyền truy cập chi tiết.
# Bước 2: Phối hợp nhân sự IT
Chuẩn hóa việc phối hợp giữa JTHT và đại lý F1 để thu thập thông tin kỹ thuật, thiết lập portal, cấu hình bảo mật, và sinh sẵn (stage) bộ credentials trên hệ thống C4, sẵn sàng bàn giao ở Bước 3.
# Sơ đồ Phối hợp nhân sự IT
# Bảng mô tả Quy trình Phối hợp Nhân sự IT (Tích hợp)
# 1. Vai trò: Đại lý (F1/Đối tác)
| Thành phần | Mô tả |
|---|---|
| Xác nhận phạm vi API | Đại lý xác định rõ ràng các API, module, và phạm vi nghiệp vụ cần tích hợp để làm cơ sở cho việc khởi động dự án. |
| Cung cấp thông tin kỹ thuật | Gửi các thông tin cần thiết cho việc cấu hình và bảo mật, bao gồm: IP, Email, Domain sử dụng. |
| Nhận thông tin bàn giao | Tiếp nhận các thông tin cấu hình đã hoàn tất từ JTHT, bao gồm Credentials, Portal, phân quyền, Whitelist đã áp dụng. |
# 2. Vai trò: Đội ngũ JTHT (IT & Vận hành)
| Thành phần | Mô tả |
|---|---|
| Kickoff Kỹ thuật | Buổi họp khởi động chung giữa hai bên để thống nhất yêu cầu kỹ thuật chi tiết, thời gian biểu và các thông số tích hợp. (Liên kết với bước xác nhận phạm vi của Đại lý). |
| Thiết lập Portal & Phân quyền | Tiến hành tạo tài khoản truy cập (Portal) và cấp quyền (User role) phù hợp cho đội ngũ Đại lý, áp dụng cho các môi trường (Dev, UAT, Production). |
| Cấu hình Whitelist/Security | Áp dụng các biện pháp bảo mật dựa trên thông tin Đại lý cung cấp, bao gồm: Whitelisting IP/Domain và thiết lập các rule bảo mật liên quan. |
| Sinh & Mã hóa Credentials | Tạo ra các API Credentials (Key, Secret, v.v.), tiến hành mã hóa bảo mật, và chuẩn bị để bàn giao chính thức. |
# 3. Luồng công việc (Tổng quan)
| Bước | Bên thực hiện | Mô tả | Chi tiết tương tác |
|---|---|---|---|
| 1 | Đại lý | Xác nhận phạm vi API. | Hoạt động nội bộ của Đại lý trước khi Kickoff. |
| 2 | JTHT | Kickoff Kỹ thuật. | Thống nhất yêu cầu dựa trên phạm vi API đã xác nhận. |
| 3 | Đại lý | Cung cấp thông tin kỹ thuật (IP, Email, Domain). | Dữ liệu đầu vào cho việc cấu hình bảo mật. |
| 4 | JTHT | Thiết lập Portal & Phân quyền. | Cấu hình quyền truy cập dựa trên nhu cầu của Đại lý. |
| 5 | JTHT | Cấu hình Whitelist/Security. | Áp dụng bảo mật dựa trên thông tin IP, Domain. |
| 6 | JTHT | Sinh & Mã hóa Credentials. | Chuẩn bị thông tin truy cập quan trọng. |
| 7 | JTHT | Nhận thông tin bàn giao. | Bàn giao Credentials và các thông số cấu hình đã hoàn tất. |
# Bước 3: Cấp thông tin xác thực (API Credentials)
Sau khi đã hoàn tất việc phối hợp kỹ thuật và xác minh thông tin từ phía đại lý, JTHT sẽ tiến hành cấp phát thông tin xác thực (API Credentials) để đại lý có thể bắt đầu kết nối và thử nghiệm hệ thống.
# Các hoạt động chính
Tạo và quản lý thông tin xác thực JTHT khởi tạo bộ thông tin API dành riêng cho đại lý. Bao gồm 03 trường chính:
- x-api-account: Tài khoản đăng nhập Portal quản trị.
- x-api-password: Mật khẩu đăng nhập Portal.
- x-api-token: Token truy cập hệ thống API (có thời hạn và cơ chế làm mới).
Phân quyền & chính sách truy cập
- Quyền truy cập API được cấu hình dựa trên tier đại lý (Enterprise / Premium / Standard / Basic).
- Giới hạn tốc độ (Rate Limit) và quyền gọi API được thiết lập theo thỏa thuận trong hợp đồng.
- Xác định rõ phạm vi dữ liệu và dịch vụ được phép sử dụng.
Kênh bàn giao an toàn
- JTHT chỉ bàn giao credentials qua kênh bảo mật (email mã hóa hoặc qua portal quản trị có xác thực).
- Đại lý cần xác nhận đã nhận đầy đủ thông tin và cam kết tuân thủ chính sách bảo mật.
Kiểm thử kết nối ban đầu
- Đại lý sử dụng thông tin được cấp để gọi thử API cơ bản (ping, auth check).
- Nhân sự IT JTHT hỗ trợ giám sát và xác nhận kết nối thành công trước khi chuyển sang giai đoạn Sandbox.
# Sơ đồ Cấp thông tin xác thực
# Bảng mô tả Sơ đồ Cấp thông tin xác thực (API Credentials)
# 1. Vai trò và Hệ thống
| Vai trò/Hệ thống | Mô tả |
|---|---|
| Hệ thống C4 | Hệ thống trung tâm thực hiện việc tạo và quản lý tài khoản, bao gồm cả yêu cầu đổi mật khẩu lần đầu. |
| Admin JTHT | Người quản trị hệ thống có trách nhiệm nhận Credentials và gửi thông tin tài khoản cho Đại lý qua kênh bảo mật. |
| Đại lý | Người dùng cuối, có trách nhiệm nhận thông tin, đăng nhập lần đầu và cập nhật mật khẩu mới. |
# 2. Luồng công việc Chi tiết (Flow)
| Bước | Bên thực hiện | Mô tả Hoạt động | Kết quả/Ghi chú |
|---|---|---|---|
| 1 | Hệ thống C4 | Yêu cầu tạo TK | Khởi tạo tài khoản mới trong hệ thống. |
| 2 | Hệ thống C4 | Sinh Credentials & Trả về | Hệ thống tạo tên đăng nhập (Username) và mật khẩu tạm thời/khởi tạo (Initial Password) và gửi cho Admin JTHT. |
| 3 | Admin JTHT | Gửi thông tin qua kênh bảo mật | Admin gửi tên đăng nhập và mật khẩu khởi tạo cho Đại lý (sử dụng kênh an toàn như tin nhắn mã hóa hoặc email riêng). |
| 4 | Đại lý | Đăng nhập lần đầu | Đại lý sử dụng Credentials được cấp để đăng nhập vào hệ thống C4. |
| 5 | Hệ thống C4 | Bắt buộc đổi mật khẩu | Hệ thống nhận diện đây là lần đăng nhập đầu tiên và buộc Đại lý phải thiết lập mật khẩu mới (Reset Password). |
| 6 | Đại lý | Cập nhật mật khẩu mới | Đại lý nhập và xác nhận mật khẩu mới. |
| 7 | Hoàn tất | Quy trình kết thúc. | Tài khoản đã sẵn sàng sử dụng với mật khẩu bảo mật do Đại lý tự đặt. |
# Bước 4: Cấp tài liệu và môi trường thử nghiệm (Sandbox)
Sau khi đại lý đã nhận được thông tin xác thực (credentials), JTHT sẽ cung cấp đầy đủ bộ tài liệu kỹ thuật và môi trường sandbox để hỗ trợ quá trình tích hợp.
# Nội dung bao gồm:
- Tài liệu kỹ thuật (API Documentation): Cấu trúc request/response của từng API service, các tham số bắt buộc và tham số tùy chọn, ví dụ minh họa cho từng endpoint (sample code), chính sách rate limit, retry, và error handling.
- Môi trường thử nghiệm (Sandbox Environment): Cung cấp endpoint sandbox dành riêng cho đại lý F1, cho phép thực hiện các giao dịch mô phỏng mà không ảnh hưởng đến dữ liệu thật, mapping dữ liệu test (ví dụ: booking giả lập, giao dịch thanh toán demo), gói test case chuẩn để đại lý xác thực tích hợp thành công.
# Hướng dẫn sử dụng
- Cách kết nối credentials với API trong môi trường sandbox.
- Cách kiểm tra log, theo dõi request
# Sơ đồ Quy trình thử nghiệm (Sandbox)
# Bảng mô tả Quy trình Thử nghiệm (Sandbox/UAT)
# 1. Vai trò: Đội ngũ Phát triển (Đại lý/F1)
| Thành phần | Mô tả |
|---|---|
| Bắt đầu Sandbox | Khởi động quá trình tích hợp và kiểm thử trong môi trường thử nghiệm (Sandbox Environment). |
| Kết nối API & Gọi thử lệnh Ping | Thực hiện kết nối hệ thống và gọi lệnh kiểm tra cơ bản (Ping) để xác nhận kết nối mạng và xác thực (Authentication) thành công. |
| Chạy bộ Test Case chuẩn | Thực hiện các kịch bản kiểm thử nghiệp vụ chi tiết (ví dụ: Booking, Payment, Cancel, v.v.) theo tài liệu hướng dẫn. |
| Debug & Sửa lỗi | Nếu phát hiện lỗi (Có lỗi) trong quá trình kiểm tra kết quả, tiến hành gỡ lỗi (Debug) và sửa code để khắc phục. |
| Ký biên bản nghiệm thu UAT | Nếu kết quả đáp ứng yêu cầu (Đạt yêu cầu), chính thức ký kết biên bản nghiệm thu người dùng (User Acceptance Test - UAT). |
# 2. Vai trò: Đội ngũ Hỗ trợ (IT JTHT)
| Thành phần | Mô tả |
|---|---|
| Nhận Tài liệu & Env Sandbox | Cung cấp cho Đại lý đầy đủ tài liệu hướng dẫn kỹ thuật và thông tin môi trường Sandbox (URL, Credentials, v.v.). |
| Liên hệ IT JTHT hỗ trợ | Cung cấp hỗ trợ kỹ thuật và xử lý các vấn đề liên quan đến kết nối, xác thực nếu lệnh Ping Thất bại. |
| Kiểm tra kết quả | Phối hợp hoặc xác nhận kết quả kiểm thử sau khi Đại lý chạy các Test Case. |
# 3. Luồng công việc (Tổng quan)
| Bước | Bên thực hiện | Mô tả | Kết quả/Quyết định |
|---|---|---|---|
| 1 | Phát triển | Bắt đầu Sandbox. | Khởi động quá trình. |
| 2 | Hỗ trợ/Phát triển | Nhận Tài liệu & Env Sandbox. | Chuẩn bị môi trường và công cụ. |
| 3 | Phát triển | Kết nối API & Gọi thử lệnh Ping. | Kiểm tra kết nối cơ bản. |
| 4a | Phát triển/Hỗ trợ | Ping Thất bại | Xử lý lỗi kết nối/xác thực. |
| 4b | Phát triển | Ping Thành công | Thực hiện kiểm thử nghiệp vụ sâu hơn. |
| 5 | Phát triển/Hỗ trợ | Kiểm tra kết quả của bộ Test Case. | Đánh giá kết quả kiểm thử. |
| 6a | Phát triển | Kết quả Có lỗi | Sửa lỗi, sau đó quay lại Chạy bộ Test Case chuẩn (Bước 4b). |
| 6b | Phát triển/Hỗ trợ | Kết quả Đạt yêu cầu | Nghiệm thu và xác nhận chất lượng. |
| 7 | Phát triển/Hỗ trợ | Sẵn sàng Go-live. | Kết thúc giai đoạn Sandbox, chuyển sang quy trình Go-live Production. |
# Bước 5: Go-live Môi trường Production
Tổng quan: Sau khi hoàn tất thử nghiệm trên môi trường Sandbox và được JTHT xác nhận đạt yêu cầu, Đại lý sẽ được kích hoạt sử dụng môi trường Production để chính thức triển khai hoạt động kinh doanh.
# Các hoạt động chính chi tiết
Xác nhận điều kiện Go-live Trước khi chuyển sang môi trường thật, cần đảm bảo các điều kiện sau:
- Hoàn tất kiểm thử tích hợp: Đã kiểm tra thành công kết nối API, luồng booking, thanh toán và báo cáo.
- Kiểm soát lỗi: Không còn lỗi nghiêm trọng (Critical/Major bugs) ảnh hưởng đến giao dịch.
- Pháp lý: Đã ký biên bản nghiệm thu thử nghiệm (UAT Sign-off).
Cấp quyền Production JTHT sẽ tiến hành thiết lập môi trường thật cho Đại lý:
- Cấp Credentials: Cung cấp bộ
API Key/Client Secretriêng biệt cho Production (khác với Sandbox). - Cấu hình hệ thống:
- Thiết lập Domain Production.
- Cấu hình IP Whitelist, OAuth Redirect, Webhook URLs.
- Thiết lập chính sách: Cập nhật Rate Limit và Quota theo chính sách hợp đồng.
Giám sát & Hỗ trợ khởi động Trong giai đoạn đầu vận hành (1–2 tuần đầu):
- Giám sát: JTHT bố trí nhân sự IT và Vận hành theo dõi sát sao các giao dịch để phát hiện và xử lý sự cố kịp thời.
- Kênh hỗ trợ: Cung cấp Hotline hỗ trợ 24/7 dành riêng cho Đại lý trong giai đoạn này.
Bàn giao chính thức Sau khi giai đoạn theo dõi kết thúc và hệ thống chạy ổn định:
- JTHT bàn giao trạng thái vận hành chính thức cho Đại lý.
- Đại lý chịu trách nhiệm duy trì hệ thống tích hợp phía mình.
- JTHT tiếp tục cung cấp hỗ trợ kỹ thuật định kỳ theo quy trình chuẩn.
# Sơ đồ Quy trình Go-live
# Bảng mô tả quy trình Go-live Production
# 1. Vai trò: Đội ngũ Kỹ thuật & Vận hành (Go-live Team)
| Thành phần | Mô tả |
|---|---|
| Đánh giá Điều kiện Go-live | Kiểm tra toàn bộ yêu cầu về kỹ thuật, nghiệp vụ, kiểm thử (UAT) và hợp đồng đã được đáp ứng chưa. |
| Cấp Credentials Production | Tạo và cung cấp thông tin xác thực (Key, Secret, Token) chính thức cho môi trường Production. |
| Cấu hình tham số thật | Thực hiện cấu hình các thông số quan trọng: IP Whitelist, Callback URL, và các tham số môi trường thật khác. |
| Cập nhật Rate Limit | Thiết lập giới hạn truy cập (Rate Limit) hệ thống theo đúng thỏa thuận đã ký trong Hợp đồng/Phụ lục. |
| Giám sát Đặc biệt (1-2 tuần đầu) | Thực hiện theo dõi chuyên sâu, đánh giá hiệu năng và xử lý sự cố ngay lập tức trong giai đoạn đầu. |
| Bàn giao Vận hành Chính thức | Hoàn tất quá trình Go-live và chuyển giao trách nhiệm vận hành hệ thống cho đội ngũ Operation/Vận hành thường xuyên. |
# 2. Vai trò: Đại lý (F1/Đối tác)
| Thành phần | Mô tả |
|---|---|
| Cung cấp thông tin hoàn thiện | Nếu chưa đủ điều kiện Go-live, Đại lý phải hoàn thiện lại các vấn đề phát sinh ở môi trường Sandbox/UAT. |
| Tiếp nhận & Kiểm tra bàn giao | Nhận lại Credentials Production và các thông số cấu hình đã được JTHĐ thiết lập. |
| Tiến hành Go-live | Thực hiện chuyển đổi từ môi trường UAT/Sandbox sang môi trường Production chính thức. |
# 3. Luồng công việc (Tổng quan)
| Bước | Bên thực hiện | Mô tả |
|---|---|---|
| 1 | Kỹ thuật & Vận hành | Đánh giá: Kiểm tra Đủ điều kiện Go-live? |
| 2a | Đại lý | Nếu chưa (Chưa), Quay lại hoàn thiện Sandbox. |
| 2b | Kỹ thuật & Vận hành | Nếu đã OK, Cấp Credentials Production. |
| 3 | Kỹ thuật & Vận hành | Cấu hình tham số thật (IP Whitelist, Callback URL, v.v.). |
| 4 | Kỹ thuật & Vận hành | Cập nhật Rate Limit theo Hợp đồng. |
| 5 | Kỹ thuật & Vận hành | Giám sát đặc biệt trong 1-2 tuần đầu. |
| 6 | Kỹ thuật & Vận hành | Bàn giao vận hành chính thức (Kết thúc quy trình Go-live). |
# 3. Mẫu form thông tin kỹ thuật
Dành cho: Đại lý / Đối tác tích hợp Mục đích: Thu thập thông tin cấu hình kỹ thuật, môi trường và chính sách bảo mật.
- Thông tin đại lý
- Tên đại lý:
....................................................... - Mã đại lý:
........................................................ - Tier đăng ký: - [ ] Enterprise - [ ] Premium - [ ] Standard - [ ] Basic
- Thông tin liên hệ
- Email kỹ thuật (Technical):
....................................................... - Email vận hành (Operations):
...................................................... - Số điện thoại liên hệ:
............................................................
- Thông tin tích hợp
- Tên ứng dụng tích hợp:
............................................................ - Môi trường yêu cầu: - [ ] Dev (Development) - [ ] Staging (UAT) - [ ] Prod (Production)
- Danh sách IP Whitelist:
........................................................... - Đường dẫn callback:
- OAuth Redirect:
..............................................................- Webhook (C4):.................................................................
- API Services yêu cầu Vui lòng tích chọn các quyền truy cập (Scope) cần thiết:
- [ ]
booking.read - [ ]
booking.write - [ ]
payment.create - [ ]
report.read - [ ] Khác:
.......................................................
- Chính sách & Cam kết Hiệu năng hệ thống:
- Expected RPS (Requests per second):
............... - Peak RPS:
...............
Bảo mật & Dữ liệu:
- Cam kết lưu trữ dữ liệu (Data Retention Acknowledgement): - [ ] Đồng ý tuân thủ quy định
- Xử lý dữ liệu nhạy cảm (PII Handling):
- [ ] Masking
- [ ] Tokenization
- [ ] Khác:
..........................................................
- Xác nhận & Chữ ký
| Đại diện Đại lý | Đại diện JTHT |
|---|---|
| Họ và tên: ...................................................... | Họ và tên: ...................................................... |
| Chức vụ: ........................................................ | Chức vụ: ........................................................ |
| Ngày: ......./......./20....... | Ngày: ......./......./20....... |
| Chữ ký & đóng dấu: | Chữ ký: |