Chúng tôi có thể giúp bạn tìm thông tin gì?

Trang chủ | 5. Tích hợp API | 5. Tài liệu kết nối API – dành cho Developers

5. Tài liệu kết nối API – dành cho Developers

I. MÔ TẢ TỔNG QUAN

1. Mục đích

UBot – hệ sinh thái tự động hóa nghiệp vụ toàn diện cho doanh nghiệp. UBot Invoice – phần mềm xử lý hóa đơn tự động. 

UBot hỗ trợ khách hàng tự động tải hóa đơn từ email của nhà cung cấp và kiểm tra tính xác thực từ Tổng cục thuế, tự động trích xuất dữ liệu hóa đơn ra file excel theo chuẩn định dạng của các phần mềm kế toán và tự động lưu trữ hóa đơn cùng với các chứng từ đi kèm.

Tài liệu này được xây dựng nhằm giúp UBot kết nối với các đối tác để gửi/nhận thông tin của hóa đơn và trạng thái xử lý email hóa đơn bằng API.

2. Đối tượng sử dụng

Đối tượng sử dụng tài liệu là các đối tác, khách hàng có nhu cầu, gửi hóa đơn vào UBot xử lý và lấy thông tin hóa đơn từ UBot qua API.

  • Thuật ngữ và viết tắt
# Viết tắt Giải thích
1 TCT Tổng cục thuế
2 KH Khách hàng
3 MST Mã số thuế

 

3. Danh sách các API 

  • API đăng nhập
  • API nhận thông tin hóa đơn từ UBot
  • API gửi thông tin hóa đơn 
  • API gửi hóa đơn OCR
  • API nhận trạng thái của TransactionId

II. ĐỊA CHỈ API KẾT NỐI

1. Môi trường

Môi trường Test: https://portal-dev.ubot.vn/api

Môi trường production: https://portal.ubot.vn/api

2. Thông tin xác thực

Tên đăng nhập: <UBot đã gửi riêng cho khách hàng>

Mật khẩu: <UBot đã gửi riêng cho khách hàng>

3. Luồng xử lý

4. API

4.1. API đăng nhập

# Item Thông tin
1 URL  Product: https://portal.ubot.vn/api/authenticate
2 HTTP method POST
3 Header Content-Type: application/json

 

# Tên trường thông tin Tính chất bắt buộc Kiểu dữ liệu Max length Mô tả
Request
1 username x string 256 Email đăng nhập
2 password x string 256 Mật khẩu đăng nhập
3 rememberMe boolean 256 Có nhớ phiên đăng nhập sau khi đóng trang lại không
 + true:  token đăng nhập sẽ hết hạn trong 30 ngày
 + false (Default): token đăng nhập sẽ hết hạn trong 30′
Response
1 token string Mỗi lần gọi API hệ thống sẽ gen ra một token mới. Trong trường hợp Token hết hạn cần gọi lại hàm tạo token để lấy token mới.

 

Request mẫu

curl –location ‘https://portal.ubot.vn/api/authenticate’ \

–header ‘Content-Type: application/json’ \

–data-raw ‘{

    “username”: “abc@ubot.vn”,

    “password”: “abc@2022”,

    “rememberMe”: “true”

}’ 
Respone mẫu 

{

    “id_token”: “eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiJob25kYXZuQHVib3Qudm4iLCJhdXRoIjoiQUNDRVNTX0lOVk9JQ0VfU09MVVRJT04sQUNDRVNTX1

NPTFVUSU9OLEFDQ09VTlRfTUFOQUdFTUVOVCxBQ1RJT05fSU5QVVRfSU5WT0lDRSxBRERfQ09NUEFOWV9JTlZPSUNFLEFERF9QRVJNSVNT

SU9OX01BTkFHRVJfR1JPVVAsQUREX1BFUk1JU1NJT05fU09MVVRJT05fR1JPVVsQVNTSUdOX0xBQkVMX0lOUFVUX0lOVk9JQ0UsQVNTSUdOX0

1VTFRJX0xBQkVMX0lOUFVUX0lOVk9JQ0UsQ09ORklERU5DRV9ISVNUT1JZLENSRUFURV9MQUJFTF9JTlBVVF9JTlZPSUNFLENSRUFURV9MQU

JFTF9JTlZPSUNFLENSRUFURV9VU0VSX0FDQ09VTlQsREVMRVRFX0NPTVBBTllfSU5WT0lDRSxERUxFVEVfRE9DVU1FTlRfSU5QVVRfSU5WT0lD

RSxERUxFVEVfTEFCRUxfSU5WT0lDRSxERUxFVEVfUEVSTUlTU0lPTl9NQU5BR0VSX0dST1VQLERFTEVURV9QRVJNSVNTSU9OX1NPTFVUSU9O

X0dST1VQLERPV05MT0FEX0RPQ1VNRU5UX0lOUFVUX0lOVk9JQ0UsRE9XTkxPQURfUkVMQVRFRF9ET0NVTUVOVF9JTlBVVF9JTlZPSUNFLERP

V05MT0FEX1JFU1VMVF9QUk9DRVNTSU5HX0lOVk9JQ0UsRURJVF9DT01QQU5ZX0lOVk9JQ0UsRURJVF9DT05GSURFTkNFLEVESVRfUEVSTUlT

U0lPTl9NQU5BR0VSX0dST1VQLEVESVRfUEVSTUlTU0lPTl9TT0xVVElPTl9HUk9VUCxFRElUX1VTRVJfQUNDT1VOVCxFWFBPUlRfSU5QVVRfSU5W

T0lDRSxJTlBVVF9JTlZPSUNFLElOUFVUX0lOVk9JQ0VfU1RBVElTVElDLElOVk9JQ0VfU1RBVElTVElDLExJU1RfQ09ORklERU5DRV9ISVNUT1JZLExJ

U1RfSU5QVVRfSU5WT0lDRSxMSVNUX1VTRVJfQUNDT1VOVCxNQUlMX0lOUFVUX0lOVk9JQ0VfU1RBVElTVElDLE1BSUxfSU5WT0lDRSxNQU5BR

0VSX0dST1VQLE1BTlVBTF9WQUxJRF9NQVJLX0lOUFVUX0lOVk9JQ0UsTUFSS19SRUFEX01BSUxfSU5WT0lDRSxNQVJLX1ZBTElEX0lOUFVUX0l

OVk9JQ0UsT0NSX0lOVEVHUkFUSU9OX0lOVk9JQ0VfUFJPQ0VTU0lORyxQRVJNSVNTSU9OX0dST1VQLFFVT1RBX0lOVk9JQ0VfU1RBVElTVElDLF

JFQ0hFQ0tfSU5QVVRfSU5WT0lDRSxST0xFX0NVU1RPTUVSLFJPTEVfSU5WT0lDRSxST0xFX09DUl9JTlRFR1JBVElPTl9DT05GSUdfQ09ORklERU5

DRSxST0xFX09DUl9JTlRFR1JBVElPTl9JTlZPSUNFX1BST0NFU1NJTkcsU0VUVElOR19CQUNLVVBfSU5WT0lDRSxTRVRUSU5HX0NPTVBBTllfSU5W

T0lDRSxTRVRUSU5HX0lOVk9JQ0UsU0VUVElOR19MQUJFTF9JTlZPSUNFLFNFVFRJTkdfVEVNUExBVEVfRVhDRUwsU09MVVRJT05fR1JPVVAsVU

JPVF9MT09LVVBfSU5QVVRfSU5WT0lDRV9TVEFUSVNUSUMsVUJPVF9NQU5BR0VNRU5ULFVQTE9BRF9ET0NVTUVOVF9JTlBVVF9JTlZPSUNFL

FVTRVJfTUFOQUdFTUVOVCxWSUVXX0RFVEFJTF9JTlBVVF9JTlZPSUNFLFZJRVdfREVUQUlMX1BFUk1JU1NJT05fU09MVVRJT05fR1JPVVAsVklF

V19ERVRBSUxfVVNFUl9BQ0NPVU5ULFZJRVdfRE9DVU1FTlRfSU5QVVRfSU5WT0lDRSxWSUVXX0hJU1RPUllfU0VBUkNIX0lOUFVUX0lOVk9JQ0Us

VklFV19QRVJNSVNTSU9OX01BTkFHRVJfR1JPVVAiLCJleHAiOjE2ODM5NjE0MzZ9.D86xhrnKvzSS9QkJSgOT6ZwybxAX68iujhtQNXxHCWFSZQ8RN

xTgiZzaEqCz3YwgQPeSSkt2Umvg5etbd6XZ-Q”

}

 

4.2. API nhận thông tin hóa đơn từ UBot

API trả về:

  • Tất cả các thông tin mà UBot đọc được từ hóa đơn
  • Thông tin danh mục nhà cung cấp, hàng hóa (nếu có)
  • Kết quả tra cứu hóa đơn
# Item Thông tin
1 URL  Product: https://portal.ubot.vn/api/third-party/invoices
2 HTTP method POST
3 Header Content-Type: application/json
Authorization: Bear + token lấy từ API đăng nhập

 

# Tên trường thông tin Tính chất bắt buộc Kiểu dữ liệu Max length Mô tả
Request Parameter
1 page number 256 Thứ tự trang đã được phân trang. Mặc định: 0
2 size number 256 Số lượng bản ghi mỗi trang.  Default: 10. Max: 100 hóa đơn/response
3 sort string 256 Sort theo các tiêu chí:
+ receivedDate (Default): Ngày nhận hóa đơn về UBot
+ invoiceReleaseDate: Ngày phát hành
VÀ sắp xếp theo thứ tự
Request Body
1 invoiceId string 36 Request theo invoice id cụ thể
2 invoiceTypes x array 256 Request theo loại hóa đơn

+ []: Tất cả (Default)

+ INPUT_PAPER_INVOICE: Hóa đơn đầu vào (giấy)
+ INPUT_ELECTRONIC_INVOICE: Hóa đơn đầu vào (điện tử)

+ OUTPUT_ELECTRONIC_INVOICE: Hoá đơn đầu ra (điện tử)
+ INPUT_PAPER_INVOICE_OCR: Hóa đơn đầu vào (giấy) đọc OCR

+ INPUT_ELECTRONIC_INVOICE_OCR: Hóa đơn đầu vào (điện tử) đọc OCR
+ OUTPUT_ELECTRONIC_INVOICE_OCR: Hoá đơn đầu ra (điện tử) đọc OCRLoại hóa đơn
3 transactionIds array 256 Request theo transaction code đã đính kèm trong API gửi
2 buyerTaxNo string 256 Request theo mã số thuế bên mua
3 buyerName string 256 Request theo  tên công ty bên mua
4 invoiceNo string 256 Request theo số hóa đơn
5 sellerTaxNo string 256 Request theo mẫ số thuế bên bán
6 sellerName string 256 Request theo tên công ty bên bán
7 releasedDateFrom date 256 Request ngày phát hành hóa đơn bắt đầu từ ngày
Định dạng: dd/mm/yyyy
8 releasedDateTo date 256 Request ngày phát hành hóa đơn đến ngày
Định dạng: dd/mm/yyyy
9 receivedDateFrom date 256 Request ngày nhận hóa đơn bắt đầu từ ngày
Định dạng: dd/mm/yyyy
10 receivedDateTo date 256 Request ngày nhận hóa đơn đến ngày
Định dạng: dd/mm/yyyy
11 tagNames array 256 Request theo tên nhãn đã gắn trên hóa đơn
12 isCombinedTag boolean 256 Request theo tìm các nhãn theo
+ true: Điều kiện AND
+ false: Điều kiện OR (Default)
13 invoiceStatus string 256 Request theo trạng thái hóa đơn
+ VALID: Trả tất cả các hóa đơn có trạng thái kiểm tra=hợp lệ
+ INVALID: Trả tất cả các hóa đơn có trạng thái kiểm tra = không hợp lệ
+ IS_WAITING: Chờ xác thực
+ IS_RECHECKING: Chờ xác thực lại
14 releaseStatus string 256 Request theo Trạng thái phát hành
+ VALID: Tồn tại hóa đơn
+ VALID_INVOICE_MODIFIED: Hóa đơn điều chỉnh
+ VALID_INVOICE_ALTERNATIVE: Hóa đơn thay thế
+ NOT_ENOUGH_CONDITION_PROVIDE_CODE: Hóa đơn không đủ điều kiện cấp mã
+ INVALID: Không tồn tại hóa đơn
+ INVALID_INVOICE_MODIFIED: Hóa đơn đã bị điều chỉnh
+ INVALID_INVOICE_ALTERNATIVE: Hóa đơn đã bị thay thế
+ IS_DELETE_OR_CANCEL_INVOICE: Hóa đơn đã bị xóa/hủy bỏ
+ EXPIRE_DATE: Hóa đơn hết giá trị sử dụng
+ EXPIRE_USED: Hóa đơn không còn giá trị sử dụng
15 getMatchingData boolean true/false Lựa chọn có lấy thêm dữ liệu danh mục (matching data) không
+ True: Lấy cả dữ liệu danh mục
+ False: Không lấy thêm dữ liệu danh mục
Nếu getMatchingData=True, dữ liệu trả về ở các trường vendorCode, paymentCode, itemCode, inventoryAccount, inventoryCode, expenseAccount, taxAccount, revenueAccount
16 getAttachments boolean true/false Lựa chon có trả về các file đính kèm không
+ True: Trả link download các file đính kèm
+ False: Không trả tệp đính kèm
17 getTaxes boolean true/false Lựa chọn có trả về chi tiết từng loại thuế suất hay không
Response
1 statusResponse Kết quả xử lý request
1.1 statusCode string Tham khảo bảng Status code, mục V. Mã lỗi
1.2 errorCode string Mã lỗi. Tham khảo bảng Error code, mục V. Mã lỗi #1 và #6
1.3 message string Nội dung lỗi. Tham khảo bảng Error code, mục V. Mã lỗi
2 metadata Thông tin bổ sung
2.1 page number Số thứ tự trang kết quả trả về
2.2 size number Số hóa đơn trong 1 trang kết quả trả về
2.3 total number Tổng số hóa đơn trả về
2.4 orderBy string Thứ tự của hóa đơn trả về
+ receivedDate (Default): Ngày nhận hóa đơn về UBot
+ invoiceReleaseDate: Ngày phát hành
2.5 sort Sort theo các tiêu chí:
+ ASC: tăng dần
+ DESC (default): giảm dần
3 invoices Danh sách hóa đơn
3.1 companyId string ID của công ty
3.2 invoiceId string ID hóa đơn
3.3 emailId string ID của email chứa hóa đơn
3.4 modelNo string Mẫu số hóa đơn
3.5 serial string Ký hiệu hóa đơn
3.6 invoiceNo string Số hóa đơn
3.7 sellerName string Tên công ty bán
3.8 sellerTaxNo string MST công ty bán
3.9 sellerAddress string Địa chỉ công ty bán
3.10 sellerPhone string Số điện thoại công ty bán
3.11 signedBy string Tên người ký
3.12 isSignValid boolean Chữ ký số có hợp lệ không
+ true: Hợp lệ
+ false: Không hợp lệ
3.13 signIssuerName string Tên nhà cung cấp chữ ký số cho bên bán
3.14 signSerialNumber string Số seri của chữ ký số
3.15 signValidFrom date Ngày bắt đầu có hiệu lực của chữ ký số
3.16 signValidTo date Ngày hết hiệu lực của chữ ký số
3.17 markedValidBy string Tên tài khoản đánh dấu hóa đơn hợp lệ bằng tay
3.18 markedValidDate string Ngày đánh dấu hóa đơn hợp lệ bằng tay
3.19 buyerName string Tên công ty mua
3.20 buyerTaxNo string MST công ty mua
3.21 buyerAddress string Địa chỉ công ty mua
3.22 subTotal number Tổng tiền trước thuế
3.23 grandTotal number Tổng tiền sau thuế
3.24 discount number Phần trăm chiết khấu
3.25 discountAmount number Tiền chiết khấu
3.26 paymentDiscount number Phần trăm chiết khấu thanh toán
3.27 tax array Phần trăm thuế
3.28 taxAmount number Tiền thuế
3.29 changeFees number Phụ phí (với các hóa đơn hàng không)
3.30 cod number Tiền phí thu hộ (với các hóa đơn hàng không)
3.31 status string Trạng thái tra cứu hóa đơn
+ VALID: Hợp lệ
+ INVALID: Không hợp lệ
3.32 receivedDate date Ngày UBot nhận hóa đơn
3.33 invoiceReleaseDate date Ngày phát hành hóa đơn
3.34 invoiceSignDate date Ngày ký hóa đơn
3.35 isInvoiceRelease boolean Hóa đơn đã phát hành chưa
+ true: Hóa đơn đã phát hành
+ false: Hóa đơn chưa phát hành
3.36 isSellerActive boolean Người bán có hoạt động hay không
+ true: Bên bán đang hoạt động
+ false: Bên bán không hoạt động
3.37 sellerActiveStatus Chi tiết trạng thái bên bán
+ Bên bán đang hoạt động
+ NNT đang hoạt động (đã được cấp GCN ĐKT)
+ Bên bán không hoạt động tại địa chỉ đã đăng ký
+ NNT không hoạt động
+ NNT đã được cấp MST
+ Bên bán ngừng hoạt động nhưng chưa hoàn thành thủ tục chấm dứt hiệu lực MST
+ Bên bán ngừng hoạt động và đã hoàn thành thủ tục chấm dứt hiệu lực MST
+ Bên bán tạm ngừng hoạt động, kinh doanh
+ NNT không hoạt động tại địa chỉ đăng ký
+ NNT đang hoạt động (được cấp thông báo MST)
+ NNT ngừng hoạt động nhưng chưa hoàn thành thủ tục đóng MST
+ Bên bán đã chuyển cơ quan thuế quản lý
+ NNT tạm ngừng KD có thời hạn
+ NNT tạm nghỉ kinh doanh có thời hạn
+ NNT đang hoạt động (chưa đầy đủ thủ tục cấp MST)
+ Bên bán đã được cấp MST
+ NNT không hoạt động tại địa chỉ đã đăng ký
+ NNT ngừng hoạt động và đã đóng MST
+ NNT ngừng HĐ nhưng chưa hoàn thành thủ tục chấm dứt hiệu lực MST
+ NNT đang hoạt động (áp dụng cho hộ kinh doanh, cá nhân, chưa đủ thông tin đăng ký thuế)
+ NNT ngừng hoạt động và đã hoàn thành thủ tục chấm dứt hiệu lực MST
+ NNT đã chuyển cơ quan thuế quản lý
3.38 rawCheckingStatus string Trạng thái hóa đơn tra cứu trên TCT
3.39 isBuyerAddressValid boolean Địa chỉ công ty mua có hợp lệ không
+ true: Hợp lệ
+ false: Không hợp lệ
3.40 isBuyerNameValid boolean Tên công ty mua có hợp lệ không
+ true: Hợp lệ
+ false: Không hợp lệ
3.41 isSellerSignatureValid boolean Chữ ký số bên bán có hợp lệ không
+ true: Hợp lệ
+ false: Không hợp lệ
3.42 isBuyerTaxValid boolean MST công ty mua có hợp lệ không
+ true: Hợp lệ
+ false: Không hợp lệ
3.43 manuallyMarkedValid boolean Hóa đơn có được đánh dấu hợp lệ bằng tay hay không
+ true: Đánh dấu bằng tay
+ false: Không đánh dấu hợp lệ bằng tay
3.44 currency string Đơn vị tiền tệ
3.45 downloadLink string Link tra cứu hóa đơn
3.46 downloadCode string Mã tra cứu hóa đơn
3.47 invoiceChangeTimes number Số lần hóa đơn bị sửa đổi bởi người dùng
3.48 invoiceLastChangedBy string Người chỉnh sửa thông tin hóa đơn cuối cùng
3.49 invoiceLastChangedDate date Ngày chỉnh sửa thông tin hóa đơn cuối cùng
3.50 invoiceLastCheckedDate date Ngày tra cứu hóa đơn gần nhất
3.51 po string Số PO đọc được trên hóa đơn
3.52 tags array Danh sách nhãn gắn với hóa đơn
3.53 tagId string Id của nhãn
3.54 tagName string Tên của nhãn
3.55 invoiceType string Loại hóa đơn
+ INPUT_PAPER_INVOICE: Hóa đơn đầu vào (giấy)
+ INPUT_ELECTRONIC_INVOICE: Hóa đơn đầu vào (điện tử)
+ OUTPUT_ELECTRONIC_INVOICE: Hoá đơn đầu ra (điện tử)
+ INPUT_PAPER_INVOICE_OCR: Hóa đơn đầu vào (giấy) đọc OCR
+ INPUT_ELECTRONIC_INVOICE_OCR: Hóa đơn đầu vào (điện tử) đọc OCR
+ OUTPUT_ELECTRONIC_INVOICE_OCR: Hoá đơn đầu ra (điện tử) đọc OCR
3.56 vendorCode string Mã nhà cung cấp
3.57 paymentCode string Mã thanh toán
3.58 requestId string Mã request gửi hóa đơn sang UBot (Nếu KH gửi hóa đơn sang UBot qua API)
3.59 linkPDF string Link download file PDF
3.60 linkXML string Link download file XML
3.61 linkAttachment string Link download file zip chứa các tài liệu đính kèm
3.62 linkScreenshot string Link download file ảnh chụp tra cứu hóa đơn trên TCT
3.63 taxAuthorityCode string Mã cơ quan thuế
3.64 exchangeRate number Tỷ giá ngoại tệ
3.65 invoiceNote string Ghi chú hóa đơn hủy/thay thế
4 invoiceItems Danh sách chi tiết hàng hóa
4.1 itemId string id của hóa đơn
4.2 itemOrderNo string Số thứ tự của hàng hóa trong hóa đơn
4.3 itemCode string Mã hàng hóa map được từ matching data
4.4 itemCodeXml string Mã hàng hóa đọc được từ xml
4.5 itemName string Tên hàng hóa
4.6 itemPrice number Đơn giá của hàng hóa
4.7 itemQuantity number Số lượng của hàng hóa
4.8 itemUnit string Đơn vị tính
4.9 itemDiscount number Phần trăm chiết khấu của hàng hóa
4.10 itemDiscountAmount number Tiền chiết khấu của hàng hóa
4.11 itemTax number Thuế của hàng hóa
4.12 itemTaxAmount number Tiền thuế của hàng hóa
4.13 itemSubTotal number Tiền trước thuế của hàng hóa
4.14 itemGrandTotal number Tiền sau thuế của hàng hóa
4.15 inventoryAccount string Tài khoản kho
4.16 inventoryCode string Mã kho mặc định
4.17 expenseAccount string Tài khoản chi phí
4.18 taxAccount string Tài khoản thuế
4.19 revenueAccount string Tài khoản doanh thu
4.20 paymentMethod string Hình thức thanh toán
5 invoiceTaxes Chi tiết thuế suất
5.2 taxPercentage string Loại thuế kê khai: KCT/KKKNT/KHAC/0/5/8/10
5.3 amount number Thành tiền chịu thuế
5.4 taxAmount number Tiền thuế

 

Request mẫu

curl –location ‘https://portal.ubot.vn/api/third-party/invoices?page=0&size=10&sort=createdDate%2Cdesc’ \

–header ‘Authorization: Bearer eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiJob25kYXZuQHVib3Qudm4iLCJhdXRoIjoiQUNDRVNTX0lOVk9JQ0VfU09

MVVRJT04sQUNDRVNTX1NPTFVUSU9OLEFDQ09VTlRfTUFOQUdFTUVOVCxBQ1RJT05fSU5QVVRfSU5WT0lDRSxBRERfQ09NUEFOW

V9JTlZPSUNFLEFERF9QRVJNSVNTSU9OX01BTkFHRVJfR1JPVVAsQUREX1BFUk1JU1NJT05fU09MVVRJT05fR1JPVVAsQVNTSUdOX0

xBQkVMX0lOUFVUX0lOVk9JQ0UsQVNTSUdOX01VTFRJX0xBQkVMX0lOUFVUX0lOVk9JQ0UsQ09ORklERU5DRV9ISVNUT1JZLENSRUF

URV9MQUJFTF9JTlBVVF9JTlZPSUNFLENSRUFURV9MQUJFTF9JTlZPSUNFLENSRUFURV9VU0VSX0FDQ09VTlQsREVMRVRFX0NPTV

BBTllfSU5WT0lDRSxERUxFVEVfRE9DVU1FTlRfSU5QVVRfSU5WT0lDRSxERUxFVEVfTEFCRUxfSU5WT0lDRSxERUxFVEVfUEVSTUlTU0

lPTl9NQU5BR0VSX0dST1VQLERFTEVURV9QRVJNSVNTSU9OX1NPTFVUSU9OX0dST1VQLERPV05MT0FEX0RPQ1VNRU5UX0lOUFVU

X0lOVk9JQ0UsRE9XTkxPQURfUkVMQVRFRF9ET0NVTUVOVF9JTlBVVF9JTlZPSUNFLERPV05MT0FEX1JFU1VMVF9QUk9DRVNTSU5H

X0lOVk9JQ0UsRURJVF9DT01QQU5ZX0lOVk9JQ0UsRURJVF9DT05GSURFTkNFLEVESVRfUEVSTUlTU0lPTl9NQU5BR0VSX0dST1VQLE

VESVRfUEVSTUlTU0lPTl9TT0xVVElPTl9HUk9VUCxFRElUX1VTRVJfQUNDT1VOVCxFWFBPUlRfSU5QVVRfSU5WT0lDRSxJTlBVVF9JTlZ

PSUNFLElOUFVUX0lOVk9JQ0VfU1RBVElTVElDLElOVk9JQ0VfU1RBVElTVElDLExJU1RfQ09ORklERU5DRV9ISVNUT1JZLExJU1RfSU5Q

VVRfSU5WT0lDRSxMSVNUX1VTRVJfQUNDT1VOVCxNQUlMX0lOUFVUX0lOVk9JQ0VfU1RBVElTVElDLE1BSUxfSU5WT0lDRSxNQU5BR

0VSX0dST1VQLE1BTlVBTF9WQUxJRF9NQVJLX0lOUFVUX0lOVk9JQ0UsTUFSS19SRUFEX01BSUxfSU5WT0lDRSxNQVJLX1ZBTElEX0l

OUFVUX0lOVk9JQ0UsT0NSX0lOVEVHUkFUSU9OX0lOVk9JQ0VfUFJPQ0VTU0lORyxQRVJNSVNTSU9OX0dST1VQLFFVT1RBX0lOVk9J

Q0VfU1RBVElTVElDLFJFQ0hFQ0tfSU5QVVRfSU5WT0lDRSxST0xFX0NVU1RPTUVSLFJPTEVfSU5WT0lDRSxST0xFX09DUl9JTlRFR1JBV

ElPTl9DT05GSUdfQ09ORklERU5DRSxST0xFX09DUl9JTlRFR1JBVElPTl9JTlZPSUNFX1BST0NFU1NJTkcsU0VUVElOR19CQUNLVVBfSU5

WT0lDRSxTRVRUSU5HX0NPTVBBTllfSU5WT0lDRSxTRVRUSU5HX0lOVk9JQ0sU0VUVElOR19MQUJFTF9JTlZPSUNFLFNFVFRJTkdfVE

VNUExBVEVfRVhDRUwsU09MVVRJT05fR1JPVVAsVUJPVF9MT09LVVBfSU5QVVRfSU5WT0lDRV9TVEFUSVNUSUMsVUJPVF9NQU5BR

0VNRU5ULFVQTE9BRF9ET0NVTUVOVF9JTlBVVF9JTlZPSUNFLFVTRVJfTUFOQUdFTUVOVCxWSUVXX0RFVEFJTF9JTlBVVF9JTlZPSU

NFLFZJRVdfREVUQUlMX1BFUk1JU1NJT05fU09MVVRJT05fR1JPVVAsVklFV19ERVRBSUxfVVNFUl9BQ0NPVU5ULFZJRVdfRE9DVU1FTl

RfSU5QVVRfSU5WT0lDRSxWSUVXX0hJU1RPUllfU0VBUkNIX0lOUFVUX0lOVk9JQ0UsVklFV19QRVJNSVNTSU9OX01BTkFHRVJfR1JPV

VAiLCJleHAiOjE2ODM5NjE3MzN9.agCJS1emLFCioaIH8jKUvpoIFCz4_4ehjaQWUFX9IUUT8wOhOvu80aAp82Bxc5ROFV09MsIjG_zE-IYBaO77as’ \

–header ‘Content-Type: application/json’ \

–data ‘{

    “invoiceTypes”: [],

    “buyerTaxNo”: “2500150511”,

    “buyerName”: “CÔNG TY HONDA VIỆT NAM”,

    “invoiceNo”: “00000400”,

    “sellerTaxNo”: “2500257610”,

    “sellerName”: “CÔNG TY TNHH CÔNG NGHIỆP STRONG WAY VĨNH PHÚC”,

    “releasedDateFrom”: “11/04/2023”,

    “releasedDateTo”: “13/04/2023”,

    “receivedDateFrom”: “11/04/2023”,

    “receivedDateTo”: “14/04/2023”,

    “tagNames”: [“Chưa gắn nhãn”],

    “isCombinedTag”: “False”,

    “invoiceStatus”: “VALID”,

    “releaseStatus”: “VALID”,

    “getMatchingData”: “False”,

   “getTaxes”: “False”,

    “getAttachments”: “True”,

    “page”: “1”,

    “size”: “100”,

    “sort”: “receivedDate “

}’
Respone mẫu
{
    “statusResponse”: {
        “statusCode”: 200,
        “errorCode”: null,
        “message”: “Success”
    },
    “metadata”: {
        “page”: 0,
        “size”: 10,
        “total”: 1,
        “orderBy”: “createdDate”,
        “sort”: “ASC”
    },
    “data”: [
        {
            “companyId”: “25f00000-edd9-4a46-a07a-23efda2ed60c”,
            “invoiceId”: “e2cd4461-100d-22f0-a613-e89b0000c3af”,
            “transactionId”: null,
            “emailId”: “c123d33e-a8f8-111-bb76-c3743ebca769”,
            “sender”: “autobot@ubot.vn”,
            “modelNo”: “1”,
            “serial”: “C24MYY”,
            “invoiceNo”: “00009000”,
            “sellerName”: “CÔNG TY TNHH”,
            “sellerTaxNo”: “0108440000,
            “sellerAddress”: “Phường Quỳnh Mai, Quận Hai Bà Trưng, Thành phố Hà Nội, Việt Nam”,
            “sellerPhone”: null,
            “signBy”: “CÔNG TY TNHH”,
            “isSignValid”: true,
            “signIssuerName”: “BkavCA SHA256”,
            “signSerialNumber”: “5403009860ae82a40a000b66e518fd00”,
            “signValidFrom”: “2024-05-11T03:42:01Z”,
            “signValidTo”: “2029-05-09T03:33:06Z”,
            “markedValidBy”: null,
            “markedValidDate”: null,
            “buyerName”: “TỔNG CÔNG TY CỔ PHẦN”,
            “buyerRepresentation”: null,
            “buyerTaxNo”: “0100930000”,
            “buyerAddress”: “Cầu Giấy, Phường Dịch Vọng, Quận Cầu Giấy, Thành phố Hà Nội”,
            “subTotal”: 6751000.00000,
            “grandTotal”: 7293680.00000,
            “discount”: 0.00000,
            “discountAmount”: 0.00000,
            “paymentDiscount”: null,
            “feeAmount”: 0.00000,
            “tax”: 8.00000,
            “taxAmount”: 542680.00000,
            “changeFees”: null,
            “cod”: null,
            “exchangeRate”: 1.00000,
            “status”: “IS_WAITING”,
            “receivedDate”: “2024-09-23T00:11:02Z”,
            “invoiceReleaseDate”: “2024-09-22T07:00:00Z”,
            “invoiceSignDate”: “2024-09-22T14:45:16Z”,
            “isInvoiceRelease”: true,
            “isSellerActive”: null,
            “releaseStatus”: “VALID”,
            “sellerActiveStatus”: null,
            “rawCheckingStatus”: “Tồn tại hóa đơn có thông tin trùng khớp với các thông tin tổ chức, cá nhân tìm kiếm.\nTrạng thái xử lý hoá đơn: Tổng cục thuế đã nhận hóa đơn có mã khởi tạo từ máy tính tiền”,
            “isBuyerAddressValid”: true,
            “isBuyerNameValid”: true,
            “isSellerSignatureValid”: true,
            “isBuyerTaxValid”: true,
            “manuallyMarkedValid”: null,
            “currency”: “VND”,
            “downloadLink”: null,
            “downloadCode”: null,
            “invoiceChangeTimes”: 0,
            “invoiceLastChangedBy”: null,
            “invoiceLastChangedDate”: null,
            “invoiceLastCheckedDate”: “2024-09-23T00:11:13Z”,
            “invoiceCreatedDate”: “2024-09-23T00:11:02Z”,
            “invoiceLastModifiedDate”: “2024-09-23T00:11:13Z”,
            “po”: null,
            “detailSellerStatusIds”: [],
            “tags”: [],
            “invoiceItems”: [
                {
                    “itemId”: “94427bb2-1141-49d0-b532-34bf5c207a98”,
                    “invoiceId”: “e3cd1111-607d-44f0-a613-e89b0000c3af”,
                    “itemOrderNo”: 6,
                    “itemCode”: null,
                    “itemCodeXml”: “CANHSUONTANG”,
                    “itemName”: “Canh sườn bò (Tặng)”,
                    “itemUnit”: “Suất”,
                    “itemPrice”: 0.00000,
                    “itemQuantity”: 4.00000,
                    “itemDiscount”: 0.00000,
                    “itemDiscountAmount”: 0.00000,
                    “itemTax”: 8.0,
                    “itemTaxAmount”: 0.00000,
                    “itemSubTotal”: 0.00000,
                    “itemGrandTotal”: 0.00000,
                    “inventoryAccount”: null,
                    “inventoryCode”: null,
                    “expenseAccount”: null,
                    “taxAccount”: null,
                    “revenueAccount”: null,
                    “vendorCode”: null,
                    “paymentCode”: null,
                    “paymentMethod”: null,
                    “billCode”: null
                },
                {
                    “itemId”: “485b7fc1-fa72-4256-ab84-b41b282172a8”,
                    “invoiceId”: “e3cd1111-607d-44f0-a613-e89b0000c3af”,
                    “itemOrderNo”: 4,
                    “itemCode”: null,
                    “itemCodeXml”: “JIMA26”,
                    “itemName”: “Thăn lưng Jima ướp + Dẻ sườn LA 4+4”,
                    “itemUnit”: “Suất”,
                    “itemPrice”: 1390000.00000,
                    “itemQuantity”: 1.00000,
                    “itemDiscount”: 0.00000,
                    “itemDiscountAmount”: 0.00000,
                    “itemTax”: 8.0,
                    “itemTaxAmount”: 111200.00000,
                    “itemSubTotal”: 1390000.00000,
                    “itemGrandTotal”: 1501200.00000,
                    “inventoryAccount”: null,
                    “inventoryCode”: null,
                    “expenseAccount”: null,
                    “taxAccount”: null,
                    “revenueAccount”: null,
                    “vendorCode”: null,
                    “paymentCode”: null,
                    “paymentMethod”: null,
                    “billCode”: null
                }
            ],
            “invoiceTaxes”: [
                {
                    “id”: “4cab3c0d-15bc-4ac6-bbe7-c8602e7d3b69”,
                    “taxType”: “TAX10”,
                    “taxPercentage”: “10%”,
                    “amount”: 130000.00000,
                    “taxAmount”: 13000.00000
                },
                {
                    “id”: “2e76a39c-54a1-4668-9079-329d57193e3b”,
                    “taxType”: “TAX8”,
                    “taxPercentage”: “8%”,
                    “amount”: 6621000.00000,
                    “taxAmount”: 529680.00000
                }
            ],
            “invoiceType”: “INPUT_ELECTRONIC_INVOICE”,
            “paymentDate”: null,
            “paymentType”: null,
            “requestId”: null,
            “linkXml”: “https://ubots3.s3.ap-northeast-1.amazonaws.com/Xml_Processing/1727050251049350108449908_C24MYY_9062.xml?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Date=20240923T024303Z&X-Amz-SignedHeaders=host&X-Amz-Expires=300000&X-Amz-Credential=AKIAUZX3YY3RJTL6TKFI%2F20240923%2Fap-northeast-1%2Fs3%2Faws4_request&X-Amz-Signature=d088d66eaabd6ad12634728307eccd255c6584a3fb1fc92715743e149f5a6cc6”,
            “linkPdf”: “https://ubots3.s3.ap-northeast-1.amazonaws.com/Pdf_Processing/e3cd4461-607d-44f0-a613-e89b1499c3af.pdf?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Date=20240923T024303Z&X-Amz-SignedHeaders=host&X-Amz-Expires=300000&X-Amz-Credential=AKIAUZX3YY3RJTL6TKFI%2F20240923%2Fap-northeast-1%2Fs3%2Faws4_request&X-Amz-Signature=301c0155344259fb88ec4202a41fbaf0182620e9dfab675842dab80f7cc4c889”,
            “linkScreenshot”: “https://ubots3.s3.ap-northeast-1.amazonaws.com/Screenshot/KQ_00009062_1727050271945.png?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Date=20240923T024303Z&X-Amz-SignedHeaders=host&X-Amz-Expires=300000&X-Amz-Credential=AKIAUZX3YY3RJTL6TKFI%2F20240923%2Fap-northeast-1%2Fs3%2Faws4_request&X-Amz-Signature=345a1bd623e6c50f970154517e139cb4f653a3b7490129f9e3d9c022768b8b1c”,
            “taxAuthorityCode”: “M1-24-JULPS-00000015822”,
            “invoiceNote”: null,
            “linkAttachment”: null
        }
    ]
}

4.3. API gửi thông tin hóa đơn

  # Item Thông tin
1 URL  Product: https://portal.ubot.vn/api/third-party/upload-email
2 HTTP method POST
3 Header Content-Type: application/json

Authorization: Bear + token lấy từ API đăng nhập

 

# Tên trường thông tin Tính chất bắt buộc Kiểu dữ liệu Max length Mô tả
Request
1 transactionId x string 256 TransactionID của bản ghi
2 files pdf/xml List file (có thể gửi được nhiều file max 15 PDF & XML)
3 companyId x string 256 Company id UBOT gửi (UBot sẽ gửi list companyId của từng Khách hàng)
4 title string Tiêu đề của email (nếu có thì lưu, không thì sẽ lấy transactionId để hiển thị tiêu đề email)
5 downloadLink string 255 Link tra cứu
6 downloadCode string 255 Mã tra cứu
7 invoiceNo string  15 Số hóa đơn
8  sellerTaxNo string  15 MST bên bán
9 sender x string 400 Người gửi
10 transactionMetadata string 500 Thông tin gửi kèm của hóa đơn
11 generalModelNo  string 255 Mẫu số
12 generalNotation  string 255 Ký hiệu
Response
1 status x string 256 Mã trạng thái đẩy file thông tin hóa đơn
2 message x string 256 Mô tả chi tiết trạng thái (Bảng mã lỗi)
Request mẫu

