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 ĐOÀN VIỄN THÔNG QUÂN ĐỘ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 bản Ngày

Chi tiết

0.1

09/2017

Phiên bả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ả bản 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ữ và viết tắt..................................................................................................................................6
Mục đích và phạm vi..................................................................................................................................6
Mô hình kết nối...........................................................................................................................................6
Các tiêu chuẩn.............................................................................................................................................7
4.1. Tiêu chuẩn thời gian........................................................................................................................7
4.2. Tiêu chuẩn dữ liệu...........................................................................................................................8
4.3. Các ký tự đặc biệt...........................................................................................................................8
Các API kết nối............................................................................................................................................8
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 các 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 trong usb token.................................................................................................40
5.17. Chuyển font.................................................................................................................................41
5.18. Cập nhật trạng thái thanh toán....................................................................................................42
5.19. Hủy trạng thái thanh 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 bằng POSTMAN..............................................................................................................73

v1.0 Sinvoice: Tài liệu mô tả webservice

5/73


Thuật ngữ và viết tắt
STT
1

Từ viết tắt

Nghĩa đầy đủ

XML

eXtensible Markup Language - Ngôn ngữ Đánh dấu Mở rộng

2

VAN

Taxation Value Added Network

3

ICC

Invoice Certification Center

4

PSD

Portable Security Device

5

SGML

Standard Generalized Markup Language

6

W3C

World Wide Web Consortium, viết tắt W3C, lập ra các chuẩn cho
Internet, nhất là cho World Wide Web

7

SInvoice

Dịch vụ/hệ thống hóa đơn điện tử của Viettel

8

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 và phạm vi
Mô tả chi tiết chuẩn kết nối để các hệ thống có thể kết nối vào dịch vụ Hóa đơn điện tử đại trà của
Viettel nhằm đảm bảo phát hành đúng thông tin.

Mô hình kết nối

Hệ thống SInvoice đóng vai trò nhận dữ liệu hóa đơn từ các hệ thống bên ngoài (hệ thống tích
hợp) gửi về và phát hành thành hóa đơn theo mẫu mà doanh nghiệp đã chọn. Các API của hệ thống
SInvoice được cung cấp theo chuẩn Restful Webservice, hỗ trợ cả XML và Json.
Ban đầu, doanh nghiệp thực hiện các thao tác khai báo mẫu hóa đơn trên web của 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 các bước hướng dẫn có thể xem thêm tại: />Sau khi các thông tin khai báo mẫu hóa đơn đã được thực hiện đầy đủ trên SInvoice, doanh nghiệp
có thể thông qua các hệ thống bên ngoài để gọi các API thực hiện 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 và USB token sử dụng các hàm khác nhau. HSM sử
dụng 1 hàm duy nhất, việc tương tác với chữ ký do hệ thống Hóa đơn điện tử đảm nhiệm. USB sử
dụng 2 hàm khác nhau, việc tương tác với chữ ký do phần mềm tích hợp đảm nhiệm. Khách hàng cần
được tư vấn trước khi sử dụng.
Lưu ý 2: Một doanh nghiệp có thể có nhiều mã số thuế (doanh nghiệp, chi nhánh), mẫu hóa đơn, ký
hiệu hóa đơn. Vì vậy các 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 này sang hệ thống sẽ tự động nhận phần giờ là 00:00:00
Các ngôn ngữ khác có thể xác định thời gian như sau:
-

Sử dụng chuẩn UNIX time: là hệ thống mô tả một điểm trong thời gian. Thời gian Unix được
định nghĩa bằng số giây kể từ 00:00:00 theo giờ Phối hợp Quốc tế (UTC) ngày 1 tháng 1 năm
1970, trừ đi giây nhuận. Tính đến mili giây. Tham khảo />o Ví dụ: 1551872514000.
o Lưu ý: Đối với UNIX time chỉ sử dụng cho đầu vào là json.

-

Lưu ý: múi giờ hệ thống SInvoice đang chạy là GMT+7, trong trường hợp gửi UNIX time sang
là giờ UTC thì hệ thống sẽ tự động chuyển sang GMT+7 (cộng thêm 7 giờ vào giờ gốc).

