API Công ty
Tài liệu về cách sử dụng API công ty thông qua OAuth2 trong SePay.
Giới thiệu
API công ty của SePay cho phép bạn truy cập thông tin về công ty hiện tại và cấu hình của công ty. API này chỉ dành cho người dùng có vai trò Admin hoặc SuperAdmin trong công ty.
Để sử dụng API này, bạn cần có quyền company trong phạm vi (scope) của Access Token và phải là người dùng với vai trò Admin hoặc SuperAdmin.
Các Endpoints
API công ty cung cấp các endpoints sau:
/api/v1/companyLấy thông tin của công ty hiện tại
/api/v1/company/configurationsCập nhật cấu hình công ty
Lấy thông tin công ty
/api/v1/companyAuthorization: Bearer {YOUR_ACCESS_TOKEN}
Endpoint này trả về thông tin của công ty hiện tại và các cấu hình liên quan.
Quyền yêu cầu:
- Scope:
company - Vai trò người dùng:
AdminhoặcSuperAdmin
curl -X GET "https://my.sepay.vn/api/v1/company" \-H "Authorization: Bearer YOUR_ACCESS_TOKEN"
{
"status": "success",
"data": {
"id": 123,
"full_name": "Công ty TNHH Một Thành Viên ABC",
"short_name": "ABC Corp",
"role": "Admin",
"status": "active",
"subscription": "Premium",
"begin_date": "2023-01-01",
"end_date": "2023-12-31",
"configurations": {
"bank_sub_account": true,
"paycode": true,
"data_storage_time": "90",
"payment_code_formats": [
{
"prefix": "DH",
"suffix_from": 6,
"suffix_to": 8,
"character_type": "NumberOnly",
"is_active": true
},
{
"prefix": "HD",
"suffix_from": 4,
"suffix_to": 6,
"character_type": "NumberAndLetter",
"is_active": true
}
]
}
}
}idintegerID của công ty
full_namestringTên đầy đủ của công ty
short_namestringTên viết tắt của công ty
rolestringVai trò của người dùng trong công ty
statusstringTrạng thái của công ty (active, inactive, v.v.)
subscriptionstringGói đăng ký của công ty
begin_datestringNgày bắt đầu gói đăng ký
end_datestringNgày kết thúc gói đăng ký
configurationsobjectCác cấu hình của công ty
Cập nhật cấu hình công ty
/api/v1/company/configurationsAuthorization: Bearer {YOUR_ACCESS_TOKEN}
Content-Type: application/json
Endpoint này cho phép cập nhật cấu hình của công ty, đặc biệt là cấu trúc mã thanh toán.
Quyền yêu cầu:
- Scope:
company - Vai trò người dùng:
AdminhoặcSuperAdmin
Tham số yêu cầu:
Chi tiết payment_code_formats:
| Tham số | Kiểu | Bắt buộc | Mô tả |
|---|---|---|---|
prefix | string | Có | Tiền tố của mã thanh toán. Chỉ chứa chữ cái, độ dài từ 2–3 ký tự |
suffix_from | integer | Có | Độ dài tối thiểu của hậu tố. Là số nguyên từ 1–30 |
suffix_to | integer | Có | Độ dài tối đa của hậu tố. Là số nguyên từ 1–30, phải lớn hơn hoặc bằng suffix_from |
character_type | string | Có | Loại ký tự của hậu tố. Chỉ có thể là NumberOnly hoặc NumberAndLetter |
is_active | integer | Có | Trạng thái kích hoạt của định dạng này. Chỉ có thể là 0 hoặc 1 |
curl -X PATCH "https://my.sepay.vn/api/v1/company/configurations" \-H "Content-Type: application/json" \-H "Authorization: Bearer YOUR_ACCESS_TOKEN" \-d '{"payment_code_formats": [{"prefix": "DH","suffix_from": 6,"suffix_to": 8,"character_type": "NumberOnly","is_active": 1},{"prefix": "HD","suffix_from": 4,"suffix_to": 6,"character_type": "NumberAndLetter","is_active": 1}]}'
Phản hồi thành công:
{
"status": "success",
"data": {
"status": true,
"data": {
"bank_sub_account": true,
"paycode": true,
"data_storage_time": "90",
"payment_code_formats": [
{
"prefix": "DH",
"suffix_from": 6,
"suffix_to": 8,
"character_type": "NumberOnly",
"is_active": true
},
{
"prefix": "HD",
"suffix_from": 4,
"suffix_to": 6,
"character_type": "NumberAndLetter",
"is_active": true
}
]
}
}
}Phản hồi lỗi:
{
"status": "success",
"data": {
"status": false,
"message": "Hậu tố mã thanh toán từ phải nhỏ hơn hoặc bằng hậu tố mã thanh toán đến (Cấu trúc mã thanh toán 1)"
}
}Mã lỗi
Dưới đây là các mã lỗi có thể gặp khi sử dụng API công ty:
401UnauthorizedAccess token không hợp lệ hoặc đã hết hạn
403ForbiddenKhông đủ quyền truy cập (không phải Admin hoặc SuperAdmin)
400Bad RequestDữ liệu gửi lên không hợp lệ (không đáp ứng các ràng buộc)
500Internal Server ErrorLỗi máy chủ khi xử lý yêu cầu