Tải ảnh lên

Tải một ảnh lên eKYC và trả về một image_id. Đây là bước đầu tiên bắt buộc cho mọi service khác — mọi API downstream đều nhận một image_id thay vì dữ liệu ảnh thô.

Endpoint

POST /v1/images
Content-Type: multipart/form-data

Tham số:

Tham số	Kiểu	Bắt buộc	Mặc định	Mô tả
file	file	Có	—	File ảnh cần tải lên. JPG hoặc PNG, tối đa 15MB.
label	string	Có	—	Nhãn của ảnh. Phải là một trong các giá trị trong Khuyến nghị sử dụng.
metadata	string_json	Không	{}	Chuỗi JSON của các cặp key/value. Key là string; value là string, int, float hoặc bool. Ví dụ: {"id":"<ID>","type":1}

Trả về: UploadImageResponse

Dùng portrait cho một ảnh selfie chụp bằng camera và portrait_nfc cho một ảnh chân dung đọc từ chip NFC.

Ví dụ request

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

Response

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

Trường	Kiểu	Mô tả
data.image_id	string	UUID của ảnh đã tải lên trong StoreDB. Truyền giá trị này cho mọi API khác.
errors	array	Chi tiết từng lỗi. Rỗng khi thành công.
success	bool	Cuộc gọi có thành công hay không.
code	int	status code dạng số — 0 khi thành công.
message	string	Thông báo trạng thái.

Khi thành công, HTTP status là 200. Chỉ riêng HTTP 200 là chưa đủ — hãy kiểm tra success và data.status trước khi coi việc tải lên đã hoàn tất.

Lỗi

Khi success là false, một trong các mã số sau sẽ được trả về:

Mã	Thông báo
2001010	Không tìm thấy Access ID.
2001014	Vượt giới hạn tốc độ đăng ký.
2001015	Vượt giới hạn brute-force khi đăng ký.
401100	Bạn không được phép thực hiện hành động này.
4001000	Tham số đầu vào vi phạm một ràng buộc.
4001001	Header X-TV-Timestamp đã hết hạn, cần một cái mới hơn.
4041001	Không tìm thấy người dùng.
4091000	cus_user_id đã được đăng ký.
4291000	Số lượng request vượt quá giới hạn throughput của bạn.
5001000	Xảy ra lỗi không mong đợi trong quá trình xử lý request.

Mảng errors mang một hoặc nhiều mã lỗi chi tiết:

Mã	Mô tả
invalid_parameter_exception	Tham số đầu vào vi phạm một ràng buộc.
request_time_too_skewed	Header X-TV-Timestamp đã hết hạn, cần một cái mới hơn.
access_denied_exception	Bạn không được phép thực hiện hành động này.
image_not_found_exception	Không tìm thấy image ID trong DB.
image_too_large_exception	Kích thước ảnh đầu vào vượt quá giới hạn cho phép (15MB).
invalid_image_format_exception	Định dạng ảnh được cung cấp không được hỗ trợ (JPG/PNG).
rate_limit_exception	Số lượng request vượt quá giới hạn throughput của bạn.
internal_server_error	Xảy ra lỗi không mong đợi trong quá trình xử lý request.

Bước tiếp theo

• Khuyến nghị sử dụng — toàn bộ bộ từ vựng nhãn và loại thẻ
• Xác minh sanity thẻ ID — chạy bước này trước bất kỳ lệnh gọi thẻ ID nào khác
• Xác minh sanity khuôn mặt — chạy bước này trước bất kỳ lệnh gọi khuôn mặt nào khác