Bắt đầu trong 10 phút

Có hai lộ trình, tuỳ kiểu ứng dụng bạn chọn ở bước 1. Bước 1–2 giống nhau.

Bạn là	Chọn	Đi tiếp
doanh nghiệp nối hệ thống của chính mình (POS, ERP, máy chấm công)	Nội bộ	Lộ trình A
nhà cung cấp phần mềm có nhiều khách hàng dùng CTAS Work	Nền tảng	Lộ trình B

1. Tạo ứng dụng

Đăng nhập developer.ctas.vn bằng tài khoản CTAS. Tài khoản phải là quản trị viên của một tổ chức ở gói có API. Bấm Tạo ứng dụng, chọn tổ chức sở hữu, kiểu Nội bộ hoặc Nền tảng, tên, và những quyền truy cập ứng dụng sẽ xin.

Bạn làm tích hợp thuê cho một doanh nghiệp? Không cần là nhân viên của họ. Quản trị viên của họ tạo ứng dụng rồi mời email của bạn ở Cài đặt › Thành viên với vai trò *Lập trình viên*; bạn đăng nhập bằng đúng email đó và bấm Tham gia. Lập trình viên dùng được khoá Thử nghiệm, tổ chức thử nghiệm, webhook và nhật ký; khoá Chính thức và phát hành chỉ chủ sở hữu làm.

Ứng dụng có sẵn một tổ chức thử nghiệm với 3 phòng ban và 12 nhân sự giả. Bạn là quản trị viên của tổ chức đó.

2. Tạo khoá bí mật Thử nghiệm

Trang ứng dụng › mục Khoá API, công tắc môi trường ở góc trên để ở Thử nghiệm › Tạo khoá bí mật. Bạn có:

Client ID, bắt đầu bằng ctas_ci_test_, luôn hiện trên thẻ;
khoá bí mật, bắt đầu bằng ctas_cs_test_, chỉ hiện một lần ngay dưới nút tạo. Lưu lại trước khi đóng.

Đừng nhầm Client ID với mã ứng dụng (dạng ADT-JWT-ORW, in ở đầu trang). Mã ứng dụng là thứ tổ chức khách hàng gõ để tìm ứng dụng của bạn; nó không dùng để lấy token.

Lộ trình A: ứng dụng nội bộ

A3. Lấy token

Ứng dụng nội bộ đã được kết nối sẵn với tổ chức thử nghiệm, nên chỉ cần Client ID và khoá bí mật:

curlNode.jsPHP

curl -X POST https://api.ctas.vn/api/developer/oauth/token \
  -H "Content-Type: application/json" \
  -d '{
    "grant_type": "client_credentials",
    "client_id": "ctas_ci_test_…",
    "client_secret": "ctas_cs_test_…"
  }'

const response = await fetch('https://api.ctas.vn/api/developer/oauth/token', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    grant_type: 'client_credentials',
    client_id: process.env.CTAS_CLIENT_ID,
    client_secret: process.env.CTAS_CLIENT_SECRET,
  }),
})
const { access_token } = await response.json()

$response = (new \GuzzleHttp\Client())->post('https://api.ctas.vn/api/developer/oauth/token', [
    'json' => [
        'grant_type' => 'client_credentials',
        'client_id' => getenv('CTAS_CLIENT_ID'),
        'client_secret' => getenv('CTAS_CLIENT_SECRET'),
    ],
]);
$accessToken = json_decode((string) $response->getBody(), true)['access_token'];

{
  "access_token": "ctas_at_…",
  "token_type": "Bearer",
  "expires_in": 3600,
  "scope": "organization:read members:read",
  "connection": { "id": "con_…", "organization_id": "org_…", "environment": "test" }
}

A4. Gọi thử

curlNode.jsPHP

curl https://api.ctas.vn/api/developer/v1/work/organization \
  -H "Authorization: Bearer ctas_at_…"

const organization = await fetch('https://api.ctas.vn/api/developer/v1/work/organization', {
  headers: { Authorization: `Bearer ${access_token}` },
}).then(r => r.json())

$organization = json_decode((string) (new \GuzzleHttp\Client())
    ->get('https://api.ctas.vn/api/developer/v1/work/organization', [
        'headers' => ['Authorization' => "Bearer {$accessToken}"],
    ])->getBody(), true);

Token sống 1 giờ; hết hạn thì gọi lại client_credentials.

A5. Chạy thật

Khi đã chạy ổn trên tổ chức thử nghiệm:

Chủ sở hữu ứng dụng gạt công tắc sang Chính thức, vào mục Kết nối, bấm Kết nối để nối tổ chức của mình.
Tạo khoá bí mật ở mục Khoá API (vẫn ở Chính thức).
client_credentials bằng khoá Chính thức trả token của tổ chức thật, như bước A3.