4.2.

Tiêu chuẩn dữ liệu

-

Hệ thống SInvoice hỗ trợ dữ liệu chuẩn Unicode (UTF-8)

-

Đối với các dữ liệu gửi sang, hệ thống SInvoice sẽ để nguyên format dữ liệu để hiển thị. Ngoài
trừ với dữ 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 luôn có định dạng là [0-9.]+. Ví dụ như 100000.1234. Template của
SInvoice sẽ tự động format hiển thị. Đối với dữ liệu như tên ngân hàng, tài khoản có thể nhập nhiều,
cách nhau bởi dấu “;”.

4.3.

Các ký tự đặc biệt

Các ký tự đặc biệt cần lưu ý và 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 và hàm thực thi (ví dụ: “/InvoiceAPI/InvoiceWS” phương thức POST).

-

Data: định dạng dữ liệu truyền vào.

-

Đầu ra webservice: Đố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ề

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 hiện test kết nối trên hệ thống test không test kết nối trên hệ
thống thật)

Link web:
Link API: :8443/InvoiceAPI
Link nội bộ: https://10.60.105.238:8443
-

Thông tin hệ thống thật (Chỉ thực hiện phát hành hóa đơn thật sự)

Link web:
Link API: :443
Link nội bộ: https://10.60.135.246:443
-

Header xác thực: Header xác thực được gửi đi cùng mỗi request trong quá trình sử dụng. Xác
thực bằng chuỗi user:pass (Basic Authentication) được mã hóa dạng Base64. Header xác thực
có format Authorization: Basic QWxhZGRpbjpPcGVuU2VzYW1l
Chi tiết xem thêm tại link: />
Ví dụ: Với user/pass: 0100109106-997/123456a@A (Tài khoản test sẽ được gửi riêng)
Chuỗi đầu vào mã hóa sẽ là 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 cũng hỗ trợ Basic Authentication này.
Lưu ý: Với mỗi user, hệ thống chỉ cho phép một vài địa chỉ IP nhất định truy cập đến web service.
IP phải là IP public của hệ thống đối tác. Để cập nhật IP, người dùng có thể tự cập nhật thông qua các

bước như sau:
B1: Vào hệ thống trên web, sử dụng đúng acc đang 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 màn hình cập nhật thông tin, trường thông tin địa chỉ IP được khai báo theo quy định như
sau: Các IP liên tiếp phân cách bằng ký tự |.
Ví dụ: 2.2.2.2|3.3.3.3|4.4.4.4
Chi tiết xem tại: />
Bất cứ trường hợp nào sai tài khoản/mật khẩu hay IP sẽ nhận về kết quả trả về là 500
Request Fail.
-

Header định dạng dữ liệu: Dữ liệu gửi lên Web service có thể là 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ả về từ Web service có thể là JSON hay XML
o Để nhận về JSON: Thêm header: Accept: application/xml
o Để nhận về XML: Thêm header: Accept: application/json

Lưu ý: Do cần thời gian kết nối và thời gian xử lý yêu cầu nên kết quả trả về có thể phải chờ 1 khoảng
thời gian (khuyến nghị để thời gian timeout khi 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 các trường thông tin chi tiết xem ở mục 6
 Đầu vào:
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}
Trong đó: {supplierTaxCode}: mã số thuế của doanh nghiệp/chi nhánh phát hành

v1.0 Sinvoice: Tài liệu mô tả webservice

10/73


Tên trường

Kiểu dữ liệu,

Mô tả

ràng buộc
supplierTaxCode

Required: true

Mã số thuế của doanh nghiệp/chi nhánh phát hành hóa đơn.

DataType:

Một doanh nghiệp có thể có nhiều mã số thuế

String

Mẫu 1: 0312770607

Minlength: 10

Mẫu 2: 0312770607-001

Maxlength: 14

Hệ thống sẽ dùng trường thông tin này để kiểm tra và lấy thông

Format : [0-9-]+

tin về mã số thuế của chi nhánh/doanh nghiệp.
/>%87t_Nam

Data: Dữ liệu mẫu lập hóa đơn.

-

Lưu ý: các dữ liệu này bao gồm tất cả các trường dữ liệu có thể có khi lập hóa đơn. Không phải tất cả
các trường thông tin đều bắt buộc, người dùng có thể bỏ bớt cho phù hợp với nhu cầu của khách hàng.
Chi tiết các trường thông tin bắt buộc hoặc không bắt buộc xem ở mục 6.

Dữ liệu mẫu

JSON

XML

Hóa đơn gốc
HD_Goc.txt

HD_Goc.xml

HD_ThayThe.txt

HD_ThayThe.xml

Hóa đơn thay thế

Hóa đơn điều chỉnh thông tin (dự
kiến bỏ theo NĐ 119)

HD_DieuChinh_ThongTin.txt

HD_DieuChinh_ThongTin.xml

Hóa đơn điều chỉnh tiền (dự kiến
bỏ theo NĐ 119)

HD_DieuChinh_Tien.txt

HD_DieuChinh_Tien.xml

 Đầ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

{
"errorCode": "",
"description": "",
"result": {
"supplierTaxCode": 1258694363,
"invoiceNo": AA/16E0000001,
"transactionID": 12523522245,
"reservationCode": AXHBNK8I0H
}
}

v1.0 Sinvoice: Tài liệu mô tả webservice

11/73


Định dạng XML
<?xml version="1.0" encoding="UTF-8" standalone="yes" ?>
<createInvoiceOutput>
<result>
<invoiceNo>BD/17E0000110</invoiceNo>
<reservationCode>2M9U3PU638</reservationCode>
<supplierTaxCode>0100109106</supplierTaxCode>

<transactionID>1514296135756</transactionID>
</result>
</createInvoiceOutput>
<?xml version="1.0" encoding="UTF-8" standalone="yes" ?>
<createInvoiceOutput>
<description>Phải chọn loại template hóa đơn</description>
<errorCode>TEMPLATE_NOT_FOUND</errorCode>
</createInvoiceOutput>

Mô tả
Tên trường
errorCode
description
supplierTaxCode
invoiceNo
transactionID
reservationCode

