Xác nhận bằng mã QR

Bài toán

POS hay máy tính tại cửa hàng cần biết *ai* đang thao tác, nhưng không ai muốn quản lý thêm một bộ mật khẩu cho từng nhân viên. Nhân viên đã có ứng dụng CTAS Work để chấm công. Hãy để họ quét thay vì đăng nhập.

Luồng

Máy chủ của bạn, bằng token kết nối của tổ chức đó, tạo một yêu cầu xác nhận và nhận về qr_text.
Bạn hiện qr_text dưới dạng mã QR.
Nhân viên mở CTAS Work › Tổng quan › QR Code và quét. Trên iPhone, quét bằng máy ảnh cũng mở thẳng ứng dụng.
Ứng dụng hiện tên tổ chức, tên ứng dụng của bạn và thứ sẽ chia sẻ: chỉ mã nhân sự. Nhân viên bấm Đồng ý.
Bạn nhận webhook identity.confirmed, hoặc hỏi GET /identity-requests/{id}.

Tạo yêu cầu

POST /identity-requests — quyền identity:write

{ "reference": "TERMINAL-01", "ttl_seconds": 300,
  "constraints": { "department_ids": ["dep_2Hs8…"] } }

{ "data": { "id": "idr_Tt9…", "reference": "TERMINAL-01", "status": "pending",
            "qr_text": "https://developer.ctas.vn/i/8fJ2kQ…",
            "expires_at": "2026-09-06T09:05:00+07:00" } }

Trường	Ghi chú
`reference`	chuỗi của bạn, tối đa 120 ký tự, trả lại nguyên vẹn trong webhook
`ttl_seconds`	30 đến 900, mặc định 300
`constraints.department_ids`	chỉ nhân sự thuộc các phòng ban này quét được
`constraints.member_ids`	chỉ đúng những người này
không ràng buộc	mọi nhân sự đang hoạt động của tổ chức

Mỗi kết nối giữ tối đa 200 yêu cầu đang chờ. Vượt thì nhận 429 TOO_MANY_PENDING.

Theo dõi

GET /identity-requests/{id} · POST /identity-requests/{id}/cancel

status đi từ pending sang confirmed, declined, expired hoặc canceled. Khi confirmed có thêm member_id, department_id, confirmed_at.

Webhook `identity.confirmed`

{ "id": "evt_01J9…", "type": "identity.confirmed", "api_version": "2026-09-01",
  "created_at": "2026-09-06T09:01:12+07:00",
  "connection_id": "con_…", "organization_id": "org_…",
  "data": { "identity_request_id": "idr_Tt9…", "reference": "TERMINAL-01",
            "member_id": "mem_Kd7p…", "department_id": "dep_2Hs8…",
            "confirmed_at": "2026-09-06T09:01:12+07:00" } }

Dữ liệu chỉ có mã nhân sự. Cần tên để hiện trên màn hình? Gọi GET /members/{member_id} với quyền members:read.

Những gì không xảy ra

Quét không chấm công.
Người ngoài tổ chức, hoặc không thuộc constraints, thấy "Mã này không dành cho bạn" và không biết mã của tổ chức nào.
Một mã dùng đúng một lần.
Hiện chỉ ứng dụng iOS hỗ trợ quét. Android sẽ có sau.