Tiêu đề Tài liệu tích hợp hệ thống hóa đơn EasyPos (V2).docx ✅

1 | Page TÀI LIỆU TÍCH HỢP HỆ THỐNG HOÁ ĐƠN ĐIỆN TỬ EASY POS
2 | Page Mục lục I. Mô hình tích hợp tổng quan 3 II. Nguyên tắc tích hợp 3 III. Mô tả đầu hàm 4 IV. Danh sách chi tiết đầu hàm 5 1. POST /api/account/verify (API xác thực tài khoản tích hợp) 5 2. POST /api/invoices/patterns (API lấy về các mẫu số ký hiệu hóa đơn) 6 3. POST /api/publish/importAndIssueInvoice (API Tạo và phát hành hóa đơn tự động từ đơn hàng) 6 4. POST /api/publish/getInvoicesByIkeys (Lấy thông tin hóa đơn theo ikey) 12 5. POST /api/publish/importInvoice (API tạo hóa đơn chưa phát hành) 13 6. POST /api/business/cancelInvoice 13 7. POST /api/publish/getInvoicePdf 14 8. POST /api/business/sendIssuanceNotice (Gửi email hoá đơn cho khách hàng) 14 V. Phụ lục 15 1. Phương thức thanh toán (trường bắt buộc) 15 2. Trạng thái hoá đơn 15 3. Thuế suất 15 4. Tên sản phẩm 16 5. Chiết khấu (quan trọng) 16 6. Extra (thông tin bổ sung) 16 7. Trường sản phẩm ghi chú 16 8. Feature - Tính chất sản phẩm 16 9. Mã cơ quan thuế 16
3 | Page I. Mô hình tích hợp tổng quan Các thông tin làm rõ thêm mô hình: - Người dùng đăng ký sử dụng Hóa đơn điện tử từ Máy tính tiền ở Phần mềm Hóa đơn điện tử. - Sau khi được Thuế phê duyệt, PM Hóa đơn điện tử cập nhật lại thông tin về Mã CQT, Mẫu số hóa đơn về cho PM Bán hàng. - PM Bán hàng sẽ thực hiện cấp mã CQT theo chuẩn mỗi khi tạo đơn hàng. - Người dùng sau đó có thể chọn các hình thức sau để phát hành hóa đơn điện tử từ đơn hàng: + Chỉ tạo hóa đơn mới tạo lập, sau đó phát hành hóa đơn và gửi CQT trên PM Hóa đơn (áp dụng thường khi người dùng sử dụng USB Token, không thể tự động phát hành hóa đơn). + Tạo và phát hành hóa đơn tự động (áp dụng khi người dùng sử dụng chứng thư số hỗ trợ ký số từ xa như HSM, RemoteSigning). - PM bán hàng sau đó cập nhật từ PM Hóa đơn các thông tin như: kết quả xử lý, số hóa đơn để hiển thị cho người dùng. II. Nguyên tắc tích hợp 1. Ikey - Đây là yếu tố để liên kết 1-1 giữa đơn hàng (PM Bán hàng) và Hóa đơn điện tử (PM hóa đơn); - Ikey là duy nhất;
4 | Page - PM bán hàng EasyPOS dựa vào IKey để kiểm tra trạng thái xử lý, thông tin hóa đơn điện tử tương ứng từ PM Hóa đơn. 2. Fkey - Đây là mã người dùng (người mua) có thể tra cứu hóa đơn điện tử; - Fkey tương tự như Ikey, được tạo khi người dùng lập đơn hàng ở EasyPOS; III. Mô tả đầu hàm - Toàn bộ các API trong tài liệu đều có header: Content-Type=application/json. - Toàn bộ các API trong tài liệu đều sử dụng header: Authentication=Chuỗi xác thực như mô tả dưới đây: - Chuỗi xác thực có cấu trúc như sau: signature:nonce:timestamp:username:password + timestamp: Số giây từ mốc thời gian năm 1970, tháng 01, ngày 01, 00 giờ, 00 phút, 00 giây, 000 mili giây đến thời điểm hiện tại (tính theo giờ Utc). + nonce: Chuỗi ký tự ngẫu nhiên chỉ bao gồm chữ cái và chữ số. + signature: Giá trị base64 của mã MD5 cho chuỗi được tạo từ sự kết hợp giữa Http Method, timestamp và nonce ghép liền theo đúng thứ tự, ví dụ: POST155350749068CFE3F19B4B4668AE7746A514FAF2CD. + username: Tên đăng nhập. + password: Mật khẩu. - Ví dụ về tạo chuỗi xác thực trong C#: private static string GenerateToken(string httpMethod, string username, string password) { DateTime epochStart = new DateTime(1970, 01, 01, 0, 0, 0, 0, DateTimeKind.Utc); TimeSpan timeSpan = DateTime.UtcNow - epochStart; string timestamp = Convert.ToUInt64(timeSpan.TotalSeconds).ToString(); string nonce = Guid.NewGuid().ToString("N").ToLower(); string signatureRawData = $"{httpMethod.ToUpper()}{timestamp}{nonce}"; using (MD5 md5 = MD5.Create()) { var hash = md5.ComputeHash(Encoding.UTF8.GetBytes(signatureRawData)); var signature = Convert.ToBase64String(hash); return $"{signature}:{nonce}:{timestamp}:{username}:{password}"; } } - Ví dụ về tạo chuỗi xác thực trong Java: