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

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

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

2.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.

3.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.

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
• Đă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: https://sinvoice.viettel.vn/ho-tro/huong-dan-su-dung/mo-ta-tong-the-cac-buoc-dang-ky-va-su-dung-dich-vu-hoa-don-dien-tu

4.Một số luồng cơ bản

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

• Luồng đơn giản

• Phát hành/Thay thế/điều chỉnh hóa đơn  (Tương ứng API mục: 7.2 đối với loại chứng thư số HSM hoặc 7.15 và 7.16 đối với loại chứng thư số USB-TOKEN)
• Hủy hóa đơn  (Tương ứng API mục: 7.6)
• Tải file hóa đơn  (Tương ứng API mục: 7.3)
• Tra cứu hóa đơn  (Tương ứng API mục: 7.7)
• Lập hóa đơn nháp  (Tương ứng API mục: 7.9)

• Luồng hóa đơn có phát sinh các trường thông tin thêm (Các thông tin ngoài các khai báo chuẩn trong phần 5. VD: Điện nước, bệnh viện, hải hảng, xuất nhập kho ….)

• Lấy danh sách trường động được khai báo theo mẫu hóa đơn (Tương ứng API mục: 7.8 và mục 7.9)
• Phát hành/Thay thế/điều chỉnh hóa đơn  (Tương ứng API mục: 7.2 đối với loại chứng thư số HSM hoặc 7.15 và 7.16 đối với loại chứng thư số USB-TOKEN)
• Hủy hóa đơn  (Tương ứng API mục: 7.6)
• Tải file hóa đơn  (Tương ứng API mục: 7.3)
• Tra cứu hóa đơn  (Tương ứng API mục: 7.7)
• Lập hóa đơn nháp  (Tương ứng API mục: 7.9)

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.

5.Các tiêu chuẩn

1. Tiêu chuẩn thời gian

Toàn bộ trường dữ liệu chỉ định sử dụng tiêu chuẩn 4.1 này,kiểu datetime (đầy đủ giờ, phút, giây. Hiện tại hệ thống chỉ ghi nhận đến giá trị giây, không ghi nhận giá trị mili giây) đầu vào và đầu ra của 20 API theo tiêu chuẩn này chuyển hết về dạng longTime.

Ví dụ: 1587797116000.Cách tính toán DATE như hình ảnh:

Tham khảo trang web: https://currentmillis.com/

1. 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 “;”.
  1. Các ký tự đặc biệt 

Các ký tự đặc biệt cần lưu ý và cách xử lý theo đúng chuẩn json (cần ký tự đánh dấu để nhận dạng ký tự đặc biệt)

Trong json cần thêm ký tự đánh dấu \ trước các ký tự đặc biệt.

VD:

• Json: Muốn truyền dữ liệu là: Nguyễn Văn A "B"

Thì cần truyền trong json như sau: "buyerName": "Nguyễn Văn A \"B\""

1. Cơ chế kiểm trùng giao dịch

• Phần mềm tích hợp và SInvoice giao tiếp qua môi trường mạng, vì vậy rất có thể trong quá trình giao dịch phát sinh ra lỗi về đường truyền (lỗi mạng, hệ thống cao tải v.v.v). Để tránh một giao dịch được tạo thành 2 hóa đơn, với mỗi request hóa đơn gửi sang trong các thao tác lập hóa đơn, hệ thống tích hợp tự sinh ra transactionUuid là duy nhất cho hóa đơn đó và gửi kèm trong request lập hóa đơn. Chi tiết xem mục 5.2 về định dạng dữ liệu transactionUuid.
• Sau khi request được thực hiện, cần đợi request phản hồi xem kết quả đúng hay sai, hoặc request không phản hồi sau khoảng thời gian timeout (tối thiểu 90 giây). Sau đó mới được gửi request khác với trùng transactionUuid. Việc gửi 2 request đồng thời cùng một thời điểm với trùng transactionUuid sẽ không được hệ thống xử lý kiểm soát mà tạo thành 2 hóa đơn khác nhau.
• Trong trường hợp chưa nhận được thông tin phản hồi. Có thể chủ động tra cứu lại thông tin hóa đơn dựa theo transactionUuid để biết hóa đơn đã được sinh ra hay chưa. Chi tiết xem mục 6.21 Tra cứu hóa đơn bằng transactionUuid
  1. Tiêu chuẩn bảo mật kết nối
• API kết nối được mã hóa sử dụng giao thức https với xác thực bằng Token.
• Lấy thông tin Token
  • Gọi API

API: /auth/login

Method: POST

Content-Type: application/json

Body: {"username":"0100109106-712","password":"12345678aA@"}

• Lấy giá trị access_token sinh ra từ API trên để sử dụng trong các lần gọi API tương đương với việc xác thực:
  • Truyền vào Header của các API thông tin access_token
    • Key: Cookie
    • Value: access_token=abc…def

Ví dụ cách sử dụng token với Postman

• Authorization: https://api-vinvoice.viettel.vn/auth/login

• Headers:

• Body:

Kết quả:

Sau đó sử dụng access_token tại Headers

6.Đặc tả chi tiết đầu vào lập hóa đơn

1. Tổng quan

Đối với các API lập hóa đơn, điều chỉnh hóa đơn, thay thế hóa đơn, lập hóa đơn nháp, lập hóa đơn usb token, xem trước hóa đơn nháp các trường dữ liệu truyền vào sẽ có dạng chung

{

   "generalInvoiceInfo":{ //Thông tin chung của hóa đơn

   },

   "buyerInfo":{      //thông tin người mua

   },

   "sellerInfo":{      //thông tin người bán

   },

   "payments":[  //thông tin thanh toán     

   ],

   "itemInfo":[      //thông tin hàng hóa

   ],  

   "metadata":[  //thông tin trường động

   ],

   "meterReading":         //thông tin đặc biệt dành cho hóa đơn điện nước

   ],

   "summarizeInfo":{      //thông tin tổng hợp tiền của hóa đơn

   },

   "taxBreakdowns":[     //thông tin gom nhóm tiền hóa đơn theo thuế suất

   ]

}

Mô tả:

1. generalInvoiceInfo

Chứa thông tin cơ bản của hóa đơn,

Dữ liệu mẫu

Hóa đơn thường

  "generalInvoiceInfo": {

    "transactionUuid": "859f390a-1e59-4a05-9663-1e9ec7afdb8f",

    "invoiceType": "01GTKT",

    "templateCode": "01GTKT0/001",

    "invoiceSeries": "AB/20E",

    "invoiceIssuedDate": 1605027600000,

    "currencyCode": "VND",

    "adjustmentType": "1",

    "paymentStatus": true,

    "cusGetInvoiceRight": true

}

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

"generalInvoiceInfo": {

    "transactionUuid": "859f390a-1e59-4a05-9663-1e9ec7afdb8f",

    "invoiceType": "01GTKT",

    "templateCode": "01GTKT0/001",

    "invoiceSeries": "AB/20E",

    "invoiceIssuedDate": 1605027600000,

    "currencyCode": "VND",

    "adjustmentType": "5",

    "adjustmentInvoiceType": "1",

    "originalInvoiceId": "AB/20E0000036",

    "originalInvoiceIssueDate": 1605027600000,

    "additionalReferenceDesc": "Văn bản",

    "additionalReferenceDate": 1605027600000,

    "paymentStatus": true,

    "cusGetInvoiceRight": true

  }

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

