Skip to main content

​
Khởi tạo phiên ký

Bắt đầu quá trình ký số cho một bên ký trên hợp đồng. 
POST /api/signing/initiate
Content-Type: application/json
Body: 
{
  "contractId": "ctr_abc123",
  "signerEmail": "nguyen@example.com",
  "signingMethod": "usb_token"
}
signingMethodMô tả
usb_tokenKý bằng USB Token vật lý
cloud_hsmKý bằng chứng thư Cloud HSM
otp_smsKý xác nhận bằng OTP SMS
image_signatureKý bằng ảnh chữ ký
Response: 
{
  "statusCode": 200,
  "data": {
    "sessionId": "sess_xyz789",
    "contractHash": "sha256:abc123def456...",
    "expiresAt": "2025-01-15T10:00:00Z",
    "signingUrl": "https://sign.econtractid.vn/s/sess_xyz789"
  }
}
signingUrl là URL cho phép người ký mở trực tiếp màn hình ký mà không cần đăng nhập lại (single-use, hiệu lực 30 phút).

​
Gửi OTP xác nhận ký

Dùng cho phương thức otp_sms hoặc cloud_hsm. 
POST /api/signing/:sessionId/send-otp
Hệ thống gửi OTP 6 chữ số về số điện thoại đã đăng ký. OTP hiệu lực 5 phút. Response: 
{
  "statusCode": 200,
  "message": "OTP đã được gửi tới số ***567",
  "data": {
    "otpExpiredAt": "2025-01-15T09:05:00Z"
  }
}

​
Xác nhận ký với OTP

POST /api/signing/:sessionId/confirm
Content-Type: application/json

{
  "otp": "123456"
}
Response thành công: 
{
  "statusCode": 200,
  "message": "Ký thành công",
  "data": {
    "signatureId": "sig_111aaa",
    "signedAt": "2025-01-15T09:04:30Z",
    "certificateInfo": {
      "subject": "CN=Nguyễn Văn A, O=Công ty ABC, C=VN",
      "issuer": "CN=Viettel-CA G2, O=Viettel, C=VN",
      "validFrom": "2024-01-01",
      "validTo": "2026-01-01"
    },
    "contractStatus": "signing"
  }
}

​
Xác nhận ký USB Token (Server-side)

Dành cho tích hợp ký server-side với USB Token thông qua econtractid Desktop Agent. 
POST /api/signing/:sessionId/sign-with-token
Content-Type: application/json

{
  "signedHash": "base64_encoded_signature_bytes",
  "certificateChain": ["base64_cert_1", "base64_cert_2"],
  "timestampToken": "base64_tsa_token"
}

​
Từ chối ký

POST /api/signing/:sessionId/reject
Content-Type: application/json

{
  "reason": "Nội dung hợp đồng cần sửa đổi điều khoản 5.2"
}
Response: 
{
  "statusCode": 200,
  "message": "Đã từ chối ký",
  "data": {
    "contractId": "ctr_abc123",
    "contractStatus": "rejected"
  }
}

​
Kiểm tra trạng thái chữ ký

Kiểm tra tính hợp lệ của chữ ký số trên một hợp đồng đã ký. 
GET /api/signing/verify/:contractId
Response: 
{
  "statusCode": 200,
  "data": {
    "isValid": true,
    "signatures": [
      {
        "signerName": "Nguyễn Văn A",
        "signedAt": "2025-01-16T10:30:00Z",
        "isValid": true,
        "integrityCheck": "passed",
        "certificateStatus": "valid",
        "timestampVerified": true
      }
    ]
  }
}