Logo
  • Support
  • Youtube
  • Facebook
  • Telegram
Logo
  • SePay OAuth2
  • Tổng quan
  • Đăng ký ứng dụng
  • Luồng xác thực
  • Access Token
  • API
  • Tài khoản ngân hàng
  • Giao dịch
  • Webhook
  • Người dùng
  • Công ty

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ặc SuperAdmin

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ặc SuperAdmin

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
API Người dùng

Quay lại API Người dùng

Facebook Messenger

Hỗ trợ live chat 24/7

Hotline

Điện thoại hỗ trợ

Youtube

Theo dõi video mới nhất của SePay

Telegram

Nhận thông tin mới nhất từ SePay
Liên hệ chúng tôi