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 Y string 256 Email đăng nhập
2 password Y string 256 Mật khẩu đăng nhập
3 rememberMe N 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
1 invoiceTypes Y array 256 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 OCR
2 buyerTaxNo N string 256 Mã số thuế bên mua
3 buyerName N string 256 Tên công ty bên mua
4 invoiceNo N string 256 Số hóa đơn
5 sellerTaxNo N string 256 Mã số thuế bên bán
6 sellerName N string 256 Tên công ty bên bán
7 releasedDateFrom N date 256 Ngày phát hành hóa đơn (Từ ngày)

Định dạng: dd/mm/yyyy
8 releasedDateTo N date 256 Ngày phát hành hóa đơn (Đến ngày)

Định dạng: dd/mm/yyyy
9 receivedDateFrom N date 256 Ngày nhận hóa đơn về UBot (Từ ngày)

Định dạng: dd/mm/yyyy
10 receivedDateTo N date 256 Ngày nhận hóa đơn về UBot (Đến ngày)

Định dạng: dd/mm/yyyy
11 tagNames N array 256 Danh sách nhãn gắn với hóa đơn. VD: [“tag1”, “tag2”]
12 isCombinedTag N boolean 256 Lựa chọn tìm các nhãn theo
 + true: Điều kiện AND
 + false: Điều kiện OR (Default)
13 invoiceStatus N string 256 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 N string 256 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 N boolean 256 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 N boolean 256 Có muốn 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 page N number 256 Lấy kết quả trang thứ mấy. Default: 0
18 size N number 256 Mỗi trang lấy bao nhiêu kết quả. Default: 10. Max 100 hóa đơn/response
19 sort N 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ự
 + asc: tăng dần
 + desc (default): giảm dần
Response
1 statusResponse array
2 statusCode string Tham khảo bảng Status code, mục V. Mã lỗi
3 errorCode string Mã lỗi. Tham khảo bảng Error code, mục V. Mã lỗi #1 và #6
4 message string Nội dung lỗi. Tham khảo bảng Error code, mục V. Mã lỗi
5 metadata array
6 page number Số thứ tự trang kết quả trả về
7 size number Số hóa đơn trong 1 trang kết quả trả về
8 total number Tổng số hóa đơn trả về
9 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
10 sort Sort theo các tiêu chí:
 + ASC: tăng dần
 + DESC (default): giảm dần
11 invoices array Danh sách hóa đơn
12 companyId string ID của công ty
13 invoiceId string ID hóa đơn
14 emailId string ID của email chứa hóa đơn
15 modelNo string Mẫu số hóa đơn
16 serial string Ký hiệu hóa đơn
17 invoiceNo string Số hóa đơn
18 sellerName string Tên công ty bán
19 sellerTaxNo string MST công ty bán
20 sellerAddress string Địa chỉ công ty bán
21 sellerPhone string Số điện thoại công ty bán
22 signedBy string Tên người ký
23 isSignValid boolean Chữ ký số có hợp lệ không
 + true: Hợp lệ
 + false: Không hợp lệ
24 signIssuerName string Tên nhà cung cấp chữ ký số cho bên bán
25 signSerialNumber string Số seri của chữ ký số
26 signValidFrom date Ngày bắt đầu có hiệu lực của chữ ký số
27 signValidTo date Ngày hết hiệu lực của chữ ký số
28 markedValidBy string Tên tài khoản đánh dấu hóa đơn hợp lệ bằng tay
29 markedValidDate string Ngày đánh dấu hóa đơn hợp lệ bằng tay
30 buyerName string Tên công ty mua
31 buyerTaxNo string MST công ty mua
32 buyerAddress string Địa chỉ công ty mua
33 subTotal number Tổng tiền trước thuế
34 grandTotal number Tổng tiền sau thuế
35 discount number Phần trăm chiết khấu
36 discountAmount number Tiền chiết khấu
37 paymentDiscount number Phần trăm chiết khấu thanh toán
38 tax array Phần trăm thuế
39 taxAmount number Tiền thuế
40 changeFees number Phụ phí (với các hóa đơn hàng không)
41 cod number Tiền phí thu hộ (với các hóa đơn hàng không)
42 status string Trạng thái tra cứu hóa đơn
 + VALID: Hợp lệ
 + INVALID: Không hợp lệ
43 receivedDate date Ngày UBot nhận hóa đơn
44 invoiceReleaseDate date Ngày phát hành hóa đơn
45 invoiceSignDate date Ngày ký hóa đơn
46 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
47 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
48 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ý
49 rawCheckingStatus string Trạng thái hóa đơn tra cứu trên TCT
50 isBuyerAddressValid boolean Địa chỉ công ty mua có hợp lệ không
 + true: Hợp lệ
 + false: Không hợp lệ
51 isBuyerNameValid boolean Tên công ty mua có hợp lệ không
 + true: Hợp lệ
 + false: Không hợp lệ
52 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ệ
53 isBuyerTaxValid boolean MST công ty mua có hợp lệ không
 + true: Hợp lệ
 + false: Không hợp lệ
54 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
55 currency string Đơn vị tiền tệ
56 downloadLink string Link tra cứu hóa đơn
57 downloadCode string Mã tra cứu hóa đơn
58 invoiceChangeTimes number Số lần hóa đơn bị sửa đổi bởi người dùng
59 invoiceLastChangedBy string Người chỉnh sửa thông tin hóa đơn cuối cùng
60 invoiceLastChangedDate date Ngày chỉnh sửa thông tin hóa đơn cuối cùng
61 invoiceLastCheckedDate date Ngày tra cứu hóa đơn gần nhất
62 po string Số PO đọc được trên hóa đơn
63 tags array Danh sách nhãn gắn với hóa đơn
64 tagId string Id của nhãn
65 tagName string Tên của nhãn
66 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
67 vendorCode string Mã nhà cung cấp
68 paymentCode string Mã thanh toán
69 invoiceItems array Danh sách chi tiết hàng hóa
70 itemId string id của hóa đơn
71 itemOrderNo string Số thứ tự của hàng hóa trong hóa đơn
72 itemCode string Mã hàng hóa map được từ matching data
73 itemCodeXml string Mã hàng hóa đọc được từ xml
74 itemName string Tên hàng hóa
75 itemPrice number Đơn giá của hàng hóa
76 itemQuantity number Số lượng của hàng hóa
77 itemUnit string Đơn vị tính
78 itemDiscount number Phần trăm chiết khấu của hàng hóa
79 itemDiscountAmount number Tiền chiết khấu của hàng hóa
80 itemTax number Thuế của hàng hóa
81 itemTaxAmount number Tiền thuế của hàng hóa
82 itemSubTotal number Tiền trước thuế của hàng hóa
83 itemGrandTotal number Tiền sau thuế của hàng hóa
84 inventoryAccount string Tài khoản kho
85 inventoryCode string Mã kho mặc định
86 expenseAccount string Tài khoản chi phí
87 taxAccount string Tài khoản thuế
88 revenueAccount string Tài khoản doanh thu
89 paymentMethod string Hình thức thanh toán
90 requestId string Mã request gửi hóa đơn sang UBot (Nếu KH gửi hóa đơn sang UBot qua API)
91 linkPDF string Link download file PDF
92 linkXML string Link download file XML
93 linkAttachment string Link download file zip chứa các tài liệu đính kèm
94 linkScreenshot string Link download file ảnh chụp tra cứu hóa đơn trên TCT
95 taxAuthorityCode string Mã cơ quan 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”,

    “getAttachments”: “True”,

    “page”: “1”,

    “size”: “100”,

    “sort”: “receivedDate “

}’
Respone mẫu

