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

Ws Nghiệp vụ hóa đơn

Webservice lập hóa đơn

Webservice dùng chung trong các 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 thế

- Action (POST): /InvoiceAPI/InvoiceWS/createInvoice/{supplierTaxCode}

{supplierTaxCode}: mã số thuế của doanh nghiệp phát hành

Tên trường Kiểu dữ liệu, ràng buộc Mô tả supplierTaxCode Required: true

Mã mẫu hóa đơn, tuân thủ theo quy định ký hiệu mẫu hóa đơn của Thông tư hướng dẫn thi hành nghị định số 51/2010/NĐ-CP

- Data: Định dạng JSON hoặc XML

Ví dụ định dạng Json

+ Trường hợp lập hóa đơn gốc.

"currencyCode":"VND", "adjustmentType":"1", "paymentStatus":true, "paymentType":"TM", "paymentTypeName":"TM", "cusGetInvoiceRight":true, "buyerIdNo":"123456789", "buyerIdType":"1",

"buyerName":"Đặng thị thanh tâm", "buyerLegalName":"",

"buyerTaxCode":"", "buyerAddressLine":"HN VN", "buyerPhoneNumber":"11111", "buyerEmail":"",

"sellerLegalName":"Đặng thị thanh tâm", "sellerTaxCode":"0100109106-501",

"sellerAddressLine":"test", "sellerPhoneNumber":"0123456789", "sellerEmail":"PerformanceTest1@viettel.com.vn", "sellerBankName":"vtbank",

"itemName":"Khóa học tiếng anh",

"totalAmountWithTaxInWords":"Ba mươi tám triệu năm trăm nghìn đồng chẵn",

Trường hợp lập hóa đơn điều chỉnh tiền

"invoiceNote":"Điều chỉnh tăng tiền hàng, tiền thuế cho hóa đơn điện tử số AA/17E0003470 lập ngày 11/09/2017 số tiền: 52.500 ",

"buyerName":"Trỏằ‹nh Thanh HÃ²a",

"buyerLegalName":"Trung tâm phần mềm Viễn thông Viettel",

"buyerAddressLine":"Tầng 42, tòa nhà Keangnam Landmark 72 - Hà Nội",

"buyerEmail":"viettelsoftware@viettel.com.vn"

"sellerLegalName":"Công ty cổ phần nước sạch Lai Châu - test", "sellerTaxCode":"6200000230-999",

"sellerEmail":"hoatt16_1@viettel.com.vn"

"itemName":"Điều chỉnh tăng tiền hàng, tiền thuế ",

"totalAmountWithTaxInWords":"Năm mươi hai nghìn năm trăm đồng", "isTotalAmountPos":false,

Trường hợp lập hóa đơn điều chỉnh thông tin

"invoiceNote":"Điều chỉnh thông tin khách hàng cho hóa đơn điện tử số AA/17E0003470 lập ngày 11/09/2017: Tên người mua: Trịnh Thanh Hòa >Trịnh Thanh Hòa 123",

"buyerLegalName":"Trung tâm phần mềm Viettel",

"buyerEmail":"viettelsoftware@viettel.com.vn",

"sellerLegalName":"Công ty nước Lai Châu",

"sellerEmail":"hoatt16_1@viettel.com.vn"

"itemName":"Điều chỉnh thông tin khách hàng cho hóa đơn điện tử số AA/17E0003470 lập ngày 11/09/2017: Tên người mua: Trịnh Thanh Hòa >Trịnh Thanh Hòa 123",

Ví dụ định dạng XML của các tham số truyền vào

Trường hợp lập hóa đơn gốc

Lương Thị Huyền

Supplier perfom test 1

PerformanceTest1@viettel.com.vn

Khóa học tiếng anh

Ba mươi tám triệu năm trăm nghìn đồng chẵn

Trường hợp lập hóa đơn điều chỉnh tiền

Điều chỉnh tăng tiền hàng, tiền thuế cho hóa đơn điện tử số AA/17E0003470 lập ngày 11/09/2017 số tiền: 52.500

Trỏằ‹nh Thanh HÃ²a

Trung tâm phần mềm Viễn thông Viettel

Tầng 42, tòa nhà Keangnam Landmark 72 -

viettelsoftware@viettel.com.vn

Công ty cổ phần nước sạch Lai Châu - test

hoatt16_1@viettel.com.vn

Điều chỉnh tăng tiền hàng, tiền thuế

Năm mươi hai nghìn năm trăm đồng

Trường hợp lập hóa đơn điều chỉnh thông tin

Điều chỉnh thông tin khách hàng cho hóa đơn điện tử số AA/17E0003470 lập ngày 11/09/2017: Tên người mua: Trịnh Thanh Hòa >Trịnh Thanh Hòa 123

Trịnh Thanh Hòa 123

Trung tâm phần mềm Viettel

Keangnam - Hà Nội

viettelsoftware@viettel.com.vn

Công ty nước Lai Châu

hoatt16_1@viettel.com.vn

Điều chỉnh thông tin khách hàng cho hóa đơn điện tử số AA/17E0003470 lập ngày 11/09/2017: Tên người mua: Trịnh Thanh Hòa >Trịnh Thanh Hòa 123

Thông tin và ý nghĩa các trường dữ liệu:

Tên trường Kiểu dữ liệu, ràng buộc

1) Thông tin chung hóa đơn (generalInvoiceInfo) invoiceType Required: true

Mã loại hóa đơn hợp lệ bao gồm các giá trị: 01GTKT, 02GTTT, 07KPTQ, 03XKNB, và 04HGDL, theo quy định tại Thông tư hướng dẫn thi hành Nghị định số 51/2010/NĐ-CP.

Mã mẫu hóa đơn, tuân thủ theo quy định ký hiệu mẫu hóa đơn của Thông tư hướng dẫn thi hành nghị định số 51/2010/NĐ-CP invoiceSeries Required : false

Là “Ký hiệu hóa đơn” tuân thủ theo quy tắc tạo ký hiệu hóa đơn của Thông tư hướng dẫn thi hành nghị định số 51/2010/NĐ-CP

Lưu ý rằng nếu bạn nhập invoiceSeries, hệ thống sẽ sử dụng dữ liệu đó Nếu không nhập, hệ thống sẽ tự động lấy ký hiệu hóa đơn đang phát hành theo mẫu Đối với hóa đơn có nhiều dải, việc nhập invoiceSeries là bắt buộc cùng với invoiceIssuedDate.

Required: true DataType: Long Minlength:

Ngày lập hóa đơn quy đổi ra số (time in miliseconds) được thiết lập theo Nghị định 51/2010/NĐ-CP.

Hoặc 1 số định dạng như sau:

"yyyy-MM-dd'T'HH:mm:ss.SSSZ", "yyyy-MM- dd'T'HH:mm:ss.SSS'Z'", "EEE, dd MMM yyyy HH:mm:ss zzz",

"yyyy-MM-dd") currencyCode Required: true

Mã tiền tệ dùng cho hóa đơn có chiều dài 3 ký tự theo quy định của NHNN Việt Nam Ví dụ: USD, VND, EUR… adjustmentType Required: true