Mô tả
Mã lỗi (giá trị là null nếu lập hóa đơn thành công)
Mô tả lỗi (giá trị là null nếu 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 ví dụ: AA/16E0000001
Id của giao dịch
Mã số bí mật dùng để tra khách hàng tra cứu

5.3. Lấy file hóa đơn
Webservice dùng cho hệ thống tích hợp có thể lấy các file hóa đơn sau khi được lập ở bước 5.2 về.
Lưu ý: Hệ thống hóa đơn điện tử chạy theo cơ chế bất đồng bộ, vì vậy hệ thống đẩy hóa đơn lên cơ sở
dữ liệu sau khi nhận request phát hành hóa đơn khoảng 1s. Vì vậy, khi tích hợp, request lấy file hóa

đơn nên được thực hiện sau từ 2-5 giây sau khi phát hành hóa đơn.
 Đầu vào:
• Action (POST) URL: /InvoiceAPI/InvoiceUtilsWS/getInvoiceRepresentationFile
• Các tham số của đối tượng CommonDataInput
Tên tham số

Kiểu dữ liệu,

Mô tả

ràng buộc
supplierTaxCode

Required: true

Mã số thuế của doanh nghiệp/chi nhánh phát hành hóa

DataType: String

đơn. Một doanh nghiệp có thể có nhiều mã số thuế

Minlength: 10

Mẫu 1: 0312770607

Maxlength: 14

Mẫu 2: 0312770607-001

Format : [0-9-]+

/>%E1%BB%87t_Nam

v1.0 Sinvoice: Tài liệu mô tả webservice

12/73


invoiceNo

Required : true

Số hóa đơn, bao gồm ký hiệu hóa đơn và số thứ tự hóa

DataType: String

đơn

Format : [A-Z]{2}/

templateCode

transactionUuid

[a-zA-Z0-9]{10}
Required : true

Mã mẫu hóa đơn

DataType: String

Mã mẫu hóa đơn, tuân thủ theo quy định ký hiệu mẫu hóa

Minlength : 11

đơn của Thông tư hướng dẫn thi hành nghị định số

Maxlength : 11

51/2010/NĐ-CP

Format : [a-zA-Z0-

Chi tiết xem PL1 Thông tư 39/2014/TT-BTC

9]{7}/[0-9]{3}
Required : false

Chuỗi kiểm tra dữ liệu (fkey) được truyền vào khi lập hóa

DataType: String

đơn. Chi tiết xem mục 6.2

Minlength : 10
Maxlength : 36
fileType

Format : N/A
Required : false

Loại file muốn tải về, các định dạng được phép ZIP, PDF

DataType: String
Minlength : 3
Maxlength : 3
paid

Format : N/A
Required : false

true – Đã thanh toán

DataType: boolean

false – Chưa thanh toán

Minlength : 3
Maxlength : 3
Format : N/A

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

JSON:
{
"supplierTaxCode":"0100109106",
"invoiceNo":"AA/17E0000166",
"pattern":"01GTKT0/151",
"transactionUuid":"testuuid9999999",

"fileType":"ZIP"
}

-

XML:

v1.0 Sinvoice: Tài liệu mô tả webservice

13/73


<?xml version="1.0" encoding="UTF-8" ?>
<commonDataInput>
<supplierTaxCode>0100109106</supplierTaxCode>
< invoiceNo>AA/17E0000166</invoiceNo >
< pattern>01GTKT0/151</ pattern >
< transactionUuid >ZIP</ transactionUuid >
< fileType>ZIP</fileType >
</commonDataInput>

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

Mô tả

errorCode
description
fileName

fileToBytes

Mã lỗi (giá trị là null không có lỗi gì xảy ra)
Mô tả lỗi (giá trị là null không có lỗi gì xảy ra)
Tên file tải về
Nội dung file được chuyển thành kiểu byte

5.4. Lấy file hóa đơn có mã số bí mật
Cho phép lấy file hóa đơn có kiểm tra mã số bí mật.
Lưu ý: Hệ thống hóa đơn điện tử chạy theo cơ chế bất đồng bộ, vì vậy hệ thống đẩy hóa đơn lên cơ sở
dữ liệu sau khi nhận request phát hành hóa đơn khoảng 1s. Vì vậy, khi tích hợp, request lấy file hóa
đơn nên được thực hiện sau từ 2-5 giây sau khi phát hành hóa đơn.
 Đầu vào:
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

Mô tả

buộc
supplierTaxCod

Required: true

Mã số thuế của doanh nghiệp/chi nhánh phát hành hóa đơn.

e

DataType: String

Một doanh nghiệp có thể có nhiều mã số thuế

Minlength:

Mẫu 1: 0312770607

Maxlength: 11

Mẫu 2: 0312770607-001

Format: [a-zA-Z0-9/]+

templateCode

Hiện đang chưa có, cần bổ sung, không bắt buộc do có

v1.0 Sinvoice: Tài liệu mô tả webservice

14/73


KH cũ không truyền.
invoiceNo

Required: true

Là ký hiệu hóa đơn + số hóa đơn vd: AA/16E0000001, tuân

DataType: String

theo chuẩn của cục thuế

Minlength: 7
Maxlength: 13
buyerIdNo

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

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

DataType: String
Minlength:
Maxlength: 100
reservationCode

Format:
Required: true

Mã số bí mật

DataType: String
Minlength:
Maxlength: 100

Format:
Required: true

fileType

Loại file: xml, zip

DataType: String
Minlength:
Maxlength: 100
strIssueDate

Format:
Required: true

Ngày lập hóa đơn. Cần bổ sung format hỗ trợ, trường

DataType: String

này không nên bắt buộc. Có thể bỏ đi.

Minlength:
Maxlength:
Format:
yyyyMMddHHmmss
-

Ví dụ trường hợp dùng POST và FormParam
Body:
supplierTaxCode=0100109106&invoiceNo=AC

%2F18E0000039&strIssueDate=20180130094136&fileType=zip&reservationCode=HXY9RJWTND

-

Ví dụ với trường hợp dùng GET và QueryParam:
/InvoiceAPI/InvoiceUtilsWS/getInvoiceFilePortal?supplierTaxCode=0100109106&invoiceNo=NO
%2F17E0000017&fileType=zip&strIssueDate=20171227161438&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

v1.0 Sinvoice: Tài liệu mô tả webservice

15/73


Ví dụ kết quả trả về với XML
<?xml version="1.0" encoding="UTF-8" ?>
<invoiceFileOutput>
<fileName>LE3IMP8O5Y-NO_17E0000017</fileName>
<fileToBytes>UEsDBBQACAgIAJV8m0sAAAAAAAAAAAAAAAALAAAAaW52b2ljZS54c2ztPVtvG9l5z1u</fileToBytes>
true</paymentStatus>
</invoiceFileOutput>

Bảng mã lỗi :
Mã lỗi

Mô tả mã lỗi

200 OK
201 Created
400 Bad Request
403 Forbidden
404 Not Found
422 Unprocessable Entity
429 Too Many Requests

Success
Success of a resource creation when using the POST method
The request parameters are incomplete or missing
The action or the request URI is not allowed by the system
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

500 Internal Server Error

limited
Used in case of time out or when the request, otherwise correct, was
not able to complete.

Mô tả
Tên trường
errorCode
description
fileToBytes

Mô tả
Mã lỗi (giá trị là null nếu lấy hóa đơn thành công)
Mô tả lỗi (giá trị là null nếu lấy hóa đơn thành công)

Mảng bytes file hóa đơn, chuyển mảng bytes này ra file sẽ được file chứa các
thông tin của hóa đơn, ví dụ file .zip bao gồm file .xml, .xsl, ảnh logo, watermark,
qrcode

v1.0 Sinvoice: Tài liệu mô tả webservice

16/73


Code chuyển ra file Java
FileUtils.writeByteArrayToFile(newFile("D:/viettel/fileName.zip"), output.getFileToBytes());

paymentStatus
fileName

Trạng thái thanh toán
Tên file

5.5. Lấy file hóa đơn chuyển đổi (pdf)
Cho phép hệ thống tích hợp lấy file hóa đơn chuyển đổi của hóa đơn điện tử. Trong trường hợp hóa
đơn đã được chuyển đổi trước đó, SInvoice sẽ cho tải lại file cũ mà không tạo ra file mới.
Lưu ý: Hệ thống hóa đơn điện tử chạy theo cơ chế bất đồng bộ, vì vậy hệ thống đẩy hóa đơn lên cơ sở
dữ liệu sau khi nhận request phát hành hóa đơn khoảng 1s. Vì vậy, khi tích hợp, request lấy file hóa
đơn nên được thực hiện sau từ 2-5 giây sau khi phát hành hóa đơn.
 Đầu vào:
-

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,

Mô tả

ràng buộc
supplierTaxCode

Required : true

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

DataType: String

Mã mẫu hóa đơn, tuân thủ theo quy định ký hiệu mẫu hóa đơn

Minlength :

của Thông tư hướng dẫn thi hành nghị định số 51/2010/NĐ-

Maxlength : 11

CP

Format : [a-zAZ0-9/]+

templateCode

Hiện đang chưa có, cần bổ sung, không bắt buộc do có
KH cũ không truyền.

invoiceNo

Required : true

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

DataType: String
Minlength : 7
Maxlength : 13
Format : [a-zA-

strIssueDate

Z0-9/]+
Required : true

Ngày lập hóa đơn. Bổ sung format hỗ trợ, trường này

DataType: String

không nên bắt buộc.

Minlength :
Maxlength :

v1.0 Sinvoice: Tài liệu mô tả webservice

17/73


Format:
yyyyMMdd
Required : true

exchangeUser

Tên người chuyển đổi

DataType: String
Minlength : 1
Maxlength : 100
-

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

supplierTaxCode=0100109106&invoiceNo=AC

%2F18E0000039&strIssueDate=20180130094136&exchangeUser=%C4%90%E1%BA%B7ng%20T.T
%20T%C3%A2m

-

Ví dụ với trường hợp dùng GET và QueryParam:
InvoiceAPI/InvoiceWS/createExchangeInvoiceFile?
supplierTaxCode=0100109106&invoiceNo=AA%2F17E0037914
&strIssueDate=20170907161438&exchangeUser=%C4%90%E1%BA%B7ng%20T.T%20T
%C3%A2m
 Đầ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ề:


Bảng mã lỗi :

Mã lỗi

Mô tả mã lỗi

200 OK
201 Created
400 Bad Request
403 Forbidden
404 Not Found
422 Unprocessable Entity
429 Too Many Requests

Success
Success of a resource creation when using the POST method
The request parameters are incomplete or missing
The action or the request URI is not allowed by the system

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

500 Internal Server Error

limited
Used in case of time out or when the request, otherwise correct, was
not able to complete.

Mô tả
Tên trường

Mô tả

errorCode
description

Mã lỗi (giá trị là null nếu lấy hóa đơn thành công)
Mô tả lỗi (giá trị là null nếu lấy hóa đơn thành công)

fileToBytes

Mảng bytes file hóa đơn, chuyển mảng bytes này ra file sẽ được file pdf hóa đơn
chuyển đổi
Code chuyển ra file Java

v1.0 Sinvoice: Tài liệu mô tả webservice

18/73

FileUtils.writeByteArrayToFile(newFile("D:/viettel/fileName.pdf"),
output.getFileToBytes());

fileName

Tên của file hóa đơn

Hình ảnh Response trả về

5.6. Hủy hóa đơn
Cho phép xóa bỏ (chuyển hóa đơn sang trạng thái hóa bỏ) trên hệ thống SInvoice, từ hệ thống tích
hợp.
 Đầu vào:
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

Mô tả

buộc
supplierTaxCode

Required : true

Mã số thuế của doanh nghiệp/chi nhánh phát hành hóa

DataType: String

đơn. Một doanh nghiệp có thể có nhiều mã số thuế

Minlength :

Mẫu 1: 0312770607

Maxlength : 11

Mẫu 2: 0312770607-001

Format : [a-zA-Z0-9/]+

templateCode

Hiện đang chưa có, cần bổ sung, không bắt buộc do
có KH cũ không truyền.

invoiceNo

Required : true

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

DataType: String
Minlength : 7

Maxlength : 13
Format :

[a-zA-Z0-

9/]+

v1.0 Sinvoice: Tài liệu mô tả webservice

19/73


strIssueDate

Required : true

Ngày lập hóa đơn Cần chi tiết format hỗ trợ, không

DataType: String

bắt buộc.

Minlength :

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

Maxlength :
Format:
additionalRefere

yyyyMMddHHmmss
Required : true

nceDesc

DataType: String

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

Minlength : 1

additionalRefer

Maxlength : 100
Required : true

Ngày thỏa thuận Cần chi tiết format hỗ trợ

enceDate

DataType: String

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

Minlength :
Maxlength :
Format:
yyyyMMddHHmmss

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ụ:
supplierTaxCode=0100109106-997&invoiceNo=AB
%2F17E0000325&strIssueDate=20171219081259&additionalReferenceDesc=hello&additionalReferenceDate=201712220
81259

 Đầ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ụ trả về thành công:
{
"errorCode": null,
"description": "CANCEL TRANSACTION INVOICE SUCCESS"
}



Bảng mã lỗi :

Mô tả
Tên trường
errorCode
description

Mô tả
Mã lỗi (giá trị là null nếu lấy hóa đơn thành công)
Mô tả lỗi (giá trị là null nếu lấy hóa đơn thành công),
Kiểm tra hóa đơn có phải là các hóa đơn gốc, chưa kê khai thuế
,trạng thái đã thanh toán, không phải hóa đơn điều chỉnh , hóa
đơn thay thế và không và hóa đơn điều chỉnh hủy hay không?

v1.0 Sinvoice: Tài liệu mô tả webservice

20/73


Nếu phải trả lại thông tin hóa đơn không hợp lệ

5.7. Tra cứu hóa đơn
Trường hợp doanh nghiệp có trang webportal để tra cứu hóa đơn thì có thể kết nối đến
webservice Hóa đơn điện tử của Viettel để tra cứu hóa đơn theo các điều kiện.
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}
 Trong đó:
{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)
Tên trường

