Giới thiệu Open API

TConnect Open API là bộ API mở cho phép đối tác tích hợp các dịch vụ của TConnect vào hệ thống của mình. Tất cả API dùng chung một cơ chế xác thực qua API Gateway và tuân theo các quy ước chung bên dưới.

Danh mục API

Nhóm API	Mô tả	Tài liệu
Tra cứu hóa đơn đầu vào	Lấy hộ hóa đơn mua vào của doanh nghiệp từ cổng thuế (Tổng cục Thuế): đăng ký tài khoản, đồng bộ, truy xuất, đối soát.	Xem chi tiết →
Tra cứu mã số thuế	Tra thông tin doanh nghiệp theo MST (tên, địa chỉ, cơ quan thuế, người đại diện…). Không cần mã hóa, tính phí theo request.	Xem chi tiết →

Xác thực

TConnect Open API dùng chung một cơ chế xác thực cho tất cả nhóm API: JWT Bearer token do Keycloak cấp (giống API Thanh toán).

1. Gọi POST /openapi/v1/auth/login (header Partner-Code, body mã hóa AES-256-CBC chứa username/password/client_id/client_secret) → nhận access_token.
2. Thêm vào mọi request:

Authorization: Bearer <access_token>
Partner-Code: <mã Merchant TConnect cấp>

Chi tiết cơ chế + mã hóa AES: xem Xác thực (Mã hóa AES). Token hết hạn thì gọi /openapi/v1/auth/refresh-token để lấy mới.

Môi trường

Môi trường	Base URL
Staging	https://sme-open-api-sandbox.tconnect.vn
Production	Được cung cấp sau khi hoàn tất kiểm thử

Quy ước chung

• Định danh tài nguyên (ví dụ accountId, invoiceId) là UUID.
• Ngày theo giờ Việt Nam (UTC+7), định dạng YYYY-MM-DD.
• Lỗi trả về chuẩn HTTP: 400 (dữ liệu sai / sai định dạng), 404 (không tìm thấy), 401/403 (xác thực / không có quyền).
• Body dạng JSON (Content-Type: application/json).