Trạng thái điều chỉnh hóa đơn: 1: Hóa đơn gốc 3: Hóa đơn thay thế 5: Hóa đơn điều chỉnh invoiceNo Required: true

Số hóa đơn, được sinh bởi hàm getNextInvoice invoiceNote Required: false

Ghi chú cho hóa đơn, bắt buộc cho các trường hợp lập hóa đơn thay thế, hóa đơn điều chỉnh originalInvoiceI d

DataType: String Minlength: 7 Số hóa đơn của hóa đơn đã xác thực gốc trong trường hợp hóa đơn là:

Hóa đơn thay thế Hóa đơn điều chỉnh adjustmentInvoi ceType

1: Hóa đơn điều chỉnh tiền

2: Hóa đơn điều chỉnh thông tin originalInvoiceI ssueDate

Thời gian lập hóa đơn gốc, bắt buộc trong trường hợp lập hóa đơn thay thế và hóa đơn điều chỉnh. additionalRefer enceDesc

Required : false DataType: String Minlength : Maxlength : 225 Format :

Thông tin tham khảo kèm theo hóa đơn bao gồm văn bản thỏa thuận giữa bên mua và bên bán về việc thay thế hoặc điều chỉnh hóa đơn Việc này là bắt buộc khi lập hóa đơn thay thế hoặc hóa đơn điều chỉnh.

Ngày phát sinh văn bản thỏa thuận giữa bên mua và bên bán, bắt buộc khi lập hóa đơn thay thế, hóa đơn điều chỉnh. paymentStatus Required: true

True: Đã thanh toán paymentType Required: false

Loại hình thức thanh toán: Bao gồm:

CK – Chuyển khoản DTCN – Đối trừ công nợ

TM – tiền mặt TM/CK – Tiền mặt/ Chuyển khoản

Nếu paymentStatus = true thì bắt buộc phải truyền paymentTypeNa me

Required: false DataType: String Minlength:

Tên phương thức thanh toán

Format: DTCN – Đối trừ công nợ

Nếu paymentStatus = true thì bắt buộc phải truyền cusGetInvoiceR ight

Required: true DataType: Bollean Minlength:

Mặc định true buyerIdType Required: false

Loại giấy tờ của khách hàng:

- 2: Hộ chiếu buyerIdNo Required: false

Số giấy tờ của khách hàng transactionUuid Required: false

ID giao dịch lập hóa đơn, được tạo ra từ hệ thống của bên đối tác, là duy nhất cho mỗi hóa đơn Khi gửi transactionUuid, hệ thống đối tác sẽ tự quản lý để đảm bảo tính duy nhất của nó Mỗi transactionUuid chỉ có thể liên kết với một hóa đơn; nếu đã gửi transactionUuid cho hóa đơn A, mọi yêu cầu lập hóa đơn khác với cùng transactionUuid sẽ trả về hóa đơn A Thời gian hiệu lực của transactionUuid là 3 ngày.

Khuyến cáo: sử dụng UUID V4 để tránh bị trùng số

Tham khảo: https://en.wikipedia.org/wiki/Universally_unique_identifier userName Required: false

DataType: String Tên người lập hóa đơn

2) Thông tin bên mua buyerName Required: true

Tên (đăng ký kinh doanh trong trường hợp là doanh nghiệp) của người mua buyerTaxCode Required: false

Mã số thuế người mua được cấp bởi TCT Việt Nam

Required: true DataType: String Minlength:

Maxlength: 255 Format: Địa chỉ bưu điện người mua buyerPhoneNu mber

Số điện thoại người mua buyerFaxNumb er

Số fax người mua buyerEmail Required: false

Maxlength: 50 Format: ^[_A-Za-z0- 9-\+]+(\.[_A-Za-z0- 9-]+)*@[A-Za-z0-9-]

Tên trụ sở chính ngân hàng nơi người mua mở tài khoản giao dịch buyerBankAcco unt

Tài khoản ngân hàng của người mua buyerDistrictNa me

Tên Quận Huyện buyerCityName Required: false

Tên Tỉnh/Thành phố buyerCountryC ode

3) Thông tin bên bán(sellerInfo) sellerLegalNam e

Tên (đăng ký kinh doanh trong trường hợp là doanh nghiệp) của người bán sellerTaxCode Required: true

Mã số thuế người bán được cấp bởi TCT Việt Nam Mẫu 1:

Maxlength: 255 Format: Địa chỉ bưu điện người bán sellerPhoneNu mber

Số điện thoại người bán sellerFaxNumb er

Số fax người bán sellerEmail Required: false

[A-Za-z]{2,})$ Địa chỉ thư điện tử người bán sellerBankNam e

Tên trụ sở chính ngân hàng nơi người bán mở tài khoản giao dịch sellerBankAcco unt

Tài khoản ngân hàng của người bán sellerDistrictNa me

Tên Quận Huyện sellerCityName Required: false

Tên Tỉnh/Thành phố sellerCountryC ode

4) Thông tin thanh toán (payments) paymentMethod

Tên phương thức thanh toán: Bao gồm

CK – Chuyển khoản DTCN – Đối trừ công nợ

5) Thông tin hàng hóa (itemInfo) lineNumber Required: true

Thứ tự dòng hóa đơn, bắt đầu từ 1 itemCode Required: false

Mã hàng hóa, dịch vụ itemName Required: true

Tên hàng hóa, dịch vụ unitCode Required: false

DataType: String Mã đơn vị tính TM: Tiền mặt CK: Chuyển khoản

Maxlength: 10 Format: unitName Required: true

Tên đơn vị tính hàng hóa, dịch vụ unitPrice Required: false

Maxlength: 13 Format: [0-9.]+ Đơn giá quantity Required: false

Required: true DataType: Double Minlength:

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 của hàng hóa dịch vụ chưa có VAT taxPercentage Required: false

Thuế suất của hàng hóa, dịch vụ taxAmount Required: true

Tổng tiền thuế isIncreaseItem Required: false

Hóa đơn bình thường: có giá trị là 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 - True: dòng hàng hóa dịch vụ bị điều chỉnh tăng itemNote Required: false

Ghi chú cho hàng hóa batchNo Required: false

Số lô expDate Required: false

Hạn sử dụng của hàng hóa selection Required: false

Null hoặc 1- Hàng Hóa 2: Ghi chú

6) Thông tin chiết khấu hàng hóa (discountItemInfo) lineNumber Required: true

Mã đơn vị tính Vd: C: cái … unitName Required: false

Tên đơn vị tính hàng hóa, dịch vụ vd: cái, chiếc…. unitPrice Required: false

Số tiền khấu trừ quantity Required: false

Tổng số tiền khấu trừ chưa thuế taxPercentage Required: false

Tổng tiền thuế adjustmentTaxA mount

Required: false DataType: Double Minlength:

Hóa đơn thường: có giá trị là Null Hóa đơn điều chỉnh: Tổng giá trị tiền thuế bị điều chỉnh