curl –location ‘https://portal.ubot.vn/api/third-party/upload-email’ \
–header ‘Authorization: Bearer eyJhbGciOiJIUzUxMiJ9.ey0VNRU5ULEFDVElPTl9JTlBVVF9JTlZPSUNFLEFDT01B1JFUVVFU1QsQ0FURUdPUllfSU5WT0lDRSxDSEFOR0VfQUNUSVZFX0VQQVlfU0VUVElOR19DT1NUX1RZUEUsQ09ORklERU5DRV9ISVNUT1JZLENPTkZJR19FUEFZX0FQUFJPVkVfUkVRVUVTVF9QQVlNRU5ULENPTkZJR19FUEFZX0NPU1RfVFlQRSxDT05GSUdfRVBBWV9ERVBBUlRNRU5ULENPTkZJR19FUEFZX1BBSUQsQ09ORklHX0VQQVlfUEFZTUVOVF9JTkZPUk1BVElPTixDT05GSUdfRVBBWV9QQVlNRU5UX1JFUVVFU1QsQ1JFQVRFX0VQQVlfUEFZTUVOVF9SRVFVRVNULENSRUFURV9FUEFZX1BBWU1FTlRfUkVRVUVTVF9GUk9NX0VYQ0VMLENSRUFURV9FUEFZX1NFVFRJTkdfQ09TVF9UWVBFLENSRUFURV9FUEFZX1NFVFRJTkdfREVQQVJUTUVOVCxDUkVBVEVfRVBBWV9TRVRUSU5HX1BBWU1FTlRfSU5GT1JNQVRJT04sQ1JFQVRFX0xBQkVMX0lOUFVUX0lOVk9JQ0UsQ1JFQVRFX0xBQkVMX0lOVk9JQ0UsQ1JFQVRFX0xBQkVMX09VVFBVVF9JTlZPSUNFLENSRUFURV9VU0VSX0FDQ09VTlQsREVMRVRFX0NPTVBBTllfSU5WT0lDRSxERUxFVEVfRE9DVU1FTlRfSU5QVVRfSU5WT0lDRSxERUxFVEVfRE9DVU1FTlRfT1VUUFVUX0lOVk9JQ0UsREVMRVRFX0VQQVlfU0VUVElOR19ERVBBUlRNRU5ULERFTEVURV9FUEFZX1NFVFRJTkdfUEFZTUVOVF9JTkZPUk1BVElPTixERUxFVEVfRklMRV9PVVRQVVRfSU5WT0lDRSxERUxFVEVfTEFCRUxfSU5WT0lDRSxERUxFVEVfUEFQRVJfSU5WT0lDRSxERUxFVEVfUEVSTUlTU0lPTl9NQU5BR0VSX0dST1VQLERFTEVURV9QRVJNSVNTSU9OX1NPTFVUSU9OX0dST1VQLERPV05MT0FEX0RPQ1VNRU5UX0lOUFVUX0lOVk9JQ0UsRE9XTkxPQURfRE9DVU1FTlRfT1VUUFVUX0lOVk9JQ0UsRE9XTkxPQURfRklMRV9PVVRQVVRfSU5WT0lDRSxET1dOTE9BRF9GSUxFX1JFU1VMVF9DQVRFR09SWV9JTlZPSUNFLERPV05MT0FEX1BBUEVSX0lOVk9JQ0UsRE9XTkxPQURfUkVMQVRFRF9ET0NVTUVOVF9JTlBVVF9JTlZPSUNFLERPV05MT0FEX1JFTEFURURfT1VUUFVUX0lOVk9JQ0UsRE9XTkxPQURfUkVTVUxUX1BST0NFU1NJTkdfSU5WT0lDRSxFRElUX0NPTVBBTllfSU5WT0lDRSxFRElUX0NPTkZJREVOQ0UsRURJVF9FUEFZX1BBWU1FTlRfUkVRVUVTVCxFRElUX0VQQVlfU0VUVElOR19DT1NUX1RZUEUsRURJVF9FUEFZX1NFVFRJTkdfREVQQVJUTUVOVCxFRElUX0VQQVlfU0VUVElOR19QQVlNRU5UX0lORk9STUFUSU9OLEVESVRfUEVSTUlTU0lPTl9NQU5BR0VSX0dST1VQLEVESVRfUEVSTUlTU0lPTl9TT0xVVElPTl9HUk9VUCxFRElUX1VTRVJfQUNDT1VOVCxFUEFZX1BBWU1FTlQsRVhQT1JUX0VQQVlfQVBQUk9WRV9QQVlNRU5UX1JFUVVFU1QsRVhQT1JUX0lOUFVUX0lOVk9JQ0UsRVhQT1JUX09VVFBVVF9JTlZPSUNFLEVwYXkgUGF5bWVudCxHUk9VUF9DT01QQU5ZX0FVVEhFTlRJQ0FUSU9OLElOUFVUX0lOVk9JQ0UsSU5QVVRfSU5WT0lDRV9TVEFUSVNUSUMsSU5QVVRfUEFQRVJfSU5WT0lDRSxJTlZPSUNFX1NPVVJDRSxJTlZPSUNFX1NUQVRJU1RJQyxJU1NVRURfU1RBVFVTX0lOUFVUX0lOVk9JQ0UsSVNTVUVEX1NUQVRVU19PVVRQVVRfSU5WT0lDRSxMSVNUX0NPTkZJREVOQ0VfSElTVE9SWSxMSVNUX0VQQVlfQVBQUk9WRV9QQVlNRU5UX1JFUVVFU1QsTElTVF9FUEFZX1JFUVVFU1RfUEFZTUVOVCxMSVNUX0VQQVlfU0VUVElOR19DT1NUX1RZUEUsTElTVF9FUEFZX1NFVFRJTkdfREVQQVJUTUVOVCxMSVNUX0VQQVlfU0VUVElOR19QQVlNRU5UX0lORk9STUFUSU9OLExJU1RfSU5QVVRfSU5WT0lDRSxMSVNUX09VVFBVVF9JTlZPSUNFLExJU1RfVVNFUl9BQ0NPVU5ULE1BSUxfSU5QVVRfSU5WT0lDRV9TVEFUSVNUSUMsTUFJTF9JTlZPSUNFLE1BTkFHRVJfR1JPVVAsTUFOVUFMX1ZBTElEX01BUktfSU5QVVRfSU5WT0lDRSxNQVJLX1JFQURfTUFJTF9JTlZPSUNFLE1BUktfVkFMSURfSU5QVVRfSU5WT0lDRSxNWV9PUkRFUl9DUkVBVEUsTVlfT1JERVJfVklFVyxPQ1JfSU5URUdSQVRJT05fSU5WT0lDRV9QUk9DRVNTSU5HLE9VVFBVVF9JTlZPSUNFLE9VVFBVVF9JTlZPSUNFX1NUQVRJU1RJQyxQRVJNSVNTSU9OX0dST1VQLFFVT1RBX0lOVk9JQ0VfU1RBVElTVElDLFJFQ0hFQ0tfSU5QVVRfSU5WT0lDRSxST0xFX0NVU1RPTUVSLFJPTEVfQ1VTVE9NRVJfT05MSU5FX1BBWU1FTlRfU0VSVklDRSxST0xFX0NVU1RPTUVSX1BBUEVSX0lOVk9JQ0UsUk9MRV9JTVBPUlRfTUFTVEVSX0RBVEEsUk9MRV9JTlZPSUNFLFJPTEVfSVNTVUVEX0lOVk9JQ0VfU1RBVFVTLFJPTEVfT0NSX0lOVEVHUkFUSU9OX0NPTkZJR19DT05GSURFTkNFLFJPTEVfT0NSX0lOVEVHUkFUSU9OX0lOVk9JQ0VfUFJPQ0VTU0lORyxST0xFX1VQTE9BRF9PVVRQVVRfRUxFQ1RST05JQ19JTlZPSUNFUyxTRVRUSU5HX0JBQ0tVUF9JTlZPSUNFLFNFVFRJTkdfQ09NUEFOWV9JTlZPSUNFLFNFVFRJTkdfR0RUX0lOVk9JQ0UsU0VUVElOR19JTlZPSUNFLFNFVFRJTkdfTEFCRUxfSU5WT0lDRSxTRVRUSU5HX1RFTVBMQVRFX0VYQ0VMLFNPTFVUSU9OX0dST1VQLFRIUkVFX1dBWV9NQVRDSElORyxUT1RPLFRSQU5TRkVSX0RFUEFSVE1FTlRfSU5QVVRfSU5WT0lDRSxUaHJlZSBXYXkgTWF0Y2hpbmcsVUJPVF9MT09LVVBfSU5QVVRfSU5WT0lDRV9TVEFUSVNUSUMsVUJPVF9NQU5BR0VNRU5ULFVQTE9BRF9DQVRFR09SWV9JTlZPSUNFLFVQTE9BRF9ET0NVTUVOVF9JTlBVVF9JTlZPSUNFLFVQTE9BRF9ET0NVTUVOVF9PVVRQVVRfSU5WT0lDRSxVUExPQURfRklMRV9PVVRQVVRfSU5WT0lDRSxVUExPQURfSU5QVVRfSU5WT0lDRSxVUExPQURfT1VUUFVUX0lOVk9JQ0UsVVBMT0FEX1BBUEVSX0lOVk9JQ0UsVVNFUl9NQU5BR0VNRU5ULFZJRVdfREVUQUlMX0lOUFVUX0lOVk9JQ0UsVklFV19ERVRBSUxfT1VUUFVUX0lOVk9JQ0UsVklFV19ERVRBSUxfUEVSTUlTU0lPTl9TT0xVVElPTl9HUk9VUCxWSUVXX0RFVEFJTF9VU0VSX0FDQ09VTlQsVklFV19ET0NVTUVOVF9JTlBVVF9JTlZPSUNFLFZJRVdfRE9DVU1FTlRfT1VUUFVUX0lOVk9JQ0UsVklFV19ISVNUT1JZX1NFQVJDSF9JTlBVVF9JTlZPSUNFLFZJRVdfUEVSTUlTU0lPTl9NQU5BR0VSX0dST1VQIiwiZXhwIjoxNzMyOTU5MTkzfQ.t2R9aYuD3wcsy5GAZkRsZbkhpS8DmAUARHBTHGO2K9zKd0VQiSow6fc7FgcaSMxxuWYBRpyIb-9s7wF75wczcQ’ \
–form ‘transactionId=”10″‘ \
–form ‘files=@”/path/to/file”‘ \
–form ‘files=@”jJuPCJd9-/2024_0901014110_C24TKG_341.xml”‘ \
–form ‘companyId=”21c62ec6-2fe4-40d7-8e60-f6f0f816dc31″‘ \
–form ‘downloadLink=””‘ \
–form ‘downloadCode=””‘ \
–form ‘invoiceNo=””‘ \
–form ‘sellerTaxNo=””‘ \
–form ‘sender=”Binhtt@gmail.com”‘ \
–form ‘transactionMetadata=”{ \”sellerTaxNo\”: \”01838393993\”, \”modelNo\”: \”1\”, \”serial\”: \”C23TYY\”, \”buyer\”: \”FE\”, \”status\”: \”done\”, \”createdBy\”: \”linhnt@fpt.com\”, \”approver\”: \”admin@fpt.com\”, \”invoiceId\”: \”19298esh838383774\”, \”paymentId\”: \”123555\”}”‘
Respone mẫu

{
          “status”: 200,
          “message”: “Success”
      }

 

4.4. API gửi hóa đơn OCR

  # Item Thông tin
1 URL  Product: https://portal.ubot.vn/api/third-party/upload-file
2 HTTP method POST
3 Header Content-Type: application/json

Authorization: Bear + token lấy từ API đăng nhập

 

# Tên trường thông tin Tính chất bắt buộc Kiểu dữ liệu Max length Mô tả
Request
1 files array Y List file (có thể gửi được nhiều file max 15 PDF & XML). Ví dụ: [“file_name_1″,”file_name_2”,…]
2 companyId string Y 256 Company id UBOT gửi (UBot sẽ gửi list companyId của từng Khách hàng)
Response
1 status string Y 256 Mã trạng thái đẩy file hóa đơn
2 message string Y  256 Mô tả chi tiết trạng thái (Bảng mã lỗi)

 

Request mẫu

{
    “files”: [],
    “companyId” : “1743467345354354fgdfd33”
}{
    “transactionId” : “ABC177R2538944”, 
    “files”: []
    “companyId” : “1743467345354354fgdfd33”,
    “title” : “HÓA ĐƠN ĐIỆN NƯỚC”,
    “body” : “InvNo123”,
    “downloadLink” : “tracuu.ehoadon.vn”,
    “downloadCode” : “DFGDFUGFUGF”,
    “invoiceNo” : “1234”,
    “sellerTaxNo” : “12345678”,
    “sender” : “autobot@ubot.com”
}
Respone mẫu

{
          “status”: 200,
          “message”: “Success”
      }

 

4.5. API nhận trạng thái của TransactionId

Mục đích: API trả trạng thái của TransacstionID nhằm mục đích UBot kết nối với đối tác trả thông tin trạng thái của email hóa đơn UBot nhận xử lý.

# Item Thông tin
1 URL  Product: https://portal.ubot.vn/api/third-party/transaction-status-by-ids
2 HTTP method POST
3 Header Content-Type: application/json

Authorization: Bear + token lấy từ API đăng nhập

 

# Tên trường thông tin Tính chất bắt buộc Kiểu dữ liệu Max length Mô tả
Request
1 transactionIds array Y Truyền 1 hoặc list TransactionId 
Response
meta (trả thông tin trạng thái email)
1 status string Y 256 Mã trạng thái đẩy xử lý email 
2 message string Y  256 Mô tả chi tiết trạng thái (Bảng mã lỗi)
data (trả thông tin chi tiết trạng thái từng file dữ liệu trong 1 email)
3 transactionId array Y 256 transactionId
4 status string Y  256 Trạng thái từng file trong email được xử lý:

+ Done: Đã xử lý

+ Running: Đang xử lý

+ Duplicate: Trùng lặp

+ Unknown: Không xác định
5 invoiceId string Y 256 Mã hóa đơn xử lý
6 totalInvoice string Y  256 Tổng số lượng hóa đơn xử lý thành công của TransactionId hoặc EmailId

 

Request mẫu

{
    “files”: [],
    “companyId” : “1743467345354354fgdfd33”
}
Respone mẫu

– meta:

{

statusCode: “200”,

message: Thành công

}

– data:

{

transactionId:

status: //gồm các giá trị: done, running, duplicate, unknown

invoiceId: //Id hóa đơn bị trùng lặp (1 hoặc list invoiceId)

totalInvoice: //tổng số hóa đơn xử lý thành công của TransactionId or emailId

}

 

4.6. API trả danh sách TransactionId

Mục đích: API trả danh sách TransacstionID nhằm mục đích đối tác có thể biết được danh sách TransactionId (danh sách hóa đơn) đẩy thành công vào UBot nhận xử lý.

# Item Thông tin
1 URL  Product: https://portal.ubot.vn/api/third-party/transactions
2 HTTP method POST
3 Header Content-Type: application/json

Authorization: Bear + token lấy từ API đăng nhập

 

# Tên trường thông tin Tính chất bắt buộc Kiểu dữ liệu Max length Mô tả
Request Parameter
1 from x date 256 Ngày UBot nhận hóa đơn
2 to x date 256 Ngày UBot nhận hóa đơn
3 page x number 256 Thứ tự trang đã được phân trang. Mặc định: 0
4 size x number 256 Số lượng bản ghi mỗi trang.  Default: 10. Max: 100 hóa đơn/response
5 sort x string 256 Sort theo tiêu chí:
+ createdDate: Ngày nhận hóa đơn về UBot
6 companyId string 256 Id của công ty (UBot cung cấp)
Response
1 statusResponse Kết quả xử lý request
1.1 statusCode string Tham khảo bảng Status code, mục V. Mã lỗi
1.2 errorCode string Mã lỗi. Tham khảo bảng Error code, mục V. Mã lỗi #1 và #6
1.3 message string Nội dung lỗi. Tham khảo bảng Error code, mục V. Mã lỗi
2 metadata Thông tin bổ sung
2.1 page number Số thứ tự trang kết quả trả về
2.2 size number Số hóa đơn trong 1 trang kết quả trả về
2.3 total number Tổng số hóa đơn trả về
2.4 orderBy string Thứ tự của hóa đơn trả về
+ receivedDate (Default): Ngày nhận hóa đơn về UBot
+ invoiceReleaseDate: Ngày phát hành
2.5 sort Sort theo các tiêu chí:
+ ASC: tăng dần
+ DESC (default): giảm dần
3 data Danh sách hóa đơn
3.1 id string ID của bản ghi
3.2 transactionId string TransactionId của hóa đơn
3.3 companyId string CompanyId của hóa đơn
3.4 metadata string Thông tin đi kèm của hóa đơn
3.5 createdBy string Người gửi
3.6 createDate string Ngày UBot nhận hóa đơn
Request mẫu

