Tài liệu Mô tả webservice hóa đơn điện tử TẬP ĐOÀN VIỄN THÔNG QUÂN ĐỘI VIETTE

TẬP ĐỒN VIỄN THƠNG QN ĐỘI VIETTEL Tài liệu Mơ tả webservice hóa đơn điện tử Hà Nội, 01/2019 BẢNG GHI NHẬN THAY ĐỔI Phiên Ngày Chi tiết 0.1 09/2017 Phiên khởi tạo 0.2 03/2018 Bổ sung thêm mục 2.1.11, 2.1.12, 2.1.13 0.3 09/2018 Bổ sung thêm 2.1.14, 2.1.15 1.0 09/2018 Bổ sung thêm chi tiết đặc tả tin v1.0 Sinvoice: Tài liệu mô tả webservice 2/73 v1.0 Sinvoice: Tài liệu mô tả webservice 3/73 MỤC LỤC Thuật ngữ viết tắt Mục đích phạm vi Mơ hình kết nối Các tiêu chuẩn 4.1 Tiêu chuẩn thời gian 4.2 Tiêu chuẩn liệu 4.3 Các ký tự đặc biệt Các API kết nối 5.1 Các khái niệm chung .8 5.2 Phát hành/thay thế/điều chỉnh hóa đơn (HSM) 10 5.3 Lấy file hóa đơn 12 5.4 Lấy file hóa đơn có mã số bí mật 14 5.5 Lấy file hóa đơn chuyển đổi (pdf) 17 5.6 Hủy hóa đơn 19 5.7 Tra cứu hóa đơn 21 5.8 Lấy thông tin trường động 26 5.9 Lập hóa đơn nháp 30 5.10 Lập hóa đơn theo lô 31 5.11 Cập nhật kê khai thuế 32 5.12 Cung cấp tình hình sử dụng hóa đơn theo dải 33 5.13 Cung cấp danh sách hóa đơn theo khoảng thời gian 35 5.14 Gửi email cho hoá đơn khách hàng 37 5.15 Lập hóa đơn ký USB Token 38 5.16 Đẩy chữ ký vào usb token .40 5.17 Chuyển font .41 5.18 Cập nhật trạng thái toán 42 5.19 Hủy trạng thái toán 44 5.20 Xem trước hóa đơn nháp 45 v1.0 Sinvoice: Tài liệu mô tả webservice 4/73 Đặc tả chi tiết đầu vào lập hóa đơn 45 1.1 Tổng quan 45 1.2 generalInvoiceInfo .46 1.3 sellerInfo 51 1.4 buyerInfo 53 1.5 extAttribute 56 1.6 payments 56 1.7 deliveryInfo 56 1.8 itemInfo 58 1.9 discountItemInfo 66 1.10 taxBreakdowns 66 1.11 summarizeInfo 68 1.12 metadata .71 1.13 meterReading .72 Kiểm tra API POSTMAN 73 v1.0 Sinvoice: Tài liệu mô tả webservice 5/73 Thuật ngữ viết tắt STT Từ viết tắt Nghĩa đầy đủ XML eXtensible Markup Language - Ngôn ngữ Đánh dấu Mở rộng VAN Taxation Value Added Network ICC Invoice Certification Center PSD Portable Security Device SGML Standard Generalized Markup Language W3C World Wide Web Consortium, viết tắt W3C, lập chuẩn cho Internet, cho World Wide Web SInvoice Dịch vụ/hệ thống hóa đơn điện tử Viettel HTTH Hệ thống phần mềm kế tốn, quản trị doanh nghiệp tích hợp với hệ thống SInvoice để phát hành hóa đơn Mục đích phạm vi Mơ tả chi tiết chuẩn kết nối để hệ thống kết nối vào dịch vụ Hóa đơn điện tử đại trà Viettel nhằm đảm bảo phát hành thông tin Mô hình kết nối Hệ thống SInvoice đóng vai trị nhận liệu hóa đơn từ hệ thống bên ngồi (hệ thống tích hợp) gửi phát hành thành hóa đơn theo mẫu mà doanh nghiệp chọn Các API hệ thống SInvoice cung cấp theo chuẩn Restful Webservice, hỗ trợ XML Json Ban đầu, doanh nghiệp thực thao tác khai báo mẫu hóa đơn web hệ thống SInvoice bao gồm: - Khai báo tên mẫu hóa đơn - Chọn mẫu hóa đơn - Khai báo dải hóa đơn - Lập thông báo phát hành v1.0 Sinvoice: Tài liệu mô tả webservice 6/73 - Đăng ký thông tin chứng thư số Chi tiết bước hướng dẫn xem thêm tại: https://sinvoice.viettel.vn/ho-tro/huong-dan-sudung/mo-ta-tong-the-cac-buoc-dang-ky-va-su-dung-dich-vu-hoa-don-dien-tu Sau thông tin khai báo mẫu hóa đơn thực đầy đủ SInvoice, doanh nghiệp thơng qua hệ thống bên để gọi API thực việc - Phát hành/Thay thế/điều chỉnh hóa đơn - Hủy hóa đơn - Tải file hóa đơn - Tra cứu hóa đơn - Lập hóa đơn nháp Lưu ý 1: Lập hóa đơn sử dụng chữ ký số HSM USB token sử dụng hàm khác HSM sử dụng hàm nhất, việc tương tác với chữ ký hệ thống Hóa đơn điện tử đảm nhiệm USB sử dụng hàm khác nhau, việc tương tác với chữ ký phần mềm tích hợp đảm nhiệm Khách hàng cần tư vấn trước sử dụng Lưu ý 2: Một doanh nghiệp có nhiều mã số thuế (doanh nghiệp, chi nhánh), mẫu hóa đơn, ký hiệu hóa đơn Vì hệ thống tích hợp phải cho phép DN cấu hình nhiều thơng tin để gửi sang hệ thống SInvoice Các tiêu chuẩn 4.1 - Tiêu chuẩn thời gian C#: o Đinh dạng: yyyy-MM-ddTHH:mm:sszzz o Ví dụ: 2009-06-15T08:45:30+07:00 - Java: o Định dạng: yyyy-MM-dd'T'HH:mm:ssZ o Ví dụ: 2019-02-10T23:46:53+0700 - Format: yyyy-MM-dd o Ví dụ: 2019-03-06 v1.0 Sinvoice: Tài liệu mô tả webservice 7/73 o Lưu ý: gửi format sang hệ thống tự động nhận phần 00:00:00 Các ngơn ngữ khác xác định thời gian sau: - Sử dụng chuẩn UNIX time: hệ thống mô tả điểm thời gian Thời gian Unix định nghĩa số giây kể từ 00:00:00 theo Phối hợp Quốc tế (UTC) ngày tháng năm 1970, trừ giây nhuận Tính đến mili giây Tham khảo https://www.epochconverter.com/ o Ví dụ: 1551872514000 o Lưu ý: Đối với UNIX time sử dụng cho đầu vào json - Lưu ý: múi hệ thống SInvoice chạy GMT+7, trường hợp gửi UNIX time sang UTC hệ thống tự động chuyển sang GMT+7 (cộng thêm vào gốc) 4.2 Tiêu chuẩn liệu - Hệ thống SInvoice hỗ trợ liệu chuẩn Unicode (UTF-8) - Đối với liệu gửi sang, hệ thống SInvoice để nguyên format liệu để hiển thị Ngoài trừ với liệu số (liên quan đến tiền, số lượng, đơn giá, thuế suất), tên ngân hàng, tài khoản ngân hàng Dữ liệu số gửi sang ln có định dạng [0-9.]+ Ví dụ 100000.1234 Template SInvoice tự động format hiển thị Đối với liệu tên ngân hàng, tài khoản nhập nhiều, cách dấu “;” 4.3 Các ký tự đặc biệt Các ký tự đặc biệt cần lưu ý cách xử lý Các API kết nối 5.1 Các khái niệm chung Giải thích: - Action: Phương thức hàm thực thi (ví dụ: “/InvoiceAPI/InvoiceWS” phương thức POST) - Data: định dạng liệu truyền vào - Đầu webservice: Đối tượng Response mô tả trạng thái lỗi Webservice trả đối tượng liệu Webservice trả Mã lỗi 200 OK 201 Created Mô tả mã lỗi Success Success of a resource creation when using the POST method v1.0 Sinvoice: Tài liệu mô tả webservice 8/73 400 Bad Request 403 Forbidden The request parameters are incomplete or missing The action or the request URI is not allowed by the system 404 Not Found 422 Unprocessable Entity 429 Too Many Requests 500 Internal Server Error The resource referenced by the URI was not found One of the requested action has generated an error Your application is making too many requests and is being rate limited Used in case of time out or when the request, otherwise correct, was not able to complete - Thông tin hệ thống test (Thực test kết nối hệ thống test không test kết nối hệ thống thật) Link web: https://demo-sinvoice.viettel.vn Link API: https://demo-sinvoice.viettel.vn:8443/InvoiceAPI Link nội bộ: https://10.60.105.238:8443 - Thông tin hệ thống thật (Chỉ thực phát hành hóa đơn thật sự) Link web: https://business-sinvoice.viettel.vn Link API: https://API-sinvoice.viettel.vn:443 Link nội bộ: https://10.60.135.246:443 - Header xác thực: Header xác thực gửi request trình sử dụng Xác thực chuỗi user:pass (Basic Authentication) mã hóa dạng Base64 Header xác thực có format Authorization: Basic QWxhZGRpbjpPcGVuU2VzYW1l Chi tiết xem thêm link: https://en.wikipedia.org/wiki/Basic_access_authentication Ví dụ: Với user/pass: 0100109106-997/123456a@A (Tài khoản test gửi riêng) Chuỗi đầu vào mã hóa 0100109106-997:123456a@A Code mã hóa tham khảo (Java): String encodedAuth = new String(Base64.encodeBase64 ("0104831030:123".getBytes (Charset.forName("utf8")))); Chuỗi mã hóa: MDEwNDgzMTAzMDoxMjM= Một số thư viện HTTP client hỗ trợ Basic Authentication Lưu ý: Với user, hệ thống cho phép vài địa IP định truy cập đến web service IP phải IP public hệ thống đối tác Để cập nhật IP, người dùng tự cập nhật thơng qua bước sau: B1: Vào hệ thống web, sử dụng acc sử dụng để tích hợp v1.0 Sinvoice: Tài liệu mô tả webservice 9/73 B2 Vào chức năng: Quản lý thông tin doanh nghiệp/ Quản lý người dùng B3 Tìm đến user cần add IP, chọn buttom Cập nhật B4: Trên hình cập nhật thông tin, trường thông tin địa IP khai báo theo quy định sau: Các IP liên tiếp phân cách ký tự | Ví dụ: 2.2.2.2|3.3.3.3|4.4.4.4 Chi tiết xem tại: https://sinvoice.viettel.vn/ho-tro/huong-dan-su-dung/7-huong-dan-cap-nhat-quanly-nguoi-dung Bất trường hợp sai tài khoản/mật hay IP nhận kết trả 500 Request Fail - Header định dạng liệu: Dữ liệu gửi lên Web service JSON, XML, FormParam hay QueryParam o Với JSON: Thêm header: Content-Type: application/json o Với XML: Thêm header: Content-Type: application/xml o Với FormParam: Thêm header: Content-Type: application/x-www-form-urlencoded o Với QueryParam: Không cần header, tham số truyền vào qua URL - Dữ liệu trả từ Web service JSON hay XML o Để nhận JSON: Thêm header: Accept: application/xml o Để nhận XML: Thêm header: Accept: application/json Lưu ý: Do cần thời gian kết nối thời gian xử lý yêu cầu nên kết trả phải chờ khoảng thời gian (khuyến nghị để thời gian timeout gửi yêu cầu khoảng 60-90 giây) 5.2 Phát hành/thay thế/điều chỉnh hóa đơn (HSM) Lưu ý: chi tiết trường thông tin chi tiết xem mục  Đầu vào: Webservice dùng chung trường hợp lập hóa đơn gốc, lập hóa đơn điều chỉnh tiền, lập hóa đơn điều chỉnh thơng tin, lập hóa đơn thay - Action (POST): /InvoiceAPI/InvoiceWS/createInvoice/{supplierTaxCode} Trong đó: {supplierTaxCode}: mã số thuế doanh nghiệp/chi nhánh phát hành v1.0 Sinvoice: Tài liệu mô tả webservice 10/73 liệu Hóa đơn thường: Là tổng tiền hàng hóa dịch vụ chưa có VAT Hóa đơn điều chỉnh: Là tổng tiền phần điều chỉnh hàng hóa dịch vụ chưa có VAT Chi tiết điều kiện nhập với loại taxPercentage - Hàng hóa: phải có thơng tin - Ghi chú: khơng bắt buộc có - Chiết khấu: phải có thơng tin - Bảng kê: phải có thơng tin Required: false - Phí khác: phải có thơng tin Trong trường hợp thuế tổng/hóa đơn bán hàng (theo DataType: BigDecimal chuẩn hóa đơn xác thực phải có) Minlength: - Thuế tổng: để theo số chung Maxlength: 13 - Hóa đơn bán hàng/hóa đơn khơng thuế: -2 Format: [0-9.]+ Thuế suất hàng hóa, dịch vụ Thuế suất bao gồm loại: -2: không thuế -1: không kê khai tính/nộp thuế Chỗ ngược với hóa đơn có mã xác thực TCT 0: 0% 5: 5% taxAmount isIncreaseItem Required: false 10: 10% Trong trường hợp thuế tổng/hóa đơn bán hàng: (theo DataType: BigDecimal chuẩn hóa đơn xác thực phải có) Minlength: - Thuế tổng: tổng tiền hàng * thuế chung Maxlength: 13 - Hóa đơn bán hàng/hóa đơn khơng thuế: Format: [0-9.]+ Required: false Tổng tiền thuế, khơng có số âm Dùng để biểu thị tiền hóa đơn số âm trường DataType: Boolean hợp hàng hóa chiết khấu, dịng hàng hóa biểu thị Minlength: điều chỉnh giảm tiền hàng Maxlength: 20 Khi cờ đánh dấu false, toàn tiền Format: taxAmount, itemTotalAmountWithoutTax, itemTotalAmountWithTax đánh dấu âm Hóa đơn bình thường: có giá trị null Hóa đơn điều chỉnh: - false: dịng hàng hóa/dịch vụ bị điều chỉnh giảm v1.0 Sinvoice: Tài liệu mô tả webservice 60/73 itemNote Required: false - true: dịng hàng hóa/dịch vụ bị điều chỉnh tăng Ghi cho dịng hàng hóa DataType: String Minlength: Maxlength: 50 batchNo Format: Required: false Số lô, thường dùng cho hàng hóa thuốc, sử DataType: String dụng để hiển thị thêm thông tin trường hợp cần Minlength: thiết Maxlength: 50 expDate Format: Required: false Hạn sử dụng hàng hóa, thường dùng cho hàng DataType: String hóa thuốc, sử dụng để hiển thị thêm thông tin Minlength: trường hợp cần thiết Maxlength: 50 discount Format: Required: false % chiết khấu dịng sản phẩm, tính đơn giá DataType: BigDecimal sản phẩm Trong trường hợp khơng có truyền null Minlength: Maxlength: 13 itemDiscount Format: [0-9.]+ Required: false Giá trị chiết khấu dòng sản phẩm, sau nhân với DataType: BigDecimal số lượng % chiết khấu Minlength: Maxlength: 13 Format: [0-9.]+ itemTotalAmountW Required: false Là tổng tiền chưa bao gồm VAT hàng hóa/dịch vụ ithTax Tổng tiền khơng có số âm DataType: BigDecimal Minlength: Maxlength: 13 Format: [0-9.]+ Lưu ý: Đối với dịng hàng hóa, trường hợp trường thông tin quantity, unitPrice, itemTotalAmountWithoutTax, taxPercentage, taxAmount, discount, itemDiscount, itemTotalAmountWithTax có liệu (dữ liệu khác null), hệ thống tính tốn kiểm tra liệu Hệ thống so sánh quantity x unitPrice lệch không đồng so với itemTotalAmountWithoutTax Hệ thống so sánh itemTotalAmountWithoutTax bị lệch hệ thống báo lỗi v1.0 Sinvoice: Tài liệu mô tả webservice 61/73 Dữ liệu mẫu "itemInfo": [ { hàng_hóa_1}, ] { hàng_hóa_1} Hàng hóa thơng thường "itemInfo": [ { "lineNumber": 1, "itemCode": "PCDELLV3653_i56400_R4H10DVDRW", "itemName": "Máy tính để bàn DELL VOSTRO 3653 Desktop Core i5-6400 upto3.30Ghz/ 4GB/ 1TB HDD/DVDRW/NVIDIA Geforce 705 2Gb/ Wireless-Bluetooth/ K/ M/1Yr Pro", "unitName": "Cái", "itemNote": "", "unitPrice": 10300000, "quantity": 1, "itemTotalAmountWithoutTax": 10300000, "itemTotalAmountWithTax": 11330000, "itemTotalAmountAfterDiscount": 10300000, "taxPercentage": 10, "taxAmount": 1030000, "customTaxAmount": "0", "discount": 0, "itemDiscount": 0, "batchNo": "", "expDate": "" } ] Hàng hóa kèm ghi "itemInfo": [ { "lineNumber": 2, "selection": 2, "itemName": "Ghi cho hóa đơn", } ] Hàng hóa có chiết khấu dịng sản phẩm "itemInfo": [ { "lineNumber": 1, "itemCode": "LCDLI2215S_LNV", "itemName": "Màn hình vi tính LENOVO LCD LI2215S 21.5\" Led (65CCAACC6VN)", "unitName": "Cái", "itemNote": "", "unitPrice": 1750000, "quantity": 2, "itemTotalAmountWithoutTax": 3500000, "itemTotalAmountWithTax": 3696000, "itemTotalAmountAfterDiscount": 3360000, "taxPercentage": 10, "taxAmount": 336000, "customTaxAmount": "0", "discount": 4, "itemDiscount": 140000, "batchNo": "", "expDate": "" v1.0 Sinvoice: Tài liệu mơ tả webservice 62/73 } ] Hàng hóa có dòng chiết khấu "itemInfo": [ { "lineNumber": 2, "itemCode": "chieu_khau_hang_hoa", "selection": 3, "itemName": "Chiếu khấu hàng hóa", "unitName": "", "itemNote": "", "itemTotalAmountWithoutTax": 50000, "itemTotalAmountWithTax": 50000, "itemTotalAmountAfterDiscount": 50000, "taxPercentage": 0, "taxAmount": 0, "customTaxAmount": "0", "discount": 0, "itemDiscount": 0, "isIncreaseItem": false, "batchNo": "", "expDate": "" } ] Hàng hóa dạng bảng kê "itemInfo": [ { "lineNumber": 1, "itemCode": "bang_ke_hang_hoa", "selection": 4, "itemName": "Bảng kê hàng hóa", "unitName": "", "itemNote": "", "itemTotalAmountWithoutTax": 97770000, "itemTotalAmountWithTax": 107547000, "itemTotalAmountAfterDiscount": 97770000, "taxPercentage": 10, "taxAmount": 9777000, "customTaxAmount": "0", "discount": 0, "itemDiscount": 0, "batchNo": "", "expDate": "" } ] Hàng hóa có kèm phí khác "itemInfo": [ { "lineNumber": 2, "itemCode": "phi_bao_tri", "selection": 5, "itemName": "Phí bảo trì", "unitName": "", "itemNote": "", "unitPrice": 20000, "quantity": 1, v1.0 Sinvoice: Tài liệu mô tả webservice 63/73 "itemTotalAmountWithoutTax": 20000, "itemTotalAmountWithTax": 20000, "itemTotalAmountAfterDiscount": 20000, "taxPercentage": 0, "taxAmount": 0, "customTaxAmount": "0", "discount": 0, "itemDiscount": 0, "batchNo": "", "expDate": "" } ] Hàng hóa điều chỉnh giảm "itemInfo": [ { "lineNumber": 1, "itemCode": "DELL_LJ2350D", "itemName": "Điều chỉnh giảm tiền hàng, tiền thuế hàng hóa/dịch vụ: Máy in Dell LJ 2350D 1Y Wty", "unitName": "Cái", "itemNote": "", "unitPrice": 6281000, "quantity": 3, "itemTotalAmountWithoutTax": 18843000, "itemTotalAmountWithTax": 20727300, "itemTotalAmountAfterDiscount": 18843000, "taxPercentage": 10, "taxAmount": 1884300, "customTaxAmount": "0", "adjustmentTaxAmount": 1, "discount": 0, "itemDiscount": 0, "isIncreaseItem": false, "batchNo": "", "expDate": "" }, { "selection": 2, "itemName": "Điều chỉnh giảm tiền hàng, tiền thuế cho hóa đơn điện tử số AB/18E0000034 lập ngày 07/12/2018 số tiền: 20.727.300 " } ] Hàng hóa điều chỉnh tăng "itemInfo": [ { "lineNumber": 1, "itemCode": "DELL_LJ2350D", "itemName": "Điều chỉnh tăng tiền hàng, tiền thuế hàng hóa/dịch vụ: Máy in Dell LJ 2350D 1Y Wty", "unitName": "Cái", "itemNote": "", "unitPrice": 6281000, "quantity": 5, "itemTotalAmountWithoutTax": 31405000, "itemTotalAmountWithTax": 34545500, "itemTotalAmountAfterDiscount": 31405000, "taxPercentage": 10, "taxAmount": 3140500, "customTaxAmount": "0", v1.0 Sinvoice: Tài liệu mô tả webservice 64/73 "adjustmentTaxAmount": 1, "discount": 0, "itemDiscount": 0, "isIncreaseItem": true, "batchNo": "", "expDate": "" }, { "selection": 2, "itemName": "Điều chỉnh tăng tiền hàng, tiền thuế cho hóa đơn điện tử số AB/18E0000036 lập ngày 07/12/2018 số tiền: 34.545.500 " } ] Hóa đơn điều chỉnh tiền cần bổ sung dòng ghi "itemInfo": [ { "lineNumber": 1, "itemCode": "DVBH_PCHP", "itemName": "Điều chỉnh giảm tiền hàng, tiền thuế hàng hóa/dịch vụ: Dịch vụ nâng cấp bảo hành HP năm NextBusDay Onsite DT Only HW Support _ U6578E", "unitName": "Lần", "itemNote": "", "unitPrice": 600000, "quantity": 6, "itemTotalAmountWithoutTax": 3600000, "itemTotalAmountWithTax": 3960000, "itemTotalAmountAfterDiscount": 3600000, "taxPercentage": 10, "taxAmount": 360000, "customTaxAmount": "0", "adjustmentTaxAmount": 1, "discount": 0, "itemDiscount": 0, "isIncreaseItem": false, "batchNo": "", "expDate": "" }, { "selection": 2, "itemName": "Điều chỉnh giảm tiền hàng, tiền thuế cho hóa đơn điện tử số AB/18E0000068 lập ngày 25/12/2018 số tiền: 3.960.000 " } ] Hóa đơn điều chỉnh thông tin "itemInfo": [ { "selection": 2, "itemName": "Ghi điều chỉnh" } ] Hóa đơn thay cần bổ sung dòng ghi "itemInfo": [ { "lineNumber": 1, "itemCode": "DVBH_PCHP", "itemName": "Dịch vụ nâng cấp bảo hành HP năm NextBusDay Onsite DT Only HW Support _ U6578E", v1.0 Sinvoice: Tài liệu mô tả webservice 65/73 "unitName": "Lần", "itemNote": "", "unitPrice": 600000, "quantity": 6, "itemTotalAmountWithoutTax": 3600000, "itemTotalAmountWithTax": 3960000, "itemTotalAmountAfterDiscount": 3600000, "taxPercentage": 10, "taxAmount": 360000, "customTaxAmount": "0", "discount": 0, "itemDiscount": 0, "batchNo": "", "expDate": "" }, { "selection": 2, "itemName": "Hóa đơn thay cho hóa đơn điện tử số AB/18E0000071 lập ngày 25/12/2018" } ] 1.9 discountItemInfo Hiện chiết khấu gộp vào ItemInfo nên xem xét bỏ phần 1.10 taxBreakdowns Dùng để tổng hợp thuế suất theo mức cho hóa đơn Cần đưa ví dụ bao gồm item để hiểu rõ cách tính tốn liệu Nên cân nhắc khơng bắt buộc phải truyền sang Tên trường taxPercentage taxableAmount taxAmount Kiểu liệu Mô tả Required: false Mức thuế: khai báo giá trị sau DataType: BigDecimal -2: không thuế Minlength: -1: khơng kê khai tính/nộp thuế Maxlength: 13 0: 0% Format: [0-9.]+ 5: 5% Required: false 10: 10% Tổng tiền chịu thuế mức thuế tương ứng, tổng tiền DataType: BigDecimal chịu Minlength: itemTotalAmountWithoutTax tất itemInfo có mức Maxlength: 13 thuế suất giống với mức thuế suất tổng hợp Trong trường Format: [0-9.]+ Required: false hợp dòng hàng hóa chiết khấu trừ Tổng tiền thuế mức thuế tương ứng, tổng tiền thuế DataType: BigDecimal khơng có số âm Bằng tổng taxAmount tất Minlength: itemInfo có mức thuế suất giống với mức thuế suất tổng Maxlength: 13 hợp Trong trường hợp dịng hàng hóa chiết khấu Format: [0-9.]+ trừ thuế khơng có số âm Bằng tổng v1.0 Sinvoice: Tài liệu mô tả webservice 66/73 taxableAmountPos Required: false DataType: Boolean Minlength: Maxlength: 13 Format: Dùng để biểu thị tổng tiền chịu thuế mức thuế âm hay dương - null/true: Tổng tiền đánh thuế dương Được sử dụng hàng hóa thơng thường - false: Tổng tiền đánh thuế âm, sử dụng với hóa đơn điều chỉnh giảm hóa đơn có hàng hóa chiết khấu mà tổng tiền hàng hóa chiết khấu mức Required: false thuế âm Dùng để biểu thị tổng tiền thuế mức thuế âm hay DataType: Boolean dương Giá trị taxAmountPos giống với giá trị Minlength: taxableAmountPos Maxlength: 20 - null/true: Tổng tiền thuế dương taxExemptionReas Format: Required: false - false: Tổng tiền thuế âm Lý miễn giảm thuế on DataType: String taxAmountPos Minlength: Maxlength: 255 Format: Lưu ý: Hệ thống so sánh tổng itemTotalAmountWithoutTax tất itemInfo mức thuế suất với taxableAmount taxBreakDowns Trong trường hợp bị lệch hệ thống báo lỗi Hệ thống so sánh tổng taxAmount tất itemInfo mức thuế suất với taxAmount taxBreakDowns Trong trường hợp bị lệch hệ thống báo lỗi Dữ liệu mẫu Thuế có % "taxBreakdowns": [ { "taxPercentage": 5, "taxableAmount": 400000, "taxAmount": 20000 }, { "taxPercentage": 10, "taxableAmount": 400000, "taxAmount": 40000 } ] Không thuế "taxBreakdowns": [ { "taxPercentage": -2, v1.0 Sinvoice: Tài liệu mô tả webservice 67/73 "taxableAmount": 400000, "taxAmount": } ] Không kê khai tính/nộp thuế "taxBreakdowns": [ { "taxPercentage": -1, "taxableAmount": 400000, "taxAmount": } ] Hóa đơn có tiền thuế âm "taxBreakdowns": [ { "taxPercentage": 10, "taxableAmount": 100000,//tổng tiền âm 100000 "taxAmount": 10000,//thuế âm 10000 "taxableAmountPos": false, "taxAmountPos": false } ] 1.11 summarizeInfo Dùng để tổng hợp tiền hàng cho tồn hóa đơn Cần đưa ví dụ bao gồm item để hiểu rõ cách tính tốn liệu Nên cân nhắc không bắt buộc phải truyền sang Tên trường Kiểu liệu Mô tả sumOfTotalLineA Required: true Tổng thành tiền itemTotalAmountWithoutTax mountWithoutTax DataType: BigDecimal cộng gộp tất dịng hóa đơn chưa bao gồm Minlength: VAT Tổng thành tiền khơng có số âm Maxlength: 13 - Hóa đơn thường: Tổng tiền HHDV dịng Format: [0-9.]+ HĐ - Hóa đơn điều chỉnh: Tổng tiền điều chỉnh totalAmountWithou Required: true dòng HĐ Tổng tiền hóa đơn chưa bao gồm VAT (đã tính chiết tTax DataType: BigDecimal khấu (nếu có)) Tổng tiền hóa đơn khơng có số âm Minlength: - Hóa đơn thường: Tổng tiền HHDV dòng Maxlength: 15 HĐ khoản tăng/giảm khác tồn HĐ Format: [0-9.]+ - Hóa đơn điều chỉnh: Tổng tiền điều chỉnh Required: true dịng HĐ khoản tăng/giảm khác tồn HĐ Tổng tiền thuế tồn hóa đơn Tổng tiền thuế DataType: BigDecimal khơng có số âm Minlength: - Hóa đơn thường: Tổng tiền VAT dòng HĐ Maxlength: 13 khoản thuế khác toàn HĐ totalTaxAmount v1.0 Sinvoice: Tài liệu mô tả webservice 68/73 Format: [0-9.]+ - Hóa đơn điều chỉnh: Tổng tiền VAT điều chỉnh dòng HĐ khoản tăng/giảm VAT khác totalAmountWithTa Required: true tồn HĐ Tổng tiền hóa đơn bao gồm VAT Tổng tiền x DataType: BigDecimal sau thuế khơng có số âm Minlength: - Hóa đơn thường: Tổng tiền HHDV dòng Maxlength: 13 HĐ khoản tăng/giảm khác toàn HĐ Format: [0-9.]+ bao gồm VAT - Hóa đơn điều chỉnh: Tổng tiền điều chỉnh dòng HĐ khoản tăng/giảm khác toàn HĐ totalAmountWithTa Required: false bao gồm VAT Tổng tiền ngoại tệ hóa đơn bao gồm VAT xFrn DataType: BigDecimal Dùng trường hợp hóa đơn khơng chọn loại tiền Minlength: VND Maxlength: 13 - Hóa đơn thường: Tổng tiền HHDV dòng Format: [0-9.]+ HĐ khoản tăng/giảm khác toàn HĐ bao gồm VAT - Hóa đơn điều chỉnh: Tổng tiền điều chỉnh dịng HĐ khoản tăng/giảm khác tồn HĐ totalAmountWithTa Required: false bao gồm VAT Số tiền hóa đơn bao gồm VAT viết chữ Hệ xInWords DataType: String thống hóa đơn điện tử tự động sinh lại liệu Minlength: để đảm bảo theo liệu hệ thống Maxlength: 255 isTotalAmountPos Format: Required: false Để đánh dấu tổng tiền sau thuế âm hay dương DataType: Boolean - null/True: Tổng tiền số dương, sử dụng Minlength: hóa đơn thơng thường hóa đơn có chiết Maxlength: 20 khấu tổng thuế dương sau trừ chiết Format: khấu - False: Tổng tiền âm, sử dụng hóa đơn điều chỉnh giảm có chiết khấu mà tiền chiết khấu lớn isTotalTaxAmount Required: false tiền hàng hóa thơng thường Để đánh dấu tổng tiền thuế âm hay dương Pos DataType: Boolean - null/true: tổng tiền thuế dương Minlength: - false: tổng tiền thuế âm Maxlength: 20 Format: v1.0 Sinvoice: Tài liệu mô tả webservice 69/73 isTotalAmtWithout Required: false Để đánh dấu tổng tiền trước thuế âm hay dương TaxPos DataType: Boolean - null/true: tổng tiền trước thuế dương Minlength: - false: tổng tiền trước thuế âm Maxlength: 20 discountAmount Format: Required: true DataType: BigDecimal Minlength: Maxlength: 13 settlementDiscou ntAmount Format: [0-9.]+ Required: false DataType: BigDecimal Minlength: Maxlength: 13 isDiscountAmtPos Tổng tiền chiết khấu thương mại tồn hóa đơn trước tính thuế Chú ý: Khi tính chiết khấu, tồn hóa đơn sử dụng mức thuế Tổng tiền chiết khấu tốn tồn hóa đơn sau tính thuế Chú ý: Khi tính chiết khấu, tồn hóa đơn sử dụng mức thuế Format: [0-9.]+ Required: false Trường nhận biết tổng tiền chiết khấu số dương DataType: Boolean hay âm Minlength: - null/true: tổng tiền trước thuế dương Maxlength: 20 - false: tổng tiền trước thuế âm Format: Dữ liệu mẫu Hóa đơn thường "summarizeInfo": { "sumOfTotalLineAmountWithoutTax": 100000, "totalAmountWithoutTax": 100000, "totalTaxAmount": 10000, "totalAmountWithTax": 110000, "totalAmountAfterDiscount": 0, "totalAmountWithTaxInWords": "Một trăm mười nghìn đồng", "discountAmount": 0, "taxPercentage": 10 } Hóa đơn có tổng tiền âm "summarizeInfo": { "sumOfTotalLineAmountWithoutTax": 100000, "totalAmountWithoutTax": 100000, "totalTaxAmount": 10000, "totalAmountWithTax": 110000, "totalAmountAfterDiscount": 0, "totalAmountWithTaxInWords": "Một trăm mười nghìn đồng", "discountAmount": 0, "taxPercentage": 10, "isTotalAmountPos": false, "isTotalTaxAmountPos": false, "isTotalAmtWithoutTaxPos": false v1.0 Sinvoice: Tài liệu mô tả webservice 70/73 } 1.12 metadata Dữ liệu trường thông tin động Tên trường keyTag Kiểu liệu Required: false Mô tả Tên liệu DataType: String Minlength: Maxlength: 50 valueType Format: Required: false Kiểu liệu gồm: text, number, date DataType: String Minlength: Maxlength: 25 dateValue Format: Required: false Giá trị liệu kiểu date DataType: Date Minlength: Maxlength: textValue Format: Required: false Giá trị liệu kiểu text DataType: String Minlength: Maxlength: 13 numberValue Format: Required: false Giá trị liệu kiểu number DataType: Integer Minlength: Maxlength: keyLabel Format: Required: false Nhãn hiển thị liệu DataType: String Minlength: Maxlength: 50 isRequired Format: Required: false Giá trị có bắt buộc hay khơng DataType: Boolean Minlength: v1.0 Sinvoice: Tài liệu mô tả webservice 71/73 Maxlength: isSeller Format: Required: false Giá trị người bán hay mua DataType: Boolean False: Người mua Minlength: True: Người bán Maxlength: Format: Dữ liệu mẫu "metadata": [ { "invoiceCustomFieldId": 1135, "keyTag": "dueDate", "valueType": "date", "dateValue": 1544115600000, "keyLabel": "Hạn toán", "isRequired": false, "isSeller": false }, { "invoiceCustomFieldId": 1136, "keyTag": "contractNo", "stringValue": "555", "valueType": "text", "keyLabel": "Hợp dong số", "isRequired": false, "isSeller": false } ] 1.13 meterReading Dữ liệu đặc thù cho riêng hóa đơn điện/nước Tên trường previousIndex Kiểu liệu Required: false Mơ tả Chỉ số cũ hóa đơn điện nước DataType: String Minlength: Maxlength: 50 currentIndex Format: Required: false Chỉ số hóa đơn điện nước DataType: String Minlength: Maxlength: 25 factor Format: Required: false Hệ số nhân hóa đơn điện nước Ví dụ nước DataType: String sinh hoạt có hệ số nhân khác với nước kinh doanh Minlength: Nội dung tùy theo công ty điện/ nước quy v1.0 Sinvoice: Tài liệu mô tả webservice 72/73 amount Maxlength: định hiển thị Format: Required: false Tổng số hóa đơn = (chỉ số cuối – số đầu ) x DataType: String hệ số nhân Minlength: Maxlength: 13 Format: Kiểm tra API POSTMAN Trước lập trình, phần mềm tích hợp nên kiểm tra trước API POSTMAN để hiểu liệu cần phải truyền vào/trả hệ thống Sau chạy thử xong, việc code nhanh Chi tiết xem ở: https://sinvoice.viettel.vn/ho-tro/huong-dan-su-dung/35-huong-dan-su-dung-postman-goi-apiwebservice-hoa-don-dien-tu v1.0 Sinvoice: Tài liệu mô tả webservice 73/73 ... nhóm tiền hóa đơn theo thuế suất ] Mô tả: Tên trường generalInvoiceInfo Mô tả Đây thông tin chung để phát hành hóa đơn, bao gồm ký hiệu mẫu hóa đơn, sellerInfo ký hiệu hóa đơn, loại hóa đơn, ngày... file tải Nội dung file chuyển thành kiểu byte, dạng base64 Đặc tả chi tiết đầu vào lập hóa đơn 1.1 Tổng quan Đối với API lập hóa đơn, điều chỉnh hóa đơn, thay hóa đơn, lập hóa đơn nháp, lập hóa đơn. .. JSON XML Thông số liệu truyền vào tương tự phần Lập hóa đơn  Đầu ra: v1.0 Sinvoice: Tài liệu mô tả webservice 30/73 Đối tượng Response mô tả trạng thái lỗi Webservice trả đối tượng liệu Webservice