Kiểu dữ liệu,

Mô tả

ràng buộc

supplierTaxCode

Required : true

Mã số thuế của doanh nghiệp/chi nhánh phát hành hóa

DataType: String

đơn. Một doanh nghiệp có thể có nhiều mã số thuế

Minlength :

Mẫu 1: 0312770607

Maxlength : 15

Mẫu 2: 0312770607-001

Format : [a-zA-Z0GetInvoiceInput
-

9/]+
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
Tên tham số

Mô tả
Kiểu dữ liệu, ràng

invoiceNo

Required : false
DataType: String

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

Minlength : 7
Maxlength : 13
Format :

startDate

[a-zA-Z0-

9/]+
Required : true

Từ ngày

v1.0 Sinvoice: Tài liệu mô tả webservice

21/73


DataType: Date

Minlength :
Maxlength : 50

endDate

Format :
Required : true

Đến ngày

DataType: Date
Minlength :
Maxlength : 50

invoiceType

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

rowPerPage

:

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

[a-zA-Z0-

9/]+
Required : true
DataType: Number

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

Minlength :

pageNum

Maxlength : 18
Required : true

Chỉ số trang

DataType: Number
Minlength :

contractNo

Maxlength : 18
Required : true
DataType: Number

Số hợp đồng

Minlength :

