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 Required : false buyerIdNo DataType: String templateCode Required : false DataType: String Số giấy tờ khách hàng Mã mẫu hóa đơn Minlength : 11 Maxlength : 11 Required : false invoiceSeri DataType: String Seri hóa đơn Minlength : Maxlength : Format : [a-zA-Z0- 9/]+ Chú ý: để tra cứu hóa đơn theo khách hàng doanh nghiệp cần có thơng tin:  buyerTaxCode: Mã số thuế khách hàng doanh nghiệp  contractNo: Số hợp đồng  contractId: Id hợp đồng  customerId: Id khách hàng doanh nghiệp  buyerIdNo: Số giấy tờ khách hàng doanh nghiệp Ví dụ gửi liệu với JSON: { "startDate" : "2017-12-12T10:14:32.611+07:00", "endDate" : "2017-12-31T10:14:32.611+07:00", "invoiceType" : "02GTTT", "rowPerPage" : 20, "pageNum" : 1, "templateCode" : null } Ví dụ gửi liệu với XML: 2017-12-12T10:14:32.611+07:00 2017-12-31T10:14:32.611+07:00 02GTTT 20 1 v1.0 Sinvoice: Tài liệu mô tả webservice 23/73  Đầu ra: { "errorCode": null, "description": null, "totalRow": 286, "invoices": [ { "invoiceId": 213469, "invoiceType": "02GTTT", "adjustmentType": "1", "templateCode": "02GTTT0/089", "invoiceSeri": "QT/17E", "invoiceNumber": "0000003", "invoiceNo": "QT/17E0000003", "currency": "VND", "total": 3800000, "issueDate": 1514281815000, "issueDateStr": null, "state": null, "requestDate": null, "description": null, "buyerIdNo": null, "stateCode": null, "subscriberNumber": null, "paymentStatus": 1, "viewStatus": 1, "downloadStatus": null, "exchangeStatus": null, "numOfExchange": null, "createTime": 1514281826000, "contractId": null, "contractNo": null, "supplierTaxCode": "0100109106", "buyerTaxCode": "6200000230", "totalBeforeTax": 3800000, "taxAmount": 0, v1.0 Sinvoice: Tài liệu mô tả webservice 24/73 "taxRate": null, "paymentMethod": null, "paymentTime": null, "customerId": null, "buyerName": "Trần Trung Dũng", "no": null, "paymentStatusName": null } } Hoặc XML 1 Trần Trung Dũng 6200000230 2017-12-26T16:50:26+07:00 VND 213469 QT/17E0000003 0000003 QT/17E 02GTTT 2017-12-26T16:50:15+07:00 1 0100109106 0 02GTTT0/089 3800000 3800000 v1.0 Sinvoice: Tài liệu mô tả webservice 25/73 1 Đối tượng Response với HTTPStatus output Entity Tên trường errorCode description List Mô tả Mã lỗi (giá trị null lấy hóa đơn thành cơng) Mơ tả lỗi (giá trị null lấy hóa đơn thành cơng) Danh sách ghi hóa đơn thỏa mãn điều kiện 5.8 Lấy thơng tin trường động Với mẫu hóa đơn, có thơng tin trường động khác (các trường thơng tin ngồi trường tĩnh mơ tả mục 6) SInvoice cho phép hệ thống tích hợp lấy thơng tin trường động mẫu hóa đơn cụ thể mà khách hàng sử dụng  Đầu vào: - Action (GET) có truyền Query Parameter: /InvoiceAPI/InvoiceWS/getCustomFields? taxCode=&templateCode= - Ví dụ: /InvoiceAPI/InvoiceWS/getCustomFields? taxCode=0100109106&templateCode=01GTKT0%2f085 - Data: liệu truyền vào dạng Query Param gồm tham số: Tên trường Kiểu liệu, Mô tả ràng buộc taxCode Required : true Mã số thuế DataType: String Minlength : Maxlength : 11 Format : [a-zAtemplateCode Z0-9/]+ Required : false Mã mẫu hóa đơn, tuân thủ theo quy định ký hiệu mẫu hóa DataType: String đơn Thơng tư hướng Minlength : dẫn thi hành nghị định số 51/2010/NĐ-CP Maxlength : 11 Format : [a-zAZ0-9/]+  Đầu ra: v1.0 Sinvoice: Tài liệu mô tả webservice 26/73 Đối tượng Response danh sách trường động tương ứng với mẫu hóa đơn doanh nghiệp: Ví dụ: - [{ "id": 189, "invoiceTemplatePrototypeId": 1032, "keyLabel": "Năm sinh", "keyTag": "buyerDateOfBirth", "valueType": "date", "isRequired": false, "isSeller": false }, { "id": 190, "invoiceTemplatePrototypeId": 1032, "keyLabel": "Mã bệnh nhân", "keyTag": "buyerCode", "valueType": "number", "isRequired": false, "isSeller": false }, { "id": 191, "invoiceTemplatePrototypeId": 1032, "keyLabel": "Khoa phòng", "keyTag": "buyerDepartments", "valueType": "text", "isRequired": false, "isSeller": true }, { "id": 192, "invoiceTemplatePrototypeId": 1032, "keyLabel": "Lý thu", "keyTag": "invoiceReason", "valueType": "text", "isRequired": false, "isSeller": true }] Tên trường Kiểu liệu, Mô tả ràng buộc id DataType: ID trường động keyLabel Number DataType: String Tên hiển thị trường động, keyTag DataType: String Hiển thị giao diện nhập liệu lập hóa đơn Tên trường động lưu vào liệu valueType DataType: String Kiểu liệu trường động Chỉ bao gồm giá trị: isRequired DataType: “text”, “date”, “number” Trường có bắt buộc hay khơng isSeller Boolean DataType: isSeller = true: Trường liệu thuộc bên bán Boolean isSeller = false: Trường liệu thuộc bên mua Gửi liệu lập hóa đơn với trường động: Thêm vào mảng metadata, phần tử bao gồm: v1.0 Sinvoice: Tài liệu mô tả webservice 27/73 Tên trường Kiểu liệu, ràng Mô tả buộc invoiceCustomFieldId Required : true ID trường động DataType: Number Minlength : Maxlength : 10 keyTag Format : Required : true Tên trường động lưu vào liệu DataType: String valueType keyLabel dateValue numberValue stringValue Required : true Kiểu liệu trường động Chỉ bao gồm giá DataType: String trị: “text”, “date”, “number” Required : true Tên hiển thị trường động, DataType: String Hiển thị giao diện nhập liệu lập hóa đơn Required : false Giá trị trường liệu trường hợp DataType: Date valueType = date Required : false Giá trị trường liệu trường hợp DataType: Number valueType = number Required : false Giá trị trường liệu trường hợp DataType: String valueType = text { "generalInvoiceInfo":{ "invoiceType":"01GTKT", "templateCode":"01GTKT0/028", "invoiceIssuedDate":1505098310271, "currencyCode":"VND", "adjustmentType":"1", "paymentStatus":true, "paymentType":"TM", "paymentTypeName":"TM", "cusGetInvoiceRight":true, "buyerIdNo":"123456789", "buyerIdType":"1" }, "buyerInfo":{ "buyerName":"Lương Thị Huyền", "buyerLegalName":"", "buyerTaxCode":"", "buyerAddressLine":"HN VN", "buyerPhoneNumber":"09880830406", "buyerEmail":"", v1.0 Sinvoice: Tài liệu mô tả webservice 28/73 "buyerIdNo":"123456789", "buyerIdType":"1" }, "sellerInfo":{ "sellerLegalName":"Supplier perfom test 1", "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":[ ], "summarizeInfo":{ "sumOfTotalLineAmountWithoutTax":35000000, "totalAmountWithoutTax":35000000, "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, "taxPercentage":10.0 }, "taxBreakdowns":[ { "taxPercentage":10.0, "taxableAmount":35000000, "taxAmount":3500000.0 } ], "metadata": [ { "invoiceCustomFieldId": 82, v1.0 Sinvoice: Tài liệu mô tả webservice 29/73 "keyTag": "buyerDateOfBirth", "dateValue": "1514019933737", "valueType": "date", "keyLabel": "Ngày sinh" }, { "invoiceCustomFieldId": 83, "keyTag": "buyerCode", "numberValue": 12323, "valueType": "number", "keyLabel": "Mã bệnh nhân" }, { "invoiceCustomFieldId": 84, "keyTag": "buyerDepartments", "stringValue": "Tim mach", "valueType": "text", "keyLabel": "Khoa phòng" }, { "invoiceCustomFieldId": 85, "keyTag": "invoiceReason", "stringValue": "Khám bệnh", "valueType": "text", "keyLabel": "Lý thu" } ] } 5.9 Lập hóa đơn nháp  Đầu vào: Webservice dùng để lưu liệu hóa đơn nháp lên hệ thống SInvoice Các hóa đơn nháp xem/phát hành website SInvoice - Action (POST): /InvoiceAPI/InvoiceWS/createOrUpdateInvoiceDraft/{supplierTaxCode} Trong đó: {supplierTaxCode}: mã số thuế doanh nghiệp phát hành 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 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 Data: Định dạng 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 trả về:  Dữ liệu thơng tin hóa đơn lập { "errorCode": "", "description": "", "result": { } } Định dạng XML Phải chọn loại template hóa đơn TEMPLATE_NOT_FOUND Mơ tả Tên trường Mơ tả errorCode description 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) 5.10 Lập hóa đơn theo lơ Trường hợp khách hàng muốn lập hóa đơn theo lơ sử dụng hàm sau Lưu ý: Hệ thống cho phép tối đa 50 hóa đơn/1 lô thời gian xử lý đơn lẻ hóa đơn lâu, để lơ nhiều q bị timeout Trong trường hợp liệu từ hệ thống tích hợp nhiều hơn, tự động chia nhỏ số lượng hóa đơn gửi sang  Đầu vào: o Action (POST) URL: /InvoiceAPI/InvoiceWS/createBatchInvoice/ {supplierTaxCode} {supplierTaxCode}: mã số thuế doanh nghiệp phát hành 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 DataType: String đơn Một doanh nghiệp có nhiều mã số thuế v1.0 Sinvoice: Tài liệu mô tả webservice 31/73 - Minlength: Mẫu 1: 0312770607 Maxlength: 11 Mẫu 2: 0312770607-001 Data: Dữ liệu mẫu lập hóa đơn theo lơ JSON XML Lập hóa đơn theo lơ HD_Lo.txt HD_Lo.xml Kết lập hóa đơn theo lơ thành cơng 5.11 Cập nhật kê khai thuế Cho phép hệ thống tích hợp gửi thông tin cập nhật kê khai thuế sang, để tránh cho khách hàng bị sai sót q trình sử dụng (hóa đơn hủy xóa bỏ, thay thế)  Đầu vào: - Action (POST): InvoiceAPI/InvoiceUtilsWS/updateTaxDeclaration/ - Headers: - + Authorization: username/pass đăng nhập web - + Content-Type: application/json (application/xml) gồm tham số: Tên trường Kiểu liệu, Dữ liệu/mô tả ràng buộc supplierTaxCode strIssueDate 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 Ngày lập hóa đơn DataType: String Minlength: v1.0 Sinvoice: Tài liệu mơ tả webservice 32/73 Maxlength: Format: dd/mm/yyyy - Ví dụ với định dạng json: { "supplierTaxCode":"0100109106", "strIssueDate":"14/03/2018" } - Ví dụ với định dạng xml: 0100109106 14/03/2018  Đầu ra: Hình ảnh Response trả thành cơng 5.12 Cung cấp tình hình sử dụng hóa đơn theo dải Trả thông tin chi tiết số lượng hóa đơn dùng, số lượng cịn lại dải hóa đơn để từ đối tác tích hợp chủ động cảnh báo khách hàng trường hợp khơng đủ hóa đơn  Đầu vào: • Action (POST) URL: /InvoiceAPI/InvoiceUtilsWS/getProvidesStatusUsingInvoice • Các tham số đối tượng CommonDataInput Tên tham số Kiểu liệu, Mô tả ràng buộc v1.0 Sinvoice: Tài liệu mô tả webservice 33/73 supplierTaxCode Required : true Mã số thuế doanh nghiệp/chi nhánh phát hành hóa đơn DataType: Một doanh nghiệp có nhiều mã số thuế String Mẫu 1: 0312770607 Minlength : Mẫu 2: 0312770607-001 Maxlength : 15 Format : [a-zAZ0-9/]+ Required : true pattern Mã mẫu hóa đơn DataType: String Minlength : 11 Maxlength : 11 Format : [a-zAZ0-9]{7}/[0-9] {3} templateCode Hiện chưa có, cần bổ sung, khơng bắt buộc có KH cũ khơng truyền Trong trường hợp có templateCode pattern ưu tiên lấy templateCode Sửa đồng khái niệm cho ơng đối tác serial Required : true Seri hóa đơn DataType: String Minlength : Maxlength : Format : [a-zAZ0-9/]+ Chú ý: Để biết tình trạng sử dụng hóa đơn dải cần số thơng tin sau:  supplierTaxCode: Mã số thuế doanh nghiệp  pattern: Mã số mẫu hóa đơn  serial: Seri hóa đơn Ví dụ mẫu trường liệu:Tải FULL (file word 73 trang): bit.ly/3gHRVNg - JSON: Dự phịng: fb.com/TaiHo123doc.net { v1.0 Sinvoice: Tài liệu mơ tả webservice 34/73 "supplierTaxCode":"0100109106", "pattern":"01GTKT0/003", "serial":"AA/18E" } - XML: 0100109106 01GTKT0/003 AA/17E  Đầu ra: Đối tượng Response với HTTPStatus output Entity 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 5.13 Cung cấp danh sách hóa đơn theo khoảng thời gian Trả chi tiết thơng tin hóa đơn để đối sốt xem sai hóa đơn  Đầu vào: • Action (POST) URL: /InvoiceAPI/InvoiceUtilsWS/getListInvoiceDataControl • 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-zAZ0-9/]+ v1.0 Sinvoice: Tài liệu mô tả webservice 35/73 fromDate Required : true Ngày bắt đầu muốn tìm kiếm DataType: String Format : dd/MM/yyyy Required : true toDate Ngày kết thúc muốn tìm kiếm DataType: String Format : dd/MM/yyyy Chú ý: Để biết tình trạng sử dụng hóa đơn dải cần số thông tin sau:  supplierTaxCode: Mã số thuế doanh nghiệp  fromDate: Ngày bắt đầu muốn tìm kiếm  toDate: Ngày kết thúc muốn tìm kiếm Ví dụ mẫu trường liệu: - JSON: { "supplierTaxCode":"0100109106", "fromDate":"10/03/2018", "toDate":"16/03/2018" } - XML: 0100109106 < fromDate> 10/03/2018 < toDate> 16/03/2018  Đầu ra: Tải FULL (file word 73 trang): bit.ly/3gHRVNg Dự phòng: fb.com/TaiHo123doc.net v1.0 Sinvoice: Tài liệu mô tả webservice 36/73 Đối tượng Response với HTTPStatus output Entity Tên trường errorCode description lstInvoiceBO Mô tả 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 5.14 Gửi email cho hoá đơn khách hàng 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 URL: /InvoiceAPI/InvoiceUtilsWS/sendHtmlMailProcess • 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 32 – 36 ký tự) Chú ý: Để gửi email cho hoá đơn khách hàng cần số thông tin sau:  supplierTaxCode: Mã số thuế doanh nghiệp  lstTransactionUuid: Danh sách key request Ví dụ mẫu trường liệu: - JSON: { "supplierTaxCode":"0100109106", "lstTransactionUuid":"idtest9999999999,testuuid8888888,transactionUuid123" } v1.0 Sinvoice: Tài liệu mô tả webservice 5326583 37/73 ... 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. .. 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... description Mô tả Mã lỗi (giá trị null lấy hóa đơn thành cơng) Mơ tả lỗi (giá trị null lấy hóa đơn thành cơng), Kiểm tra hóa đơn có phải hóa đơn gốc, chưa kê khai thuế ,trạng thái tốn, khơng phải hóa đơn