Bắt đầu nhanh

Chạy phiên eKYC đầu tiên của bạn trong khoảng 10 phút bằng cURL và những ảnh bạn đã có sẵn. Trang này bỏ qua các SDK và mọi tùy chọn nâng cao — đọc Tổng quan khi bạn cần bức tranh đầy đủ.

Những gì bạn cần

Thông tin	Mô tả
Access ID + Access Key	Liên hệ CAKE Support để lấy.
Base URL	Do CAKE cấp cùng bộ credentials, cho cả môi trường stage và production.
Ba ảnh test	Mặt trước CCCD, mặt sau CCCD, và một ảnh selfie. JPG hoặc PNG, dưới 15MB.
Một bộ ký HMAC	Mọi request đều phải được ký. Dùng script bên dưới.

Bước 0 — Ký request

Mọi lệnh gọi đều cần header Authorization và X-TV-Timestamp. Đoạn code này tạo ra cả hai:

const CryptoJS = require("crypto-js");

const ACCESS_ID  = "<ACCESS_ID>";
const ACCESS_KEY = "<ACCESS_KEY>";

function sign(method, path, body) {
  const timestamp = new Date().toISOString();
  const hashedBody = CryptoJS.SHA256(body).toString(CryptoJS.enc.Hex);
  const stringToSign = `${method}\n${path}\n${timestamp}\n${hashedBody}`;
  const hmac = CryptoJS.HmacSHA256(stringToSign, ACCESS_KEY);
  const signature = CryptoJS.enc.Base64.stringify(
    CryptoJS.enc.Hex.parse(hmac.toString(CryptoJS.enc.Hex))
  );
  return {
    "X-TV-Timestamp": timestamp,
    "Authorization": `ATV ${ACCESS_ID}:${signature}`,
  };
}

Thuật toán đầy đủ nằm ở Tổng quan § Xác thực.

Bước 1 — Tải ảnh lên

Tải mỗi ảnh lên một lần và nhận về một image_id. Mọi lệnh gọi sau đó dùng ID này thay vì dữ liệu ảnh gốc.

curl -X POST '<BASE_URL>/v1/images' \
  -H 'Authorization: ATV <ACCESS_ID>:<SIGNATURE>' \
  -H 'X-TV-Timestamp: <TIMESTAMP>' \
  -F 'file=@"nid-front.jpg"' \
  -F 'label="id_card.vn.national_id.front"'

{ "data": { "image_id": "20b457d2-cf11-4c2b-a491-8137ae6b0bc8" }, "success": true, "code": 0 }

Lặp lại cho mặt sau (id_card.vn.national_id.back) và ảnh selfie (portrait). Giữ lại cả ba image ID.

→ Tải ảnh lên

Bước 2 — Kiểm tra chất lượng ảnh thẻ

Luôn chạy bước này trước tiên. Một ảnh bị mờ hoặc lóa sẽ làm sai lệch mọi kiểm tra tiếp theo.

curl -X POST '<BASE_URL>/v1/verify_id_card_sanity_sync' \
  -H 'Authorization: ATV <ACCESS_ID>:<SIGNATURE>' \
  -H 'X-TV-Timestamp: <TIMESTAMP>' \
  -H 'Content-Type: application/json' \
  -d '{
    "card_type": "vn.national_id",
    "image1": { "id": "<FRONT_IMAGE_ID>" },
    "image2": { "id": "<BACK_IMAGE_ID>" }
  }'

{ "data": { "card_sanity": { "verdict": "good", "score": 1 }, "status": "success" } }

Bất kỳ giá trị nào khác good nghĩa là người dùng phải chụp lại ảnh — tra cứu verdict tại Định nghĩa kết luận.

→ Xác minh ID Card Sanity

Bước 3 — Đọc thông tin thẻ

curl -X POST '<BASE_URL>/v1/read_id_card_info_sync' \
  -H 'Authorization: ATV <ACCESS_ID>:<SIGNATURE>' \
  -H 'X-TV-Timestamp: <TIMESTAMP>' \
  -H 'Content-Type: application/json' \
  -d '{
    "card_type": "vn.national_id",
    "image1": { "id": "<FRONT_IMAGE_ID>" }
  }'

Response mang theo card_information — một mảng các trường, mỗi trường có một điểm độ tin cậy.

→ Đọc thông tin thẻ ID

Bước 4 — So khớp khuôn mặt

So sánh ảnh selfie với ảnh chân dung in trên thẻ.

curl -X POST '<BASE_URL>/v1/compare_faces_sync' \
  -H 'Authorization: ATV <ACCESS_ID>:<SIGNATURE>' \
  -H 'X-TV-Timestamp: <TIMESTAMP>' \
  -H 'Content-Type: application/json' \
  -d '{
    "image1": { "id": "<SELFIE_IMAGE_ID>" },
    "image2": { "id": "<FRONT_IMAGE_ID>" }
  }'

{
  "data": {
    "compare_faces": [
      { "result": "matched", "score": 0.95 }
    ],
    "status": "success"
  }
}

→ So sánh khuôn mặt

Vậy là xong phần cốt lõi

Bạn vừa chạy xong xương sống của một phiên eKYC: tải lên → kiểm tra chất lượng → đọc thẻ → so khớp khuôn mặt.

WARNING

Luồng này chưa sẵn sàng cho production. Nó còn thiếu ít nhất là phát hiện giả mạo thẻ, kiểm tra liveness của selfie, và kiểm tra trùng lặp. Xem Onboard một khách hàng mới để biết luồng đầy đủ.

Bước tiếp theo

• Onboard một khách hàng mới — luồng sẵn sàng cho production
• Chọn phương thức tích hợp — API, Mobile SDK hay Web SDK
• Kiểm thử — chạy luồng mà không cần camera thật
• Tổng quan — kiến trúc, xác thực, ký response