Tạo giao dịch

Mở một giao dịch NFC và trả về JWT token mà Mobile SDK dùng để xác thực lần đọc chip của nó. Đây là lệnh gọi đầu tiên trong mọi phiên NFC.

Endpoint

POST /v1/create_transaction
Content-Type: application/json

{
  "document_id": "001xxxxxxxxx",
  "ref_id": "ref_00000001"
}

Tham số:

Tham số	Kiểu	Bắt buộc	Mặc định	Mô tả
document_id	string	Có	—	Document ID — số CCCD/CMND của công dân. Độ dài tối đa 64.
ref_id	string	Có	—	ID tham chiếu giao dịch do bạn tạo và quản lý. Độ dài tối đa 64.

Trả về: CreateTransactionResponse

Xác thực lệnh gọi này bằng HMAC — xem Tổng quan § Xác thực.

Ví dụ request

curl --location '<BASE_URL>/v1/create_transaction' \
  --header 'Authorization: ATV <ACCESS_ID>:<SIGNATURE>' \
  --header 'X-TV-Timestamp: <TIMESTAMP>' \
  --header 'Content-Type: application/json' \
  --data '{
    "document_id": "001xxxxxxxxx",
    "ref_id": "ref_00000001"
  }'

Response

{
  "success": true,
  "code": 0,
  "message": "success",
  "request_id": "133963a4-3d2c-4a85-b0a1-3fa2878b8f99",
  "data": {
    "id": "4b1f99a2-7569-4fde-b65a-1260794cb9c6",
    "ref_id": "ref_00000001",
    "document_id": "001xxxxxxxxx",
    "status": "NOT_VERIFIED",
    "token": "<JWT_TOKEN>"
  }
}

Trường	Kiểu	Mô tả
code	int	Mã lỗi — 0 nghĩa là không có lỗi. Độ dài tối đa 10.
request_id	string	ID request của server, dùng để tracing. Độ dài tối đa 64.
data.id	string	ID duy nhất của giao dịch. Độ dài tối đa 64.
data.ref_id	string	ID tham chiếu giao dịch bạn đã cung cấp. Độ dài tối đa 64.
data.document_id	string	Document ID. Độ dài tối đa 64.
data.status	string	Trạng thái giao dịch: NOT_VERIFIED, VERIFIED hoặc EXPIRED. Độ dài tối đa 32.
data.token	string	Token riêng cho giao dịch này, dùng để Mobile SDK xác thực với server. Độ dài tối đa 1000.

WARNING

token chỉ có hiệu lực trong phạm vi một giao dịch và sẽ hết hạn. Hãy chuyển nó thẳng cho SDK qua kênh xác thực riêng của bạn, không bao giờ ghi log, và tạo một giao dịch mới thay vì dùng lại một token cũ.

Lỗi

Mã	Mô tả
2001010	API key không đúng.
2001020	Lock giao dịch thất bại.
2001021	Request giao dịch không hợp lệ.
2001022	Giao dịch đã được xác minh.
2001023	Khóa giao dịch không hợp lệ.

Mã	Mô tả
401	Bạn không được phép thực hiện hành động này.
500	Xảy ra lỗi không mong đợi trong quá trình xử lý request.

Bước tiếp theo

• Đọc NFC — lệnh gọi tiếp theo của SDK, dùng token được trả về ở đây
• Tổng quan — trạng thái giao dịch thay đổi thế nào xuyên suốt luồng