curl –location ‘https://portal.ubot.vn/api/third-party/transactions?from=31%2F10%2F2024&to=31%2F10%2F2024&page=0&size=10&sort=createdDate%2Cdesc’ \
–header ‘Authorization: Bearer OiJ0aGFvbnRwNDBAdWJvdC52biIsImF1dGgiOiJBQ0NFU1NfSFDVElPTl9JTlBVVF9JTlZPSUNFLEFDVElPTl9PVVRQVVRfSU5WT0lDRSxBQ1RJT05fVVBMT0FEX0lOUFVUX0lOVk9JQ0UsQUNUSU9OX1VQTE9BRF9PVVRQVVRfSU5WT0lDRSxBRERfQ09NUEFOWV9JTlZPSUNFLEFERF9QRVJNSVNTSU9OX01BTkFHRVJfR1JPVVAsQUREX1BFUk1JU1NJT05fU09MVVRJT05fR1JPVVAsQVBQUk9WRV9FUEFZX0FQUFJPVkVfUEFZTUVOVF9SRVFVRVNULEFQUFJPVkVfVkFSSUFOVF9JTlBVVF9JTlZPSUNFLEFTU0lHTl9MQUJFTF9JTlBVVF9JTlZPSUNFLEFTU0lHTl9MQUJFTF9PVVRQVVRfSU5WT0lDRSxBU1NJR05fTVVMVElfTEFCRUxfSU5QVVRfSU5WT0lDRSxBU1NJR05fTVVMVElfTEFCRUxfT1VUUFVUX0lOVk9JQ0UsQVVUSE9SSVRZX0VQQVlfQVBQUk9WRV9QQVlNRU5UX1JFUVVFU1QsQVVUT01BVElPTl9DUkVBVEVfTEFCRUxfSU5WT0lDRSxDQU5DRUxfRVBBWV9QQVlNRU5UX1JFUVVFU1QsQ0FURUdPUllfSU5WT0lDRSxDSEFOR0VfQUNUSVZFX0VQQVlfU0VUVElOR19DT1NUX1RZUEUsQ09ORklERU5DRV9ISVNUT1JZLENPTkZJR19FUEFZX0FQUFJPVkVfUkVRVUVTVF9QQVlNRU5ULENPTkZJR19FUEFZX0NPU1RfVFlQRSxDT05GSUdfRVBBWV9ERVBBUlRNRU5ULENPTkZJR19FUEFZX1BBSUQsQ09ORklHX0VQQVlfUEFZTUVOVF9JTkZPUk1BVElPTixDT05GSUdfRVBBWV9QQVlNRU5UX1JFUVVFU1QsQ1JFQVRFX0VQQVlfUEFZTUVOVF9SRVFVRVNULENSRUFURV9FUEFZX1BBWU1FTlRfUkVRVUVTVF9GUk9NX0VYQ0VMLENSRUFURV9FUEFZX1NFVFRJTkdfQ09TVF9UWVBFLENSRUFURV9FUEFZX1NFVFRJTkdfREVQQVJUTUVOVCxDUkVBVEVfRVBBWV9TRVRUSU5HX1BBWU1FTlRfSU5GT1JNQVRJT04sQ1JFQVRFX0xBQkVMX0lOUFVUX0lOVk9JQ0UsQ1JFQVRFX0xBQkVMX0lOVk9JQ0UsQ1JFQVRFX0xBQkVMX09VVFBVVF9JTlZPSUNFLENSRUFURV9VU0VSX0FDQ09VTlQsREVMRVRFX0NPTVBBTllfSU5WT0lDRSxERUxFVEVfRE9DVU1FTlRfSU5QVVRfSU5WT0lDRSxERUxFVEVfRE9DVU1FTlRfT1VUUFVUX0lOVk9JQ0UsREVMRVRFX0VQQVlfU0VUVElOR19ERVBBUlRNRU5ULERFTEVURV9FUEFZX1NFVFRJTkdfUEFZTUVOVF9JTkZPUk1BVElPTixERUxFVEVfRklMRV9PVVRQVVRfSU5WT0lDRSxERUxFVEVfTEFCRUxfSU5WT0lDRSxERUxFVEVfUEFQRVJfSU5WT0lDRSxERUxFVEVfUEVSTUlTU0lPTl9NQU5BR0VSX0dST1VQLERFTEVURV9QRVJNSVNTSU9OX1NPTFVUSU9OX0dST1VQLERPV05MT0FEX0RPQ1VNRU5UX0lOUFVUX0lOVk9JQ0UsRE9XTkxPQURfRE9DVU1FTlRfT1VUUFVUX0lOVk9JQ0UsRE9XTkxPQURfRklMRV9PVVRQVVRfSU5WT0lDRSxET1dOTE9BRF9GSUxFX1JFU1VMVF9DQVRFR09SWV9JTlZPSUNFLERPV05MT0FEX1BBUEVSX0lOVk9JQ0UsRE9XTkxPQURfUkVMQVRFRF9ET0NVTUVOVF9JTlBVVF9JTlZPSUNFLERPV05MT0FEX1JFTEFURURfT1VUUFVUX0lOVk9JQ0UsRE9XTkxPQURfUkVTVUxUX1BST0NFU1NJTkdfSU5WT0lDRSxFRElUX0NPTVBBTllfSU5WT0lDRSxFRElUX0NPTkZJREVOQ0UsRURJVF9FUEFZX1BBWU1FTlRfUkVRVUVTVCxFRElUX0VQQVlfU0VUVElOR19DT1NUX1RZUEUsRURJVF9FUEFZX1NFVFRJTkdfREVQQVJUTUVOVCxFRElUX0VQQVlfU0VUVElOR19QQVlNRU5UX0lORk9STUFUSU9OLEVESVRfUEVSTUlTU0lPTl9NQU5BR0VSX0dST1VQLEVESVRfUEVSTUlTU0lPTl9TT0xVVElPTl9HUk9VUCxFRElUX1VTRVJfQUNDT1VOVCxFUEFZX1BBWU1FTlQsRVhQT1JUX0VQQVlfQVBQUk9WRV9QQVlNRU5UX1JFUVVFU1QsRVhQT1JUX0lOUFVUX0lOVk9JQ0UsRVhQT1JUX09VVFBVVF9JTlZPSUNFLEVwYXkgUGF5bWVudCxHUk9VUF9DT01QQU5ZX0FVVEhFTlRJQ0FUSU9OLElOUFVUX0lOVk9JQ0UsSU5QVVRfSU5WT0lDRV9TVEFUSVNUSUMsSU5QVVRfUEFQRVJfSU5WT0lDRSxJTlZPSUNFX1NPVVJDRSxJTlZPSUNFX1NUQVRJU1RJQyxJU1NVRURfU1RBVFVTX0lOUFVUX0lOVk9JQ0UsSVNTVUVEX1NUQVRVU19PVVRQVVRfSU5WT0lDRSxMSVNUX0NPTkZJREVOQ0VfSElTVE9SWSxMSVNUX0VQQVlfQVBQUk9WRV9QQVlNRU5UX1JFUVVFU1QsTElTVF9FUEFZX1JFUVVFU1RfUEFZTUVOVCxMSVNUX0VQQVlfU0VUVElOR19DT1NUX1RZUEUsTElTVF9FUEFZX1NFVFRJTkdfREVQQVJUTUVOVCxMSVNUX0VQQVlfU0VUVElOR19QQVlNRU5UX0lORk9STUFUSU9OLExJU1RfSU5QVVRfSU5WT0lDRSxMSVNUX09VVFBVVF9JTlZPSUNFLExJU1RfVVNFUl9BQ0NPVU5ULE1BSUxfSU5QVVRfSU5WT0lDRV9TVEFUSVNUSUMsTUFJTF9JTlZPSUNFLE1BTkFHRVJfR1JPVVAsTUFOVUFMX1ZBTElEX01BUktfSU5QVVRfSU5WT0lDRSxNQVJLX1JFQURfTUFJTF9JTlZPSUNFLE1BUktfVkFMSURfSU5QVVRfSU5WT0lDRSxNWV9PUkRFUl9DUkVBVEUsTVlfT1JERVJfVklFVyxPQ1JfSU5URUdSQVRJT05fSU5WT0lDRV9QUk9DRVNTSU5HLE9VVFBVVF9JTlZPSUNFLE9VVFBVVF9JTlZPSUNFX1NUQVRJU1RJQyxQRVJNSVNTSU9OX0dST1VQLFFVT1RBX0lOVk9JQ0VfU1RBVElTVElDLFJFQ0hFQ0tfSU5QVVRfSU5WT0lDRSxST0xFX0NVU1RPTUVSLFJPTEVfQ1VTVE9NRVJfT05MSU5FX1BBWU1FTlRfU0VSVklDRSxST0xFX0NVU1RPTUVSX1BBUEVSX0lOVk9JQ0UsUk9MRV9JTVBPUlRfTUFTVEVSX0RBVEEsUk9MRV9JTlZPSUNFLFJPTEVfSVNTVUVEX0lOVk9JQ0VfU1RBVFVTLFJPTEVfT0NSX0lOVEVHUkFUSU9OX0NPTkZJR19DT05GSURFTkNFLFJPTEVfT0NSX0lOVEVHUkFUSU9OX0lOVk9JQ0VfUFJPQ0VTU0lORyxST0xFX1VQTE9BRF9PVVRQVVRfRUxFQ1RST05JQ19JTlZPSUNFUyxTRVRUSU5HX0JBQ0tVUF9JTlZPSUNFLFNFVFRJTkdfQ09NUEFOWV9JTlZPSUNFLFNFVFRJTkdfR0RUX0lOVk9JQ0UsU0VUVElOR19JTlZPSUNFLFNFVFRJTkdfTEFCRUxfSU5WT0lDRSxTRVRUSU5HX1RFTVBMQVRFX0VYQ0VMLFNPTFVUSU9OX0dST1VQLFRIUkVFX1dBWV9NQVRDSElORyxUT1RPLFRSQU5TRkVSX0RFUEFSVE1FTlRfSU5QVVRfSU5WT0lDRSxUaHJlZSBXYXkgTWF0Y2hpbmcsVUJPVF9MT09LVVBfSU5QVVRfSU5WT0lDRV9TVEFUSVNUSUMsVUJPVF9NQU5BR0VNRU5ULFVQTE9BRF9DQVRFR09SWV9JTlZPSUNFLFVQTE9BRF9ET0NVTUVOVF9JTlBVVF9JTlZPSUNFLFVQTE9BRF9ET0NVTUVOVF9PVVRQVVRfSU5WT0lDRSxVUExPQURfRklMRV9PVVRQVVRfSU5WT0lDRSxVUExPQURfSU5QVVRfSU5WT0lDRSxVUExPQURfT1VUUFVUX0lOVk9JQ0UsVVBMT0FEX1BBUEVSX0lOVk9JQ0UsVVNFUl9NQU5BR0VNRU5ULFZJRVdfREVUQUlMX0lOUFVUX0lOVk9JQ0UsVklFV19ERVRBSUxfT1VUUFVUX0lOVk9JQ0UsVklFV19ERVRBSUxfUEVSTUlTU0lPTl9TT0xVVElPTl9HUk9VUCxWSUVXX0RFVEFJTF9VU0VSX0FDQ09VTlQsVklFV19ET0NVTUVOVF9JTlBVVF9JTlZPSUNFLFZJRVdfRE9DVU1FTlRfT1VUUFVUX0lOVk9JQ0UsVklFV19ISVNUT1JZX1NFQVJDSF9JTlBVVF9JTlZPSUNFLFZJRVdfUEVSTUlTU0lPTl9NQU5BR0VSX0dST1VQIiwiZXhwIjoxNzMyOTU5MTkzfQ.t2R9aYuD3wcsy5GAZkRsZbkhpS8DmAUARHBTHGO2K9zKd0VQiSow6fc7FgcaSMxxuWYBRpyIb-9s7wF75wczcQ’
Respone mẫu
{
    “statusResponse”: {
        “statusCode”: 200,
        “errorCode”: null,
        “message”: “Success”
    },
    “metadata”: {
        “page”: 0,
        “size”: 10,
        “total”: 30,
        “orderBy”: null,
        “sort”: null
    },
    “data”: [
          {
            “id”: “29559556-4c76-4765-b060-fee39f0f3d2f”,
            “transactionId”: “11”,
            “companyId”: “21c62ec6-2fe4-40d7-8e60-f6f0f816dc31”,
            “emailId”: “fb66270b-7b4d-4384-81d6-3e78cae020b6”,
            “metaData”: “{ \”sellerTaxNo\”: \”01838393993\”, \”modelNo\”: \”1\”, \”serial\”: \”C23TYY\”,  \”buyer\”: \”FE\”,  \”status\”: \”done\”,  \”createdBy\”: \”linhnt@fpt.com\”,  \”approver\”: \”admin@fpt.com\”,  \”invoiceId\”: \”19298esh838383774\”,  \”paymentId\”: \”123555\”}”,
            “createdBy”: “thaontp40@ubot.vn”,
            “createdDate”: “2024-10-31T09:50:35Z”
        },
        {
            “id”: “abc1e7c9-1f3b-4062-8ea1-efb2a7a362ce”,
            “transactionId”: “a242395f-2042-44fa-91fd-4c5c77d6f11a”,
            “companyId”: “f10b63e9-9036-4846-b3b7-9b92c532b427”,
            “emailId”: “9d689254-87a1-44ad-b738-66d065d394cb”,
            “metaData”: null,
            “createdBy”: “thaontp40@ubot.vn”,
            “createdDate”: “2024-10-31T10:57:43Z”
        },
        {
            “id”: “2e7e2b21-9fa7-4f70-a693-b09d0cf5e9ce”,
            “transactionId”: “7749a678-7ff5-4281-b03c-e209a8d468e6”,
            “companyId”: “f10b63e9-9036-4846-b3b7-9b92c532b427”,
            “emailId”: “88e39011-bc81-4d23-b2ea-c6154715729e”,
            “metaData”: null,
            “createdBy”: “thaontp40@ubot.vn”,
            “createdDate”: “2024-10-31T10:57:34Z”
        }
    ]
}

  • MÃ LỖI

Bảng V.1 Status code

# statusCode Mô tả
1 200 Success
2 400 Bad Request (required fields; over max length; wrong data type).
3 401 Un-authorized (Chưa login, Sai token)
4 403 Không có quyền truy cập
5 500 Error exception

 

Bảng V.2 Error code

# errorCode message
1 Null/Blank Không có lỗi
2 INV0005 Maximum size is 100
3 INV0006 The company does not belong to this account

 

 

Bài viết liên quan