"generalInvoiceInfo": {

    "transactionUuid": "859f390a-1e59-4a05-9663-1e9ec7afdb8f",

    "invoiceType": "01GTKT",

    "templateCode": "01GTKT0/001",

    "invoiceSeries": "AB/20E",

    "invoiceIssuedDate": 1605027600000,

    "currencyCode": "VND",

    "adjustmentType": "5",

    "adjustedNote": "",

    "adjustmentInvoiceType": "2",

    "originalInvoiceId": "AB/20E0000036",

    "originalInvoiceIssueDate": 1605027600000,

    "additionalReferenceDesc": "Văn bản",

    "additionalReferenceDate": 1605027600000,

    "originalInvoiceType": "1",

    "originalTemolateCode": "1/0224",

    "paymentStatus": true,

    "cusGetInvoiceRight": true

  }

Hóa đơn thay thế

"generalInvoiceInfo": {

    "transactionUuid": "859f390a-1e59-4a05-9663-1e9ec7afdb8f",

    "invoiceType": "01GTKT",

    "templateCode": "01GTKT0/001",

    "invoiceSeries": "AB/20E",

    "invoiceIssuedDate": 1605027600000,

    "currencyCode": "VND",

    "adjustmentType": "3",

    "adjustedNote": "",

    "originalInvoiceId": "AB/20E0000037",

    "originalInvoiceIssueDate": 1605027600000,

    "additionalReferenceDesc": "Văn bản",

    "additionalReferenceDate": 1605027600000,

    "originalInvoiceType": "1",

    "originalTemolateCode": "1/0224",

    "paymentStatus": true,

    "cusGetInvoiceRight": true

  }

1. sellerInfo

Thông tin người bán trên hóa đơn, có thể được truyền sang hoặc lấy tự động trên hệ thống hóa đơn điện tử. Trong trường hợp sellerTaxCode KHÔNG ĐƯỢC truyền sang thì dữ liệu sẽ được lấy từ hệ thống hóa đơn điện tử.

Chú ý 1: Các trường dữ liệu có required = true khi có truyền sellerTaxCode, nếu không truyền sellerTaxCode thì các trường khác được lấy từ hệ thống HDDT, không lấy từ thông tin truyền vào.

Chú ý 2: sellerTaxCode phải trùng khớp với taxCode của user đăng nhập

Dữ liệu mẫu

"sellerInfo": {

    "sellerLegalName": "Người bán hàng",

    "sellerTaxCode": "0100109106",

    "sellerAddressLine": "Thành Phố Hà Nội - Việt Nam",

    "sellerPhoneNumber": "0123456789",

   "sellerFaxNumber": "0123456789",

    "sellerEmail": "[email protected]",

    "sellerBankName": "Ngân hàng ",

    "sellerBankAccount": "012345678901",

   "sellerDistrictName": "",

    "sellerCityName": "Thành Phố Hà Nội",

    "sellerCountryCode": "84”,

    "sellerWebsite": "sinvoice.viettel.vn"

  }

1. buyerInfo

Thông tin người mua trên hóa đơn.

Dữ liệu mẫu

"buyerInfo": {

    "buyerName": "Tên khách hàng",

    "buyerLegalName": "Tên đơn vị",

    "buyerTaxCode": "0100109106",

    "buyerAddressLine": "An Khánh Hoài Đức Hà Nội",

    "buyerPostalCode": "2342324323",

    "buyerDistrictName": "Số 9, đường 11, VSIP Bắc Ninh, Thị xã Từ Sơn, Tỉnh",

    "buyerCityName": "Thành Phố Hà Nội",

    "buyerCountryCode": "84",

    "buyerPhoneNumber": "987999999",

    "buyerFaxNumber": "0458954",

    "buyerEmail": "[email protected]",

    "buyerBankName": "Ngân hàng Quân đội MB",

    "buyerBankAccount": "01578987871236547",

    "buyerIdType": "3",

    "buyerIdNo": "8888899999",

    "buyerCode": "832472343b_b",

    "buyerBirthDay": ""

  }

1. payments

Dữ liệu mẫu

"payments": [

    {

     "paymentMethod": "2",

      "paymentMethodName": "CK"

    }

  ]

Hoặc

"payments": [

    {

      "paymentMethodName": "Truyền trực tiếp giá trị mong muốn vào đây"

    }

  ]

1. itemInfo

Là một danh sách các hàng hóa/dịch vụ được hiển thị trên hóa đơn

Lưu ý: Đối với từng dòng hàng hóa, trong trường hợp các trường thông tin như quantity, unitPrice, itemTotalAmountWithoutTax, taxPercentage, taxAmount, discount, itemDiscount, itemTotalAmountWithTax có dữ liệu (dữ liệu khác null), hệ thống sẽ tính toán và kiểm tra các dữ liệu

Hệ thống so sánh quantity x unitPrice lệch không quá 5 đồng so với itemTotalAmountWithoutTax

Hệ thống so sánh itemTotalAmountWithoutTax khi bị lệch quá hệ thống báo lỗi.

Dòng ghi chú cho hóa đơn điều chỉnh, thay thế tổng hợp hệ thống sẽ tự động thêm.

VD Điều chỉnh tăng tiền hàng, tiền thuế của hàng hóa dịch vụ: Hàng hóa 01, hệ thống sẽ tự tổng hợp lại và sinh 1 item dạng selection =2 với nội dung tổng hợp như sau, hệ thống phần mềm không cần thêm, tránh trùng lặp:

Hóa đơn điều chỉnh tăng tiền hàng, tiền thuế cho hóa đơn điện tử mẫu số01GTKT0/002, kí hiệu AA/20E, số hóa đơn AA/20E0000162, ngày lập09:22:25 19/11/2020: số tiền: 165,495 VN

Hóa đơn thay thế cho hóa đơn điện tử mẫu số 01GTKT0/002, kí hiệuAA/20E, số hóa đơn AA/20E0000156, ngày lập 14:01:00 18/11/2020

Dữ liệu mẫu

"itemInfo": [

    { hàng_hóa_1},      { hàng_hóa_1}

  ]

Hàng hóa thông thường

"itemInfo": [

    {

      "lineNumber": 1,

      "itemCode": "PCDELLV3653_i56400_R4H10DVDRW",

      "itemName": "Máy tính để bàn DELL VOSTRO 3653 Desktop Core i5-6400 upto3.30Ghz/ 4GB/ 1TB HDD/DVDRW/NVIDIA Geforce 705 2Gb/ Wireless-Bluetooth/ K/ M/1Yr Pro",

      "unitName": "Cái",

      "itemNote": "",

      "unitPrice": 10300000,

      "quantity": 1,

      "itemTotalAmountWithoutTax": 10300000,

      "itemTotalAmountWithTax": 11330000,

      "itemTotalAmountAfterDiscount": 10300000,

      "taxPercentage": 10,

      "taxAmount": 1030000,

      "customTaxAmount": "0",

      "discount": 0,

      "itemDiscount": 0,

      "batchNo": "",

      "expDate": ""

    }

  ]

Hàng hóa kèm ghi chú:

