Tài liệu Mô tả webservice hóa đơn điện tử

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, tổ chức lại tài liệu 1.1 04/2019 Bổ sung mục mapping trường thơng tin mẫu hóa đơn v1.0 Sinvoice: Tài liệu mô tả webservice 2/79 v1.0 Sinvoice: Tài liệu mô tả webservice 3/79 MỤC LỤC Thuật ngữ viết tắt .6 Mục đích phạm vi .6 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 4.4 Cơ chế kiểm trùng giao dịch 4.5 Tiêu chuẩn bảo mật kết nối 10 Đặc tả chi tiết đầu vào lập hóa đơn 10 1.1 Tổng quan 10 1.2 generalInvoiceInfo .11 1.3 sellerInfo 16 1.4 buyerInfo 18 1.5 extAttribute 21 1.6 payments 21 1.7 deliveryInfo 21 1.8 itemInfo 21 1.9 taxBreakdowns .30 1.10 summarizeInfo 32 1.11 metadata .35 1.12 meterReading .36 1.13 invoiceFile 37 Các API kết nối 38 1.14 Các khái niệm chung 38 1.15 Phát hành/thay thế/điều chỉnh hóa đơn (Dùng cho CTS HSM) 40 1.16 Lấy file hóa đơn 43 1.17 Lấy file hóa đơn có mã số bí mật .45 v1.0 Sinvoice: Tài liệu mô tả webservice 4/79 1.18 Lấy file hóa đơn chuyển đổi (pdf) .48 1.19 Hủy hóa đơn .50 1.20 Tra cứu hóa đơn 52 1.21 Lấy thông tin trường động 56 1.22 Lập hóa đơn nháp .61 1.23 Lập hóa đơn theo lơ 62 1.24 Cập nhật kê khai thuế 63 1.25 Cung cấp tình hình sử dụng hóa đơn theo dải 64 1.26 Cung cấp danh sách hóa đơn theo khoảng thời gian 66 1.27 Gửi email cho hoá đơn khách hàng .67 1.28 Lập hóa đơn ký USB Token .69 1.29 Đẩy chữ ký vào usb token 71 1.30 Chuyển font 72 1.31 Cập nhật trạng thái toán 73 1.32 Hủy trạng thái toán 75 1.33 Xem trước hóa đơn nháp 76 1.34 Tra cứu hóa đơn transactionUuid 77 Danh sách lỗi trả hệ thống 78 Mapping trường thơng tin mẫu hóa đơn .78 Kiểm tra API POSTMAN 79 v1.0 Sinvoice: Tài liệu mô tả webservice 5/79 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ế toá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/79 - Đă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 Một số luồng 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 • Luồng đơn giản - Phát hành/Thay thế/điều chỉnh hóa đơn (Tương ứng API mục: 6.2) - Hủy hóa đơn (Tương ứng API mục: 6.6) - Tải file hóa đơn (Tương ứng API mục: 6.3) - Tra cứu hóa đơn (Tương ứng API mục: 6.7) - Lập hóa đơn nháp (Tương ứng API mục: 6.9) • Luồng hóa đơn có phát sinh trường thông tin thêm (Các thông tin khai báo chuẩn phần VD: Điện nước, bệnh viện, hải hảng, xuất nhập kho ….) - Lấy danh sách trường động khai báo theo mẫu hóa đơn (Tương ứng API mục: 6.8 mục 5.11) - Phát hành/Thay thế/điều chỉnh hóa đơn (Tương ứng API mục: 6.2) - Hủy hóa đơn (Tương ứng API mục: 6.6) - Tải file hóa đơn (Tương ứng API mục: 6.3) - Tra cứu hóa đơn (Tương ứng API mục: 6.7) - Lập hóa đơn nháp (Tương ứng API mục: 6.9) 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ệ v1.0 Sinvoice: Tài liệu mô tả webservice 7/79 thống SInvoice Các tiêu chuẩn 4.1 Tiêu chuẩn thời gian Thời gian lấy theo Time Zone Việt Nam, 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) - 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+07:00 - Dữ liệu có thơng tin ngày: o Format: yyyy-MM-dd o Ví dụ: 2019-03-06 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://currentmillis.com/ lấy giá trị “to local time &date” https://www.epochconverter.com/ Lấy giá trị “Your time zone” o Ví dụ: 1551872514000 o Lưu ý: Đối với UNIX time sử dụng cho đầu vào json 4.2 - Tiêu chuẩn liệu Hệ thống SInvoice hỗ trợ liệu chuẩn Unicode (UTF-8) (Đối với chuẩn liệu khác, hệ thống có API tiện ích convert font từ font khác sang Unicode Tham khảo tài liệu convert v1.0 Sinvoice: Tài liệu mô tả webservice 8/79 font mục 6.17) - Đố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ý theo chuẩn json xml ( cần ký tự đánh dấu để nhận dạng ký tự đặc biệt) Trong json cần thêm ký tự đánh dấu \ trước ký tự đặc biệt Trong xml cần truyền dạng entity encode cho ký tự đặc biệt sử dụng CDATA xml VD: - Json: Muốn truyền liệu là: Nguyễn Văn A “B” Thì cần truyền json sau: "buyerName": "Nguyễn Văn A \"B\"", - Xml: Muốn truyền liệu : Nguyễn Văn A > B Thì cần truyền xml dạng encode sau: Nguyễn Văn A > B Hoặc sử dụng CDATA sau B ]]> 4.4 - Cơ chế kiểm trùng giao dịch Phần mềm tích hợp SInvoice giao tiếp qua mơi trường mạng, q trình giao dịch phát sinh lỗi đường truyền (lỗi mạng, hệ thống cao tải v.v.v) Để tránh giao dịch tạo thành hóa đơn, với request hóa đơn gửi sang thao tác lập hóa đơn, hệ thống tích hợp tự sinh transactionUuid cho hóa đơn gửi kèm request lập hóa đơn Chi tiết xem mục 5.2 định dạng liệu transactionUuid - Sau request thực hiện, cần đợi request phản hồi xem kết hay sai, request không phản hồi sau khoảng thời gian timeout (tối thiểu 90 giây) Sau gửi v1.0 Sinvoice: Tài liệu mô tả webservice 9/79 request khác với trùng transactionUuid Việc gửi request đồng thời thời điểm với trùng transactionUuid không hệ thống xử lý kiểm sốt mà tạo thành hóa đơn khác - Trong trường hợp chưa nhận thông tin phản hồi Có thể chủ động tra cứu lại thơng tin hóa đơn dựa theo transactionUuid để biết hóa đơn sinh hay chưa Chi tiết xem mục 6.21 Tra cứu hóa đơn transactionUuid 4.5 Tiêu chuẩn bảo mật kết nối - API kết nối mã hóa sử dụng giao thức https với xác thực Basic Auth - Để đảm bảo bảo mật, mặc định hệ thống không cho phép tài khoản kết nối qua API Để kết nối API cho tài khoản, người dùng phải đăng nhập vào web Viettel cấu hình IP phép truy cập Chi tiết xem Bước tài liệu hướng dẫn cấu hình user (Link đính kèm): https://sinvoice.viettel.vn/download/soft/h%C3%A6%C2%AF%C3%A1%C2%BB %C2%9Ang_d%C3%A1%C2%BA%C2%AAn_c%C3%A1%C2%BA%C2%A4u_h %C3%A3%C2%8Cnh_user_webservice.doc Đặ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 usb token, xem trước hóa đơn nháp trường liệu truyền vào có dạng chung { "generalInvoiceInfo":{ //Thơng tin chung hóa đơn }, "buyerInfo":{ //thông tin người mua }, "sellerInfo":{ //thông tin người bán }, "extAttribute":[ //thông tin trường mở rộng không bắt buộc ], "payments":[ //thơng tin tốn ], "deliveryInfo":{ //thơng tin vận chuyển }, "itemInfo":[ //thơng tin hàng hóa ], "metadata":[ //thông tin trường động ], "meterReading": //thông tin đặc biệt dành cho hóa đơn điện nước ], "summarizeInfo":{ //thơng tin tổng hợp tiền hóa đơn }, "taxBreakdowns":[ //thơng tin gom nhóm tiền hóa đơn theo thuế suất v1.0 Sinvoice: Tài liệu mô tả webservice 10/79 Z0-9/]+ templateCode Required : true Mã mẫu hóa đơn DataType: Mã mẫu hóa đơn, tuân thủ theo quy định ký hiệu mẫu hóa String đơn Thông tư hướng dẫn thi hành nghị định số Minlength : 11 51/2010/NĐ-CP Maxlength : 11 Chi tiết xem PL1 Thông tư 39/2014/TT-BTC Format : [a-zAZ0-9]{7}/[0-9] {3} Required : true serial Seri hóa đơn DataType: String Minlength : Maxlength : Format : [a-zAZ0-9/]+ Ví dụ mẫu trường liệu: - JSON: { "supplierTaxCode":"0100109106", "templateCode":"01GTKT0/003", "serial":"AA/18E" } - XML: 0100109106 < templateCode >01GTKT0/003 AA/17E  Đầu ra: Đối tượng Response với HTTPStatus output Entity v1.0 Sinvoice: Tài liệu mô tả webservice 65/79 Tên trường Mô tả errorCode description status numOfpublishInv totalInv Mã lỗi (giá trị null khơng có lỗi xảy ra) Mơ tả lỗi (giá trị null khơng có lỗi xảy ra) Trạng thái (giá trị 200 lấy thông tin sử dụng hóa đơn thành cơng) Tổng số hóa đơn phát hành Tổng số hóa đơn lập với mẫu hóa đơn + dải truyển vào Cung cấp danh sách hóa đơn theo khoảng thời gian 1.26 Trả chi tiết thơng tin hóa đơn để đối sốt xem sai hóa đơn khoảng thời gian  Đầu vào: - Action (POST): /InvoiceAPI/InvoiceUtilsWS/getListInvoiceDataControl - Headers: + Authorization: username/pass đăng nhập web + Content-Type : application/json application/xml Các tham số đối tượng CommonDataInput Tên tham số Kiểu liệu, Mô tả ràng buộc supplierTaxCode Required : true Mã số thuế doanh nghiệp/chi nhánh phát hành hóa DataType: String đơn Một doanh nghiệp có nhiều mã số thuế Minlength : Mẫu 1: 0312770607 Maxlength : 15 Mẫu 2: 0312770607-001 Format : [a-zAfromDate Z0-9/]+ Required : true Ngày bắt đầu muốn tìm kiếm DataType: String Format toDate : dd/MM/yyyy Required : true Ngày kết thúc muốn tìm kiếm DataType: String Format : dd/MM/yyyy Ví dụ mẫu trường liệu: - JSON: v1.0 Sinvoice: Tài liệu mô tả webservice 66/79 { "supplierTaxCode":"0100109106", "fromDate":"10/03/2018", "toDate":"16/03/2018" } - XML: 0100109106 < fromDate> 10/03/2018 < toDate> 16/03/2018  Đầu ra: Đối tượng Response với HTTPStatus output Entity Tên trường Mô tả errorCode description lstInvoiceBO Mã lỗi (giá trị null khơng có lỗi xảy ra) Mơ tả lỗi (giá trị null khơng có lỗi xảy ra) Danh sách hóa đơn tạo theo thời gian truyền vào Gửi email cho hoá đơn khách hàng 1.27 Trong trường hợp khách hàng cấu hình email hệ thống SInvoice, hệ thống tự động thực gửi email cho người mua thơng tin hóa đơn có email Webservice cho phép phần mềm tích hợp chủ động việc gửi email cho khách hàng, trường hợp cấu hình email khơng hoạt động  Đầuvào: - Action (POST): /InvoiceAPI/InvoiceUtilsWS/sendHtmlMailProcess - Headers: + Authorization: username/pass đăng nhập web v1.0 Sinvoice: Tài liệu mô tả webservice 67/79 + Content-Type : application/json application/xml • Các tham số sendHtmlMailProcess Tên tham số Kiểu liệu, ràng Mô tả buộc supplierTaxCode Required : true Mã số thuế doanh nghiệp/chi nhánh phát DataType: String hành hóa đơn Một doanh nghiệp có nhiều Minlength : mã số thuế Maxlength : 15 Mẫu 1: 0312770607 Format lstTransactionUuid : [a-zA-Z0- Mẫu 2: 0312770607-001 9/]+ Required : true Danh sách key request, transactionUuid DataType: String tương ứng với hoá đơn (Validate độ dài transactionUuid khoảng 10 – 36 ký tự) Các transactionUuid cách dấu “,” Ví dụ mẫu trường liệu: - JSON: { "supplierTaxCode":"0100109106", "lstTransactionUuid":"idtest9999999999,testuuid8888888,transactionUuid123" } - XML: 0100109106 idtest9999999999,testuuid8888888,transactionUuid123  Đầura: Đối tượng Response với HTTPStatus output Entity Tên trường errorCode description Mô tả Mã lỗi (giá trị null khơng có lỗi xảy ra) Mô tả lỗi (giá trị null lỗi xảy ra) v1.0 Sinvoice: Tài liệu mơ tả webservice 68/79 Lập hóa đơn ký USB Token 1.28 Sinh file xml chuỗi hash file XML hóa đơn ký USB Token  Đầuvào: - Action (POST): - Headers: InvoiceAPI/InvoiceWS/createInvoiceUsbTokenGetHash/{supplierTaxCode} + Authorization: username/pass đăng nhập web + Content-Type : application/json Đầu vào tương tư lập hóa đơn, bổ sung thêm thơng tin chứng thư gửi kèm Tên tham số Kiểu liệu, ràng Mơ tả buộc certificateSerial • • • • • • • • • • • • • • • • • • • • • • • • • • Required : true Serial Number chứng thư số doanh nghiệp, DataType: String chứng thư số doanh nghiệp đẩy lên hệ Minlength : 32 thống đăng ký sử dụng USB Token Maxlength : 32 Định dạng Hex Format : [a-zA-Z0-9]+ Ví dụ: 5404FFFEB7033FB316D672201B7BA4FE { "generalInvoiceInfo":{ "invoiceType":"01GTKT", "templateCode":"01GTKT0/170", "invoiceSeries":"AA/17E", "transactionUuid": "123e4567-e89b-12d3-a456-426655440000", "invoiceIssuedDate":1517301625626, "currencyCode":"VND", "adjustmentType":"1", "paymentStatus":true, "cusGetInvoiceRight":true, "userName":"user 1", “certificateSerial”:”5404FFFEB7033FB316D672201B7BA4FE” }, "buyerInfo":{ "buyerName":"Đặng thị tâm", "buyerLegalName":"", "buyerTaxCode":"", "buyerAddressLine":"HN VN", "buyerPhoneNumber":"11111", "buyerEmail":"", "buyerIdNo":"123456789", "buyerIdType":"1" }, "sellerInfo":{ "sellerLegalName":"Đặng thị tâm", v1.0 Sinvoice: Tài liệu mô tả webservice 69/79 • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • "sellerTaxCode":"0100109106-501", "sellerAddressLine":"test", "sellerPhoneNumber":"0123456789", "sellerEmail":"PerformanceTest1@viettel.com.vn", "sellerBankName":"vtbank", "sellerBankAccount":"23423424" }, "extAttribute":[ ], "payments":[ { "paymentMethodName":"TM" } ], "deliveryInfo":{ }, "itemInfo":[ { "lineNumber":1, "itemCode":"ENGLISH_COURSE", "itemName":"Khóa học tiếng anh", "unitName":"khóa học", "unitPrice":3500000.0, "quantity":10.0, "itemTotalAmountWithoutTax":35000000, "taxPercentage":10.0, "taxAmount":0.0, "discount":0.0, "itemDiscount":150000.0 } ], "discountItemInfo":[ ], "metadata":[ ], "meterReading": [{ "previousIndex": "5454", "currentIndex": "244", "factor": "22", "amount": "2" }, { "previousIndex": "44", "currentIndex": "44", "factor": "33", "amount": "3" }], "summarizeInfo":{ "sumOfTotalLineAmountWithoutTax":35000000, "totalAmountWithoutTax":35000000, v1.0 Sinvoice: Tài liệu mơ tả webservice 70/79 • • • • • • • • • • • • • • • "totalTaxAmount":3500000.0, "totalAmountWithTax":38500000, "totalAmountWithTaxInWords":"Ba mươi tám triệu năm trăm nghìn đồng chẵn", "discountAmount":0.0, "settlementDiscountAmount":0.0, "taxPercentage":10.0 }, "taxBreakdowns":[ { "taxPercentage":10.0, "taxableAmount":35000000, "taxAmount":3500000.0 } ] }  Dữ liệu chuỗi Hash trả { "errorCode": "", "description": "", "result": { "hashString": 0HFm34vX525V3Syg5EwdTnfO21s=, } } Tên trường Kiểu liệu, Mô tả ràng buộc errorCode description hashString 1.29 DataType: String DataType: String DataType: String Mã lỗi có, khơng có lỗi trả null Mơ tả chi tiết lỗi Chuỗi Hash trả hóa đơn, dạng Base64 Đẩy chữ ký vào usb token Đẩy chữ ký sau ký chuỗi hash trả bước 6.15 vào file hóa đơn  Đầuvào: - Action (POST): - Headers: InvoiceAPI/InvoiceWS/createInvoiceUsbTokenInsertSignature + Authorization: username/pass đăng nhập web + Content-Type : application/json Tên tham số Kiểu liệu, ràng Mô tả buộc supplierTaxCode Required : true Mã số thuế doanh nghiệp/chi nhánh phát hành DataType: String hóa đơn Một doanh nghiệp có nhiều mã số Minlength : 10 thuế v1.0 Sinvoice: Tài liệu mô tả webservice 71/79 templateCode Maxlength : 15 Mẫu 1: 0312770607 Format : [0-9-]+ Required : true Mẫu 2: 0312770607-001 Mã mẫu hóa đơn DataType: String Minlength : 11 hashString Maxlength : 11 Required : true Chuỗi Hash mà liệu trả request signature DataType: String Required : true getHash phía bên Chữ ký sau ký USB token dạng DataType: String Base64 Kết trả  Dữ liệu thông tin hóa đơn lập { "errorCode": "", "description": "", "result": { "supplierTaxCode": 1258694363, "invoiceNo": AA/16E0000001, "transactionID": 12523522245, "reservationCode": AXHBNK8I0H } } Tên trường errorCode description supplierTaxCode invoiceNo transactionID reservationCode Mô tả Mã lỗi (giá trị null lập hóa đơn thành công) Mô tả lỗi (giá trị null lập hóa đơn thành cơng) Mã số thuế người bán (doanh nghiệp phát hành hóa đơn) Số hóa đơn vd: AA\16E0000001 Id giao dịch Mã số bí mật dùng để tra khách hang tra cứu Chuyển font 1.30 Hỗ trợ convert từ font chữ sang unicode  Đầuvào: - Action (POST): - Headers: InvoiceAPI/InvoiceUtilsWS/convertFont + Authorization: username/pass đăng nhập web + Content-Type : application/json v1.0 Sinvoice: Tài liệu mô tả webservice 72/79 Tên tham số Kiểu liệu, Mô tả ràng buộc font Required : true Font liệu, liệu hỗ trợ bao gồm: DataType: String VNI TCVN3 data TCVN1 Dữ liệu cần chuyển Required : true DataType: String Kết trả  { Dữ liệu thơng tin hóa đơn lập "errorCode": "", "description": "", "result": "" } Tên trường errorCode description result 1.31 Mô tả Mã lỗi (giá trị null chuyển font thành công) Mô tả lỗi (giá trị null chuyển font thành công) Dữ liệu sau chuyển Cập nhật trạng thái tốn Cho phép hệ thống tích hợp cập nhật trạng thái tốn hóa đơn sang toán  Đầu vào: - Action (POST): InvoiceAPI/InvoiceWS/updatePaymentStatus - Headers: + Authorization: username/pass đăng nhập web + Content-Type : application/x-www-form-urlencoded - Data: liệu truyền vào dạng Form Param gồm tham số: Tên trường Kiểu liệu, ràng Dữ liệu/mô tả buộc supplierTaxCode Required: true Mã số thuế doanh nghiệp/chi nhánh phát hành hóa DataType: String đơn Một doanh nghiệp có nhiều mã số thuế Minlength: Mẫu 1: 0312770607 Maxlength: 11 Mẫu 2: 0312770607-001 v1.0 Sinvoice: Tài liệu mô tả webservice 73/79 templateCode Format: [a-zA-Z0-9/]+ Required: true Mẫu số hóa đơn DataType: String Minlength: 11 Maxlength: 11 invoiceNo Format: [a-zA-Z0-9/]+ Required: true Là ký hiệu hóa đơn + số hóa đơn vd: AA/16E0000001 DataType: String Minlength: Maxlength: 13 buyerEmailAddress Format: [a-zA-Z0-9/]+ Required: false Email người mua DataType: String Minlength: Maxlength: 50 Format: ^[_A-Za-z0-9-\ +]+(\.[_A-Za-z0-9-] +)*@[A-Za-z0-9-]+(\ [A-Za-z0-9]+)*(\.[A-ZastrIssueDate z]{2,})$ Required: true Ngày lập hóa đơn DataType: String Minlength: Maxlength: Format: paymentType yyyyMMddHHmmss Required: true Loại hình thức tốn DataType: String Minlength: Maxlength: 30 Format: [a-zA-Z0-9-_./] paymentTypeName + Required: true Tên phương thức toán DataType: String Minlength: Maxlength: 100 cusGetInvoiceRight Format: Required: true Cho khách hàng xem hóa đơn Quản lý hóa đơn DataType: Boolean v1.0 Sinvoice: Tài liệu mô tả webservice 74/79 Minlength: Maxlength: Format: Ví dụ định dạng FormParam  supplierTaxCode=0100109106&templateCode=01GTKT0%2F360&invoiceNo=AB %2F18E0000035&buyerEmailAddress=tamdtt1%40viettel.com.vn&strIssueDate= 20180803000000&paymentType=TM%2FCK&paymentTypeName=TM %2FCK&cusGetInvoiceRight=true Dữ liệu trả  {"errorCode":null,"description":null,"result":true,"paymentTime":null, "paymentMethod":null} Mô tả Tên trường Mô tả errorCode Mã lỗi (giá trị null cập nhật trạng thái tốn thành description cơng) Mơ tả lỗi (giá trị null cập nhật trạng thái toán thành result cơng) Kết cập nhật trạng thái tốn Thành công: true paymentTime paymentMethod Không thành công: false Thời gian cập nhật trạng thái toán Phương thức toán Hủy trạng thái toán 1.32 Cho phép chuyển trạng thái tốn hóa đơn sang chưa toán  Đầu vào: - Action (POST): InvoiceAPI/InvoiceWS/cancelPaymentStatus - Headers: + Authorization: username/pass đăng nhập web + Content-Type : application/x-www-form-urlencoded - Data: Dạng FormParam (với method POST) QueryParam (với method GET) gồm tham số: Tên trường Kiểu liệu, Dữ liệu/mô tả ràng buộc supplierTaxCode Required : true Mã số thuế doanh nghiệp/chi nhánh phát hành hóa v1.0 Sinvoice: Tài liệu mơ tả webservice 75/79 DataType: String đơn Một doanh nghiệp có nhiều mã số thuế Minlength : Mẫu 1: 0312770607 Maxlength : 14 Mẫu 2: 0312770607-001 Format : [a-zA-Z09/]+ Required : true invoiceNo Là ký hiệu hóa đơn + số hóa đơn vd : AA/16E0000001 DataType: String Minlength : Maxlength : 13 Format : [a-zA- Z0-9/]+ Required : true strIssueDate Ngày lập hóa đơn DataType: String Minlength : Maxlength : Format:yyyyMMd dHHmmss Xem trước hóa đơn nháp 1.33  Đầu vào: Webservice dùng để lấy file PDF liệu để xem Hệ thống tích hợp đẩy liệu lập hóa đơn sang SInvoice trả file PDF liệu đó, liệu khơng lưu vào SInvoice - Action (POST): InvoiceAPI/InvoiceUtilsWS/createInvoiceDraftPreview/{supplierTaxCode} - Headers: + Authorization: username/pass đăng nhập web + Content-Type : application/json application/xml Tên trường Kiểu liệu, Mô tả ràng buộc supplierTaxCode Required: true Mã số thuế doanh nghiệp/chi nhánh phát hành hóa đơn DataType: String Một doanh nghiệp có nhiều mã số thuế Minlength: Mẫu 1: 0312770607 Maxlength: 11 Mẫu 2: 0312770607-001 v1.0 Sinvoice: Tài liệu mô tả webservice 76/79 - Data: Tương tự lập hóa đơn - Đầu ra: Đối tượng Response với HTTPStatus output Entity Tên trường Mô tả errorCode description fileName fileToBytes Mã lỗi (giá trị null lỗi xảy ra) Mơ tả lỗi (giá trị null khơng có lỗi xảy ra) Tên file tải Nội dung file chuyển thành kiểu byte, dạng base64 Tra cứu hóa đơn transactionUuid 1.34 Cho phép hệ thống tích hợp tra cứu hóa đơn phát hành thành công dựa vào transactionUuid (Dữ liệu xác định tính hóa đơn bên phần mềm tích hợp sinh liệu kiểm soát)  Đầu vào: - Action (POST): InvoiceAPI/InvoiceWS/searchInvoiceByTransactionUuid - Headers: + Authorization: username/pass đăng nhập web + Content-Type : application/x-www-form-urlencoded gồm tham số: Tên trường Kiểu liệu, Dữ liệu/mô tả ràng buộc supplierTaxCode transactionUuid Required: true Mã số thuế doanh nghiệp/chi nhánh phát hành hóa đơn DataType: String Một doanh nghiệp có nhiều mã số thuế Minlength: Mẫu 1: 0312770607 Maxlength: 11 Mẫu 2: 0312770607-001 Format: Required: true Giá trị transactionUuid gán với hóa đơn gửi liệu lập DataType: String hóa đơn Minlength: 10 Maxlength: 36 Format: Ví dụ với định dạng formParam: supplierTaxCode=0100109106&transactionUuid= 5a9b3b68-b5a3-4670-bd38-764cbe2685b5 Hình ảnh Response trả thành công v1.0 Sinvoice: Tài liệu mô tả webservice 77/79 Thông tin chi tiết Response { } "transactionUuid": "0100109106_test3_268_1", "errorCode": null, "description": null, "result": [ { "supplierTaxCode": "0100109106", "invoiceNo": "AB/19E0000522", "reservationCode": "OKMYMDX5F4", "issueDate": "2019-10-29 10:16:30", "status": "Hóa đơn gốc" } ] Danh sách lỗi trả hệ thống Đối tượng Response mô tả trạng thái lỗi Webservice trả đối tượng liệu Webservice trả Bao gồm mã lỗi mô tả lỗi Danh sách mã lỗi thường gặp danh sách tất mã lỗi hệ thống theo file đính kèm list_error.xlsx Note: Khi phát sinh lỗi việc kiểm tra mã lỗi danh sách lỗi để nắm lỗi cách khắc phục Mapping trường thông tin mẫu hóa đơn Các trường thơng tin mapping lên mẫu hóa đơn phụ thuộc vào thiết kế chi tiết mẫu hóa đơn Về mẫu hóa đơn mapping trường sau: Lưu ý: trường hợp trường thông tin khơng hiển thị đúng, ngun nhân liệu gửi sang chưa mẫu hóa đơn thiết kế không hiển thị thông tin Kiểm tra liệu file hóa đơn gốc (xml) tải xem chưa v1.0 Sinvoice: Tài liệu mô tả webservice 78/79 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 79/79