Hóa đơn bình thường có giá trị là Null Đối với hóa đơn điều chỉnh, nếu giá trị là False, điều này có nghĩa là dòng hàng hóa hoặc dịch vụ bị điều chỉnh giảm Ngược lại, nếu giá trị là True, điều này chỉ ra rằng dòng hàng hóa hoặc dịch vụ bị điều chỉnh tăng.

7) Thông tin tiền hàng trên hóa đơn (summarizeInfo) sumOfTotalLine

Tổng thành tiền cộng gộp của tất cả các dòng hóa đơn chưa bao gồm VAT.

- Hóa đơn thường: Tổng tiền HHDV trên các dòng HĐ

- Hóa đơn điều chỉnh: Tổng tiền điều chỉnh của các dòng HĐ. totalAmountWit houtTax

Tổng tiền hóa đơn chưa bao gồm VAT

- Hóa đơn thường: Tổng tiền HHDV trên các dòng HĐ và các khoản tăng/giảm khác trên toàn HĐ

- Hóa đơn điều chỉnh: Tổng tiền điều chỉnh của các dòng

HĐ và các khoản tăng/giảm khác trên toàn HĐ. totalTaxAmount Required: true

Tổng tiền thuế trên toàn hóa đơn.

- Hóa đơn thường: Tổng tiền VAT trên các dòng HĐ và các khoản thuế khác trên toàn HĐ.

- Hóa đơn điều chỉnh: Tổng tiền VAT điều chỉnh của các dòng HĐ và các khoản tăng/giảm VAT khác trên toàn HĐ. totalAmountWit hTax

Tổng tiền trên hóa đơn đã bao gồm VAT.

- Hóa đơn thường: Tổng tiền HHDV trên các dòng HĐ và các khoản tăng/giảm khác trên toàn HĐ đã bao gồm cả VAT.

HĐ và các khoản tăng/giảm khác trên toàn HĐ đã bao gồm cả VAT totalAmountWit Required: false

Tổng tiền ngoại tệ của hóa đơn đã bao gồm VAT hTaxFrn DataType: Double

HĐ và các khoản tăng/giảm khác trên toàn HĐ đã bao gồm cả VAT totalAmountWit hTaxInWords

Số tiền hóa đơn bao gồm VAT viết bằng chữ isTotalAmountP os

Required: false DataType: Boolean Minlength:

Trường nhận biết tổng tiền hóa đơn bao gồm VAT tăng giảm (Hóa đơn điều chỉnh):- Hóa đơn thường: null- True: tăng- False: Giảm isTotalTaxAmo untPos

Trường nhận biết tổng tiền thuế hóa đơn tăng giảm (Hóa đơn điều chỉnh):- Hóa đơn thường: null- True: tăng - False: Giảm isTotalAmtWith outTaxPos

Trường nhận biết tổng tiền hóa đơn chưa bao gồm VAT tăng giảm (Hóa đơn điều chỉnh):- Hóa đơn thường: null- True: tăng - False: Giảm discountAmoun t

Tổng tiền chiết khấu thương mại được tính trên toàn bộ hóa đơn trước khi áp dụng thuế Lưu ý rằng, trong quá trình tính chiết khấu, toàn bộ hóa đơn chỉ sử dụng một mức thuế duy nhất.

Tổng tiền chiết khấu thanh toán trên toàn hóa đơn sau khi tính thuế Chú ý: Khi tính chiết khấu, toàn hóa đơn chỉ sử dụng một mức thuế. isDiscountAmt

Required: false DataType: Boolean Trường nhận biết tổng tiền chiết khấu tăng (dương) hay giảm

(âm).False: giảm.True: tăng.Hóa đơn thường: giá trị này luôn là

False.Hóa đơn điều chỉnh: giá trị này có thể là True/False tuy vào là tăng hoặc giảm.

8) Thông tin các khoản thuế suất của hóa đơn (taxBreakdowns) taxPercentage Required: false

Mức thuế: khai báo giá trị như sau

- không phải kê khai và tính thuế GTGT: -1

- Không chịu thuế: -2 taxableAmount Required: false

Tổng tiền chịu thuế của mức thuế tương ứng taxAmount Required: false

Tổng tiền thuế của mức thuế tương ứng taxableAmount

Hóa đơn thường: giá trị này là Null Hóa đơn điều chỉnh: - True: Tổng tiền đánh thuế dương - False: Tổng tiền đánh thuế âm taxAmountPos Required: false

Hóa đơn thường: giá trị này là Null.Hóa đơn điều chỉnh:- True: Tổng tiền thuế dương - False: Tổng tiền thuế âm taxExemptionR eason

Lý do miễn giảm thuế

9) Trường thông tin bổ sung metadata Required : false

Trường dữ liệu bổ sung riêng cho từng hóa đơn, được gọi là DataType: Array, áp dụng cho các hóa đơn có thông tin người bán hoặc người mua không theo chuẩn Ví dụ, trường hợp này có thể bao gồm các mã như mã bệnh nhân hoặc mã sinh viên.

Chú thích chi tiết hơn ở mục 1.1.7 Web service trường động

10) Thông tin cho hóa đơn có các chỉ số (Mảng meterReading) – Hóa đơn đặc thù: điện, nước previousIndex Required : false

Chỉ số kỳ trước currentIndex Required : false

Chỉ số hiện tại factor Required : false

Hệ số amount Required : false

 Đầu ra: Đối tượng Response mô tả trạng thái lỗi Webservice trả về và đối tượng dữ liệu Webservice trả về:

 Dữ liệu về thông tin về hóa đơn đã lập

"supplierTaxCode": 1258694363, "invoiceNo": AA/16E0000001, "transactionID": 12523522245, "reservationCode": AXHBNK8I0H }

Phải chọn loại template hóa đơn TEMPLATE_NOT_FOUND

Tên trường bao gồm các thông tin quan trọng như mã lỗi (errorCode), mô tả lỗi (description), mã số thuế người bán (supplierTaxCode), số hóa đơn (invoiceNo), ID của giao dịch (transactionID) và mã số bí mật dùng để tra cứu khách hàng (reservationCode) Nếu lập hóa đơn thành công, giá trị của mã lỗi và mô tả lỗi sẽ là null Ví dụ, số hóa đơn có thể là AA\16E0000001.

Chú ý các tham số trong các trường hợp

Các tham số mô tả như ở trên, tuy nhiên cần chú ý: adjustmentType =’1’;

Trường hợp không quản lý trạng thái thanh toán thì cần set tham số noCheckPaymentStatus là true

Lập hóa đơn điều chỉnh thông tin, điều chỉnh tiền

Các tham số mô tả như ở trên, tuy nhiên cần chú ý các tham số sau: adjustmentType = ‘5’

Các trường dữ liệu về hóa đơn gốc là bắt buộc: invoiceNote originalInvoiceId originalInvoiceIssueDate

Thông tin về biên bản đính kèm hóa đơn gốc: additionalReferenceDate additionalReferenceDesc adjustmentInvoiceType =’1’ nếu là hóa đơn điều chỉnh tiền adjustmentInvoiceType = ‘2’ nếu là hóa đơn điều chỉnh thông tin