"itemInfo": [

    {

      "lineNumber": 2,

      "selection": 2,

      "itemName": "Ghi chú cho hóa đơn",

    }

  ]

Hàng hóa có chiết khấu trên dòng sản phẩm

"itemInfo": [

    {

      "lineNumber": 1,

      "itemCode": "LCDLI2215S_LNV",

      "itemName": "Màn hình vi tính LENOVO LCD LI2215S 21.5\" Led (65CCAACC6VN)",

      "unitName": "Cái",

      "itemNote": "",

      "unitPrice": 1750000,

      "quantity": 2,

      "itemTotalAmountWithoutTax": 3500000,

      "itemTotalAmountWithTax": 3696000,

      "itemTotalAmountAfterDiscount": 3360000,

      "taxPercentage": 10,

      "taxAmount": 336000,

      "customTaxAmount": "0",

      "discount": 4,

      "itemDiscount": 140000,

      "batchNo": "",

      "expDate": ""

    }

  ]

Hàng hóa có dòng chiết khấu

"itemInfo": [

    {

      "lineNumber": 2,

      "itemCode": "chieu_khau_hang_hoa",

      "selection": 3,

      "itemName": "Chiếu khấu hàng hóa",

      "unitName": "",

      "itemNote": "",

      "itemTotalAmountWithoutTax": 50000,

      "itemTotalAmountWithTax": 50000,

      "itemTotalAmountAfterDiscount": 50000,

      "taxPercentage": 0,

      "taxAmount": 0,

      "customTaxAmount": "0",

      "discount": 0,

      "itemDiscount": 0,

      "isIncreaseItem": false,

      "batchNo": "",

      "expDate": ""

    }

  ]

Hàng hóa dạng bảng kê

"itemInfo": [

    {

      "lineNumber": 1,

      "itemCode": "bang_ke_hang_hoa",

      "selection": 4,

      "itemName": "Bảng kê hàng hóa",

      "unitName": "",

      "itemNote": "",

      "itemTotalAmountWithoutTax": 97770000,

      "itemTotalAmountWithTax": 107547000,

      "itemTotalAmountAfterDiscount": 97770000,

      "taxPercentage": 10,

      "taxAmount": 9777000,

      "customTaxAmount": "0",

      "discount": 0,

      "itemDiscount": 0,

      "batchNo": "",

      "expDate": ""

    }

  ]

Hàng hóa có kèm phí khác

"itemInfo": [

    {

      "lineNumber": 2,

      "itemCode": "phi_bao_tri",

      "selection": 5,

      "itemName": "Phí bảo trì",

      "unitName": "",

      "itemNote": "",

      "unitPrice": 20000,

      "quantity": 1,

      "itemTotalAmountWithoutTax": 20000,

      "itemTotalAmountWithTax": 20000,

      "itemTotalAmountAfterDiscount": 20000,

      "taxPercentage": 0,

      "taxAmount": 0,

      "customTaxAmount": "0",

      "discount": 0,

      "itemDiscount": 0,

      "batchNo": "",

      "expDate": ""

    }

  ]

Hàng hóa là điều chỉnh giảm

"itemInfo": [

    {

      "lineNumber": 1,

      "itemCode": "DELL_LJ2350D",

      "itemName": "Máy in Dell LJ 2350D 1Y Wty",

      "unitName": "Cái",

      "itemNote": "",

      "unitPrice": 6281000,

      "quantity": 3,

      "itemTotalAmountWithoutTax": 18843000,

      "itemTotalAmountWithTax": 20727300,

      "itemTotalAmountAfterDiscount": 18843000,

      "taxPercentage": 10,

      "taxAmount": 1884300,

      "customTaxAmount": "0",

      "adjustmentTaxAmount": 1,

      "discount": 0,

      "itemDiscount": 0,

      "isIncreaseItem": false,

      "batchNo": "",

      "expDate": ""

    }

    }

  ]

Hàng hóa là điều chỉnh tăng

"itemInfo": [

    {

      "lineNumber": 1,

      "itemCode": "DELL_LJ2350D",

      "itemName": " Máy in Dell LJ 2350D 1Y Wty",

      "unitName": "Cái",

      "itemNote": "",

      "unitPrice": 6281000,

      "quantity": 5,

      "itemTotalAmountWithoutTax": 31405000,

      "itemTotalAmountWithTax": 34545500,

      "itemTotalAmountAfterDiscount": 31405000,

      "taxPercentage": 10,

      "taxAmount": 3140500,

      "customTaxAmount": "0",

      "adjustmentTaxAmount": 1,

      "discount": 0,

      "itemDiscount": 0,

      "isIncreaseItem": true,

      "batchNo": "",

      "expDate": ""

    }

]

Ghi chú của hóa đơn điều chỉnh tiền, điều chỉnh thông tin, hóa đơn thay thế sẽ được chuyển vào invoiceNote trong generalInvoiceInfo

1. taxBreakdowns

Dùng để tổng hợp thuế suất theo mức cho hóa đơn.

Lưu ý: Hệ thống so sánh tổng của itemTotalAmountWithoutTax của tất cả các itemInfo trong cùng mức thuế suất với taxableAmount trong taxBreakDowns. Trong trường hợp bị lệch hệ thống sẽ báo lỗi.

Hệ thống so sánh tổng của taxAmount của tất cả các itemInfo trong cùng mức thuế suất với taxAmount trong taxBreakDowns. Trong trường hợp bị lệch hệ thống sẽ báo lỗi.

Cho phép chênh lệch tiền thuế 20000 so với giá trị thực tính

Dữ liệu mẫu

Thuế có %

"taxBreakdowns": [

    {

      "taxPercentage": 5,

      "taxableAmount": 400000,

      "taxAmount": 20000

    },

    {

      "taxPercentage": 10,

      "taxableAmount": 400000,

      "taxAmount": 40000

    }

  ]

Không thuế

"taxBreakdowns": [

    {

      "taxPercentage": -2,

      "taxableAmount": 400000,

      "taxAmount": 0

    }

  ]

Không kê khai tính/nộp thuế

"taxBreakdowns": [

    {

      "taxPercentage": -1,

      "taxableAmount": 400000,

      "taxAmount": 0

    }

  ]

Hóa đơn có tiền thuế âm

"taxBreakdowns": [

    {

      "taxPercentage": 10,

      "taxableAmount": 100000,//tổng tiền âm 100000

      "taxAmount": 10000,//thuế âm 10000

      "taxableAmountPos": false,

      "taxAmountPos": false

    }

  ]

1. summarizeInfo

Dùng để tổng hợp tiền hàng cho toàn bộ hóa đơn., Không sử dụng, hệ thống tự tính tổng tiền hóa đơn

Dữ liệu mẫu

Hóa đơn thường

"summarizeInfo": {

    "sumOfTotalLineAmountWithoutTax": 100000,

    "totalAmountWithoutTax": 100000,

    "totalTaxAmount": 10000,

    "totalAmountWithTax": 110000,

    "totalAmountAfterDiscount": 0,

    "totalAmountWithTaxInWords": "Một trăm mười nghìn đồng",

    "discountAmount": 0,

    "taxPercentage": 10

  }

Hóa đơn có tổng tiền âm