Trang Tổng quan của ứng dụng đánh dấu từng bước khi nó xong.

Lộ trình B: ứng dụng nền tảng

Ứng dụng nền tảng đọc dữ liệu bằng token của từng kết nối: mỗi tổ chức khách hàng cho phép riêng. Bạn tập trước với tổ chức thử nghiệm.

B3. Lấy mã kết nối của tổ chức thử nghiệm

Trang ứng dụng › mục Tổ chức thử nghiệm › Tạo mã kết nối. Bạn nhận mã dạng K7M2-QD4X-RN8P, hiệu lực 10 phút, dùng một lần, kèm sẵn lệnh đổi mã ở bước B4.

Với khách hàng thật, chính quản trị viên của họ tạo mã này trong ứng dụng CTAS Work › tab Tổ chức › Ứng dụng đã kết nối › Kết nối ứng dụng, rồi dán vào phần mềm của bạn. Bạn cũng làm được đúng như vậy với tổ chức thử nghiệm: đổi sang nó trong CTAS Work trên điện thoại.

B4. Đổi mã lấy token

curlNode.jsPHP

curl -X POST https://api.ctas.vn/api/developer/oauth/token \
  -H "Content-Type: application/json" \
  -d '{
    "grant_type": "urn:ctas:params:oauth:grant-type:connection_code",
    "code": "K7M2-QD4X-RN8P",
    "client_id": "ctas_ci_test_…",
    "client_secret": "ctas_cs_test_…"
  }'

// `code` là mã quản trị viên của khách dán vào phần mềm của bạn.
const tokens = await fetch('https://api.ctas.vn/api/developer/oauth/token', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    grant_type: 'urn:ctas:params:oauth:grant-type:connection_code',
    code,
    client_id: process.env.CTAS_CLIENT_ID,
    client_secret: process.env.CTAS_CLIENT_SECRET,
  }),
}).then(r => r.json())
// Lưu tokens.access_token, tokens.refresh_token theo tokens.connection.id

// $code là mã quản trị viên của khách dán vào phần mềm của bạn.
$tokens = json_decode((string) (new \GuzzleHttp\Client())
    ->post('https://api.ctas.vn/api/developer/oauth/token', [
        'json' => [
            'grant_type' => 'urn:ctas:params:oauth:grant-type:connection_code',
            'code' => $code,
            'client_id' => getenv('CTAS_CLIENT_ID'),
            'client_secret' => getenv('CTAS_CLIENT_SECRET'),
        ],
    ])->getBody(), true);
// Lưu $tokens['access_token'], $tokens['refresh_token'] theo $tokens['connection']['id']

{
  "access_token": "ctas_at_…",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_token": "ctas_rt_…",
  "scope": "organization:read members:read identity:write",
  "connection": { "id": "con_…", "organization_id": "org_…", "environment": "test" }
}

Lưu cả hai token, gắn với connection.id. Kết nối mới hiện ở mục Kết nối của trang ứng dụng; mục Tổ chức thử nghiệm có thêm nút Lấy token thử để gọi API bằng tay.

B5. Gọi thử

curl https://api.ctas.vn/api/developer/v1/work/organization \
  -H "Authorization: Bearer ctas_at_…"

Hết hạn thì làm mới bằng refresh_token, xem Vòng đời token.

B6. Phát hành

Trước khi được duyệt, ứng dụng nền tảng chỉ kết nối được tổ chức của bạn và tổ chức thử nghiệm. Nộp duyệt ở mục Phát hành, xem Thử nghiệm và phát hành.

Gọi thử không cần viết mã

Trang Tham chiếu API có khung Thử ngay cho từng endpoint. Đăng nhập rồi chọn ứng dụng, khung này tự gắn token của tổ chức thử nghiệm.

Xác thực và kết nối: token sống bao lâu, làm mới thế nào, tổ chức khách hàng kết nối ra sao.
Webhooks và sự kiện: nhận thông báo khi dữ liệu thay đổi.
Quy ước: mã định danh, phân trang, lỗi, giới hạn.

Bắt đầu trong 10 phút

1. Tạo ứng dụng

2. Tạo khoá bí mật Thử nghiệm

Lộ trình A: ứng dụng nội bộ

A3. Lấy token

A4. Gọi thử

A5. Chạy thật

Lộ trình B: ứng dụng nền tảng

B3. Lấy mã kết nối của tổ chức thử nghiệm

B4. Đổi mã lấy token

B5. Gọi thử

B6. Phát hành

Gọi thử không cần viết mã

Tiếp theo