Lập hóa đơn thay thế: adjustmentType = ‘3’

Các trường dữ liệu về hóa đơn gốc là bắt buộc originalInvoiceId originalInvoiceIssueDate

Thông tin về biên bản đính kèm hóa đơn gốc: additionalReferenceDate additionalReferenceDesc

Để hủy hóa đơn, cần lập hóa đơn điều chỉnh giảm số tiền tương đương với hóa đơn gốc Quy trình này được thực hiện thông qua việc gọi webservice để thực hiện nghiệp vụ lập hóa đơn điều chỉnh.

Webservice lấy file hóa đơn

• Action (POST) URL: /InvoiceAPI/ InvoiceUtilsWS/getInvoiceRepresentationFile

• Các tham số của đối tượng CommonDataInput

Mô tả supplierTaxCode Required : true

Mã số thuế của doanh nghiệp xuất hóa đơn

Format : [a-zA-Z0-9/]+ invoiceNo Required : true

Mã số hóa đơn pattern Required : true

DataType: String Minlength : 11 Maxlength : 11 Format : [a-zA-Z0-9]{7}/[0-9]{3}

Mã mẫu hóa đơn, tuân thủ theo quy định ký hiệu mẫu hóa đơn của Thông tư hướng dẫn thi hành nghị định số 51/2010/NĐ-CP transactionUuid Required : false

Chuỗi xác nhận fileType Required : true

DataType: String Format : ZIP or PDF

Loại file muốn tải về paid Required : false

True – Đã thanh toán False – Chưa thanh toán

Chú ý: Để biết được tình trạng sử dụng hóa đơn của 1 dải cần một số thông tin như sau:

 supplierTaxCode: Mã số thuế của doanh nghiệp

 invoiceNo: Mã số hóa đơn

 fileType: Loại file muốn tải về

 pattern: Mã mẫu hóa đơn

Ví dụ mẫu và các trường dữ liệu:

 Đầu ra: Đối tượng Response với HTTPStatus và output Entity.

Tên trường mô tả lỗi bao gồm errorCode, với giá trị null nghĩa là không có lỗi xảy ra Thông tin thêm được cung cấp qua description, cũng có giá trị null khi không có lỗi fileName chỉ định tên file tải về, trong khi fileToBytes chứa nội dung file được chuyển đổi thành định dạng byte.

Webservice lấy file hóa đơn có mã số bí mật

Action (POST/GET): InvoiceAPI/InvoiceUtilsWS/getInvoiceFilePortal/

- Data: Dạng FormParam (với method là POST) hoặc QueryParam (với method là GET) gồm các tham số

Tên trường Kiểu dữ liệu, ràng buộc Dữ liệu/mô tả supplierTaxCo de

Mã số thuế bên bán , tuân theo tiêu chuẩn của cục thuế

Mã mẫu hóa đơn, tuân thủ theo quy định ký hiệu mẫu hóa đơn của Thông tư hướng dẫn thi hành nghị định số 51/2010/NĐ-CP invoiceNo Required: true

DataType: String Minlength: 7 Maxlength: 13 Format: [a-zA-Z0-9/]+

Là ký hiệu hóa đơn + số hóa đơn vd: AA/16E0000001, tuân theo chuẩn của cục thuế buyerIdNo Required: false

Mã số bí mật fileType Required: true

Loại file: xml, zip strIssueDate Required: true

- Ví dụ trường hợp dùng POST và FormParam

%2F18E0000039&strIssueDate 180130094136&fileType=zip&reservationCode=HXY9 RJWTND

- Ví dụ với trường hợp dùng GET và QueryParam:

/InvoiceAPI/InvoiceUtilsWS/getInvoiceFilePortal?supplierTaxCode00109106&invoiceNo=NO

%2F17E0000017&fileType=zip&strIssueDate 171227161438&reservationCode=LE3IMP8O5Y Đầu ra: Đối tượng Response mô tả trạng thái lỗi Webservice trả về và đối tượng dữ liệu Webservice trả về:

- Ví dụ: kết quả trả về với dạng FormParam

Ví dụ kết quả trả về với XML

LE3IMP8O5Y-NO_17E0000017

UEsDBBQACAgIAJV8m0sAAAAAAAAAAAAAAAALAAAAaW52b2ljZS54c2ztPVtvG9l5z1u

Mã lỗi Mô tả mã lỗi

201 Created Success of a resource creation when using the POST method

400 Bad Request The request parameters are incomplete or missing

403 Forbidden The action or the request URI is not allowed by the system

404 Not Found 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.

Mã lỗi (errorCode) sẽ có giá trị là null nếu việc lấy hóa đơn thành công Mô tả lỗi (description) cũng sẽ là null trong trường hợp này Thông tin hóa đơn được lưu trữ dưới dạng mảng bytes (fileToBytes), và khi chuyển đổi mảng bytes này thành file, nó sẽ bao gồm các thông tin liên quan đến hóa đơn, chẳng hạn như file zip chứa file xml, xsl, hình ảnh logo, watermark và mã qrcode.

Code chuyển ra file Java

FileUtils.writeByteArrayToFile(newFile("D:/viettel/fileName.zip"), output.getFileToBytes()); paymentStatus Trạng thái thanh toán fileName Tên file

Webservice lấy file hóa đơn chuyển đổi (pdf)

- Action (POST): InvoiceAPI/InvoiceWS/createExchangeInvoiceFile/

- Data: Dạng FormParam (với method là POST) hoặc QueryParam (với method là GET) gồm các tham số:

Tên trường Kiểu dữ liệu, ràng buộc Dữ liệu/mô tả supplierTaxCode Required : true

Mã số thuế bên bán

Mã mẫu hóa đơn, tuân thủ theo quy định ký hiệu mẫu hóa đơn của Thông tư hướng dẫn thi hành nghị định số 51/2010/NĐ-CP invoiceNo Required : true

DataType: String Minlength : 7 Maxlength : 13 Format : [a-zA-Z0-9/]+

Là ký hiệu hóa đơn + số hóa đơn vd : AA/16E0000001 strIssueDate Required : true

DataType: String Minlength : Maxlength : Format: yyyyMMdd

Ngày lập hóa đơn () exchangeUser Required : true

- Data: định dạng FormParam của các tham số truyền vào.

- Ví dụ với trường hợp dùng GET và QueryParam:

InvoiceAPI/InvoiceWS/createExchangeInvoiceFile? supplierTaxCode00109106&invoiceNo%2F17E0037914

Mã lỗi Mô tả mã lỗi

201 Created Success of a resource creation when using the POST method

400 Bad Request The request parameters are incomplete or missing

403 Forbidden The action or the request URI is not allowed by the system

404 Not Found 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.

Mã lỗi (errorCode) sẽ có giá trị null nếu việc lấy hóa đơn thành công Mô tả lỗi (description) cũng sẽ có giá trị null trong trường hợp này Mảng bytes (fileToBytes) chứa dữ liệu của file hóa đơn, và khi chuyển đổi mảng bytes này, bạn sẽ nhận được file PDF của hóa đơn Dưới đây là đoạn code Java để thực hiện việc chuyển đổi này.

