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

bash

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}

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

Tên	Loại	Bắt buộc	Mô tả
`payment_code_formats`	array	Bắt buộc	Danh sách các định dạng mã thanh toán (bắt buộc nếu được gửi)

bash

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:

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	—