contractId

Maxlength : 18
Required : false
DataType: Number

Id hợp đồng

Minlength :

customerId

Maxlength : 18
Required : false
DataType: Number

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

Minlength :

buyerTaxCode

Maxlength : 18
Required : false
DataType: Long

Mã số thuế của khách hàng

Minlength :
Maxlength : 15

v1.0 Sinvoice: Tài liệu mô tả webservice

22/73


Required : false

buyerIdNo

DataType: String

templateCode

Required : false
DataType: String

Số giấy tờ của khách hàng
Mã mẫu hóa đơn.

Minlength : 11
Maxlength : 11
Required : false

invoiceSeri

DataType: String

Seri hóa đơn

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



contractNo: Số hợp đồng



contractId: Id hợp đồng



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:
{
"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 dữ liệu với XML:
<?xml version="1.0" encoding="UTF-8" ?>
<getInvoiceInput>
<startDate>2017-12-12T10:14:32.611+07:00</startDate>
<endDate>2017-12-31T10:14:32.611+07:00</endDate>
<invoiceType>02GTTT</invoiceType>
<rowPerPage>20</rowPerPage>
1</pageNum>
<templateCode />
<contractNo />
<contractId />
<buyerTaxCode />
<invoiceSeri />

v1.0 Sinvoice: Tài liệu mô tả webservice

23/73


</getInvoiceInput>

 Đầ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
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<invoicesOutput>

<invoices>
<adjustmentType>1</adjustmentType>
<buyerName>Trần Trung Dũng</buyerName>
<buyerTaxCode>6200000230</buyerTaxCode>
<createTime>2017-12-26T16:50:26+07:00</createTime>
<currency>VND</currency>
<invoiceId>213469</invoiceId>
<invoiceNo>QT/17E0000003</invoiceNo>
<invoiceNumber>0000003</invoiceNumber>
<invoiceSeri>QT/17E</invoiceSeri>
<invoiceType>02GTTT</invoiceType>
<issueDate>2017-12-26T16:50:15+07:00</issueDate>
1</paymentStatus>
<supplierTaxCode>0100109106</supplierTaxCode>
<taxAmount>0</taxAmount>
<templateCode>02GTTT0/089</templateCode>
<total>3800000</total>
<totalBeforeTax>3800000</totalBeforeTax>

v1.0 Sinvoice: Tài liệu mô tả webservice

25/73