FileUtils.writeByteArrayToFile(newFile("D:/viettel/fileName.pdf"), output.getFileToBytes()); fileName Tên của file hóa đơn

Hình ảnh Response trả về

Webservice hủy hóa đơn

Action (POST): InvoiceAPI/InvoiceWS/cancelTransactionInvoice

- Data: Dạng FormParam (với method là POST) hoặc QueryParam (với method là GET) gồm các tham số:

Tên trường Kiểu dữ liệu, ràng buộc Dữ liệu/mô tả supplierTaxCode Required : true

DataType: String Minlength : Maxlength : 11 Format : [a-zA-Z0- 9/]+

Mã mẫu hóa đơn, tuân thủ theo quy định ký hiệu mẫu hóa đơn của Thông tư hướng dẫn thi hành nghị định số 51/2010/NĐ-CP invoiceNo Required : true

Là ký hiệu hóa đơn + số hóa đơn vd : AA/16E0000001 strIssueDate Required : true

DataType: String Minlength : Maxlength : Format: yyyyMMddHHmms s

(không vượt quá ngày hiện tại)

Ngày lập hóa đơn additionalReference

Required : true DataType: String Minlength : 1 Maxlength : 100

Tên văn bản thỏa thuận hủy hóa đơn additionalReference

Required : true DataType: String Minlength : Maxlength : Format: yyyyMMddHHmms s (không vượt quá ngày hiện tại)

Tiến trình tiến hành cập nhật trạng thái hóa đơn về đã hủy trong database, và thêm các thông tin về văn bản thỏa thuận và ngày thỏa thuận.

Form Data ví dụ: supplierTaxCode00109106-997&invoiceNo

%2F17E0000325&strIssueDate 171219081259&additionalReferenceDesc=hello&additiona lReferenceDate 171222081259

Ví dụ trả về thành công:

"description": "CANCEL TRANSACTION INVOICE SUCCESS"

Tên trường mô tả lỗi bao gồm errorCode, với mã lỗi có giá trị null nếu việc lấy hóa đơn thành công Ngoài ra, description cũng là mô tả lỗi, và giá trị của nó sẽ là null khi hóa đơn được lấy thành công.

Kiểm tra hóa đơn cần xác định xem đó có phải là hóa đơn gốc, chưa kê khai thuế, đã thanh toán hay không Đồng thời, cần kiểm tra xem hóa đơn có phải là hóa đơn điều chỉnh, hóa đơn thay thế hoặc hóa đơn điều chỉnh hủy hay không Nếu thông tin hóa đơn không hợp lệ, cần phải trả lại để sửa đổi.

Webservice tra cứu hóa đơn

Doanh nghiệp có thể kết nối với webservice Hóa đơn điện tử của Viettel thông qua trang web portal của mình để tra cứu hóa đơn theo các điều kiện đã được xác định.

Ví dụ khách hàng của doanh nghiệp có thể tra cứu được các hóa đơn của mình theo khoảng thời gian

 Đầu vào: o Action(POST) URL: /InvoiceAPI/InvoiceUtilsWS/getInvoices/

{supplierTaxCode} : mã số thuế của đơn vị phát hành (có thể là mã số thuế của doanh nghiệp hoặc chi nhánh của doanh nghiệp)

Kiểu tham số Tên trường Kiểu dữ liệu, ràng buộc Mô tả

DataType: String Minlength : Maxlength : 15 Format : [a-zA-Z0-9/]+

Mã mẫu hóa đơn, tuân thủ theo quy định ký hiệu mẫu hóa đơn của Thông tư hướng dẫn thi hành nghị định số

JSon GetInvoiceInput Object Đối tượng gồm các trường dữ liệu tham số

- Data: JSON hoặc XML o Các tham số của đối tượng GetInvoiceInput

Mô tả invoiceNo Required : false

Số hóa đơn đầy đủ bao gồm seri và số

Theo định dạng XX/YYENNNNNNN.

Trong đó XX là 2 chữ cái viết hoa, YY là 2 chữ số cuối của năm (ví dụ năm 2016 thì YY là 16)

E là dấu hiệu của hóa đơn điện tử. startDate Required : true

DataType: Date Minlength : Maxlength : 50 Format :

Từ ngày endDate Required : true

DataType: Date Minlength : Maxlength : 50 Format : Đến ngày invoiceType Required : false

