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:

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
Authorization: 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: Admin hoặc SuperAdmin
1
2
curl -X GET "https://my.sepay.vn/api/v1/company" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"
RESPONSE
{
    "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
                }
            ]
        }
    }
}
idinteger

ID của công ty

full_namestring

Tên đầy đủ của công ty

short_namestring

Tên viết tắt của công ty

rolestring

Vai trò của người dùng trong công ty

statusstring

Trạng thái của công ty (active, inactive, v.v.)

subscriptionstring

Gói đăng ký của công ty

begin_datestring

Ngày bắt đầu gói đăng ký

end_datestring

Ngày kết thúc gói đăng ký

configurationsobject

Các cấu hình của công ty

Cập nhật cấu hình công ty

PATCH
/api/v1/company/configurations
Authorization: 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: Admin hoặc SuperAdmin

Tham số yêu cầu:

payment_code_formatsarrayrequired
Danh sách các định dạng mã thanh toán

Chi tiết payment_code_formats:

Tham sốKiểuBắt buộcMô tả
prefixstringCóTiền tố của mã thanh toán. Chỉ chứa chữ cái, độ dài từ 2–3 ký tự
suffix_fromintegerCóĐộ dài tối thiểu của hậu tố. Là số nguyên từ 1–30
suffix_tointegerCóĐộ 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_typestringCóLoại ký tự của hậu tố. Chỉ có thể là NumberOnly hoặc NumberAndLetter
is_activeintegerCóTrạng thái kích hoạt của định dạng này. Chỉ có thể là 0 hoặc 1
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
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:

RESPONSE
{
    "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:

RESPONSE
{
  "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:

401Unauthorized

Access token không hợp lệ hoặc đã hết hạn

403Forbidden

Không đủ quyền truy cập (không phải Admin hoặc SuperAdmin)

400Bad Request

Dữ liệu gửi lên không hợp lệ (không đáp ứng các ràng buộc)

500Internal Server Error

Lỗi máy chủ khi xử lý yêu cầu

Trước
—
Tiếp theo
—