API tích hợp hóa đơn thay thế, điều chỉnh Sinvoice Viettel (json mẫu)

Mục lục

Hướng dẫn API tích hợp cho hóa đơn điều chỉnh và thay thế Sinvoice Viettel (json mẫu)

Do nhiều doanh nghiệp gặp khó khăn trong việc lập hóa đơn điều chỉnh và thay thế không trực tiếp trên web Viettel, mà dùng phần mềm trung gian bên thứ ba thông qua việc đẩy dữ liệu API tích hợp sang Webservice Viettel, Trong bài viết này SInvoice hỗ trợ anh chị phát hành hóa đơn thay thế và điều chỉnh từ API tích hợp, (bỏ qua các bước cơ bản như: kết nối, phát hành hóa đơn, lập hóa đơn nháp, lập hóa đơn chuyển đổi, đăng nhập/xác thực...)

I. Đẩy API tích hợp cho hóa đơn thay thế, điều chỉnh cần đáp ứng các yêu cầu sau:

- Lập HD điều chỉnh hoặc thay thế thông qua API tích hợp phải cùng ký hiệu và mẫu số
- Không cần truyền originalInvoiceType và originalTemplateCode vì 2 trường này áp dụng cho điều chỉnh, thay thế hóa đơn khác ký hiệu và mẫu số (tức hóa đơn không chung hệ thống)
- Link để đẩy API tích hợp cho hóa đơn thay thế, điều chỉnh có thể dùng 1 trong 2 link dưới (tốt nhất nên dùng link lập nháp hóa đơn)

https://api-vinvoice.viettel.vn/services/einvoiceapplication/api/InvoiceAPI/InvoiceWS/createInvoice/{Mã số thuế}
=> Link trên là phát hành hóa đơn
https://api-vinvoice.viettel.vn/services/einvoiceapplication/api/InvoiceAPI/InvoiceWS/createOrUpdateInvoiceDraft/{Mã số thuế}
=> Link trên là lập nháp hóa đơn

- Chỉ được lập hóa đơn điều chỉnh và thay thế cho hóa đơn đã gửi cơ quan thuế, được thuế chấp nhận và cấp mã (ảnh dưới)

Cách thức truyền dữ liệu thông qua link dữ liệu có dạng chuỗi json

II. Các trường bắt buộc phải điền và trường cần lưu ý

1. Hóa đơn Thay thế

- "adjustmentType": "3", (Trạng thái hóa đơn)
- "originalInvoiceId": "K25MTA2058", (số hóa đơn gốc)
- "adjustedNote": "lý do sai sót", (không bắt buộc, nhưng tốt nhất nên điền)
- "originalInvoiceIssueDate": 1765773435000, (thời gian lập HD gốc, thời gian là milliseconds)

2. Hóa đơn điều chỉnh

A. Điều chỉnh tiền

- "adjustmentType": "5",
- "adjustmentInvoiceType": "1" , (Loại điều chỉnh đối với hóa đơn điều chỉnh)
- "originalInvoiceId": "K25MTA2058",
- "originalInvoiceIssueDate": 1765773435000, (thời gian lập HD gốc, thời gian là milliseconds)
- "adjustedNote": "lý do sai sót", (không bắt buộc, nhưng tốt nhất nên điền)
- "isIncreaseItem": false, (false là điều chỉnh giảm, true là điều chỉnh tăng)

- Hóa đơn điều chỉnh giảm tiền cứ truyền vào số dương hệ thống sẽ tự động chuyển sang số âm theo trường isIncreaseItem giá trị là false
- Hóa đơn điều chỉnh tiền không ghi nhận các giá trị trong buyerInfo (tức thông tin người mua hàng trong hóa đơn cũ)

B. Điều chỉnh thông tin (tức không liên quan đến tiền và doanh thu)

- "adjustmentType": "5",
- "adjustmentInvoiceType": "2" ,
- "originalInvoiceId": "K25MTA2058",
- "adjustedNote": "lý do sai sót", (không bắt buộc, nhưng tốt nhất nên điền)
- "originalInvoiceIssueDate": 1765773435000, (thời gian lập HD gốc, thời gian là milliseconds)
- "invoiceNote": "...", (nếu không điền thì hệ thống sẽ hiển thị mặc định đoạn ghi chú “Hóa đơn điều chỉnh thông tin cho hóa đơn điện tử mẫu ..., ký hiệu ..., số ..., ngày lập ...”, nếu có điền thông tin cho trường invoiceNote thì phải bổ sung đoạn ghi chú “Hóa đơn điều chỉnh thông tin cho hóa đơn điện tử mẫu ..., ký hiệu ..., số ..., ngày lập ...” vào để biết được hóa đơn này điều chỉnh cho hóa đơn nào)

- Hóa đơn điều chỉnh thông tin không ghi nhận các giá trị trong itemInfo (tức thông tin hàng hóa trong hóa đơn cũ)
- Trường invoiceNote không được truyền vượt quá 500 ký tự tính cả khoảng trắng vì theo cấu trúc XML hóa đơn điện tử của QĐ1306/QĐ-CT, thẻ Tên hàng hóa, dịch vụ được quy định tối đa 500 ký tự.

III. Chuỗi dữ liệu json mẫu

- Json mẫu hóa đơn thay thế: tham khảo
- Json mẫu hóa đơn điều chỉnh tiền: tham khảo
- Json mẫu hóa đơn điều chỉnh thông tin: tham khảo