"summarizeInfo": {

    "sumOfTotalLineAmountWithoutTax": 100000,

    "totalAmountWithoutTax": 100000,

    "totalTaxAmount": 10000,

    "totalAmountWithTax": 110000,

    "totalAmountAfterDiscount": 0,

    "totalAmountWithTaxInWords": "Một trăm mười nghìn đồng",

    "discountAmount": 0,

    "taxPercentage": 10,

    "isTotalAmountPos": false,

    "isTotalTaxAmountPos": false,

    "isTotalAmtWithoutTaxPos": false           

  }

1. metadata

Dữ liệu các trường thông tin động (Thông tin trường bổ sung), ngoài các trường thông tin được mô tả ở trong mục 6 này. Nếu như trường thông tin chưa tồn tại trong mục 5, sẽ phải khai thêm. Trường động này sẽ gắn riêng cho từng mẫu hóa đơn của từng khách hàng. Danh sách các trường động của một mẫu cụ thể sẽ được lấy bằng hàm 6.8

Dữ liệu mẫu

"metadata": [

    {

      "keyTag": "dueDate",

      "valueType": "date",

      "dateValue": 1544115600000,

      "keyLabel": "Hạn thanh toán",

      "isRequired": false,

      "isSeller": false

    },

    {

      "keyTag": "contractNo",

      "stringValue": "555",

      "valueType": "text",

      "keyLabel": "Hợp dong số",

      "isRequired": false,

      "isSeller": false

    }

  ]

Một số metadata đặc biệt (được sử dụng làm trường chuẩn của XML thông tư 78)

Một số metadata đặc biệt (được sử dụng làm trường chuẩn của XML thông tư 78)

1. meterReading

Dữ liệu đặc thù cho riêng hóa đơn điện/nước.

Dữ liệu mẫu

"meterReading": [{

               "previousIndex": "110",

               "currentIndex": "150",

               "factor": "1",

               "amount": "40"

             },

             {

               "previousIndex": "44",

               "currentIndex": "50",

               "factor": "1",

               "amount": "6"

             }]

1. invoiceFile

Các file đính kèm khi lập hóa đơn dạng

Dữ liệu mẫu

"invoiceFile": {

      "fileType": 1,

      "fileExtension": "xlsx",

      "fileType": "RmlsZSBi4bqjbmcga8OqIMSRxrDhu6NjIGFkZCBsw6puIHThuqFpIHBo4bqnbiBs4bqtcCBow7NhIMSRxqFu"

   }

1. Các API kết nối
   1. Các khái niệm chung 

Giải thích 1 request bao gồm

• Action: Phương thức và hàm thực thi (Vị dụ: “/InvoiceAPI/InvoiceWS” phương thức POST).
• Content-Type: Kiểu thông tin request
• 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ề
• 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)
• Thông tin hệ thống tích hợp

Link web: https://vinvoice.viettel.vn

Link API: https://api-vinvoice.viettel.vn/services/einvoiceapplication/api/

• 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 token sinh ra sau khi thực hiện gọi API login trong mục 4.5. Header cần truyền thêm thông tin Cookie có access_token dạng access_token=abc_def (Xem Vị dụ tại 4.5.    Tiêu chuẩn bảo mật kết nối)

C#:

WebRequest request = WebRequest.Create(pzUrl);

request.Headers.Add("Cookie","access_token=abc_def");

Java:

String path = "url";

HttpPost post = new HttpPost(path);

post.setHeader("Cookie", "access_token=abc_def");

• Header định dạng dữ liệu: Dữ liệu gửi lên Web service có thể là JSON, FormParam hay QueryParam
  • Với JSON: Thêm header: Content-Type: application/json
  • Với FormParam: Thêm header: Content-Type: application/x-www-form-urlencoded
  • Với QueryParam: Không cần header, tham số truyền vào qua URL
• Dữ liệu trả về từ Web service là JSON
  • Để nhận về JSON: 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)

1.  Phát hành/thay thế/điều chỉnh hóa đơn (Dùng cho CTS HSM)

• Đầ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}
• Headers:

+ Cookie: giá trị access_token

+ Content-Type : application/json

• Data: Dữ liệu mẫu lập hóa đơn (Chi tiết các đối tượng xem từng mục nhỏ trong phần 5)

{

   "generalInvoiceInfo":{ //Thông tin chung của hóa đơn

   },

   "buyerInfo":{      //thông tin người bán

   },

   "sellerInfo":{      //thông tin người mua

   },

   "payments":[  //thông tin thanh toán     

   ],

   "itemInfo":[      //thông tin hàng hóa

   ],  

   "metadata":[  //thông tin trường động

   ],

   "meterReading":         //thông tin đặc biệt dành cho hóa đơn điện nước

   ],

   "summarizeInfo":{      //thông tin tổng hợp tiền của hóa đơn

   },

   "taxBreakdowns":[     //thông tin gom nhóm tiền hóa đơn theo thuế suất

   ]

}

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 5.

• Đầ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/20E0000001,

    "transactionID": 12523522245,

    "reservationCode": AXHBNK8I0H

  }

}

Mô tả

• Vị dụ:

1.  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 6.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): /InvoiceAPI/InvoiceUtilsWS/getInvoiceRepresentationFile
• Headers:

+ Cookie: giá trị access_token

+ Content-Type : application/json

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

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

• JSON:

{

"supplierTaxCode":"0100109106-712",

"invoiceNo":"AA/20E0000166",

"templateCode":"01GTKT0/002",

"transactionUuid":"testuuid9999999",

"fileType":"ZIP"

}

• Đầu ra:

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

1.  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): InvoiceAPI/InvoiceUtilsWS/getInvoiceFilePortal
• Headers:

 + Cookie: giá trị access_token

 + Content-Type : application/x-www-form-urlencoded

• Vị dụ trường hợp dùng POST và FormParam

Body: supplierTaxCode=0100109106&invoiceNo=AC%2F20E0000039&strIssueDate=1587797116843&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=1587797116843&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

Mô tả

1. 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 (Điều kiện phải cùng exchangeUser như lần chuyển đổi đầu tiên)

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
• Headers:

+ Cookie: giá trị access_token

+ Content-Type : application/x-www-form-urlencoded

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

Body: supplierTaxCode=0100109106&invoiceNo=AC%2F20E0000039&strIssueDate=1587797116843&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=1587797116843&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ề:

Mô tả

Hình ảnh Response trả về

1. Hủy hóa đơn

Cho phép xóa bỏ (chuyển hóa đơn sang trạng thái xóa bỏ) từ hệ thống tích hợp.

• Đầu vào:

• Action (POST): InvoiceAPI/InvoiceWS/cancelTransactionInvoice
• Headers:

+ Cookie: giá trị access_token

+ Content-Type : application/x-www-form-urlencoded

Form Data Vị dụ:

supplierTaxCode=0100109106-997&invoiceNo=AB%2F17E0000325&strIssueDate=1587797116843&additionalReferenceDesc=hello&additionalReferenceDate=20171222081259

• Đầ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ả

1. 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:

• Action (POST): InvoiceAPI/InvoiceUtilsWS/getInvoices/{supplierTaxCode}
• Headers:

+ Cookie: giá trị access_token

+ Content-Type : application/json

• Data: JSON
  • Các tham số của đối tượng GetInvoiceInput

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