DataType: String Minlength : 6 Maxlength : 6 Format : [a-zA-Z0-

Loại hóa đơn, là một trong các giá trị01GTKT,02GTTT,03XKNB,04HGDL,06HDXK,07KPTQ

Số dòng trên một trang Do webservice thực hiện phân trang nên pageNum Required : true

Chỉ số trang contractNo Required : true

Số hợp đồng contractId Required : false

Id hợp đồng customerId Required : false

Id khách hàng của doanh nghiệp buyerTaxCode Required : false

Mã số thuế của khách hàng buyerIdNo Required : false

DataType: String Số giấy tờ của khách hàng templateCode Required : false

Mã mẫu hóa đơn invoiceSeri Required : false

DataType: String Minlength : 6 Maxlength : 6 Format : [a-zA-Z0- 9/]+

Chú ý: để tra cứu được hóa đơn theo một khách hàng của doanh nghiệp thì cần có một trong các thông tin:

 buyerTaxCode: Mã số thuế của khách hàng của doanh nghiệp

 customerId: Id của khách hàng của doanh nghiệp

 buyerIdNo: Số giấy tờ của khách hàng của doanh nghiệp

Ví dụ gửi dữ liệu với JSON:

Ví dụ gửi dữ liệu với XML:

Trần Trung Dũng

Đối tượng Response với HTTPStatus và output Entity.

Tên trường Mô tả errorCode Mã lỗi (giá trị là null lấy hóa đơn thành công) description Mô tả lỗi (giá trị là null lấy hóa đơn thành công)

List Danh sách các bản ghi hóa đơn thỏa mãn điều kiện

Web service trường động

- Action (GET) có truyền Query Parameter: /InvoiceAPI/InvoiceWS/getCustomFields? taxCode=&templateCode- Ví dụ: /InvoiceAPI/InvoiceWS/getCustomFields? taxCode00109106&templateCodeGTKT0%2f085

- Data: dữ liệu truyền vào dạng Query Param gồm các tham số:

Tên trường Kiểu dữ liệu, ràng buộc Mô tả taxCode Required : true

Mã số thuế templateCode Required : false

 Đầu ra: Đối tượng Response là danh sách trường động tương ứng với mẫu hóa đơn của doanh nghiệp:

"id": 189, "invoiceTemplatePrototypeId": 1032, "keyLabel": "Năm sinh",

"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",

"id": 192, "invoiceTemplatePrototypeId": 1032, "keyLabel": "Lý do thu",

Tên trường Kiểu dữ liệu, ràng buộc Mô tả id DataType: Number ID của trường động keyLabel DataType: String Tên hiển thị của trường động,

Khi lập hóa đơn, giao diện nhập liệu hiển thị các trường dữ liệu như sau: keyTag có kiểu dữ liệu là String, đại diện cho tên của trường động khi lưu vào dữ liệu; valueType cũng có kiểu dữ liệu String, xác định kiểu dữ liệu của trường động với các giá trị cho phép là “text”, “date” và “number” Thêm vào đó, trường isRequired có kiểu dữ liệu Boolean, xác định xem trường đó có bắt buộc hay không Cuối cùng, trường isSeller cũng là Boolean, với isSeller = true cho biết trường dữ liệu thuộc bên bán và isSeller = false cho biết trường dữ liệu thuộc bên mua.

Gửi dữ liệu lập hóa đơn với trường động: Thêm vào mảng metadata, mỗi phần tử bao gồm:

Required : true DataType: Number Minlength : Maxlength : 10 Format :

ID của trường động keyTag Required : true

Tên của trường động khi lưu vào dữ liệu valueType Required : true

Kiểu dữ liệu của trường động Chỉ bao gồm các giá trị: “text”, “date”, “number” keyLabel Required : true

Tên hiển thị của trường động, Hiển thị trên giao diện nhập liệu khi lập hóa đơn dateValue Required : false

Giá trị của trường dữ liệu trong trường hợp valueType = date numberValue Required : false

Giá trị của trường dữ liệu trong trường hợp valueType = number stringValue Required : false

Giá trị của trường dữ liệu trong trường hợp valueType = text

"sellerEmail":"PerformanceTest1@viettel.com.vn",

"totalTaxAmount":3500000.0, "totalAmountWithTax":38500000, "totalAmountWithTaxInWords":"Ba mươi tám triệu năm trăm nghìn đồng chẵn",

"invoiceCustomFieldId": 82, "keyTag": "buyerDateOfBirth", "dateValue": "1514019933737", "valueType": "date",

}, { "invoiceCustomFieldId": 83, "keyTag": "buyerCode", "numberValue": 12323, "valueType": "number", "keyLabel": "Mã bệnh nhân"

}, { "invoiceCustomFieldId": 84, "keyTag": "buyerDepartments", "stringValue": "Tim mach", "valueType": "text",

}, { "invoiceCustomFieldId": 85, "keyTag": "invoiceReason", "stringValue": "Khám bệnh", "valueType": "text",

Lập hóa đơn nháp

Webservice dùng chung trong các 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 thế

- Action (POST): /InvoiceAPI/InvoiceWS/createOrUpdateInvoiceDraft/{supplierTaxCode}

Tên trường Kiểu dữ liệu, ràng buộc Mô tả supplierTaxCode Required: true

- Thông số dữ liệu truyền vào tương tự phần Lập hóa đơn

Ví dụ định dạng Json

+ Trường hợp lập hóa đơn gốc.

"invoiceType":"01GTKT", "templateCode":"01GTKT0/028", "invoiceIssuedDate":1505098310271, "currencyCode":"VND",

"adjustmentType":"1", "paymentStatus":true, "paymentType":"TM", "paymentTypeName":"TM", "cusGetInvoiceRight":true, "buyerIdNo":"123456789", "buyerIdType":"1"

"buyerName":"Lương Thị Huyền", "buyerLegalName":"",

"buyerTaxCode":"", "buyerAddressLine":"HN VN", "buyerPhoneNumber":"09880830406", "buyerEmail":"",

"sellerLegalName":"Supplier perfom test 1", "sellerTaxCode":"0100109106-501",

"sellerAddressLine":"test", "sellerPhoneNumber":"0123456789", "sellerEmail":"PerformanceTest1@viettel.com.vn", "sellerBankName":"vtbank",

{ "lineNumber":1, "itemCode":"ENGLISH_COURSE", "itemName":"Khóa học tiếng anh", "unitName":"khóa học",

"totalTaxAmount":3500000.0, "totalAmountWithTax":38500000, "totalAmountWithTaxInWords":"Ba mươi tám triệu năm trăm nghìn đồng chẵn",

Thông tin và ý nghĩa các trường dữ liệu:

11) Thông tin chung hóa đơn (generalInvoiceInfo) invoiceType Required: true

Mã loại hóa đơn được chấp nhận bao gồm các giá trị: 01GTKT, 02GTTT, 07KPTQ, 03XKNB, và 04HGDL, theo quy định của Thông tư hướng dẫn thi hành Nghị định số 51/2010/NĐ-CP.

Mã mẫu hóa đơn, tuân thủ theo quy định ký hiệu mẫu hóa đơn của Thông tư hướng dẫn thi hành nghị định số 51/2010/NĐ-CP invoiceSeries Required : false

DataType: String Minlength : 6 Maxlength : 6 Format : [a-zA-Z0- 9/]+

Là “Ký hiệu hóa đơn” tuân thủ theo quy tắc tạo ký hiệu hóa đơn của Thông tư hướng dẫn thi hành nghị định số 51/2010/NĐ-CP

Nếu bạn nhập invoiceSeries, hệ thống sẽ sử dụng dữ liệu bạn cung cấp Ngược lại, nếu không có invoiceSeries, hệ thống sẽ tự động lấy ký hiệu hóa đơn theo mẫu hóa đơn invoiceIssuedDate đang được phát hành.

Required: true DataType: Long Minlength:

Ngày lập hóa đơn quy đổi ra số (time in miliseconds) được thiết lập theo Nghị định 51/2010/NĐ-CP. currencyCode Required: true

Mã tiền tệ dùng cho hóa đơn có chiều dài 3 ký tự theo quy định của NHNN Việt Nam Ví dụ: USD, VND, EUR… adjustmentType Required: true

Trạng thái điều chỉnh hóa đơn: 1: Hóa đơn gốc 3: Hóa đơn thay thế 5: Hóa đơn điều chỉnh invoiceNo Required: true

Số hóa đơn, được sinh bởi hàm getNextInvoice invoiceNote Required: false

Ghi chú cho hóa đơn, bắt buộc cho các trường hợp lập hóa đơn thay thế, hóa đơn điều chỉnh originalInvoiceI d

DataType: String Minlength: 7 Maxlength: 13 Format: [a-zA-Z0- 9/]+

Id của hóa đơn đã xác thực gốc trong trường hợp hóa đơn là:

Hóa đơn thay thế Hóa đơn điều chỉnh adjustmentInvoi ceType

1: Hóa đơn điều chỉnh tiền

2: Hóa đơn điều chỉnh thông tin originalInvoiceI ssueDate

Thời gian lập hóa đơn gốc, bắt buộc trong trường hợp lập hóa đơn thay thế và hóa đơn điều chỉnh. additionalRefer enceDesc

Required : false DataType: String Minlength : Maxlength : 225 Format :

Khi lập hóa đơn thay thế hoặc hóa đơn điều chỉnh, cần có thông tin tham khảo kèm theo, bao gồm văn bản thỏa thuận giữa bên mua và bên bán về việc thay thế hoặc điều chỉnh hóa đơn Điều này là bắt buộc để đảm bảo tính hợp lệ và minh bạch trong giao dịch.

Ngày phát sinh văn bản thỏa thuận giữa bên mua và bên bán, bắt buộc khi lập hóa đơn thay thế, hóa đơn điều chỉnh. paymentStatus Required: true

True: Đã thanh toán, false: chưa thanh toán paymentType Required: false

Loại hình thức thanh toán Nếu paymentStatus = true thì bắt buộc phải truyền

Maxlength: 30 Format: [a-zA-Z0-9- _./]+ paymentTypeNa me

Tên phương thức thanh toán Nếu paymentStatus = true thì bắt buộc phải truyền cusGetInvoiceR ight

Required: true DataType: Bollean Minlength:

Mặc định true buyerIdType Required: false

Loại giấy tờ của khách hàng:

- 3: Hộ chiếu buyerIdNo Required: false

Số giấy tờ của khách hàng transactionUuid Required: false

ID giao dịch lập hóa đơn, được tạo ra từ hệ thống đối tác, là duy nhất cho mỗi hóa đơn Khi gửi transactionUuid, hệ thống đối tác sẽ quản lý để đảm bảo tính duy nhất của nó Mỗi transactionUuid chỉ được phép gắn với một hóa đơn cụ thể; nếu đã gửi transactionUuid cho hóa đơn A, mọi yêu cầu lập hóa đơn với cùng transactionUuid sẽ trả về hóa đơn A mà không tạo hóa đơn mới Thời gian hiệu lực của transactionUuid là 3 ngày.

Khuyến cáo: sử dụng UUID V4 để tránh bị trùng số

Tham khảo: https://en.wikipedia.org/wiki/Universally_unique_identifier

12) Thông tin bên mua buyerName Required: true