{

    “statusResponse”: {

        “statusCode”: 200,

        “errorCode”: null,

        “message”: “Success”

    },

    “metadata”: {

        “page”: 0,

        “size”: 10,

        “total”: 3586,

        “orderBy”: “createdDate”,

        “sort”: “DESC”

    },

    “data”: [

        {

            “companyId”: “98aba08d-ed4e-465b-bb9d-3bee288179”,

            “invoiceId”: “12e16d22-061e-409f-801b-b51916dc6”,

            “emailId”: “39db0aa7-a26f-4bc5-8d61-96034f427”,

            “modelNo”: “1”,

            “serial”: “C23TVP”,

            “invoiceNo”: “00000411”,

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

            “sellerTaxNo”: “2500877670”,

            “sellerAddress”: “Lô 24 – CN9, Khu Công Nghiệp Khai Quang, Phường Khai Quang, Thành phố Vĩnh Yên, Tỉnh Vĩnh Phúc, Việt Nam”,

            “sellerPhone”: null,

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

            “isSignValid”: true,

            “signIssuerName”: “BkavCA”,

            “signSerialNumber”: “5403674a04b801f29e737d9ac2885892”,

            “signValidFrom”: “2020-09-21T13:24:24Z”,

            “signValidTo”: “2024-05-10T08:03:07Z”,

            “markedValidBy”: null,

            “markedValidDate”: null,

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

            “buyerTaxNo”: “2500150543”,

            “buyerAddress”: “Phường Phúc Thắng, Thành phố Phúc Yên, Tỉnh Vĩnh Phúc, Việt Nam”,

            “subTotal”: 5112711020.00000,

            “grandTotal”: 5623982122.00000,

            “discount”: 0.00000,

            “discountAmount”: 0.00000,

            “paymentDiscount”: null,

            “tax”: 10.00000,

            “taxAmount”: 511271102.00000,

            “changeFees”: null,

            “cod”: null,

            “status”: “VALID”,

            “receivedDate”: “2023-04-13T09:22:24Z”,

            “invoiceReleaseDate”: “2023-04-11T00:00:00Z”,

            “invoiceSignDate”: “2023-04-11T07:02:44Z”,

            “isInvoiceRelease”: true,

            “isSellerActive”: true,

            “sellerActiveStatus”: “Bên bán đang hoạt động”,

            “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: Đã cấp mã hóa đơn”,

            “isBuyerAddressValid”: true,

            “isBuyerNameValid”: true,

            “isSellerSignatureValid”: true,

            “isBuyerTaxValid”: true,

            “manuallyMarkedValid”: null,

            “currency”: “VND”,

            “downloadLink”: “tchd.ehoadon.vn”,

            “downloadCode”: “M6F15672WYD”,

            “invoiceChangeTimes”: 0,

            “invoiceLastChangedBy”: null,

            “invoiceLastChangedDate”: null,

            “invoiceLastCheckedDate”: “2023-04-13T09:22:50Z”,

            “po”: null,

            “tags”: [],

            “invoiceItems”: [

                {

                    “itemId”: “609c3d18-449b-499f-a0d3-1aa8d441fac4”,

                    “invoiceId”: null,

                    “itemOrderNo”: 2,

                    “itemCode”: null,

                    “itemCodeXml”: null,

                    “itemName”: “Thân bơm nước  11361-K0R-V000”,

                    “itemUnit”: “Chiếc”,

                    “itemPrice”: 37828.00000,

                    “itemQuantity”: 10686.00000,

                    “itemDiscount”: 0.00000,

                    “itemDiscountAmount”: 0.00000,

                    “itemTax”: 10.0,

                    “itemTaxAmount”: 40423000.80000,

                    “itemSubTotal”: 404230008.00000,

                    “itemGrandTotal”: 444653008.80000,

                    “inventoryAccount”: null,

                    “inventoryCode”: null,

                    “expenseAccount”: null,

                    “taxAccount”: null,

                    “revenueAccount”: null,

                    “vendorCode”: null,

                    “paymentCode”: null,

                    “paymentMethod”: null

                }

               ],

            “invoiceType”: “INPUT_ELECTRONIC_INVOICE”,

            “paymentDate”: null,

            “paymentType”: null,

            “requestId”: null,

            “linkXml”: “https://ubots3.s3.ap-northeast-1.amazonaws.com/Xml_Processing/15659824-aa29-4591-a13e-d39e7530b0f3C23TVP-00000411-M6F15672WYD-DPH.xml?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Date=20230413T094031Z&X-Amz-SignedHeaders=host&X-Amz-Expires=300000&-Amz-Credential=AKIAUZX3YY3RFVDMJI7W%2F20230413%2Fap-northeast-1%2Fs3%2Faws4_request&X-Amz-Signature=125891e92cf5658a679ce400ee4c5cabf3f44f185e3325226fe9e16ec7e51ef7”,

            “linkPdf”: “https://ubots3.s3.ap-northeast-1.amazonaws.com/Pdf_Processing/d0997cb2-6ecd-4b91-b521-e325a64318f5C23TVP-00000411-M6F15672WYD-DPH.pdf?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Date=20230413T094031Z&X-Amz-SignedHeaders=host&X-Amz-Expires=300000&X-Amz-Credential=AKIAUZX3YY3RFVDMJI7W%2F20230413%2p-northeast-1%2Fs3%2Faws4_request&X-Amz-Signature=579b318806a2262b09143b7be3311306d2b900d54c1ed14215c8f2332f386ff1”,

            “linkScreenshot”: “https://ubots3.s3.ap-northeast-1.amazonaws.com/Screenshot/KQ_00000411_1681377768258.png?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Date=20230413T094031Z&X-Amz-SignedHeaders=host&X-Amz-Expires=300000&X-Amz-Credential=AKIAUZX3YY3RFVDMJI7W%2F20230413%2Fap-northeast-1%2Fs3%2Faws4_request&X-Amz-Signature=3ef4478468f2d9e0c1ffcd4f712107e801b2a9e2d41d685c0645e33b967c35”,

            “taxAuthorityCode”: “0058C1BD1051694BA4BF5AE884E5D5F9FB”,

            “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 Y  string 256 TransactionID của bản ghi 
2 files N pdf/xml List file (có thể gửi được nhiều file max 15 PDF & XML)
3 companyId Y  string 256 Company id UBOT gửi (UBot sẽ gửi list companyId của từng Khách hàng)
4 title N 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 N string 255 Link tra cứu
6 downloadCodeN N string 255 Mã tra cứu
7 invoiceNo N string  15 Số hóa đơn
8  sellerTaxNo N string  15 MST bên bán
9 sender Y string 400 Người gửi
Response
1 status Y string 256 Mã trạng thái đẩy file thông tin hóa đơn
2 message Y string 256 Mô tả chi tiết trạng thái (Bảng mã lỗi)

 

Request mẫu

{
    “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.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

}

 

  • 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