{

  "startDate" : "2020-05-12" ,

  "endDate" : "2020-05-12",

  "invoiceType" : "02GTTT",

  "rowPerPage" : 20,

  "pageNum" : 1,

  "templateCode" : null

}

• Đầ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": 1587797116843,

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

            "contractId": null,

            "contractNo": null,

            "supplierTaxCode": "0100109106",

            "buyerTaxCode": "6200000230",

            "totalBeforeTax": 3800000,

            "taxAmount": 0,

            "taxRate": null,

            "paymentMethod": null,

            "paymentTime": null,

            "customerId": null,

            "buyerName": "Trần Trung Dũng",

            "no": null,

            "paymentStatusName": null

        }

}

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

1.  Lấy thông tin trường động

Với mỗi mẫu hóa đơn, có thể có những thông tin trường động khác nhau (các trường thông tin ngoài các trường tĩnh được mô tả ở mục 6). SInvoice cho phép các hệ thống tích hợp có thể lấy thông tin trường động của một mẫu hóa đơn cụ thể mà khách hàng sử dụng.

• Đầu vào:

• Action (GET): /InvoiceAPI/InvoiceWS/getCustomFields?taxCode=&templateCode=
• Headers:

+ Cookie: giá trị access_token

Vị dụ : /InvoiceAPI/InvoiceWS/getCustomFields?taxCode=0100109106&templateCode=01GTKT0%2f001

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

• Đầ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:

• Vị dụ:

Kết quả:

"errorCode": null,

    "description": null,

    "customFields": [

        {

            "id": null,

            "invoiceTemplatePrototypeId": 2503,

            "keyTag": "commandDes",

            "valueType": "text",

            "keyLabel": "về việc",

            "isRequired": false,

            "isSeller": false

        },

        {

            "id": null,

            "invoiceTemplatePrototypeId": 2503,

            "keyTag": "contractNo",

            "valueType": "text",

            "keyLabel": "Hợp đồng số",

            "isRequired": false,

            "isSeller": false

        },

        {

            "id": null,

            "invoiceTemplatePrototypeId": 2503,

            "keyTag": "vehicle",

            "valueType": "text",

            "keyLabel": "Phương tiện vận chuyển",

            "isRequired": false,

            "isSeller": false

        },

        {

            "id": null,

            "invoiceTemplatePrototypeId": 2503,

            "keyTag": "exportAt",

            "valueType": "text",

            "keyLabel": "Xuất tại kho",

            "isRequired": false,

            "isSeller": false

        },

        {

            "id": null,

            "invoiceTemplatePrototypeId": 2503,

            "keyTag": "exportAtNo",

            "valueType": "text",

            "keyLabel": "Mã kho",

            "isRequired": false,

            "isSeller": false

        },

        {

            "id": null,

            "invoiceTemplatePrototypeId": 2503,

            "keyTag": "importAt",

            "valueType": "text",

            "keyLabel": "Nhập tại kho",

            "isRequired": false,

            "isSeller": false

        },

        {

            "id": null,

            "invoiceTemplatePrototypeId": 2503,

            "keyTag": "importAtNo",

            "valueType": "text",

            "keyLabel": "Mã kho",

            "isRequired": false,

            "isSeller": false

        },

        {

            "id": null,

            "invoiceTemplatePrototypeId": 2503,

            "keyTag": "vehicleNo",

            "valueType": "text",

            "keyLabel": "Số xe",

            "isRequired": false,

            "isSeller": false

        },

        {

            "id": null,

            "invoiceTemplatePrototypeId": 2503,

            "keyTag": "economicContractNo",

            "valueType": "text",

            "keyLabel": "Căn cứ hợp đồng kinh tế số",

            "isRequired": false,

            "isSeller": false

        },

        {

            "id": null,

            "invoiceTemplatePrototypeId": 2503,

            "keyTag": "commandDate",

            "valueType": "date",

            "keyLabel": "Ngày điều động",

            "isRequired": false,

            "isSeller": false

        },

        {

            "id": null,

            "invoiceTemplatePrototypeId": 2503,

            "keyTag": "commandOf",

            "valueType": "text",

            "keyLabel": "của",

            "isRequired": false,

            "isSeller": false

        }

    ]

}

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 các giá trị được mapping dựa vào customFields nhận từ response như sau

