Khuyến nghị sử dụng

Các quy ước áp dụng cho mọi endpoint của FaceAuthen: cách gửi request để đối chiếu được với CAKE, và các bộ từ vựng cố định cho nhãn ảnh và loại thẻ mà các API kiểm tra theo đó.

Đối chiếu API

Để việc đối chiếu giữa hệ thống của bạn và service của CAKE trở nên đơn giản, hãy gửi một header X-Request-Id trên mỗi lệnh gọi.

Thông tin	Mô tả
X-Request-Id	Một định danh request do client tạo. Bạn tạo và quản lý giá trị của nó; CAKE lưu lại giá trị đã nhận để cả hai bên có thể đối chiếu và phát hiện sai lệch.

Dùng một UUID ngẫu nhiên, không trùng lặp cho mỗi request (ghi là <RANDOM_UUID> trong các ví dụ). Không đưa user ID hay bất kỳ dữ liệu cá nhân nào vào giá trị này — nó được lưu và ghi log ở cả hai phía. Nếu cần đối chiếu theo từng người dùng, hãy tự lưu ánh xạ từ UUID sang người dùng ở phía bạn.

Sử dụng image ID đã tải lên

Hãy tải mỗi ảnh lên một lần qua Tải ảnh lên và truyền image_id được trả về cho mọi API khác, thay vì gửi lại dữ liệu base64 ở mỗi lệnh gọi. Điều này giữ cho request nhỏ gọn, tránh lưu trữ trùng lặp, và cho phép CAKE đối chiếu mọi kiểm tra được thực hiện trên cùng một ảnh.

Nhãn ảnh

Trường label PHẢI là một trong các giá trị sau.

Nhãn	Mô tả
portrait	Ảnh chân dung (selfie)
portrait_nfc	Ảnh chân dung đọc từ chip NFC
qr_code	Ảnh mã QR
id_card.vn.national_id.front	Mặt trước của một thẻ Việt Nam (CMND cũ/mới, CCCD, Hộ chiếu)
id_card.vn.national_id.back	Mặt sau của một thẻ Việt Nam (CMND cũ/mới, CCCD, Hộ chiếu)
doc.vn.business_license	Ảnh giấy phép kinh doanh

Loại thẻ

Trường card_type PHẢI là một trong các giá trị sau.

Loại thẻ	Mô tả
vn.cccd_new	Căn cước công dân
vn.cc_new	Căn cước
vn.other	Không khớp với bất kỳ loại nào đã định nghĩa

INFO

Các sample request xuyên suốt tài liệu này dùng card_type: "vn.national_id". Hãy xác nhận bộ loại thẻ chính xác được bật cho tenant của bạn với CAKE Support trước khi go-live.

Metadata ảnh

Một số endpoint chấp nhận trường metadata trên một ảnh. Đây là một chuỗi JSON chứa một dictionary key/value phẳng, trong đó key là string và value là string, int, float hoặc bool.

"{\"id\":\"<ID>\",\"type\":1}"

Đối với một ảnh mã QR, metadata có thể mang chuỗi đã giải mã thô:

"{\"raw\":\"<decoded QR content>\"}"

Khi một request chấp nhận một object ảnh, hãy cung cấp hoặc id hoặc base64:

• Nếu bạn truyền base64, hãy truyền thêm label và metadata, và bỏ qua id.
• Nếu bạn truyền id (được trả về bởi Tải ảnh lên), hãy bỏ qua base64, label và metadata.

Bước tiếp theo

• Tải ảnh lên — lấy image_id mà các quy ước này phụ thuộc vào
• Tổng quan FaceAuthen — xác thực, cấu trúc response và luồng xử lý đầu-cuối