Phương thức API
Tài liệu mô tả các vấn đề liên quan đến việc triển khai hình thức kết nối API giữa Đối tác B2B2C (trong tài liệu này gọi là Đối tác) và Gotadi.
Tài liệu liên quan
Thông tin kết nối giữa giữ Gotadi và Đối tác.
Kịch bản kiểm kiểm thử.
Source code mẫu.
Thuật ngữ và viết tắt
URL
Uniform Resource
được dùng để tham chiếu tới tài nguyên trên Internet.SSL
Secure Sockets Layer
là các giao thức mật mã được thiết kế để cung cấp truyền thông an toàn qua Internet.HTTPS
Hypertext Transfer Protocol Secure
là một giao thức kết hợp giữa giao thức HTTP và giao thức bảo mật SSL hay TLS cho phép trao đổi thông tin một cách bảo mật trên Internet.3DES
Triple DES (3DES hay TDES)
là một thuật toán khóa đối xứng, áp dụng thuật toán mã hóa DES ba lần cho mỗi khối dữ liệu.RSA
Rivest–Shamir–Adleman
là một thuật toán mật mã hóa khóa công khai. Đây là thuật toán đầu tiên phù hợp với việc tạo ra chữ ký điện tử đồng thời với việc mã hóa.SHA-256
Secure Hash Algorithm
là giải thuật dùng để chuyển một đoạn dữ liệu nhất định thành một đoạn dữ liệu có chiều dài không đổi với xác suất khác biệt cao. SHA-256 (trả lại kết quả dài 256 bit)Chữ ký điện tử Thông tin đi kèm theo dữ liệu (văn bản, hình ảnh, video…) nhằm mục đích xác định người chủ của dữ liệu đó
Yêu cầu bảo mật
1. Kênh truyền SSL/HTTPS
SSL/HTTPS được áp dụng để truyền nhận dữ liệu giữa hệ thống của đối tác và Gotadi. Mục đích sử dụng SSL/HTTPS là giúp dữ liệu trao đổi giữa đối tác và Gotadi được mã hóa, khó bị đánh cắp và giả mạo.
2. Header bảo mật và thống kê lưu lượng truyền
Tất cả các request từ phía đối tác gọi sang hệ thống của Gotadi phải chứa các Headers bên dưới để phục vụ các nghiệp vụ về bảo mật và thống kê số liệu của Gotadi:
Lưu ý
Giá trị <api_key>
và <access_code>
do Gotadi cung cấp cho Đối tác.
3. Mã hóa dữ liệu truyền và xác thực chữ ký điện tử
Request/response giữa Gotadi và Đối tác ở một số API quan trọng được yêu cầu mã hóa bằng thuật toán mã hóa bất đối xứng 3DES và kèm theo chữ ký điện tử để xác thực. Thuật toán mã hóa, giải mã sẽ được mô tả cụ thể trong tài liệu này.
Lưu ý
Các API có yêu cầu mã hóa dữ liệu và kèm theo chữ ký điện tử sẽ được ghi chú ở phần Yêu cầu bảo mật.
3.1 Mã hóa dữ liệu gửi đi
Input Original data, RSA PublicKey của bên nhận, RSA Private Key của bên gửi
Output Encrypted Key, Encrypted Data
3.2 Giải mã dữ liệu nhận được và xác thực chữ ký điện tử
Input Encrypted Key, Encrypted Data, RSA PrivateKey của bên nhận, RSA PublicKey của bên gửi
Output Original Data, Verify Result
Kết nối
1. Quy trình kết nối
2. Các quy ước viết tắt
Viết tắt | Từ đầy đủ | Mô tả |
---|---|---|
M |
| Bắt buộc phải có khi gọi API. |
O |
| Không yêu cầu khi gọi API, tùy từng mục đích sử dụng mà có truyền tham số này không |
C |
| Dựa trên Condition của field khác khi gọi API mà field này được quyết định là Mandatory hay Optional |
3. HTTP Response code
Response code | Mô tả |
---|---|
200 | Success |
400 | Bad Request |
401 | Unauthorized |
402 | Forbidden |
402 | Not Found |
500 | Internal Server Error |
503 | Service Unavailable |
5. Các tham số phổ biến
page (Integer, Optional)
Số thứ tự của trang (bắt đầu từ 0)
size (Integer, Optional)
Số lượng phần tử của mỗi trang
sort (String, Optional)
Mảng chứa tên trường và kiểu sắp xếp dữ liệu.
VD: id,desc,createdDate,asc
duration (String, Optional)
Thời gian xử lý yêu cầu - Kể từ thời điểm nhận request đến thời điểm trả kết quả.
success (Boolean, Required)
Kết quả xử lý yêu cầu
infos (Object[], Optional)
Mảng chứa thông tin mô tả kết quả ở các bước trong quá trình xử lý yêu cầu.
errors (Object[], Optional)
Mảng chứa thông tin mô tả các lỗi đã xảy ra trong quá trình xử lý yêu cầu.
textMessage (String, Optional)
Thông báo được đề xuất hiển thị cho người dùng.
pageDTO (PageDTO, Optional)
Đối tượng mô tả các thông tin phân trang: Số thứ tự của trang được trả về, số phần tử của mỗi trang, tổng số trang, …
6. Luồng tương tác
7. Mã lỗi
Mã lỗi | Mô tả |
---|---|
00 | Yêu cầu đã được xử lý thành công. |
01 | Yêu cầu đang được xử lý. |
02 | Yêu cầu đã được xử lý thất bại. |
03 | Yêu bị từ chối do Xác thực tài khoản đại lý khoản thất bại. |
04 | Yêu bị từ chối do Chữ ký điện tử không hợp lệ. |
05 | Yêu bị từ chối do Giải mã dữ liệu không thành công. |
06 | Yêu bị từ chối do Mã xác thực (Access Code) không hợp lệ. |
07 | Yêu bị từ chối do Dữ liệu sai định dạng. |
08 | Yêu bị từ chối do Đã được xử lý trước đó. |
09 | Yêu cầu chưa được xử lý. |
10 | Thông tin tài khoản không tìm thấy |
99 | Lỗi khác. |
Last updated