{

   "generalInvoiceInfo": {

      "invoiceType": "03XKNB",

      "templateCode": "03XKNB0/003",

      "invoiceSeries": "AA/20E",

      "currencyCode": "VND",

      "adjustmentType": "1",

      "paymentStatus": true,

      "cusGetInvoiceRight": true

   },

   "sellerInfo": {

      "sellerLegalName": "Người bán hàng",

      "sellerTaxCode": "0100109106-712",

      "sellerAddressLine": "Thành Phố Hà Nội - Việt Nam",

      "sellerPhoneNumber": "0123456789",

      "sellerFaxNumber": "0123456789",

      "sellerEmail": "[email protected]",

      "sellerBankName": "Ngân hàng ",

      "sellerBankAccount": "012345678901",

      "sellerDistrictName": "",

      "sellerCityName": "Thành Phố Hà Nội",

      "sellerCountryCode": "84",

      "sellerWebsite": "sinvoice.viettel.vn"

   },

   "buyerInfo": {

      "buyerName": "Tên khách hàng",

      "buyerLegalName": "Tên đơn vị",

      "buyerTaxCode": "0100109106",

      "buyerAddressLine": "An Khánh Hoài Đức Hà Nội",

      "buyerPostalCode": "2342324323",

      "buyerDistrictName": "Số 9, đường 11, VSIP Bắc Ninh, Thị xã Từ Sơn, Tỉnh",

      "buyerCityName": "Thành Phố Hà Nội",

      "buyerCountryCode": "84",

      "buyerPhoneNumber": "987999999",

      "buyerFaxNumber": "0458954",

      "buyerEmail": "[email protected]",

      "buyerBankName": "Ngân hàng Quân đội MB",

      "buyerBankAccount": "01578987871236547",

      "buyerIdType": "3",

      "buyerIdNo": "8888899999",

      "buyerCode": "832472343b_b",

      "buyerBirthDay": ""

   },

   "payments": [

      {

         "paymentMethodName": "Truyền trực tiếp giá trị mong muốn vào đây"

      }

   ],

     "taxBreakdowns": [

    {

      "taxPercentage": -1,

      "taxableAmount": 27286150,

      "taxAmount": 0

    }

  ],

  "itemInfo": [

    {

      "lineNumber": 1,

      "itemCode": "HH0001",

      "itemName": "Hàng hóa 01",

      "unitCode": null,

      "unitName": "Chiếc",

      "unitPrice": 150450,

      "quantity": 100,

      "selection": 1,

      "itemTotalAmountWithoutTax": 15045000,

      "taxPercentage": -1,

      "taxAmount": 0,

      "discount": null,

      "discount2": null,

      "itemDiscount": 0,

      "itemNote": null,

      "batchNo": null,

      "expDate": null,

      "isIncreaseItem": null

    },

    {

      "lineNumber": 2,

      "itemCode": "HH00002",

      "itemName": "Hàng hóa 02",

      "unitCode": null,

      "unitName": "Cái",

      "unitPrice": 244823,

      "quantity": 50,

      "selection": 1,

      "itemTotalAmountWithoutTax": 12241150,

      "taxPercentage": -1,

      "taxAmount": 0,

      "discount": null,

      "discount2": null,

      "itemDiscount": 0,

      "itemNote": null,

      "batchNo": null,

      "expDate": null,

      "isIncreaseItem": null

    }

  ],

  "metadata": [

  {

    "keyTag": "commandDes",

    "keyLabel": "về việc",

    "dateValue": null,

    "stringValue": "điều chuyển nội bộ",

    "numberValue": null,

    "valueType": "text",

    "isRequired": false,

    "isSeller": false,

    "required": false

  },

  {

    "keyTag": "contractNo",

    "keyLabel": "Hợp đồng số",

    "dateValue": null,

    "stringValue": "Hợp đồng số",

    "numberValue": null,

    "valueType": "text",

    "isRequired": false,

    "isSeller": false,

    "required": false

  },

  {

    "keyTag": "vehicle",

    "keyLabel": "Phương tiện vận chuyển",

    "dateValue": null,

    "stringValue": "xe tải",

    "numberValue": null,

    "valueType": "text",

    "isRequired": false,

    "isSeller": false,

    "required": false

  },

  {

    "keyTag": "exportAt",

    "keyLabel": "Xuất tại kho",

    "dateValue": null,

    "stringValue": "Kho 1",

    "numberValue": null,

    "valueType": "text",

    "isRequired": false,

    "isSeller": false,

    "required": false

  },

  {

    "keyTag": "importAtNo",

    "keyLabel": "Mã kho",

    "dateValue": null,

    "stringValue": "KH2",

    "numberValue": null,

    "valueType": "text",

    "isRequired": false,

    "isSeller": false,

    "required": false

  },

  {

    "keyTag": "importAt",

    "keyLabel": "Nhập tại kho",

    "dateValue": null,

    "stringValue": "Kho 2",

    "numberValue": null,

    "valueType": "text",

    "isRequired": false,

    "isSeller": false,

    "required": false

  },

  {

    "keyTag": "importAtNo",

    "keyLabel": "Mã kho",

    "dateValue": null,

    "stringValue": "KH0",

    "numberValue": null,

    "valueType": "text",

    "isRequired": false,

    "isSeller": false,

    "required": false

  },

  {

    "keyTag": "vehicleNo",

    "keyLabel": "Số xe",

    "dateValue": null,

    "stringValue": "1524-jhh",

    "numberValue": null,

    "valueType": "text",

    "isRequired": false,

    "isSeller": false,

    "required": false

  },

  {

    "keyTag": "economicContractNo",

    "keyLabel": "Căn cứ hợp đồng kinh tế số",

    "dateValue": null,

    "stringValue": "123456",

    "numberValue": null,

    "valueType": "text",

    "isRequired": false,

    "isSeller": false,

    "required": false

  },

  {

    "keyTag": "commandDate",

    "keyLabel": "Ngày điều động",

    "dateValue": "1605752798000",

    "stringValue": null,

    "numberValue": null,

    "valueType": "date",

    "isRequired": false,

    "isSeller": false,

    "required": false

  },

  {

    "keyTag": "commandOf",

    "keyLabel": "của",

    "dateValue": null,

    "stringValue": "Công ty ABC",

    "numberValue": null,

    "valueType": "text",

    "isRequired": false,

    "isSeller": false,

    "required": false

  }

]

}

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

• Đầu vào:

Webservice dùng để lưu dữ liệu hóa đơn nháp lên hệ thống SInvoice. Các hóa đơn nháp này không có số hóa đơn hay kí số, chỉ có thể xem/phát hành trên website của SInvoice. Khi phát hành thì các số hóa đơn sẽ không được cập nhật lại phần mềm tích hợp.

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

+ Cookie: giá trị access_token

+ Content-Type : application/json

• Data: Định dạng JSON
• Thông số dữ liệu truyền vào tương tự phần Lập hóa đơn. Tham khảo json tại phần 6.2

• Đầ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 nháp lập thành công

{

  "errorCode": "",

  "description": "",

  "result": {   

  }

}
 

Mô tả

1. 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. Lưu ý chỉ sử dụng cho loại chứng thư số HSM

Lưu ý: Hệ thống đang cho phép tối đa 50 hóa đơn/1 lô do thời gian xử lý đơn lẻ từng hóa đơn lâu, nếu như để lô nhiều quá có thể bị timeout. Trong trường hợp dữ liệu từ hệ thống tích hợp nhiều hơn, có thể tự động chia nhỏ số lượng hóa đơn và gửi sang.

• Đầu vào:

• Action (POST): InvoiceAPI/InvoiceWS/createBatchInvoice/{supplierTaxCode}
• Headers:

+ Cookie: giá trị access_token

+ Content-Type : application/json

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

Kết quả khi lập hóa đơn theo lô thành công sẽ trả kết quả về theo transactionUuid để xác định được hóa đơn nào thành công, sinh ra số hóa đơn nào.

1. 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 trong quá trình sử dụng (hóa đơn đã kê khai thực tế vẫn có thể xóa bỏ, thay thế).

• Đầu vào:

• Action (POST):  InvoiceAPI/InvoiceUtilsWS/updateTaxDeclaration/
• Headers:
• + Cookie: giá trị access_token
• + Content-Type: application/json

gồm các tham số:

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

  {

               "supplierTaxCode":"0100109106",

               "strIssueDate":"14/03/2018"

               }

• Đầu ra:

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

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

Trả về thông tin chi tiết số lượng hóa đơn đã dùng, số lượng còn lại của một dải hóa đơn để từ đó đối tác tích hợp có thể chủ động cảnh báo khách hàng trong trường hợp không đủ hóa đơn.

• Đầu vào:

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

+ Cookie: giá trị access_token

+ Content-Type : application/json

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

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

• JSON:

{

            "supplierTaxCode":"0100109106-712",

            "templateCode":"01GTKT0/003",

            "serial":"AA/20E"

}

• Đầu ra:

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

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

Trả về chi tiết thông tin các hóa đơn để có thể đối soát xem sai đúng của hóa đơn trong một khoảng thời gian.

• Đầu vào:

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

+ Cookie: giá trị access_token

+ Content-Type : application/json

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

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

• JSON:

{

            "supplierTaxCode":"0100109106",

            "fromDate":"10/03/2018",

            "toDate":"16/03/2018"

}

• Đầu ra:

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

