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:
Method | Endpoint | Mô tả |
---|---|---|
GET | /api/v1/company |
Lấy thông tin của công ty hiện tại |
PATCH | /api/v1/company/configurations |
Cập nhật cấu hình công ty |
Lấy thông tin công ty
GET /api/v1/company
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:
Admin
hoặcSuperAdmin
Yêu cầu
GET /api/v1/company
Authorization: Bearer {YOUR_ACCESS_TOKEN}
Phản hồi
{
"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
}
]
}
}
}
Giải thích các trường dữ liệu
Trường | Kiểu | Mô tả |
---|---|---|
id |
integer | ID của công ty |
full_name |
string | Tên đầy đủ của công ty |
short_name |
string | Tên viết tắt của công ty |
role |
string | Vai trò của người dùng trong công ty |
status |
string | Trạng thái của công ty (active, inactive, etc.) |
subscription |
string | Gói đăng ký của công ty |
begin_date |
string | Ngày bắt đầu gói đăng ký |
end_date |
string | Ngày kết thúc gói đăng ký |
configurations |
object | Các cấu hình của công ty |
Chi tiết trường configurations
Trường | Kiểu | Mô tả |
---|---|---|
bank_sub_account |
boolean | Cấu hình tài khoản phụ ngân hàng |
paycode |
boolean | Bật/tắt tính năng mã thanh toán |
data_storage_time |
string | Thời gian lưu trữ dữ liệu (số ngày) |
payment_code_formats |
array | Danh sách các định dạng mã thanh toán |
Chi tiết payment_code_formats
Trường | Kiểu | Mô tả |
---|---|---|
prefix |
string | Tiền tố của mã thanh toán |
suffix_from |
integer | Độ dài tối thiểu của hậu tố |
suffix_to |
integer | Độ dài tối đa của hậu tố |
character_type |
string | Loại ký tự của hậu tố (NumberOnly, NumberAndLetter) |
is_active |
boolean | Trạng thái kích hoạt của định dạng này |
Cập nhật cấu hình công ty
PATCH /api/v1/company/configurations
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:
Admin
hoặcSuperAdmin
Tham số yêu cầu
Tham số | Kiểu | Mô tả | Ràng buộc |
---|---|---|---|
payment_code_formats |
array | Danh sách các định dạng mã thanh toán | Bắt buộc nếu được gửi |
Chi tiết tham số payment_code_formats
Trường | Kiểu | Mô tả | Ràng buộc |
---|---|---|---|
prefix |
string | 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 | Độ dài tối thiểu của hậu tố | Số nguyên từ 1-30 |
suffix_to |
integer | Độ dài tối đa của hậu tố | Số nguyên từ 1-30, phải lớn hơn hoặc bằng suffix_from |
character_type |
string | Loại ký tự của hậu tố | Chỉ có thể là NumberOnly hoặc NumberAndLetter |
is_active |
integer | Trạng thái kích hoạt của định dạng này | Chỉ có thể là 0 hoặc 1 |
Yêu cầu
PATCH /api/v1/company/configurations
Content-Type: application/json
Authorization: Bearer {YOUR_ACCESS_TOKEN}
{
"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 định dạng
{
"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)"
}
}
Ví dụ sử dụng
# Lấy thông tin công ty
curl -X GET "https://my.sepay.vn/api/v1/company" \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN"
# Cập nhật cấu hình mã thanh toán
curl -X PATCH "https://my.sepay.vn/api/v1/company/configurations" \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-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
}
]
}'
<?php
$accessToken = 'YOUR_ACCESS_TOKEN';
// Hàm lấy thông tin công ty
function getCompanyInfo($accessToken) {
$ch = curl_init('https://my.sepay.vn/api/v1/company');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
'Authorization: Bearer ' . $accessToken
]);
$response = curl_exec($ch);
$httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);
if ($httpCode === 200) {
return json_decode($response, true);
} else {
return ['error' => $httpCode, 'response' => $response];
}
}
// Hàm cập nhật cấu hình công ty
function updateCompanyConfigurations($accessToken, $paymentCodeFormats) {
$ch = curl_init('https://my.sepay.vn/api/v1/company/configurations');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'PATCH');
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode([
'payment_code_formats' => $paymentCodeFormats
]));
curl_setopt($ch, CURLOPT_HTTPHEADER, [
'Authorization: Bearer ' . $accessToken,
'Content-Type: application/json'
]);
$response = curl_exec($ch);
$httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);
if ($httpCode === 200) {
return json_decode($response, true);
} else {
return ['error' => $httpCode, 'response' => $response];
}
}
// Sử dụng các hàm
$companyInfo = getCompanyInfo($accessToken);
echo "Thông tin công ty:\n";
print_r($companyInfo);
// Cập nhật cấu hình mã thanh toán
$paymentCodeFormats = [
[
'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
]
];
$updateResult = updateCompanyConfigurations($accessToken, $paymentCodeFormats);
echo "\nKết quả cập nhật:\n";
print_r($updateResult);
const accessToken = 'YOUR_ACCESS_TOKEN';
// Hàm lấy thông tin công ty
async function getCompanyInfo() {
try {
const response = await fetch('https://my.sepay.vn/api/v1/company', {
method: 'GET',
headers: {
'Authorization': `Bearer ${accessToken}`
}
});
if (!response.ok) {
throw new Error(`HTTP error! Status: ${response.status}`);
}
const data = await response.json();
return data;
} catch (error) {
console.error('Error fetching company data:', error.message);
throw error;
}
}
// Hàm cập nhật cấu hình công ty
async function updateCompanyConfigurations(paymentCodeFormats) {
try {
const response = await fetch('https://my.sepay.vn/api/v1/company/configurations', {
method: 'PATCH',
headers: {
'Authorization': `Bearer ${accessToken}`,
'Content-Type': 'application/json'
},
body: JSON.stringify({
payment_code_formats: paymentCodeFormats
})
});
if (!response.ok) {
throw new Error(`HTTP error! Status: ${response.status}`);
}
const data = await response.json();
return data;
} catch (error) {
console.error('Error updating company configurations:', error.message);
throw error;
}
}
// Sử dụng các hàm
async function manageCompany() {
try {
// Lấy thông tin công ty
const companyInfo = await getCompanyInfo();
console.log('Thông tin công ty:');
console.log(companyInfo);
// Cập nhật cấu hình mã thanh toán
const paymentCodeFormats = [
{
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
}
];
const updateResult = await updateCompanyConfigurations(paymentCodeFormats);
console.log('\nKết quả cập nhật:');
console.log(updateResult);
} catch (error) {
console.error('Error:', error);
}
}
manageCompany();
Mã lỗi
Dưới đây là các mã lỗi có thể gặp khi sử dụng API công ty:
Mã HTTP | Mô tả | Nguyên nhân |
---|---|---|
401 | Unauthorized | Access token không hợp lệ hoặc đã hết hạn |
403 | Forbidden | Không đủ quyền truy cập (không phải Admin hoặc SuperAdmin) |
400 | Bad Request | Dữ liệu gửi lên không hợp lệ (không đáp ứng các ràng buộc) |
500 | Internal Server Error | Lỗi máy chủ khi xử lý yêu cầu |