Tên (đăng ký kinh doanh trong trường hợp là doanh nghiệp) của người mua buyerTaxCode Required: false

Mã số thuế người mua được cấp bởi TCT Việt Nam

Maxlength: 255 Format: Địa chỉ bưu điện người mua buyerPhoneNu mber

Số điện thoại người mua buyerFaxNumb er

Số fax người mua buyerEmail Required: false

Tên trụ sở chính ngân hàng nơi người mua mở tài khoản giao dịch buyerBankAcco unt

Tài khoản ngân hàng của người mua

13) Thông tin bên bán(sellerInfo) sellerLegalNam e

Tên (đăng ký kinh doanh trong trường hợp là doanh nghiệp) của người bán sellerTaxCode Required: true

Mã số thuế người bán được cấp bởi TCT Việt Nam Mẫu 1:

Maxlength: 255 Format: Địa chỉ bưu điện người bán sellerPhoneNu mber

Số điện thoại người bán sellerFaxNumb er

Số fax người bán sellerEmail Required: false

[A-Za-z]{2,})$ Địa chỉ thư điện tử người bán sellerBankNam e

Tên trụ sở chính ngân hàng nơi người bán mở tài khoản giao dịch sellerBankAcco unt

Tài khoản ngân hàng của người bán

14) Thông tin thanh toán (payments) paymentMethod

Tên phương thức thanh toán

15) Thông tin hàng hóa (itemInfo) lineNumber Required: true

Tên hàng hóa, dịch vụ

Maxlength: 300 Format: unitCode Required: false

Mã đơn vị tính TM: Tiền mặt CK: Chuyển khoản unitName Required: true

Tên đơn vị tính hàng hóa, dịch vụ unitPrice Required: false

Maxlength: 13 Format: [0-9.]+ Đơn giá quantity Required: false

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 của hàng hóa dịch vụ chưa có VAT taxPercentage Required: false

Tổng tiền thuế isIncreaseItem Required: false

Hóa đơn bình thường: có giá trị là 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 - True: dòng hàng hóa dịch vụ bị điều chỉnh tăng

16) Thông tin chiết khấu hàng hóa (discountItemInfo) lineNumber Required: true

Mã đơn vị tính Vd: C: cái … unitName Required: false

Tên đơn vị tính hàng hóa, dịch vụ vd: cái, chiếc…. unitPrice Required: false

Số tiền khấu trừ quantity Required: false

Tổng số tiền khấu trừ chưa thuế taxPercentage Required: false

Tổng tiền thuế adjustmentTaxA mount

Hóa đơn thường: có giá trị là Null Hóa đơn điều chỉnh: Tổng giá trị tiền thuế bị điều chỉnh isIncreaseItem Required: false

Hóa đơn bình thường có giá trị là Null Đối với hóa đơn điều chỉnh, nếu dòng hàng hóa dịch vụ bị điều chỉnh giảm thì giá trị là False, còn nếu dòng hàng hóa dịch vụ bị điều chỉnh tăng thì giá trị là True.

17) Thông tin tiền hàng trên hóa đơn (summarizeInfo) sumOfTotalLine

Tổng thành tiền cộng gộp của tất cả các dòng hóa đơn chưa bao gồm VAT.

- Hóa đơn thường: Tổng tiền HHDV trên các dòng HĐ

Tổng tiền hóa đơn chưa bao gồm VAT

- Hóa đơn thường: Tổng tiền HHDV trên các dòng HĐ và các khoản tăng/giảm khác trên toàn HĐ

HĐ và các khoản tăng/giảm khác trên toàn HĐ. totalTaxAmount Required: true

Tổng tiền thuế trên toàn hóa đơn.

- Hóa đơn thường: Tổng tiền VAT trên các dòng HĐ và các khoản thuế khác trên toàn HĐ.

- Hóa đơn điều chỉnh: Tổng tiền VAT điều chỉnh của các dòng HĐ và các khoản tăng/giảm VAT khác trên toàn HĐ. totalAmountWit hTax

Tổng tiền trên hóa đơn đã bao gồm VAT.

HĐ và các khoản tăng/giảm khác trên toàn HĐ đã bao gồm cả VAT totalAmountWit hTaxFrn

Tổng tiền ngoại tệ của hóa đơn đã bao gồm VAT

HĐ và các khoản tăng/giảm khác trên toàn HĐ đã bao gồm cả VAT totalAmountWit hTaxInWords

Số tiền hóa đơn bao gồm VAT viết bằng chữ isTotalAmountP os

Required: false DataType: Boolean Trường nhận biết tổng tiền hóa đơn bao gồm VAT tăng giảm

(Hóa đơn điều chỉnh):- Hóa đơn thường: null- True: tăng-

Trường nhận biết tổng tiền thuế hóa đơn tăng giảm (Hóa đơn điều chỉnh):- Hóa đơn thường: null- True: tăng - False: Giảm isTotalAmtWith outTaxPos

Trường nhận biết tổng tiền hóa đơn chưa bao gồm VAT tăng giảm (Hóa đơn điều chỉnh):- Hóa đơn thường: null- True: tăng - False: Giảm discountAmoun t

Tổng tiền chiết khấu trên toàn hóa đơn trước khi tính thuế Chú ý: Khi tính chiết khấu, toàn hóa đơn chỉ sử dụng một mức thuế. isDiscountAmt