{

  "errorCode": null,

  "description": null,

  "totalRows": 1,

  "invoices": [

    {

      "invoiceId": 8569,

      "invoiceType": "Phiếu xuất kho gửi bán hàng đại lý",

      "adjustmentType": "1",

      "templateCode": "04HGDL/0001",

      "invoiceSeri": "P01",

      "invoiceNumber": "00000001",

      "invoiceNo": "P0100000001",

      "currency": "USD",

      "total": 444,

      "issueDate": 1583810428000,

      "issueDateStr": null,

      "state": 1,

      "requestDate": null,

      "description": null,

      "buyerIdNo": "",

      "stateCode": 1,

      "subscriberNumber": null,

      "paymentStatus": 1,

      "viewStatus": null,

      "downloadStatus": null,

      "exchangeStatus": 0,

      "numOfExchange": null,

      "createTime": 1583835386000,

      "contractId": null,

      "contractNo": "",

      "supplierTaxCode": "4400282282",

      "buyerTaxCode": "",

      "totalBeforeTax": 444,

      "taxAmount": 0,

      "taxRate": null,

      "paymentMethod": "2",

      "paymentTime": null,

      "customerId": null,

      "no": null,

      "paymentStatusName": "Đã thanh toán",

      "buyerName": "Người mua không lấy hóa đơn"

}

}

1. Gửi email cho các hoá đơn khách hàng

Trong trường hợp khách hàng đã cấu hình email server và biểu mẫu email trên hệ thống SInvoice, hệ thống sẽ tự động thực hiện gửi email cho người mua khi trong thông tin hóa đơn có email. API này cho phép phần mềm tích hợp chủ động việc gửi email cho khách hàng, trong trường hợp cấu hình của email là không hoạt động hoặc muốn gửi lại email cho khách hàng khi có yêu cầu.

• Đầuvào:

• Action (POST): /InvoiceAPI/InvoiceUtilsWS/sendHtmlMailProcess
• Headers:

+ Cookie: giá trị access_token

+ Content-Type : application/json

• Các tham số sendHtmlMailProcess

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

• JSON:

{

            "supplierTaxCode":"0100109106-712s",

            "lstTransactionUuid":"idtest9999999999,testuuid8888888,transactionUuid123"

}

• Đầura:

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

1. Phát hành/thay thế/điều chỉnh cho USB-TOKEN (Bước 1: Lấy chuỗi hash)

Sinh ra file xml và chuỗi hash của file XML của hóa đơn ký bởi USB Token.

• Đầuvào:

• Action (POST):  InvoiceAPI/InvoiceWS/createInvoiceUsbTokenGetHash/{supplierTaxCode}
• Headers:

+ Cookie: giá trị access_token

+ Content-Type : application/json

Đầu vào tương tư như lập hóa đơn, bổ sung thêm thông tin chứng thư gửi kèm.

Bổ sung trường Lý do sai sót hoá đơn. Điều chỉnh cho phép truyền

{

   "generalInvoiceInfo":{

      "invoiceType":"01GTKT",

      "templateCode":"01GTKT0/170",

            "invoiceSeries":"AA/17E",

      "transactionUuid": "123e4567-e89b-12d3-a456-426655440000",

      "invoiceIssuedDate":1587797116843,

      "currencyCode":"VND",

      "adjustmentType":"1",

      "adjustedNote":"",

      "originalInvoiceType": "1",

      "originalTemolateCode": "1/0224",

      "paymentStatus":true,

      "paymentType":"TM",

      "paymentTypeName":"TM",

      "cusGetInvoiceRight":true,

      "userName":"user 1",

      “certificateSerial”:”5404FFFEB7033FB316D672201B7BA4FE”

   },

   "buyerInfo":{

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

      "buyerLegalName":"",

      "buyerTaxCode":"",

      "buyerAddressLine":"HN VN",

      "buyerPhoneNumber":"11111",

      "buyerEmail":"",

      "buyerIdNo":"123456789",

      "buyerIdType":"1"

   },

   "sellerInfo":{

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

      "sellerTaxCode":"0100109106-501",

      "sellerAddressLine":"test",

      "sellerPhoneNumber":"0123456789",

      "sellerEmail":"[email protected]",

      "sellerBankName":"vtbank",

      "sellerBankAccount":"23423424"

   },

   "extAttribute":[

   ],

   "payments":[

      {

         "paymentMethodName":"TM"

      }

   ],

   "deliveryInfo":{

   },

   "itemInfo":[

      {

         "lineNumber":1,

         "itemCode":"ENGLISH_COURSE",

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

         "unitName":"khóa học",

         "unitPrice":"-3500000.0",

         "quantity":"-10.0",

         "itemTotalAmountWithoutTax":35000000,

         "taxPercentage":10.0,

         "taxAmount":0.0,

         "discount":0.0,

         "itemDiscount":150000.0

      }

   ],

   "discountItemInfo":[

   ],

"metadata":[

   ],

  "meterReading": [{

            "previousIndex": "5454",

            "currentIndex": "244",

            "factor": "22",

            "amount": "2"

          },

          {

            "previousIndex": "44",

            "currentIndex": "44",

            "factor": "33",

            "amount": "3"

          }],

   "summarizeInfo":{

      "sumOfTotalLineAmountWithoutTax":35000000,

      "totalAmountWithoutTax":35000000,

      "totalTaxAmount":3500000.0,

      "totalAmountWithTax":38500000,

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

      "discountAmount":0.0,

      "settlementDiscountAmount":0.0,

      "taxPercentage":10.0

   },

   "taxBreakdowns":[

      {

         "taxPercentage":10.0,

         "taxableAmount":35000000,

         "taxAmount":3500000.0

      }

   ]

}

• Dữ liệu chuỗi Hash trả về

{

  "errorCode": "",

  "description": "",

  "result": {

    "hashString": 0HFm34vX525V3Syg5EwdTnfO21s=,  }

}
 

1. Phát hành/thay thế/điều chỉnh cho USB-TOKEN (Bước 2: Ký USB token và sinh hóa đơn)

Thực hiện sử dụng USB-TOKEN để ký chuỗi hashString nhận được từ API trong bước 6.15. Lấy chuỗi ký để sinh hóa đơn.

• Đầuvào:

• Action (POST):  InvoiceAPI/InvoiceWS/createInvoiceUsbTokenInsertSignature
• Headers:

+ Cookie: giá trị access_token

+ Content-Type : application/json

Vị dụ Json

{

  "supplierTaxCode": "0100109106-712",

  "templateCode": "01GTKT0/002",

  "hashString": "0HFm34vX525V3Syg5EwdTnfO21s=",

  "signature": "U0WpJk2Q/rDsnZDz8hiWKvs6QEf5DHTG8JyXjjNMtggZ/MIDP0hn9Mutc2uPZEOxqk2YnMjuRSxU8ST/T+C5i46Vb/0+7uIfzKpPm2yrsOSivCdzr6FrY6nJPkfkOWEdEs/hqDzcf4Vn8ZCVkNfovYR4prPGc7kNpO21sNb9BAI="

}

Kết quả trả về

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

{

  "errorCode": "",

  "description": "",

  "result": {

    "supplierTaxCode": 0100109106-712,

    "invoiceNo": AA/20E0000018,

    "transactionID": 12523522245,

    "reservationCode": AXHBNK8I0H

  }

}
 

Tham khảo thêm tại https://sinvoice.viettel.vn/download/soft/signhash.rar

1. Chuyển font

Hỗ trợ convert từ các font chữ sang unicode (KH sử dụng API) này kết hợp với API tạo hóa đơn để convert dữ liệu

• Đầuvào:

• Action (POST):  InvoiceAPI/InvoiceUtilsWS/convertFont
• Headers:

+ Cookie: giá trị access_token

+ Content-Type : application/json

Vị dụ json:

{

  "font": "TCVN3",

  "data": "D÷ liÖu kh«ng ®óng chuÈn Unicode cÇn convert"

}

Kết quả trả về

{

    "errorCode": null,

    "description": null,

    "result": "Dữ liệu không đúng chuẩn Unicode cần convert"

}

1. Cập nhật trạng thái thanh toán

Cho phép hệ thống tích hợp cập nhật trạng thái thanh toán của hóa đơn sang là đã thanh toán.

• Đầu vào:

• Action (POST):  InvoiceAPI/InvoiceWS/updatePaymentStatus
• Headers:

+ Cookie: giá trị access_token

+ Content-Type : application/x-www-form-urlencoded

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

• Vị dụ định dạng FormParam

supplierTaxCode=0100109106-712&templateCode=01GTKT0%2F002&invoiceNo=AA%2F20E0000035&buyerEmailAddress=abc%40gmail.com &strIssueDate=20201103000000&paymentType=TM%2FCK&paymentTypeName=TM%2FCK&cusGetInvoiceRight=true

• Dữ liệu trả về

{"errorCode":null,"description":null,"result":true,"paymentTime":null,"paymentMethod":null}

Mô tả

1. Hủy trạng thái thanh toán

Cho phép chuyển trạng thái thanh toán của hóa đơn sang chưa thanh toán.

• Đầu vào:

• Action (POST):  InvoiceAPI/InvoiceWS/cancelPaymentStatus
• Headers:

+ Cookie: giá trị access_token

+ Content-Type : application/x-www-form-urlencoded

• Vị dụ định dạng FormParam

supplierTaxCode=0100109106-712&invoiceNo=AA%2F20E0000002&strIssueDate=1600154781000

• Dữ liệu trả về

{

    "errorCode": null,

    "description": "Success"

}

1. Xem trước hóa đơn nháp

• Đầu vào:

Webservice dùng để lấy file PDF của dữ liệu để xem. Hệ thống tích hợp đẩy dữ liệu lập hóa đơn sang và SInvoice trả về file PDF của dữ liệu đó, các dữ liệu sẽ không được lưu vào trong SInvoice.

• Action (POST):  InvoiceAPI/InvoiceUtilsWS/createInvoiceDraftPreview/{supplierTaxCode}
• Headers:

+ Cookie: giá trị access_token

+ Content-Type : application/json

• Data: Định dạng JSON

Thông số dữ liệu truyền vào tương tự phần Lập hóa đơn. Tham khảo json tại phần 6.2

• Đầu ra:

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

1. Tra cứu hóa đơn bằng transactionUuid

Cho phép hệ thống tích hợp tra cứu hóa đơn đã được phát hành thành công dựa vào transactionUuid (Dữ liệu xác định tính duy nhất của 1 hóa đơn do bên phần mềm tích hợp sinh dữ liệu và kiểm soát)

Thường sử dụng API này khi cần đối soát dữ liệu giữa 2 hệ thống HDDT và phần mềm tích hợp.

• Đầu vào:

• Action (POST):  InvoiceAPI/InvoiceWS/searchInvoiceByTransactionUuid
• Headers:

+ Cookie: giá trị access_token

+ Content-Type : application/x-www-form-urlencoded

gồm các tham số:

Vị dụ với định dạng formParam:

  supplierTaxCode=0100109106&transactionUuid= 0100109106_test3_268_1

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

Thông tin chi tiết Response

{

   "transactionUuid": "0100109106_test3_268_1",

   "errorCode": null,

   "description": null,

   "result": [

      {

         "supplierTaxCode": "0100109106",

         "invoiceNo": "AB/19E0000522",

         "reservationCode": "OKMYMDX5F4",

         "issueDate": 1587797116843

         "status": "Hóa đơn gốc"

      }

   ]

}

Đối với các hóa đơn theo Thông tư 78 đã được cơ quan thuế cấp mã sẽ có các thông tin bổ sung về mã cơ quan thuế như sau

{

    "errorCode": null,

    "description": null,

    "transactionUuid": "4543Gfd565h",

    "result": [

        {

            "supplierTaxCode": "0100109106-710",

            "invoiceNo": "K21DTT4",

            "reservationCode": "UFODH7MN7LT0GW5",

            "issueDate": 1638852198000,

            "status": "Hóa đơn điều chỉnh tiền",

            "exchangeStatus": " Mã CQT cấp: 00BDD6525B75646655B654665B65466565",

            "exchangeDes": null,

            "codeOfTax": "00BDD6525B75646655B654665B65466565"

        }

    ]

}

1. Danh sách lỗi trả về của hệ thống

Đố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ề. Bao gồm mã lỗi và mô tả lỗi.

Note: Khi phát sinh lỗi việc đầu tiên kiểm tra mã lỗi trong danh sách lỗi để nắm được tại sao lỗi và cách khắc phục.

1. Mapping giữa các trường thông tin và mẫu hóa đơn

Các trường thông tin sẽ được mapping lên mẫu hóa đơn phụ thuộc vào thiết kế chi tiết của mẫu hóa đơn đó. Về cơ bản sẽ các mẫu hóa đơn sẽ được mapping các trường như sau:

Lưu ý: trong trường hợp trường thông tin không hiển thị đúng, nguyên nhân có thể do dữ liệu gửi sang chưa đúng hoặc mẫu hóa đơn thiết kế không hiển thị đúng thông tin. Kiểm tra dữ liệu trong file hóa đơn gốc (xml) tải về xem đúng chưa.

1. Kiểm tra API bằng POSTMAN

Trước khi lập trình, các phần mềm tích hợp nên kiểm tra trước các API bằng POSTMAN để hiểu các dữ liệu cần phải truyền vào/trả về của hệ thống. Sau khi chạy thử xong, việc code sẽ nhanh hơn.

Chi tiết xem ở:

https://sinvoice.viettel.vn/ho-tro/huong-dan-su-dung/35-huong-dan-su-dung-postman-goi-api-webservice-hoa-don-dien-tu

11.Điều chỉnh hóa đơn không tồn tại

Input: Các thông tin đầu vào giữ nguyên hiện trạng, chỉ bổ sung thêm trong generalInvoiceInfo hai thẻ như sau:

Output: Giữ nguyên hiện trạng

Ví dụ response trường hợp truyền sai giá trị originalInvoiceType

{

    "code": 400,

    "message": "BAD_REQUEST_ORIGINAL_INVOICE_TYPE_INVALID",

    "data": "BAD_REQUEST_ORIGINAL_INVOICE_TYPE_INVALID"

}

11.1.1.1.1Xử lý luồng sự kiện tương tác

-Trường hợp thẻ originalInvoiceType không truyền hoặc truyền giá trị rỗng/0 thì không bắt buộc truyền thẻ originalTemplateCode, hệ thống xác thực thông tin khi lập hóa đơn như hiện trạng.

-Trường hợp thẻ originalInvoiceType truyền giá trị 1, 2, 3 hoặc 4 thì

 +Bắt buộc phải truyền thẻ originalTemplateCode, quy tắc xác thực thẻ này tương tự như thẻ templateCode hiện tại.

  +Khi lập hóa đơn, hệ thống không kiểm tra tính tồn tại của hóa đơn gốc trên hệ thống, các quy tắc xác thực khác giữ nguyên hiện trạng.

Bình luận

---

Viết bình luận

Bình luận

Tên

Địa chỉ Email (Sẽ không được công bố)

Trả lời các câu hỏi dưới đây:

Gửi bình luận