Trường nhận biết tổng tiền chiết khấu có thể cho biết liệu giá trị này tăng (dương) hay giảm (âm) Đối với hóa đơn thường, giá trị luôn là False, trong khi hóa đơn điều chỉnh có thể là True hoặc False tùy thuộc vào việc là tăng hay giảm.

18) Thông tin các khoản thuế suất của hóa đơn (taxBreakdowns) taxPercentage Required: false

Mức thuế: khai báo giá trị như sau

- Không chịu thuế: null taxableAmount Required: false

Tổng tiền chịu thuế của mức thuế tương ứng taxAmount Required: false

Tổng tiền thuế của mức thuế tương ứng taxableAmount

Hóa đơn thường: giá trị này là Null Hóa đơn điều chỉnh: - True: Tổng tiền đánh thuế dương - False: Tổng tiền đánh thuế âm taxAmountPos Required: false

Hóa đơn thường: giá trị này là Null.Hóa đơn điều chỉnh:- True: Tổng tiền thuế dương - False: Tổng tiền thuế âm taxExemptionR eason

Lý do miễn giảm thuế

19) Trường thông tin bổ sung metadata Required : false

Trường dữ liệu bổ sung riêng cho từng hóa đơn được gọi là DataType: Array Trường này áp dụng cho các hóa đơn có thông tin người bán hoặc người mua không theo định dạng chuẩn, chẳng hạn như khi có thêm mã bệnh nhân hoặc mã sinh viên Để biết thêm chi tiết, vui lòng tham khảo mục 1.1.7 về web service trường động.

 Dữ liệu về thông tin về hóa đơn đã lập

"supplierTaxCode": 1258694363, "invoiceNo": AA/16E0000001, "transactionID": 12523522245, "reservationCode": AXHBNK8I0H }

Phải chọn loại template hóa đơn

TEMPLATE_NOT_FOUND

Tên trường bao gồm mã lỗi (errorCode), mô tả lỗi (description), mã số thuế người bán (supplierTaxCode), số hóa đơn (invoiceNo), mã giao dịch (transactionID), và mã số bí mật (reservationCode) dùng để tra cứu khách hàng Mã lỗi và mô tả lỗi sẽ có giá trị null nếu lập hóa đơn thành công Số hóa đơn được định dạng như ví dụ: AA\16E0000001.

Webservice 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ẽ sử dụng hàm sau.

 Đầu vào: o Action (POST) URL: /InvoiceAPI/InvoiceWS/createBatchInvoice/

Mô tả supplierTaxCode Required: true

- Ví dụ định dạng Json

"sellerEmail":"PerformanceTest1@viettel.com.vn",

"totalAmountWithTaxInWords":"Ba mươi tám triệu năm trăm nghìn đồng chẵn",

The detailed information includes a list of invoice data similar to the invoice creation section (Section 2.1.1), encompassing the following elements: general invoice information, buyer details, seller information, external attributes, payment details, delivery information, item specifics, discount item information, summary data, tax breakdowns, metadata, custom fields, and meter readings.

Kết quả khi lập hóa đơn theo lô thành công

Webservice Cập nhật kê khai thuế

- Action (POST): InvoiceAPI/InvoiceUtilsWS/updateTaxDeclaration/

- + Authorization: username/pass như đăng nhập trên web

- + Content-Type: application/json (application/xml) gồm các tham số:

Tên trường Kiểu dữ liệu, ràng buộc Dữ liệu/mô tả supplierTaxCode Required: true

Mã mẫu hóa đơn, tuân thủ theo quy định ký hiệu mẫu hóa đơn của Thông tư hướng dẫn thi hành nghị định số 51/2010/NĐ-CP strIssueDate Required: true

- Ví dụ với định dạng json:

- Ví dụ với định dạng xml:

Hình ảnh Response trả về thành công

Webservice cung cấp tình hình sử dụng hóa đơn theo dải

• Action (POST) URL: /InvoiceAPI/ InvoiceUtilsWS/getProvidesStatusUsingInvoice

Mã mẫu hóa đơn, tuân thủ theo quy định ký hiệu mẫu hóa đơn của Thông tư hướng dẫn thi hành nghị định số 51/2010/NĐ-CP pattern Required : true

Mã mẫu hóa đơn serial Required : true

 pattern: Mã số mẫu hóa đơn

Trường thông tin bao gồm tên trường, mã lỗi, mô tả lỗi, trạng thái, tổng số hóa đơn đã phát hành và tổng số hóa đơn có thể lập Mã lỗi và mô tả lỗi sẽ có giá trị là null nếu không có lỗi xảy ra, trong khi trạng thái sẽ có giá trị 200 khi việc 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 được thể hiện qua numOfpublishInv, và tổng số hóa đơn có thể lập được tính bằng tổng số hóa đơn có mẫu hóa đơn cùng với dải truyền vào.

Webservice cung cấp danh sách hóa đơn theo khoảng thời gian

• Action (POST) URL: /InvoiceAPI/ InvoiceUtilsWS/getListInvoiceDataControl

Mã mẫu hóa đơn, tuân thủ theo quy định ký hiệu mẫu hóa đơn của Thông tư hướng dẫn thi hành nghị định số 51/2010/NĐ-CP fromDate Required : true

DataType: String Format : dd/MM/yyyy

Ngày bắt đầu muốn tìm kiếm toDate Required : true

DataType: String Format : dd/MM/yyyy

Ngày kết thúc muốn tìm kiếm

 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

Tên trường mô tả lỗi bao gồm errorCode và description, trong đó giá trị null biểu thị không có lỗi xảy ra Danh sách lstInvoiceBO chứa các hóa đơn được tạo ra theo thời gian được truyền vào.

Webservice gửi email cho các hoá đơn khách hàng

• Action URL: /InvoiceAPI/ InvoiceUtilsWS/sendHtmlMailProcess

Tên tham số Kiểu dữ liệu, ràng buộc

Mã mẫu hóa đơn, tuân thủ theo quy định ký hiệu mẫu hóa đơn của Thông tư hướng dẫn thi hành nghị định số 51/2010/NĐ-CP lstTransactionUuid Required : true

Danh sách key request, mỗi transactionUuid tương ứng với 1 hoá đơn (Validate độ dài transactionUuid trong khoảng 32 – 36 ký tự)

Chú ý: Để gửi email cho các hoá đơn khách hàng cần một số thông tin như sau:

 lstTransactionUuid: Danh sách key request

idtest9999999999,testuuid8888888,transactionUuid123

 Đầura: Đối tượng Response với HTTPStatus và output Entity.

Tên trường mô tả lỗi và mã lỗi có giá trị null, cho thấy không có lỗi nào xảy ra.

Tiêu đề	Tài Liệu Mô Tả Webservice Hóa Đơn Điện Tử
Trường học	Tập Đoàn Viễn Thông Viettel
Thể loại	tài liệu
Năm xuất bản	2017
Thành phố	Hà Nội

Định dạng
Số trang	75
Dung lượng	909,5 KB